Transports v0.1: HTTP and MCP adapters over one protocol

[tim8es]

Mission

Implement MindRail v0.1 HTTP and MCP transport adapters on branch feature/transports-v0-1 without moving lifecycle/business authority out of the core protocol/runtime.

Base SHA: 87fbfcf2ed738071f648a3b94bfff1df1f235dba.

Read AGENTS.md, ADR-0001/0003/0004/0005, current protocol/runtime code, security docs, docs/CURRENT_STATE.md, and roadmap before editing. Repository HEAD is authoritative.

Architectural rule

There is one semantic protocol. HTTP and MCP are adapters only.

Transports may:

• parse/decode transport input;
• authenticate/bind a principal through an injected auth boundary;
• map to a typed MindRail command/query;
• call one protocol application port;
• map the returned protocol envelope back to transport output.

Transports must not:

• implement Task/Lease/Session/Permission lifecycle rules;
• mint revisions/fencing/ids/timestamps;
• perform alternate idempotency;
• grant permissions;
• infer authority from model text;
• expose generic arbitrary actions.

ActorRef is attribution, not authentication. The adapter must have an explicit principal-binding seam and fail closed if claimed actor/session cannot be authorized. Do not implement a real OAuth provider in this slice.

Application boundary

Introduce or reuse the smallest transport-neutral application interface needed by both transports, e.g. explicit command/query dispatch ports. Avoid coupling adapters directly to InMemoryControlPlane internals so durable runtime can replace it later.

Because Runtime Surface / Permission / Persistence are parallel streams, isolate this port in new transport/application files and minimize edits to core runtime files.

HTTP adapter

Implement ADR-0005 mapping:

• POST /v0.1/commands/{command}
• POST /v0.1/queries/{query}

Prefer Web-standard Request / Response or another vendor-neutral thin boundary. Do not introduce a large web framework merely for routing.

Requirements:

• bounded request body size;
• JSON-only command/query bodies;
• malformed JSON / structural transport input rejected before protocol dispatch;
• route command discriminator must agree with body discriminator or body must omit it and adapter supplies it deterministically; choose one and document;
• protocol error code remains canonical for client behavior; HTTP status is secondary deterministic mapping;
• no stack traces/internal objects in responses;
• preserve commandId/correlationId where valid;
• support dependency injection of application dispatcher + principal authorizer;
• no ambient credentials/global mutable auth state.

MCP adapter

Map explicit MindRail commands to explicit MCP tools; map side-effect-free reads to explicit tools/resources according to current SDK ergonomics.

No generic execute_action, update_entity, patch_object, shell, browser, filesystem, network proxy, or arbitrary JSON tool.

At minimum provide explicit adapter definitions for the v0.1 lifecycle/permission surface accepted by ADR-0005, even if some application commands are temporarily reported as unsupported until their parallel implementation lands.

MCP host approval/sandbox is an additional boundary. MindRail may not claim it can bypass host tool approvals.

If using an MCP SDK dependency:

• use the smallest official/current package justified by executable tests;
• pin it according to repository dependency policy;
• verify current API rather than coding from memory;
• keep SDK-specific types at adapter edge.

Queries

Define bounded transport shapes for current minimum reads where underlying application support exists:

• GetWorkspace
• GetGoal / ListGoals
• GetTask / ListGoalTasks
• ListClaimableTasks
• GetTaskExecutionView
• ListTaskCheckpoints
• GetAgent
• GetSession
• GetLease
• permission queries when Permission PR lands

Lists require bounded limit and opaque cursor semantics. Do not invent arbitrary filter languages.

It is acceptable for this PR to implement the adapter/application interfaces and a subset backed by currently available reads, provided unsupported accepted operations fail explicitly and the interface is ready for integration without redesign.

Security tests

Mandatory tests include:

1. claimed actor that fails principal binding never reaches dispatcher;
2. malformed/oversized HTTP body never reaches dispatcher;
3. unknown HTTP command/query route is deterministic and bounded;
4. protocol INVALID_INPUT, NOT_FOUND, CONFLICT, ACTOR_NOT_AUTHORIZED, HUMAN_DECISION_REQUIRED map predictably without changing canonical error code;
5. exact protocol success/error envelope is preserved semantically;
6. MCP exposes explicit tool names only; no generic authority escape hatch;
7. MCP arguments are validated before application dispatch;
8. adapter never mutates lifecycle state itself (use spy/fake dispatcher tests);
9. tracing/idempotency fields survive mapping correctly;
10. adapter logs/tests do not expose arbitrary credentials/secrets.

TDD / verification

Use RED -> GREEN.

Run fresh:

• pnpm install --frozen-lockfile
• pnpm check
• pnpm test:coverage
• any executable HTTP/MCP integration tests;
• permanent Quality on final PR head.

Never call an unexecuted transport/runtime test PASS.

Scope boundaries

Do NOT:

• implement persistence/D1/DO;
• implement lifecycle semantics in transport;
• implement deterministic permission policy itself;
• add real external OAuth/IAM provider;
• implement GitHub adapter;
• add frontend/dashboard;
• create arbitrary model tools;
• make Cloudflare-specific types part of protocol/application core.

Ownership / parallel safety

Primary ownership:

• new src/application/* seam if required;
• new src/transports/http/*;
• new src/transports/mcp/*;
• transport tests/docs.

Avoid broad edits to src/runtime/in-memory-control-plane.ts, src/runtime/protocol*.ts, src/policy/*, and src/persistence/*. If accepted command additions from parallel streams are not yet on this branch, design adapters against an injected typed dispatcher and document the small integration delta.

Definition of done

Open a non-draft PR from feature/transports-v0-1 to main with:

• explicit application port;
• HTTP mapping and tests;
• MCP mapping and tests;
• principal-binding boundary;
• exact unsupported-operation list if parallel runtime commands are not yet merged;
• dependency justification;
• final Quality run;
• no temporary workflow files.

Do not merge it yourself unless acting as integration owner.