sakura-agent 0.1.0 → 0.1.2

package/dist/packages/plugins/tools/src/builtin/bash.js

@@ -20,13 +20,15 @@ export function createBashTool(options = {}) {
             "A command that is still running after 120 seconds is moved to the background. You then receive its pid, the path of its output file and how to stop it. " +
             "Set `background: true` to start a server or a long job and return at once; you are told when it ends. " +
             "To wait for something, run `sleep N`; a command that starts with `sleep N` gets N extra seconds before it is moved to the background. " +
-            "Optional `timeout` (seconds) kills the command when it is reached; there is no default timeout.",
+            "Optional `timeout` (seconds) kills the command when it is reached; there is no default timeout. " +
+            "A command that runs in the background tells you when it ends, in your next turn. Set `wake: true` to be woken up for it even if you have nothing else to do by then (to act on the result when it ends), or `wake: false` if you do not need to be. If you leave it out, the application's own setting applies.",
         parameters: {
             type: "object",
             properties: {
                 command: { type: "string", description: "The shell command to run" },
                 timeout: { type: "number", description: "Kill the command after this many seconds" },
                 background: { type: "boolean", description: "Start the command and return at once, without waiting for it to end" },
+                wake: { type: "boolean", description: "For a command that runs in the background: wake you up when it ends (true), or not (false)" },
             },
             required: ["command"],
         },
@@ -37,6 +39,7 @@ export function createBashTool(options = {}) {
                 const command = requireString(args, "command");
                 const timeout = optionalNumber(args, "timeout", 0);
                 const background = optionalBoolean(args, "background") === true;
+                const wake = optionalBoolean(args, "wake");
                 const handle = env.spawn(command, { signal });
                 let timedOut = false;
                 const hardTimer = timeout !== undefined
@@ -47,21 +50,32 @@ export function createBashTool(options = {}) {
                     : undefined;
                 const soft = background ? graceMs : softLimitFor(command, softBase); // in the background it still gets a moment, so a command that fails at once is reported as a failure
                 let softTimer;
-                const raced = await Promise.race([
-                    handle.wait().then((result) => ({ background: false, result })),
-                    new Promise((resolve) => {
-                        softTimer = setTimeout(() => resolve({ background: true }), soft);
-                    }),
-                ]);
+                let raced;
+                try {
+                    raced = await Promise.race([
+                        handle.wait().then((result) => ({ background: false, result })),
+                        new Promise((resolve) => {
+                            softTimer = setTimeout(() => resolve({ background: true }), soft);
+                        }),
+                    ]);
+                }
+                catch (error) {
+                    // the environment lost contact with the command: no timer may be left running, and the model is told what happened
+                    clearTimeout(softTimer);
+                    if (hardTimer)
+                        clearTimeout(hardTimer);
+                    throw error;
+                }
                 clearTimeout(softTimer);
                 if (raced.background) {
                     // the hard timeout, if one was given, keeps running and still stops the command
                     // tell the agent when it ends, so it does not have to keep looking at the output file
-                    const ended = watch(`background command (pid ${handle.pid})`);
+                    const ended = watch(`background command (pid ${handle.pid})`, wake === undefined ? undefined : { wake });
                     void handle.wait().then((finished) => {
                         const how = finished.timedOut || timedOut ? "was stopped by its timeout" : finished.exitCode === null ? "was stopped" : `finished with exit code ${finished.exitCode}`;
-                        ended(`The background command (pid ${handle.pid}) ${how}. Its output is in ${handle.outputFile}.`);
-                    });
+                        // a command that was stopped because the run was cancelled must not start the agent again: whoever cancelled wanted it to stop
+                        ended(`The background command (pid ${handle.pid}) ${how}. Its output is in ${handle.outputFile}.`, signal.aborted ? { wake: false } : undefined);
+                    }, (error) => ended(`The background command (pid ${handle.pid}) could not be followed to its end: ${error instanceof Error ? error.message : String(error)}`));
                     const seen = await env.readFile(handle.outputFile).then((bytes) => new TextDecoder().decode(bytes), () => "");
                     const tail = foldTail(seen, { maxLines: 20, maxBytes: 4000 }).text;
                     return text((background

package/dist/packages/plugins/tools/src/builtin/image.d.ts

@@ -0,0 +1,11 @@
+/** The image formats that model APIs take. Anything else must be converted or refused before it is sent: a refused image is refused for good. */
+export declare const SENDABLE_IMAGE_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+export type ImageType = (typeof SENDABLE_IMAGE_TYPES)[number] | "image/bmp";
+/** The format a file really has, read from its first bytes (a file name proves nothing). Undefined when it is not an image we know. */
+export declare function sniffImageType(bytes: Uint8Array): ImageType | undefined;
+/**
+ * Turns an uncompressed 24-bit or 32-bit BMP (the kind programs write when they dump a frame) into a PNG. Undefined for anything else: a palette,
+ * run-length coding, 16 bits, unusual colour masks, a truncated file. The caller then tells the model the file cannot be shown. The alpha byte of a
+ * 32-bit BMP is dropped: in this form it is almost always unused (zero) and would make the picture invisible.
+ */
+export declare function bmpToPng(bytes: Uint8Array): Uint8Array | undefined;

package/dist/packages/plugins/tools/src/builtin/image.js

@@ -0,0 +1,84 @@
+import { crc32, deflateSync } from "node:zlib";
+/** The image formats that model APIs take. Anything else must be converted or refused before it is sent: a refused image is refused for good. */
+export const SENDABLE_IMAGE_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+const startsWith = (bytes, signature, at = 0) => signature.every((value, index) => bytes[at + index] === value);
+/** The format a file really has, read from its first bytes (a file name proves nothing). Undefined when it is not an image we know. */
+export function sniffImageType(bytes) {
+    if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return "image/png";
+    if (startsWith(bytes, [0xff, 0xd8, 0xff]))
+        return "image/jpeg";
+    if (startsWith(bytes, [0x47, 0x49, 0x46, 0x38]))
+        return "image/gif"; // "GIF8"
+    if (startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) && startsWith(bytes, [0x57, 0x45, 0x42, 0x50], 8))
+        return "image/webp"; // "RIFF....WEBP"
+    if (startsWith(bytes, [0x42, 0x4d]))
+        return "image/bmp"; // "BM"
+    return undefined;
+}
+/** A guard against a header that promises a picture too large to hold in memory. */
+const MAX_PIXELS = 50_000_000;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+function pngChunk(type, data) {
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    const checksum = Buffer.alloc(4);
+    checksum.writeUInt32BE(crc32(body));
+    return Buffer.concat([length, body, checksum]);
+}
+/**
+ * Turns an uncompressed 24-bit or 32-bit BMP (the kind programs write when they dump a frame) into a PNG. Undefined for anything else: a palette,
+ * run-length coding, 16 bits, unusual colour masks, a truncated file. The caller then tells the model the file cannot be shown. The alpha byte of a
+ * 32-bit BMP is dropped: in this form it is almost always unused (zero) and would make the picture invisible.
+ */
+export function bmpToPng(bytes) {
+    if (sniffImageType(bytes) !== "image/bmp" || bytes.length < 54)
+        return undefined;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const dataOffset = view.getUint32(10, true);
+    const headerSize = view.getUint32(14, true);
+    if (headerSize < 40)
+        return undefined; // the old 12-byte header is not handled
+    const width = view.getInt32(18, true);
+    const rawHeight = view.getInt32(22, true);
+    const bitsPerPixel = view.getUint16(28, true);
+    const compression = view.getUint32(30, true);
+    const height = Math.abs(rawHeight);
+    const topDown = rawHeight < 0;
+    if (width <= 0 || height === 0 || width * height > MAX_PIXELS)
+        return undefined;
+    if (bitsPerPixel !== 24 && bitsPerPixel !== 32)
+        return undefined;
+    if (compression === 3) {
+        // BI_BITFIELDS: only the usual layout (red 0x00FF0000, green 0x0000FF00, blue 0x000000FF) is understood
+        if (bitsPerPixel !== 32 || bytes.length < 66 || view.getUint32(54, true) !== 0x00ff0000 || view.getUint32(58, true) !== 0x0000ff00 || view.getUint32(62, true) !== 0x000000ff)
+            return undefined;
+    }
+    else if (compression !== 0) {
+        return undefined;
+    }
+    const bytesPerPixel = bitsPerPixel / 8;
+    const rowSize = Math.ceil((width * bitsPerPixel) / 32) * 4;
+    if (dataOffset + rowSize * height > bytes.length)
+        return undefined;
+    // PNG rows: a filter byte (0 = none) and then red, green, blue for every pixel
+    const scanline = 1 + width * 3;
+    const raw = Buffer.alloc(scanline * height);
+    for (let row = 0; row < height; row++) {
+        const source = dataOffset + (topDown ? row : height - 1 - row) * rowSize;
+        const target = row * scanline + 1;
+        for (let column = 0; column < width; column++) {
+            const pixel = source + column * bytesPerPixel;
+            raw[target + column * 3] = bytes[pixel + 2] ?? 0;
+            raw[target + column * 3 + 1] = bytes[pixel + 1] ?? 0;
+            raw[target + column * 3 + 2] = bytes[pixel] ?? 0;
+        }
+    }
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8; // bit depth
+    header[9] = 2; // colour type: truecolour
+    return new Uint8Array(Buffer.concat([PNG_SIGNATURE, pngChunk("IHDR", header), pngChunk("IDAT", deflateSync(raw)), pngChunk("IEND", Buffer.alloc(0))]));
+}

package/dist/packages/plugins/tools/src/builtin/read.js

@@ -1,14 +1,23 @@
 import { DEFAULT_FOLD, foldHead } from "../fold.js";
 import { ArgumentError, optionalInteger, requireString } from "./args.js";
-const IMAGE_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".bmp": "image/bmp" };
+import { bmpToPng, SENDABLE_IMAGE_TYPES, sniffImageType } from "./image.js";
+/** File names that say "this is a picture". What the file really is, is decided by its first bytes (image.ts). */
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"]);
+const CONVERTED_DIRECTORY = ".sakura/artifacts";
 const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
 const ok = (text) => ({ content: [{ type: "text", text }] });
+const imageResult = (mediaType, ref, note = "") => ({
+    content: [
+        { type: "text", text: `Read image file [${mediaType}]${note ? ` (${note})` : ""}` },
+        { type: "image", mediaType, ref },
+    ],
+});
 /*
  * Description adapted from Pi's read tool (MIT, Copyright (c) 2025 Mario Zechner; see THIRD_PARTY_NOTICES.md).
  */
 export const readTool = {
     name: "read",
-    description: "Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp); images are sent as attachments. " +
+    description: "Read the contents of a file. Supports text files and images (jpg, png, gif, webp; a plain bmp is converted to png); images are sent as attachments. " +
         "For text files, output is truncated to the first 2000 lines or 50KB, whichever is hit first. " +
         "Use offset and limit for large files, and continue with offset until you have the whole file.",
     parameters: {
@@ -21,7 +30,7 @@ export const readTool = {
         required: ["path"],
     },
     effect: "read",
-    async execute(args, { env }) {
+    async execute(args, { env, callId }) {
         try {
             const path = requireString(args, "path");
             const offset = optionalInteger(args, "offset", 1);
@@ -33,16 +42,21 @@ export const readTool = {
             if (info.isDirectory)
                 return fail(`${path} is a directory, not a file.`);
             const extension = absolute.slice(absolute.lastIndexOf(".")).toLowerCase();
-            const mediaType = IMAGE_TYPES[extension];
-            if (mediaType) {
-                return {
-                    content: [
-                        { type: "text", text: `Read image file [${mediaType}]` },
-                        { type: "image", mediaType, ref: absolute },
-                    ],
-                };
-            }
             const bytes = await env.readFile(absolute);
+            if (IMAGE_EXTENSIONS.has(extension)) {
+                const type = sniffImageType(bytes);
+                if (type && SENDABLE_IMAGE_TYPES.includes(type))
+                    return imageResult(type, absolute);
+                if (type === "image/bmp") {
+                    const png = bmpToPng(bytes);
+                    if (!png)
+                        return fail(`${path} is a BMP image in a form this tool cannot convert, and the model API does not accept BMP. Convert it to PNG with a command (for example ImageMagick: magick ${path} out.png) and read the PNG.`);
+                    const converted = `${CONVERTED_DIRECTORY}/read-${callId.replace(/[^A-Za-z0-9_.-]/g, "_")}.png`;
+                    await env.writeFile(converted, png);
+                    return imageResult("image/png", env.resolve(converted), `converted from BMP to PNG, original ${path}`);
+                }
+                // a name that says picture, bytes that are not one: shown as the binary or text file it is
+            }
             if (bytes.subarray(0, 8000).includes(0))
                 return fail(`${path} looks like a binary file and cannot be shown as text.`);
             const text = new TextDecoder().decode(bytes);

package/dist/packages/plugins/toolset/src/codemode.d.ts

@@ -7,6 +7,7 @@ export type Authorize = (call: ToolCall, context: {
     log: Log;
     signal: AbortSignal;
     tool(name: string): Tool | undefined;
+    cwd?: string;
 }) => Promise<{
     kind: "allow";
 } | {
@@ -16,21 +17,31 @@ export type Authorize = (call: ToolCall, context: {
 export interface CodemodeOptions {
     /** The tools the script can call as `tools.<name>(args)`. */
     catalog: Tool[];
-    /** Tools with these effects can be called from a script (default: only "read"). Others raise an error inside the script. */
+    /** Tools with these effects can be called from a script (default: all of them). Others raise an error inside the script. */
     allowEffects?: ToolEffect[];
-    /** Asked before every tool call a script makes, as the loop's hooks cannot see them. A refusal raises an error inside the script. Without it, only the effect rule above protects. */
+    /** Asked before every tool call a script makes, as the loop's hooks cannot see them. A refusal raises an error inside the script. Without it, every allowed call simply runs. */
     authorize?: Authorize;
-    /** The script is stopped after this long (default 10 seconds). */
+    /**
+     * The script is stopped after running this long (default 10 seconds). This is the script's own time: time spent running JavaScript, and time spent
+     * waiting while no tool call is under way. Time spent waiting for a tool call does not count, because tools have limits of their own.
+     */
     timeoutMs?: number;
-    /** Memory limit of the sandbox in bytes (default 64 MB). */
+    /** A limit on the whole run of the script, tool calls included. Not set by default. */
+    totalTimeoutMs?: number;
+    /** Memory limit of the script runtime in bytes (default 64 MB). */
     memoryBytes?: number;
     /** Longest text returned to the model, in characters; the middle is cut (default 20000). */
     maxOutputChars?: number;
 }
+/** The name of the tool that runs a script. Whoever needs to refer to it takes it from here. */
+export declare const CODEMODE_TOOL = "run_code";
 /**
  * Lets the model write one JavaScript program that calls tools, instead of one call per request. The program runs in QuickJS
  * (WebAssembly), which has no access to the machine: only the tools in the catalog, and only those whose effect is allowed.
- * Calls made from the script do not pass through the hooks of the loop. Two things stand in for them: only read-only tools are allowed by default,
- * and `authorize` (for example the review plugin's) is asked before each call.
+ * Calls made from the script do not pass through the hooks of the loop, so `authorize` (for example the review plugin's) is asked
+ * before each call. With no `authorize`, every call runs, as a direct call would with no review installed.
+ *
+ * The runtime only keeps the script itself away from the machine. The tools it calls (a shell command, a file write, an MCP tool) run outside the
+ * runtime with their full power, so a call from a script is exactly as risky as the same call made directly, and needs the same review.
  */
 export declare function codemodePlugin(options: CodemodeOptions): Plugin;

package/dist/packages/plugins/toolset/src/codemode.js

@@ -1,5 +1,7 @@
 import { getQuickJS } from "quickjs-emscripten";
-const DESCRIPTION = "Runs a short JavaScript program in a sandbox (no files, no network, no timers) and returns what it prints and returns. " +
+/** The name of the tool that runs a script. Whoever needs to refer to it takes it from here. */
+export const CODEMODE_TOOL = "run_code";
+const DESCRIPTION = "Runs a short JavaScript program in an isolated runtime (no files, no network, no timers) and returns what it prints and returns. " +
     "Inside the program, `tools.<name>(args)` calls a tool and returns a promise of its text; use `await`. `console.log` output is returned. " +
     "Use it to combine several tool calls or to process their results without sending everything through the conversation. Available tools: ";
 const PRELUDE = `
@@ -10,7 +12,7 @@ globalThis.tools = new Proxy({}, { get: (_t, name) => async (args) => {
 } });
 globalThis.console = { log: (...parts) => __print(parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")) };
 `;
-/** Deeper than this, the host's own stack overflows before the sandbox notices, which aborts the whole WebAssembly module; 256 KB still allows recursion about 1500 deep. */
+/** Deeper than this, the host's own stack overflows before the runtime notices, which aborts the whole WebAssembly module; 256 KB still allows recursion about 1500 deep. */
 const STACK_BYTES = 256 * 1024;
 const text = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...(isError ? { isError } : {}) });
 const textOfContent = (content) => content.map((part) => (part.type === "text" ? part.text : `[${part.type}]`)).join("\n");
@@ -23,11 +25,14 @@ function cut(value, limit) {
 /**
  * Lets the model write one JavaScript program that calls tools, instead of one call per request. The program runs in QuickJS
  * (WebAssembly), which has no access to the machine: only the tools in the catalog, and only those whose effect is allowed.
- * Calls made from the script do not pass through the hooks of the loop. Two things stand in for them: only read-only tools are allowed by default,
- * and `authorize` (for example the review plugin's) is asked before each call.
+ * Calls made from the script do not pass through the hooks of the loop, so `authorize` (for example the review plugin's) is asked
+ * before each call. With no `authorize`, every call runs, as a direct call would with no review installed.
+ *
+ * The runtime only keeps the script itself away from the machine. The tools it calls (a shell command, a file write, an MCP tool) run outside the
+ * runtime with their full power, so a call from a script is exactly as risky as the same call made directly, and needs the same review.
  */
 export function codemodePlugin(options) {
-    const allowed = new Set(options.allowEffects ?? ["read"]);
+    const allowed = new Set(options.allowEffects ?? ["read", "write", "exec", "network", "irreversible"]);
     const byName = new Map(options.catalog.map((tool) => [tool.name, tool]));
     const timeoutMs = options.timeoutMs ?? 10_000;
     const memoryBytes = options.memoryBytes ?? 64 * 1024 * 1024;
@@ -42,7 +47,7 @@ export function codemodePlugin(options) {
         try {
             const args = JSON.parse(rawArgs);
             if (options.authorize) {
-                const decision = await options.authorize({ id: `${context.callId}/${++calls}`, name, args }, { log: context.log, signal: context.signal, tool: (wanted) => byName.get(wanted) });
+                const decision = await options.authorize({ id: `${context.callId}/${++calls}`, name, args }, { log: context.log, signal: context.signal, tool: (wanted) => byName.get(wanted), ...(context.env?.cwd !== undefined ? { cwd: context.env.cwd } : {}) });
                 if (decision.kind === "deny")
                     return JSON.stringify({ error: decision.reason });
             }
@@ -55,7 +60,7 @@ export function codemodePlugin(options) {
         }
     }
     const runCode = {
-        name: "run_code",
+        name: CODEMODE_TOOL,
         description: DESCRIPTION + options.catalog.map((tool) => tool.name).join(", "),
         parameters: { type: "object", properties: { code: { type: "string", description: "The body of an async function; use `return` for the result" } }, required: ["code"] },
         effect: "exec",
@@ -68,13 +73,45 @@ export function codemodePlugin(options) {
             const runtime = QuickJS.newRuntime();
             runtime.setMemoryLimit(memoryBytes);
             runtime.setMaxStackSize(STACK_BYTES);
-            const deadline = Date.now() + timeoutMs;
-            runtime.setInterruptHandler(() => Date.now() > deadline || context.signal.aborted);
+            // The script's own time is the time spent inside the runtime plus the time spent waiting while no tool call is under way.
+            // Waiting for a tool call is not counted, but a loop that runs while a call is under way is (it is counted as it runs).
+            const startedAt = Date.now();
+            let insideMs = 0;
+            let idleMs = 0;
+            let sliceStart = 0;
+            const used = () => insideMs + idleMs + (sliceStart > 0 ? Date.now() - sliceStart : 0);
+            const inRuntime = (work) => {
+                if (sliceStart > 0)
+                    return work();
+                sliceStart = Date.now();
+                try {
+                    return work();
+                }
+                finally {
+                    insideMs += Date.now() - sliceStart;
+                    sliceStart = 0;
+                }
+            };
+            const overTotal = () => options.totalTimeoutMs !== undefined && Date.now() - startedAt > options.totalTimeoutMs;
+            runtime.setInterruptHandler(() => used() > timeoutMs || overTotal() || context.signal.aborted);
             const vm = runtime.newContext();
             const printed = [];
-            const pending = [];
+            const unsettled = new Set(); // the calls that have not come back yet; the wait below must not include the ones that have, or it would not wait
             const handles = [];
             const deferreds = [];
+            // The calls that have not returned. Each has its own signal, joined to the run's: cancelling the run stops them all, and when the script
+            // ends the ones still under way are stopped. A call that has returned (a background command, say) is left to the run.
+            const underway = new Set();
+            const failure = (message) => text(printed.length > 0 ? cut(`${printed.join("\n")}\n${message}`, maxOutput) : message, true);
+            const late = () => {
+                if (context.signal.aborted)
+                    return "The script was cancelled."; // the calls it was waiting for were stopped with the run, so the script may report their errors instead
+                if (used() > timeoutMs)
+                    return `The script took longer than ${seconds(timeoutMs)} seconds and was stopped.`;
+                if (overTotal())
+                    return `The script took longer than ${seconds(options.totalTimeoutMs ?? 0)} seconds in total and was stopped.`;
+                return undefined;
+            };
             try {
                 const print = vm.newFunction("__print", (line) => {
                     printed.push(vm.getString(line));
@@ -86,54 +123,71 @@ export function codemodePlugin(options) {
                     deferreds.push(promise);
                     const name = vm.getString(nameHandle);
                     const rawArgs = vm.getString(argsHandle);
-                    const work = callTool(name, rawArgs, context).then((reply) => {
+                    const controller = new AbortController();
+                    const stop = () => controller.abort();
+                    if (context.signal.aborted)
+                        stop();
+                    else
+                        context.signal.addEventListener("abort", stop, { once: true }); // stays joined after the call returns, so a background command it started is still stopped with the run
+                    underway.add(controller);
+                    const work = callTool(name, rawArgs, { ...context, signal: controller.signal })
+                        .then((reply) => {
                         if (!vm.alive)
                             return;
                         const value = vm.newString(reply);
                         promise.resolve(value);
                         value.dispose();
+                    })
+                        .catch(() => undefined)
+                        .finally(() => {
+                        underway.delete(controller);
+                        unsettled.delete(work);
                     });
-                    pending.push(work);
+                    unsettled.add(work);
                     void promise.settled
                         .then(() => {
                         if (runtime.alive)
-                            runtime.executePendingJobs(); // the script may be over and the sandbox gone by now
+                            inRuntime(() => runtime.executePendingJobs()); // the script may be over and the runtime gone by now
                     })
                         .catch(() => undefined);
                     return promise.handle;
                 });
                 vm.setProp(vm.global, "__callTool", call);
                 call.dispose();
-                const prelude = vm.evalCode(PRELUDE);
+                const prelude = inRuntime(() => vm.evalCode(PRELUDE));
                 if (prelude.error) {
                     prelude.error.dispose();
-                    return text("The sandbox could not start.", true);
+                    return text("The script runtime could not start.", true);
                 }
                 prelude.value.dispose();
-                const evaluated = vm.evalCode(`(async () => {\n${code}\n})()`);
+                const evaluated = inRuntime(() => vm.evalCode(`(async () => {\n${code}\n})()`));
                 if (evaluated.error) {
                     const message = vm.dump(evaluated.error);
                     evaluated.error.dispose();
-                    return text(`Script error: ${formatError(message)}`, true);
+                    return failure(late() ?? `Script error: ${formatError(message)}`);
                 }
                 handles.push(evaluated.value);
-                runtime.executePendingJobs();
+                inRuntime(() => runtime.executePendingJobs());
                 // the script is done when its promise settles; tool calls it started finish in between
                 let state = vm.getPromiseState(evaluated.value);
+                let tick = Date.now();
                 while (state.type === "pending") {
-                    if (Date.now() > deadline)
-                        return text(`The script took longer than ${Math.round(timeoutMs / 1000)} seconds and was stopped.`, true);
-                    if (context.signal.aborted)
-                        return text("The script was cancelled.", true);
-                    await Promise.race([Promise.allSettled(pending), new Promise((resolve) => setTimeout(resolve, 20))]);
-                    runtime.executePendingJobs();
+                    const now = Date.now();
+                    if (underway.size === 0)
+                        idleMs += now - tick;
+                    tick = now;
+                    const over = late();
+                    if (over)
+                        return failure(over);
+                    await Promise.race([...unsettled, new Promise((resolve) => setTimeout(resolve, 20))]);
+                    inRuntime(() => runtime.executePendingJobs());
                     state = vm.getPromiseState(evaluated.value);
                 }
                 const output = printed.length > 0 ? `${printed.join("\n")}\n` : "";
                 if (state.type === "rejected") {
                     const message = vm.dump(state.error);
                     state.error.dispose();
-                    return text(cut(`${output}Script error: ${formatError(message)}`, maxOutput), true);
+                    return failure(late() ?? `Script error: ${formatError(message)}`);
                 }
                 const value = vm.dump(state.value);
                 state.value.dispose();
@@ -142,9 +196,11 @@ export function codemodePlugin(options) {
                 return text(cut(combined === "" ? "(no output)" : combined, maxOutput));
             }
             catch (error) {
-                return text(`Script failed: ${error instanceof Error ? error.message : String(error)}`, true);
+                return failure(`Script failed: ${error instanceof Error ? error.message : String(error)}`);
             }
             finally {
+                for (const controller of underway)
+                    controller.abort(); // calls still under way when the script ends are stopped
                 for (const handle of handles)
                     if (handle.alive)
                         handle.dispose();
@@ -158,6 +214,8 @@ export function codemodePlugin(options) {
     };
     return { name: "codemode", compensates: "one tool call per model request is slow and fills the context with intermediate results", setup: (api) => api.registerTool(runCode) };
 }
+/** Seconds for an error message: a whole number when it is one, otherwise one decimal (0.3 and not 0). */
+const seconds = (ms) => Number((ms / 1000).toFixed(1));
 function formatError(dumped) {
     if (typeof dumped === "object" && dumped !== null) {
         const { name, message } = dumped;

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

@@ -2,5 +2,5 @@ export { searchPlugin } from "./search.js";
 export type { SearchOptions } from "./search.js";
 export { connectMcp } from "./mcp.js";
 export type { McpConnection, McpServerConfig, McpServerStatus } from "./mcp.js";
-export { codemodePlugin } from "./codemode.js";
+export { CODEMODE_TOOL, codemodePlugin } from "./codemode.js";
 export type { Authorize, CodemodeOptions } from "./codemode.js";

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

@@ -1,3 +1,3 @@
 export { searchPlugin } from "./search.js";
 export { connectMcp } from "./mcp.js";
-export { codemodePlugin } from "./codemode.js";
+export { CODEMODE_TOOL, codemodePlugin } from "./codemode.js";

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

@@ -0,0 +1,27 @@
+import type { Plugin } from "../../../kernel/src/index.js";
+/** One step of a run, tagged with the module that did the work. Written one per line to a trace file. */
+export interface TraceRecord {
+    /** Milliseconds since the trace began. */
+    t: number;
+    /** Module id, matching the node ids of the architecture diagram. */
+    module: string;
+    /** What happened (the event type). */
+    fn: string;
+    /** A short detail, never message text. */
+    detail?: string;
+}
+export interface TraceOptions {
+    /** Append records to this file as JSON lines. */
+    file?: string;
+    /** Receive each record. */
+    sink?(record: TraceRecord): void;
+    now?: () => number;
+}
+export interface TracePlugin extends Plugin {
+    records: TraceRecord[];
+}
+/**
+ * Records what runs, for the module map. It only watches events, never changes anything the model sees,
+ * and keeps no message text. A development aid, off unless added.
+ */
+export declare function tracePlugin(options?: TraceOptions): TracePlugin;

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

@@ -0,0 +1,29 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { moduleOf } from "./modules.js";
+/**
+ * Records what runs, for the module map. It only watches events, never changes anything the model sees,
+ * and keeps no message text. A development aid, off unless added.
+ */
+export function tracePlugin(options = {}) {
+    const now = options.now ?? Date.now;
+    const started = now();
+    const records = [];
+    if (options.file)
+        mkdirSync(dirname(options.file), { recursive: true });
+    return {
+        name: "trace",
+        compensates: "nothing: it only watches",
+        records,
+        setup(api) {
+            api.on("event", (event) => {
+                const { module, detail } = moduleOf(event);
+                const record = { t: now() - started, module, fn: event.type, ...(detail !== undefined ? { detail } : {}) };
+                records.push(record);
+                options.sink?.(record);
+                if (options.file)
+                    appendFileSync(options.file, `${JSON.stringify(record)}\n`);
+            });
+        },
+    };
+}

package/dist/packages/plugins/trace/src/modules.d.ts

@@ -0,0 +1,6 @@
+import type { Event } from "../../../kernel/src/index.js";
+/** Which module does the work behind each kind of event. */
+export declare function moduleOf(event: Event): {
+    module: string;
+    detail?: string;
+};

package/dist/packages/plugins/trace/src/modules.js

@@ -0,0 +1,28 @@
+/** Which module does the work behind each kind of event. */
+export function moduleOf(event) {
+    switch (event.type) {
+        case "run_start":
+        case "run_end":
+        case "turn_start":
+        case "turn_end":
+        case "paused":
+            return { module: "kernel", ...(event.type === "run_end" ? { detail: event.reason } : event.type === "paused" ? { detail: event.reason } : {}) };
+        case "message_start":
+        case "message_update":
+        case "reasoning_update":
+        case "message_reset":
+        case "message_end":
+            return { module: "llm" };
+        case "tool_start":
+        case "tool_end":
+            return { module: "tools", detail: event.call.name };
+        case "compaction":
+            return { module: "compaction" };
+        case "goal":
+            return { module: "goal", detail: event.status };
+        case "signal":
+            return { module: "kernel", detail: "signal" };
+        case "plugin":
+            return { module: `plugin-${event.name}` };
+    }
+}

package/dist/packages/session/src/file-log.d.ts

@@ -1,10 +1,15 @@
-import type { LogOptions, RewindableLog } from "./memory-log.js";
+import type { LogOptions, RewindableLog } from "./log-core.js";
 export interface SessionHeader {
     type: "header";
     version: number;
     id: string;
     cwd: string;
     ts: number;
+    /** Set on a session that was made by forking another: the entry it was copied up to, and the session it came from when that is known. */
+    forkedFrom?: {
+        entry: string;
+        session?: string;
+    };
 }
 export interface FileLog extends RewindableLog {
     header: SessionHeader;