Metadata-Version: 2.4
Name: mcp-workstate-orchestrator
Version: 0.7.0
Summary: MCP server for orchestration, lane management, worker daemons, and turn metrics.
Project-URL: Homepage, https://github.com/darce/workstate
Project-URL: Source, https://github.com/darce/workstate/tree/main/packages/mcp-workstate-orchestrator
Project-URL: Changelog, https://github.com/darce/workstate/blob/main/packages/mcp-workstate-orchestrator/CHANGELOG.md
Project-URL: Issues, https://github.com/darce/workstate/issues
Requires-Python: >=3.12
Requires-Dist: fastmcp
Requires-Dist: mcp-workstate-handoff<0.14.0,>=0.13.0
Requires-Dist: workstate-protocol<0.4.0,>=0.3.0
Provides-Extra: bridge
Requires-Dist: workstate-codex-bridge<0.3.0,>=0.2.0; extra == 'bridge'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
Requires-Dist: mypy<2.0.0,>=1.13.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.11.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: hypothesis>=6.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Workstate Orchestrator MCP

MCP server for orchestration, lane management, worker daemons, review dispatch, and ACE metrics.

## Installation

### From PyPI (recommended)

```bash
pip install mcp-workstate-orchestrator
# or, as an isolated tool:
uv tool install mcp-workstate-orchestrator
# or, ad-hoc without installing:
uvx mcp-workstate-orchestrator --help
```

`mcp-workstate-orchestrator` declares `mcp-workstate-handoff>=0.5.0,<0.6.0` as a
required dependency; pip resolves it from PyPI automatically.
`workstate-codex-bridge` remains optional unless you want the local
bridge backend.

### From the monorepo source tree (development)

From this package root inside `workstate`:

```bash
cd packages/mcp-workstate-orchestrator
python -m pip install -e ".[dev]"
```

When developing both MCP servers in lockstep, install the sibling
handoff package as an editable first so the orchestrator picks it up:

```bash
pip install -e ../mcp-workstate-handoff
pip install -e ".[dev]"
```

## Development

Run package-local commands from the package root:

```bash
make lint-orchestrator
make fix-lint-orchestrator
make format-orchestrator
make mypy-orchestrator
make test-orchestrator
make check-orchestrator
```

The package Makefile keeps `workstate-codex-bridge` as an optional sibling source path for local bridge-backend development, but it expects `mcp-workstate-handoff` to be installed as a normal package dependency.

Direct commands also work:

```bash
PYTHONPATH=src python -m ruff check src tests
PYTHONPATH=src python -m mypy src
PYTHONPATH=src python -m pytest tests -q
```

## Token-Efficient Usage

For bounded reads and compact caller patterns, follow the shared guide in [`packages/mcp-workstate-handoff/docs/guides/token-efficient-usage.md`](../mcp-workstate-handoff/docs/guides/token-efficient-usage.md). The orchestrator package reuses that guidance instead of maintaining a separate copy of the same parameter semantics.

## Runtime Notes

This package orchestrates work against a target workspace. The workspace you point it at still needs the expected task state and orchestration inputs, such as:

- `.task-state/`
- lane manifests
- task plans or other orchestration docs the lane logic references

Those assets belong to the workspace being orchestrated, not to the package checkout itself.

## Backends

The orchestration layer supports multiple execution backends, including:

- `codex-cli`
- `codex-subagent`
- `claude-code`
- `local-model-openai`

Some backends are optional and require host-specific tooling to be installed separately.

### Availability vs. the optional bridge

The static backend table always lists every declared backend. That a backend is
*listed* does not mean it will *run* in the current process. The `codex-subagent`
backend needs the optional `workstate-codex-bridge` host module, which is **not** a
base dependency and is **not** installed by the bootstrap presync (the launcher
runs `uv run --no-sync`). If the orchestrator server launches from a venv that
lacks the bridge, `resolve_bridge("codex-subagent")` raises `ImportError` at
dispatch even though the backend is listed.

To surface this without a live turn, call the MCP tool `list_available_backends`
with its default settings, or call the CLI with probing on:

```bash
mcp-workstate-orchestrator list-backends --probe
```

Each probed backend carries an `availability_state`:

- `available` — in-process adapter, or a CLI binary found on PATH.
- `reachable` — a bridge module imports and exposes a runner; **liveness is not
  verified** (a real turn may still time out at dispatch).
- `declared_not_installed` — the backend is declared but its optional host module
  (e.g. `workstate-codex-bridge`) is not importable in this runtime.
- `unavailable` — a CLI backend whose binary is not on PATH, or a bridge module
  that imports but does not expose the required runner.
- `unknown` — no probe is implemented for that backend kind.

Install the bridge on demand to move `codex-subagent` from
`declared_not_installed` to `reachable`:

```bash
uv sync --extra bridge   # resolves workstate-codex-bridge from the sibling source
```

## Source Checkout Usage

For local source execution without installation:

```bash
PYTHONPATH=src python -m workstate_orchestrator_mcp --help
```

If you are testing against a sibling `workstate-codex-bridge` checkout instead of an installed bridge dependency, extend `PYTHONPATH` with that sibling `src` directory as needed.
