GRACE Orchestrator MCP

Local MCP control-plane for the Codex → GLM → worker → acceptance workflow.

This repository contains the reusable host/tooling layer. Product repositories keep their own GRACE artifacts, policies, and runtime contracts; this server only owns workflow ledger state, gate execution, handoff events, and host continuation plumbing.

Runtime routing is provider-neutral. The server records the workflow ledger, accepts only server-bound roles, derives Git evidence, and keeps an immutable record of each execution attempt. Provider, model, and target selection live in operator-managed TOML, so changing from GLM to Kimi (or disabling any provider) does not require changing a GRACE task or asking an LLM to edit code.

Local development

py -3.11 -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[dev]"
.\.venv\Scripts\python -m pytest

Set GRACE_MCP_HOME in consuming projects to this checkout when docs or MCP configuration need to refer to the external tool source.

Related MCP server: agentloop

STDIO identity

Set the identity before starting the server. It is deliberately process-bound, so no MCP tool can elevate itself by supplying a role argument.

$env:GRACE_ORCHESTRATOR_ACTOR_NAME = "codex"
$env:GRACE_ORCHESTRATOR_ACTOR_ROLE = "codex"
$env:GRACE_ORCHESTRATOR_DATA_DIR = "D:\path\to\grace-orchestrator-state"
.\.venv\Scripts\grace-orchestrator-mcp

Logs use stderr; stdout is reserved for MCP JSON-RPC.

Keep GRACE_ORCHESTRATOR_DATA_DIR outside the repository: it holds the local ledger, routing configuration, run evidence, and any driver-managed workspaces.

GUI-Neutral Inbox & Project Authorization

inbox.next and inbox.list provide passive, backend-neutral inbox queries returning actor-bound execution items:

• Queries are strictly bounded by process identity (GRACE_ORCHESTRATOR_ACTOR_NAME / GRACE_ORCHESTRATOR_ACTOR_ROLE).

• Inbox items contain only actions that the caller has active role or project capability/delegation authorization to perform.

• For GUI-backed environments (e.g. Antigravity IDE, VSCode, Codex GUI), active tab or context switching is performed manually by the human user.

• Calling inbox.next or inbox.list eliminates context transfer overhead, but does NOT launch, spawn, or wake up background Codex/ZCode/Antigravity instances.

• Project-scoped authorization is strictly enforced across both tool calls and FastMCP @mcp.resource endpoints. GLM and TEST_OWNER primary roles require explicit project capability registration or delegation to access project resources.

Runtime routing and model changes

Initialize and edit the operational configuration directly; these commands do not use MCP or an LLM:

grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state config init
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state provider add moonshot --driver openai_compatible --credential-env MOONSHOT_API_KEY
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state model add kimi-main --provider moonshot --remote-id kimi-k2
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state target add kimi-planner --model kimi-main --capability planner
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state route set planner --target kimi-planner
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state config doctor --capability planner --min-candidates 2
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state health status
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state health reset kimi-planner

routing.toml is atomically written under config/, versioned in config/history/, and hot-reloaded with last-known-good protection. Disable or drain a target to stop new dispatches; previously-created attempts retain their selected target, routing generation, and evidence. The v4 lifecycle is grace.dispatch_v4_task → attempt.start → verification → attempt.complete. attached_actor, command, and openai_compatible are explicit driver types. MCP records a handoff for external drivers; it never accepts arbitrary argv or credentials and does not impersonate an external provider executor.

config doctor is the preflight check for routing. Use --min-candidates 2 for a capability that must remain available after one provider/model target is quarantined. Quarantine is scoped to the actual failure blast radius (target, model, provider, credential, or host), so a quota or authentication fault is not blindly retried through another target using the same provider account.

The retired transport is not part of the runtime. Existing historical sessions are copied on startup into the immutable legacy_execution_sessions archive for audit only; no executable legacy transport is exposed.

New MCP servers expose the GRACE v4 attempt surface only. The superseded task/work-package surface is an explicit temporary compatibility mode. An environment start requires both GRACE_ORCHESTRATOR_LEGACY_API=1 and GRACE_ORCHESTRATOR_LEGACY_API_ACK=1; every such start is written to the audit ledger. This mode restores legacy package tools only — not the retired MiMo transport.

GRACE v4 completion and recovery

Import accepts an active approved GraceChangeSpec/GraceChangePlan only when its version, scope, graph anchors, task dependencies, acceptance criteria, and verification commands form a safe runtime contract. The server also requires a successful canonical upstream validator receipt at import. Set the validator once in the MCP host environment with JSON argv; it is executed without a shell and supports {project_root}, {grace_root}, and {change_id} placeholders:

$env:GRACE_V4_VALIDATOR_ARGV_JSON = '["bun","run","D:\tools\GRACE\src\grace.ts","lint","--path","{project_root}"]'
$env:GRACE_V4_VALIDATOR_CWD = 'D:\tools\GRACE'

The server records hashes of the command and its output in the execution policy, then re-hashes the approved bundle at start and completion.

attempt.complete cannot mark a v4 task successful until every plan-declared acceptance criterion and verification command has structured passing evidence. Use attempt.record_verification for evidence produced by a test owner, or attempt.run_verification for a plan-declared command that is also in the project allowlist. The latter records command exit code and log locations.

Every started attempt holds a renewable lease. attempt.heartbeat renews it; server startup reconciles expired leases into one SESSION_STALLED failure and an idempotent fallback attempt when an eligible route remains. An MCP host is still responsible for reconnecting/restarting a dead STDIO process.

For an imported v4 task, a changed or unavailable approved spec.xml or plan.xml closes the active attempt as APPROVED_CONTRACT_DRIFT in the ledger and requires a replan. Legacy package operations are also disabled inside the service by default; exposing them requires explicit compatibility mode in addition to the server-level acknowledgement.

For a product repository, enforce v4 guidance with:

grace-docs-lint D:\path\to\product-repository

It rejects active AGENTS.md and docs/grace/**/*.md references to v3 packet/work-package controls. Historical material belongs under a legacy or archive directory and is intentionally excluded.

Legacy worker handoff and controller wait

This section documents the temporary GRACE_ORCHESTRATOR_LEGACY_API package compatibility surface. It is not part of the default v4 execution path.

Dispatch does not end controller responsibility. Every launch writes WORKER_STARTED; a valid submission.create writes a durable WORKER_READY_FOR_REVIEW event and a controller-readable report. Workers must use handoff.report_worker_event for WORKER_BLOCKED, WORKER_NEEDS_CONTROLLER, or WORKER_FAILED; controller review writes CONTROLLER_ACCEPTED or CONTROLLER_REWORK_REQUESTED.

Events and reports live below the configured external data directory at runs/project-<id>/task-<id>/package-<id>/, never in a product worktree. A live Codex controller reads the current count with handoff.list_events and then blocks through handoff.wait_for_event. The wait is a bounded, cross-process Windows named-event wait rather than a blind polling timer; it returns only when a new durable event appears or its explicit timeout expires. The controller then reviews or escalates and renews the wait while the package is still open. A host that has completely ended a Codex conversation must provide its own continuation/wakeup integration; the MCP server cannot revive an already-terminated client process.

Host-level continuation

handoff.wait_for_event is the live-controller wait path. It only works while the controller session is alive and actively waiting inside an MCP tool call. Host-level continuation is the external recovery path for the opposite case: the runtime/host process watches durable files under GRACE_ORCHESTRATOR_DATA_DIR\runs\... and starts controller review from those files after a worker emits WORKER_READY_FOR_REVIEW, WORKER_BLOCKED, WORKER_FAILED, or WORKER_NEEDS_CONTROLLER.

Start it from the repository root:

$env:GRACE_ORCHESTRATOR_DATA_DIR = "D:\path\to\grace-orchestrator-state"
$env:GRACE_CODEX_START_COMMAND = 'codex "{prompt_file}"'
.\scripts\Start-GraceHostContinuation.ps1

Use -Once for a single scan during tests or manual recovery. The supervisor keeps its cursor under GRACE_ORCHESTRATOR_DATA_DIR\host-continuation\cursor.json, writes per-run host events to runs\project-<id>\task-<id>\package-<id>\host-events.ndjson, and uses per-run directory locks under host-continuation\locks\ so two host instances do not start duplicate controller continuation for the same run.

Continuation has two modes. If per-run controller metadata records a usable controller_session_id and GRACE_CODEX_RESUME_COMMAND is configured, the host attempts that resume command first. Resume syntax is Codex-version and host-version dependent, so the command is deliberately configured instead of hardcoded. If resume is unavailable or fails, the reliable baseline is logical continuation: the host writes a compact controller prompt and launches GRACE_CODEX_START_COMMAND. The configured command can use placeholders such as {prompt_file}, {data_dir}, {run_id}, {task_id}, {work_package_id}, {report_path}, {worktree_path}, and {controller_session_id}. The prompt file path is also supplied through GRACE_CONTROLLER_CONTINUATION_PROMPT_FILE.

The host emits these durable host events: HOST_CONTINUATION_DETECTED, HOST_CONTROLLER_RESUME_ATTEMPTED, HOST_CONTROLLER_RESUME_STARTED, HOST_CONTROLLER_RESUME_FAILED, and HOST_CONTROLLER_LOGICAL_CONTINUATION_STARTED. These are workflow wakeup evidence only. They do not accept a package, do not mutate product runtime truth, and do not prove that a closed Codex session was revived. A closed session is resumed only if the configured resume command really starts.

Enforcement gates

The server is a gatekeeper, not only a ledger. It exposes:

• gate.contract_discovery: reads current GRACE/code-adjacent sources and returns contracts, M-* refs, V-M-* refs, rule refs, and blocking issues.

• gate.validate_execution_packet: rejects worker packets missing task, module, verification, scope, contracts-read, test surface, rollback, command, stop-condition, or compact-report fields.

• gate.validate_worker_report: rejects worker reports missing files read, files changed, contract delta, exact command results, scaffolded/wired/ verified split, unverified gaps, protected-test scope statement, or delta proposals.

• gate.agent_infra_lint: validates AGENTS/GRACE enforcement files without executing a shell command.

• gate.acceptance_review: projects whether a task currently satisfies package acceptance, worker report, and agent-infra prerequisites.

workpackage.create, submission.create, GLM acceptance, and Codex final acceptance call these validators internally. A client can preflight with the gate.* tools, but cannot bypass the same checks by calling the lifecycle tools directly.

Transactional hooks

The server has a trusted in-process HookRegistry, not a public scripting surface. It audits and revalidates the relevant scope after task, artifact, package, submission, and review mutations. A rejected GLM package enables only its assigned Pro repair path; the Codex final gate requires all canonical GRACE artifacts; a Codex acceptance closes the task atomically.

gate.promote is an internal EventBus event and intentionally is not an MCP tool. Hooks do not accept shell commands, scripts, or client-defined handlers.