toolroll 0.5.0

package/dist/capscan.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reading what a repository says it needs.
+ *
+ * Detection walks files the repo itself controls — .env.example, .mcp.json,
+ * supabase/config.toml, workflow files — which makes every byte here
+ * untrusted input. The rule that keeps that safe: **scanned content never
+ * becomes shell code.** A probe is either a fixed template over an
+ * identifier that passed a strict validator, or it is absent. A name that
+ * fails validation is dropped with a note, not quoted, not escaped, not
+ * given the benefit of the doubt — escaping is how injection bugs are
+ * born promising to behave.
+ *
+ * Detection is not authorization, and it is not verification either: every
+ * capability found here lands `unprobed`. CI secret references are recorded
+ * as `ci` capabilities with no probe — a secret living in GitHub's vault is
+ * a fact about CI, not about this machine's environment, and synthesizing
+ * a local env probe for it would manufacture a gap that is not real.
+ */
+import type { Capability } from "./store.js";
+/** A capability as detected, before anybody decides to record it. */
+export type Found = {
+    kind: Capability["kind"];
+    name: string;
+    probe: string | null;
+    source: string;
+};
+export type ScanReport = {
+    found: Found[];
+    /** Names that appeared but failed validation — reported, never used. */
+    rejected: {
+        name: string;
+        source: string;
+    }[];
+};
+export declare function scanRepo(repo: string): ScanReport;

package/dist/capscan.js

@@ -0,0 +1,113 @@
+/**
+ * Reading what a repository says it needs.
+ *
+ * Detection walks files the repo itself controls — .env.example, .mcp.json,
+ * supabase/config.toml, workflow files — which makes every byte here
+ * untrusted input. The rule that keeps that safe: **scanned content never
+ * becomes shell code.** A probe is either a fixed template over an
+ * identifier that passed a strict validator, or it is absent. A name that
+ * fails validation is dropped with a note, not quoted, not escaped, not
+ * given the benefit of the doubt — escaping is how injection bugs are
+ * born promising to behave.
+ *
+ * Detection is not authorization, and it is not verification either: every
+ * capability found here lands `unprobed`. CI secret references are recorded
+ * as `ci` capabilities with no probe — a secret living in GitHub's vault is
+ * a fact about CI, not about this machine's environment, and synthesizing
+ * a local env probe for it would manufacture a gap that is not real.
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+/** Environment variable names, and nothing that only resembles one. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** MCP server labels: package-ish names, no shell metacharacters possible. */
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Reading a whole minified bundle to find nothing is not detection. */
+const MAX_BYTES = 256 * 1024;
+export function scanRepo(repo) {
+    const found = [];
+    const rejected = [];
+    const seen = new Set();
+    const keep = (one) => {
+        const key = `${one.kind}:${one.name}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        found.push(one);
+    };
+    // .env.example — each key is an env capability, probe from a fixed
+    // template. The identifier validator is what makes the template safe.
+    const envExample = readSmall(join(repo, ".env.example"));
+    if (envExample !== null) {
+        for (const line of envExample.split("\n")) {
+            const match = /^\s*(?:export\s+)?([^#\s=]+)=/.exec(line);
+            if (match === null)
+                continue;
+            const name = match[1];
+            if (!IDENTIFIER.test(name)) {
+                rejected.push({ name, source: ".env.example" });
+                continue;
+            }
+            keep({ kind: "env", name, probe: `test -n "$${name}"`, source: ".env.example" });
+        }
+    }
+    // .mcp.json — server names, probe-less: whether a server answers is a
+    // question `mcp initialize` will earn a probe for later; inventing one
+    // now would verify nothing.
+    const mcp = readSmall(join(repo, ".mcp.json"));
+    if (mcp !== null) {
+        try {
+            const parsed = JSON.parse(mcp);
+            for (const name of Object.keys(parsed.mcpServers ?? {})) {
+                if (!LABEL.test(name)) {
+                    rejected.push({ name, source: ".mcp.json" });
+                    continue;
+                }
+                keep({ kind: "mcp", name, probe: null, source: ".mcp.json" });
+            }
+        }
+        catch {
+            // A file that does not parse describes nothing.
+        }
+    }
+    // supabase/config.toml — its presence means the supabase CLI is part of
+    // this repo's workflow. The probe is a constant; nothing scanned enters it.
+    if (existsSync(join(repo, "supabase", "config.toml"))) {
+        keep({
+            kind: "cli",
+            name: "supabase",
+            probe: "supabase projects list",
+            source: "supabase/config.toml",
+        });
+    }
+    // Workflow files — `secrets.NAME` references are ci capabilities, no
+    // probe: they live in GitHub's vault, not this machine's environment.
+    const workflows = join(repo, ".github", "workflows");
+    if (existsSync(workflows)) {
+        for (const file of readdirSync(workflows).filter(name => /\.ya?ml$/.test(name))) {
+            const text = readSmall(join(workflows, file));
+            if (text === null)
+                continue;
+            for (const match of text.matchAll(/secrets\.([A-Za-z0-9_]+)/g)) {
+                const name = match[1];
+                if (name === "GITHUB_TOKEN")
+                    continue; // furnished by the platform, never a gap
+                if (!IDENTIFIER.test(name)) {
+                    rejected.push({ name, source: `.github/workflows/${file}` });
+                    continue;
+                }
+                keep({ kind: "ci", name, probe: null, source: `.github/workflows/${file}` });
+            }
+        }
+    }
+    return { found, rejected };
+}
+function readSmall(path) {
+    try {
+        const text = readFileSync(path, "utf8");
+        return text.length > MAX_BYTES ? text.slice(0, MAX_BYTES) : text;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/chat-acceptance.d.ts

@@ -0,0 +1,71 @@
+/** Read-only acceptance evidence for every chat surface. The saved verdict,
+ * human acceptance and current file health remain separate facts. Reading or
+ * sending this packet never accepts a result or authorizes another action. */
+import type { Store } from "./store.js";
+import type { VerifiedApprover } from "./principal.js";
+import { type CriterionMatrixRow } from "./proof.js";
+export declare const ACCEPTANCE_PAGE_SIZE = 3;
+export declare function acceptanceStatus(proof: {
+    verdict: string;
+    reasons: readonly string[];
+    matrix: readonly CriterionMatrixRow[];
+} | null, accepted: boolean): string;
+export declare function readAcceptanceEvidence(store: Store, who: VerifiedApprover, root: string | undefined, task: string, runId?: number, offset?: number): {
+    ok: false;
+    message: string;
+    body?: never;
+} | {
+    message?: never;
+    ok: true;
+    body: {
+        task: string;
+        run: number;
+        title: string;
+        currentExecution: string;
+        isCurrent: boolean;
+        status: string;
+        recordedVerdict: "attested" | "refuted" | "short" | "verified" | null;
+        accepted: boolean;
+        acceptance: {
+            at: string;
+            note: string | null;
+        } | null;
+        reasons: (string | null)[];
+        gate: Record<string, unknown>;
+        criteriaTotal: number;
+        nextCriterionOffset: number | null;
+        criteria: {
+            id: string;
+            requirement: string | null;
+            state: string;
+            details: (string | null)[];
+            requiredEvidence: readonly import("./scope.js").EvidenceKind[];
+            reviewer: {
+                judgement: import("./proof.js").CriterionJudgementWord;
+                note: string | null;
+            } | null;
+            evidence: {
+                kind: import("./scope.js").EvidenceKind;
+                reference: string | null;
+            }[];
+            coverageGaps: (string | null)[];
+        }[];
+        caveats: (string | null)[];
+        problems: string[];
+        notices: string[];
+        nextStep: string;
+        disclosure: string;
+    };
+};
+/** Deterministic outbox text uses the same verified reader as conversational
+ * requests. Every criterion is included; long values disclose shortening. */
+export declare function acceptanceEvidenceText(store: Store, who: VerifiedApprover, root: string | undefined, task: string, run: number): {
+    ok: false;
+    message: string;
+    body?: never;
+} | {
+    ok: true;
+    text: string;
+    isCurrent: boolean;
+    accepted: boolean;
+};

package/dist/chat-acceptance.js

@@ -0,0 +1,120 @@
+import { readVerifiedArtifact, readVerifiedProofForRun, scanForSecrets } from "./evidence.js";
+import { verificationEvidence } from "./verification-evidence.js";
+import { manualReviewOnly } from "./proof.js";
+export const ACCEPTANCE_PAGE_SIZE = 3;
+export function acceptanceStatus(proof, accepted) {
+    if (accepted)
+        return manualReviewOnly(proof) ? "Accepted by a person" : "Accepted with an exception";
+    if (manualReviewOnly(proof))
+        return "Ready to inspect";
+    return proof === null ? "No checks recorded" : ({ verified: "Checks passed", attested: "Checks reported by the agent", short: "Some required material is missing", refuted: "Saved result conflicts with the approved scope" }[proof.verdict] ?? "Some required material is missing");
+}
+export function readAcceptanceEvidence(store, who, root, task, runId, offset = 0) {
+    const ref = store.lookupRef(task);
+    if (ref?.repo == null || !who.repos.includes(ref.repo))
+        return { ok: false, message: "That task is not in your projects." };
+    const family = store.taskFamilyOf(task, who.repos, false);
+    if (family === null || family.problem !== null)
+        return { ok: false, message: "This task's revision history needs attention." };
+    if (runId === undefined && family.current.id !== task)
+        return { ok: false, message: "A newer revision is current. Choose the exact result before requesting its evidence." };
+    const run = runId === undefined ? store.runsFor(ref.id).find(one => one.finishedAt !== null && ["builder", "repair", "scout"].includes(one.role)) : store.getRun(runId);
+    if (run == null || run.taskRef !== ref.id || run.finishedAt === null || run.outcome === null || !["builder", "repair", "scout"].includes(run.role))
+        return { ok: false, message: "Choose a finished result belonging to that task." };
+    const recorded = store.proofVerdictFor(run.id);
+    const acceptance = store.proofAcceptance(run.id);
+    const matrix = recorded?.matrix ?? [];
+    if (!Number.isSafeInteger(offset) || offset < 0 || (offset > 0 && offset >= matrix.length))
+        return { ok: false, message: "Choose a criterion offset from this result's evidence." };
+    const artifacts = store.artifactsFor(run.id);
+    const problems = [];
+    const notices = [];
+    if (root === undefined)
+        problems.push("This chat cannot read the saved result files.");
+    for (const artifact of artifacts.filter(one => ["proof", "terminal-diff", "diff-stat", "check-log", "review-context", "report", "handoff", "screenshot"].includes(one.kind))) {
+        if (root === undefined)
+            break;
+        const read = readVerifiedArtifact(root, artifact);
+        if (!read.ok || artifact.captureStatus === "failed")
+            problems.push(`Saved ${artifact.kind} #${artifact.id} is unavailable or changed.`);
+        if (artifact.truncated)
+            notices.push(`Saved ${artifact.kind} #${artifact.id} was shortened; omitted content is unavailable.`);
+        if (artifact.redacted)
+            notices.push(`Sensitive content was removed from ${artifact.kind} #${artifact.id}; it cannot support a claim.`);
+    }
+    const proof = root === undefined ? null : readVerifiedProofForRun(store, root, run.id);
+    if (proof === null)
+        problems.push("No readable saved proof is available.");
+    else if (!proof.ok)
+        problems.push("The saved proof is unavailable or cannot be read.");
+    const verification = root === undefined ? null : verificationEvidence(store, root, run.id);
+    let gate = { status: "No machine verification receipt available" };
+    if (verification !== null && !verification.ok) {
+        problems.push(verification.problem);
+        gate = { status: "Verification evidence unavailable" };
+    }
+    else if (verification?.ok && verification.bytes !== null) {
+        const receipt = JSON.parse(verification.bytes);
+        gate = { status: receipt.result.ran ? (receipt.result.exitCode === 0 ? "Passed" : "Failed") : "Did not run", exitCode: receipt.result.exitCode ?? null, command: "The approved project verification command", logShortened: receipt.log.truncated };
+    }
+    // These are summaries for conversation, not substitute approval terms.
+    // Full statements, caveats and references remain on the authenticated screen.
+    const brief = (text, cap = 600) => {
+        if (text == null)
+            return null;
+        if (scanForSecrets(text).length > 0 || /\b\d{5,}:[A-Za-z0-9_-]{20,}\b/.test(text))
+            return "[Sensitive text hidden; inspect the original result in Toolroll]";
+        const clean = text.replace(/(?:[A-Za-z]:[\\/]|\\\\)[^\s"'<>]+/g, "[path]").replace(/(^|[\s"'`(<[=:,])\/(?:[A-Za-z0-9._~-]+\/)*[A-Za-z0-9._~-]+/g, "$1[path]");
+        return clean.length <= cap ? clean : `${clean.slice(0, cap)}… [shortened; open the result for the full text]`;
+    };
+    const page = matrix.slice(offset, offset + ACCEPTANCE_PAGE_SIZE);
+    return { ok: true, body: {
+            task, run: run.id, title: store.getTask(task)?.title ?? task, currentExecution: family.current.id,
+            isCurrent: family.current.id === task && store.runsFor(ref.id).find(one => one.finishedAt !== null && ["builder", "repair", "scout"].includes(one.role))?.id === run.id,
+            status: acceptanceStatus(recorded, acceptance !== null), recordedVerdict: recorded?.verdict ?? null,
+            accepted: acceptance !== null, acceptance: acceptance === null ? null : { at: acceptance.acceptedAt, note: brief(acceptance.note) },
+            reasons: (recorded?.reasons ?? []).map(one => brief(one)), gate,
+            criteriaTotal: matrix.length, nextCriterionOffset: offset + page.length < matrix.length ? offset + page.length : null,
+            criteria: page.map(row => ({ id: row.id, requirement: brief(row.statement), state: row.state === "manual-review" ? "Human review required" : row.state,
+                details: row.detail.map(one => brief(one)), requiredEvidence: row.requiredEvidence,
+                reviewer: row.review == null ? null : { judgement: row.review.judgement, note: brief(row.review.note) },
+                evidence: row.answered.map(one => ({ kind: one.kind, reference: brief(one.ref) })),
+                coverageGaps: row.coverage?.gaps.map(one => brief(one)) ?? [],
+            })),
+            caveats: proof?.ok ? proof.proof.caveats.map(one => brief(one)) : [],
+            problems, notices,
+            nextStep: acceptance !== null ? "Acceptance is already recorded. No further acceptance is needed for this result." : "Inspect the saved result, then mark it complete or request changes. Opening a link or requesting images changes nothing.",
+            disclosure: "Conversation summary only. Inspect the complete result, its checks and its terms on the result screen before marking it complete.",
+        } };
+}
+/** Deterministic outbox text uses the same verified reader as conversational
+ * requests. Every criterion is included; long values disclose shortening. */
+export function acceptanceEvidenceText(store, who, root, task, run) {
+    const first = readAcceptanceEvidence(store, who, root, task, run);
+    if (!first.ok)
+        return first;
+    const packet = first.body;
+    const criteria = [...packet.criteria];
+    let offset = packet.nextCriterionOffset;
+    while (offset !== null) {
+        const page = readAcceptanceEvidence(store, who, root, task, run, offset);
+        if (!page.ok)
+            return page;
+        criteria.push(...page.body.criteria);
+        offset = page.body.nextCriterionOffset;
+    }
+    const lines = [
+        `Result #${run} · ${packet.status}`,
+        `Project checks: ${String(packet.gate["status"])}${packet.gate["logShortened"] === true ? " (saved log shortened)" : ""}`,
+        ...criteria.map(row => [
+            `${row.id}: ${row.requirement} — ${row.state === "pass" ? "passed" : row.state}`,
+            ...(row.reviewer === null ? [] : [`Earlier assessment ${row.reviewer.judgement === "upholds" ? "supported this finding" : row.reviewer.judgement === "contradicts" ? "disputed this finding" : "could not confirm this finding"}: ${row.reviewer.note ?? "No note saved."}`]),
+            ...row.coverageGaps.map(gap => `Coverage gap: ${gap}`),
+        ].join("\n")),
+        ...packet.caveats.map(caveat => `Limitation: ${caveat}`),
+        ...packet.problems.map(problem => `Saved material problem: ${problem}`),
+        ...packet.notices,
+        packet.disclosure,
+    ];
+    return { ok: true, text: lines.join("\n\n"), isCurrent: packet.isCurrent, accepted: packet.accepted };
+}

package/dist/chat-actions.d.ts

@@ -0,0 +1,265 @@
+import { type Store } from "./store.js";
+import { type VerifiedApprover } from "./principal.js";
+export declare const CHAT_ACTIONS: {
+    readonly skill_import: {
+        readonly label: "Add skill";
+        readonly protected: true;
+        readonly password: false;
+    };
+    readonly skill_enable: {
+        readonly label: "Enable skill";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly skill_disable: {
+        readonly label: "Disable skill";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly skill_restore: {
+        readonly label: "Restore skills";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly skill_test: {
+        readonly label: "Test skill";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly knowledge_instructions: {
+        readonly label: "Save project instructions";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly knowledge_save: {
+        readonly label: "Save reference";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly knowledge_remove: {
+        readonly label: "Remove reference";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly knowledge_restore: {
+        readonly label: "Restore knowledge";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly tool_add: {
+        readonly label: "Add tool";
+        readonly protected: true;
+        readonly password: true;
+    };
+    readonly tool_remove: {
+        readonly label: "Remove tool";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_create: {
+        readonly label: "Create flow";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_edit: {
+        readonly label: "Save flow";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_add: {
+        readonly label: "Add card";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_move: {
+        readonly label: "Move card";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_approve: {
+        readonly label: "Approve";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_send_back: {
+        readonly label: "Send back";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_cancel: {
+        readonly label: "Cancel card";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_comment: {
+        readonly label: "Comment";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_assign: {
+        readonly label: "Set owner";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_card_watch: {
+        readonly label: "Follow card";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_script_save: {
+        readonly label: "Save script";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_trigger_add: {
+        readonly label: "Add trigger";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_trigger_pause: {
+        readonly label: "Pause trigger";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_trigger_resume: {
+        readonly label: "Turn trigger on";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly flow_trigger_remove: {
+        readonly label: "Remove trigger";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_create: {
+        readonly label: "Add teammate";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_soul: {
+        readonly label: "Update soul file";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_state: {
+        readonly label: "Change teammate";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_note: {
+        readonly label: "Tell teammate";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_answer: {
+        readonly label: "Answer teammate";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_tools: {
+        readonly label: "Change teammate's tools";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_memory: {
+        readonly label: "Change teammate's memory";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_routine: {
+        readonly label: "Change teammate's routines";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly teammate_undo: {
+        readonly label: "Undo teammate's call";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly kit_setup: {
+        readonly label: "Set up kit";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly decision_record: {
+        readonly label: "Record decision";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly decision_retire: {
+        readonly label: "Retire decision";
+        readonly protected: false;
+        readonly password: false;
+    };
+    readonly scope_approve: {
+        readonly label: "Approve work";
+        readonly protected: true;
+        readonly password: true;
+    };
+    readonly result_accept: {
+        readonly label: "Mark complete";
+        readonly protected: true;
+        readonly password: false;
+    };
+    readonly task_cancel: {
+        readonly label: "Cancel task";
+        readonly protected: true;
+        readonly password: false;
+    };
+    readonly task_resume: {
+        readonly label: "Resume task";
+        readonly protected: true;
+        readonly password: true;
+    };
+};
+export type ChatAction = keyof typeof CHAT_ACTIONS;
+/** Protected actions a paired phone may confirm behind its own explicit
+ * yes/cancel challenge instead of the console's secure screen. Password
+ * actions and long or redacted terms never qualify. */
+export declare const CHALLENGE_ACTIONS: ReadonlySet<ChatAction>;
+export declare function isChatAction(value: unknown): value is ChatAction;
+export type SharedAction = {
+    operation: ChatAction;
+    request: Record<string, unknown>;
+    repo: string;
+    title: string;
+    terms: string[];
+    stamp: string;
+    state: Record<string, unknown>;
+};
+export declare const CHAT_ACTION_FIELDS: Record<ChatAction, readonly string[]>;
+/** No writes, including at preview. Store-derived snapshots are never accepted
+ * from a model. Rebuilding the same request before execution catches changes. */
+export declare function prepareSharedAction(store: Store, who: VerifiedApprover, operation: ChatAction, input: Record<string, unknown>, root?: string, now?: Date): SharedAction;
+export declare function sharedActionPayload(value: Record<string, unknown>): SharedAction | null;
+export declare function sharedActionNeedsReview(action: SharedAction): boolean;
+/** Whether a paired phone may confirm this protected action behind its own
+ * explicit challenge: the action is on the challenge list, needs no
+ * password, and every term fits the card unshortened. */
+export declare function sharedActionAllowsChallenge(action: SharedAction): boolean;
+export declare function sharedActionReviewPath(id: number): string;
+export declare function mintSharedActionReview(store: Store, who: VerifiedApprover, id: number, root: string, now: Date): {
+    payload: SharedAction;
+    nonce: string;
+};
+export type SharedActionOptions = {
+    via: "web" | "cli" | "telegram" | "slack" | "discord" | "teams";
+    root?: string;
+    review?: {
+        nonce: string;
+        password: string;
+    };
+    confirm?: boolean;
+};
+/** Called inside the proposal door's transaction, after ownership and session
+ * checks. No password or review receipt is ever part of a saved proposal. */
+export declare function executeSharedAction(store: Store, who: VerifiedApprover, id: number, payload: SharedAction, now: Date, options: SharedActionOptions): {
+    ok: true;
+    said: string;
+    taskId: string | null;
+    href?: string;
+} | {
+    ok: false;
+    reason: "needs-confirm" | "stale" | "refused";
+    said: string;
+};