toolroll 0.9.43 → 0.9.44

package/dist/mcp-core.d.ts

@@ -0,0 +1,110 @@
+import { type GatewayToolName } from "./contracts/gateway-tools.js";
+import type { Store } from "./store.js";
+import { type VerifiedCoordinator } from "./coordinator.js";
+export declare const MODERN = "2026-07-28";
+export declare const LEGACY = "2025-11-25";
+/** The modern revision namespaces its per-request metadata. */
+export declare const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const META_SERVER = "io.modelcontextprotocol/serverInfo";
+export declare const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+/** The revision's own error code for an unsupported protocol version. */
+export declare const UNSUPPORTED_VERSION = -32022;
+export declare const MAX_REQUEST: number;
+export declare const MAX_DEPTH = 32;
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export declare function depthOf(value: unknown): number;
+/** One handler per tool; its input is GATEWAY_TOOL_INPUTS[name]
+ * (src/contracts/gateway-tools.ts) — THE source for parsing and inputSchema.
+ * Output is built field-by-field; spreading a database row into a result is
+ * forbidden in this module (arch-tested). */
+export type ToolContext = {
+    store: Store;
+    who: VerifiedCoordinator;
+    /** The installation's enrolled repos (repos.json), when the launcher
+     * knows them — list_repos answers allowlist ∩ enrolled. null = the
+     * launcher could not read the registry; the allowlist alone answers. */
+    enrolled: readonly string[] | null;
+    /** The raw credential, per-SERVER closure state — never module state:
+     * two serveMcp instances in one process must not cross credentials
+     * (implementation review, finding 5). Filing re-authenticates with it
+     * inside its own transaction. */
+    token: string;
+    now: Date;
+    /** Decisions this connection read with get_decision — propose_answer needs one. */
+    readDecisions: Set<number>;
+    /** Where evidence lives, when the launcher knows — get_task reads a scout's report from here. */
+    evidenceRoot?: string;
+};
+export type Answer = {
+    ok: true;
+    body: Json;
+} | {
+    ok: false;
+    message: string;
+};
+type Tool = {
+    name: GatewayToolName;
+    description: string;
+    inputSchema: Json;
+    handle: (ctx: ToolContext, args: Record<string, unknown>) => Answer;
+};
+/** The gateway's tools in tools/list order, each inputSchema derived from its contract. */
+export declare const TOOLS: Tool[];
+/** The tools/list payload for a registry. No outputSchema: MCP output schemas describe structuredContent, and these
+ * tools return text content only (round-2 finding 1). */
+export declare const toolsPayload: (tools: readonly {
+    name: string;
+    description: string;
+    inputSchema: Json;
+}[]) => {
+    tools: Json;
+};
+/** A modern result is schema-complete; a cacheable one (tools/list, discover) carries `ttlMs: 0` and the narrowest scope. */
+export declare function shapeResult(era: "modern" | "legacy", result: Record<string, Json>, cacheable: boolean): Record<string, Json>;
+/** One JSON-RPC message, read and checked before any method applies. */
+export type ReadMessage = {
+    ok: true;
+    hasId: boolean;
+    id: Json;
+    method: string;
+    params: Record<string, unknown>;
+    meta: Record<string, unknown>;
+} | {
+    ok: false;
+    id: Json;
+    code: number;
+    message: string;
+};
+/** Read one message's text: size, JSON, no batching, depth, `jsonrpc`, and the id rules. A notification is the message
+ * that carries NO id — the method name never decides (round-3 finding 3). MCP RequestId is a string or an INTEGER
+ * (round-2 finding 2): floats, null, and object shapes refuse wherever an id appears. */
+export declare function readMessage(text: string): ReadMessage;
+/** ClientCapabilities is an OBJECT shape (round-3 finding 5): an array is not a capabilities declaration. */
+export declare const capabilitiesShape: (value: unknown) => boolean;
+/** What a tools/call came to: a JSON-RPC error (`fatal` = the stdio server must exit after it) or a tool result. */
+export type CallOutcome = {
+    kind: "error";
+    code: number;
+    message: string;
+    fatal: boolean;
+} | {
+    kind: "result";
+    result: Record<string, Json>;
+};
+/** The `arguments` of a call: only an ABSENT value defaults to empty (round-3 finding 2), and the root is an object
+ * BEFORE any schema applies (round-2 finding 2): 42 or false never passes an empty schema. */
+export declare function callArguments(params: Record<string, unknown>): Record<string, unknown> | null;
+/** A handler's answer as a tools/call result: a refusal is `isError`, never a protocol error. */
+export declare function answerResult(answered: Answer): Record<string, Json>;
+/**
+ * One coordinator tools/call. ONE snapshot per call (review finding 3): the version check, the credential re-read, and
+ * every data read share a transaction, so a concurrent migration cannot slip between them; filing's own BEGIN IMMEDIATE
+ * reenters this one. tools/list visibility is presentation — authorization happens HERE, on every call, against the
+ * live credential row.
+ */
+export declare function callCoordinatorTool(call: Omit<ToolContext, "who" | "now"> & {
+    clock: () => Date;
+}, params: Record<string, unknown>): CallOutcome;
+export {};

package/dist/mcp-core.js

@@ -0,0 +1,311 @@
+/**
+ * The MCP gateway's transport-free core (MCP gateway spec v6): protocol
+ * constants and limits, message reading, the coordinator tool registry and
+ * its per-call authorization. The stdio adapter (mcp.ts) and the HTTP adapter
+ * (mcp-http.ts) each own their transport and lifecycle; neither re-implements
+ * what a call means.
+ *
+ * Protocol errors are JSON-RPC errors; tool-level refusals are successful
+ * `tools/call` results with `isError: true`.
+ */
+import { dirname, join } from 'node:path';
+import { statSync } from 'node:fs';
+import { repositoryContextRead } from './repository-context.js';
+import { ASSIGNMENT_TOOLS, assignmentForCoordinator } from "./assignment-adapters.js";
+import { parseContract, toModelSchema } from "./contracts/contract.js";
+import { GATEWAY_TOOL_INPUTS, GATEWAY_TOOL_OUTPUTS } from "./contracts/gateway-tools.js";
+import { reportToolOutput } from "./contracts/lead-tools.js";
+import { PACKAGE_VERSION } from "./version.js";
+import { authenticateCoordinator, fileCoordinatorProposal, statusFor, listTasksFor, taskDetailFor, } from "./coordinator.js";
+import { ISO_STAMP_RULE, decisionOver, decisionsOver, labelRepos, queueOver, recapOver } from "./mate-tools.js";
+import { proposeAsCoordinator } from "./coordinator-proposals.js";
+export const MODERN = "2026-07-28";
+export const LEGACY = "2025-11-25";
+/** The modern revision namespaces its per-request metadata. */
+export const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+export const META_SERVER = "io.modelcontextprotocol/serverInfo";
+export const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+/** The revision's own error code for an unsupported protocol version. */
+export const UNSUPPORTED_VERSION = -32022;
+export const MAX_REQUEST = 256 * 1024;
+export const MAX_DEPTH = 32;
+export function depthOf(value) {
+    // The byte cap bounds the work list. Neither nesting nor array width
+    // becomes a JavaScript call stack or a spread argument list.
+    const pending = [{ value, depth: 0 }];
+    let maximum = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current.depth > MAX_DEPTH)
+            return current.depth;
+        maximum = Math.max(maximum, current.depth);
+        if (current.value !== null && typeof current.value === "object") {
+            const children = Array.isArray(current.value) ? current.value : Object.values(current.value);
+            for (const child of children)
+                pending.push({ value: child, depth: current.depth + 1 });
+        }
+    }
+    return maximum;
+}
+const CONTRACT_GUIDE = [
+    "Toolroll MCP contract.",
+    "You hold a coordinator credential: you may read inside your repo allowlist, file proposals, and record assignment ownership and receipt checks. Ownership and receipt checks grant no execution or approval authority.",
+    "A filed proposal is an ordinary unapproved task: it is quarantined from planning, claiming, and running until the operator signs its scope in a password ceremony that shows them who asked. Modes never auto-admit coordinator filings.",
+    "file_proposal requires an idempotency_key (8-64 printable chars, unique per request): replaying the same key+request returns the original task; the same key with a different request refuses. deliverable 'report' files a scout task: a read-only investigation whose only output is a report on the task page, never a branch.",
+    "You are rate-limited per hour and capped on outstanding unapproved filings. Refusals say the limit and the road in words.",
+    "recap, list_decisions, get_decision, and queue are the plane's own read queries (shared with the operator's mate). get_decision shows each option's consequence, never the builder's recommendation.",
+    "propose_next, propose_reserve, propose_hold, propose_unhold, propose_scope, propose_cancel, and propose_answer write a PROPOSAL row and nothing else: an approver confirms it on the console or the CLI, and a stale one refuses there. Proposals share your hourly filing rate and hold at most 20 pending per credential; they expire after seven days.",
+    "Approve, steer, answer, pick, mint, configure, merge: those verbs do not exist on this surface, by construction.",
+    "Claim one assignment, then follow list_assignment_updates with a saved cursor; inspect get_assignment when a current result or decision needs attention. claim_assignment records its lead; acknowledge_assignment records that lead's check of an exact ready receipt. Neither operation grants authority, accepts proof, answers decisions, approves work, publishes, or deploys.",
+].join("\n");
+/** An assignment tool: the adapter reads its call with the same schema `toolroll assignment` does. */
+const assignmentHandler = (operation) => (ctx, args) => {
+    const result = assignmentForCoordinator(ctx.store, ctx.token, operation, args, ctx.now, ctx.evidenceRoot);
+    return result.ok ? { ok: true, body: result.body } : { ok: false, message: `${result.reason}: ${result.message}` };
+};
+const assignmentTool = (name) => {
+    const spec = ASSIGNMENT_TOOLS.find(one => one.name === name);
+    return { description: spec.description, handle: assignmentHandler(spec.operation) };
+};
+/** A propose_* tool: it writes one proposal row through the coordinator door. */
+const proposeTool = (kind, description) => ({
+    description,
+    handle: (ctx, args) => {
+        const outcome = proposeAsCoordinator(ctx.store, ctx.token, kind, args, ctx.now, { readDecisions: ctx.readDecisions });
+        if (!outcome.ok)
+            return { ok: false, message: outcome.message };
+        return { ok: true, body: { proposal: outcome.id, kind: outcome.kind, awaiting: outcome.awaiting } };
+    },
+});
+const HANDLERS = {
+    get_project_context: {
+        description: 'Read bounded source excerpts or advisory static import impact in an admitted project. Falls back to text search without an index.',
+        handle: (ctx, args) => {
+            const repo = args.repo;
+            if (!ctx.who.repos.includes(repo) || ctx.enrolled !== null && !ctx.enrolled.includes(repo))
+                return { ok: false, message: 'That project is outside your access.' };
+            return { ok: true, body: repositoryContextRead({ repo, query: args.query, mode: args.mode === 'impact' ? 'impact' : 'search', audience: 'lead',
+                    ...(ctx.evidenceRoot === undefined ? {} : { cacheRoot: join(dirname(ctx.evidenceRoot), 'repository-context') }) }) };
+        },
+    },
+    get_assignment: assignmentTool("get_assignment"),
+    list_assignment_updates: assignmentTool("list_assignment_updates"),
+    claim_assignment: assignmentTool("claim_assignment"),
+    acknowledge_assignment: assignmentTool("acknowledge_assignment"),
+    get_assignment_brief: assignmentTool("get_assignment_brief"),
+    get_assignment_inbox: assignmentTool("get_assignment_inbox"),
+    acknowledge_assignment_delivery: assignmentTool("acknowledge_assignment_delivery"),
+    status: {
+        description: "The plane's liveness facts over your repo allowlist: what waits on the operator, what runs, what finished in the last 24h.",
+        handle: ctx => ({ ok: true, body: statusFor(ctx.store, ctx.who, ctx.now) }),
+    },
+    list_tasks: {
+        description: "Tasks in your repo allowlist. Filter by state and repo; cursor-paginated, stable order.",
+        handle: (ctx, args) => {
+            const filter = {};
+            if (args.state !== undefined)
+                filter.state = args.state;
+            if (args.repo !== undefined)
+                filter.repo = args.repo;
+            if (args.cursor !== undefined)
+                filter.cursor = args.cursor;
+            if (args.limit !== undefined)
+                filter.limit = args.limit;
+            return { ok: true, body: listTasksFor(ctx.store, ctx.who, filter, ctx.now) };
+        },
+    },
+    get_task: {
+        description: "One task's deliverable (branch or report), scope standing, filer provenance, attempt ledger, and — for a finished scout — the report's title, summary, and follow-ups. A ref outside your allowlist answers not-found.",
+        handle: (ctx, args) => {
+            const detail = taskDetailFor(ctx.store, ctx.who, args.ref, ctx.evidenceRoot, ctx.now);
+            if (detail === null)
+                return { ok: false, message: `not-found: no task \`${args.ref}\` in your repositories` };
+            return { ok: true, body: detail };
+        },
+    },
+    list_repos: {
+        description: "The repositories your credential may see and file into, with their operating-mode standing.",
+        handle: ctx => {
+            // FAIL CLOSED when the project registry cannot be read (round-2
+            // finding 4): answering the full allowlist would claim enrollment
+            // nobody proved.
+            if (ctx.enrolled === null) {
+                return { ok: false, message: "the project registry could not be read — the enrolled set is unknown, so nothing lists" };
+            }
+            return {
+                ok: true,
+                body: {
+                    repos: ctx.who.repos
+                        .filter(repo => ctx.enrolled !== null && ctx.enrolled.includes(repo))
+                        .map(repo => {
+                        const mode = ctx.store.activeMode(repo, ctx.now);
+                        return { repo, mode: mode === null ? "no operating mode — every act is a ceremony" : `mode ${mode.name} signed until ${mode.absoluteExpiry}` };
+                    }),
+                },
+            };
+        },
+    },
+    recap: {
+        description: "How things stand per repository in your allowlist, counts and ids: what waits on the operator (decisions, incidents, scopes awaiting approval), what runs, what is queued, finished, failed. Pass `since` (an ISO timestamp) to count only decisions, incidents, and attempts newer than it, to the hour; queued work and scopes awaiting approval always count.",
+        handle: (ctx, args) => {
+            const since = args.since;
+            if (since !== undefined && (!ISO_STAMP_RULE.test(since) || Number.isNaN(Date.parse(since)))) {
+                return { ok: false, message: "since is an ISO timestamp like 2026-09-02T12:00:00Z" };
+            }
+            return { ok: true, body: labelRepos(recapOver(ctx.store, ctx.who.repos, ctx.now, since ?? null), index => ctx.who.repos[index] ?? "") };
+        },
+    },
+    list_decisions: {
+        description: "Open decisions in your allowlist: id, task, question, options (id, label, reversible), age in hours. Never consequences or recommendations; the operator answers them.",
+        handle: ctx => ({ ok: true, body: labelRepos(decisionsOver(ctx.store, ctx.who.repos, ctx.now), index => ctx.who.repos[index] ?? "") }),
+    },
+    queue: {
+        description: "One repository's queue by column — the shared column, then each worker's reserved column — each in dispatch order.",
+        handle: (ctx, args) => {
+            const repo = args.repo;
+            if (!ctx.who.repos.includes(repo))
+                return { ok: false, message: "not-found: that repository is not in your allowlist" };
+            // The installation-wide revision stays home (slice-2 review, finding
+            // 12): a coordinator cannot move queues, and the counter would tell it
+            // about repos it may not see.
+            const { queueRevision: _revision, ...columns } = queueOver(ctx.store, repo, ctx.now);
+            return { ok: true, body: { repo, ...columns } };
+        },
+    },
+    get_decision: {
+        description: "One open decision in your allowlist in full: question, options with id, label, reversible, and consequence. Never the builder's recommendation.",
+        handle: (ctx, args) => {
+            const found = decisionOver(ctx.store, ctx.who.repos, args.decision, ctx.now);
+            if (found === null)
+                return { ok: false, message: "not-found: no such decision in your repositories" };
+            ctx.readDecisions.add(args.decision);
+            return { ok: true, body: labelRepos(found, index => ctx.who.repos[index] ?? "") };
+        },
+    },
+    propose_next: proposeTool("next", "Propose moving a queued task to the front of its column. An approver confirms; a queue that moved meanwhile refuses."),
+    propose_reserve: proposeTool("reserve", "Propose reserving a queued task for one worker, or releasing it to the shared queue with worker null."),
+    propose_hold: proposeTool("hold", "Propose holding a task's next attempt, with a reason. A running attempt is never interrupted."),
+    propose_unhold: proposeTool("unhold", "Propose lifting the operator's own hold on a task."),
+    propose_scope: proposeTool("scope", "Propose rewriting a task's scope. An approver confirms the rewrite, then approves it with a password — a scope you wrote never seals under a mode."),
+    propose_cancel: proposeTool("cancel", "Propose cancelling a task, with a reason. The approver arms and confirms it on the task itself."),
+    propose_answer: proposeTool("answer", "Propose an answer to an open decision you read with get_decision, with a rationale. The approver confirms where every consequence and the builder's recommendation are shown; an irreversible option needs their explicit confirmation."),
+    get_contract: {
+        description: "This surface's contract: what a coordinator may do, the proposal lifecycle, and the admission promise.",
+        handle: () => ({ ok: true, body: { contract: CONTRACT_GUIDE } }),
+    },
+    file_proposal: {
+        description: "File a task proposal into one of your repositories. It stays quarantined until the operator signs its scope.",
+        handle: (ctx, args) => {
+            // The token, not the pre-verified identity: filing re-authenticates
+            // INSIDE its own transaction (the session's `who` is a courtesy).
+            const outcome = fileCoordinatorProposal(ctx.store, ctx.token, { repo: args.repo, title: args.title, ...(args.intent === undefined ? {} : { intent: args.intent }), ...(args.deliverable === undefined ? {} : { deliverable: args.deliverable }), idempotencyKey: args.idempotency_key }, ctx.now);
+            if (!outcome.ok)
+                return { ok: false, message: outcome.message };
+            return {
+                ok: true,
+                body: {
+                    ref: outcome.id,
+                    replayed: outcome.replayed,
+                    admission: "quarantined until the operator signs its scope — the ceremony shows them your name",
+                },
+            };
+        },
+    },
+};
+/** The gateway's tools in tools/list order, each inputSchema derived from its contract. */
+export const TOOLS = Object.keys(GATEWAY_TOOL_INPUTS).map((name) => {
+    const handler = HANDLERS[name];
+    return { name, description: handler.description, inputSchema: toModelSchema(GATEWAY_TOOL_INPUTS[name]), handle: (ctx, args) => handler.handle(ctx, args) };
+});
+/** The tools/list payload for a registry. No outputSchema: MCP output schemas describe structuredContent, and these
+ * tools return text content only (round-2 finding 1). */
+export const toolsPayload = (tools) => ({
+    tools: tools.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),
+});
+/** A modern result is schema-complete; a cacheable one (tools/list, discover) carries `ttlMs: 0` and the narrowest scope. */
+export function shapeResult(era, result, cacheable) {
+    return era === "modern" ? { ...result, resultType: "complete", ...(cacheable ? { ttlMs: 0, cacheScope: "private" } : {}) } : result;
+}
+/** Read one message's text: size, JSON, no batching, depth, `jsonrpc`, and the id rules. A notification is the message
+ * that carries NO id — the method name never decides (round-3 finding 3). MCP RequestId is a string or an INTEGER
+ * (round-2 finding 2): floats, null, and object shapes refuse wherever an id appears. */
+export function readMessage(text) {
+    if (Buffer.byteLength(text, "utf8") > MAX_REQUEST)
+        return { ok: false, id: null, code: -32600, message: "request over 256 KiB" };
+    let message;
+    try {
+        message = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, id: null, code: -32700, message: "parse error" };
+    }
+    // Batching left MCP in 2025-06-18 — neither pinned era accepts it.
+    if (Array.isArray(message))
+        return { ok: false, id: null, code: -32600, message: "JSON-RPC batching is not part of MCP — send one request per line" };
+    if (message === null || typeof message !== "object" || depthOf(message) > MAX_DEPTH)
+        return { ok: false, id: null, code: -32600, message: "invalid request" };
+    const request = message;
+    if (request["jsonrpc"] !== "2.0")
+        return { ok: false, id: null, code: -32600, message: 'jsonrpc must be "2.0"' };
+    const hasId = "id" in request;
+    const rawId = request["id"];
+    if (hasId && (rawId === null || (typeof rawId !== "string" && !(typeof rawId === "number" && Number.isInteger(rawId))))) {
+        return { ok: false, id: null, code: -32600, message: "id must be a string or an integer" };
+    }
+    const method = typeof request["method"] === "string" ? request["method"] : "";
+    if (method.startsWith("notifications/")) {
+        if (hasId)
+            return { ok: false, id: rawId, code: -32600, message: "a notification carries no id" };
+    }
+    else if (!hasId) {
+        return { ok: false, id: null, code: -32600, message: "a request carries an id — a string or an integer" };
+    }
+    const params = (request["params"] ?? {});
+    const meta = (params["_meta"] ?? {});
+    return { ok: true, hasId, id: (rawId ?? null), method, params, meta };
+}
+/** ClientCapabilities is an OBJECT shape (round-3 finding 5): an array is not a capabilities declaration. */
+export const capabilitiesShape = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The `arguments` of a call: only an ABSENT value defaults to empty (round-3 finding 2), and the root is an object
+ * BEFORE any schema applies (round-2 finding 2): 42 or false never passes an empty schema. */
+export function callArguments(params) {
+    const raw = params["arguments"] === undefined ? {} : params["arguments"];
+    return typeof raw !== "object" || raw === null || Array.isArray(raw) ? null : raw;
+}
+/** A handler's answer as a tools/call result: a refusal is `isError`, never a protocol error. */
+export function answerResult(answered) {
+    return answered.ok ? { content: [{ type: "text", text: JSON.stringify(answered.body) }] } : { content: [{ type: "text", text: answered.message }], isError: true };
+}
+/**
+ * One coordinator tools/call. ONE snapshot per call (review finding 3): the version check, the credential re-read, and
+ * every data read share a transaction, so a concurrent migration cannot slip between them; filing's own BEGIN IMMEDIATE
+ * reenters this one. tools/list visibility is presentation — authorization happens HERE, on every call, against the
+ * live credential row.
+ */
+export function callCoordinatorTool(call, params) {
+    const { store, token, clock, ...rest } = call;
+    return store.transact(() => {
+        if (!store.schemaCurrent())
+            return { kind: "error", code: -32000, message: "the database schema moved underneath this server — restart it", fatal: true };
+        const name = typeof params["name"] === "string" ? params["name"] : "";
+        const tool = TOOLS.find(one => one.name === name);
+        if (tool === undefined)
+            return { kind: "error", code: -32602, message: `no tool \`${name}\``, fatal: false };
+        const session = authenticateCoordinator(store, token);
+        if (!session.ok)
+            return { kind: "error", code: -32000, message: "this credential no longer stands — the server exits", fatal: true };
+        const rawArgs = callArguments(params);
+        if (rawArgs === null)
+            return { kind: "error", code: -32602, message: "arguments must be an object", fatal: false };
+        // The call is read by the schema tools/list advertised (review finding 2): unknown fields, bad types, bad enums,
+        // and bound violations are protocol errors (InvalidParams) naming each path, never tool refusals.
+        const read = parseContract(GATEWAY_TOOL_INPUTS[tool.name], rawArgs);
+        if (!read.ok)
+            return { kind: "error", code: -32602, message: read.issues.map(one => one.line).join("; "), fatal: false };
+        const answered = tool.handle({ store, token, who: session.who, now: clock(), ...rest }, read.value);
+        // Checked against its output schema before delivery; a disagreement is reported, never refused.
+        if (answered.ok)
+            reportToolOutput("gateway", tool.name, GATEWAY_TOOL_OUTPUTS[tool.name], answered.body);
+        return { kind: "result", result: answerResult(answered) };
+    });
+}

package/dist/mcp-http.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The MCP gateway over streamable HTTP, served at /mcp by the console (serve.ts). Stateless: one JSON-RPC message per
+ * POST, answered with one JSON body (a notification gets 202 and no body); there is no session and no event stream.
+ * The modern revision carries its version in `_meta` as on stdio; a handshake-era client may initialize, and because
+ * nothing is kept between requests its tools work without the stdio lifecycle.
+ *
+ * Every POST signs in again. The caller is a coordinator credential (the coordinator registry, exactly as on stdio) or
+ * a person's own API token `so_…` (mcp-person.ts: their role, project grants and token scope). A password
+ * (`name:password`) and cookies sign in nothing here, a request carrying a browser Origin is refused, and the console's
+ * Host check runs before this route. A revoked or expired token answers 401 on its next request.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Store } from "./store.js";
+import { type RunOperateAs } from "./mcp-person.js";
+export type McpHttpOptions = {
+    store: Store;
+    clock: () => Date;
+    /** The enrolled projects: a coordinator's list_repos answers allowlist ∩ enrolled. */
+    enrolled: () => readonly string[] | null;
+    evidenceRoot?: string;
+    /** The console's own sign-in for an `so_` bearer: the address's tries, expiry, revocation, a removed account. */
+    signedIn: (request: IncomingMessage) => boolean;
+    /** Runs a person's command on the server (operate.ts); resolved from operate.ts when not injected. */
+    runAs?: RunOperateAs;
+};
+export declare function createMcpHttp(options: McpHttpOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;

package/dist/mcp-http.js

@@ -0,0 +1,151 @@
+/**
+ * The MCP gateway over streamable HTTP, served at /mcp by the console (serve.ts). Stateless: one JSON-RPC message per
+ * POST, answered with one JSON body (a notification gets 202 and no body); there is no session and no event stream.
+ * The modern revision carries its version in `_meta` as on stdio; a handshake-era client may initialize, and because
+ * nothing is kept between requests its tools work without the stdio lifecycle.
+ *
+ * Every POST signs in again. The caller is a coordinator credential (the coordinator registry, exactly as on stdio) or
+ * a person's own API token `so_…` (mcp-person.ts: their role, project grants and token scope). A password
+ * (`name:password`) and cookies sign in nothing here, a request carrying a browser Origin is refused, and the console's
+ * Host check runs before this route. A revoked or expired token answers 401 on its next request.
+ */
+import { PACKAGE_VERSION } from "./version.js";
+import { parseApiToken, secretMatches } from "./api-tokens.js";
+import { authenticateCoordinator } from "./coordinator.js";
+import { LEGACY, MAX_REQUEST, META_CAPABILITIES, META_SERVER, META_VERSION, MODERN, TOOLS, UNSUPPORTED_VERSION, callCoordinatorTool, capabilitiesShape, readMessage, shapeResult, toolsPayload, } from "./mcp-core.js";
+import { callPersonTool, personTools } from "./mcp-person.js";
+/** The most decisions a coordinator credential is remembered to have read (propose_answer needs one). */
+const READ_DECISIONS_KEPT = 200;
+export function createMcpHttp(options) {
+    const { store } = options;
+    /** Stdio remembers per connection which decisions a coordinator read; stateless HTTP remembers it per credential. */
+    const readDecisions = new Map();
+    const send = (response, status, body, headers = {}) => {
+        response.writeHead(status, { "cache-control": "no-store", "x-content-type-options": "nosniff", ...(body === null ? {} : { "content-type": "application/json" }), ...headers });
+        response.end(body === null ? undefined : JSON.stringify(body));
+    };
+    const refuse = (response, status, message, headers = {}) => send(response, status, { jsonrpc: "2.0", id: null, error: { code: -32000, message } }, headers);
+    /** Who signed this request, from the live rows — nothing is cached, so revocation and grant changes apply at once. */
+    const callerOf = (request) => {
+        const presented = /^Bearer (\S+)$/.exec(request.headers.authorization ?? "")?.[1];
+        if (presented === undefined || presented.includes(":"))
+            return null;
+        if (presented.startsWith("so_")) {
+            if (!options.signedIn(request))
+                return null;
+            const parsed = parseApiToken(presented);
+            const kept = parsed === null ? null : store.apiTokenSecret(parsed.id);
+            // The secret is checked here too, so this door never rests on how signedIn reads the request.
+            if (parsed === null || kept === null || !secretMatches(parsed.secret, kept.secretHash))
+                return null;
+            if (kept.row.revokedAt !== null || Date.parse(kept.row.expiresAt) <= options.clock().getTime())
+                return null;
+            const account = store.accountOf(kept.row.account);
+            if (account === null || account.revokedAt !== null)
+                return null;
+            return {
+                kind: "person",
+                person: {
+                    principal: { kind: "person", account: kept.row.account, generation: account.generation, scope: kept.row.access, tokenId: kept.row.id, projects: account.projects === null ? null : [...account.projects] },
+                    role: account.role,
+                    tokenName: kept.row.name,
+                },
+            };
+        }
+        const auth = authenticateCoordinator(store, presented);
+        return auth.ok ? { kind: "coordinator", token: presented, cid: auth.who.cid } : null;
+    };
+    /** Loaded on first use: operate.ts imports serve.ts, which serves this gateway. */
+    const runAs = async () => options.runAs ?? (await import("./operate.js")).runOperateAs;
+    /** The body, or null the moment it passes MAX_REQUEST: reading stops there and nothing more is buffered. */
+    const readBody = (request) => new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        const onData = (chunk) => {
+            size += chunk.length;
+            if (size <= MAX_REQUEST)
+                return void chunks.push(chunk);
+            request.off("data", onData);
+            request.pause();
+            chunks.length = 0;
+            resolve(null);
+        };
+        request.on("data", onData);
+        request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        request.on("error", reject);
+    });
+    /** 413, then the connection goes: the rest of an oversized body is never read. */
+    const tooLarge = (request, response) => {
+        response.once("finish", () => request.destroy());
+        refuse(response, 413, "request over 256 KiB", { connection: "close" });
+    };
+    const call = async (caller, params) => {
+        if (caller.kind === "person") {
+            return callPersonTool(caller.person, store, await runAs(), params);
+        }
+        let read = readDecisions.get(caller.cid);
+        if (read === undefined)
+            readDecisions.set(caller.cid, read = new Set());
+        const outcome = callCoordinatorTool({ store, token: caller.token, enrolled: options.enrolled(), clock: options.clock, readDecisions: read, ...(options.evidenceRoot === undefined ? {} : { evidenceRoot: options.evidenceRoot }) }, params);
+        for (const id of read)
+            if (read.size > READ_DECISIONS_KEPT)
+                read.delete(id);
+        return outcome;
+    };
+    return async (request, response) => {
+        if (request.method !== "POST")
+            return refuse(response, 405, "the MCP gateway takes POST only — one JSON-RPC message per request", { allow: "POST" });
+        // A browser page must never drive the gateway with whatever it can reach: agents send no Origin.
+        if (request.headers.origin !== undefined)
+            return refuse(response, 403, "browser requests are refused — connect an MCP client with your API token");
+        const caller = callerOf(request);
+        if (caller === null) {
+            return refuse(response, 401, "sign in with your API token (Authorization: Bearer so_…) or a coordinator credential — passwords and cookies are not accepted here", { "www-authenticate": 'Bearer realm="toolroll-mcp"' });
+        }
+        if (!/^application\/json\s*(;|$)/i.test(request.headers["content-type"] ?? ""))
+            return refuse(response, 415, "send the JSON-RPC message as application/json");
+        if (Number(request.headers["content-length"] ?? 0) > MAX_REQUEST)
+            return tooLarge(request, response);
+        const text = await readBody(request);
+        if (text === null)
+            return tooLarge(request, response);
+        const message = readMessage(text);
+        if (!message.ok)
+            return send(response, 400, { jsonrpc: "2.0", id: message.id, error: { code: message.code, message: message.message } });
+        const { id, method, params, meta } = message;
+        const error = (code, text, data) => send(response, 200, { jsonrpc: "2.0", id, error: { code, message: text, ...(data === undefined ? {} : { data }) } });
+        const answer = (era, result, cacheable) => send(response, 200, { jsonrpc: "2.0", id, result: shapeResult(era, result, cacheable) });
+        if (!store.schemaCurrent())
+            return error(-32000, "the database schema moved underneath this server — try again after it restarts");
+        // Notifications (initialized, cancelled) need nothing from a stateless server: accepted, never answered.
+        if (method.startsWith("notifications/"))
+            return send(response, 202, null);
+        const header = request.headers["mcp-protocol-version"];
+        const declared = typeof meta[META_VERSION] === "string" ? meta[META_VERSION] : typeof header === "string" ? header : null;
+        if (method !== "initialize" && declared !== null && declared !== MODERN && declared !== LEGACY) {
+            return error(UNSUPPORTED_VERSION, `unsupported protocol version \`${declared}\``, { supported: [MODERN, LEGACY], requested: declared });
+        }
+        const tools = () => caller.kind === "person" ? personTools(caller.person) : TOOLS;
+        if (method === "initialize") {
+            // The handshake era negotiates only itself; nothing is kept, so no session id is issued.
+            return answer("legacy", { protocolVersion: LEGACY, capabilities: { tools: {} }, serverInfo: { name: "toolroll", version: PACKAGE_VERSION } }, false);
+        }
+        const era = declared === MODERN ? "modern" : "legacy";
+        if (era === "modern" && !capabilitiesShape(meta[META_CAPABILITIES]))
+            return error(-32600, `a ${MODERN} request carries _meta["${META_CAPABILITIES}"]`);
+        if (method === "server/discover") {
+            if (era !== "modern")
+                return error(-32600, `server/discover requires _meta["${META_VERSION}"] = "${MODERN}" and _meta["${META_CAPABILITIES}"]`);
+            return answer("modern", { protocolVersion: MODERN, supportedVersions: [MODERN, LEGACY], capabilities: { tools: {} }, _meta: { [META_SERVER]: { name: "toolroll", version: PACKAGE_VERSION } }, ...toolsPayload(tools()) }, true);
+        }
+        if (method === "ping")
+            return era === "modern" ? error(-32601, "ping is not part of the modern revision") : answer("legacy", {}, false);
+        if (method === "tools/list")
+            return answer(era, toolsPayload(tools()), true);
+        if (method === "tools/call") {
+            const outcome = await call(caller, params);
+            return outcome.kind === "result" ? answer(era, outcome.result, false) : error(outcome.code, outcome.message);
+        }
+        return error(-32601, `unknown method \`${method}\``);
+    };
+}

package/dist/mcp-person.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A person's tools on the HTTP gateway. A person signs in with their own API token (api-tokens.ts) and every tool call
+ * is the exact `toolroll` command line they could type, run on the server under their principal through
+ * `runOperateAs` with source "mcp": the command's own authorization, project grants and attribution apply, and its
+ * `--json` envelope is the answer. Nothing here reads data directly — a coordinator handler would skip the person's
+ * project grants — and nothing here approves, answers or changes people or policy: those verbs have no tool.
+ *
+ * tools/list follows the account's role and the token's scope; dispatch checks again, independent of the list.
+ */
+import { type PersonToolName } from "./contracts/gateway-tools.js";
+import { type CallOutcome, type Json } from "./mcp-core.js";
+import type { Store } from "./store.js";
+import type { Principal } from "./operate.js";
+/** The shared remote seam (operate.ts): who runs a command on the server, and the runner itself. Type-only, so a
+ * change to either breaks this build instead of drifting; the value is loaded lazily (operate.ts imports serve.ts). */
+export type { Principal } from "./operate.js";
+export type RunOperateAs = typeof import("./operate.js").runOperateAs;
+/** A signed-in person: the principal the command runs as, and what their account may do. */
+export type Person = {
+    principal: Principal;
+    role: "approver" | "viewer";
+    tokenName: string;
+};
+/** What this person may call: every read, and the acts only on an act token of an account that acts. */
+export declare function personTools(person: Person): {
+    name: PersonToolName;
+    description: string;
+    inputSchema: Json;
+}[];
+/** One person tools/call: read by its schema, checked against the person, then run as the command it names. */
+export declare function callPersonTool(person: Person, store: Store, runAs: RunOperateAs, params: Record<string, unknown>): Promise<CallOutcome>;