M08: MCP, REST, and CLI compatibility; optional remote mode #93

New issue

Closed

opened 2026-09-19 13:08:51 +00:00 by kilo · 1 comment

kilo commented

2026-09-19 13:08:51 +00:00

Member

Goal

Preserve existing users and maintain one authoritative core across all interfaces while adding an optional, explicit remote mode.

Module of the execution-gateway program; architecture and contracts come from A0 (#85). This issue protects compatibility throughout the program — it is a continuous regression surface, not a one-off task.

User value

Existing MCP/CLI/REST users keep working with zero migration; users who want a shared server can opt in explicitly and get identical semantics for identical state/policy.

Relationship to current code

Guards the frozen surfaces: MCP tools scarcity_status / scarcity_select / scarcity_simulate (mcp.py, machine_api.py), REST v1 /healthz, /v1/status, /v1/select, /v1/simulate (server.py), CLI status/select/simulate/install-config (cli.py), and the parity suites (tests/test_mcp.py, tests/test_server.py, tests/test_selection_app.py).
The remote mode is an ADDITIONAL configured bridge (MCP/control client → central Scarcity Router server); it never replaces local mode, and the selected operating mode is always explicit.

Scope

Regression tests and parity tests over the frozen v1 surfaces as the gateway program lands; each module issue must keep them green, and this issue owns the guardrail suite.
Continued standalone local stdio MCP operation (no Docker, no worker, no mandatory central HTTP server); continued existing CLI operation; continued existing REST control operation.
Optional configured bridge from an MCP/control client to the central server: explicit configuration, explicit failure — if a configured remote server fails, do NOT silently fall back to local state or local policy (the error is surfaced, never silently degraded).
MCP remains recommendation/control only: it does not execute inference, does not trigger quota-reset actions, does not mutate provider entitlements, and does not reserve execution capacity unless explicitly designed and versioned later.
Preserve actual current tool names and endpoint paths from the repository; version any necessary data-contract changes explicitly (machine-interface v1 additive rules, or a deliberate version bump with a migration decision).
Preserve current status freshness semantics unless an explicit migration decision changes them.

Non-goals

No new MCP execution tools; no automatic edits to a user's global IDE configuration; no semantic drift in freshness/no-solution/error semantics or endpoint paths.

Contracts / interfaces affected

Machine-interface v1 (preserved; additive only per D-028); optional new remote-mode configuration contract (A0).

Dependencies

Depends on: A0 (#85). The remote-bridge portion additionally sequences with M03 (documented inside this issue; deliberately no blocking Forgejo dependency so the guardrail scope never waits on the gateway).
Feeds: every module (guardrail), M10.

Acceptance criteria

Existing MCP clients still work without server or worker.
Equivalent local and remote select / simulate inputs produce equivalent decisions when state/policy are equivalent.
Remote authentication failure does not silently trigger local fallback.
MCP does not reserve execution capacity and does not execute inference.
Scarcity Router does not automatically modify a user's global IDE configuration.
The parity suite (direct == CLI == REST == MCP) is extended to cover gateway-era additive fields and stays green throughout the program.
Full validation gate green (uv sync --only-dev && make check && uv run basedpyright && git diff --check).

Security considerations

The remote bridge adds the first network client for the control plane: authenticated client identity (A0/M09), verified TLS, no bearer secrets in URLs, explicit mode selection, and no silent fallback. The local stdio and loopback boundaries are unchanged.

Risks

Compatibility-suite rot as the gateway adds fields — mitigated by making the parity suite a per-module gate.

Evidence still required

None beyond A0's remote-mode contract decision.

## Goal Preserve existing users and maintain one authoritative core across all interfaces while adding an optional, explicit remote mode. Module of the execution-gateway program; architecture and contracts come from A0 (#85). This issue protects compatibility throughout the program — it is a continuous regression surface, not a one-off task. ## User value Existing MCP/CLI/REST users keep working with zero migration; users who want a shared server can opt in explicitly and get identical semantics for identical state/policy. ## Relationship to current code - Guards the frozen surfaces: MCP tools `scarcity_status` / `scarcity_select` / `scarcity_simulate` (`mcp.py`, `machine_api.py`), REST v1 `/healthz`, `/v1/status`, `/v1/select`, `/v1/simulate` (`server.py`), CLI `status`/`select`/`simulate`/`install-config` (`cli.py`), and the parity suites (`tests/test_mcp.py`, `tests/test_server.py`, `tests/test_selection_app.py`). - The remote mode is an ADDITIONAL configured bridge (MCP/control client → central Scarcity Router server); it never replaces local mode, and the selected operating mode is always explicit. ## Scope - Regression tests and parity tests over the frozen v1 surfaces as the gateway program lands; each module issue must keep them green, and this issue owns the guardrail suite. - Continued standalone local stdio MCP operation (no Docker, no worker, no mandatory central HTTP server); continued existing CLI operation; continued existing REST control operation. - Optional configured bridge from an MCP/control client to the central server: explicit configuration, explicit failure — if a configured remote server fails, do NOT silently fall back to local state or local policy (the error is surfaced, never silently degraded). - MCP remains recommendation/control only: it does not execute inference, does not trigger quota-reset actions, does not mutate provider entitlements, and does not reserve execution capacity unless explicitly designed and versioned later. - Preserve actual current tool names and endpoint paths from the repository; version any necessary data-contract changes explicitly (machine-interface v1 additive rules, or a deliberate version bump with a migration decision). - Preserve current status freshness semantics unless an explicit migration decision changes them. ## Non-goals - No new MCP execution tools; no automatic edits to a user's global IDE configuration; no semantic drift in freshness/no-solution/error semantics or endpoint paths. ## Contracts / interfaces affected Machine-interface v1 (preserved; additive only per D-028); optional new remote-mode configuration contract (A0). ## Dependencies - Depends on: A0 (#85). The remote-bridge portion additionally sequences with M03 (documented inside this issue; deliberately no blocking Forgejo dependency so the guardrail scope never waits on the gateway). - Feeds: every module (guardrail), M10. ## Acceptance criteria - [ ] Existing MCP clients still work without server or worker. - [ ] Equivalent local and remote `select` / `simulate` inputs produce equivalent decisions when state/policy are equivalent. - [ ] Remote authentication failure does not silently trigger local fallback. - [ ] MCP does not reserve execution capacity and does not execute inference. - [ ] Scarcity Router does not automatically modify a user's global IDE configuration. - [ ] The parity suite (direct == CLI == REST == MCP) is extended to cover gateway-era additive fields and stays green throughout the program. - [ ] Full validation gate green (`uv sync --only-dev && make check && uv run basedpyright && git diff --check`). ## Security considerations The remote bridge adds the first network client for the control plane: authenticated client identity (A0/M09), verified TLS, no bearer secrets in URLs, explicit mode selection, and no silent fallback. The local stdio and loopback boundaries are unchanged. ## Risks - Compatibility-suite rot as the gateway adds fields — mitigated by making the parity suite a per-module gate. ## Evidence still required - None beyond A0's remote-mode contract decision.

kilo referenced this issue

2026-09-19 13:11:01 +00:00

A0: Architecture, decisions, and contracts for the optional execution gateway #85

kilo added the

enhancement

label

2026-09-19 13:11:41 +00:00

kilo added a new dependency

2026-09-19 13:12:17 +00:00

#85 A0: Architecture, decisions, and contracts for the optional execution gateway