toolroll 0.9.103 → 0.9.105

package/dist/contracts/integration-metadata.js

@@ -1,28 +1,8 @@
-/**
- * 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";
 import { isRecord } from "../is-record.js";
-/** RFC 6749 scope tokens. */
 export const SCOPE_TOKEN = /^[\x21\x23-\x5b\x5d-\x7e]{1,128}$/;
-/** 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)) {
@@ -37,14 +17,11 @@ function fieldsOf(schema, input) {
     }
     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, register, and revoke. */
 export const authorizationServerSchema = z.object({
     authorization_endpoint: z.string().optional(),
     token_endpoint: z.string().optional(),
@@ -52,12 +29,10 @@ export const authorizationServerSchema = z.object({
     revocation_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(),
@@ -67,36 +42,22 @@ export const tokenResponseSchema = z.object({
 });
 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/lead-context.js

@@ -1,15 +1,7 @@
-/**
- * The lead's catch-up bundle (lead-context.ts): one schema for the DATA each lead turn opens with, built fresh from the
- * local database, in order of importance. The bundle is checked before it is scrubbed and serialized; its whole size
- * (TEXT_LIMITS.leadContextBytes, in UTF-8 bytes) is met in plain code after, by dropping the least important parts.
- */
 import { z } from "zod";
 import { limited } from "./contract.js";
-/** How many tasks the bundle reads, projects it names, and open promises, corrections and proposals it shows. */
 export const LEAD_CONTEXT_COUNTS = { tasks: 8, projects: 8, promises: 10, corrections: 5, proposals: 5 };
 export const LEAD_CHANNELS = ["console", "terminal", "telegram", "slack", "discord", "teams"];
-/** A task as the lead reads it: which project (`r1`...), its ids, state, goal, outcome, checks, the next action and
- * the questions still open on it. */
 export const leadTaskSchema = z.strictObject({
     repo: z.string(),
     id: z.string(),
@@ -22,11 +14,8 @@ export const leadTaskSchema = z.strictObject({
     next: z.string().nullable(),
     decisions: z.array(z.strictObject({ id: z.int(), question: z.string() })),
 });
-/** The lead's own open promise in this conversation, and when it is due. */
 export const leadPromiseSchema = z.strictObject({ id: z.int(), what: limited("promise", "leadPromise"), when: z.string(), expires: z.string() });
-/** A correction the operator confirmed since the lead's last reply. */
 export const leadCorrectionSchema = z.strictObject({ proposal: z.int(), change: limited("correction", "leadCorrection") });
-/** A proposal still open in this conversation, which a correction may affect. */
 export const leadOpenProposalSchema = z.strictObject({ proposal: z.int(), kind: z.string(), about: limited("about", "leadProposalAbout").nullable() });
 export const LEAD_CONTEXT_VERSION = 3;
 export const leadContextSchema = z.strictObject({
@@ -34,13 +23,10 @@ export const leadContextSchema = z.strictObject({
     source: z.literal("local-database"),
     me: z.strictObject({ name: z.string(), persona: z.string() }),
     you: z.strictObject({ firstName: z.string().nullable(), timeZone: z.string(), today: z.string() }),
-    /** Lines the person confirmed about themselves. */
     aboutYou: z.array(z.string()),
-    /** The people, subagents and team chats the lead works with, one line each. */
     people: z.strictObject({ people: z.array(z.string()), subagents: z.array(z.string()), teams: z.array(z.string()) }),
     channel: z.strictObject({ id: z.enum(LEAD_CHANNELS), fit: z.string(), replyLimit: z.int().nullable() }).nullable(),
     needsYou: z.array(leadTaskSchema),
-    /** This conversation's follow-through; absent outside one. */
     commitments: z.array(leadPromiseSchema).max(LEAD_CONTEXT_COUNTS.promises).optional(),
     corrections: z.array(leadCorrectionSchema).max(LEAD_CONTEXT_COUNTS.corrections).optional(),
     openProposals: z.array(leadOpenProposalSchema).max(LEAD_CONTEXT_COUNTS.proposals).optional(),

package/dist/contracts/lead-tools.js

@@ -1,13 +1,3 @@
-/**
- * The lead's tools (docs/plans/zod-revamp.md, item 5): one input schema per tool, and one output schema for what each
- * returns when it succeeds. The input schema supplies the JSON Schema the lead is given (`toModelSchema`) and the
- * compatible reader used before any handler runs (mate-tools.ts), so a refusal names the paths it reads next step.
- * What JSON Schema can't say — a repo the operator may reach, plain text without secrets, an ISO time, a decision read
- * in an earlier step — is still checked in plain code after parsing, with its own words.
- *
- * Output schemas describe a result's top level. They are checked in tests and logged when a result disagrees; a call
- * that succeeds is never refused because of one (an output schema is a record of the contract, not a gate).
- */
 import { z } from "zod";
 import { CHAT_ACTIONS } from "../chat-actions.js";
 import { RESULT_IMAGES_PER_TURN_CAP } from "../chat-evidence.js";
@@ -30,30 +20,20 @@ const enumOf = (values) => z.enum(values);
 const text = (key) => z.string().max(TEXT_LIMITS[key]);
 const id = z.int().min(1);
 const offset = z.int().min(0);
-/** Text a model is told is "refused with its length, not cut": the refusal says how long it was. */
 function overBy(limit, input) {
     const count = (n) => n.toLocaleString("en-US");
     return `over ${count(limit)} characters (it is ${typeof input === "string" ? count(input.length) : "longer"}): shorten it and call again`;
 }
-/** A task as a tool names it: its id. */
 export const taskRef = z.string().min(1).max(TEXT_LIMITS.taskRef);
-/** A project as list_repos names it (r1, r2). */
 export const repoId = z.string().regex(/^r[0-9]{1,3}$/);
-/** A task's goal or what it leaves out: the length a model is told before it writes, and refused (not cut) beyond. */
 export const scopeText = z.string().max(TEXT_LIMITS.goal, { error: issue => overBy(TEXT_LIMITS.goal, issue.input) })
     .describe(`At most ${TEXT_LIMITS.goal.toLocaleString("en-US")} characters (UTF-16 code units) and ${TEXT_LIMITS.goalBytes.toLocaleString("en-US")} UTF-8 bytes; no control or disguised text. Longer text is refused with its length, not cut: shorten it and call again.`);
-/** The paths a task expects to touch. */
 export const touches = z.array(text("taskTouch")).max(50);
-/** The rubric a task is accepted against: the plan's own criterion schema; duplicate ids and byte limits are checked after. */
 export const acceptance = z.array(acceptanceCriterionSchema).min(1).max(ACCEPTANCE_LIMITS.criteria);
-/** A note the operator's own words fill (revise feedback, steering, a flow card's note). */
 const note = z.string().max(LIMITS.note, { error: issue => overBy(LIMITS.note, issue.input) }).describe(`At most ${LIMITS.note} characters; longer is refused with its length, not cut.`);
 export const CODE_MAP_VIEWS = ["overview", "area", "file", "search"];
-/** Task states a list filters by. */
 export const LISTED_TASK_STATES = ["queued", "running", "done", "failed", "cancelled"];
-/** The shared actions the lead proposes with propose_action; flows and subagents have their own tools. */
 const ACTION_OPERATIONS = Object.keys(CHAT_ACTIONS).filter(one => !one.startsWith("flow_") && !one.startsWith("subagent_") && one !== "task_start");
-/** A card's spec as the lead sees it: one flat props object. Each element's own props are read strictly by card-catalog.ts. */
 const cardProps = z.strictObject({
     source: z.enum(CARD_SOURCES).optional(), chart: z.enum(CARD_CHART_TYPES).optional(), columns: z.array(z.string().max(40)).max(CARD_LIMITS.columns).optional(), facts: z.array(z.string().max(40)).max(CARD_LIMITS.facts).optional(),
     repo: repoId.optional(), state: z.enum(CARD_TASK_STATES).optional(), limit: z.int().min(1).max(CARD_LIMITS.rows).optional(), flow: id.optional(), days: z.int().min(1).max(90).optional(),
@@ -90,7 +70,6 @@ export const LEAD_TOOL_INPUTS = {
     get_result_images: z.strictObject({ task: taskRef, run: id.optional(), offset: offset.optional(), images: z.array(id).min(1).max(RESULT_IMAGES_PER_TURN_CAP).optional() }),
     propose_review: z.strictObject({
         run: id, operation: z.enum(["note", "revise"]),
-        // A note, path or line left as null reads as left out, as it always has.
         note: z.string().max(LIMITS.note).nullable().optional(), path: text("diffPath").nullable().optional(),
         line: z.int().min(1).max(1_000_000).nullable().optional(),
         saved_notes: z.array(id).max(100).optional(),
@@ -101,7 +80,6 @@ export const LEAD_TOOL_INPUTS = {
     find_tools: z.strictObject({ query: z.string().min(1).max(200).describe("What you want to do, in a few words (\"make a flow\", \"add a subagent\", \"hold a task\").") }),
     get_project_tools: z.strictObject({ repo: repoId }),
     get_flows: z.strictObject({ repo: repoId.optional(), flow: id.optional(), card: id.optional() }),
-    // The flow contract's own schema (src/contracts/flow-propose.ts), never a second one here.
     propose_flow: proposeFlowInputSchema,
     get_subagents: z.strictObject({ repo: repoId.optional(), subagent: id.optional() }),
     propose_subagent: z.strictObject({
@@ -143,13 +121,10 @@ export const LEAD_TOOL_INPUTS = {
     queue: z.strictObject({ repo: repoId }),
     propose_task: z.strictObject({
         repo: repoId, title: text("taskTitle"), goal: scopeText,
-        // Exclusions left as null read as none, as they always have.
         not: scopeText.nullable().optional(), touches: touches.optional(), acceptance,
         planning: z.enum(["auto", "required", "skip"]).optional(), report: z.boolean().optional(), checks: text("checksWords").optional(),
     }),
-    // One-step start from chat (docs/plans/one-step-chat.md C3): one small change the person asked to be done now.
     propose_start: z.strictObject({ repo: repoId, title: text("taskTitle") }),
-    // Lead fan-out (docs/plans/lead-fan-out.md): 2 to 20 independent items under one shared brief and one success test.
     propose_sweep: z.strictObject({
         repo: repoId, title: text("taskTitle"), brief: scopeText,
         items: z.array(z.strictObject({ title: text("taskTitle"), item: scopeText })).min(2).max(20),
@@ -161,9 +136,6 @@ export const LEAD_TOOL_INPUTS = {
     propose_reserve: z.strictObject({ task: taskRef, worker: text("workerName").nullable() }),
     propose_hold: z.strictObject({ task: taskRef, reason: text("proposalReason") }),
     propose_unhold: z.strictObject({ task: taskRef }),
-    // mode: a note (the default), Pause (stop a running Claude build's turn, keep the build), Pause and steer, or Resume
-    // (a paused build goes on where it stopped, without a note).
-    // question: a running agent's open question (Agents board); the note is its reply, sent as an ordinary note.
     propose_steer: z.strictObject({ task: taskRef, note: note.optional(), mode: z.enum(["note", "pause", "pause-and-steer", "resume"]).optional(),
         question: z.number().int().positive().optional().describe("A running agent's open question (get_task agentQuestions): the note becomes its reply and closes it.") }),
     propose_dependency_repair: z.strictObject({ task: taskRef, blocker: taskRef, operation: z.enum(["retry", "unlink", "replace"]), replacement: taskRef.optional() }),
@@ -178,45 +150,28 @@ export const LEAD_TOOL_INPUTS = {
     propose_answer: z.strictObject({ decision: id, option: text("answerOption").min(1), rationale: text("answerRationale") }),
     propose_cancel: z.strictObject({ task: taskRef, reason: text("proposalReason") }),
 };
-/**
- * Read the same calls the 0.9.36 handlers accepted. Derive readers from the advertised contracts, leaving these
- * optional values to their existing clamp/fallback code. Unknown top-level keys are stripped by the tool registry,
- * except for flow proposals, whose strict contract predates item 5. The gateway also keeps its strict schemas.
- */
 export const LEAD_TOOL_READ_INPUTS = {
     ...LEAD_TOOL_INPUTS,
     list_tasks: LEAD_TOOL_INPUTS.list_tasks.extend({ limit: z.unknown().optional() }),
     get_task_conversation: LEAD_TOOL_INPUTS.get_task_conversation.extend({ limit: z.unknown().optional() }),
-    // 0.9.36 read a null repo as every project.
     get_flow_insights: LEAD_TOOL_INPUTS.get_flow_insights.extend({ repo: repoId.nullable().optional(), days: z.unknown().optional() }),
     get_person: LEAD_TOOL_INPUTS.get_person.extend({ id: z.unknown().optional(), name: z.unknown().optional() }),
     propose_agents: LEAD_TOOL_INPUTS.propose_agents.extend({ agent: LEAD_TOOL_INPUTS.propose_agents.shape.agent.unwrap().strip().optional() }),
 };
-/** How a tool's call names a key it doesn't know: propose_flow suggests the flow vocabulary's own words. */
 export const LEAD_TOOL_OPTIONS = { propose_flow: FLOW_ALIASES };
-// ------------------------------------------------------------- outputs
 const str = z.string();
 const int = z.number().int();
 const list = z.array(z.unknown());
 const nullable = (schema) => schema.nullable();
 const rows = (shape) => z.array(z.looseObject(shape));
-/** A proposal drafted as a card the operator confirms (propose_action, propose_flow, propose_subagent). */
 const cardDrafted = z.looseObject({ proposal: int, label: str, awaiting: str, executed: z.literal(false) });
-/** A proposal row drafted by one of the queue, hold, scope and answer tools. */
 const proposed = (kind, shape = {}) => z.looseObject({ proposal: int, kind: z.literal(kind), awaiting: str, ...shape });
-/** One bounded answer from the shared code map reader (code-map-read.ts `MapAnswer`). */
 export const codeMapOutput = z.looseObject({ v: z.literal(1), ok: z.boolean() });
-/** A repository-context read (repository-context.ts `RepositoryContext`). */
 export const repositoryContextOutput = z.looseObject({ version: z.literal(1), readOnly: z.boolean(), query: str, mode: z.enum(["search", "impact"]), asOf: str, excerpts: list });
-/** The local catch-up (assignment-brief.ts `AssignmentCatchUp`). */
 export const catchUpOutput = z.looseObject({ version: z.literal(1), asOf: str, readOnly: z.literal(true), assignments: list, projects: list, omissions: z.looseObject({}) });
-/** How things stand per repository (mate-tools.ts `recapOver`), its repos labelled. */
 export const recapOutput = z.looseObject({ since: nullable(str), repos: list, waitsOnYou: z.looseObject({ decisions: list, incidents: int, scopesAwaitingApproval: list }), running: list, truncated: z.boolean() });
-/** Open decisions (`decisionsOver`). */
 export const decisionsOutput = z.looseObject({ decisions: rows({ decision: int, task: str, question: str, options: list, ageHours: z.number() }), truncated: z.boolean() });
-/** One decision in full (`decisionOver`), without the builder's recommendation. */
 export const decisionOutput = z.looseObject({ repo: str, decision: int, task: str, state: str, question: str, options: rows({ id: str, label: str, reversible: z.boolean(), consequence: str }), ageHours: z.number() });
-/** One repository's queue by column (`queueOver`). */
 export const queueColumnsOutput = { columns: rows({ column: str, tasks: list }) };
 export const LEAD_TOOL_OUTPUTS = {
     get_brief: catchUpOutput,
@@ -303,10 +258,6 @@ export const LEAD_TOOL_OUTPUTS = {
     propose_answer: proposed("answer", { decision: int, option: str }),
     propose_cancel: proposed("cancel", { task: str }),
 };
-/**
- * Report a result that disagrees with its output schema without hiding the actual result, including under Vitest.
- * Contract tests assert output shapes directly; executing a tool always writes the diagnostic and returns its result.
- */
 export function reportToolOutput(surface, tool, schema, body) {
     const read = parseContract(schema, body);
     if (read.ok)

package/dist/contracts/mcp-oauth.js

@@ -1,14 +1,5 @@
-/**
- * MCP sign-in (mcp-oauth.ts): what an MCP client may send when it registers itself (RFC 7591) and when it trades a
- * code or a refresh secret for tokens (RFC 6749 §4.1.3, §6, with PKCE, RFC 7636).
- *
- * A registration is read strictly for the fields Toolroll uses and ignores the rest (RFC 7591 §2: unknown metadata
- * is ignored). Only public clients register: no secret is issued, so `token_endpoint_auth_method` is `none` when
- * given. Whether a redirect is https, or http on 127.0.0.1 / [::1], is checked by mcp-oauth.ts after reading.
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
-/** The most redirects one client registers, and how long each and the client's name may be. */
 export const OAUTH_LIMITS = { redirects: 5, redirect: 512, name: 100 };
 export const OAUTH_GRANTS = ["authorization_code", "refresh_token"];
 export const oauthRegistrationSchema = z.object({
@@ -18,17 +9,14 @@ export const oauthRegistrationSchema = z.object({
     grant_types: z.array(z.enum(OAUTH_GRANTS)).min(1).max(2).optional(),
     response_types: z.array(z.literal("code")).min(1).max(1).optional(),
 });
-/** A PKCE verifier (RFC 7636 §4.1) and a S256 challenge (43 base64url characters). */
 export const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/;
 export const PKCE_CHALLENGE = /^[A-Za-z0-9_-]{43}$/;
 const bounded = z.string().min(1).max(2048);
-/** A token request, by grant type. Every value is one form field. */
 export const oauthTokenRequestSchema = z.discriminatedUnion("grant_type", [
     z.object({ grant_type: z.literal("authorization_code"), code: bounded, redirect_uri: bounded, client_id: bounded, code_verifier: z.string().regex(PKCE_VERIFIER), resource: bounded.optional() }),
     z.object({ grant_type: z.literal("refresh_token"), refresh_token: bounded, client_id: bounded, resource: bounded.optional(), scope: bounded.optional() }),
 ]);
 export const readOAuthRegistration = (input) => parseContract(oauthRegistrationSchema, input);
-/** A token request's form: a field given twice is refused (RFC 6749 §3.2); fields this grant doesn't take are ignored. */
 export function readOAuthTokenRequest(form) {
     const fields = {};
     for (const [key, value] of form) {

package/dist/contracts/memory-pass.js

@@ -1,9 +1,3 @@
-/**
- * The memory pass (memory-pass.ts): one schema for the verdict a model returns on one session — the analyser's
- * `--json-schema` (Codex's output schema), with a tolerant read side for older answers — the verdict each session keeps
- * (`memory_session.verdict`), and a proposal with its evidence (`memory_proposal`). What JSON Schema cannot state —
- * a quote really in the trace, an instruction id on the surface audited — is checked in plain code after parsing.
- */
 import { z } from "zod";
 import { TEXT_LIMITS } from "../text-limits.js";
 import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
@@ -28,21 +22,14 @@ const verdictShape = (text) => {
         })),
     };
 };
-/** The verdict a model returns on one session. */
 export const memoryVerdictSchema = z.strictObject(verdictShape(bounded));
-/** What the analyser is told to return: `--json-schema` for Claude, the output schema for Codex, and the prompt for
- * every other provider. */
 export const MEMORY_VERDICT_MODEL_SCHEMA = toModelSchema(memoryVerdictSchema);
-/** Parse-side compatibility with the pre-Zod analyser: clip with the same trailing ellipsis, coerce effects and
- * instruction ids, default gap metadata, ignore unknown keys and discard bad claims individually. These transforms
- * never enter the strict model schema. */
 const clipped = (key) => z.string().transform(text => text.length > TEXT_LIMITS[key] ? `${text.slice(0, TEXT_LIMITS[key])}…` : text);
 const readShape = verdictShape(saved);
 const effectFields = {
     instruction: z.coerce.string(),
     effect: z.preprocess(value => String(value ?? ""), clipped("memoryEffect")),
 };
-/** Keep the quote even when a claim is bad: the old reader applied its twenty-quote cap before dropping bad claims. */
 function readClaims(schema) {
     return z.array(z.looseObject({ quote: z.string() }).transform(input => {
         const parsed = schema.safeParse(input);
@@ -63,12 +50,7 @@ export const memoryVerdictReadSchema = memoryVerdictSchema.strip().extend({
     })),
 });
 export const MEMORY_VERDICT_VERSION = 1;
-/** A verdict as a session keeps it. */
 export const savedVerdictSchema = versioned(MEMORY_VERDICT_VERSION, verdictShape(saved));
-/**
- * A verdict kept before it carried `version` (through 0.9.36), as version 1. Those left a gap's `matchesGap` out when
- * there was none; that reads as null. Values are never rewritten.
- */
 export function upgradeVerdictV0(body) {
     const gaps = body["gaps"];
     return {
@@ -78,13 +60,10 @@ export function upgradeVerdictV0(body) {
     };
 }
 export const MEMORY_VERDICT_UPGRADES = { 0: upgradeVerdictV0 };
-/** Read a kept verdict: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
 export function readSavedVerdict(input) {
     return readVersioned(savedVerdictSchema, input, MEMORY_VERDICT_UPGRADES);
 }
-/** One corroborating sighting: the session and its verbatim quote. A proposal keeps at most six. */
 export const memoryEvidenceSchema = z.array(z.strictObject({ session: z.string(), quote: z.string() })).max(6);
-/** A proposal as its row reads; its evidence is a JSON list (an older runtime reads it as one, so it has no envelope). */
 export const memoryProposalSchema = z.strictObject({
     id: z.int(),
     repo: z.string(),

package/dist/contracts/model-catalog.js

@@ -1,14 +1,5 @@
-/**
- * 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";
 import { modelIdSchema } from "./provider.js";
-/** One listed Codex model: a usable id, shown in the picker. Its display name is used when it is text. */
 export const codexModelSchema = z.object({ slug: modelIdSchema, visibility: z.literal("list"), display_name: z.unknown().optional() });
-/** The Codex cache file: its `models` list, entries read one by one with `codexModelSchema`. */
 export const codexModelsCacheSchema = z.object({ models: z.array(z.unknown()) });
-/** npm's `/<package>/latest` answer: a version starting with major.minor.patch. */
 export const npmLatestSchema = z.object({ version: z.string().regex(/^\d+\.\d+\.\d+/) });

package/dist/contracts/observation-request.js

@@ -1,13 +1,3 @@
-/**
- * A focused observation request (observations.ts `parseObservationCases`): the file a builder writes to ask for one to
- * four focused test runs, each naming a criterion, base or head, one test file and one test name.
- *
- * Toolroll defines this request, so it is strict: an unknown key, at the top or in an observation, is refused, as it
- * always was. It must say `version: 1`, as it always had to: a request without `version`, or with any other version, is
- * refused. What JSON Schema can't say —
- * a criterion the brief asked about, a normalized test path, a usable test name, one distinct observation per
- * criterion — is checked after parsing.
- */
 import { z } from "zod";
 import { readVersioned, versioned } from "./contract.js";
 export const observationCaseSchema = z.strictObject({
@@ -19,7 +9,6 @@ export const observationCaseSchema = z.strictObject({
 export const observationRequestSchema = versioned(1, {
     observations: z.array(observationCaseSchema).min(1).max(4),
 });
-/** A parsed request (JSON already read). Only version 1 is read; there is no earlier version to upgrade. */
 export function readObservationRequest(input) {
     return readVersioned(observationRequestSchema, input);
 }

package/dist/contracts/plan.js

@@ -1,16 +1,8 @@
-/**
- * The planner's handoff: one schema for the file a planner writes, the JSON Schema it is given (`--json-schema`) and
- * the parser that reads it back (`parsePlan` in plan.ts). The rules JSON Schema cannot state — the plan document's
- * sections, UTF-8 byte limits, control characters, duplicate criterion ids, the Proof naming every criterion and the
- * silent-amendment contract check — run in plain code after parsing, each with a named error.
- */
 import { z } from "zod";
 import { ACCEPTANCE_LIMITS, EVIDENCE_KINDS } from "../scope.js";
 import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
 import { isRecord } from "../is-record.js";
-/** How many paths a plan may say it touches. */
 export const PLAN_TOUCHES = 32;
-/** One acceptance criterion: the scope's own shape (scope.ts `AcceptanceCriterion`), `how` advisory and unsigned. */
 export const acceptanceCriterionSchema = z.strictObject({
     id: limited("acceptance id", "acceptanceIdBytes").min(1),
     statement: limited("acceptance statement", "acceptanceStatementBytes").min(1),
@@ -26,7 +18,6 @@ export const planSchema = versioned(PLAN_VERSION, {
     plan: limited("plan", "planDocumentBytes").min(1),
     amendment: limited("amendment", "planAmendment").nullable().optional(),
 });
-/** What the planner's `--json-schema` is: the plan schema, exactly. */
 export const PLAN_MODEL_SCHEMA = toModelSchema(planSchema);
 const PLAN_FIELDS = ["goal", "outOfScope", "touches", "acceptance", "plan", "amendment"];
 const CRITERION_FIELDS = ["id", "statement", "how", "evidence"];
@@ -38,11 +29,6 @@ function pick(body, fields) {
     }
     return out;
 }
-/**
- * A plan written before plans carried `version` (every plan through 0.9.33), as version 1. The old parser read only
- * the fields it knew and ignored any others, read a null goal, plan or acceptance as missing and null touches as
- * none; this keeps exactly that, so every plan that parsed then parses now. Values themselves are never rewritten.
- */
 export function upgradeUnversionedPlan(body) {
     const out = { version: PLAN_VERSION, ...pick(body, PLAN_FIELDS) };
     for (const field of ["goal", "plan", "touches", "acceptance"]) {
@@ -55,13 +41,11 @@ export function upgradeUnversionedPlan(body) {
     return out;
 }
 export const PLAN_UPGRADES = { 0: upgradeUnversionedPlan };
-/** The payload as version 1, upgraded when it was saved unversioned; null for anything that is not an object. */
 export function planPayloadBody(input) {
     if (!isRecord(input))
         return null;
     return Object.prototype.hasOwnProperty.call(input, "version") ? input : upgradeUnversionedPlan(input);
 }
-/** Read a plan payload: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
 export function readPlanPayload(input) {
     return readVersioned(planSchema, input, PLAN_UPGRADES);
 }

package/dist/contracts/project-knowledge.js

@@ -1,15 +1,7 @@
-/**
- * Project knowledge (project-knowledge.ts): one schema for the saved knowledge (instructions and references, every
- * revision in `knowledge_change` and the current one in `project_knowledge`), and for the selection a run is given and
- * keeps (`knowledge_snapshot`). The rules JSON Schema cannot state — UTF-8 byte limits, control characters, secrets,
- * the selection's total size — run in plain code when knowledge is written. A saved payload's digest is checked
- * against its stored bytes before it is parsed, and it is upgraded only in memory: stored bytes are never rewritten.
- */
 import { z } from "zod";
 import { limited, readVersioned, versioned } from "./contract.js";
 import { decisionLineSchema } from "./project-memory.js";
 import { isRecord } from "../is-record.js";
-/** How many references a project keeps, and how many a run is given. Text limits live in TEXT_LIMITS. */
 export const KNOWLEDGE_COUNTS = { references: 12, selected: 3, decisions: 8 };
 const written = limited;
 const saved = () => z.string();
@@ -17,7 +9,6 @@ const referenceShape = (text) => ({
     id: z.string(),
     title: text("reference title", "knowledgeTitleBytes"),
     content: text("reference text", "knowledgeReferenceBytes"),
-    /** A committed .md or .txt file the text was read from, at `sourceRevision` with blob `sourceSha`; null for a note. */
     path: text("reference path", "knowledgePathBytes").nullable(),
     sourceSha: z.string().nullable(),
     sourceRevision: z.string().nullable(),
@@ -27,9 +18,7 @@ const knowledgeShape = (text) => ({
     references: z.array(z.strictObject(referenceShape(text))).max(KNOWLEDGE_COUNTS.references),
 });
 export const KNOWLEDGE_VERSION = 1;
-/** Knowledge as it is written. */
 export const knowledgeSchema = versioned(KNOWLEDGE_VERSION, knowledgeShape(written));
-/** Knowledge as it is read back. */
 export const savedKnowledgeSchema = versioned(KNOWLEDGE_VERSION, knowledgeShape(saved));
 function pick(body, fields) {
     const out = {};
@@ -39,10 +28,6 @@ function pick(body, fields) {
     return out;
 }
 const REFERENCE_FIELDS = Object.keys(referenceShape(saved));
-/**
- * Knowledge saved before it carried `version` (through 0.9.36: `{instructions, references}`), as version 1. Its
- * readers took the fields they knew, so this keeps exactly those; values are never rewritten.
- */
 export function upgradeKnowledgeV0(body) {
     const references = body["references"];
     return {
@@ -52,7 +37,6 @@ export function upgradeKnowledgeV0(body) {
     };
 }
 export const KNOWLEDGE_UPGRADES = { 0: upgradeKnowledgeV0 };
-/** Read saved knowledge: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
 export function readKnowledge(input) {
     const read = readVersioned(savedKnowledgeSchema, input, KNOWLEDGE_UPGRADES);
     if (!read.ok)
@@ -60,7 +44,6 @@ export function readKnowledge(input) {
     const { version: _version, ...knowledge } = read.value;
     return { ok: true, value: knowledge };
 }
-/** What a person drafts on the Knowledge page or the CLI; each action reads the fields it needs. */
 export const knowledgeDraftSchema = z.strictObject({
     instructions: z.string().optional(),
     title: z.string().optional(),
@@ -68,29 +51,20 @@ export const knowledgeDraftSchema = z.strictObject({
     path: z.string().optional(),
     id: z.string().optional(),
 });
-/** A source a run was not given, and why. */
 export const knowledgeOmissionSchema = z.strictObject({ title: z.string(), reason: z.string() });
 const selectionShape = (text) => ({
     revision: z.int().min(0),
     instructions: text("instructions", "knowledgeInstructionsBytes"),
     references: z.array(z.strictObject(referenceShape(text))).max(KNOWLEDGE_COUNTS.references),
     omitted: z.array(knowledgeOmissionSchema),
-    /** The run whose selection a reviewer inherited; null for a selection of its own. */
     inheritedFrom: z.int().nullable(),
-    /** Settled decisions, one line each; absent when there are none. */
     decisions: z.array(decisionLineSchema).max(KNOWLEDGE_COUNTS.decisions).optional(),
-    /** Source excerpts from the crew's checkout (repository-context.ts owns their shape); absent when not captured. */
     repository: z.looseObject({}).optional(),
 });
-/** Version 2 (docs/plans/learning-loops.md, "Versioned snapshots"): a selection says when it was frozen, and its decision
- * lines their revision. Version 1 stays readable exactly as it was frozen, its fields as they are. */
 export const KNOWLEDGE_SELECTION_VERSION = 2;
-/** The selection a run is given, as it is frozen. The keys are in the order a selection has always been written. */
 export const knowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, { ...selectionShape(written), capturedAt: z.string() });
-/** A frozen selection as it is read back: the version it was frozen under. */
 export const savedKnowledgeSelectionSchema = versioned(KNOWLEDGE_SELECTION_VERSION, { ...selectionShape(saved), capturedAt: z.string() });
 export const savedKnowledgeSelectionV1Schema = versioned(1, selectionShape(saved));
-/** Read a frozen selection: version 1 and 2 each as themselves, a newer one refused plainly. */
 export function readKnowledgeSelection(input) {
     const version = input !== null && typeof input === "object" ? input.version : undefined;
     if (version === 1)

package/dist/contracts/project-memory.js

@@ -1,9 +1,3 @@
-/**
- * Project memory's decisions (project-memory.ts): one schema for a decision as its row reads, the record its history
- * keeps, the change a person or the lead drafts, and the one line a brief carries. The rules JSON Schema cannot state —
- * UTF-8 byte limits, blank text, control characters and secrets — run in plain code (`clean`) when a decision is
- * written; a row is read as it was written, and its digest is checked against the row before anything trusts it.
- */
 import { z } from "zod";
 import { limited, versioned } from "./contract.js";
 export const DECISION_STATUSES = ["active", "superseded", "retired"];
@@ -17,18 +11,14 @@ const recordShape = (text) => ({
     why: text("reason", "decisionWhyBytes"),
     status: z.enum(DECISION_STATUSES),
     supersedes: z.int().nullable(),
-    // An omitted draft author defaults to the account name, which has never had the explicit author's byte limit.
     decidedBy: z.string(),
     decidedAt: z.string(),
     sourceKind: z.enum(DECISION_SOURCES),
     sourceRef: text("source", "decisionSourceBytes").nullable(),
     recordedBy: z.string(),
 });
-/** A decision as it is recorded, in the order its digest lists the fields. */
 export const decisionRecordSchema = z.strictObject(recordShape(written));
-/** A decision as its row reads. */
 export const decisionSchema = z.strictObject({ id: z.int(), ...recordShape(saved) });
-/** What a person or the lead asks to record; only the choice and its reason are required. */
 export const decisionDraftSchema = z.strictObject({
     claim: z.string(),
     why: z.string(),
@@ -38,14 +28,8 @@ export const decisionDraftSchema = z.strictObject({
     sourceRef: z.string().nullable().optional(),
     supersedes: z.int().nullable().optional(),
 });
-/** One decision in a brief: its id, the choice and when (the revision on snapshots from version 2 on); the why loads on
- * demand by id. */
 export const decisionLineSchema = z.strictObject({ id: z.int(), claim: z.string(), decidedAt: z.string(), revision: z.int().min(1).optional() });
 export const DECISION_CHANGE_VERSION = 1;
-/**
- * One entry of a decision's history (`decision_change.payload`): the record when it was made, or the reason its status
- * changed. Entries written before this carried `version` are the same shapes without it; nothing reads them back.
- */
 export const decisionChangeSchema = z.union([
     versioned(DECISION_CHANGE_VERSION, recordShape(written)),
     versioned(DECISION_CHANGE_VERSION, { reason: limited("reason", "decisionRetireBytes") }),