@intentic/sandbox-contract 1.245.0 → 1.247.0

package/src/peer-mcp-server.test.ts

@@ -0,0 +1,104 @@
+import { expect, test } from "vitest";
+import { z } from "zod";
+import { createMcpServer, type McpAuditEntry, textResult, tool } from "./peer-mcp-server.js";
+
+/* The dispatch every peer serves its tools through, against two hand-written tools: what the model is shown,
+ * what an arriving call is checked against, and the rule that a failed tool is a result and not a fault. */
+
+class Refused extends Error {}
+
+const build = () => {
+    const audits: McpAuditEntry[] = [];
+    const handle = createMcpServer<{ readonly allowed: boolean }>({
+        serverInfo: () => ({ name: "intentic-test", version: "9.9.9" }),
+        tools: [
+            tool({
+                name: "echo",
+                description: "Say it back.",
+                input: z.object({ text: z.string().min(1) }),
+                run: async ({ text }, ctx) => {
+                    if (!ctx.allowed) {
+                        throw new Refused("the switch is off");
+                    }
+                    return textResult(text);
+                },
+            }),
+            tool({
+                name: "fail",
+                description: "Always errs as a result.",
+                input: z.object({}),
+                run: async () => textResult("nope", true),
+            }),
+        ],
+        noSuchTool: (name) => `This peer has no tool called "${name}".`,
+        refused: (error) => error instanceof Refused,
+        errorMessage: (error) => (error instanceof Error ? error.message : String(error)),
+        audit: (entry) => void audits.push(entry),
+    });
+    return { handle, audits };
+};
+
+const call = (name: string, args: Record<string, unknown>, allowed = true) => build().handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, { allowed });
+
+test("initialize names the peer and its build; ping answers empty; an unknown method is a JSON-RPC error", async () => {
+    const { handle } = build();
+    expect(await handle({ jsonrpc: "2.0", id: 1, method: "initialize" }, { allowed: true })).toMatchObject({
+        result: { capabilities: { tools: {} }, serverInfo: { name: "intentic-test", version: "9.9.9" } },
+    });
+    expect(await handle({ jsonrpc: "2.0", id: 2, method: "ping" }, { allowed: true })).toEqual({ jsonrpc: "2.0", id: 2, result: {} });
+    expect(await handle({ jsonrpc: "2.0", id: 3, method: "resources/list" }, { allowed: true })).toMatchObject({ error: { code: -32601 } });
+    expect(await handle({ jsonrpc: "2.0", method: "notifications/initialized" }, { allowed: true })).toBeUndefined();
+    expect(await handle("not an object", { allowed: true })).toMatchObject({ error: { code: -32600 } });
+});
+
+test("tools/list publishes each tool's schema as JSON Schema, without the dialect line", async () => {
+    const { handle } = build();
+    const listed = (await handle({ jsonrpc: "2.0", id: 1, method: "tools/list" }, { allowed: true })) as { result: { tools: { name: string; inputSchema: Record<string, unknown> }[] } };
+    expect(listed.result.tools.map((entry) => entry.name)).toEqual(["echo", "fail"]);
+    expect(listed.result.tools[0]?.inputSchema).toMatchObject({ type: "object", properties: { text: { type: "string" } } });
+    expect(listed.result.tools[0]?.inputSchema).not.toHaveProperty("$schema");
+});
+
+test("a call is checked against the same schema, and a bad argument is a readable result, not a fault", async () => {
+    expect(await call("echo", { text: "hi" })).toEqual({ jsonrpc: "2.0", id: 1, result: { content: [{ type: "text", text: "hi" }], isError: false } });
+    const bad = (await call("echo", { text: "" })) as { result: { content: { text: string }[]; isError: boolean } };
+    expect(bad.result.isError).toBe(true);
+    expect(bad.result.content[0]?.text).toContain("text");
+});
+
+test("a tool this peer does not have answers in the peer's own words", async () => {
+    expect(await call("delete_everything", {})).toEqual({
+        jsonrpc: "2.0",
+        id: 1,
+        result: { content: [{ type: "text", text: `This peer has no tool called "delete_everything".` }], isError: true },
+    });
+});
+
+test("a thrown refusal and a thrown failure are both results, and the audit line says which", async () => {
+    const { handle, audits } = build();
+    const refused = (await handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "echo", arguments: { text: "hi" } } }, { allowed: false })) as {
+        result: { content: { text: string }[]; isError: boolean };
+    };
+    expect(refused.result).toEqual({ content: [{ type: "text", text: "the switch is off" }], isError: true });
+    await handle({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "fail", arguments: {} } }, { allowed: true });
+    await handle({ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "echo", arguments: { text: "ok" } } }, { allowed: true });
+    expect(audits).toEqual([
+        { tool: "echo", args: { text: "hi" }, ok: false, failure: { refused: true, message: "the switch is off" } },
+        { tool: "fail", args: {}, ok: false },
+        { tool: "echo", args: { text: "ok" }, ok: true },
+    ]);
+});
+
+test("an audit log that cannot be written never fails the answer", async () => {
+    const handle = createMcpServer<undefined>({
+        serverInfo: () => ({ name: "x", version: "1" }),
+        tools: [tool({ name: "hi", description: "Hi.", input: z.object({}), run: async () => textResult("hi") })],
+        noSuchTool: () => "no",
+        refused: () => false,
+        errorMessage: String,
+        audit: () => {
+            throw new Error("disk full");
+        },
+    });
+    expect(await handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "hi", arguments: {} } }, undefined)).toMatchObject({ result: { isError: false } });
+});

package/src/peer-mcp-server.ts

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { MCP_PROTOCOL_VERSION } from "./host-protocol.js";
+
+/* THE MCP SERVER A PEER RUNS, on the peer, not in the sandbox.
+ *
+ * The sandbox's daemon forwards JSON-RPC verbatim and interprets none of it, so the tool table handed to this is
+ * the entire tool surface: what a device or a browser can do is decided by the build installed on it, and a
+ * peer that upgrades learns new tools without anything changing in the sandbox. That is the reason for the
+ * split; the alternative (schemas in the daemon, execution on the peer) makes every new tool a coordinated
+ * release of two products.
+ *
+ * The protocol implemented is the subset a Streamable HTTP client actually uses against a stateless server:
+ * initialize, tools/list, tools/call, ping, and notifications (which get no reply). Anything else answers
+ * "method not found", which is the correct JSON-RPC response and not an error worth logging.
+ *
+ * A FAILED TOOL IS NOT A FAILED CALL. Every error, a refused scope, a missing file, a command that exited 1, an
+ * argument that does not typecheck, comes back as a normal result with isError, because that is what a model can
+ * read and act on; a JSON-RPC error surfaces as a transport fault and invites a retry loop against a peer that
+ * will refuse it exactly the same way the second time.
+ *
+ * EACH TOOL'S ARGUMENTS ARE DESCRIBED ONCE. The zod schema a tool is built with is what the model is shown
+ * (`tools/list` publishes it as JSON Schema) AND what an arriving call is checked against, so the advertised
+ * shape and the accepted one cannot drift, the failure mode of writing both by hand, where a renamed field
+ * keeps validating and the model keeps being told about the old name. A handler receives its arguments typed. */
+
+export interface McpTool<Ctx> {
+    readonly name: string;
+    readonly description: string;
+    // JSON Schema for `tools/list`, derived from the zod schema once at module load rather than per request.
+    readonly inputSchema: Record<string, unknown>;
+    readonly call: (args: unknown, ctx: Ctx) => Promise<Record<string, unknown>>;
+}
+
+export const textResult = (text: string, isError = false): Record<string, unknown> => ({ content: [{ type: "text", text }], isError });
+
+/* One tool, from the only description of its arguments there is. The generic is what carries the schema's type
+ * through to the handler's parameter; `McpTool` erases it again, because the dispatch table holds them all and
+ * the parse is what re-establishes the type at the boundary. `Ctx` is what the peer hands every call beside
+ * its arguments: a device's live grant, nothing for a browser.
+ *
+ * `$schema` is dropped: the enclosing tool entry already says what this document is, and MCP clients read the
+ * keywords rather than the dialect declaration. */
+export const tool = <Schema extends z.ZodType, Ctx>(spec: {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Schema;
+    readonly run: (args: z.output<Schema>, ctx: Ctx) => Promise<Record<string, unknown>>;
+}): McpTool<Ctx> => {
+    const { $schema: _dialect, ...inputSchema } = z.toJSONSchema(spec.input, { io: "input" });
+    return {
+        name: spec.name,
+        description: spec.description,
+        inputSchema,
+        call: async (args, ctx) => {
+            const parsed = spec.input.safeParse(args);
+            // Readable enough for a model to fix its own call: which field, and what was expected there.
+            return parsed.success ? await spec.run(parsed.data, ctx) : textResult(z.prettifyError(parsed.error), true);
+        },
+    };
+};
+
+// What the peer's audit log is told about one call: the arguments verbatim (redaction is the peer's, it knows
+// which of its tools carry typed secrets), and how it ended. A tool that answered with isError is `ok: false`
+// with no message; one that threw carries what it said, and whether it was the peer's own refusal.
+export interface McpAuditEntry {
+    readonly tool: string;
+    readonly args: Record<string, unknown>;
+    readonly ok: boolean;
+    readonly failure?: { readonly refused: boolean; readonly message: string };
+}
+
+export interface McpServerSpec<Ctx> {
+    readonly serverInfo: () => { readonly name: string; readonly version: string };
+    readonly tools: readonly McpTool<Ctx>[];
+    // The sentence for a tool this peer does not have, in the peer's own noun.
+    readonly noSuchTool: (name: string) => string;
+    // Whether a thrown error is this peer's own refusal (a switch that is off, a site that is not granted) as
+    // opposed to a tool that failed: the audit line says which.
+    readonly refused: (error: unknown) => boolean;
+    readonly errorMessage: (error: unknown) => string;
+    // Every call, accepted or refused, once it has an outcome. Best-effort: a log that cannot be written must
+    // never fail the answer, so a rejection here is swallowed.
+    readonly audit: (entry: McpAuditEntry) => Promise<void> | void;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// Handle one JSON-RPC message. Returns the response, or undefined for a notification (nothing to answer). `ctx`
+// is read per call by the tool that runs, so a grant pushed mid-session takes effect on the very next call.
+export const createMcpServer = <Ctx>(spec: McpServerSpec<Ctx>): ((message: unknown, ctx: Ctx) => Promise<Record<string, unknown> | undefined>) => {
+    const byName = new Map(spec.tools.map((entry) => [entry.name, entry]));
+    const listing = spec.tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+    const audited = async (entry: McpAuditEntry): Promise<void> => {
+        try {
+            await spec.audit(entry);
+        } catch {
+            // Deliberately silent: a record for a human, never a control.
+        }
+    };
+
+    const callTool = async (name: string, args: Record<string, unknown>, ctx: Ctx): Promise<Record<string, unknown>> => {
+        const found = byName.get(name);
+        if (found === undefined) {
+            return textResult(spec.noSuchTool(name), true);
+        }
+        try {
+            const result = await found.call(args, ctx);
+            await audited({ tool: name, args, ok: result["isError"] !== true });
+            return result;
+        } catch (error) {
+            const message = spec.errorMessage(error);
+            await audited({ tool: name, args, ok: false, failure: { refused: spec.refused(error), message } });
+            return textResult(message, true);
+        }
+    };
+
+    return async (message, ctx) => {
+        if (!isRecord(message)) {
+            return { jsonrpc: "2.0", id: null, error: { code: -32600, message: "invalid request" } };
+        }
+        const id = message["id"];
+        if (id === undefined) {
+            return undefined;
+        }
+        const method = message["method"];
+        const reply = (result: Record<string, unknown>): Record<string, unknown> => ({ jsonrpc: "2.0", id, result });
+        if (method === "initialize") {
+            return reply({ protocolVersion: MCP_PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: spec.serverInfo() });
+        }
+        if (method === "ping") {
+            return reply({});
+        }
+        if (method === "tools/list") {
+            return reply({ tools: listing });
+        }
+        if (method === "tools/call") {
+            const params = isRecord(message["params"]) ? message["params"] : {};
+            const name = typeof params["name"] === "string" ? params["name"] : "";
+            const args = isRecord(params["arguments"]) ? params["arguments"] : {};
+            return reply(await callTool(name, args, ctx));
+        }
+        return { jsonrpc: "2.0", id, error: { code: -32601, message: `method "${String(method)}" is not supported` } };
+    };
+};

package/src/plan-pools.ts

@@ -6,7 +6,7 @@ import type { AccountUsage, UsageWindow, WindowGates } from "./schemas/plan-limi
  * call, is this Google fleet spent for Claude Opus, when does the pool that refused this turn reopen, what
  * does the ring beside the composer measure. The pools a reading carries answer that only through their
  * `gates` (UsageWindowSchema says why the reader decides them), and this file is the one place the gate is
- * read, so the daemon's account picker, its quick-model walk, its refusal dressing and the browser's rings,
+ * read, so the daemon's account picker, its one-shot helper walk, its refusal dressing and the browser's rings,
  * rail and picker rows all agree about which pool is binding for a given model.
  *
  * WITHOUT A MODEL the answer is the account's own tightest pool, which is what a roster or a rail that has not

package/src/prompt-complexity.test.ts

@@ -88,7 +88,7 @@ test("plan mode is a request to think, so it is never answered by the model that
 });
 
 test("a surface-started run is never downgraded, because nobody is watching it fail", () => {
-    // Same call agentRunModels already makes in the other direction: a run billed whole, with a worktree in
+    // Same call a `run` role already makes in the other direction: a run billed whole, with a worktree in
     // it, is not the place to spend a guess.
     expect(tierOf(`what is a closure?`, { unattended: true })).toBe(`standard`);
 });

package/src/prompt-complexity.ts

@@ -3,7 +3,7 @@
  * The job is narrow on purpose: decide whether this turn could have run on the cheap rung of the provider the
  * user is already on. Nothing here picks a model, nothing here reads a catalog, and nothing here calls
  * anything. It is a pure function over the turn's own words and shape, so the daemon and the composer can both
- * ask it and get the same answer, which is the same reason quick-model.ts lives in the contract rather than in
+ * ask it and get the same answer, which is the same reason model-pins.ts lives in the contract rather than in
  * either of them.
  *
  * IT CAN ONLY EVER ROUTE DOWN. The standard tier is not a setting: it is whatever the user already picked. So
@@ -213,7 +213,7 @@ const forcing = (input: ComplexityInput, text: string): ComplexityRule[] => {
         rules.push("plan-mode");
     }
     /* An unattended run is billed whole and nobody is watching it fail. The settings this repo already ships
-     * make the same call in the other direction: agentRunModels resolves to NOTHING when empty precisely
+     * make the same call in the other direction: a `run` role resolves to NOTHING when empty precisely
      * because "nothing here can judge whether a job is worth the frontier tier". This file does judge, but not
      * for the runs where a wrong guess costs a whole session with a worktree in it. */
     if (input.unattended) {

package/src/provider-specs.test.ts

@@ -1,7 +1,16 @@
 import { PROVIDER_BRAND_PATHS } from "@intentic/constants";
 import { describe, expect, test } from "vitest";
 import { accessFor, capabilitiesOf, harnessChoosable, PROVIDER_ACCESS, PROVIDER_VENDOR, PROVIDERS, providerLabel } from "./agent-catalog.js";
-import { ACCESS_COST, cliProxyIdOf, KEY_PROVIDERS, keyEndpointOf, NATIVE_PROVIDERS, PROVIDER_SPECS, providerSpec } from "./provider-specs.js";
+import {
+    ACCESS_COST,
+    cliProxyIdOf,
+    MINTED_PROVIDERS,
+    mintedVariant,
+    mintedVariants,
+    NATIVE_PROVIDERS,
+    PROVIDER_SPECS,
+    providerSpec,
+} from "./provider-specs.js";
 import { NativeProviderParamSchema } from "./schemas/agent.js";
 import { TranslatorAccountsSchema } from "./schemas/plan-limits.js";
 import { KeyedProviderSchema } from "./schemas/provider-subscriptions.js";
@@ -44,22 +53,39 @@ describe("every provider in the table", () => {
             expect(Object.keys(TranslatorAccountsSchema.shape), `${id} has no slot in TranslatorAccounts`).toContain(id);
             return;
         }
-        if (spec.auth.kind === "key") {
-            const endpoint = keyEndpointOf(id);
-            expect(endpoint, `${id} is keyed but names no endpoint`).toMatchObject({ kind: "key" });
-            expect(KEY_PROVIDERS, `${id} is keyed but missing from KEY_PROVIDERS`).toContain(id);
-            /* THE TURN URL AND THE CATALOG URL ARE DIFFERENT SURFACES OF ONE VENDOR, and both halves of that
-             * sentence are asserted: same host (a pair that drifted apart would send the catalog to one vendor
-             * and the turn to another), and the turn's base carries NO version segment, because the harness
-             * appends `/v1/messages` itself and a doubled one is a 404 mid-conversation. */
-            expect(new URL(endpoint!.anthropicBase).host, `${id}'s catalog and turn hosts differ`).toBe(new URL(endpoint!.catalogBase).host);
-            expect(endpoint!.anthropicBase, `${id}'s turn base carries a version segment the harness would double`).not.toMatch(/\/v\d+$/);
-            expect(new URL(endpoint!.console).protocol, `${id}'s key console is not a link`).toBe("https:");
+        if (spec.auth.kind === "minted") {
+            expect(MINTED_PROVIDERS, `${id} is minted but missing from MINTED_PROVIDERS`).toContain(id);
+            // At least one estate to sign in to, because the head of this list is what a `login/start` that names
+            // no variant gets: an empty one is a provider whose connect row has no button that can do anything.
+            expect(spec.auth.variants.length, `${id} is minted but offers no estate to sign in to`).toBeGreaterThan(0);
+            for (const variant of spec.auth.variants) {
+                /* THE TURN URL AND THE CATALOG URL ARE DIFFERENT SURFACES OF ONE ESTATE, and both halves of that
+                 * sentence are asserted: same host (a pair that drifted apart would send the catalog to one
+                 * vendor and the turn to another), and the turn's base carries NO version segment, because the
+                 * harness appends `/v1/messages` itself and a doubled one is a 404 mid-conversation. */
+                expect(new URL(variant.anthropicBase).host, `${id}/${variant.id}'s catalog and turn hosts differ`).toBe(
+                    new URL(variant.catalogBase).host,
+                );
+                expect(variant.anthropicBase, `${id}/${variant.id}'s turn base carries a version segment the harness would double`).not.toMatch(
+                    /\/v\d+$/,
+                );
+                expect(variant.label.trim(), `${id}/${variant.id} has no estate label`).not.toBe("");
+                // The lookup every surface goes through, rather than the row behind it: an id that names a
+                // variant must resolve to that variant and nothing else.
+                expect(mintedVariant(id, variant.id), `${id}/${variant.id} does not resolve`).toEqual(variant);
+            }
+            // An absent variant takes the head of the list, which is what a single-estate provider's connect row
+            // always sends and what a `login/start` with no choice on it means.
+            expect(mintedVariant(id), `${id}'s default estate is not the head of its list`).toEqual(spec.auth.variants[0]);
+            // An estate id nobody declared is NOT the default: falling back would mint a key on one estate and
+            // dial it at another, and report the refusal as an authentication problem.
+            expect(mintedVariant(id, "no-such-estate"), `${id} defaults an unknown estate instead of refusing`).toBeUndefined();
             return;
         }
         // An oauth provider is served by a handshake this daemon runs; it is in neither routed list.
         expect(KeyedProviderSchema.options, `${id} is not routed but appears in KeyedProvider`).not.toContain(id);
-        expect(KEY_PROVIDERS, `${id} is not keyed but appears in KEY_PROVIDERS`).not.toContain(id);
+        expect(MINTED_PROVIDERS, `${id} is not minted but appears in MINTED_PROVIDERS`).not.toContain(id);
+        expect(mintedVariants(id), `${id} is not minted but names estates`).toBeUndefined();
     });
 
     test.each(PROVIDER_SPECS.map((spec) => ({ id: spec.id })))("$id is in every derived list", ({ id }) => {
@@ -89,7 +115,7 @@ test("provider ids are unique", () => {
 
 /* An id may contain neither a slash nor a colon, and both exclusions are load-bearing rather than tidy.
  * `endpoint/<id>` uses the slash to namespace a capability-minted provider, and the picker's pinned selections
- * are `${provider}:${model}` split on the FIRST colon (quick-model.ts), so an id carrying either would parse as
+ * are `${provider}:${model}` split on the FIRST colon (model-pins.ts), so an id carrying either would parse as
  * something else entirely, silently. */
 test("no provider id can be mistaken for an endpoint or a pinned selection", () => {
     for (const spec of PROVIDER_SPECS) {
@@ -109,11 +135,11 @@ test("the harness chip is offered exactly where the two harnesses run different
     }
 });
 
-/* A KEYED PROVIDER HAS NO NATIVE RUNTIME, by construction rather than by coincidence: it is reached by pointing
+/* A MINTED PROVIDER HAS NO NATIVE RUNTIME, by construction rather than by coincidence: it is reached by pointing
  * the Claude Code loop at the vendor's own Anthropic endpoint, and there is no second loop to point anywhere
  * else. A spec row that claimed one would produce a picker chip offering a runtime nothing serves. */
-test("a keyed provider runs the Claude Code loop on both harnesses", () => {
-    for (const provider of KEY_PROVIDERS) {
+test("a minted provider runs the Claude Code loop on both harnesses", () => {
+    for (const provider of MINTED_PROVIDERS) {
         expect(capabilitiesOf(provider, "native").runtime, provider).toBe("claude-code");
         expect(capabilitiesOf(provider, "claude-code").runtime, provider).toBe("claude-code");
     }
@@ -125,6 +151,7 @@ test("an id that is not a provider resolves to nothing", () => {
     for (const id of ["", "some-installed-agent", "endpoint/ollama", "META", "z.ai"]) {
         expect(providerSpec(id), id).toBeUndefined();
         expect(cliProxyIdOf(id), id).toBeUndefined();
-        expect(keyEndpointOf(id), id).toBeUndefined();
+        expect(mintedVariants(id), id).toBeUndefined();
+        expect(mintedVariant(id), id).toBeUndefined();
     }
 });