sakura-agent 0.1.0 → 0.1.2

package/dist/packages/plugins/review/src/chain.d.ts

@@ -1,11 +1,15 @@
-import type { Tool, ToolCall } from "../../../kernel/src/index.js";
+import type { Tool, ToolCall, Usage } from "../../../kernel/src/index.js";
 import type { Log } from "../../../kernel/src/index.js";
+/** What an authorizer may report besides its answer: the tokens it spent, and (for a refusal) that the check itself failed rather than judged. */
 export type Verdict = {
     kind: "allow";
     reason?: string;
+    usage?: Usage;
 } | {
     kind: "deny";
     reason: string;
+    technical?: true;
+    usage?: Usage;
 } | {
     kind: "pass";
 };
@@ -13,6 +17,8 @@ export interface ReviewContext {
     log: Log;
     signal: AbortSignal;
     tool(name: string): Tool | undefined;
+    /** The working directory the call runs in. Paths that leave it are not waved through as read-only. */
+    cwd?: string;
 }
 /** One link of the chain. `pass` hands the call to the next link. */
 export interface Authorizer {
@@ -23,6 +29,9 @@ export interface ChainResult {
     kind: "allow" | "deny";
     reason: string;
     decidedBy: string;
+    /** True when the check itself failed (an unreadable answer, a timeout, an exception): the action was not judged, and trying it again is fine. */
+    technical?: true;
+    usage?: Usage;
 }
 /**
  * Asks each authorizer in turn. The first answer that is not `pass` wins. The chain always ends in an answer:

package/dist/packages/plugins/review/src/chain.js

@@ -1,3 +1,4 @@
+import { describeFailure } from "../../../kernel/src/index.js";
 /**
  * Asks each authorizer in turn. The first answer that is not `pass` wins. The chain always ends in an answer:
  * if every authorizer passes (or one fails), the call is denied. An empty chain is the caller's choice to skip review.
@@ -11,14 +12,16 @@ export async function runChain(authorizers, call, context) {
         catch (error) {
             return {
                 kind: "deny",
-                reason: `The safety check '${authorizer.name}' failed (${error instanceof Error ? error.message : String(error)}), so the action was not allowed.`,
+                reason: `The safety check '${authorizer.name}' failed (${describeFailure(error)}), so the action was not allowed.`,
                 decidedBy: authorizer.name,
+                technical: true,
             };
         }
         if (verdict.kind === "allow")
-            return { kind: "allow", reason: verdict.reason ?? "allowed", decidedBy: authorizer.name };
-        if (verdict.kind === "deny")
-            return { kind: "deny", reason: verdict.reason, decidedBy: authorizer.name };
+            return { kind: "allow", reason: verdict.reason ?? "allowed", decidedBy: authorizer.name, ...(verdict.usage ? { usage: verdict.usage } : {}) };
+        if (verdict.kind === "deny") {
+            return { kind: "deny", reason: verdict.reason, decidedBy: authorizer.name, ...(verdict.technical ? { technical: true } : {}), ...(verdict.usage ? { usage: verdict.usage } : {}) };
+        }
     }
     return { kind: "deny", reason: "No safety check approved this action.", decidedBy: "end-of-chain" };
 }

package/dist/packages/plugins/review/src/hard-rules.d.ts

@@ -1,7 +1,13 @@
 import type { Authorizer } from "./chain.js";
+/** Whether a word contains a variable or command substitution, so what it stands for cannot be told from the text. */
+export declare function mayExpand(word: string): boolean;
+export declare function mayLeaveDirectory(word: string, cwd: string | undefined): boolean;
 export declare function mentionsSensitivePath(text: string): boolean;
 /**
  * Deterministic rules, no model: read-only calls are allowed, catastrophic ones are refused, everything else
  * is passed on. Reading credentials counts as sensitive and is passed on instead of allowed.
  */
+export declare function createHardRules(options?: {
+    directoryRules?: boolean;
+}): Authorizer;
 export declare const hardRules: Authorizer;

package/dist/packages/plugins/review/src/hard-rules.js

@@ -1,3 +1,4 @@
+import { posix } from "node:path";
 import { parseShell } from "./shell.js";
 const READ_ONLY = new Set([
     "ls",
@@ -88,6 +89,31 @@ const CATASTROPHIC = [
     [new RegExp(`${RUNS}(shutdown|reboot|halt|poweroff)(\\s|[);&|]|$)`), "shutting the machine down"],
     [/(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(sh|bash|zsh|dash|ksh|python3?|perl|ruby|node)\b/, "running downloaded code without looking at it"],
 ];
+/**
+ * Whether a word of a command may point outside the working directory, or cannot be told. Such a word sends a read-only call on to the
+ * next link (the reviewer) instead of waving it through. Only the text is read: a symbolic link inside the directory is not followed.
+ */
+const optionValue = (word) => (word.startsWith("-") ? (word.includes("=") ? word.slice(word.indexOf("=") + 1) : "") : word);
+/** Whether a word contains a variable or command substitution, so what it stands for cannot be told from the text. */
+export function mayExpand(word) {
+    return /[$`]/.test(optionValue(word));
+}
+export function mayLeaveDirectory(word, cwd) {
+    const value = optionValue(word);
+    if (value === "")
+        return false;
+    if (/[$`]/.test(value) || value.startsWith("~"))
+        return true;
+    if (value.startsWith("/")) {
+        if (cwd === undefined)
+            return true;
+        const root = posix.normalize(cwd).replace(/\/+$/, "");
+        const target = posix.normalize(value);
+        return !(target === root || target.startsWith(`${root}/`));
+    }
+    const target = posix.normalize(value);
+    return target === ".." || target.startsWith("../");
+}
 export function mentionsSensitivePath(text) {
     return SENSITIVE.test(text);
 }
@@ -95,29 +121,36 @@ export function mentionsSensitivePath(text) {
  * Deterministic rules, no model: read-only calls are allowed, catastrophic ones are refused, everything else
  * is passed on. Reading credentials counts as sensitive and is passed on instead of allowed.
  */
-export const hardRules = {
-    name: "hard-rules",
-    async review(call, { tool }) {
-        const args = (typeof call.args === "object" && call.args !== null ? call.args : {});
-        if (call.name === "bash" || tool(call.name)?.effect === "exec") {
-            const command = typeof args.command === "string" ? args.command : "";
-            for (const [pattern, what] of CATASTROPHIC) {
-                if (pattern.test(command))
-                    return { kind: "deny", reason: `This command looks like ${what}. It is never allowed.` };
+export function createHardRules(options = {}) {
+    const directoryRules = options.directoryRules !== false;
+    return {
+        name: "hard-rules",
+        async review(call, { tool, cwd }) {
+            const outside = (word) => (directoryRules ? mayLeaveDirectory(word, cwd) : mayExpand(word));
+            const args = (typeof call.args === "object" && call.args !== null ? call.args : {});
+            if (call.name === "bash" || tool(call.name)?.effect === "exec") {
+                const command = typeof args.command === "string" ? args.command : "";
+                for (const [pattern, what] of CATASTROPHIC) {
+                    if (pattern.test(command))
+                        return { kind: "deny", reason: `This command looks like ${what}. It is never allowed.` };
+                }
+                const parsed = parseShell(command);
+                if (parsed.complex || parsed.writesFile || parsed.commands.length === 0)
+                    return { kind: "pass" };
+                if (!parsed.commands.every(commandIsReadOnly))
+                    return { kind: "pass" };
+                if (mentionsSensitivePath(command))
+                    return { kind: "pass" };
+                if (parsed.commands.some((words) => words.slice(1).some(outside)))
+                    return { kind: "pass" };
+                return { kind: "allow", reason: "read-only command" };
             }
-            const parsed = parseShell(command);
-            if (parsed.complex || parsed.writesFile || parsed.commands.length === 0)
-                return { kind: "pass" };
-            if (!parsed.commands.every(commandIsReadOnly))
-                return { kind: "pass" };
-            if (mentionsSensitivePath(command))
-                return { kind: "pass" };
-            return { kind: "allow", reason: "read-only command" };
-        }
-        if (tool(call.name)?.effect === "read") {
-            const path = typeof args.path === "string" ? args.path : "";
-            return mentionsSensitivePath(path) ? { kind: "pass" } : { kind: "allow", reason: "read-only tool" };
-        }
-        return { kind: "pass" };
-    },
-};
+            if (tool(call.name)?.effect === "read") {
+                const path = typeof args.path === "string" ? args.path : "";
+                return mentionsSensitivePath(path) || outside(path) ? { kind: "pass" } : { kind: "allow", reason: "read-only tool" };
+            }
+            return { kind: "pass" };
+        },
+    };
+}
+export const hardRules = createHardRules();

package/dist/packages/plugins/review/src/index.d.ts

@@ -1,8 +1,10 @@
 import type { Decision, LlmClient, Log, Plugin, Tool, ToolCall } from "../../../kernel/src/index.js";
 import type { Authorizer } from "./chain.js";
 import type { PolicyInput } from "./policy.js";
+import type { ReviewerLimits } from "./reviewer.js";
 export type { Authorizer, Verdict } from "./chain.js";
 export type { PolicyInput } from "./policy.js";
+export type { ReviewerLimits } from "./reviewer.js";
 export interface BreakerOptions {
     /** Stop the run after this many refusals in a row. */
     consecutive?: number;
@@ -16,9 +18,21 @@ export interface ReviewOptions {
     /** The model that reviews. Usually the same one as the agent's. */
     llm: LlmClient;
     policy?: PolicyInput;
+    /**
+     * By default a read-only command or tool that points outside the working directory is not allowed by the hard rules but sent to the reviewer.
+     * `false` removes that rule, for an application where the agent works on the whole machine and has no working directory in that sense. The other rules
+     * stay: commands that write, expansions the text cannot show, credentials and the catastrophic patterns.
+     */
+    directoryRules?: boolean;
     /** Extra authorizers, asked after the hard rules and before the reviewer. */
     authorizers?: Authorizer[];
     timeoutMs?: number;
+    /**
+     * How big the reviewer's conversation may get and what goes into it (see ReviewerLimits; every field is optional). The conversation only grows, so the
+     * provider's cache works, until it passes `maxThreadTokens` (default 24000); then a new one starts with the goal, the project instructions, the latest
+     * user messages and a digest of the latest verdicts, which costs one cache miss. A value that is not a whole number of at least 1 throws here.
+     */
+    limits?: Partial<ReviewerLimits>;
     /** Off unless given. When it trips, refusals continue and the run is paused for the owner to look at. */
     breaker?: BreakerOptions;
 }
@@ -27,6 +41,8 @@ export interface AuthorizeContext {
     log: Log;
     signal: AbortSignal;
     tool(name: string): Tool | undefined;
+    /** The working directory the call runs in (optional; without it any absolute path counts as outside). */
+    cwd?: string;
 }
 export interface ReviewPlugin extends Plugin {
     /**
@@ -36,6 +52,11 @@ export interface ReviewPlugin extends Plugin {
     authorize(call: ToolCall, context: AuthorizeContext): Promise<Extract<Decision, {
         kind: "allow" | "deny";
     }>>;
+    /**
+     * Stops the loop from reviewing calls to this tool itself. For a tool that only runs other tools and has each of them reviewed through `authorize`
+     * (code mode's `run_code`), so one script is not reviewed twice. `createAgent` does this for code mode; a plugin wired by hand is reviewed as a whole unless told.
+     */
+    exempt(toolName: string): void;
 }
 /**
  * Automatic review of tool calls, with nobody to ask: hard rules, then any extra authorizers, then a reviewer

package/dist/packages/plugins/review/src/index.js

@@ -1,5 +1,5 @@
 import { runChain } from "./chain.js";
-import { hardRules } from "./hard-rules.js";
+import { createHardRules } from "./hard-rules.js";
 import { resolvePolicy } from "./policy.js";
 import { createReviewer } from "./reviewer.js";
 const stable = (value) => JSON.stringify(value, (_key, inner) => (inner && typeof inner === "object" && !Array.isArray(inner) ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => a.localeCompare(b))) : inner));
@@ -12,8 +12,8 @@ export function reviewPlugin(options) {
     const policy = resolvePolicy(options.policy);
     const states = new WeakMap();
     const fresh = () => ({ verdicts: new Map(), recent: [], consecutive: 0, tripped: false });
-    const reviewer = createReviewer({ llm: options.llm, policy, ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}) });
-    const chain = [hardRules, ...(options.authorizers ?? []), reviewer];
+    const reviewer = createReviewer({ llm: options.llm, policy, ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}), ...(options.limits ? { limits: options.limits } : {}) });
+    const chain = [createHardRules({ directoryRules: options.directoryRules !== false }), ...(options.authorizers ?? []), reviewer];
     function record(state, refused) {
         state.recent.push(refused);
         if (state.recent.length > (options.breaker?.window?.size ?? 50))
@@ -24,6 +24,31 @@ export function reviewPlugin(options) {
             state.tripped = true;
     }
     let emit = () => undefined;
+    const exempted = new Set();
+    /** Every decision is written to the conversation log as a `custom` entry (never shown to the model) and what the reviewer spent as a `usage` entry. */
+    async function writeRecord(log, call, result, technical, latencyMs, usage) {
+        try {
+            await log.append({
+                type: "custom",
+                customType: "review",
+                data: {
+                    callId: call.id,
+                    tool: call.name,
+                    outcome: result.kind,
+                    decidedBy: result.decidedBy,
+                    reason: result.reason,
+                    latencyMs,
+                    ...(technical ? { technical } : {}),
+                    ...(usage ? { usage } : {}),
+                },
+            });
+            if (usage && usage.input + usage.output + usage.cacheRead + usage.cacheWrite > 0)
+                await log.append({ type: "usage", kind: "review", usage });
+        }
+        catch {
+            // the decision matters more than its record; the same facts go out as a `review` event
+        }
+    }
     async function authorize(call, context) {
         const state = states.get(context.log) ?? fresh();
         states.set(context.log, state);
@@ -31,27 +56,37 @@ export function reviewPlugin(options) {
             return { kind: "deny", reason: "Too many actions were refused in this run, so further actions are blocked until the owner looks at it." };
         const key = `${call.name}\u0000${stable(call.args)}`;
         const cached = state.verdicts.get(key);
-        const result = cached ? { ...cached, decidedBy: "cache" } : await runChain(chain, call, { log: context.log, signal: context.signal, tool: context.tool });
+        const started = Date.now();
+        const result = cached
+            ? { ...cached, decidedBy: "cache" }
+            : await runChain(chain, call, { log: context.log, signal: context.signal, tool: context.tool, ...(context.cwd !== undefined ? { cwd: context.cwd } : {}) });
+        const technical = "technical" in result && result.technical === true;
         if (!cached) {
-            if (result.decidedBy === "reviewer")
+            // a failed review is not a judgement: it is not remembered, so the next try asks again
+            if (result.decidedBy === "reviewer" && !technical)
                 state.verdicts.set(key, { kind: result.kind, reason: result.reason });
             record(state, result.kind === "deny");
         }
-        emit({ kind: "review", tool: call.name, outcome: result.kind, decidedBy: result.decidedBy, reason: result.reason });
+        const usage = "usage" in result ? result.usage : undefined;
+        await writeRecord(context.log, call, result, technical, Date.now() - started, usage);
+        emit({ kind: "review", tool: call.name, callId: call.id, outcome: result.kind, decidedBy: result.decidedBy, reason: result.reason, ...(technical ? { technical } : {}) });
         if (result.kind === "allow")
             return { kind: "allow" };
+        if (technical)
+            return { kind: "deny", reason: `${result.reason} This was a failure of the review, not a decision about the action. Trying the same action again is fine; if it keeps failing, tell the user.` };
         return { kind: "deny", reason: `${result.reason} Do not try the same action again; choose another approach, or tell the user what you need.` };
     }
     return {
         name: "review",
         compensates: "models act without anyone checking the risky ones",
         authorize,
+        exempt: (toolName) => void exempted.add(toolName),
         async prepare({ log }) {
             states.set(log, fresh()); // decisions are remembered within one run only
         },
         setup(api) {
             emit = api.emit;
-            api.on("tool.before", (call, context) => authorize(call, context));
+            api.on("tool.before", (call, context) => exempted.has(call.name) ? undefined : authorize(call, { log: context.log, signal: context.signal, tool: context.tool, cwd: context.env.cwd }));
             api.on("turn.end", ({ log }) => (states.get(log)?.tripped ? { pause: "approval" } : undefined));
         },
     };

package/dist/packages/plugins/review/src/reviewer.d.ts

@@ -13,16 +13,45 @@ export interface Assessment {
 export declare function parseAssessment(text: string): Assessment | undefined;
 /** The outcome that follows from risk and authorization: low and medium pass, high needs clear authorization, critical never passes. */
 export declare function outcomeFor(risk: Risk, authorization: Authorization): "allow" | "deny";
+/** The sizes that keep the reviewer's conversation small. All are numbers of characters unless the name says tokens. */
+export interface ReviewerLimits {
+    /** When the reviewer's conversation is estimated to pass this many tokens, the next review starts a new one (default 24000). */
+    maxThreadTokens: number;
+    /** How many of the latest user messages a new conversation starts with (default 5). */
+    recentUserMessages: number;
+    /** How many of the latest earlier verdicts a new conversation starts with, one line each (default 10). */
+    digestVerdicts: number;
+    /** Cap for each user message and each tool call put into the conversation: head and tail, the middle left out (default 1200). */
+    entryChars: number;
+    /** Cap for the goal and the project instructions (default 4000). */
+    instructionChars: number;
+    /** Cap for the action under review (default 6000, head and tail). */
+    actionChars: number;
+}
+export declare const defaultReviewerLimits: ReviewerLimits;
+/** The limits with the defaults filled in; throws when one is not a positive whole number (a mistake in the definition is found at the definition). */
+export declare function resolveReviewerLimits(given?: Partial<ReviewerLimits>): ReviewerLimits;
+/** At most `max` characters: the beginning and the end, with a note of how much was left out between them. */
+export declare function shorten(text: string, max: number): string;
 /**
  * What the reviewer is told since the last time: the user's words, project instructions and goal, and the tool
  * calls the agent made. Tool results and the agent's own text are left out on purpose.
  */
-export declare function transcriptDelta(entries: readonly LogEntry[], from: number, skipCallId: string): string[];
+export declare function transcriptDelta(entries: readonly LogEntry[], from: number, skipCallId: string, limits?: ReviewerLimits): string[];
+/** One line per earlier verdict, from the `review` records in the log: the last `limit` of them, oldest first. A review that failed technically is not a verdict. */
+export declare function verdictDigest(entries: readonly LogEntry[], limit: number): string[];
+/**
+ * What a new conversation starts with: the active goal, the project instructions, the latest few user messages and the digest of the latest verdicts.
+ * Everything before is left out, and the reviewer is told so.
+ */
+export declare function seedLines(entries: readonly LogEntry[], limits: ReviewerLimits): string[];
 export interface ReviewerOptions {
     llm: LlmClient;
     policy: PolicyLists;
-    /** Default 90 seconds. A timeout counts as a refusal. */
+    /** Default 90 seconds for each try. A timeout counts as a technical failure. */
     timeoutMs?: number;
+    /** See ReviewerLimits. */
+    limits?: Partial<ReviewerLimits>;
     /** Called with every assessment, for logs and evaluation. */
     onAssessment?(info: {
         call: ToolCall;
@@ -32,7 +61,7 @@ export interface ReviewerOptions {
 }
 /**
  * A model asks "may this run?". One conversation per log is kept and only ever appended to, so the provider's
- * prompt cache keeps working. Anything unexpected (timeout, unreadable answer, error) is a refusal.
+ * prompt cache keeps working. Anything unexpected (timeout, unreadable answer, error) is tried once more and then refused, marked as a technical failure.
  */
 export declare function createReviewer(options: ReviewerOptions): Authorizer & {
     reset(log: Log): void;

package/dist/packages/plugins/review/src/reviewer.js

@@ -33,75 +33,163 @@ export function outcomeFor(risk, authorization) {
         return authorization === "high" || authorization === "medium" ? "allow" : "deny";
     return "deny";
 }
-const clip = (text, max = 2000) => (text.length > max ? `${text.slice(0, max)}… [cut]` : text);
+export const defaultReviewerLimits = { maxThreadTokens: 24_000, recentUserMessages: 5, digestVerdicts: 10, entryChars: 1200, instructionChars: 4000, actionChars: 6000 };
+/** The limits with the defaults filled in; throws when one is not a positive whole number (a mistake in the definition is found at the definition). */
+export function resolveReviewerLimits(given = {}) {
+    const limits = { ...defaultReviewerLimits };
+    for (const key of Object.keys(defaultReviewerLimits)) {
+        const value = given[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isInteger(value) || value < 1)
+            throw new RangeError(`review: ${key} must be a whole number of at least 1, got ${String(value)}`);
+        limits[key] = value;
+    }
+    return limits;
+}
+/** At most `max` characters: the beginning and the end, with a note of how much was left out between them. */
+export function shorten(text, max) {
+    if (text.length <= max)
+        return text;
+    const note = (left) => `… [${left} characters left out] …`;
+    const room = Math.max(2, max - note(text.length).length);
+    const head = Math.ceil(room / 2);
+    const tail = Math.floor(room / 2);
+    return `${text.slice(0, head)}${note(text.length - head - tail)}${text.slice(text.length - tail)}`;
+}
+const clip = shorten;
 const textOf = (content) => content.map((part) => (part.type === "text" ? part.text : part.type === "image" ? "[image]" : "")).join("");
 /**
  * What the reviewer is told since the last time: the user's words, project instructions and goal, and the tool
  * calls the agent made. Tool results and the agent's own text are left out on purpose.
  */
-export function transcriptDelta(entries, from, skipCallId) {
+export function transcriptDelta(entries, from, skipCallId, limits = defaultReviewerLimits) {
     const lines = [];
     for (const entry of entries.slice(from)) {
         if (entry.type === "custom_message") {
             const label = entry.customType === "goal" ? "goal" : entry.customType === "agents_md" ? "project instructions" : entry.customType;
-            lines.push(`[${label}] ${clip(textOf(entry.content), 6000)}`);
+            lines.push(`[${label}] ${clip(textOf(entry.content), limits.instructionChars)}`);
         }
         else if (entry.type === "message" && entry.message.role === "user") {
-            lines.push(`[user] ${clip(textOf(entry.message.content))}`);
+            lines.push(`[user] ${clip(textOf(entry.message.content), limits.entryChars)}`);
         }
         else if (entry.type === "message" && entry.message.role === "assistant") {
             for (const part of entry.message.content) {
                 if (part.type === "tool_call" && part.id !== skipCallId)
-                    lines.push(`[agent tool call] ${part.name} ${clip(JSON.stringify(part.args ?? {}))}`);
+                    lines.push(`[agent tool call] ${part.name} ${clip(JSON.stringify(part.args ?? {}), limits.entryChars)}`);
             }
         }
     }
     return lines;
 }
+/** One line per earlier verdict, from the `review` records in the log: the last `limit` of them, oldest first. A review that failed technically is not a verdict. */
+export function verdictDigest(entries, limit) {
+    const lines = [];
+    for (const entry of entries) {
+        if (entry.type !== "custom" || entry.customType !== "review")
+            continue;
+        const data = entry.data;
+        if (!data || data.technical === true || typeof data.tool !== "string" || (data.outcome !== "allow" && data.outcome !== "deny"))
+            continue;
+        const reason = typeof data.reason === "string" ? data.reason.replace(/\s+/g, " ").trim() : "";
+        lines.push(`[earlier review] ${data.tool}: ${data.outcome}${reason ? ` - ${shorten(reason, 160)}` : ""}`);
+    }
+    return lines.slice(-limit);
+}
+/**
+ * What a new conversation starts with: the active goal, the project instructions, the latest few user messages and the digest of the latest verdicts.
+ * Everything before is left out, and the reviewer is told so.
+ */
+export function seedLines(entries, limits) {
+    const withdrawn = new Set(entries.flatMap((entry) => (entry.type === "context_edit" && entry.replacement === null ? [entry.targetId] : [])));
+    const newest = (customType) => entries.findLast((entry) => entry.type === "custom_message" && entry.customType === customType && !withdrawn.has(entry.id));
+    const lines = ["(Earlier parts of the conversation are left out. What follows is the project's instructions, the goal, the latest user messages and the latest verdicts.)"];
+    const instructions = newest("agents_md");
+    const goal = newest("goal");
+    if (instructions?.type === "custom_message")
+        lines.push(`[project instructions] ${clip(textOf(instructions.content), limits.instructionChars)}`);
+    if (goal?.type === "custom_message")
+        lines.push(`[goal] ${clip(textOf(goal.content), limits.instructionChars)}`);
+    const users = entries.flatMap((entry) => (entry.type === "message" && entry.message.role === "user" ? [`[user] ${clip(textOf(entry.message.content), limits.entryChars)}`] : []));
+    lines.push(...users.slice(-limits.recentUserMessages), ...verdictDigest(entries, limits.digestVerdicts));
+    return lines;
+}
+/** The review is asked twice at most: a second try for a technical failure (timeout, error, unreadable answer). */
+const ATTEMPTS = 2;
+/** `{ usage }` when the reviewer spent any tokens, otherwise nothing. */
+const usageOf = (spent) => (spent.input + spent.output + spent.cacheRead + spent.cacheWrite > 0 ? { usage: spent } : {});
+/** Four characters to a token, as everywhere else. */
+const estimatedTokens = (texts) => Math.ceil(texts.reduce((sum, text) => sum + text.length, 0) / 4);
 const userMessage = (text) => ({ role: "user", content: [{ type: "text", text }], ts: 0 });
 /**
  * A model asks "may this run?". One conversation per log is kept and only ever appended to, so the provider's
- * prompt cache keeps working. Anything unexpected (timeout, unreadable answer, error) is a refusal.
+ * prompt cache keeps working. Anything unexpected (timeout, unreadable answer, error) is tried once more and then refused, marked as a technical failure.
  */
 export function createReviewer(options) {
     const system = reviewerSystemPrompt(options.policy);
     const timeoutMs = options.timeoutMs ?? 90_000;
+    const limits = resolveReviewerLimits(options.limits);
     const threads = new WeakMap();
     const queues = new WeakMap();
+    /** One request to the reviewer model; returns its text and adds the tokens it used to `spent`. Throws on a timeout or an error. */
+    async function ask(messages, runSignal, spent) {
+        const signal = AbortSignal.any([runSignal, AbortSignal.timeout(timeoutMs)]);
+        let answer = "";
+        for await (const event of options.llm.stream({ system, messages, tools: [], maxTokens: 1000 }, signal)) {
+            if (event.type === "text_delta")
+                answer += event.delta;
+            else if (event.type === "usage") {
+                spent.input += event.usage.input;
+                spent.output += event.usage.output;
+                spent.cacheRead += event.usage.cacheRead;
+                spent.cacheWrite += event.usage.cacheWrite;
+            }
+        }
+        return answer;
+    }
     async function review(call, context) {
         const entries = await context.log.branch();
-        const thread = threads.get(context.log) ?? { messages: [], cursor: 0 };
-        const delta = transcriptDelta(entries, thread.cursor, call.id);
-        const prompt = (delta.length > 0 ? `<context>\n${delta.join("\n")}\n</context>\n\n` : "") + `<action>\ntool: ${call.name}\narguments: ${clip(JSON.stringify(call.args ?? {}), 4000)}\n</action>`;
+        const known = threads.get(context.log) ?? { messages: [], cursor: 0 };
+        const action = `<action>\ntool: ${call.name}\narguments: ${shorten(JSON.stringify(call.args ?? {}), limits.actionChars)}\n</action>`;
+        const promptFor = (lines) => (lines.length > 0 ? `<context>\n${lines.join("\n")}\n</context>\n\n` : "") + action;
+        // The conversation only grows, so the provider's cache keeps working, until it is too big or its basis changed; then a new one starts from a seed.
+        const rewritten = entries.length < known.cursor || entries.slice(known.cursor).some((entry) => entry.type === "compaction");
+        let thread = rewritten ? { messages: [], cursor: 0 } : known;
+        let prompt = promptFor(thread.messages.length === 0 ? seedLines(entries, limits) : transcriptDelta(entries, thread.cursor, call.id, limits));
+        if (thread.messages.length > 0 && estimatedTokens([system, ...thread.messages.map((message) => textOf(message.content)), prompt]) > limits.maxThreadTokens) {
+            thread = { messages: [], cursor: 0 };
+            prompt = promptFor(seedLines(entries, limits));
+        }
         const messages = [...thread.messages, userMessage(prompt)];
+        // a technical failure is tried once more; what the attempts cost is counted either way
+        const spent = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+        let failure = "";
         let answer = "";
-        try {
-            const signal = AbortSignal.any([context.signal, AbortSignal.timeout(timeoutMs)]);
-            for await (const event of options.llm.stream({ system, messages, tools: [], maxTokens: 1000 }, signal)) {
-                if (event.type === "text_delta")
-                    answer += event.delta;
+        let assessment;
+        for (let attempt = 1; attempt <= ATTEMPTS && !assessment; attempt++) {
+            try {
+                answer = await ask(messages, context.signal, spent);
+                assessment = parseAssessment(answer);
+                if (!assessment)
+                    failure = "it gave an answer that could not be read";
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    return { kind: "deny", reason: "The run was stopped during the safety review, so the action was not allowed.", technical: true, ...usageOf(spent) };
+                const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+                failure = timedOut ? "it did not finish in time" : `it failed (${error instanceof Error ? error.message : "error"})`;
             }
         }
-        catch (error) {
-            const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
-            return {
-                kind: "deny",
-                reason: timedOut
-                    ? "The safety review did not finish in time, so the action was not allowed."
-                    : `The safety review failed (${error instanceof Error ? error.message : "error"}), so the action was not allowed.`,
-            };
-        }
-        const assessment = parseAssessment(answer);
         if (!assessment)
-            return { kind: "deny", reason: "The safety review gave an answer that could not be read, so the action was not allowed." };
+            return { kind: "deny", reason: `The safety review failed technically (${failure}, also on a second try), so the action was not judged and not allowed.`, technical: true, ...usageOf(spent) };
         // keep the conversation append-only: this exchange becomes part of the prefix of the next one
         threads.set(context.log, { messages: [...messages, { role: "assistant", content: [{ type: "text", text: answer }], ts: 0 }], cursor: entries.length });
         const computed = outcomeFor(assessment.risk_level, assessment.user_authorization);
         const outcome = computed === "deny" || assessment.outcome === "deny" ? "deny" : "allow";
         options.onAssessment?.({ call, assessment, outcome });
         return outcome === "allow"
-            ? { kind: "allow", reason: assessment.rationale || "approved by the safety review" }
-            : { kind: "deny", reason: assessment.rationale || `risk ${assessment.risk_level}, user authorization ${assessment.user_authorization}` };
+            ? { kind: "allow", reason: assessment.rationale || "approved by the safety review", ...usageOf(spent) }
+            : { kind: "deny", reason: assessment.rationale || `risk ${assessment.risk_level}, user authorization ${assessment.user_authorization}`, ...usageOf(spent) };
     }
     return {
         name: "reviewer",