toolroll 0.9.40 → 0.9.42

package/dist/contracts/console-api.js

@@ -0,0 +1,273 @@
+/**
+ * The console's form bodies and JSON API (docs/plans/zod-revamp.md, item 13): one schema for every URL-encoded body a
+ * console route reads, and one for each `?format=json` response.
+ *
+ * A form is read exactly as before. Each field is what `URLSearchParams` holds for it — every value in the order
+ * sent, so `get()` is the first and `getAll()` the list — and every field may be left out, because each handler
+ * already supplies its own default, trimming, clipping, number conversion and refusal after reading. Unknown fields
+ * are ignored (browsers send `csrf`, buttons send their own names, and older pages send fields no longer read). What a
+ * handler may read is the schema's field list: `readForm` hands it a view typed by that list, so reading a field the
+ * contract doesn't name fails the typecheck instead of drifting. Nothing a person or script sent before is refused
+ * now; the CSRF, nonce, digest, password and duplicate-field checks stay in the handlers, in their order.
+ *
+ * The JSON responses are checked as they are sent (unversioned, unknown keys allowed, their bytes unchanged — an
+ * evidence pack carries sealed ledger entries); a response that disagrees is logged and sent anyway.
+ *
+ * Not here: Telegram's pushed updates (item 11), flow webhooks and public flow forms (item 15).
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+/** One form field: every value sent for it, in order. Text only — a URL-encoded body has nothing else. */
+const formField = z.array(z.string());
+/** A form's contract: a loose object of optional text fields (unknown fields ignored, as the handlers always did). */
+export function formContract(route, fields, more = {}) {
+    const schema = z.looseObject(Object.fromEntries(fields.map(field => [field, formField.optional()]))).catchall(formField);
+    return { route, fields, prefixes: more.prefixes ?? [], dynamic: more.dynamic ?? false, schema: schema };
+}
+/**
+ * A body as its schema sees it: each field name once, in first-sent order, with all its values in sent order. Built
+ * with `Object.fromEntries`, so a field named `__proto__` is an ordinary field.
+ */
+export function formFields(body) {
+    const fields = new Map();
+    for (const [name, value] of body) {
+        const values = fields.get(name);
+        if (values === undefined)
+            fields.set(name, [value]);
+        else
+            values.push(value);
+    }
+    return Object.fromEntries(fields);
+}
+const toStderr = (what, issues) => {
+    process.stderr.write(`${what}: disagrees with its contract — ${issues.map(one => one.line).join("; ")}\n`);
+};
+/**
+ * Read a form through its contract. It never refuses: every value is text and every field optional, so a body that
+ * somehow disagrees is reported and read as it was sent (the handler's own checks decide, as before).
+ */
+export function readForm(body, contract, report = toStderr) {
+    const parsed = parseContract(contract.schema, formFields(body));
+    if (!parsed.ok)
+        report(`form ${contract.route}`, parsed.issues);
+    return {
+        get: name => body.get(name),
+        getAll: name => body.getAll(name),
+        has: name => body.has(name),
+        keys: () => body.keys(),
+        sent: body,
+    };
+}
+// ---- every console form ------------------------------------------------------------------------------------------
+//
+// One per route (or per verb, where one route takes several bodies). A family whose sub-routes share one dispatch —
+// `/code/*`, `/flows/*`, the teammate pages, Slack/Teams/Discord — has one contract naming every field its handlers
+// read. Every body also passes through `mutationGuardForm` (the shared CSRF and duplicate check, unchanged) and
+// `ledgerTargetForm` (the project a request is recorded against).
+export const CONSOLE_FORMS = {
+    // Before sign-in.
+    signup: formContract("POST /signup", ["code", "name", "password"]),
+    login: formContract("POST /login", ["name", "token", "return"]),
+    join: formContract("POST /join/<invite>", ["name", "password"]),
+    // Shared by every signed-in POST.
+    mutationGuard: formContract("POST (every signed-in form)", ["csrf", "token", "digest", "nonce", "confirm"]),
+    ledgerTarget: formContract("POST (the action ledger's project)", ["repo"]),
+    projectCeiling: formContract("POST (project ceiling)", ["repo"]),
+    demo: formContract("POST /chat/demo/<act>", ["message", "note"]),
+    updatesDismiss: formContract("POST /settings/updates/dismiss", ["version", "quiet", "return"]),
+    updatesChecks: formContract("POST /settings/updates/checks", ["check"]),
+    code: formContract("POST /code, /code/start, /code/<session>/<act>", ["repo", "password", "title", "model", "prompt", "requestId", "base", "candidate", "goal", "acceptance", "visual", "decision", "answers"], { prefixes: ["question:"] }),
+    skillsRevise: formContract("POST /settings/skills/revise", ["run", "repo", "feedback", "nonce"]),
+    skillsChange: formContract("POST /settings/skills/import, /settings/skills/change", ["repo", "identity", "revision", "method", "content", "files", "url", "action", "sha", "sample", "nonce", "restore"]),
+    kit: formContract("POST /kits/<kit>/<act>", ["repo"]),
+    teammates: formContract("POST /teammates/new, /teammates/<id>/<part>, /teammates/questions/<id>/answer", ["choice", "text", "repo", "template", "name", "soul", "op", "id", "schedule", "tool", "state", "note", "model", "dailyTurns", "manager"], { prefixes: ["use.", "undo.", "field.", "over."] }),
+    galleryUse: formContract("POST /flows/new/<template>", ["repo", "send-result", "name", "intent", "previewed"], { dynamic: true }),
+    flows: formContract("POST /flows/new, /flows/example, /flows/import, /flows/<id>/<act>, /flows/<id>/cards/<card>/<act>, /flows/<id>/triggers/<trigger>/<act>", ["repo", "document", "url", "confirm", "previewed", "template", "name", "answers", "password", "secret", "trigger", "approve", "remove", "about", "body", "timeoutMinutes", "language", "file", "address", "key", "definition", "owner", "revision", "value", "title", "description", "stage", "decision", "note", "draft", "choice", "entry", "label", "watching"], { prefixes: ["param."] }),
+    spendBudget: formContract("POST /spend/budget", ["password", "target", "action", "usd", "stop"]),
+    projectConcurrency: formContract("POST /settings/project/concurrency", ["repo", "concurrency"]),
+    projectDelete: formContract("POST /settings/project/delete", ["repo", "name", "step", "password"]),
+    policy: formContract("POST /settings/policy", ["password", "provider", "models", "tools", "ceiling"]),
+    approval: formContract("POST /settings/approval", ["repo", "password", "protect", "paths", "not_requester"]),
+    sessions: formContract("POST /settings/sessions", ["everyone", "action", "session", "token", "name", "access", "days", "password"]),
+    signIn: formContract("POST /settings/sign-in", ["action", "password", "issuer", "client-id", "client-secret", "label", "scopes", "groups-claim", "passwords"], { prefixes: ["group-", "role-", "projects-"] }),
+    updates: formContract("POST /settings/updates, /settings/updates/seen, /settings/updates/cancel", ["password", "version", "when"]),
+    retention: formContract("POST /settings/retention", ["password", "evidence", "checkouts", "chat", "notifications"]),
+    storage: formContract("POST /settings/storage, /settings/storage/clean, /settings/storage/discard", ["password", "cleanup", "preview", "path"]),
+    pullRequests: formContract("POST /settings/pull-requests", ["repo", "act", "password", "github", "base", "method", "when-green"]),
+    checks: formContract("POST /settings/checks", ["repo", "password", "act", "on", "level", "command", "timeout"]),
+    backups: formContract("POST /settings/backups", ["password", "every", "keep", "folder"]),
+    data: formContract("POST /settings/data", ["password"]),
+    flowsOn: formContract("POST /settings/flows/on", ["repo", "starter"]),
+    integrationsTest: formContract("POST /settings/integrations/test", ["key"]),
+    monitoring: formContract("POST /settings/monitoring", ["password", "webhook", "folder", "traces", "header-name", "header-value", "rotate"]),
+    toolsConnect: formContract("POST /settings/tools/connect", ["repo", "also", "service", "template", "kit", "shown", "password", "access"]),
+    toolsChange: formContract("POST /settings/tools/change", ["repo", "shown", "action", "name", "password", "catalog", "transport", "target", "secrets", "import", "secret", "value"]),
+    appearance: formContract("POST /settings/appearance", ["accent", "quiet", "return", "theme"]),
+    models: formContract("POST /settings/models/check, /settings/models/watch, /settings/models/update, /settings/models/agent", ["enabled", "tool", "phase", "agent"]),
+    knowledgeRefresh: formContract("POST /settings/knowledge/refresh", ["repo"]),
+    knowledgeProposal: formContract("POST /settings/knowledge/proposal", ["repo", "decision", "proposal"]),
+    knowledgeDecision: formContract("POST /settings/knowledge/decision", ["repo", "action", "claim", "why", "decision", "reason"]),
+    knowledgeChange: formContract("POST /settings/knowledge/change", ["repo", "action", "identity", "revision", "instructions", "title", "content", "path", "id", "restore"]),
+    learningChange: formContract("POST /settings/learning/change", ["repo", "action", "identity", "revision", "lesson", "version", "sha"]),
+    projectSetup: formContract("POST /control/setup-preview, /control/setup-approve, /control/instructions-preview, /control/instructions-approve", ["repo", "nonce", "fingerprint", "token", "provider", "model", "command", "seconds"]),
+    slack: formContract("POST /settings/slack/<connect|pair|unpair|disconnect|alerts>", ["password", "app-token", "bot-token"]),
+    telegramPair: formContract("POST /settings/telegram/pair, /settings/telegram/unpair", ["password"]),
+    teams: formContract("POST /settings/teams/<connect|pair|unpair|disconnect|alerts>", ["password", "app-id", "tenant", "secret"]),
+    discord: formContract("POST /settings/discord/<connect|pair|unpair|disconnect|alerts>", ["password", "bot-token"]),
+    messaging: formContract("POST /settings/messaging", ["primary"]),
+    permissionDefault: formContract("POST /settings/permission-default", ["permission-mode"]),
+    qualityDefault: formContract("POST /settings/quality-default", ["quality-mode"]),
+    notifications: formContract("POST /settings/notifications", ["mode", "digest", "screenshots"]),
+    notificationsMute: formContract("POST /settings/notifications/mute", ["repo", "pings"]),
+    telegramDigest: formContract("POST /settings/telegram-digest", ["every"]),
+    providerKey: formContract("POST /settings/provider-key, /settings/provider-key-clear", ["provider", "auth-mode", "value"]),
+    telegramToken: formContract("POST /settings/telegram-token", ["token"]),
+    email: formContract("POST /settings/email, /settings/email-test, /settings/email-read-test", ["host", "port", "secure", "user", "from", "password", "imapHost", "imapPort"]),
+    google: formContract("POST /settings/google, /settings/google/disconnect", ["clientId", "clientSecret"]),
+    projectsSelect: formContract("POST /projects/select", ["path", "return"]),
+    projectsRemove: formContract("POST /projects/remove", ["repo"]),
+    projectsOpen: formContract("POST /projects/open", ["path", "return"]),
+    tasksAdd: formContract("POST /tasks/add", ["projectRevision", "id", "title", "repo", "goal", "not", "touches", "scout", "permission-mode", "quality-mode", "after", "acceptance", "planning-policy", "plan-first"]),
+    queue: formContract("POST /queue/move, /queue/note", ["runner", "note", "from", "projectRevision", "respond", "task", "column", "before", "queueRevision"]),
+    runnerRegister: formContract("POST /fleet/runner/register", ["token", "name", "capacity"]),
+    mode: formContract("POST /mode/confirm, /mode/sign", ["name", "days", "auto-approve", "plan-auto", "allow-paid-fallback", "chat-approve", "publication", "expiry", "nonce", "digest", "token", "review-auto", "review-retry-auto", "repair-auto"]),
+    peopleProjects: formContract("POST /people/projects", ["token", "name", "access", "projects"]),
+    peopleInvite: formContract("POST /people/invite", ["token", "role", "access", "projects"]),
+    peopleInviteRevoke: formContract("POST /people/invite-revoke", ["token", "id"]),
+    peopleRevoke: formContract("POST /people/revoke", ["token", "name"]),
+    runnerRetire: formContract("POST /fleet/runner/retire", ["token", "name"]),
+    decisionAnswer: formContract("POST /d/<id>/answer", ["return", "choice", "confirm", "note"]),
+    contest: formContract("POST /contest/<id>/arm|pick|abandon", ["act", "choice", "token", "nonce"]),
+    attend: formContract("POST /t/<task>/attend|attend-preview|attend-revoke", ["parent", "followup", "minutes", "turns", "budget", "expiry", "model", "posture", "nonce", "digest", "token"]),
+    confirmStopped: formContract("POST /t/<task>/confirm-stopped", ["run", "token", "checked", "return"]),
+    merge: formContract("POST /t/<task>/merge", ["run", "token", "anyway"]),
+    onboard: formContract("POST /projects/onboard-preview, /projects/onboard-confirm", ["repo", "root", "token", "nonce", "big-ok"]),
+    pushSubscribe: formContract("POST /push/subscribe", ["token", "endpoint", "p256dh", "auth"]),
+    pushRemove: formContract("POST /push/remove", ["id"]),
+    phoneDismiss: formContract("POST /onboarding/phone/dismiss", ["quiet"]),
+    leadIdentity: formContract("POST /settings/lead/identity", ["name", "persona"]),
+    leadAbout: formContract("POST /settings/lead/about", ["about"]),
+    leadPromiseCancel: formContract("POST /settings/lead/promise/cancel", ["promise"]),
+    chatConfig: formContract("POST /chat/config", ["return", "token", "off", "forget-key", "provider", "model", "weekly-usd", "daily-turns", "key"]),
+    mateMint: formContract("POST /chat/mate/mint", ["return", "ceiling-usd", "token", "follow"]),
+    mateFollow: formContract("POST /chat/mate/follow", ["enabled", "return"]),
+    mateEnd: formContract("POST /chat/mate/end", ["return"]),
+    mateStop: formContract("POST /chat/mate/stop", ["return", "turn"]),
+    mateProposal: formContract("POST /chat/proposal/<id>/confirm|dismiss", ["return", "nonce", "confirm", "token"]),
+    coordinatorProposal: formContract("POST /proposals/<id>/confirm|dismiss", ["return", "confirm"]),
+    chat: formContract("POST /chat", ["task", "project", "result", "mode", "request", "request-session", "message", "token"]),
+    chatFile: formContract("POST /chat/file/<id>", ["token"]),
+    chatAck: formContract("POST /chat/ack/<id>", ["token", "nonce"]),
+    // A recipe's own answers and editor fields are read by recipes.ts from the whole form (`sent`; item 17).
+    recipes: formContract("POST /recipes/prepare, /recipes/preview, /recipes/import, /recipes/launch, /recipes/save", ["repo", "projectRevision", "recipe", "recipeRevision", "document", "purpose", "source", "sourceRevision", "preview", "next"]),
+    routinesAdd: formContract("POST /routines/add", ["projectRevision", "name", "ceiling", "repeat", "interval", "interval-unit", "time", "timezone", "weekday", "schedule", "goal", "not", "touches", "acceptance"]),
+    routine: formContract("POST /routines/<id>/approve|refresh|pause|resume|run-now", ["digest", "nonce", "token"]),
+    runNote: formContract("POST /r/<run>/note", ["note"]),
+    diffComment: formContract("POST /r/<run>/comment", ["return", "tab", "intent", "batch", "source", "note", "path", "line", "request"]),
+    editorLinks: formContract("POST /session/editor-links", ["on", "return"]),
+    turn: formContract("POST /r/<run>/turn", ["text"]),
+    revise: formContract("POST /r/<run>/revise", ["return", "batch", "source"]),
+    followUp: formContract("POST /r/<run>/checks|add-tests", ["return", "level"]),
+    resolveIncident: formContract("POST /i/<id>/resolve", ["return"]),
+    // A task's verbs (/t/<task>/<verb>), one body each.
+    taskSteer: formContract("POST /t/<task>/steer", ["note"]),
+    taskHold: formContract("POST /t/<task>/hold", ["reason"]),
+    taskBlock: formContract("POST /t/<task>/block|unblock", ["on"]),
+    taskRepairDependency: formContract("POST /t/<task>/repair-dependency", ["blocker", "operation", "replacement"]),
+    taskNext: formContract("POST /t/<task>/next", ["undo"]),
+    taskReopen: formContract("POST /t/<task>/reopen", ["token"]),
+    taskRequeue: formContract("POST /t/<task>/requeue", ["note", "return"]),
+    taskFollowUp: formContract("POST /t/<task>/follow-up", ["index"]),
+    taskPlanEdit: formContract("POST /t/<task>/plan-edit", ["saw-plan", "plan-document"]),
+    taskRevision: formContract("POST /t/<task>/accept-revision|reject-revision", ["revision-id", "token"]),
+    taskCancel: formContract("POST /t/<task>/cancel", ["reason"]),
+    taskRoute: formContract("POST /t/<task>/route", ["risk", "size", "risky", "phase", "clear-phase", "agent", "provider", "model", "sawDigest", "return"]),
+    taskScope: formContract("POST /t/<task>/scope", ["sawDigest", "permission-mode", "quality-mode", "budget-usd", "budget-microusd", "requirement", "requirement-new", "race-count", "race-model", "race-per-usd", "race-total-usd", "goal-brief", "goal", "not", "touches", "acceptance"], { prefixes: ["compare-provider-", "compare-model-"] }),
+    taskApprove: formContract("POST /t/<task>/approve", ["return", "digest", "token", "nonce"]),
+    taskAcceptProof: formContract("POST /t/<task>/accept-proof", ["run", "note", "return"]),
+    taskComplete: formContract("POST /t/<task>/complete", ["receipt", "run", "accept", "note", "publish", "return"]),
+    taskStop: formContract("POST /t/<task>/stop", ["run", "return"]),
+    taskResume: formContract("POST /t/<task>/resume|resume-arm", ["run", "token", "nonce", "return"]),
+};
+/** The console POSTs whose handlers read no field (sign-out and the attended beat not even the shared guard): their contract is the empty form. */
+export const BODILESS_POSTS = [
+    "POST /settings/lead/on",
+    "POST /r/<run>/draft-repair",
+    "POST /ledger/checkpoint",
+    "POST /settings/backups/now",
+    "POST /mode/revoke",
+    "POST /settings/telegram/retry",
+    "POST /providers/<provider>/resume",
+    "POST /session/attended-beats",
+    "POST /logout",
+    "POST /t/<task>/unhold",
+    "POST /t/<task>/plan",
+    "POST /t/<task>/retry-review",
+];
+// ---- the JSON API ------------------------------------------------------------------------------------------------
+const ledgerEntrySchema = z.looseObject({
+    id: z.number(), at: z.string(), actor: z.string(), repo: z.string().nullable(), taskId: z.string().nullable(), runId: z.number().nullable(),
+    action: z.string(), outcome: z.string(), source: z.string(), detail: z.string().nullable(),
+});
+/** `GET /ledger?format=json`: the chain's state, a page of entries (newest first) and the cursor for the next. */
+export const ledgerPageSchema = z.looseObject({
+    chain: z.looseObject({ ok: z.boolean(), entries: z.number(), through: z.number().nullable(), head: z.string(), problem: z.looseObject({ id: z.number().nullable(), what: z.string() }).nullable() }),
+    entries: z.array(ledgerEntrySchema),
+    nextBefore: z.number().nullable(),
+});
+/** `GET /t/<task>/evidence?format=json`: a task's evidence pack, as `evidence-pack.ts` builds and digests it. */
+export const evidencePackSchema = z.looseObject({
+    format: z.string(),
+    generatedAt: z.string(),
+    generatedBy: z.string(),
+    task: z.looseObject({ id: z.string(), title: z.string(), state: z.string(), repo: z.string().nullable(), project: z.string().nullable(), filedAt: z.string() }),
+    rules: z.looseObject({ now: z.string(), changes: z.array(z.looseObject({ id: z.number(), at: z.string(), by: z.string(), change: z.string().nullable() })) }).nullable(),
+    versions: z.array(z.looseObject({ id: z.string(), title: z.string(), state: z.string(), filedAt: z.string(), scope: z.looseObject({ digest: z.string() }).nullable(), runs: z.array(z.looseObject({ id: z.number() })) })),
+    result: z.looseObject({ runId: z.number() }).nullable(),
+    totals: z.looseObject({ runs: z.number(), costUsd: z.number(), tokensIn: z.number(), tokensOut: z.number() }),
+    ledger: z.looseObject({
+        entries: z.array(ledgerEntrySchema),
+        truncated: z.boolean(),
+        chain: z.looseObject({ ok: z.boolean(), entries: z.number(), through: z.number().nullable(), head: z.string(), problem: z.string().nullable(), checkedAt: z.string().nullable() }),
+        checkpoint: z.looseObject({ through: z.number(), hash: z.string(), at: z.string() }).nullable(),
+        recipe: z.string(),
+    }),
+    digest: z.string(),
+});
+/** `GET /flows/<id>?format=json`: the flow page's view (the same one the workspace renders). */
+export const flowViewSchema = z.looseObject({
+    kind: z.literal("flow"),
+    flow: z.looseObject({ id: z.number(), name: z.string(), project: z.string(), revision: z.number(), href: z.string(), owner: z.string() }),
+    chatHref: z.string(),
+    triggers: z.array(z.looseObject({})),
+    triggerSetup: z.looseObject({}),
+    startTrigger: z.number().nullable(),
+    me: z.string(),
+    sortReady: z.boolean(),
+    emailReady: z.boolean(),
+    requestSecrets: z.array(z.string()),
+    tools: z.array(z.looseObject({ name: z.string() })),
+    scripts: z.array(z.looseObject({ name: z.string() })),
+    start: z.string(),
+    stages: z.array(z.looseObject({ id: z.string(), kind: z.string() })),
+    cards: z.array(z.looseObject({ id: z.number() })),
+    selectedCard: z.number().nullable(),
+    live: z.string().nullable(),
+    canEdit: z.boolean(),
+    approvers: z.array(z.string()),
+    kinds: z.array(z.looseObject({ kind: z.string(), label: z.string() })),
+    colors: z.array(z.string()),
+});
+export const CONSOLE_RESPONSES = {
+    ledgerPage: { route: "GET /ledger?format=json", schema: ledgerPageSchema },
+    evidencePack: { route: "GET /t/<task>/evidence?format=json", schema: evidencePackSchema },
+    flowView: { route: "GET /flows/<id>?format=json", schema: flowViewSchema },
+};
+/** Check a JSON response just before it is sent; a disagreement is reported, and the payload is returned unchanged. */
+export function checkResponse(name, payload, report = toStderr) {
+    const { route, schema } = CONSOLE_RESPONSES[name];
+    const parsed = parseContract(schema, payload);
+    if (!parsed.ok)
+        report(route, parsed.issues);
+    return payload;
+}

package/dist/contracts/diff-stat.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The terminal diff-stat (`terminal-diff-stat.json`): one schema for what `parseNumstat` and `budgetedStatJson`
+ * write, and the two candidate-inventory reads that use it as a gate's evidence. Toolroll writes it from typed values
+ * in its own key order and never rewrites it, so the stored bytes (and every sha256 bound to them) stay as written.
+ *
+ * Both reads take only the fields their checks use and ignore the rest, exactly as the hand-written checks did: a
+ * legacy gate's endpoints, and a saved assessment's file list. Whether those fields match the run is plain code after
+ * parsing; anything the schema refuses was refused before too.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** One file's row. null additions/deletions = binary. */
+export declare const diffStatFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    additions: z.ZodNullable<z.ZodInt>;
+    deletions: z.ZodNullable<z.ZodInt>;
+    renamedFrom: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const diffStatSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    base: z.ZodString;
+    head: z.ZodString;
+    fileCount: z.ZodInt;
+    additions: z.ZodInt;
+    deletions: z.ZodInt;
+    binaryCount: z.ZodInt;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        additions: z.ZodNullable<z.ZodInt>;
+        deletions: z.ZodNullable<z.ZodInt>;
+        renamedFrom: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    filesTruncated: z.ZodBoolean;
+}, z.core.$strip>;
+export type DiffStat = z.infer<typeof diffStatSchema>;
+export type DiffStatFile = z.infer<typeof diffStatFileSchema>;
+/** What a legacy gate reads of its candidate inventory. `base` may be null, as a run without a base revision has. */
+export declare const candidateEndpointsSchema: z.ZodObject<{
+    head: z.ZodString;
+    filesTruncated: z.ZodBoolean;
+    base: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** What a saved assessment reads: the inventory's identity and every changed path. */
+export declare const savedInventorySchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    base: z.ZodString;
+    head: z.ZodString;
+    fileCount: z.ZodInt;
+    filesTruncated: z.ZodBoolean;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** A legacy gate's endpoints, from the inventory's parsed JSON (the gate names unreadable JSON itself). */
+export declare function readCandidateEndpoints(input: unknown): ContractResult<z.infer<typeof candidateEndpointsSchema>>;
+/** The changed paths of a complete inventory for exactly this candidate, or null: wrong identity, a cut or
+ * miscounted list, or a path named twice. */
+export declare function savedInventoryPaths(text: string, head: string, base: string): Set<string> | null;

package/dist/contracts/diff-stat.js

@@ -0,0 +1,59 @@
+/**
+ * The terminal diff-stat (`terminal-diff-stat.json`): one schema for what `parseNumstat` and `budgetedStatJson`
+ * write, and the two candidate-inventory reads that use it as a gate's evidence. Toolroll writes it from typed values
+ * in its own key order and never rewrites it, so the stored bytes (and every sha256 bound to them) stay as written.
+ *
+ * Both reads take only the fields their checks use and ignore the rest, exactly as the hand-written checks did: a
+ * legacy gate's endpoints, and a saved assessment's file list. Whether those fields match the run is plain code after
+ * parsing; anything the schema refuses was refused before too.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+/** One file's row. null additions/deletions = binary. */
+export const diffStatFileSchema = z.object({
+    path: z.string(),
+    additions: z.int().nullable(),
+    deletions: z.int().nullable(),
+    renamedFrom: z.string().optional(),
+});
+export const diffStatSchema = z.object({
+    schema: z.literal(1),
+    base: z.string(),
+    head: z.string(),
+    fileCount: z.int(),
+    additions: z.int(),
+    deletions: z.int(),
+    binaryCount: z.int(),
+    files: z.array(diffStatFileSchema),
+    /** True when the file list was cut to fit the cap — counts stay complete. */
+    filesTruncated: z.boolean(),
+});
+/** What a legacy gate reads of its candidate inventory. `base` may be null, as a run without a base revision has. */
+export const candidateEndpointsSchema = diffStatSchema.pick({ head: true, filesTruncated: true }).extend({ base: z.string().nullable() });
+/** What a saved assessment reads: the inventory's identity and every changed path. */
+export const savedInventorySchema = diffStatSchema
+    .pick({ schema: true, head: true, base: true, filesTruncated: true, fileCount: true })
+    .extend({ files: z.array(diffStatFileSchema.pick({ path: true })) });
+/** A legacy gate's endpoints, from the inventory's parsed JSON (the gate names unreadable JSON itself). */
+export function readCandidateEndpoints(input) {
+    return parseContract(candidateEndpointsSchema, input);
+}
+/** The changed paths of a complete inventory for exactly this candidate, or null: wrong identity, a cut or
+ * miscounted list, or a path named twice. */
+export function savedInventoryPaths(text, head, base) {
+    let input;
+    try {
+        input = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const read = parseContract(savedInventorySchema, input);
+    if (!read.ok)
+        return null;
+    const inventory = read.value;
+    const paths = new Set(inventory.files.map(one => one.path));
+    if (inventory.head !== head || inventory.base !== base || inventory.filesTruncated || inventory.fileCount !== inventory.files.length || paths.size !== inventory.files.length)
+        return null;
+    return paths;
+}

package/dist/contracts/integration-metadata.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Integration metadata (mcp-connect.ts, project-tools.ts): one schema each for what a service's sign-in says about
+ * itself — its protected-resource metadata, its authorization server's metadata, its answer to registering Toolroll,
+ * and its token answers — and for a project tool's spec.
+ *
+ * A server's answers are external, so they are read field by field and never strictly: an unknown key is ignored, a
+ * field of the wrong type reads as absent, and a list keeps the items of the right type (`scopes_supported` keeps the
+ * well-formed scope tokens). What JSON Schema doesn't say — https or loopback addresses, S256, how much scope fits a
+ * sign-in address, when a token expires — is checked by mcp-connect.ts after reading, as before.
+ *
+ * A tool spec is what `validateToolSpec` makes of a tool from any source (the catalog, the console, the lead, an
+ * import, a saved `project_tool` row). Saved specs were never versioned and every one is read by that adapter, which
+ * keeps its defaults, trimming, string-secret shorthand and plain-word refusals; the spec it returns is this schema.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** RFC 6749 scope tokens. */
+export declare const SCOPE_TOKEN: RegExp;
+/** RFC 9728 protected-resource metadata: the resource a token is for, who signs in for it, and the scopes it lists. */
+export declare const protectedResourceSchema: z.ZodObject<{
+    resource: z.ZodOptional<z.ZodString>;
+    authorization_servers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** RFC 8414 (or OpenID) authorization-server metadata: where to sign in, trade a code, and register. */
+export declare const authorizationServerSchema: z.ZodObject<{
+    authorization_endpoint: z.ZodOptional<z.ZodString>;
+    token_endpoint: z.ZodOptional<z.ZodString>;
+    registration_endpoint: z.ZodOptional<z.ZodString>;
+    code_challenge_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** RFC 7591 registration answer: the client Toolroll is, and its secret when the server gives one. */
+export declare const registrationResponseSchema: z.ZodObject<{
+    client_id: z.ZodOptional<z.ZodString>;
+    client_secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** RFC 6749 §5.1/§5.2 token answer, for a code or a refresh: the tokens, how long they last, the scope granted, or the error. */
+export declare const tokenResponseSchema: z.ZodObject<{
+    access_token: z.ZodOptional<z.ZodString>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    expires_in: z.ZodOptional<z.ZodNumber>;
+    scope: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProtectedResource = z.infer<typeof protectedResourceSchema>;
+export type AuthorizationServer = z.infer<typeof authorizationServerSchema>;
+export type RegistrationResponse = z.infer<typeof registrationResponseSchema>;
+/** `scopeSaid`: the answer has a `scope` key at all. Absent, an initial grant is what was asked for and a refresh
+ * keeps the grant it had; present but not scope text, the grant is unknown. */
+export type TokenResponse = z.infer<typeof tokenResponseSchema> & {
+    scopeSaid: boolean;
+};
+export declare const readProtectedResource: (body: Record<string, unknown>) => ProtectedResource;
+export declare const readAuthorizationServer: (body: Record<string, unknown>) => AuthorizationServer;
+/** A registration answer's JSON; null when the server answered `null`, which has always read as no answer. Any other
+ * non-object (a list, a string) carries no client. */
+export declare const readRegistration: (body: unknown) => RegistrationResponse | null;
+/** A token answer's JSON; null when the server answered `null` (no answer), as for a registration. */
+export declare const readTokenResponse: (body: unknown) => TokenResponse | null;
+export declare const TOOL_NAME: RegExp;
+export declare const SECRET_NAME: RegExp;
+export declare const HEADER_NAME: RegExp;
+/** How long a tool's settings may be, and how many arguments and secrets it names. `about` is clipped to its limit
+ * when given; the one made for a tool without one names its host or program, however long. */
+export declare const TOOL_SPEC_LIMITS: {
+    readonly name: 40;
+    readonly command: 400;
+    readonly arg: 400;
+    readonly args: 40;
+    readonly url: 500;
+    readonly about: 240;
+    readonly secrets: 12;
+};
+/** One secret a tool needs: an env name for a local server, or the value behind an http header. */
+export declare const toolSecretSchema: z.ZodObject<{
+    name: z.ZodString;
+    optional: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const toolSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    transport: z.ZodEnum<{
+        http: "http";
+        stdio: "stdio";
+    }>;
+    command: z.ZodNullable<z.ZodString>;
+    args: z.ZodArray<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    secrets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        optional: z.ZodBoolean;
+    }, z.core.$strict>>;
+    bearer: z.ZodNullable<z.ZodString>;
+    headerSecrets: z.ZodRecord<z.ZodString, z.ZodString>;
+    about: z.ZodString;
+}, z.core.$strict>;
+export type ToolSecret = z.infer<typeof toolSecretSchema>;
+export type ToolSpec = z.infer<typeof toolSpecSchema>;
+/** A spec as the tool adapter made it, checked against the schema (path-named lines when it isn't one). */
+export declare const readToolSpec: (input: unknown) => ContractResult<ToolSpec>;

package/dist/contracts/integration-metadata.js

@@ -0,0 +1,101 @@
+/**
+ * Integration metadata (mcp-connect.ts, project-tools.ts): one schema each for what a service's sign-in says about
+ * itself — its protected-resource metadata, its authorization server's metadata, its answer to registering Toolroll,
+ * and its token answers — and for a project tool's spec.
+ *
+ * A server's answers are external, so they are read field by field and never strictly: an unknown key is ignored, a
+ * field of the wrong type reads as absent, and a list keeps the items of the right type (`scopes_supported` keeps the
+ * well-formed scope tokens). What JSON Schema doesn't say — https or loopback addresses, S256, how much scope fits a
+ * sign-in address, when a token expires — is checked by mcp-connect.ts after reading, as before.
+ *
+ * A tool spec is what `validateToolSpec` makes of a tool from any source (the catalog, the console, the lead, an
+ * import, a saved `project_tool` row). Saved specs were never versioned and every one is read by that adapter, which
+ * keeps its defaults, trimming, string-secret shorthand and plain-word refusals; the spec it returns is this schema.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+/** RFC 6749 scope tokens. */
+export const SCOPE_TOKEN = /^[\x21\x23-\x5b\x5d-\x7e]{1,128}$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A field's schema without its optional wrapper. */
+const inner = (field) => (field instanceof z.ZodOptional ? field.unwrap() : field);
+/**
+ * An external object read by `schema`, field by field: an absent or wrong-typed field is left out, a list keeps the
+ * items its schema takes, and keys the schema doesn't name are ignored.
+ */
+function fieldsOf(schema, input) {
+    const out = {};
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        const of = inner(field);
+        if (of instanceof z.ZodArray && Array.isArray(value))
+            out[key] = value.filter(item => of.element.safeParse(item).success);
+        else if (field.safeParse(value).success)
+            out[key] = value;
+    }
+    return out;
+}
+// ---- a service's sign-in (OAuth) -------------------------------------------------------------------------------
+/** RFC 9728 protected-resource metadata: the resource a token is for, who signs in for it, and the scopes it lists. */
+export const protectedResourceSchema = z.object({
+    resource: z.string().optional(),
+    authorization_servers: z.array(z.string()).optional(),
+    scopes_supported: z.array(z.string().regex(SCOPE_TOKEN)).optional(),
+});
+/** RFC 8414 (or OpenID) authorization-server metadata: where to sign in, trade a code, and register. */
+export const authorizationServerSchema = z.object({
+    authorization_endpoint: z.string().optional(),
+    token_endpoint: z.string().optional(),
+    registration_endpoint: z.string().optional(),
+    code_challenge_methods_supported: z.array(z.string()).optional(),
+});
+/** RFC 7591 registration answer: the client Toolroll is, and its secret when the server gives one. */
+export const registrationResponseSchema = z.object({
+    client_id: z.string().optional(),
+    client_secret: z.string().optional(),
+});
+/** RFC 6749 §5.1/§5.2 token answer, for a code or a refresh: the tokens, how long they last, the scope granted, or the error. */
+export const tokenResponseSchema = z.object({
+    access_token: z.string().optional(),
+    refresh_token: z.string().optional(),
+    expires_in: z.number().positive().optional(),
+    scope: z.string().optional(),
+    error: z.string().optional(),
+});
+export const readProtectedResource = (body) => fieldsOf(protectedResourceSchema, body);
+export const readAuthorizationServer = (body) => fieldsOf(authorizationServerSchema, body);
+/** A registration answer's JSON; null when the server answered `null`, which has always read as no answer. Any other
+ * non-object (a list, a string) carries no client. */
+export const readRegistration = (body) => body === null ? null : isRecord(body) ? fieldsOf(registrationResponseSchema, body) : {};
+/** A token answer's JSON; null when the server answered `null` (no answer), as for a registration. */
+export const readTokenResponse = (body) => body === null ? null : isRecord(body) ? { ...fieldsOf(tokenResponseSchema, body), scopeSaid: "scope" in body } : { scopeSaid: false };
+// ---- a project's tool -----------------------------------------------------------------------------------------
+export const TOOL_NAME = /^[a-z0-9][a-z0-9_-]{0,39}$/;
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+export const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
+/** How long a tool's settings may be, and how many arguments and secrets it names. `about` is clipped to its limit
+ * when given; the one made for a tool without one names its host or program, however long. */
+export const TOOL_SPEC_LIMITS = { name: 40, command: 400, arg: 400, args: 40, url: 500, about: 240, secrets: 12 };
+/** One secret a tool needs: an env name for a local server, or the value behind an http header. */
+export const toolSecretSchema = z.strictObject({ name: z.string().regex(SECRET_NAME), optional: z.boolean() });
+export const toolSpecSchema = z.strictObject({
+    name: z.string().regex(TOOL_NAME),
+    transport: z.enum(["stdio", "http"]),
+    /** stdio: the program and its arguments (no secrets in either). */
+    command: z.string().max(TOOL_SPEC_LIMITS.command).nullable(),
+    args: z.array(z.string().max(TOOL_SPEC_LIMITS.arg)).max(TOOL_SPEC_LIMITS.args),
+    /** http: the server's address. */
+    url: z.string().max(TOOL_SPEC_LIMITS.url).nullable(),
+    /** Every secret the tool needs. stdio: each is an env variable of the server process. */
+    secrets: z.array(toolSecretSchema).max(TOOL_SPEC_LIMITS.secrets),
+    /** http: the secret sent as `Authorization: Bearer <value>`. */
+    bearer: z.string().regex(SECRET_NAME).nullable(),
+    /** http: header name (HEADER_NAME, checked by the adapter: a key pattern has no exact JSON Schema) → the secret sent as its raw value. */
+    headerSecrets: z.record(z.string(), z.string().regex(SECRET_NAME)),
+    /** What it does, in plain words. */
+    about: z.string(),
+});
+/** A spec as the tool adapter made it, checked against the schema (path-named lines when it isn't one). */
+export const readToolSpec = (input) => parseContract(toolSpecSchema, input);

package/dist/contracts/model-catalog.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What the model catalog (model-catalog.ts) reads from outside Toolroll: the Codex CLI's own model list
+ * (`~/.codex/models_cache.json`) and npm's latest-version answer for each agent CLI. Both belong to someone else, so
+ * both are read loosely: unknown keys are ignored, an entry that doesn't fit is skipped, and a file or answer that
+ * doesn't fit at all reads as nothing (an empty list, no version) — never an error.
+ */
+import { z } from "zod";
+/** One listed Codex model: a usable id, shown in the picker. Its display name is used when it is text. */
+export declare const codexModelSchema: z.ZodObject<{
+    slug: z.ZodString;
+    visibility: z.ZodLiteral<"list">;
+    display_name: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** The Codex cache file: its `models` list, entries read one by one with `codexModelSchema`. */
+export declare const codexModelsCacheSchema: z.ZodObject<{
+    models: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+/** npm's `/<package>/latest` answer: a version starting with major.minor.patch. */
+export declare const npmLatestSchema: z.ZodObject<{
+    version: z.ZodString;
+}, z.core.$strip>;