toolroll 0.9.42 → 0.9.44

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>;

package/dist/mcp-person.js

@@ -0,0 +1,96 @@
+/**
+ * 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 { parseContract, toModelSchema } from "./contracts/contract.js";
+import { PERSON_TOOL_INPUTS, PERSON_TOOL_OUTPUTS } from "./contracts/gateway-tools.js";
+import { reportToolOutput } from "./contracts/lead-tools.js";
+import { callArguments } from "./mcp-core.js";
+const TOOLS = {
+    status: {
+        description: "Running work, queued reasons, results to review and plan windows, over the projects you may see.",
+        acts: false,
+        argv: () => ["status"],
+    },
+    list_tasks: {
+        description: "A page of tasks in the projects you may see. Filter by state and repo; cursor-paginated.",
+        acts: false,
+        argv: args => [
+            "task", "list",
+            ...(args.state === undefined ? [] : ["--state", args.state]),
+            ...(args.repo === undefined ? [] : ["--repo", args.repo]),
+            ...(args.cursor === undefined ? [] : ["--cursor", String(args.cursor)]),
+            ...(args.limit === undefined ? [] : ["--limit", String(args.limit)]),
+        ],
+    },
+    task_show: {
+        description: "One task in full. A task outside your projects answers unknown-task.",
+        acts: false,
+        argv: args => ["task", "show", args.ref],
+    },
+    task_review: {
+        description: "A task's compact result packet: saved conclusion, changed files, checks, findings, screenshots, plan and next actions. Pass run for an exact finished attempt; all includes LOW findings.",
+        acts: false,
+        argv: args => ["task", "review", args.ref, "--brief", ...(args.run === undefined ? [] : ["--run", String(args.run)]), ...(args.all === true ? ["--all"] : [])],
+    },
+    review_findings: {
+        description: "One run's automatic review findings.",
+        acts: false,
+        argv: args => ["task", "review", String(args.run)],
+    },
+    file_task: {
+        description: "File a task into one of your projects, under your name. It waits for approval as usual; approving stays in the console or chat. Replaying the same idempotency_key returns the first answer.",
+        acts: true,
+        argv: args => ["task", "add", args.title, "--repo", args.repo, "--key", args.idempotency_key, ...(args.deliverable === "report" ? ["--report"] : [])],
+    },
+};
+const NAMES = Object.keys(PERSON_TOOL_INPUTS);
+/** What this person may call: every read, and the acts only on an act token of an account that acts. */
+export function personTools(person) {
+    return NAMES.filter(name => mayCall(person, name)).map(name => ({ name, description: TOOLS[name].description, inputSchema: toModelSchema(PERSON_TOOL_INPUTS[name]) }));
+}
+const mayCall = (person, name) => !TOOLS[name].acts || person.principal.scope === "act" && person.role === "approver";
+/** One person tools/call: read by its schema, checked against the person, then run as the command it names. */
+export async function callPersonTool(person, store, runAs, params) {
+    const name = typeof params["name"] === "string" ? params["name"] : "";
+    if (!NAMES.includes(name))
+        return { kind: "error", code: -32602, message: `no tool \`${name}\``, fatal: false };
+    const tool = name;
+    const rawArgs = callArguments(params);
+    if (rawArgs === null)
+        return { kind: "error", code: -32602, message: "arguments must be an object", fatal: false };
+    const read = parseContract(PERSON_TOOL_INPUTS[tool], rawArgs);
+    if (!read.ok)
+        return { kind: "error", code: -32602, message: read.issues.map(one => one.line).join("; "), fatal: false };
+    if (!mayCall(person, tool)) {
+        const why = person.principal.scope === "read" ? "this token reads only — make an act token in the console to file work" : "your account can watch, not act";
+        return refused(`${tool}: ${why}`);
+    }
+    const argv = [...TOOLS[tool].argv(read.value), "--json"];
+    let written = "";
+    let code;
+    try {
+        code = await runAs(argv, { principal: person.principal, store, write: chunk => { written += chunk; }, source: "mcp" });
+    }
+    catch (error) {
+        return refused(`the command failed on the server: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const text = written.trim();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return refused(text === "" ? `the command answered nothing (exit ${code})` : text);
+    }
+    const ok = code === 0 && typeof body === "object" && body !== null && body["ok"] === true;
+    if (ok)
+        reportToolOutput("gateway", tool, PERSON_TOOL_OUTPUTS[tool], body);
+    return { kind: "result", result: ok ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text }], isError: true } };
+}
+const refused = (message) => ({ kind: "result", result: { content: [{ type: "text", text: message }], isError: true } });

package/dist/mcp.d.ts

@@ -1,12 +1,5 @@
 import type { Store } from "./store.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 { LEGACY, META_CAPABILITIES, META_SERVER, META_VERSION, MODERN, UNSUPPORTED_VERSION } from "./mcp-core.js";
 export type McpIo = {
     onLine: (handler: (line: string) => void) => void;
     onEof: (handler: () => void) => void;