toolroll 0.9.34 → 0.9.37

package/dist/project-skills.js

@@ -6,6 +6,10 @@ import { parseDocument } from "yaml";
 import { acceptedIdentities, learningIdentity, learningSha } from "./project-learning.js";
 import { scanForSecrets } from "./evidence.js";
 import { fileTaskProposal } from "./proposal.js";
+import { TEXT_LIMITS } from "./text-limits.js";
+import { contractError } from "./contracts/contract.js";
+import { SKILL_COUNTS, SKILL_LIMITS, readSkillsSnapshotPayload, savedSkillPackageSchema, savedSkillsSnapshotSchema, skillPackageSchema, skillSelectionSchema, } from "./contracts/project-skills.js";
+export { SKILL_LIMITS };
 export const SKILLS_SCHEMA = `
 CREATE TABLE IF NOT EXISTS skill_package (sha TEXT PRIMARY KEY, payload TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS skill_owner (sha TEXT NOT NULL REFERENCES skill_package(sha), actor TEXT NOT NULL, at TEXT NOT NULL, PRIMARY KEY(sha,actor));
@@ -14,14 +18,6 @@ CREATE TABLE IF NOT EXISTS skill_snapshot (run INTEGER PRIMARY KEY REFERENCES ru
 CREATE TABLE IF NOT EXISTS skill_test (task_ref INTEGER PRIMARY KEY REFERENCES task_ref(id), package TEXT NOT NULL REFERENCES skill_package(sha), actor TEXT NOT NULL, request_sha TEXT NOT NULL, sample TEXT NOT NULL, source_run INTEGER REFERENCES run(id), feedback TEXT, identity TEXT NOT NULL);
 ${["skill_package", "skill_owner", "project_skill_change", "skill_snapshot", "skill_test"].map((t) => `CREATE TRIGGER IF NOT EXISTS ${t}_no_update BEFORE UPDATE ON ${t} BEGIN SELECT RAISE(ABORT,'Skill history is immutable'); END; CREATE TRIGGER IF NOT EXISTS ${t}_no_delete BEFORE DELETE ON ${t} BEGIN SELECT RAISE(ABORT,'Skill history is immutable'); END;`).join("\n")}
 `;
-export const SKILL_LIMITS = {
-    files: 64,
-    packageBytes: 1024 * 1024,
-    fileBytes: 256 * 1024,
-    bodyBytes: 24 * 1024,
-    enabled: 8,
-    selectionBytes: 2 * 1024 * 1024,
-};
 const controls = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufffd]/u;
 const text = (value, max, label) => {
     if (typeof value !== "string" ||
@@ -44,7 +40,7 @@ export function validateSkill(files, source) {
         .map((file) => {
         if (!file ||
             typeof file.path !== "string" ||
-            file.path.length > 240 ||
+            file.path.length > TEXT_LIMITS.skillPath ||
             !/^[a-zA-Z0-9_. -]+(?:\/[a-zA-Z0-9_. -]+)*$/.test(file.path) ||
             file.path
                 .split("/")
@@ -91,13 +87,13 @@ export function validateSkill(files, source) {
     }
     if (!front || typeof front !== "object" || Array.isArray(front))
         throw Error("Skill metadata must contain a name and description.");
-    const name = text(front["name"], 64, "Skill name");
+    const name = text(front["name"], TEXT_LIMITS.skillNameBytes, "Skill name");
     if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
         throw Error("Use a lowercase skill name with hyphens between words.");
-    const description = text(front["description"], 1024, "Description");
+    const description = text(front["description"], TEXT_LIMITS.skillDescriptionBytes, "Description");
     const requirements = front["compatibility"] === undefined
         ? ""
-        : text(front["compatibility"], 500, "Requirements");
+        : text(front["compatibility"], TEXT_LIMITS.skillRequirementsBytes, "Requirements");
     const extensions = Object.keys(front).filter((k) => !["name", "description", "license", "compatibility", "metadata"].includes(k));
     const warnings = [];
     if (extensions.length || safe.some((f) => f.path === "agents/openai.yaml"))
@@ -106,14 +102,21 @@ export function validateSkill(files, source) {
         warnings.push("Dynamic shell substitutions are not evaluated by the skill manager.");
     if (safe.some((f) => f.path.startsWith("scripts/")))
         warnings.push("Includes scripts. Agents may run them only within their task permissions.");
-    return {
+    return written(skillPackageSchema, {
         name,
         description,
-        source: text(source, 500, "Source"),
+        source: text(source, TEXT_LIMITS.skillSourceBytes, "Source"),
         requirements,
         warnings,
         files: safe,
-    };
+    });
+}
+/** A payload through its schema before it is written; a refusal names the field. */
+function written(schema, value) {
+    const read = schema.safeParse(value, { reportInput: true });
+    if (!read.success)
+        throw Error(`This skill could not be saved: ${contractError(read.error).join("; ")}`);
+    return read.data;
 }
 function admit(store, repo, actor, write = false) {
     if (!store.schemaCurrent() ||
@@ -125,18 +128,24 @@ function admit(store, repo, actor, write = false) {
 /** Revisions under any identity this project accepts, as a bound JSON list. */
 const IN_ACCEPTED = "identity IN (SELECT value FROM json_each(?))";
 const listOf = (accepted) => JSON.stringify([...accepted]);
-function unpack(payload, sha) {
+/** Saved bytes are checked against their digest first; only then are they parsed through their schema. */
+function unpack(payload, sha, read) {
     if (typeof payload !== "string" || learningSha(payload) !== sha)
         throw Error("Saved skills could not be verified.");
-    return JSON.parse(payload);
+    const value = read(JSON.parse(payload));
+    if (value === null)
+        throw Error("Saved skills could not be verified.");
+    return value;
 }
+const through = (schema) => (input) => { const read = schema.safeParse(input); return read.success ? read.data : null; };
+const unpackSelection = (payload, sha) => unpack(payload, sha, through(skillSelectionSchema));
 function packageOf(store, sha) {
     const row = store.handle
         .prepare("SELECT payload FROM skill_package WHERE sha=?")
         .get(sha);
     if (!row)
         throw Error("That skill version is unavailable.");
-    return { ...unpack(row["payload"], sha), sha };
+    return { ...unpack(row["payload"], sha, through(savedSkillPackageSchema)), sha };
 }
 function current(store, repo, accepted) {
     const row = store.handle
@@ -148,7 +157,7 @@ function current(store, repo, accepted) {
         throw Error("The project changed. Its previous skills have not been applied.");
     return {
         revision: Number(row["revision"]),
-        selection: unpack(row["payload"], row["sha"]),
+        selection: unpackSelection(row["payload"], row["sha"]),
     };
 }
 export function skillsView(store, repo, actor) {
@@ -173,7 +182,7 @@ export function skillsView(store, repo, actor) {
             }
         }
         if (row)
-            for (const c of Object.values(unpack(row["payload"], row["sha"])))
+            for (const c of Object.values(unpackSelection(row["payload"], row["sha"])))
                 visible.add(c.sha);
     }
     for (const c of Object.values(value.selection))
@@ -192,7 +201,7 @@ export function skillsView(store, repo, actor) {
         revision: Number(r["revision"]),
         actor: String(r["actor"]),
         at: String(r["at"]),
-        enabled: Object.entries(unpack(r["payload"], r["sha"]))
+        enabled: Object.entries(unpackSelection(r["payload"], r["sha"]))
             .filter(([, c]) => c.enabled)
             .map(([name, c]) => ({ name, version: c.sha.slice(0, 10) })),
     }));
@@ -215,7 +224,7 @@ export function skillsVersion(store, repo, actor, revision) {
     const row = store.handle.prepare(`SELECT payload,sha FROM project_skill_change WHERE repo=? AND ${IN_ACCEPTED} AND revision=?`).get(repo, listOf(accepted), revision);
     if (!row)
         throw Error("That skills version is unavailable.");
-    const selection = unpack(row["payload"], row["sha"]);
+    const selection = unpackSelection(row["payload"], row["sha"]);
     for (const choice of Object.values(selection))
         packageOf(store, choice.sha);
     return selection;
@@ -229,7 +238,7 @@ export function importSkill(store, repo, actor, files, source, now = new Date())
             .get(sha, actor) &&
             Number(store.handle
                 .prepare("SELECT COUNT(*) AS n FROM skill_owner WHERE actor=?")
-                .get(actor)?.["n"]) >= 100)
+                .get(actor)?.["n"]) >= SKILL_COUNTS.library)
             throw Error("Your library has 100 saved versions. Reuse an existing version.");
         store.handle
             .prepare("INSERT OR IGNORE INTO skill_package VALUES (?,?)")
@@ -255,7 +264,7 @@ export function changeSkills(store, args, now = new Date()) {
                 .get(args.repo, listOf(accepted), args.restore ?? -1);
             if (!row)
                 throw Error("That version is unavailable.");
-            selection = unpack(row["payload"], row["sha"]);
+            selection = unpackSelection(row["payload"], row["sha"]);
         }
         else {
             const skill = view.library.find((p) => p.sha === args.sha);
@@ -274,7 +283,7 @@ export function changeSkills(store, args, now = new Date()) {
         if (enabled.length > SKILL_LIMITS.enabled ||
             Buffer.byteLength(JSON.stringify(enabled)) > SKILL_LIMITS.selectionBytes)
             throw Error("Enable up to 8 skills, totaling at most 2 MB.");
-        const payload = JSON.stringify(selection);
+        const payload = JSON.stringify(written(skillSelectionSchema, selection));
         store.handle
             .prepare("INSERT INTO project_skill_change VALUES (?,?,?,?,?,?,?)")
             .run(args.repo, identity, view.revision + 1, args.actor, now.toISOString(), payload, learningSha(payload));
@@ -316,7 +325,7 @@ export function readSkillsSnapshot(store, runId) {
     const run = store.getRun(runId);
     if (!run || store.refForId(run.taskRef)?.repo !== row["repo"])
         throw Error("Saved skills belong to another project.");
-    const saved = unpack(row["payload"], row["sha"]);
+    const saved = unpack(row["payload"], row["sha"], (input) => { const read = readSkillsSnapshotPayload(input); return read.ok ? read.value : null; });
     const { packageShas, ...facts } = saved;
     if (packageShas.length &&
         !acceptedIdentities(store, String(row["repo"])).has(facts.identity))
@@ -401,10 +410,10 @@ export function freezeSkills(store, runId) {
             }
         }
         const { packages, ...facts } = snapshot;
-        const payload = JSON.stringify({
+        const payload = JSON.stringify(written(savedSkillsSnapshotSchema, {
             ...facts,
             packageShas: packages.map((p) => p.sha),
-        });
+        }));
         store.handle
             .prepare("INSERT INTO skill_snapshot VALUES (?,?,?,?)")
             .run(runId, ref.repo, payload, learningSha(payload));
@@ -474,11 +483,11 @@ export function testSkill(store, args, now = new Date()) {
     const skill = view.library.find((p) => p.sha === args.sha);
     if (!skill)
         throw Error("Choose an available skill.");
-    const sample = text(args.sample, 4000, "Sample request");
-    if (sample.length > 800)
+    const sample = text(args.sample, TEXT_LIMITS.skillSampleBytes, "Sample request");
+    if (sample.length > TEXT_LIMITS.skillSample)
         throw Error("Keep the sample request to 800 characters.");
-    const feedback = args.feedback === undefined ? null : text(args.feedback, 2000, "Feedback");
-    if (feedback && feedback.length > 500)
+    const feedback = args.feedback === undefined ? null : text(args.feedback, TEXT_LIMITS.skillFeedbackBytes, "Feedback");
+    if (feedback && feedback.length > TEXT_LIMITS.skillFeedback)
         throw Error("Keep feedback to 500 characters.");
     if (args.sourceRun !== undefined) {
         const source = skillTestResult(store, args.sourceRun, args.actor);

package/dist/project-tools.d.ts

@@ -201,6 +201,7 @@ export declare function prepareRunTools(store: Pick<Store, "projectTools" | "get
     now: Date;
     includeModel: boolean;
     readOnly?: Readonly<Record<string, readonly string[]>>;
+    withheld?: Readonly<Record<string, string>>;
 }): ToolLaunchArgs;
 /** When a launch's tools cannot be prepared, it still gets none of anything else's: the same isolation with an empty list. */
 export declare function noToolsArgs(provider: "claude" | "codex" | "openrouter" | "gemini", includeModel: boolean): ToolLaunchArgs;

package/dist/project-tools.js

@@ -694,7 +694,7 @@ export function toolLaunchFor(store, runId, home = homedir()) {
  * with `argv`/`env` and calls `cleanup` when the process is done.
  */
 export function prepareRunTools(store, runId, provider, options) {
-    const launch = limitedTo(toolLaunchFor(store, runId, options.home), options.readOnly);
+    const launch = limitedTo(toolLaunchFor(store, runId, options.home), options.readOnly, options.withheld);
     const enabledTools = options.readOnly === undefined ? {} : { enabledTools: options.readOnly };
     const prepared = provider === "claude" ? claudeToolArgs(launch)
         : provider === "codex" ? codexToolArgs(launch, { includeModel: options.includeModel, ...enabledTools })
@@ -710,14 +710,14 @@ export function prepareRunTools(store, runId, provider, options) {
     }), options.now);
     return prepared;
 }
-/** A research step's launch: only the servers it may read, each limited to its read-only actions; the rest left out, saying why. */
-function limitedTo(launch, readOnly) {
+/** A research step's launch: only the servers it may read, each limited to its read-only actions; the rest left out, saying why (`withheld`, when a service has its own reason). */
+function limitedTo(launch, readOnly, withheld = {}) {
     if (readOnly === undefined)
         return launch;
     const readable = (name) => (readOnly[name] ?? []).length > 0;
     return {
         tools: launch.tools.filter(one => readable(one.spec.name)),
-        skipped: [...launch.skipped, ...launch.tools.filter(one => !readable(one.spec.name)).map(one => ({ name: one.spec.name, reason: "research reads only connected services' read-only actions" }))],
+        skipped: [...launch.skipped, ...launch.tools.filter(one => !readable(one.spec.name)).map(one => ({ name: one.spec.name, reason: withheld[one.spec.name] ?? "research reads only connected services' read-only actions" }))],
     };
 }
 /** When a launch's tools cannot be prepared, it still gets none of anything else's: the same isolation with an empty list. */

package/dist/proof.d.ts

@@ -18,31 +18,12 @@
  * returned — is gathered by the caller (`builder.ts`) and handed in as data,
  * so the review itself stays testable without a filesystem or a database.
  */
-import { type EvidenceKind } from "./scope.js";
+import type { EvidenceKind } from "./scope.js";
+import { type ContractProblem } from "./contracts/contract.js";
+import type { VerifyCommandFacts } from "./contracts/verification-receipt.js";
+import { type CriterionEvidenceRef, type ParsedProof } from "./contracts/proof.js";
+export { PROOF_LIMITS, type CriterionEvidenceRef, type ParsedCheck, type ParsedCriterion, type ParsedProof, type ParsedScreenshot } from "./contracts/proof.js";
 export type ProofVerdict = "verified" | "attested" | "short" | "refuted";
-/** One typed reference the proof cites to answer a criterion's required
- * evidence: `ref` names an existing check's command, an existing
- * screenshot's path, a path inside `changed`, or (kind `manual-review`)
- * free-text pointing at nothing machine-checkable. Additive (v39): a
- * criterion with no `evidence` array parses the same as one that always
- * had none — legacy proofs, and every proof against a rubric-less scope,
- * are untouched. */
-export type CriterionEvidenceRef = {
-    kind: EvidenceKind;
-    ref: string;
-};
-export type ParsedCriterion = {
-    id: string;
-    statement: string;
-    /** pending-verification asserts all agent-owned work is met; only the
-     * machine-owned final check remains. It never upgrades a legacy failure. */
-    verdict: "met" | "not-met" | "not-checked" | "pending-verification";
-    how: string;
-    /** v39: typed references answering a SIGNED criterion by exact id.
-     * `[]` for a criterion the agent added beyond the rubric, or for any
-     * proof written before this migration. */
-    evidence: CriterionEvidenceRef[];
-};
 /** v39: the rubric side of a criterion, as `adjudicate` reads it — the
  * SIGNED id, statement, and required evidence kinds. Never `how` (never
  * signed). Empty = nothing signed: `adjudicate` runs the v1 rules,
@@ -54,31 +35,7 @@ export type ApprovedCriterion = {
 };
 /** Only submission defects. A truthful not-met answer is not malformed. */
 export declare function proofSubmissionProblems(proof: ParsedProof, rubric: readonly ApprovedCriterion[]): string[];
-export type ParsedCheck = {
-    command: string;
-    exitCode: number;
-    summary: string;
-};
-/** A screenshot the agent claims proves UI-facing work. `path` is the
- * repository-relative path the file lived at in the worktree when the
- * agent wrote the proof — validated as a path shape here; validated as an
- * actual bounded PNG/JPEG, and read, by the caller. */
-export type ParsedScreenshot = {
-    path: string;
-    caption: string;
-};
-export type ParsedProof = {
-    version: 1;
-    criteria: ParsedCriterion[];
-    checks: ParsedCheck[];
-    changed: string[];
-    caveats: string[];
-    screenshots: ParsedScreenshot[];
-};
-export type ProofProblem = {
-    reason: string;
-    message: string;
-};
+export type ProofProblem = ContractProblem;
 export type ProofParseResult = {
     ok: true;
     proof: ParsedProof;
@@ -86,31 +43,14 @@ export type ProofParseResult = {
     ok: false;
     problems: ProofProblem[];
 };
-/** Caps are BYTES of UTF-8, matching the scout report's rule: a payload is
- * the same size whatever script it is written in. */
-export declare const PROOF_LIMITS: {
-    readonly payload: number;
-    readonly criteria: 12;
-    readonly criterionId: 40;
-    readonly criterionStatement: 300;
-    readonly criterionHow: 500;
-    readonly evidencePerCriterion: 4;
-    readonly evidenceRef: 300;
-    readonly checks: 12;
-    readonly checkCommand: 300;
-    readonly checkSummary: 300;
-    readonly changed: 64;
-    readonly changedPath: 300;
-    readonly caveats: 8;
-    readonly caveat: 300;
-    readonly screenshots: 8;
-    readonly screenshotPath: 300;
-    readonly screenshotCaption: 300;
-};
+/**
+ * Read a proof: the payload byte cap and JSON first, then the proof schema (version 2 as itself, the version 1 a
+ * builder writes upgraded, a newer one refused plainly), then the plain-code rules. Every problem names its path and
+ * is reported at once; fail closed.
+ */
 export declare function parseProof(raw: string): ProofParseResult;
-/** Re-serialize the validated shape, never the agent's raw bytes (the
- * scout report's rule, `scout.ts`): what is stored and later hash-verified
- * is exactly what this parser admitted, key order and all. */
+/** Serialize the validated shape, never the agent's raw bytes (the scout report's rule, `scout.ts`): what is stored
+ * and later hash-verified is exactly what the schema admitted, in its key order. */
 export declare function serializeProof(proof: ParsedProof): string;
 /** One caveat that admits an exception to a criterion the same proof marks
  * `met` — the proof's own verdict disagreeing with its own words (atomic
@@ -255,24 +195,8 @@ export declare function frozenCriterionProblems(submitted: ParsedProof, correcte
  * correction and re-reads it after that correction and after the final
  * gate; a reading that differs is never adjudicated from the cached one. */
 export declare function sameDiffStatFacts(a: DiffStatFacts | null, b: DiffStatFacts | null): boolean;
-/** The plane's own re-run of the repository's approved verification
- * command, when one is configured. `ran: false` covers both "none
- * configured" and "configured but the run could not attempt it" — the
- * latter is distinguished by `attemptFailed`, which downgrades to `short`
- * rather than `refuted`: "we could not check" is not "the claim is false". */
-export type VerifyCommandFacts = {
-    configured: false;
-} | {
-    configured: true;
-    ran: false;
-    attemptFailed: true;
-    failure?: "spawn-failed" | "timed-out" | "dependency-missing" | "setup-stale" | "setup-failed" | "own-install-failed" | "tracked-files-changed" | "setup-changed-files" | "checkout-moved" | "cleanliness-unavailable" | "dependency-still-missing" | "retry-spawn-failed" | "retry-timed-out" | "custody-lost";
-} | {
-    configured: true;
-    ran: true;
-    exitCode: number;
-    setupReplayed?: true;
-};
+/** What the approved verification command did (the receipt's `result`); its schema lives with the receipt. */
+export type { VerifyCommandFacts } from "./contracts/verification-receipt.js";
 export type AdjudicateInput = {
     /** New captures may assess the signed goal directly when the builder wrote
      * no optional proof. Historical calls retain their original contract. */