toolroll 0.9.104 → 0.9.105

package/dist/contracts/verification-receipt.js

@@ -1,16 +1,3 @@
-/**
- * The machine verification receipt (`verification-receipt.json`): one schema for what `sealVerificationReceipt`
- * writes and what `verificationEvidence` reads back. Only the machine writes it, from typed values, so every receipt
- * ever sealed already has exactly this shape; the bindings that need the store — the run, its candidate, the approved
- * command, the retained log and a reused gate's source — are checked in plain code after parsing.
- *
- * Version 1 is a gate executed in its own run. Version 2 added `reusedFrom` and `executedHere: false` for a gate
- * reused by an unchanged observation follow-up. Version 3 (docs/plans/release-once.md) is a release check: it keeps
- * the raw exit (`result`) apart from `coverage` — `full`, `composed` (a targeted run composed with the full check A),
- * `partial` (never passes) or `identity-removed` (a required test went away; asks again) — names the sealed check
- * artifacts, and for a composed check every link its reader proves again. A direct receipt is still sealed as version 1,
- * so its bytes (and the digests bound to them) read the same in every Toolroll that reads receipts.
- */
 import { z } from "zod";
 import { readVersioned, versioned } from "./contract.js";
 export const VERIFICATION_FAILURES = [
@@ -28,29 +15,17 @@ export const VERIFICATION_FAILURES = [
     "retry-spawn-failed",
     "retry-timed-out",
     "custody-lost",
-    // A release check that didn't cover what it owed, or lost a required test (release-once.md): never a pass.
     "coverage-incomplete",
-    // A Full release check with no complete, valid result (check-report.ts fullCheckProblem): an error, never a pass.
     "no-result",
-    // Toolroll's own shutdown stopped the check (its hard stop): it never finished.
     "stopped-by-toolroll",
-    // A Full check whose recorded last release couldn't be verified: what it owed is unknown, so it never ran.
     "baseline-unverifiable",
 ];
-/**
- * What the repository's approved verification command did: not configured; configured but the run could not attempt
- * it (`attemptFailed`, which downgrades to `short` rather than `refuted`: "we could not check" is not "the claim is
- * false"); or ran, with its exit code.
- */
 export const verifyCommandFactsSchema = z.union([
     z.strictObject({ configured: z.literal(false) }),
     z.strictObject({ configured: z.literal(true), ran: z.literal(false), attemptFailed: z.literal(true), failure: z.enum(VERIFICATION_FAILURES).optional() }),
     z.strictObject({ configured: z.literal(true), ran: z.literal(true), exitCode: z.int().min(0).max(255), setupReplayed: z.literal(true).optional(),
-        // The first attempt of a check rerun after the approved setup, classified on its own (eval-harness review 2,
-        // finding 5): only a launch failure — its program missing — is ever replayed.
         firstAttempt: z.strictObject({ class: z.literal("launch"), program: z.string().min(1).max(200), exitCode: z.int().min(0).max(255) }).optional() }),
 ]);
-/** The approved verification grant the gate ran, exactly as the store held it. */
 export const receiptCommandSchema = z.strictObject({
     id: z.int(),
     repo: z.string(),
@@ -63,7 +38,6 @@ export const receiptCommandSchema = z.strictObject({
     revokedAt: z.string().nullable(),
     revokedBy: z.string().nullable(),
 });
-/** The retained check log the receipt binds, by artifact id and content. */
 export const receiptLogSchema = z.strictObject({
     artifactId: z.int(),
     sha256: z.string(),
@@ -81,7 +55,6 @@ const receiptFields = {
     base: z.string().nullable(),
     scopeDigest: z.string().nullable(),
 };
-/** The receipt as read: a reused gate names its source run and digest; a direct one names neither. */
 export const verificationReceiptSchema = versioned(RECEIPT_VERSION, {
     ...receiptFields,
     reusedFrom: z.strictObject({ run: z.int(), digest: z.string() }).optional(),
@@ -89,28 +62,19 @@ export const verificationReceiptSchema = versioned(RECEIPT_VERSION, {
     command: receiptCommandSchema,
     result: verifyCommandFactsSchema,
     log: receiptLogSchema,
-    /** Version 3: what the check covered, apart from its exit. */
     coverage: z.enum(RECEIPT_COVERAGES).optional(),
-    /** Version 3: the attempt sealed before the check ran, and its sealed report (null: it gave none). */
     check: z.strictObject({ attempt: z.enum(["full", "targeted"]), report: z.string().nullable(), inventory: z.string().nullable(),
-        /** The command's own exit, kept here when `result` reads a failed attempt because the coverage fell short. */
         exitCode: z.int().min(0).max(255).nullable().optional(),
-        /** What passed only on a retry inside the check (check-failure.ts retriedInside), sealed here from its report: null
-         * when it gave no valid report, so nobody can tell (unknown, never "no retries"). Absent on older receipts. */
         retried: z.array(z.string().min(1).max(800)).max(6000).nullable().optional() }).optional(),
-    /** Version 3, composed: the full check A and every link the reader proves again. */
     composed: z.strictObject({
         base: z.int().min(1), baseReceipt: z.string(), baseReport: z.string(), authority: z.int().min(1), carries: z.array(z.int()),
         artifacts: z.string(), plan: z.string(), snapshot: z.string(), report: z.string(),
     }).optional(),
 });
-/** A version 1 or 2 receipt read as version 3: the same fields. Reuse is a version 2 field and coverage a version 3
- * one; a receipt naming a field newer than it was sealed as is refused by its reader, which still knows the version. */
 export function upgradeDirectReceipt(body) {
     return { ...body, version: RECEIPT_VERSION };
 }
 export const RECEIPT_UPGRADES = { 1: upgradeDirectReceipt, 2: upgradeDirectReceipt };
-/** Read a receipt: version 3 as itself, 1 and 2 upgraded, a newer one refused plainly. */
 export function readVerificationReceipt(input) {
     return readVersioned(verificationReceiptSchema, input, RECEIPT_UPGRADES);
 }

package/dist/contracts/verification-view.js

@@ -1,12 +1,3 @@
-/**
- * The gate view `verificationEvidence` returns as `bytes`: a sealed receipt exactly as sealed (either version), or,
- * for a run from before receipts, the view of its legacy machine log header. Reused gates, failed-check repair and
- * saved assessments read a view back through `readVerificationView`.
- *
- * A legacy view is built by Toolroll from the run's single-attempt log header (the "check log metadata"), its
- * approved command and its candidate inventory; it is never saved, so its schema is strict. A sealed receipt is read
- * by the receipt's own contract.
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
 import { readVerificationReceipt, receiptCommandSchema, receiptLogSchema, verifyCommandFactsSchema } from "./verification-receipt.js";
@@ -17,18 +8,12 @@ export const legacyGateViewSchema = z.strictObject({
     run: z.int(),
     head: z.string(),
     base: z.string().nullable(),
-    /** Left out of the bytes when the run never recorded one. */
     scopeDigest: z.string().nullable().optional(),
     command: receiptCommandSchema,
     result: verifyCommandFactsSchema,
     log: receiptLogSchema,
-    /** The diff-stat artifact whose endpoints bound the candidate. */
     candidate: receiptLogSchema,
 });
-/**
- * Read a view's bytes. The value is the object as written, once its shape is checked: its key order is part of what a
- * reused gate compares and seals again.
- */
 export function readVerificationView(bytes) {
     let input;
     try {

package/dist/contracts/youiyoux-request.js

@@ -1,31 +1,16 @@
-/**
- * A youiyoux request as Toolroll reads it (youiyoux-intake.ts): the published `youi.request/v1` schema (youiyoux's
- * schema/youi.request.schema.json), held to its own limits, and the `youi.proposal/v1` options file an options request's
- * agent writes (schema/youi.proposal.schema.json). Unknown keys are allowed, as the published schemas allow them;
- * everything Toolroll reads is checked here, and every string is outside text all the same.
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
 export const REQUEST_ID = /^r-[0-9a-f]{10}$/;
-/** An options file's id: `p-` and the same 10 hex as the options request it answers. */
 export const PROPOSAL_ID = /^p-[0-9a-f]{10}$/;
-/** The provenance every task filed from a request carries (task_ref.filed_via): immutable, and the seal reads it. */
 export const YOUIYOUX_FILED_VIA = "youiyoux";
-/** The one chat card a pass's filings make for a project (youiyoux-intake.ts), drawn by chat-decide.ts: the new tasks,
- * Approve all and each one's own Approve and Open. */
 export const YOUIYOUX_CARD_KIND = "youiyoux-requests";
-/** Where a person sees and approves everything waiting on them in the console (flow-triggers.ts NEEDS_YOU_HREF). */
 export const YOUIYOUX_HOME_PATH = "/tasks?view=needs-you";
 const text = (max) => z.string().min(1).max(max);
 const who = z.object({ kind: z.enum(["person", "agent"]), name: text(100) });
-// The published schema's date-time: an ISO timestamp with a zone.
 const when = z.string().max(40).regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/);
 export const YOUIYOUX_EVIDENCE = ["screenshot", "check", "changed-path", "manual-review"];
-/** A component prop as youiyoux names one: what an option may set. */
 const PROP = /^[A-Za-z_$][\w$]{0,63}$/;
 const value = z.union([z.string().max(2000), z.number().finite(), z.boolean()]);
-/** What an options request offers its agent: the one file to write (`.youi/proposals/<proposal>.json`), the props an
- * option may set (enum values from `values`), and whether it may give the component new text. */
 export const youiyouxOfferSchema = z.object({
     proposal: z.string().regex(PROPOSAL_ID),
     file: text(500),
@@ -44,7 +29,6 @@ export const youiyouxTaskSchema = z.object({
     why: text(500).optional(),
     not: z.array(text(300)).max(10),
     acceptance: z.array(z.object({ statement: text(300), evidence: z.array(z.enum(YOUIYOUX_EVIDENCE)).min(1) })).min(1).max(10),
-    /** An options request's: what its agent writes (optionsProblem holds it to the request). */
     offer: youiyouxOfferSchema.optional(),
 });
 export const youiyouxRequestSchema = z.object({
@@ -57,7 +41,6 @@ export const youiyouxRequestSchema = z.object({
     author: who,
     createdAt: when,
     updatedAt: when,
-    // Where the person pointed: the page, the component, and (when youiyoux knew it) the file and line that draw it.
     target: z.object({ route: text(300), scope: z.enum(["here", "element"]), name: text(200), file: text(500).optional(), line: z.int().positive().max(Number.MAX_SAFE_INTEGER).optional() }),
     task: youiyouxTaskSchema.optional(),
     thread: z.array(z.unknown()).max(500),
@@ -65,11 +48,8 @@ export const youiyouxRequestSchema = z.object({
 export function readYouiyouxRequest(raw) {
     return parseContract(youiyouxRequestSchema, raw);
 }
-/** The one file an options request's agent may write: `.youi/proposals/p-<the request's hex>.json`. */
 export const proposalIdOf = (request) => `p-${request.slice(2)}`;
 export const proposalFileOf = (proposal) => `.youi/proposals/${proposal}.json`;
-/** Why an options request can't be filed as youiyoux's contract has it, or null: it carries a task with an offer whose
- * proposal is `p-<its own hex>`, whose file is that proposal's, and the task may touch that one file and nothing else. */
 export function optionsProblem(request) {
     if (request.kind !== "options")
         return null;
@@ -85,9 +65,6 @@ export function optionsProblem(request) {
         return "its task may touch more than its options file";
     return null;
 }
-/** `youi.proposal/v1`: the options an agent puts on youiyoux's Screens canvas (youiyoux's packages/core/src/proposals.ts,
- * mirrored). Toolroll checks only the shape and what it reads; youiyoux checks each option against the component's
- * contract when it reads the file. */
 const OPTION_IDS = ["a", "b", "c", "d"];
 export const PROPOSAL_STATUSES = ["open", "chosen", "dismissed"];
 export const youiyouxProposalSchema = z.object({
@@ -124,10 +101,7 @@ export const youiyouxProposalSchema = z.object({
 export function readYouiyouxProposal(raw) {
     return parseContract(youiyouxProposalSchema, raw);
 }
-/** What Toolroll writes beside a request (`youi.request-task/v1`): the task it became, how that task stands, and, when
- * the console has an address, the task's link and `home`, where a person sees and approves all waiting work. */
 export const YOUIYOUX_TASK_STATUSES = ["queued", "needs-you", "building", "ready", "done", "failed", "stopped"];
-/** A link youiyoux opens: http or https, at most 2,000 characters, with no user name or password in it. */
 export const youiyouxLinkSchema = z.string().max(2000).refine(value => {
     try {
         const url = new URL(value);

package/dist/control-setup.js

@@ -36,16 +36,12 @@ export function approveSetup(store, repo, inputs, fingerprint, by, token, now) {
         if (preview.fingerprint !== fingerprint)
             return { ok: false, message: "Setup changed. Review it again." };
         if (preview.models !== null) {
-            // The installation's models, through Settings → Models' one write path (an instance operator's act). The proof
-            // above ran in this same transaction, so the generation read here is the one it was checked against.
             if (!store.isInstanceOperator(by))
                 return { ok: false, message: "Models for this installation aren't chosen yet. An instance operator sets them up first." };
             const applied = applyModelChoices(store, { scope: INSTALLATION_SCOPE, change: presetChange(DEFAULT_PRESET), expected: { state: preview.models.state, change: preview.models.change }, strict: true, knownProject: () => false }, { actor: by, generation: store.accountOf(by)?.generation ?? -1, method: proved.method, live: () => true }, now);
             if (!applied.ok)
                 return { ok: false, message: applied.problem };
         }
-        // The project's own builder only when it differs from what it inherits: a project left on the installation's
-        // routine builder keeps following the installation's sizes and presets.
         const inherited = store.phaseConfig(INSTALLATION_SCOPE, "build");
         const same = inherited !== null && inherited.provider === preview.provider && inherited.model === preview.model;
         if (!same || store.phaseConfig(repo, "build") !== null)
@@ -57,9 +53,6 @@ export function approveSetup(store, repo, inputs, fingerprint, by, token, now) {
         return { ok: true };
     });
 }
-// Last in the file, so the password tripwire's function positions (password-freshness.test.ts) stay as reviewed.
-/** A new installation, nothing chosen yet: setup applies the default preset ("Sized by job") with the project's
- * builder, previewed here row by row, so the first task files on exact models for every size. */
 function installationModels(store) {
     if (!ALL_SLOTS.every(slot => rowAt(store, INSTALLATION_SCOPE, slot) === null))
         return null;

package/dist/control-ui.js

@@ -1,4 +1,3 @@
-/** Shared setup views over the existing project configuration and approval doors. */
 import { html, joinHtml, postForm, reauth } from "./html.js";
 import { ASSISTANTS } from "./setup-guide.js";
 import { openRouterPicker } from "./openrouter-models.js";
@@ -8,7 +7,6 @@ export function connectionWords(connection) {
         unverified: "Not verified", "key-present": "API key saved · not verified", "key-works": "API key works", "key-refused": "API key refused", "missing-key": "API key needed",
     }[connection.state];
 }
-/** The last sign-in check (null: none yet). Check again posts: a page never runs a check (docs/plans/get-side-effects.md). */
 export function connectionHtml(provider, connection, task = "") {
     const query = new URLSearchParams({ provider, ...(task ? { task } : {}) });
     const back = `/control?${query.toString()}`;
@@ -26,7 +24,6 @@ export function controlSetupHtml(data) {
     return html `<h1>Project setup</h1><p>${data.repo}</p><p class="meta">Choose the default builder for new tasks and the preparation command for this project.</p><nav class="assistant-picker row" aria-label="Choose provider">${joinHtml(Object.keys(ASSISTANTS).map(id => html `<a class="button-link" href="/control?${new URLSearchParams({ provider: id, ...(task ? { task } : {}) }).toString()}"${id === provider ? html ` aria-current="page"` : ""}>${ASSISTANTS[id].name}</a>`), " ")}</nav>${connectionHtml(provider, data.connection, task)}${postForm("/control/setup-preview", html `${model}<details class="setup-advanced"><summary>Project preparation</summary>${data.preparation === null ? "" : html `<p class="meta">Suggested from ${data.preparation.evidence}: ${data.preparation.label} — <code>${data.preparation.command}</code>. Review before approving.</p>`}<label>Preparation command<textarea name="command" rows="2" maxlength="2000">${inputs.command}</textarea></label><label>Preparation timeout in seconds<input name="seconds" type="number" min="1" max="3600" value="${inputs.seconds}" required></label><p class="meta">Preparation applies to subsequent runs, including already approved tasks. Saving setup does not execute it.</p></details><button type="submit">Review project setup</button>`, { attrs: { class: "card" }, hidden: { repo: data.repo, provider, task } })}<section class="card"><h2>Agent instructions</h2>${data.instructions.message ? html `<p>${data.instructions.message}</p>` : data.instructions.installed ? html `<p>Toolroll instructions are installed.</p>` :
         html `<p>Give the agent the project's Toolroll handoff instructions.</p>${postForm("/control/instructions-preview", html `<button>Review instructions</button>`, { hidden: { repo: data.repo } })}`}</section><p><a href="/fleet">Configure planning, repair, and review agents</a> · <a href="/tasks/new">Describe a task</a></p>`;
 }
-/** `fields` may still carry the session's csrf (a caller's habit): postForm writes the one CSRF field. */
 export function setupPreviewHtml(inputs, fields, models = null) {
     const { csrf: _csrf, ...rest } = fields;
     const chosen = models === null ? "" : html `<p><strong>Models for every project:</strong> ${models.label}</p><ul>${models.rows.map(row => html `<li>${row.role}: <span class="mono">${row.model}</span></li>`)}</ul><p class="meta">Change them later in Settings → Models.</p>`;

package/dist/controller-service.js

@@ -1,4 +1,3 @@
-/** Service entry for CLI controllers; the engine remains the watch child. */
 import { superviseController } from "./controller-supervisor.js";
 const [file, ...argv] = process.argv.slice(2);
 if (!file)
@@ -8,9 +7,6 @@ const stop = () => stopping.abort();
 process.on("SIGTERM", stop);
 process.on("SIGINT", stop);
 try {
-    // A stop is forwarded to the controller (SIGTERM) and waited for. Past 55 s its whole tree is stopped outright: before
-    // launchd's own ExitTimeOut (60 s) kills this process and could leave the controller running without it. `up` signs
-    // off within 50 s at its default grace and stops itself if this process dies first (operate.ts upCommand).
     await superviseController({ file, argv, signal: stopping.signal, shutdownMs: 55_000, onState: state => {
             if (state.phase === "backoff")
                 process.stderr.write(`Controller exited (${state.exit?.signal ?? state.exit?.code ?? "unknown"}); restart in ${state.retryMs} ms.\n`);

package/dist/controller-supervisor.js

@@ -1,14 +1,6 @@
 import { spawn } from "node:child_process";
 import { performance } from "node:perf_hooks";
 import { stopProcessTree } from "./process-tree.js";
-/** A service process supervises exactly one controller. It knows nothing
- * about tasks, credentials, claims, or retries: those remain in `up`.
- *
- * This closes a Node-controller crash without depending on launchd starting
- * another process. It does not claim to survive its own SIGKILL or bypass an
- * OS policy that defers a LaunchAgent. Children share the service's process
- * group so launchd can also clean up the controller when this process dies.
- */
 export async function superviseController(args) {
     const retryMs = args.retryMs ?? 1_000;
     const maxRetryMs = args.maxRetryMs ?? 30_000;
@@ -25,7 +17,6 @@ export async function superviseController(args) {
     let child = null;
     let escalation = null;
     const emit = (state) => {
-        // Telemetry cannot interrupt a graceful stop or orphan the owned child.
         try {
             args.onState?.(state);
         }
@@ -41,7 +32,6 @@ export async function superviseController(args) {
         if (escalation !== null)
             return;
         escalation = setTimeout(() => {
-            // Signals come only from the still-owned ChildProcess, never status PIDs.
             if (owned.exitCode === null && owned.signalCode === null && !stopProcessTree(owned))
                 owned.kill("SIGKILL");
         }, shutdownMs);
@@ -52,7 +42,6 @@ export async function superviseController(args) {
             generation++;
             const started = performance.now();
             emit({ phase: "starting", generation, controllerPid: null });
-            // The callback above can synchronously cancel before the OS spawn.
             if (args.signal.aborted)
                 break;
             const exited = await new Promise(done => {
@@ -78,8 +67,6 @@ export async function superviseController(args) {
                     if (args.signal.aborted)
                         stop();
                 });
-                // `close` follows both a spawn error and ordinary exit; await it so
-                // the next generation cannot overlap the previous controller handle.
                 owned.once("error", () => { });
                 owned.once("close", (code, signal) => done({ code, signal }));
                 if (args.signal.aborted)
@@ -112,7 +99,6 @@ export async function superviseController(args) {
         emit({ phase: "stopped", generation, controllerPid: null });
     }
 }
-/** Each whole line of a controller's output, prefixed with its label, on this process's stderr. */
 function labelLines(stream, label) {
     if (stream === null)
         return;
@@ -122,7 +108,6 @@ function labelLines(stream, label) {
     stream.on("data", (chunk) => {
         const lines = (pending + chunk).split("\n");
         pending = lines.pop() ?? "";
-        // Bounded: a controller that never ends a line still reaches the log.
         if (pending.length > 64 * 1024) {
             lines.push(pending);
             pending = "";