sakura-agent 0.1.0 → 0.1.2

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

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

@@ -5,7 +5,7 @@ export const defaultRetry = {
     baseDelayMs: 500,
     maxDelayMs: 32_000,
     maxServerDelayMs: 60_000,
-    maxStallRetries: 1,
+    maxStallRetries: 4,
     sleep: (ms, signal) => new Promise((resolve, reject) => {
         if (signal.aborted)
             return reject(Object.assign(new Error("aborted"), { name: "AbortError" }));

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/llm/src/index.js

@@ -16,8 +16,13 @@ async function* watchIdle(source, ms, cancel) {
             const stalled = new Promise((resolve) => {
                 timer = setTimeout(() => resolve("stalled"), ms);
             });
-            const result = await Promise.race([next, stalled]);
-            clearTimeout(timer);
+            let result;
+            try {
+                result = await Promise.race([next, stalled]);
+            }
+            finally {
+                clearTimeout(timer); // also when the read fails (a cancel, a broken connection): a timer left running keeps the process alive
+            }
             if (result === "stalled") {
                 cancel();
                 throw new StalledStreamError(Math.round(ms / 1000));

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

@@ -21,6 +21,7 @@ export interface ContextPlugin extends Plugin {
 /**
  * Puts project instructions (AGENTS.md) at the start of the conversation as a pinned message, once.
  * They survive compaction and are not summarised. Only the AGENTS.md name is understood; there is no
- * parent-directory search, no per-directory loading and no @path includes.
+ * parent-directory search, no per-directory loading and no @path includes. A changed file replaces the instructions after the next compaction;
+ * a file that is removed or emptied does not take them back.
  */
 export declare function contextPlugin(options?: ContextOptions): ContextPlugin;

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

@@ -13,7 +13,8 @@ async function readSource(env, source, maxBytes) {
 /**
  * Puts project instructions (AGENTS.md) at the start of the conversation as a pinned message, once.
  * They survive compaction and are not summarised. Only the AGENTS.md name is understood; there is no
- * parent-directory search, no per-directory loading and no @path includes.
+ * parent-directory search, no per-directory loading and no @path includes. A changed file replaces the instructions after the next compaction;
+ * a file that is removed or emptied does not take them back.
  */
 export function contextPlugin(options = {}) {
     const fileName = options.fileName ?? "AGENTS.md";

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

@@ -8,7 +8,10 @@ export interface Budget {
     maxTokens?: number;
     /** Stop after this much spend in the session; needs `prices`. */
     maxCostUsd?: number;
-    /** Stop a single run that has been going this long. */
+    /**
+     * Stop a single run that has been going this long. This is checked at the end of each turn, not during one: a turn that is under way (a model
+     * request, a command) finishes first, and what stops those is their own limits. So it is a budget, not a hard deadline.
+     */
     maxRunSeconds?: number;
 }
 export interface LimitsOptions extends Budget {

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

@@ -20,6 +20,9 @@ export interface RedactionPlugin extends Plugin {
  * Keeps secrets away from the model. Every request is scanned; secrets become stable placeholders, and the model's
  * reply (text and tool arguments) gets the real values back before anything runs or is saved. If scanning fails the
  * request is not sent. Off unless you add it.
+ *
+ * It protects what is sent to the model provider, not what is stored here: the log (the session file), the events and any trace keep the real values,
+ * because the tools need them and a resumed session is read from the log. Use `scrub` on anything you export or share.
  */
 export declare function redactionPlugin(options?: RedactionOptions): RedactionPlugin;
 export type { SecretRule } from "./engine.js";

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

@@ -9,6 +9,9 @@ const MAX_REMEMBERED = 5000;
  * Keeps secrets away from the model. Every request is scanned; secrets become stable placeholders, and the model's
  * reply (text and tool arguments) gets the real values back before anything runs or is saved. If scanning fails the
  * request is not sent. Off unless you add it.
+ *
+ * It protects what is sent to the model provider, not what is stored here: the log (the session file), the events and any trace keep the real values,
+ * because the tools need them and a resumed session is read from the log. Use `scrub` on anything you export or share.
  */
 export function redactionPlugin(options = {}) {
     const engine = createEngine({ ...(options.key ? { key: options.key } : {}), ...(options.rules ? { rules: options.rules } : {}) });

package/dist/packages/plugins/redaction/src/rules.gen.js

@@ -1,4 +1,4 @@
-// Generated by scripts/gen-secret-rules.py from the gitleaks rule table.
+// Generated from the gitleaks rule table.
 // gitleaks: https://github.com/gitleaks/gitleaks, MIT License, Copyright (c) 2019 Zachary Rice.
 // The licence text is in licenses/gitleaks-MIT.txt. Do not edit by hand.
 export const gitleaksRules = [