sakura-agent 0.1.0 → 0.1.1

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. */

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,8 +27,18 @@ 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

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";

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

@@ -1,6 +1,6 @@
-import type { CompactionConfig } from "./compaction.js";
+import type { CompactionConfig, ContextStatus } from "./compaction.js";
 import type { Prompts } from "./prompts.js";
-import type { Content, Environment, Event, LlmClient, Log, PauseReason, Plugin, RunEndReason, ThinkingLevel, Tool } from "./types.js";
+import type { Content, Environment, Event, GoalRecord, LlmClient, Log, PauseReason, Plugin, RunEndReason, ThinkingLevel, Tool, UsageTotals } from "./types.js";
 export interface KernelConfig {
     llm: LlmClient;
     env: Environment;
@@ -19,7 +19,9 @@ export interface KernelConfig {
     };
     prompts?: Partial<Prompts>;
     /** Called whenever a tool or plugin reports a change, even when no run is active, so the caller can decide to start one. */
-    onSignal?(log: Log, text: string): void;
+    onSignal?(log: Log, text: string, options?: {
+        wake?: boolean;
+    }): void;
 }
 export type UserInput = string | Content[];
 export interface RunResult {
@@ -27,6 +29,15 @@ export interface RunResult {
     pause?: PauseReason;
     error?: string;
 }
+export interface RunOptions {
+    /**
+     * Compact the history before anything else in this run, whatever its size (a person asked for it). It happens after an interrupted run has been
+     * put right and before the new input, if any, is added, so that input is not part of the summary. Without input the run ends after the compaction,
+     * unless the conversation ends with something the model has not answered. Works also when automatic compaction is off; then the defaults apply.
+     * Whether it happened shows as a `compaction` event; there is none when there was nothing worth summarising.
+     */
+    compact?: boolean;
+}
 export interface RunHandle {
     events: AsyncIterable<Event>;
     result: Promise<RunResult>;
@@ -41,11 +52,24 @@ export interface Kernel {
      * The single entry for starting, resuming and following up. The tail of the log decides what happens:
      * unanswered user input or tool results go to the model, a finished reply ends the run immediately.
      */
-    run(log: Log, input?: UserInput): RunHandle;
+    run(log: Log, input?: UserInput, options?: RunOptions): RunHandle;
     /** What the agent has not been told yet, and the background work it is still waiting for. Lets a host wake an agent that went quiet. */
     pending(log: Log): {
         signals: string[];
         watching: string[];
     };
+    /** The goal of the conversation, from the log: undefined when there never was one. */
+    goal(log: Log): Promise<GoalRecord | undefined>;
+    /** Sets the goal of the conversation, replacing an earlier one. It is checked before a run may stop. Fails while a run is active. */
+    setGoal(log: Log, goal: {
+        objective: string;
+        verify?: string;
+    }): Promise<void>;
+    /** Ends the goal: it counts as complete and is not checked any more. Fails while a run is active. */
+    clearGoal(log: Log): Promise<void>;
+    /** How full the conversation is: tokens used, the window, what is free, and where compaction starts. */
+    context(log: Log): Promise<ContextStatus>;
+    /** What the conversation has spent so far, counted from the log. */
+    usage(log: Log): Promise<UsageTotals>;
 }
 export declare function createKernel(config: KernelConfig): Kernel;

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

@@ -1,11 +1,13 @@
 import { createChannel } from "./channel.js";
-import { contextTokens, defaultCompaction, planCompaction, shouldCompact } from "./compaction.js";
-import { BLOCKED_AFTER, describeRemaining, judgeChecklist, newGoal, parseChecklist } from "./goal.js";
+import { contextStatus, contextTokens, defaultCompaction, planCompaction, shouldCompact } from "./compaction.js";
+import { usageTotals } from "./usage.js";
+import { BLOCKED_AFTER, currentGoal, describeRemaining, endGoal, judgeChecklist, parseChecklist, startGoal } from "./goal.js";
 import { defaultPrompts, fill } from "./prompts.js";
 import { createHookSet } from "./hooks.js";
 import { diffSystem, renderSystem, replaySystem } from "./system.js";
 import { ProviderError } from "./types.js";
 const CANCELLED_RESULT = "The run was cancelled before this tool finished.";
+const INTERRUPTED_NOTE = "[The user interrupted this request before it was answered.]";
 const INTERRUPTED_RESULT = "This tool was interrupted and may have partially run. Check the current state before deciding what to do.";
 const TRUNCATED_RESULT = "Your output was cut off before this tool call was complete, so it was not run. Split the work into smaller parts and try again.";
 function isAbort(error) {
@@ -25,28 +27,15 @@ async function* throughTransforms(transforms, source) {
     for (const [index, transform] of transforms.entries())
         yield* run(transform.flush(), index + 1);
 }
-function usageTotals(branch) {
-    const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, turns: 0 };
-    for (const entry of branch) {
-        const usage = entry.type === "message" ? entry.message.usage : entry.type === "usage" ? entry.usage : undefined;
-        if (entry.type === "message" && entry.message.role === "assistant")
-            totals.turns++;
-        if (!usage)
-            continue;
-        totals.input += usage.input;
-        totals.output += usage.output;
-        totals.cacheRead += usage.cacheRead;
-        totals.cacheWrite += usage.cacheWrite;
-    }
-    return totals;
-}
 function toolCallsOf(message) {
     return message.content.flatMap((part) => (part.type === "tool_call" ? [{ id: part.id, name: part.name, args: part.args }] : []));
 }
 export function createKernel(config) {
     const now = config.now ?? Date.now;
     const prompts = { ...defaultPrompts, ...config.prompts };
-    const compactionConfig = config.compaction === false ? undefined : { ...defaultCompaction, ...config.compaction };
+    // a caller who gives `reserveTokens` (and no share) gets exactly that, as before; the share is for the default
+    const given = config.compaction === false ? undefined : config.compaction;
+    const compactionConfig = config.compaction === false ? undefined : { ...defaultCompaction, ...(given?.reserveTokens !== undefined && given.reserveFraction === undefined ? { reserveFraction: 0 } : {}), ...given };
     const activeLogs = new WeakSet();
     // Plugins are set up once. Failures of their handlers are reported to the runs that are active.
     const failureReporters = new Set();
@@ -62,7 +51,7 @@ export function createKernel(config) {
             send(plugin, data);
     });
     const toolByName = new Map(hooks.tools.map((tool) => [tool.name, tool]));
-    function run(log, input) {
+    function run(log, input, runOptions = {}) {
         if (activeLogs.has(log))
             throw new Error("this log already has an active run");
         activeLogs.add(log);
@@ -85,6 +74,11 @@ export function createKernel(config) {
         async function appendMessage(message) {
             return log.append({ type: "message", message });
         }
+        /** A message from the person, added while the run goes on: the screen is told when the agent takes it. */
+        async function appendAndAnnounce(message) {
+            await appendMessage(message);
+            emit({ type: "message_end", message });
+        }
         function userMessage(content) {
             return { role: "user", content, ts: now() };
         }
@@ -109,22 +103,22 @@ export function createKernel(config) {
             systemState = replaySystem(await log.branch());
         }
         // ----- signals -----
-        const reportChange = (text) => {
+        const reportChange = (text, wake) => {
             const list = pendingSignals.get(log) ?? [];
             list.push(text);
             pendingSignals.set(log, list);
-            config.onSignal?.(log, text);
+            config.onSignal?.(log, text, wake === undefined ? undefined : { wake });
             if (!finished)
                 emit({ type: "signal", text });
         };
-        const watchWork = (label) => {
+        const watchWork = (label, options) => {
             const entry = { label };
             const set = watchedWork.get(log) ?? new Set();
             set.add(entry);
             watchedWork.set(log, set);
-            return (text) => {
+            return (text, ending) => {
                 if (set.delete(entry))
-                    reportChange(text);
+                    reportChange(text, ending?.wake ?? options?.wake);
             };
         };
         /** Tells the agent what changed, as one message in a fixed form. */
@@ -183,6 +177,13 @@ export function createKernel(config) {
             await Promise.all(parallel);
         }
         /** After a cancel or a crash: give every call without a result an error result so the log stays valid. */
+        /** A cancelled request is closed with a note, so the next message is not answered together with it. */
+        async function noteInterruption() {
+            const last = (await log.project()).at(-1);
+            if (!last || last.role === "assistant")
+                return;
+            await appendMessage({ role: "assistant", content: [{ type: "text", text: INTERRUPTED_NOTE }], ts: now(), stop: "stop" });
+        }
         async function closeOpenCalls(text) {
             const branch = await log.branch();
             const answered = new Set(branch.flatMap((entry) => (entry.type === "message" && entry.message.toolCallId ? [entry.message.toolCallId] : [])));
@@ -235,7 +236,18 @@ export function createKernel(config) {
             let truncated;
             let usage;
             let stop = "stop";
+            let announced = false;
+            const announce = () => {
+                if (announced)
+                    return;
+                announced = true;
+                emit({ type: "message_start", message: { role: "assistant", content: [], ts: now() } });
+            };
             for await (const event of throughTransforms(prepared.transforms, config.llm.stream(request, controller.signal))) {
+                if (event.type === "text_delta" || event.type === "reasoning_delta" || event.type === "provider" || event.type === "tool_call")
+                    announce();
+                if (event.type === "reasoning_delta")
+                    emit({ type: "reasoning_update", delta: event.delta });
                 if (event.type === "text_delta") {
                     text += event.delta;
                     emit({ type: "message_update", delta: { type: "text", text: event.delta } });
@@ -259,6 +271,7 @@ export function createKernel(config) {
                     truncated = undefined;
                     usage = undefined;
                     stop = "stop";
+                    announced = false;
                     emit({ type: "message_reset" });
                 }
                 else if (event.type === "done") {
@@ -273,7 +286,7 @@ export function createKernel(config) {
             if (truncated)
                 content.push({ type: "tool_call", id: truncated.id, name: truncated.name, args: {} });
             const message = { role: "assistant", content, ts: now(), stop, ...(usage ? { usage } : {}) };
-            return { message, calls, truncated };
+            return { message, calls, truncated, announced };
         }
         // ----- side requests: compaction and the goal check -----
         /** Asks the model something about the conversation without letting it act: tool calls are ignored. */
@@ -301,11 +314,12 @@ export function createKernel(config) {
             return { text, usage };
         }
         /** Replaces old history with a summary. Returns false when nothing was compacted. */
-        async function compact() {
-            if (!compactionConfig)
+        async function compact(forced = false) {
+            const settings = compactionConfig ?? (forced ? defaultCompaction : undefined);
+            if (!settings)
                 return false;
             const branch = await log.branch();
-            const plan = planCompaction(branch, compactionConfig);
+            const plan = planCompaction(branch, settings);
             if (!plan)
                 return false;
             const previous = [...branch].reverse().find((entry) => entry.type === "compaction");
@@ -330,9 +344,9 @@ export function createKernel(config) {
             return true;
         }
         /** A failed compaction must not stop the run; the caller carries on with the full context. */
-        async function tryCompact() {
+        async function tryCompact(forced = false) {
             try {
-                return await compact();
+                return await compact(forced);
             }
             catch (error) {
                 if (cancelled || isAbort(error))
@@ -341,21 +355,10 @@ export function createKernel(config) {
                 return false;
             }
         }
-        function currentGoal(branch) {
-            const entry = [...branch].reverse().find((candidate) => candidate.type === "goal");
-            return entry?.type === "goal" ? entry.goal : undefined;
-        }
         async function openGoal() {
             if (!config.goal || currentGoal(await log.branch()))
                 return;
-            const goal = newGoal(config.goal.objective, config.goal.verify);
-            await log.append({ type: "goal", goal });
-            await log.append({
-                type: "custom_message",
-                customType: "goal",
-                pinned: true,
-                content: [{ type: "text", text: fill(prompts.goalStatement, { objective: goal.objective }) }],
-            });
+            await startGoal(log, config.goal, fill(prompts.goalStatement, { objective: config.goal.objective }));
         }
         /** Runs when the agent wants to stop. Returns what the run should do next. */
         async function wrapUp() {
@@ -406,6 +409,8 @@ export function createKernel(config) {
                 await plugin.prepare?.({ log, env: config.env });
             await recover();
             await openGoal();
+            if (runOptions.compact)
+                await tryCompact(true);
             if (input !== undefined) {
                 await deliverSignals();
                 const message = userMessage(toContent(input));
@@ -421,7 +426,7 @@ export function createKernel(config) {
                 if (cancelled)
                     return { reason: "cancelled" };
                 for (const text of steered.splice(0))
-                    await appendMessage(userMessage([{ type: "text", text }]));
+                    await appendAndAnnounce(userMessage([{ type: "text", text }]));
                 let messages = await log.project();
                 if (compactionConfig && shouldCompact(messages, config.llm.model.contextWindow, compactionConfig) && (await tryCompact())) {
                     messages = await log.project();
@@ -438,7 +443,7 @@ export function createKernel(config) {
                     const next = queued.shift();
                     if (next === undefined)
                         return { reason: "done" };
-                    await appendMessage(userMessage([{ type: "text", text: next }]));
+                    await appendAndAnnounce(userMessage([{ type: "text", text: next }]));
                     continue;
                 }
                 if (await deliverSignals())
@@ -467,7 +472,8 @@ export function createKernel(config) {
                     throw error;
                 }
                 overflowRetried = false;
-                emit({ type: "message_start", message: turn.message });
+                if (!turn.announced)
+                    emit({ type: "message_start", message: turn.message });
                 await appendMessage(turn.message);
                 emit({ type: "message_end", message: turn.message });
                 if (turn.truncated) {
@@ -504,10 +510,13 @@ export function createKernel(config) {
                 outcome = await drive();
             }
             catch (error) {
-                outcome = { reason: "error", error: error instanceof Error ? error.message : String(error) };
+                // a cancel that reaches a step with no handling of its own (summarising, for one) stops the run; it is a cancel and not a failure
+                outcome = cancelled ? { reason: "cancelled" } : { reason: "error", error: error instanceof Error ? error.message : String(error) };
             }
-            if (outcome.reason === "cancelled")
+            if (outcome.reason === "cancelled") {
                 await closeOpenCalls(CANCELLED_RESULT).catch(() => undefined);
+                await noteInterruption().catch(() => undefined);
+            }
             emit({ type: "run_end", reason: outcome.reason });
             channel.end();
             failureReporters.delete(reportFailure);
@@ -529,6 +538,19 @@ export function createKernel(config) {
     }
     return {
         run,
+        goal: async (log) => currentGoal(await log.branch()),
+        setGoal: async (log, goal) => {
+            if (activeLogs.has(log))
+                throw new Error("this log already has an active run");
+            await startGoal(log, goal, fill(prompts.goalStatement, { objective: goal.objective }));
+        },
+        clearGoal: async (log) => {
+            if (activeLogs.has(log))
+                throw new Error("this log already has an active run");
+            await endGoal(log);
+        },
+        context: async (log) => contextStatus(await log.project(), config.llm.model.contextWindow, compactionConfig),
+        usage: async (log) => usageTotals(await log.branch()),
         pending: (log) => ({ signals: [...(pendingSignals.get(log) ?? [])], watching: [...(watchedWork.get(log) ?? [])].map((entry) => entry.label) }),
     };
 }

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

@@ -190,15 +190,23 @@ export interface ProcessHandle {
     pid: number;
     /** File the output is written to as it arrives. */
     outputFile: string;
-    /** Resolves when the command has finished and its output has been written. */
+    /**
+     * Resolves when the command has finished and its output has been written. Rejects only when the environment lost contact with the command and
+     * cannot say how it ended (a remote machine that stopped answering); the message says so, and where the output is being written.
+     */
     wait(): Promise<ExecResult>;
     /** Stops the command and everything it started. */
     kill(): void;
     readonly finished: boolean;
 }
-/** Where tools run. The local implementation has no sandbox; sandboxes arrive in v2. */
+/** Where tools run. The local implementation has no sandbox: to confine commands or run them elsewhere, an application supplies its own Environment. */
 export interface Environment {
     cwd: string;
+    /**
+     * What the model should know about where its tools run, when that is not simply this machine: it is put into the system prompt. A remote machine, for
+     * example, says that commands go over a connection that can fail. Left out for an environment that is just the local machine.
+     */
+    description?: string;
     resolve(path: string): string;
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array | string): Promise<void>;
@@ -227,8 +235,16 @@ export interface ToolContext {
     log: Log;
     /** Tells the agent that something changed (for example a background command finished). Delivered before its next request. */
     notify(text: string): void;
-    /** Says that something is going on in the background. Call the returned function with the text to tell the agent when it ends; until then the work counts as pending. */
-    watch(label: string): (text: string) => void;
+    /**
+     * Says that something is going on in the background. Call the returned function with the text to tell the agent when it ends; until then the work counts as pending.
+     * `wake` says whether the end should wake an agent that has gone quiet (the host decides what that means); left out, the host's own setting applies.
+     * The function that reports the end may take its own `wake`, which wins for that ending (work that was stopped because the run was cancelled should not wake the agent).
+     */
+    watch(label: string, options?: {
+        wake?: boolean;
+    }): (text: string, ending?: {
+        wake?: boolean;
+    }) => void;
 }
 export interface Tool {
     name: string;
@@ -257,6 +273,11 @@ export type Event = {
     type: "message_update";
     delta: Content;
 }
+/** A piece of the model's reasoning, while it reasons. Only for showing: it is not kept in the log and not sent again. */
+ | {
+    type: "reasoning_update";
+    delta: string;
+}
 /** The reply that was being streamed is void (the request was sent again after a dropped connection). */
  | {
     type: "message_reset";

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

@@ -0,0 +1,3 @@
+import type { LogEntry, UsageTotals } from "./types.js";
+/** Everything the session has spent, counted from the log (so it survives restarts). */
+export declare function usageTotals(branch: readonly LogEntry[]): UsageTotals;

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

@@ -0,0 +1,16 @@
+/** Everything the session has spent, counted from the log (so it survives restarts). */
+export function usageTotals(branch) {
+    const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, turns: 0 };
+    for (const entry of branch) {
+        const usage = entry.type === "message" ? entry.message.usage : entry.type === "usage" ? entry.usage : undefined;
+        if (entry.type === "message" && entry.message.role === "assistant")
+            totals.turns++;
+        if (!usage)
+            continue;
+        totals.input += usage.input;
+        totals.output += usage.output;
+        totals.cacheRead += usage.cacheRead;
+        totals.cacheWrite += usage.cacheWrite;
+    }
+    return totals;
+}

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

@@ -1,4 +1,13 @@
 import { thinkingParameters } from "./compat.js";
+/** The URL for an image, or a sentence for the model when it cannot be read (the file is gone, or it is on another machine): one bad image must not stop every later request. */
+async function imageUrl(context, ref, mediaType) {
+    try {
+        return { url: await context.resolveImage(ref, mediaType) };
+    }
+    catch (error) {
+        return { note: `[an image could not be read: ${ref} (${error instanceof Error ? error.message : String(error)})]` };
+    }
+}
 const textOf = (content) => content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("");
 async function userParts(content, context) {
     const parts = [];
@@ -7,7 +16,8 @@ async function userParts(content, context) {
             parts.push({ type: "text", text: part.text });
         else if (part.type === "image") {
             if (context.compat.images) {
-                parts.push({ type: "image_url", image_url: { url: await context.resolveImage(part.ref, part.mediaType) } });
+                const resolved = await imageUrl(context, part.ref, part.mediaType);
+                parts.push("url" in resolved ? { type: "image_url", image_url: { url: resolved.url } } : { type: "text", text: resolved.note });
             }
             else {
                 parts.push({ type: "text", text: "[an image was attached but this model cannot read images]" });
@@ -60,12 +70,20 @@ export async function toWireRequest(request, context) {
             let content = textOf(message.content);
             if (images.length > 0) {
                 if (compat.images) {
+                    let attached = 0;
                     for (const image of images) {
-                        if (image.type === "image") {
-                            pendingImages.push({ type: "image_url", image_url: { url: await context.resolveImage(image.ref, image.mediaType) } });
+                        if (image.type !== "image")
+                            continue;
+                        const resolved = await imageUrl(context, image.ref, image.mediaType);
+                        if ("url" in resolved) {
+                            pendingImages.push({ type: "image_url", image_url: { url: resolved.url } });
+                            attached++;
                         }
+                        else
+                            content = content ? `${content}\n${resolved.note}` : resolved.note;
                     }
-                    content = content ? `${content}\n(see attached image)` : "(see attached image)";
+                    if (attached > 0)
+                        content = content ? `${content}\n(see attached image)` : "(see attached image)";
                 }
                 else {
                     content = content ? `${content}\n[an image was returned but this model cannot read images]` : "[an image was returned but this model cannot read images]";

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

@@ -6,7 +6,7 @@ export interface RetryPolicy {
     maxDelayMs: number;
     /** A server-requested wait longer than this is not honoured; the error is returned instead. */
     maxServerDelayMs: number;
-    /** A stalled stream is tried again only this many times. */
+    /** A stalled stream (silence for the idle timeout) is tried again this many times; each stall costs the idle timeout, so this bounds the waiting. */
     maxStallRetries: number;
     sleep(ms: number, signal: AbortSignal): Promise<void>;
     random(): number;