toolroll 0.5.0

package/dist/mate-progress.js

@@ -0,0 +1,121 @@
+/** Live progress of one lead turn (chat streaming): what the lead is doing
+ * and the reply as it is written. Nothing here is durable or authoritative —
+ * the finished turn's saved message and cards remain the record. */
+/** Plain words for each tool the lead uses, as the person watching reads them. */
+const TOOL_LABELS = {
+    get_brief: "Catching up on your work",
+    get_project_context: "Reading the project",
+    get_action_status: "Checking an action",
+    get_actions: "Checking available actions",
+    get_controls: "Checking the controls",
+    get_result: "Reading the result",
+    get_diff: "Reading the changes",
+    get_check_log: "Reading the check log",
+    get_acceptance_evidence: "Checking the evidence",
+    get_result_images: "Looking at the screenshots",
+    recap: "Recapping",
+    list_repos: "Listing projects",
+    get_skills: "Checking skills",
+    get_project_tools: "Checking the project's tools",
+    get_flows: "Reading the flows",
+    get_flow_insights: "Looking at how the flows are doing",
+    get_project_knowledge: "Reading project knowledge",
+    search_project_memory: "Searching project memory",
+    get_models: "Checking the models",
+    list_tasks: "Listing tasks",
+    get_task: "Reading the task",
+    get_task_conversation: "Reading the task's conversation",
+    get_agents: "Checking the agents",
+    list_decisions: "Reading decisions",
+    get_decision: "Reading a decision",
+    queue: "Checking the queue",
+    show_control: "Finding the right control",
+};
+export function mateToolLabel(name) {
+    if (name in TOOL_LABELS)
+        return TOOL_LABELS[name];
+    return name.startsWith("propose_") ? "Preparing a card for you to confirm" : "Working";
+}
+/** The `text` of a structured answer still being written, when the answer
+ * opens with it (`{"text": "…`); null until then. Escapes are decoded, and
+ * an escape cut off at the end is left for the next chunk. */
+export function partialAnswerText(partial) {
+    const opening = /^\s*\{\s*"text"\s*:\s*"/.exec(partial);
+    if (opening === null)
+        return null;
+    const simple = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+    let out = "";
+    for (let i = opening[0].length; i < partial.length; i++) {
+        const char = partial[i];
+        if (char === '"')
+            return out;
+        if (char !== "\\") {
+            out += char;
+            continue;
+        }
+        const next = partial[i + 1];
+        if (next === undefined)
+            return out;
+        if (next in simple) {
+            out += simple[next];
+            i++;
+            continue;
+        }
+        if (next !== "u")
+            return out;
+        const hex = partial.slice(i + 2, i + 6);
+        if (!/^[0-9a-fA-F]{4}$/.test(hex))
+            return out;
+        out += String.fromCharCode(parseInt(hex, 16));
+        i += 5;
+    }
+    return out;
+}
+/** A reader for `claude -p --output-format stream-json --include-partial-messages`:
+ * follows the structured-output block and reports its text as it grows. */
+export function claudeStreamReader(onText, capBytes = 1_048_576) {
+    let pending = "";
+    let json = "";
+    let structured = false;
+    let last = "";
+    const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+    return chunk => {
+        pending += chunk;
+        if (pending.length > capBytes) {
+            pending = "";
+            return;
+        }
+        for (let newline = pending.indexOf("\n"); newline >= 0; newline = pending.indexOf("\n")) {
+            const line = pending.slice(0, newline);
+            pending = pending.slice(newline + 1);
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!record(event) || event["type"] !== "stream_event" || !record(event["event"]))
+                continue;
+            const inner = event["event"];
+            if (inner["type"] === "content_block_start") {
+                const block = inner["content_block"];
+                structured = record(block) && block["type"] === "tool_use" && block["name"] === "StructuredOutput";
+                if (structured)
+                    json = "";
+                continue;
+            }
+            const delta = inner["delta"];
+            if (inner["type"] !== "content_block_delta" || !structured || !record(delta) || delta["type"] !== "input_json_delta" || typeof delta["partial_json"] !== "string")
+                continue;
+            json += delta["partial_json"];
+            if (json.length > capBytes)
+                continue;
+            const text = partialAnswerText(json);
+            if (text !== null && text !== last) {
+                last = text;
+                onText(text);
+            }
+        }
+    };
+}

package/dist/mate-tools.d.ts

@@ -0,0 +1,94 @@
+import { type ReviewSnapshot } from "./chat-review.js";
+import type { Store, MateProposalKind, MateTurnEvidence } from "./store.js";
+import type { VerifiedApprover } from "./principal.js";
+import type { MateToolSchema } from "./converse.js";
+import { type AcceptanceCriterion } from "./scope.js";
+export declare const MATE_MAX_PROPOSALS_PER_TURN = 5;
+export type MateToolContext = {
+    store: Store;
+    who: VerifiedApprover;
+    now: Date;
+    /** Records a proposal as `drafting` under the running turn; null when the turn may draft no more. */
+    draft: (kind: MateProposalKind, payload: Record<string, unknown>) => number | null;
+    /** The step this call runs in, and which decisions were read (by get_decision) at which step —
+     * an answer may be proposed only for a decision read in an EARLIER step (v3 review, finding 6). */
+    step: number;
+    readDecisions: Map<number, number>;
+    readResults?: Map<number, {
+        step: number;
+        snapshot: ReviewSnapshot;
+    }>;
+    /** Where evidence lives, when the surface knows — a scout's report reads from here. */
+    evidenceRoot?: string;
+    /** Records the screenshots this turn selected, under the turn, for a channel that delivers files; returns how many are recorded. Absent: nothing durable is kept. */
+    /** Return the exact artifact ids reserved under this running turn, including earlier calls. */
+    selectEvidence?: (rows: readonly Omit<MateTurnEvidence, "turn" | "ordinal" | "createdAt">[]) => readonly number[];
+    /** How this surface delivers selected images: Telegram sends them as documents after the reply; every other surface shows identity only. */
+    mediaDelivery?: "documents";
+};
+export type MateToolResult = {
+    ok: true;
+    body: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+export { reportSummaryFor } from "./report-summary.js";
+export type MateViewContext = {
+    repos: readonly string[];
+    names: readonly string[];
+};
+/** Scrub one string. Exact repo paths and their basenames go first (v13: no paths, no basenames), then shapes. */
+export declare function redactForMate(text: string, view: MateViewContext): string;
+/** The choke point: every string inside a tool result, recursively, scrubbed. */
+export declare function mateView<T>(value: T, view: MateViewContext): T;
+export declare function mateViewContextFor(store: Store, who: VerifiedApprover): MateViewContext;
+/** The same text rule, for the gateway's proposals. */
+export declare function honestText(value: unknown, maxChars: number): value is string;
+export declare function readOptionalText(value: unknown, maxChars: number): string | null | undefined;
+export declare function readTouches(value: unknown): string[] | null;
+/** v39: the rubric a mate or coordinator proposal drafts — mandatory,
+ * parsed the same way every other authoring road parses one. `null` means
+ * the argument did not even parse into a non-empty rubric. */
+export declare function readAcceptanceArg(value: unknown): AcceptanceCriterion[] | null;
+export type MateTool = MateToolSchema & {
+    handle: (ctx: MateToolContext, args: Record<string, unknown>) => MateToolResult;
+};
+/** Replace every `repoIndex` with a `repo` label, recursively. */
+export declare function labelRepos<T>(value: T, label: (index: number) => string): T;
+export declare function recapOver(store: Store, repos: readonly string[], now: Date, since: string | null): Record<string, unknown>;
+export declare function decisionsOver(store: Store, repos: readonly string[], now: Date): Record<string, unknown>;
+/**
+ * One decision as a proposer may read it (mate arc v3, rule change #3):
+ * the question, each option's id, label, reversibility, and consequence —
+ * never the recap or the builder's recommendation. `repoIndex` names the
+ * task's repo for the view; a decision outside `repos` is null.
+ */
+export declare function decisionOver(store: Store, repos: readonly string[], decisionId: number, now: Date): Record<string, unknown> | null;
+export declare function queueOver(store: Store, repo: string, now: Date): Record<string, unknown>;
+export declare const ISO_STAMP_RULE: RegExp;
+/**
+ * THE AGENTS A TASK RUNS UNDER, as chat reads them (v48): the declared
+ * risk and what it means, the same one-line summary the task page and CLI
+ * print, each role's exact agent with its reasons, the standing of those
+ * agents (approved / awaiting approval / recommended), and — for a
+ * proposal — only the configured, role-valid choices an operator could
+ * pick. Nothing here is a term chat may bind on its own; every change goes
+ * through a confirmed card into the one authenticated edit transaction.
+ */
+export declare function agentsOver(store: Store, taskId: string, now: Date): Record<string, unknown> | null;
+export declare const MATE_TOOLS: MateTool[];
+/** A unified diff, file by file, with each file's added and removed lines. */
+export declare function patchFiles(patch: string): {
+    path: string;
+    added: number;
+    removed: number;
+    text: string;
+}[];
+export declare const MATE_TOOL_SCHEMAS: MateToolSchema[];
+export declare function isMateTool(name: string): boolean;
+/** Scrub every result. Only list_repos then adds validated display metadata
+ * from the same admitted project list; no user-authored result gets an exemption. */
+export declare function executeMateTool(ctx: MateToolContext, name: string, args: Record<string, unknown>, view?: MateViewContext): MateToolResult;
+/** Bytes of a serialized tool result as it will sit inside the request body. */
+export declare function toolResultBytes(text: string): number;