toolroll 0.9.63 → 0.9.65

package/dist/webhook-signing.js

@@ -0,0 +1,119 @@
+/**
+ * How a webhook proves who sent it (docs/plans/webhook-tasks.md §1). Each sender's check runs over the raw bytes,
+ * before anything is parsed; a security header sent more than once, or not at all, is refused. Nothing here reads or
+ * writes the store: the caller passes the current generation's secret, and a refusal writes nothing.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { WEBHOOK_SENDERS } from "./contracts/flow.js";
+export { WEBHOOK_SENDERS };
+export const SENDER_WORDS = {
+    none: "Unsigned", standard: "Standard Webhooks", "github-style": "GitHub-style signature", sentry: "Sentry", vercel: "Vercel",
+};
+/** A Standard Webhooks timestamp may be this far from now, either way. */
+export const STANDARD_TOLERANCE_MS = 5 * 60_000;
+const HEX = (bytes) => new RegExp(`^[0-9a-f]{${bytes * 2}}$`);
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const HIDDEN = /[\u0000-\u001f\u007f]/;
+/** Exactly one value for a security header, or why not. */
+function single(headers, name) {
+    const values = headers[name] ?? [];
+    if (values.length === 0)
+        return { ok: false, said: `The ${name} header is missing.` };
+    if (values.length > 1)
+        return { ok: false, said: `The ${name} header was sent more than once.` };
+    return { ok: true, value: values[0] };
+}
+function same(expected, given) {
+    return expected.length === given.length && timingSafeEqual(expected, given);
+}
+/** A `whsec_` secret's key bytes, or null when it isn't one. */
+export function standardKey(secret) {
+    if (!secret.startsWith("whsec_"))
+        return null;
+    const encoded = secret.slice("whsec_".length);
+    if (!BASE64.test(encoded) || encoded.length % 4 !== 0)
+        return null;
+    const key = Buffer.from(encoded, "base64");
+    return key.length >= 24 && key.length <= 64 ? key : null;
+}
+/** Whether a delivery was signed with this secret by this sender. `none` proves nothing and is never passed here. */
+export function proveDelivery(sender, secret, headers, body, now) {
+    switch (sender) {
+        case "github-style": {
+            const header = single(headers, "x-hub-signature-256");
+            if (!header.ok)
+                return header;
+            const given = header.value.trim().toLowerCase();
+            if (!given.startsWith("sha256=") || !HEX(32).test(given.slice(7)))
+                return { ok: false, said: "The signature isn't sha256=<hex>." };
+            return same(createHmac("sha256", secret).update(body).digest(), Buffer.from(given.slice(7), "hex")) ? { ok: true, signedId: null } : { ok: false, said: "Signature doesn't match." };
+        }
+        case "sentry": {
+            const header = single(headers, "sentry-hook-signature");
+            if (!header.ok)
+                return { ok: false, said: header.said.includes("missing") ? "Sentry didn't sign this: use an Internal Integration's webhook." : header.said };
+            const given = header.value.trim().toLowerCase();
+            if (!HEX(32).test(given))
+                return { ok: false, said: "The signature isn't a SHA-256 hex digest." };
+            return same(createHmac("sha256", secret).update(body).digest(), Buffer.from(given, "hex")) ? { ok: true, signedId: null } : { ok: false, said: "Signature doesn't match." };
+        }
+        case "vercel": {
+            const header = single(headers, "x-vercel-signature");
+            if (!header.ok)
+                return header;
+            const given = header.value.trim().toLowerCase();
+            if (!HEX(20).test(given))
+                return { ok: false, said: "The signature isn't a SHA-1 hex digest." };
+            return same(createHmac("sha1", secret).update(body).digest(), Buffer.from(given, "hex")) ? { ok: true, signedId: null } : { ok: false, said: "Signature doesn't match." };
+        }
+        case "standard": {
+            const key = standardKey(secret);
+            if (key === null)
+                return { ok: false, said: "The saved secret isn't a whsec_ secret." };
+            const id = single(headers, "webhook-id"), stamp = single(headers, "webhook-timestamp"), signature = single(headers, "webhook-signature");
+            for (const header of [id, stamp, signature])
+                if (!header.ok)
+                    return header;
+            const idText = id.value, stampText = stamp.value, signatureText = signature.value;
+            if (idText === "" || idText.length > 200 || HIDDEN.test(idText))
+                return { ok: false, said: "The webhook-id header isn't usable." };
+            // Unix seconds, as an integer: milliseconds, decimals and signs are refused, not guessed at.
+            if (!/^\d{1,11}$/.test(stampText))
+                return { ok: false, said: "The webhook-timestamp isn't Unix seconds." };
+            if (Math.abs(now.getTime() - Number(stampText) * 1000) > STANDARD_TOLERANCE_MS)
+                return { ok: false, said: "Too old, or from the future." };
+            const expected = createHmac("sha256", key).update(Buffer.concat([Buffer.from(`${idText}.${stampText}.`, "utf8"), body])).digest();
+            // Any well-formed v1 entry may match; a malformed entry is passed over, and none well-formed is a refusal.
+            let wellFormed = 0;
+            for (const entry of signatureText.split(" ")) {
+                if (!entry.startsWith("v1,"))
+                    continue;
+                const encoded = entry.slice(3);
+                if (!BASE64.test(encoded) || encoded.length % 4 !== 0)
+                    continue;
+                const given = Buffer.from(encoded, "base64");
+                if (given.length !== 32)
+                    continue;
+                wellFormed++;
+                if (same(expected, given))
+                    return { ok: true, signedId: idText };
+            }
+            return { ok: false, said: wellFormed === 0 ? "The webhook-signature has no v1 signature." : "Signature doesn't match." };
+        }
+    }
+}
+/** Whether a pasted secret has its sender's shape (Sentry's and Vercel's come from them; the others can be made here). */
+export function secretShapeOk(sender, secret) {
+    switch (sender) {
+        case "sentry": return /^[0-9a-fA-F]{32,128}$/.test(secret);
+        case "vercel": return /^[A-Za-z0-9]{16,200}$/.test(secret);
+        case "standard": return standardKey(secret) !== null;
+        case "github-style": return /^[\x21-\x7e]{16,200}$/.test(secret);
+    }
+}
+/** A new secret for a sender Toolroll can make one for; Sentry's and Vercel's are pasted from them. */
+export function makeSecret(sender) {
+    return sender === "standard" ? `whsec_${randomBytes(32).toString("base64")}` : randomBytes(32).toString("hex");
+}
+/** Whether Toolroll makes this sender's secret (and shows it once), rather than asking for the sender's own. */
+export const makesSecret = (sender) => sender === "standard" || sender === "github-style";

package/dist/work-index.d.ts

@@ -47,6 +47,8 @@ export type WorkIndexOptions = {
     state?: TaskState;
     leadId?: string;
     root?: string;
+    /** Only these families (by root task id): the sidebar reads its rows' own words this way. */
+    roots?: readonly string[];
 };
 /** How the list is grouped: the Needs you rows by their ask, then building, then the rest. */
 export type WorkIndexGroup = Ask | 'building' | 'rest';
@@ -85,6 +87,33 @@ export declare function workIndexPage(store: Store, now: Date, access: WorkSumma
  * permission-bound and bypasses pagination, never action-time verification. */
 export declare function workIndexTask(store: Store, taskId: string, now: Date, access: WorkSummaryAccess, root?: string): WorkIndexItem | null;
 export declare function workCountsByProject(store: Store, now: Date, access: WorkSummaryAccess): WorkProjectCounts[];
+/** One row per task family the person may see (the Tasks list's own projection: current version, admission, unplaced
+ * work and the ceiling as the list applies them), with what the cockpit's states read (agent-state.ts): its code, whether
+ * it waits on a person, whether a lead took it on, and its live, unfinished and result runs. Every family, no page. */
+export type WorkStateRow = {
+    repo: string | null;
+    rootId: string;
+    code: string;
+    needs: boolean;
+    personNeed: boolean;
+    leadClaim: boolean;
+    liveRun: number | null;
+    unfinished: number | null;
+    resultRun: number | null;
+    /** The Tasks list ranks it as waiting its turn (custody confirmations from another computer included). */
+    waits: boolean;
+    /** What it needs now, as an identity: its code and the question, hold, result or stop it is about. A new one of
+     * these — or a changed plan or approval terms (its digests) — is a new thing to need a person, even on the same task. */
+    version: string;
+    /** When what it needs now began: the newest of its plan's proposal, its question, its hold, its result and its stop
+     * (each fixed once written, so an unrelated edit never moves it). Newer asks are named first. */
+    at: string;
+    /** The agent its ask is about: the live one, or the one whose question or decision it parked on. */
+    askRun: number | null;
+    /** Every task_ref of the family (its versions), for counting each of its live attempts. */
+    members: number[];
+};
+export declare function workStateRows(store: Store, now: Date, access: WorkSummaryAccess): WorkStateRow[];
 /** Families whose headline is Ready for review, newest first: the Tasks
  * list's own rows, so a completed family (root or any revision), a failed
  * check and a superseded version never count. */

package/dist/work-index.js

@@ -388,7 +388,7 @@ function readWorkIndexPage(store, now, access, options, taskId = null) {
     const scope = cursorScope(access, options, view), cursor = readCursor(options.cursor, scope);
     const filter = view === 'needs-you' ? 'needs=1' : view === 'running' ? 'family_running=1' : view === 'completed' ? "code='complete'" : '1';
     const rows = prepared(store, `${projection}, selected_page AS MATERIALIZED (
-    SELECT * FROM ranked WHERE ${filter} AND ($taskId IS NULL OR root_ref IN (SELECT root_ref FROM members WHERE id=$taskId)) AND ($cursorRoot=0 OR
+    SELECT * FROM ranked WHERE ${filter} AND ($taskId IS NULL OR root_ref IN (SELECT root_ref FROM members WHERE id=$taskId)) AND ($roots IS NULL OR root_id IN (SELECT value FROM json_each($roots))) AND ($cursorRoot=0 OR
       ${ORDER}>$cursorRank OR (${ORDER}=$cursorRank AND (sort_at<$cursorAt OR (sort_at=$cursorAt AND root_ref<$cursorRoot))))
     ORDER BY ${ORDER},sort_at DESC,root_ref DESC LIMIT $limit
   ), page AS (SELECT p.*,COALESCE(p.result_id,(SELECT id FROM run WHERE task_ref=p.ref_id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1)) page_result_id FROM selected_page p), totals AS (SELECT ${TOTALS},${GROUP_TOTALS} FROM ranked), project_totals AS (
@@ -415,7 +415,7 @@ function readWorkIndexPage(store, now, access, options, taskId = null) {
     'agent_ask_run',(SELECT run FROM agent_question WHERE id=page.agent_ask),'agent_ask_text',(SELECT substr(question,1,300) FROM agent_question WHERE id=page.agent_ask),'replaced_by',(SELECT successor FROM task_replacement WHERE task_ref=page.ref_id),
     'completed_by_lead',(SELECT lead FROM task_act WHERE task_ref=page.root_ref AND act='completed' ORDER BY id DESC LIMIT 1),
     'question_task',(SELECT r.external_id FROM decision d JOIN run ON run.id=d.run JOIN task_ref r ON r.id=run.task_ref WHERE d.id=page.question_id)) FROM page`)
-        .all({ ...parameters(now, access, options, custody), $taskId: taskId, $cursorRoot: cursor?.root ?? 0, $cursorRank: cursor?.rank ?? 0, $cursorAt: cursor?.at ?? '', $limit: limit + 1, $recent: new Date(now.getTime() - 86_400_000).toISOString() });
+        .all({ ...parameters(now, access, options, custody), $taskId: taskId, $roots: options.roots === undefined ? null : JSON.stringify(options.roots), $cursorRoot: cursor?.root ?? 0, $cursorRank: cursor?.rank ?? 0, $cursorAt: cursor?.at ?? '', $limit: limit + 1, $recent: new Date(now.getTime() - 86_400_000).toISOString() });
     const selected = rows.slice(1).map(row => JSON.parse(String(row['row_json'])));
     const page = selected.slice(0, limit), last = page.at(-1);
     const nextCursor = selected.length > limit && last !== undefined ? Buffer.from(JSON.stringify({ version: 2, scope,
@@ -442,6 +442,20 @@ export function workCountsByProject(store, now, access) {
         .all({ ...parameters(now, access, {}, custodyReadings(store)), $recent: new Date(now.getTime() - 86_400_000).toISOString() })
         .map(row => ({ repo: s(row, 'repo'), totals: counts(row), queued: n(row, 'queued'), doneRecently: n(row, 'done_recently') }));
 }
+export function workStateRows(store, now, access) {
+    const projection = registerValidators(store);
+    return store.handle.prepare(`${projection} SELECT repo,root_id,code,needs,person_need,lead_claim,live_run,unfinished,result_id,rank,
+      code||':'||COALESCE(question_id,'')||':'||COALESCE(agent_ask,'')||':'||COALESCE(hold_id,'')||':'||COALESCE(result_id,'')||':'||COALESCE(stop_run,'')||':'||COALESCE(digest,'')||':'||COALESCE(scope_digest,'') version,
+      COALESCE(NULLIF(MAX(COALESCE(proposed_at,''),COALESCE(finished_at,''),
+        COALESCE((SELECT created_at FROM decision WHERE id=question_id),''),COALESCE((SELECT asked_at FROM agent_question WHERE id=agent_ask),''),
+        COALESCE((SELECT held_at FROM hold WHERE id=hold_id),''),COALESCE((SELECT requested_at FROM run_stop WHERE run=stop_run),'')),''),sort_at) ask_at,
+      COALESCE(live_run,(SELECT run FROM decision WHERE id=question_id),(SELECT run FROM agent_question WHERE id=agent_ask)) ask_run,
+      (SELECT json_group_array(m.ref_id) FROM members m WHERE m.root_ref=ranked.root_ref) members FROM ranked`)
+        .all(parameters(now, access, {}, custodyReadings(store)))
+        .map(row => ({ repo: s(row, 'repo'), rootId: String(row['root_id']), code: String(row['code']), needs: n(row, 'needs') === 1, personNeed: n(row, 'person_need') === 1,
+        leadClaim: n(row, 'lead_claim') === 1, liveRun: row['live_run'] == null ? null : n(row, 'live_run'), unfinished: row['unfinished'] == null ? null : n(row, 'unfinished'),
+        resultRun: row['result_id'] == null ? null : n(row, 'result_id'), waits: Number(row['rank']) === 2, version: String(row['version']), at: String(row['ask_at'] ?? ''), askRun: row['ask_run'] == null ? null : n(row, 'ask_run'), members: JSON.parse(String(row['members'] ?? '[]')).map(Number) }));
+}
 /** Families whose headline is Ready for review, newest first: the Tasks
  * list's own rows, so a completed family (root or any revision), a failed
  * check and a superseded version never count. */

package/dist/workspace-revision.js

@@ -6,7 +6,9 @@ const MAX_AGE_MS = 60_000;
 const OMIT = new Set(['schema_version', 'service_cursor', 'wake', 'notification_delivery', 'sqlite_sequence',
     'team_read', 'team_request', 'push_delivery', 'chat_message_ref',
     // Who is watching an agent right now: renewed by every open page's keep-alive, never news.
-    'agent_view']);
+    'agent_view',
+    // A run's How it ran, derived from its own records on first view (run-efficiency.ts): a cache, never news.
+    'run_efficiency']);
 const QUIET = {
     runner: ['heartbeat_at'], claim: ['heartbeat_at', 'expires_at'], watch_lease: ['heartbeat_at', 'expires_at'],
     watch_episode: ['ticks'], provider_readiness: ['observed_at'],

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "toolroll",
-  "version": "0.9.63",
+  "version": "0.9.65",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/browser-build.mjs && node scripts/postbuild.mjs",
-    "test": "vitest run",
+    "test": "vitest run --exclude '**/*.slow.test.ts'",
+    "test:slow": "vitest run .slow.test",
+    "test:all": "vitest run",
     "test:attacks": "vitest run --config test/attacks/vitest.config.ts",
     "check:quick": "node scripts/quick-check.mjs",
     "dev": "tsx src/cli.ts",
@@ -80,6 +82,9 @@
     "@types/node": "26.6.4",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
+    "@types/ws": "8.18.2",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
     "@xyflow/react": "12.12.0",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
@@ -124,7 +129,11 @@
     "mailparser": "3.9.36",
     "nodemailer": "10.0.15",
     "typescript-parser": "npm:typescript@6.0.3",
+    "ws": "8.22.0",
     "yaml": "2.9.1",
     "zod": "^4.6.5"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "1.2.0-beta.15"
   }
 }