sakura-agent 0.1.0 → 0.1.2

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

@@ -1,5 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { posix } from "node:path";
+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;
 /**
@@ -8,7 +11,7 @@ const CHUNK = 48_000;
  */
 export function createRemoteEnvironment(options) {
     const root = posix.resolve("/", options.cwd);
-    const workDir = posix.join(root, ".sakura", "remote");
+    const workDir = posix.resolve("/", options.workDir ?? "/tmp/.sakura-remote");
     const { run } = options;
     const resolvePath = (path) => (path.startsWith("/") ? posix.normalize(path) : posix.resolve(root, path));
     const running = new Set();
@@ -20,7 +23,8 @@ export function createRemoteEnvironment(options) {
             throw new Error(result.output.trim() || `command failed with exit code ${result.exitCode}`);
         return result.output;
     }
-    function spawn(command, spawnOptions) {
+    const killing = new Map();
+    function spawnPolled(command, spawnOptions) {
         const id = `${prefix}-${++counter}`;
         const log = posix.join(workDir, `${id}.log`);
         const codeFile = posix.join(workDir, `${id}.code`);
@@ -28,16 +32,34 @@ export function createRemoteEnvironment(options) {
         let pid = 0;
         let finished = false;
         let result;
+        let startFailure;
         const script = `cd ${quote(spawnOptions.cwd ? resolvePath(spawnOptions.cwd) : root)} || exit 1\n${command}\n`;
         const started = run(`mkdir -p ${quote(workDir)} && echo ${Buffer.from(script).toString("base64")} | base64 -d > ${quote(scriptFile)} || exit $?; ` +
             `setsid bash -c ${quote(`bash ${quote(scriptFile)} > ${quote(log)} 2>&1; echo $? > ${quote(codeFile)}`)} > /dev/null 2>&1 & echo $!`, { cwd: root }).then((outcome) => {
             if (outcome.exitCode === 0)
                 pid = Number.parseInt(outcome.output.trim().split("\n").at(-1) ?? "", 10) || 0;
+        }, (error) => {
+            if (!(error instanceof RemoteConnectionError))
+                throw error;
+            startFailure = error;
         });
+        // Stopping is done once, however often it is asked for, and can be waited for (dispose does).
         const kill = () => {
-            void started.then(() => (pid > 0 ? run(`kill -TERM -- -${pid} 2>/dev/null; sleep 1; kill -KILL -- -${pid} 2>/dev/null; true`, { cwd: root }) : undefined)).catch(() => undefined);
+            if (killing.has(handle))
+                return;
+            killing.set(handle, started
+                .then(() => (pid > 0 ? run(`kill -TERM -- -${pid} 2>/dev/null; sleep 1; kill -KILL -- -${pid} 2>/dev/null; true`, { cwd: root }) : undefined))
+                .then(() => undefined, () => undefined));
         };
         spawnOptions.signal?.addEventListener("abort", kill, { once: true });
+        /** The connection failed and nothing can be said about how the command ended: say that, and where its output is. */
+        const lost = (error, what) => {
+            finished = true;
+            running.delete(handle);
+            return error instanceof RemoteConnectionError
+                ? new RemoteConnectionError(`${what} (${error.message}). The command may still be running; its output is being written to ${log} on the remote machine.`)
+                : error;
+        };
         let done;
         const handle = {
             get pid() {
@@ -52,6 +74,11 @@ export function createRemoteEnvironment(options) {
         };
         done = (async () => {
             await started;
+            if (startFailure) {
+                finished = true;
+                running.delete(handle);
+                throw new RemoteConnectionError(`The connection to the remote machine failed while the command was being started, so it may or may not be running (${startFailure.message}). If it is, its output is being written to ${log} on the remote machine.`);
+            }
             if (pid === 0) {
                 finished = true;
                 running.delete(handle);
@@ -60,10 +87,14 @@ export function createRemoteEnvironment(options) {
             for (let attempt = 0;; attempt++) {
                 const state = await run(`if [ -f ${quote(codeFile)} ]; then cat ${quote(codeFile)}; elif kill -0 ${pid} 2>/dev/null; then echo running; else echo gone; fi`, {
                     cwd: root,
+                }).catch((error) => {
+                    throw lost(error, "The connection to the remote machine was lost while waiting for the command");
                 });
                 const text = state.output.trim();
                 if (text !== "running") {
-                    const output = await run(`cat ${quote(log)} 2>/dev/null`, { cwd: root });
+                    const output = await run(`cat ${quote(log)} 2>/dev/null`, { cwd: root }).catch((error) => {
+                        throw lost(error, "The connection to the remote machine was lost while reading the output of the command");
+                    });
                     const exitCode = /^\d+$/.test(text) ? Number(text) : null;
                     finished = true;
                     running.delete(handle);
@@ -73,11 +104,32 @@ export function createRemoteEnvironment(options) {
                 await new Promise((resolve) => setTimeout(resolve, attempt < 8 ? 250 : 1000));
             }
         })();
+        done.catch(() => undefined); // a caller that never waits must not cause an unhandled rejection
         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,
+        ...(options.description !== undefined ? { description: options.description } : {}),
         resolve: resolvePath,
         async readFile(path) {
             const output = await must(`set -o pipefail; base64 < ${quote(resolvePath(path))} | tr -d '\\n'`);
@@ -107,14 +159,25 @@ 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() {
-            for (const handle of [...running])
+            if (disposed)
+                return;
+            disposed = true;
+            const handles = [...running];
+            for (const handle of handles)
                 handle.kill();
+            await Promise.all(handles.map((handle) => killing.get(handle)));
+            // the scripts, logs and exit codes of this session are of no use to anyone afterwards
+            if (counter > 0)
+                await run(`rm -f ${quote(posix.join(workDir, `${prefix}-`))}*`, { cwd: root }).catch(() => undefined);
+            await options.close?.();
         },
     };
 }

package/dist/packages/evals/src/bfcl.d.ts

@@ -0,0 +1,24 @@
+export interface BfclFunction {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface BfclItem {
+    id: string;
+    question: Array<Array<{
+        role: string;
+        content: string;
+    }>>;
+    function: BfclFunction[];
+}
+export type GroundTruth = Array<Record<string, Record<string, unknown[]>>>;
+/** The wire tool name: BFCL names may contain dots, which tool name rules do not allow. */
+export declare const wireName: (name: string) => string;
+/** BFCL schemas use "dict", "float", "tuple" and similar; map them to JSON Schema types. */
+export declare function toJsonSchema(value: unknown): unknown;
+export interface ActualCall {
+    name: string;
+    args: Record<string, unknown>;
+}
+/** Every expected call must be matched by a different actual call (order does not matter). */
+export declare function scoreCalls(calls: ActualCall[], truth: GroundTruth): boolean;

package/dist/packages/evals/src/bfcl.js

@@ -0,0 +1,71 @@
+/*
+ * Scoring for the Berkeley Function Calling Leaderboard (Gorilla, Apache-2.0) "simple", "multiple" and
+ * "parallel" sets, in a simplified form: function names and argument values are compared; types are
+ * compared loosely. Data files live in external/bfcl (downloaded, not committed).
+ */
+/** The wire tool name: BFCL names may contain dots, which tool name rules do not allow. */
+export const wireName = (name) => name.replace(/[^A-Za-z0-9_-]/g, "_");
+/** BFCL schemas use "dict", "float", "tuple" and similar; map them to JSON Schema types. */
+export function toJsonSchema(value) {
+    if (Array.isArray(value))
+        return value.map(toJsonSchema);
+    if (typeof value !== "object" || value === null)
+        return value;
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+        if (key === "type" && typeof inner === "string") {
+            out.type = { dict: "object", float: "number", tuple: "array", any: "string", integer: "integer" }[inner] ?? inner;
+        }
+        else
+            out[key] = toJsonSchema(inner);
+    }
+    return out;
+}
+const normalizeString = (value) => value.toLowerCase().replace(/[\s,.\-_/:'"`()]/g, "");
+function valuesEqual(actual, allowed) {
+    if (typeof allowed === "number" && typeof actual === "number")
+        return Math.abs(allowed - actual) < 1e-9 * Math.max(1, Math.abs(allowed));
+    if (typeof allowed === "number" && typeof actual === "string")
+        return Number(actual) === allowed;
+    if (typeof allowed === "string" && typeof actual === "string")
+        return normalizeString(allowed) === normalizeString(actual);
+    if (typeof allowed === "string" && typeof actual === "number")
+        return normalizeString(allowed) === normalizeString(String(actual));
+    if (Array.isArray(allowed) && Array.isArray(actual))
+        return allowed.length === actual.length && allowed.every((item, index) => valuesEqual(actual[index], item));
+    if (typeof allowed === "object" && allowed && typeof actual === "object" && actual) {
+        const keys = Object.keys(allowed);
+        return keys.length === Object.keys(actual).length && keys.every((key) => valuesEqual(actual[key], allowed[key]));
+    }
+    return actual === allowed;
+}
+/** One call matches one ground-truth entry when the name matches and every argument is an allowed value. */
+function callMatches(call, truth) {
+    const [name, allowedArgs] = Object.entries(truth)[0] ?? [];
+    if (!name || !allowedArgs || wireName(name) !== call.name)
+        return false;
+    for (const [parameter, allowed] of Object.entries(allowedArgs)) {
+        const given = call.args[parameter];
+        if (given === undefined) {
+            if (allowed.includes(""))
+                continue; // optional parameter
+            return false;
+        }
+        if (!allowed.some((candidate) => valuesEqual(given, candidate)))
+            return false;
+    }
+    return Object.keys(call.args).every((parameter) => parameter in allowedArgs);
+}
+/** Every expected call must be matched by a different actual call (order does not matter). */
+export function scoreCalls(calls, truth) {
+    if (calls.length !== truth.length)
+        return false;
+    const used = new Set();
+    return truth.every((expected) => {
+        const index = calls.findIndex((call, position) => !used.has(position) && callMatches(call, expected));
+        if (index === -1)
+            return false;
+        used.add(index);
+        return true;
+    });
+}

package/dist/packages/evals/src/index.d.ts

@@ -0,0 +1,3 @@
+export { liveProviders, apiKeyFor } from "./providers.js";
+export type { LiveProvider } from "./providers.js";
+export { solidPng } from "./png.js";

package/dist/packages/evals/src/index.js

@@ -0,0 +1,2 @@
+export { liveProviders, apiKeyFor } from "./providers.js";
+export { solidPng } from "./png.js";

package/dist/packages/evals/src/png.d.ts

@@ -0,0 +1,2 @@
+/** A solid-colour PNG, used to check that a model can really see an image. */
+export declare function solidPng(width: number, height: number, [red, green, blue]: [number, number, number]): Buffer;

package/dist/packages/evals/src/png.js

@@ -0,0 +1,30 @@
+import { deflateSync } from "node:zlib";
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit++)
+            crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const out = Buffer.alloc(8 + data.length + 4);
+    out.writeUInt32BE(data.length, 0);
+    body.copy(out, 4);
+    out.writeUInt32BE(crc32(body), 8 + data.length);
+    return out;
+}
+/** A solid-colour PNG, used to check that a model can really see an image. */
+export function solidPng(width, height, [red, green, blue]) {
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header.set([8, 2, 0, 0, 0], 8);
+    const row = Buffer.alloc(1 + width * 3);
+    for (let x = 0; x < width; x++)
+        row.set([red, green, blue], 1 + x * 3);
+    const raw = Buffer.concat(Array.from({ length: height }, () => row));
+    return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk("IHDR", header), chunk("IDAT", deflateSync(raw)), chunk("IEND", Buffer.alloc(0))]);
+}

package/dist/packages/evals/src/pool.d.ts

@@ -0,0 +1,3 @@
+/** Runs async jobs with a fixed number at a time and returns their results in order. */
+export declare function mapPool<T, R>(items: readonly T[], limit: number, work: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function parseArgs(argv: string[]): Record<string, string>;

package/dist/packages/evals/src/pool.js

@@ -0,0 +1,22 @@
+/** Runs async jobs with a fixed number at a time and returns their results in order. */
+export async function mapPool(items, limit, work) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await work(items[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+export function parseArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index++) {
+        const key = argv[index];
+        if (key?.startsWith("--"))
+            args[key.slice(2)] = argv[index + 1] ?? "true";
+    }
+    return args;
+}

package/dist/packages/evals/src/providers.d.ts

@@ -0,0 +1,13 @@
+import type { ChatCompat } from "../../llm/src/index.js";
+/** The real endpoints used by live tests. Keys are read from the environment and never printed. */
+export interface LiveProvider {
+    name: string;
+    baseUrl: string;
+    keyEnv: string[];
+    model: string;
+    contextWindow: number;
+    compat: Partial<ChatCompat>;
+    headers?: Record<string, string>;
+}
+export declare const liveProviders: LiveProvider[];
+export declare function apiKeyFor(provider: LiveProvider): string | undefined;

package/dist/packages/evals/src/providers.js

@@ -0,0 +1,23 @@
+import { randomUUID } from "node:crypto";
+import { compatPresets } from "../../llm/src/index.js";
+export const liveProviders = [
+    { name: "deepseek", baseUrl: "https://api.deepseek.com", keyEnv: ["DEEPSEEK_API_KEY"], model: "deepseek-flash", contextWindow: 128_000, compat: compatPresets.deepseek },
+    { name: "kimi", baseUrl: "https://api.moonshot.cn/v1", keyEnv: ["MOONSHOT_API_KEY", "KIMI_API_KEY"], model: "kimi-k3", contextWindow: 128_000, compat: compatPresets.moonshot },
+    {
+        name: "opencode",
+        baseUrl: "https://opencode.ai/zen/go/v1",
+        keyEnv: ["OPENCODE_API_KEY"],
+        model: "deepseek-v4.1-flash",
+        contextWindow: 128_000,
+        compat: compatPresets.deepseek,
+        headers: { "x-opencode-session": randomUUID() },
+    },
+];
+export function apiKeyFor(provider) {
+    for (const name of provider.keyEnv) {
+        const value = process.env[name];
+        if (value)
+            return value;
+    }
+    return undefined;
+}

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

@@ -2,6 +2,11 @@ import type { LogEntry, Message } from "./types.js";
 export interface CompactionConfig {
     /** Compact when the context is within this many tokens of the model's window. */
     reserveTokens: number;
+    /**
+     * Compact when the free part of the window is smaller than this share of it (default 0.17, so at 83% full). The larger of this and
+     * `reserveTokens` applies. Left out or not a number between 0 and 1, it counts as 0.
+     */
+    reserveFraction?: number;
     /** Roughly how many recent tokens stay word for word after a compaction. */
     keepRecentTokens: number;
 }
@@ -10,6 +15,20 @@ export declare const defaultCompaction: CompactionConfig;
 export declare function estimateTokens(message: Message): number;
 /** Tokens in the context now: the last reported usage plus an estimate for what came after it. */
 export declare function contextTokens(messages: readonly Message[]): number;
+/** How many tokens of the window must stay free: the larger of the fixed amount and the share of the window. */
+export declare function reservedTokens(contextWindow: number, config: CompactionConfig): number;
+/** How full the conversation is, for a host that shows it. */
+export interface ContextStatus {
+    /** Tokens in the context now (see contextTokens). */
+    tokens: number;
+    /** The model's window. */
+    window: number;
+    /** What is left of the window; never below zero. */
+    free: number;
+    /** The size at which the conversation is compacted by itself; undefined when automatic compaction is off. */
+    compactAt: number | undefined;
+}
+export declare function contextStatus(messages: readonly Message[], window: number, config: CompactionConfig | undefined): ContextStatus;
 export declare function shouldCompact(messages: readonly Message[], contextWindow: number, config: CompactionConfig): boolean;
 export interface CompactionPlan {
     /** Id of the first entry that stays word for word. */
@@ -18,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

@@ -1,4 +1,4 @@
-export const defaultCompaction = { reserveTokens: 16_384, keepRecentTokens: 20_000 };
+export const defaultCompaction = { reserveTokens: 16_384, reserveFraction: 0.17, keepRecentTokens: 20_000 };
 /** A rough token count: four characters per token, a flat cost for images. */
 export function estimateTokens(message) {
     let characters = 0;
@@ -27,13 +27,25 @@ export function contextTokens(messages) {
     const base = reported ? reported.input + reported.output + reported.cacheRead + reported.cacheWrite : 0;
     return messages.slice(lastUsage + 1).reduce((sum, message) => sum + estimateTokens(message), base);
 }
+/** How many tokens of the window must stay free: the larger of the fixed amount and the share of the window. */
+export function reservedTokens(contextWindow, config) {
+    const share = config.reserveFraction;
+    const fraction = typeof share === "number" && share > 0 && share < 1 ? share : 0;
+    return Math.max(config.reserveTokens, Math.ceil(contextWindow * fraction));
+}
+export function contextStatus(messages, window, config) {
+    const tokens = contextTokens(messages);
+    return { tokens, window, free: Math.max(0, window - tokens), compactAt: config ? window - reservedTokens(window, config) : undefined };
+}
 export function shouldCompact(messages, contextWindow, config) {
-    return messages.length > 1 && contextTokens(messages) > contextWindow - config.reserveTokens;
+    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 = (() => {
@@ -57,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/kernel/src/goal.d.ts

@@ -1,4 +1,4 @@
-import type { GoalRecord } from "./types.js";
+import type { GoalRecord, Log, LogEntry } from "./types.js";
 export type ItemStatus = "done" | "todo" | "human";
 export interface ChecklistItem {
     status: ItemStatus;
@@ -24,3 +24,12 @@ export declare function judgeChecklist(items: readonly ChecklistItem[]): GoalVer
 export declare const BLOCKED_AFTER = 3;
 export declare function describeRemaining(items: readonly ChecklistItem[]): string;
 export declare const newGoal: (objective: string, verify?: string) => GoalRecord;
+/** The goal of the conversation as the log says it is now: the last goal entry on the branch. */
+export declare function currentGoal(branch: readonly LogEntry[]): GoalRecord | undefined;
+/** Starts a goal: the record, and a pinned message that tells the model about it. A goal that was there before is replaced. The one place that writes a new goal. */
+export declare function startGoal(log: Log, goal: {
+    objective: string;
+    verify?: string;
+}, statement: string): Promise<void>;
+/** Ends the goal by hand: it counts as complete and the model is no longer told about it. Does nothing when there is no goal or it has ended. */
+export declare function endGoal(log: Log): Promise<void>;

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

@@ -35,3 +35,31 @@ export const newGoal = (objective, verify) => ({
     status: "active",
     humanStreak: 0,
 });
+/** The goal of the conversation as the log says it is now: the last goal entry on the branch. */
+export function currentGoal(branch) {
+    const entry = [...branch].reverse().find((candidate) => candidate.type === "goal");
+    return entry?.type === "goal" ? entry.goal : undefined;
+}
+/** Takes the earlier "your goal is ..." messages out of the context, so the model is told about one goal only. */
+async function withdrawGoalMessages(log) {
+    const branch = await log.branch();
+    const withdrawn = new Set(branch.flatMap((entry) => (entry.type === "context_edit" ? [entry.targetId] : [])));
+    for (const entry of branch) {
+        if (entry.type === "custom_message" && entry.customType === "goal" && !withdrawn.has(entry.id))
+            await log.append({ type: "context_edit", targetId: entry.id, replacement: null });
+    }
+}
+/** Starts a goal: the record, and a pinned message that tells the model about it. A goal that was there before is replaced. The one place that writes a new goal. */
+export async function startGoal(log, goal, statement) {
+    await withdrawGoalMessages(log);
+    await log.append({ type: "goal", goal: newGoal(goal.objective, goal.verify) });
+    await log.append({ type: "custom_message", customType: "goal", pinned: true, content: [{ type: "text", text: statement }] });
+}
+/** Ends the goal by hand: it counts as complete and the model is no longer told about it. Does nothing when there is no goal or it has ended. */
+export async function endGoal(log) {
+    const goal = currentGoal(await log.branch());
+    if (!goal || goal.status === "complete")
+        return;
+    await withdrawGoalMessages(log);
+    await log.append({ type: "goal", goal: { ...goal, status: "complete", humanStreak: 0 } });
+}

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

@@ -1,5 +1,10 @@
 import type { Decision, Event, EventTransform, HookContext, LlmRequest, Message, Plugin, ProviderError, Tool, ToolCall, ToolResult, TurnInfo } from "./types.js";
 import type { PauseReason } from "./types.js";
+/**
+ * A short account of why a check failed, for the model: the first line of the message, at most 200 characters, no stack. The whole error goes to the
+ * `plugin` event for the person running the agent; the model needs enough to choose what to do next and no more.
+ */
+export declare function describeFailure(error: unknown): string;
 export type ReportFailure = (plugin: string, hook: string, error: unknown) => void;
 export interface TurnEndOutcome {
     append: Message[];

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

@@ -1,4 +1,18 @@
 import { FatalHookError } from "./types.js";
+/**
+ * A short account of why a check failed, for the model: the first line of the message, at most 200 characters, no stack. The whole error goes to the
+ * `plugin` event for the person running the agent; the model needs enough to choose what to do next and no more.
+ */
+export function describeFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const line = message
+        .split("\n")
+        .find((candidate) => candidate.trim() !== "")
+        ?.trim();
+    if (line === undefined)
+        return error instanceof Error ? error.name : "unknown error";
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}
 export function createHookSet(plugins, builtinTools, report, emitFromPlugin) {
     const registry = {
         context: [],
@@ -77,7 +91,13 @@ export function createHookSet(plugins, builtinTools, report, emitFromPlugin) {
                 }
                 catch (error) {
                     report(plugin, "tool.before", error);
-                    return { decision: { kind: "deny", reason: `The check by '${plugin}' failed, so the call was not allowed.` }, args };
+                    return {
+                        decision: {
+                            kind: "deny",
+                            reason: `The check by '${plugin}' failed (${describeFailure(error)}), so the call was not allowed. Do not simply repeat the call; choose another approach, or tell the user what you need.`,
+                        },
+                        args,
+                    };
                 }
             }
             return { decision: { kind: "allow" }, args };

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

@@ -1,6 +1,7 @@
 export * from "./types.js";
 export { COMPACTION_PREFIX } from "./constants.js";
 export { createKernel } from "./loop.js";
-export type { Kernel, KernelConfig, RunHandle, RunResult, UserInput } from "./loop.js";
-export type { CompactionConfig } from "./compaction.js";
+export { describeFailure } from "./hooks.js";
+export type { Kernel, KernelConfig, RunHandle, RunOptions, RunResult, UserInput } from "./loop.js";
+export type { CompactionConfig, ContextStatus } from "./compaction.js";
 export type { Prompts } from "./prompts.js";

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

@@ -1,3 +1,4 @@
 export * from "./types.js";
 export { COMPACTION_PREFIX } from "./constants.js";
 export { createKernel } from "./loop.js";
+export { describeFailure } from "./hooks.js";