sakura-agent 0.1.1 → 0.1.2

package/dist/packages/env/src/remote-stream.js

@@ -0,0 +1,143 @@
+import { posix } from "node:path";
+import { RemoteConnectionError } from "./remote-types.js";
+const quote = (text) => `'${text.replace(/'/g, `'\\''`)}'`;
+/** Output kept from one command, as for a local one. */
+const MAX_OUTPUT_CHARS = 20_000_000;
+/** After a stop was asked for, how long the connection gets to report the end before the local child is killed. */
+const STOP_GRACE_MS = 4000;
+/** What the model sees of a command that was lost in the middle. */
+const TAIL_LINES = 20;
+/**
+ * The shell text one streamed command is sent as. It writes the script, starts it detached (own session, output into a log file, so it survives the
+ * connection and the log can be read afterwards), prints the process group id, then copies the log to its own output as the log grows. When the command
+ * has ended and the log is copied to the last byte, it prints the exit code after a marker. `wait` gives the exit code without anyone looking for it.
+ */
+export function launcherFor(options) {
+    const { id, workDir } = options;
+    const script = posix.join(workDir, `${id}.sh`);
+    const log = posix.join(workDir, `${id}.log`);
+    const stop = posix.join(workDir, `${id}.stop`);
+    const body = `cd ${quote(options.cwd)} || exit 1\n${options.command}\n`;
+    const detached = `bash ${quote(script)} > ${quote(log)} 2>&1; code=$?; exit $code`;
+    return [
+        `mkdir -p ${quote(workDir)} && echo ${Buffer.from(body).toString("base64")} | base64 -d > ${quote(script)} && : > ${quote(log)} && rm -f ${quote(stop)} || exit 126`,
+        `setsid bash -c ${quote(detached)} < /dev/null > /dev/null 2>&1 &`,
+        "main=$$ job=$!",
+        `printf '@@${id}-pid %s\\n' "$job"`,
+        // copy the log as it grows; the end is known when the stop file exists (or the shell that started this is gone) AND nothing more was written after that was seen
+        `( sent=0; while :; do ended=0; [ -e ${quote(stop)} ] && ended=1; kill -0 "$main" 2>/dev/null || ended=1; size=$(wc -c < ${quote(log)}); if [ "$size" -gt "$sent" ]; then tail -c +$((sent+1)) ${quote(log)} | head -c $((size-sent)); sent=$size; continue; fi; [ $ended = 1 ] && break; sleep 0.05; done ) &`,
+        "follower=$!",
+        'wait "$job"; code=$?',
+        `: > ${quote(stop)}`,
+        'wait "$follower"',
+        `printf '\\n@@${id}-exit %s\\n' "$code"`,
+        // the command's own code is in the line above; the child ends with 0, so that an ssh that ends with 255 can only mean that the connection failed
+        "exit 0",
+    ].join("\n");
+}
+/** `kill` text for the group of a command: ask nicely, then insist. */
+export const stopCommand = (pid) => `kill -TERM -- -${pid} 2>/dev/null; sleep 1; kill -KILL -- -${pid} 2>/dev/null; true`;
+const lastLines = (text) => text.trimEnd().split("\n").slice(-TAIL_LINES).join("\n");
+/**
+ * `spawn` for an environment that has a streamer. Each command is one child of the connection; the exit code is the end of that child's script, no
+ * file is looked at to find it; stopping a command stops its process group on the other side. When the connection is lost the command is NOT followed:
+ * it keeps running there (it is detached), and the error says that, where its output is, and that the model must stop and report it.
+ */
+export function createStreamedSpawn(deps) {
+    return (command, spawnOptions) => {
+        const id = deps.nextId();
+        const log = posix.join(deps.workDir, `${id}.log`);
+        const pidMarker = `@@${id}-pid `;
+        const exitMarker = `\n@@${id}-exit `;
+        const local = new AbortController();
+        let pid = 0;
+        let finished = false;
+        let stopRequested = false;
+        let received = "";
+        let pidSeen;
+        const pidKnown = new Promise((resolve) => {
+            pidSeen = resolve;
+        });
+        const launcher = launcherFor({ id, command, cwd: spawnOptions.cwd ? deps.resolvePath(spawnOptions.cwd) : deps.root, workDir: deps.workDir });
+        const kill = () => {
+            if (deps.killing.has(handle))
+                return;
+            stopRequested = true;
+            deps.killing.set(handle, (async () => {
+                const ended = new Promise((resolve) => void done.then(() => resolve(), () => resolve()));
+                await Promise.race([pidKnown, ended]);
+                if (pid > 0 && !finished)
+                    await deps.run(stopCommand(pid), { cwd: deps.root }).catch(() => undefined);
+                // the connection normally reports the end now; if it does not, the local child is stopped so that nobody waits for ever
+                const timer = setTimeout(() => local.abort(), STOP_GRACE_MS);
+                await ended;
+                clearTimeout(timer);
+            })());
+        };
+        spawnOptions.signal?.addEventListener("abort", kill, { once: true });
+        if (spawnOptions.signal?.aborted)
+            queueMicrotask(kill);
+        const lostMessage = (reason) => `The connection to the remote machine was lost while the command was running (${reason}). The command may still be running or may have finished; its output is being written to ${log} on the remote machine. ` +
+            "Stop here and tell the user that the connection was lost, and where that output file is. Do not reconnect or run the command again yourself." +
+            (received.trim() !== "" ? `\nLast output received:\n${lastLines(received)}` : "");
+        const handle = {
+            get pid() {
+                return pid;
+            },
+            outputFile: log,
+            wait: () => done,
+            kill,
+            get finished() {
+                return finished;
+            },
+        };
+        const done = (async () => {
+            const end = () => {
+                finished = true;
+                deps.running.delete(handle);
+            };
+            let outcome;
+            try {
+                outcome = await deps.stream(launcher, {
+                    cwd: deps.root,
+                    signal: local.signal,
+                    onData: (text) => {
+                        received += text;
+                        if (received.length > MAX_OUTPUT_CHARS)
+                            received = received.slice(received.length - MAX_OUTPUT_CHARS);
+                        if (pid === 0 && received.startsWith(pidMarker) && received.includes("\n")) {
+                            pid = Number.parseInt(received.slice(pidMarker.length, received.indexOf("\n")), 10) || 0;
+                            received = received.slice(received.indexOf("\n") + 1);
+                            pidSeen();
+                        }
+                    },
+                });
+            }
+            catch (error) {
+                end();
+                pidSeen();
+                if (!(error instanceof RemoteConnectionError))
+                    throw error;
+                throw new RemoteConnectionError(pid === 0
+                    ? `The connection to the remote machine failed while the command was being started, so it may or may not be running (${error.message}). If it is, its output is being written to ${log} on the remote machine. Stop here and tell the user.`
+                    : lostMessage(error.message));
+            }
+            end();
+            pidSeen();
+            const at = received.lastIndexOf(exitMarker);
+            const trailer = at === -1 ? undefined : /^(\d+)\n$/.exec(received.slice(at + exitMarker.length));
+            if (at !== -1 && trailer) {
+                const code = Number(trailer[1]);
+                const output = received.slice(0, at);
+                // stopped on request: the number says which signal ended it, which nobody asked about
+                return { exitCode: stopRequested && code > 128 ? null : code, output: output.length > MAX_OUTPUT_CHARS ? output.slice(output.length - MAX_OUTPUT_CHARS) : output, timedOut: false };
+            }
+            if (pid === 0)
+                return { exitCode: null, output: `the command could not be started${outcome.stderr.trim() ? `: ${outcome.stderr.trim()}` : ""}`, timedOut: false };
+            throw new RemoteConnectionError(lostMessage(outcome.stderr.trim() || `the connection ended with ${outcome.exitCode === null ? "a signal" : `exit code ${outcome.exitCode}`}`));
+        })();
+        done.catch(() => undefined); // a caller that never waits must not cause an unhandled rejection
+        deps.running.add(handle);
+        return handle;
+    };
+}

package/dist/packages/env/src/remote-types.d.ts

@@ -0,0 +1,17 @@
+import type { ExecResult } from "../../kernel/src/index.js";
+/**
+ * Thrown by a runner when it could not reach the other side, so nothing is known about whether the command ran. A command that did run and failed
+ * is not this: it is a result with its own exit code. Whoever writes a runner translates its transport's failures (ssh exits with 255, for example) into this.
+ */
+export declare class RemoteConnectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * The one thing a remote environment needs: a way to run a shell command somewhere else and get its output back.
+ * It resolves with the result of a command that ran, whatever its exit code, and rejects with a RemoteConnectionError when it could not reach the other side.
+ */
+export type RemoteRunner = (command: string, options: {
+    cwd?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}) => Promise<ExecResult>;

package/dist/packages/env/src/remote-types.js

@@ -0,0 +1,10 @@
+/**
+ * Thrown by a runner when it could not reach the other side, so nothing is known about whether the command ran. A command that did run and failed
+ * is not this: it is a result with its own exit code. Whoever writes a runner translates its transport's failures (ssh exits with 255, for example) into this.
+ */
+export class RemoteConnectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RemoteConnectionError";
+    }
+}

package/dist/packages/env/src/remote.d.ts

@@ -1,20 +1,8 @@
-import type { Environment, ExecResult } from "../../kernel/src/index.js";
-/**
- * Thrown by a runner when it could not reach the other side, so nothing is known about whether the command ran. A command that did run and failed
- * is not this: it is a result with its own exit code. Whoever writes a runner translates its transport's failures (ssh exits with 255, for example) into this.
- */
-export declare class RemoteConnectionError extends Error {
-    constructor(message: string);
-}
-/**
- * The one thing a remote environment needs: a way to run a shell command somewhere else and get its output back.
- * It resolves with the result of a command that ran, whatever its exit code, and rejects with a RemoteConnectionError when it could not reach the other side.
- */
-export type RemoteRunner = (command: string, options: {
-    cwd?: string;
-    timeoutMs?: number;
-    signal?: AbortSignal;
-}) => Promise<ExecResult>;
+import type { Environment } from "../../kernel/src/index.js";
+import type { RemoteRunner } from "./remote-types.js";
+import type { RemoteStreamer } from "./remote-stream.js";
+export { RemoteConnectionError } from "./remote-types.js";
+export type { RemoteRunner } from "./remote-types.js";
 /**
  * An environment on another machine (a container, say) reached only through `run`. Files are read and written
  * with base64 over the shell, and long commands are started detached so they can outlive a single call.
@@ -22,6 +10,11 @@ export type RemoteRunner = (command: string, options: {
 export declare function createRemoteEnvironment(options: {
     cwd: string;
     run: RemoteRunner;
+    /**
+     * Optional. With it, every command (`spawn` and `exec`) is one streamed child of the connection and its end is the end of that child; without it the
+     * environment starts commands detached through `run` and looks for their exit code from time to time, which is all a runner without a live channel can do.
+     */
+    stream?: RemoteStreamer;
     /** Called once when the environment is disposed, after its commands were stopped: close the connection the runner uses. */
     close?: () => Promise<void>;
     /** What the model is told about where its tools run (see Environment.description). */

package/dist/packages/env/src/remote.js

@@ -1,15 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { posix } from "node:path";
-/**
- * Thrown by a runner when it could not reach the other side, so nothing is known about whether the command ran. A command that did run and failed
- * is not this: it is a result with its own exit code. Whoever writes a runner translates its transport's failures (ssh exits with 255, for example) into this.
- */
-export class RemoteConnectionError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "RemoteConnectionError";
-    }
-}
+import { RemoteConnectionError } from "./remote-types.js";
+import { createStreamedSpawn } from "./remote-stream.js";
+export { RemoteConnectionError } from "./remote-types.js";
 const quote = (text) => `'${text.replace(/'/g, `'\\''`)}'`;
 const CHUNK = 48_000;
 /**
@@ -31,7 +24,7 @@ export function createRemoteEnvironment(options) {
         return result.output;
     }
     const killing = new Map();
-    function spawn(command, spawnOptions) {
+    function spawnPolled(command, spawnOptions) {
         const id = `${prefix}-${++counter}`;
         const log = posix.join(workDir, `${id}.log`);
         const codeFile = posix.join(workDir, `${id}.code`);
@@ -115,6 +108,24 @@ export function createRemoteEnvironment(options) {
         running.add(handle);
         return handle;
     }
+    const spawn = options.stream ? createStreamedSpawn({ stream: options.stream, run, root, workDir, resolvePath, nextId: () => `${prefix}-${++counter}`, running, killing }) : spawnPolled;
+    /** A command run to its end: started like any other, so stopping it (timeout, cancel) stops it on the other side too. */
+    async function execStreamed(command, execOptions) {
+        const handle = spawn(command, { ...(execOptions.cwd !== undefined ? { cwd: execOptions.cwd } : {}), ...(execOptions.signal ? { signal: execOptions.signal } : {}) });
+        let timedOut = false;
+        const timer = execOptions.timeoutMs !== undefined
+            ? setTimeout(() => {
+                timedOut = true;
+                handle.kill();
+            }, execOptions.timeoutMs)
+            : undefined;
+        try {
+            return { ...(await handle.wait()), timedOut };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     let disposed = false;
     return {
         cwd: root,
@@ -148,11 +159,13 @@ export function createRemoteEnvironment(options) {
             return output.split("\n").filter(Boolean).sort();
         },
         spawn,
-        exec: (command, execOptions) => run(command, {
-            cwd: execOptions.cwd ? resolvePath(execOptions.cwd) : root,
-            ...(execOptions.timeoutMs !== undefined ? { timeoutMs: execOptions.timeoutMs } : {}),
-            ...(execOptions.signal ? { signal: execOptions.signal } : {}),
-        }),
+        exec: (command, execOptions) => options.stream
+            ? execStreamed(command, execOptions)
+            : run(command, {
+                cwd: execOptions.cwd ? resolvePath(execOptions.cwd) : root,
+                ...(execOptions.timeoutMs !== undefined ? { timeoutMs: execOptions.timeoutMs } : {}),
+                ...(execOptions.signal ? { signal: execOptions.signal } : {}),
+            }),
         async dispose() {
             if (disposed)
                 return;

package/dist/packages/kernel/src/compaction.d.ts

@@ -37,8 +37,10 @@ export interface CompactionPlan {
     splitTurn: boolean;
 }
 /**
- * Chooses where to cut. History before the cut is summarised, the rest stays. The cut is placed at a user
- * message where possible; it is never placed on a tool result, so a call and its results stay together.
- * Returns undefined when there is nothing worth summarising.
+ * Chooses where to cut. History before the cut is summarised, the rest stays. The cut is at the newest user or
+ * assistant message that keeps at least `keepRecentTokens`, so about that much stays word for word; it does not wait for a
+ * user message, because with user messages far apart that would keep far more (or, when the user message is the only
+ * boundary, nearly everything). A cut at an assistant message splits the turn (`splitTurn`). It is never placed on a tool
+ * result, so a call and its results stay together. Returns undefined when there is nothing worth summarising.
  */
 export declare function planCompaction(branch: readonly LogEntry[], config: CompactionConfig): CompactionPlan | undefined;

package/dist/packages/kernel/src/compaction.js

@@ -41,9 +41,11 @@ export function shouldCompact(messages, contextWindow, config) {
     return messages.length > 1 && contextTokens(messages) > contextWindow - reservedTokens(contextWindow, config);
 }
 /**
- * Chooses where to cut. History before the cut is summarised, the rest stays. The cut is placed at a user
- * message where possible; it is never placed on a tool result, so a call and its results stay together.
- * Returns undefined when there is nothing worth summarising.
+ * Chooses where to cut. History before the cut is summarised, the rest stays. The cut is at the newest user or
+ * assistant message that keeps at least `keepRecentTokens`, so about that much stays word for word; it does not wait for a
+ * user message, because with user messages far apart that would keep far more (or, when the user message is the only
+ * boundary, nearly everything). A cut at an assistant message splits the turn (`splitTurn`). It is never placed on a tool
+ * result, so a call and its results stay together. Returns undefined when there is nothing worth summarising.
  */
 export function planCompaction(branch, config) {
     const start = (() => {
@@ -67,19 +69,14 @@ export function planCompaction(branch, config) {
             candidates.push({ index, tokensAfter: running, role: entry.message.role });
         }
     }
-    // candidates run from newest to oldest; the first one with enough tokens after it is where we cut,
-    // but never at the very first entry (that would summarise nothing)
+    // never at the very first entry (that would summarise nothing)
     const firstIndex = branch.findIndex((entry, index) => index >= start && entry.type === "message");
     const usable = candidates.filter((candidate) => candidate.index > firstIndex);
-    const enough = usable.filter((candidate) => candidate.tokensAfter >= config.keepRecentTokens);
-    const pool = enough.length > 0 ? enough : usable;
-    if (pool.length === 0)
-        return undefined;
-    // prefer the newest user boundary among the candidates that keep at least keepRecentTokens; otherwise
-    // the newest candidate that keeps enough; if only assistant boundaries exist the turn is split
-    const byAge = [...pool].sort((a, b) => b.index - a.index);
-    const userCut = byAge.find((candidate) => candidate.role === "user");
-    const chosen = userCut ?? byAge[0];
+    // candidates run from newest to oldest, so the first one with enough tokens after it is the newest such
+    const chosen = usable.find((candidate) => candidate.tokensAfter >= config.keepRecentTokens) ??
+        // the whole visible history is smaller than keepRecentTokens (a manual compaction of a short conversation): the newest user message, else the newest message
+        usable.find((candidate) => candidate.role === "user") ??
+        usable[0];
     if (!chosen)
         return undefined;
     const entry = branch[chosen.index];

package/dist/packages/llm/src/chat/errors.d.ts

@@ -1,6 +1,17 @@
 import { ProviderError } from "../../../kernel/src/index.js";
 /** Maps an HTTP error response to a ProviderError. */
 export declare function classifyHttpError(status: number, bodyText: string, headers: Headers): ProviderError;
+/**
+ * An error sent inside a stream that already started (the HTTP status was 200). It is classified like the same error would be as an HTTP status:
+ * the status comes from the frame's `code` or `status`, or from a bracketed number in the text ("[500] EngineCore ..."). Without a status, a type
+ * that names a server-side failure counts as overloaded; anything else stays "other" and is not retried, because a request that is wrong would be wrong again.
+ */
+export declare function classifyStreamError(error: {
+    message?: string;
+    code?: unknown;
+    status?: unknown;
+    type?: unknown;
+}): ProviderError;
 export declare const isRetryable: (error: ProviderError) => boolean;
 /** The connection is open but nothing has arrived for too long. */
 export declare class StalledStreamError extends ProviderError {

package/dist/packages/llm/src/chat/errors.js

@@ -34,6 +34,23 @@ export function classifyHttpError(status, bodyText, headers) {
         return new ProviderError("quota", message, status);
     return new ProviderError("invalid_request", message, status);
 }
+const BRACKETED_STATUS = /\[(\d{3})\]/;
+const SERVER_SIDE_TYPE = /server_error|overloaded|internal/i;
+/**
+ * An error sent inside a stream that already started (the HTTP status was 200). It is classified like the same error would be as an HTTP status:
+ * the status comes from the frame's `code` or `status`, or from a bracketed number in the text ("[500] EngineCore ..."). Without a status, a type
+ * that names a server-side failure counts as overloaded; anything else stays "other" and is not retried, because a request that is wrong would be wrong again.
+ */
+export function classifyStreamError(error) {
+    const message = error.message?.trim() || "the provider reported an error in the stream";
+    const given = Number(error.code ?? error.status);
+    const status = Number.isInteger(given) && given >= 400 && given < 600 ? given : Number(BRACKETED_STATUS.exec(message)?.[1]);
+    if (status >= 400 && status < 600)
+        return classifyHttpError(status, message, new Headers());
+    if (typeof error.type === "string" && SERVER_SIDE_TYPE.test(error.type))
+        return new ProviderError("overloaded", message);
+    return new ProviderError("other", message);
+}
 export const isRetryable = (error) => error.kind === "rate_limit" || error.kind === "overloaded" || error.kind === "network";
 /** The connection is open but nothing has arrived for too long. */
 export class StalledStreamError extends ProviderError {

package/dist/packages/llm/src/chat/stream.js

@@ -1,4 +1,5 @@
 import { ProviderError } from "../../../kernel/src/index.js";
+import { classifyStreamError } from "./errors.js";
 /** Input excludes cached tokens, so the four numbers add up to what was processed. */
 export function normalizeUsage(raw) {
     const cached = raw.prompt_cache_hit_tokens ?? raw.prompt_tokens_details?.cached_tokens ?? 0;
@@ -62,7 +63,7 @@ export async function* parseChatStream(body, compat) {
             throw new ProviderError("network", "the provider sent a malformed stream chunk");
         }
         if (chunk.error)
-            throw new ProviderError("other", chunk.error.message ?? "the provider reported an error in the stream");
+            throw classifyStreamError(chunk.error);
         if (chunk.usage)
             usage = normalizeUsage(chunk.usage);
         const choice = chunk.choices?.[0];

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";
 };
@@ -25,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

@@ -14,12 +14,14 @@ export async function runChain(authorizers, call, context) {
                 kind: "deny",
                 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/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;
@@ -25,6 +27,12 @@ export interface ReviewOptions {
     /** 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;
 }

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

@@ -12,7 +12,7 @@ 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 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);
@@ -25,6 +25,30 @@ export function reviewPlugin(options) {
     }
     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);
@@ -32,17 +56,24 @@ 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 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, callId: call.id, 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 {

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;