sakura-agent 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,166 @@
+import { createChatClient } from "../../llm/src/index.js";
+import { createLocalEnvironment } from "../../env/src/index.js";
+import { createKernel } from "../../kernel/src/index.js";
+import { agentsPlugin } from "../../plugins/agents/src/index.js";
+import { contextPlugin } from "../../plugins/context/src/index.js";
+import { codemodePlugin, connectMcp, searchPlugin } from "../../plugins/toolset/src/index.js";
+import { limitsPlugin } from "../../plugins/limits/src/index.js";
+import { resiliencePlugin } from "../../plugins/resilience/src/index.js";
+import { builtinTools, toolsPlugin } from "../../plugins/tools/src/index.js";
+import { createMemoryLog, openFileLog } from "../../session/src/index.js";
+import { compose } from "./compose.js";
+import { buildSystemPrompt } from "./system-prompt.js";
+/** The plugins every agent gets unless the caller passes its own list: project instructions (AGENTS.md), long tool output saved to files, resilience (replies that were cut off or came back empty are asked again), and limits (unlimited until configured). */
+export function corePlugins() {
+    return [contextPlugin(), toolsPlugin(), resiliencePlugin(), limitsPlugin()];
+}
+const SUB_AGENT_NOTE = "You are a sub-agent working for another agent. Do the task you are given completely, then finish with a clear written report of what you did and found. That report is the only thing that goes back to the agent that asked.";
+const CACHE_CHECK_MS = 240_000;
+const checkInput = (labels) => `Background work you started is still running: ${labels.join(", ")}. Check on it once now (for example read its output), then stop and wait; you will be told when it ends. Do not poll.`;
+const isClient = (model) => "stream" in model;
+export async function createAgent(config) {
+    const cwd = config.cwd ?? process.cwd();
+    const env = config.environment ?? createLocalEnvironment(cwd);
+    const connection = config.mcp ? await connectMcp(config.mcp.servers, config.mcp.timeoutMs !== undefined ? { timeoutMs: config.mcp.timeoutMs } : {}) : undefined;
+    const mcpTools = connection?.tools ?? [];
+    const expose = config.mcp?.expose ?? (mcpTools.length > 10 ? "search" : "direct");
+    const bashOptions = {
+        ...(config.bashSoftTimeoutMs !== undefined ? { softTimeoutMs: config.bashSoftTimeoutMs } : {}),
+        ...(config.bashBackgroundGraceMs !== undefined ? { backgroundGraceMs: config.bashBackgroundGraceMs } : {}),
+    };
+    const tools = builtinTools(config.tools, { bash: bashOptions });
+    const declared = expose === "direct" ? [...tools, ...mcpTools] : tools;
+    const clientFor = (model) => isClient(model)
+        ? model
+        : createChatClient({
+            baseUrl: model.baseUrl,
+            apiKey: model.apiKey,
+            model: model.model,
+            contextWindow: model.contextWindow,
+            ...(model.compat ? { compat: model.compat } : {}),
+            ...(model.headers ? { headers: model.headers } : {}),
+        });
+    const llm = clientFor(config.model);
+    const thinkingModel = !isClient(config.model) && config.model.compat?.thinkingFormat !== undefined && config.model.compat.thinkingFormat !== "none";
+    const thinking = config.thinking ?? (thinkingModel ? "medium" : undefined);
+    const system = config.system ?? buildSystemPrompt({ tools, cwd: env.cwd, platform: process.platform });
+    // bundles are opened and a plugin that appears twice is installed once; a missing requirement, a cycle or two plugins with one name fail here, before anything runs
+    const plugins = compose(config.plugins ?? corePlugins());
+    const notInherited = new Set(config.subAgents?.notInherited ?? ["agents", "limits", "context", "tools"]);
+    const inherited = plugins.filter((plugin) => !notInherited.has(plugin.name));
+    if (mcpTools.length > 0 && expose === "search")
+        plugins.push(searchPlugin({ catalog: mcpTools }));
+    // a plugin that offers `authorize` (the review plugin does) is asked before each call a script makes, because those calls do not pass the loop's hooks
+    const authorize = plugins.map((plugin) => plugin.authorize).find((candidate) => typeof candidate === "function");
+    if (mcpTools.length > 0 && expose === "codemode")
+        plugins.push(codemodePlugin({ catalog: mcpTools, ...(authorize ? { authorize } : {}) }));
+    const childLogs = [];
+    const childModels = new Map(Object.entries(config.subAgents?.models ?? {}).map(([name, model]) => [name, clientFor(model)]));
+    if (config.subAgents) {
+        const childLogDirectory = config.sessionFile?.replace(/\.jsonl$/, "") ?? undefined;
+        plugins.push(agentsPlugin({
+            ...(({ models: _models, notInherited: _notInherited, ...rest }) => rest)(config.subAgents),
+            createChild: ({ definition, maxTurns, model }) => createKernel({
+                llm: (model !== undefined && childModels.get(model)) || llm,
+                env,
+                system: `${definition.systemPrompt ?? system}\n\n${SUB_AGENT_NOTE}`,
+                tools: definition.tools ? tools.filter((tool) => definition.tools?.includes(tool.name)) : tools,
+                plugins: maxTurns !== undefined ? [...inherited, limitsPlugin({ maxTurns })] : inherited,
+                ...(config.maxTokens !== undefined ? { maxTokens: config.maxTokens } : {}),
+                ...(thinking !== undefined ? { thinking } : {}),
+                ...(config.compaction !== undefined ? { compaction: config.compaction } : {}),
+            }),
+            ...(childLogDirectory
+                ? {
+                    openLog: async (id) => {
+                        const log = await openFileLog(`${childLogDirectory}/agents/${id}.jsonl`, { cwd: env.cwd });
+                        childLogs.push(log);
+                        return log;
+                    },
+                }
+                : {}),
+        }));
+    }
+    const kernel = createKernel({
+        llm,
+        env,
+        system,
+        tools: declared,
+        plugins,
+        ...(config.maxTokens !== undefined ? { maxTokens: config.maxTokens } : {}),
+        ...(thinking !== undefined ? { thinking } : {}),
+        ...(config.now ? { now: config.now } : {}),
+        ...(config.wake ? { onSignal: () => onBackgroundEnd() } : {}),
+        ...(config.compaction !== undefined ? { compaction: config.compaction } : {}),
+        ...(config.goal ? { goal: config.goal } : {}),
+        ...(config.prompts ? { prompts: config.prompts } : {}),
+    });
+    const fileLog = config.sessionFile ? await openFileLog(config.sessionFile, { cwd: env.cwd }) : undefined;
+    const log = fileLog ?? createMemoryLog();
+    let active;
+    let closed = false;
+    let timer;
+    let checkUsed = false; // the one proactive check per quiet period has been made
+    function start(input) {
+        const handle = kernel.run(log, input);
+        active = handle;
+        void handle.result.finally(() => {
+            if (active === handle)
+                active = undefined;
+            afterRun();
+        });
+        return handle;
+    }
+    function wakeWith(input) {
+        if (closed || active || !config.wake)
+            return;
+        config.wake.onRun(start(input));
+    }
+    function onBackgroundEnd() {
+        clearTimeout(timer);
+        checkUsed = false;
+        wakeWith(undefined); // while a run is going, it delivers the notice itself or afterRun does
+    }
+    /** Called when a run ends: wakes for anything the run did not get to tell the agent, or arms the one check before the cache expires. */
+    function afterRun() {
+        if (closed || !config.wake)
+            return;
+        const pending = kernel.pending(log);
+        if (pending.signals.length > 0) {
+            wakeWith(undefined);
+            return;
+        }
+        if (pending.watching.length === 0 || checkUsed)
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            const now = kernel.pending(log);
+            if (now.signals.length > 0)
+                return wakeWith(undefined);
+            if (now.watching.length === 0)
+                return;
+            checkUsed = true;
+            wakeWith(checkInput(now.watching));
+        }, config.wake.cacheCheckMs ?? CACHE_CHECK_MS);
+        timer.unref();
+    }
+    return {
+        log,
+        mcp: connection?.status ?? {},
+        rewindTo: (entryId) => log.rewindTo(entryId),
+        run: (input) => start(input),
+        queue: (text) => active?.queue(text),
+        steer: (text) => active?.steer(text),
+        cancel: () => active?.cancel(),
+        close: async () => {
+            closed = true;
+            clearTimeout(timer);
+            await connection?.close();
+            await env.dispose(); // stops commands that are still running in the background
+            await Promise.all(childLogs.map((log) => log.close()));
+            await fileLog?.close();
+        },
+    };
+}
+export { buildSystemPrompt } from "./system-prompt.js";
+export { bundle, compose, CompositionError } from "./compose.js";

package/dist/packages/agent/src/system-prompt.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from "../../kernel/src/index.js";
+export interface SystemPromptOptions {
+    tools: readonly Tool[];
+    cwd: string;
+    platform: string;
+    /** Extra rules from plugins. */
+    rules?: string[];
+}
+/** Builds the system prompt: preamble, tools, rules, environment. Callers can replace the whole thing. */
+export declare function buildSystemPrompt(options: SystemPromptOptions): string;

package/dist/packages/agent/src/system-prompt.js

@@ -0,0 +1,49 @@
+/*
+ * Rule texts adapted from the ideas in Pi's system prompt (MIT, Copyright (c) 2025 Mario Zechner) and the
+ * task-execution principles of OpenAI Codex's base instructions (Apache-2.0); reworded and shortened.
+ * See THIRD_PARTY_NOTICES.md.
+ */
+const PREAMBLE = "You are a coding agent. You help the user by reading files, running commands, editing code and writing new files. Be precise, safe and helpful.";
+const RULES = [
+    "Keep going until the user's request is completely resolved before you end your turn. Do not stop at a plan or a partial result.",
+    "Fix problems at the root cause rather than patching symptoms, and avoid unneeded complexity.",
+    "Keep changes minimal and consistent with the style of the existing code. Do not fix unrelated bugs; you may mention them in your final message.",
+    "In an existing codebase, do exactly what was asked with precision. In a brand-new project you may be more ambitious.",
+    "If the project has tests or a way to build or run, use them to check your work. Start with the most specific check for what you changed, then widen.",
+    "Do not re-read a file only to confirm an edit succeeded; a failed edit returns an error.",
+    "Do not commit changes or create branches unless the user asks.",
+    "Do not add comments or copyright headers to code unless the user asks.",
+    "Before a long or risky step, say in one short sentence what you are about to do. Do not narrate trivial reads.",
+    "Be concise. Show file paths clearly so the user can open them. Do not paste the full contents of files you have already written.",
+    "Instruction files from the project (AGENTS.md) and direct user messages take precedence over these rules.",
+];
+/** Rules that belong to one tool; they appear only when that tool is available. */
+const TOOL_RULES = {
+    read: ["Use read to examine files instead of cat or sed."],
+    write: ["Use write only for new files or complete rewrites. Keep each file under about 2000 lines; split larger work across several files, because a very long tool call can be cut off."],
+    edit: [
+        "Use edit for precise changes (edits[].oldText must match exactly).",
+        "When changing multiple separate locations in one file, use one edit call with several entries in edits[].",
+        "Each edits[].oldText is matched against the original file, not after earlier edits. Do not emit overlapping or nested edits; merge nearby changes.",
+        "Keep edits[].oldText as small as possible while still unique in the file.",
+    ],
+    bash: [
+        "When searching for text or files, prefer rg (rg --files for file names); fall back to grep or find if rg is missing.",
+        "Do not use scripts to print large chunks of a file; use read with offset and limit.",
+        "Commands run without a terminal and cannot read input. Always pass non-interactive flags (for example --yes, -y, --no-input, CI=1); a command that waits for input will hang.",
+    ],
+};
+const firstSentence = (description) => (description.split(/(?<=\.)\s/)[0] ?? description).trim();
+/** Builds the system prompt: preamble, tools, rules, environment. Callers can replace the whole thing. */
+export function buildSystemPrompt(options) {
+    const toolLines = options.tools.map((tool) => `- ${tool.name}: ${firstSentence(tool.description)}`);
+    const rules = [...new Set([...options.tools.flatMap((tool) => TOOL_RULES[tool.name] ?? []), ...RULES, ...(options.rules ?? [])])];
+    return [
+        PREAMBLE,
+        options.tools.length > 0 ? `<tools>\n${toolLines.join("\n")}\n</tools>` : "",
+        `<rules>\n${rules.map((rule) => `- ${rule}`).join("\n")}\n</rules>`,
+        `<environment>\nWorking directory: ${options.cwd}\nPlatform: ${options.platform}\n</environment>`,
+    ]
+        .filter((section) => section !== "")
+        .join("\n\n");
+}

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

@@ -0,0 +1,3 @@
+export { createLocalEnvironment } from "./local.js";
+export { createRemoteEnvironment } from "./remote.js";
+export type { RemoteRunner } from "./remote.js";

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

@@ -0,0 +1,2 @@
+export { createLocalEnvironment } from "./local.js";
+export { createRemoteEnvironment } from "./remote.js";

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

@@ -0,0 +1,3 @@
+import type { Environment } from "../../kernel/src/index.js";
+/** The environment tools run in when there is no sandbox: the local machine. */
+export declare function createLocalEnvironment(cwd: string): Environment;

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

@@ -0,0 +1,174 @@
+import { spawn as spawnProcess } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { mkdir, mkdtemp, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+const MAX_OUTPUT_CHARS = 20_000_000;
+const KILL_GRACE_MS = 1500;
+function killGroup(pid, signal) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // the group is already gone
+    }
+}
+// Commands run in their own process group, so they would outlive a host process that is stopped without closing the environment
+// (Ctrl-C, process.exit, a script that ends while a background command still runs). Every group still running is stopped when the host exits.
+const liveGroups = new Set();
+let exitHooked = false;
+function stopAllGroups() {
+    for (const pid of liveGroups)
+        killGroup(pid, "SIGKILL");
+}
+function hookExit() {
+    if (exitHooked)
+        return;
+    exitHooked = true;
+    process.on("exit", stopAllGroups);
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        const onSignal = () => {
+            stopAllGroups();
+            process.removeListener(signal, onSignal);
+            // with no other handler the signal would have ended the process; our handler must not turn that into "keeps running"
+            if (process.listenerCount(signal) === 0)
+                process.kill(process.pid, signal);
+        };
+        process.on(signal, onSignal);
+    }
+}
+/** The environment tools run in when there is no sandbox: the local machine. */
+export function createLocalEnvironment(cwd) {
+    const root = resolve(cwd);
+    const resolvePath = (path) => (isAbsolute(path) ? resolve(path) : resolve(root, path));
+    const running = new Set();
+    let outputDir;
+    let counter = 0;
+    const nextOutputFile = async () => {
+        outputDir ??= mkdtemp(join(tmpdir(), "sakura-env-"));
+        return join(await outputDir, `command-${++counter}.log`);
+    };
+    function start(command, options) {
+        const child = spawnProcess("/bin/bash", ["-c", command], {
+            cwd: options.cwd ? resolvePath(options.cwd) : root,
+            detached: true, // its own process group, so the whole tree can be stopped
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const pid = child.pid ?? -1;
+        if (child.pid !== undefined) {
+            hookExit();
+            liveGroups.add(child.pid);
+        }
+        let output = "";
+        let finished = false;
+        let killScheduled = false;
+        const fileReady = nextOutputFile().then((path) => ({ path, stream: createWriteStream(path) }));
+        const collect = (chunk) => {
+            output += chunk.toString("utf8");
+            if (output.length > MAX_OUTPUT_CHARS)
+                output = output.slice(output.length - MAX_OUTPUT_CHARS);
+            void fileReady.then(({ stream }) => stream.write(chunk));
+        };
+        child.stdout.on("data", collect);
+        child.stderr.on("data", collect);
+        const kill = () => {
+            killGroup(child.pid, "SIGTERM");
+            if (!killScheduled) {
+                killScheduled = true;
+                setTimeout(() => killGroup(child.pid, "SIGKILL"), KILL_GRACE_MS).unref();
+            }
+        };
+        if (options.signal?.aborted)
+            kill();
+        options.signal?.addEventListener("abort", kill, { once: true });
+        let outputFile = "";
+        const done = new Promise((resolveResult) => {
+            let settled = false;
+            const finish = async (exitCode) => {
+                if (settled)
+                    return;
+                settled = true;
+                options.signal?.removeEventListener("abort", kill);
+                child.stdout.destroy();
+                child.stderr.destroy();
+                const file = await fileReady;
+                await new Promise((closed) => file.stream.end(closed));
+                finished = true;
+                if (child.pid !== undefined)
+                    liveGroups.delete(child.pid);
+                running.delete(handle);
+                resolveResult({ exitCode, output, timedOut: false });
+            };
+            child.on("error", (error) => {
+                output += `\n${error.message}`;
+                void finish(null);
+            });
+            // A command that leaves a background process holding the pipes open must not make us wait for it:
+            // once the shell itself has exited, give the pipes a moment to drain and finish.
+            child.on("exit", (code) => setTimeout(() => void finish(code), 50));
+            child.on("close", (code) => void finish(code));
+        });
+        void fileReady.then(({ path }) => {
+            outputFile = path;
+        });
+        const handle = {
+            pid,
+            get outputFile() {
+                return outputFile;
+            },
+            wait: () => done,
+            kill,
+            get finished() {
+                return finished;
+            },
+        };
+        running.add(handle);
+        return handle;
+    }
+    return {
+        cwd: root,
+        resolve: resolvePath,
+        readFile: async (path) => new Uint8Array(await readFile(resolvePath(path))),
+        async writeFile(path, data) {
+            const target = resolvePath(path);
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, data);
+        },
+        async stat(path) {
+            try {
+                const info = await stat(resolvePath(path));
+                return { isFile: info.isFile(), isDirectory: info.isDirectory(), size: info.size };
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            }
+        },
+        async list(path) {
+            return (await readdir(resolvePath(path))).sort();
+        },
+        spawn: start,
+        async exec(command, options) {
+            const handle = start(command, options.signal ? { ...(options.cwd ? { cwd: options.cwd } : {}), signal: options.signal } : options.cwd ? { cwd: options.cwd } : {});
+            let timedOut = false;
+            const timer = options.timeoutMs !== undefined
+                ? setTimeout(() => {
+                    timedOut = true;
+                    handle.kill();
+                }, options.timeoutMs)
+                : undefined;
+            const result = await handle.wait();
+            if (timer)
+                clearTimeout(timer);
+            return { ...result, timedOut };
+        },
+        async dispose() {
+            for (const handle of [...running])
+                handle.kill();
+            await Promise.all([...running].map((handle) => handle.wait()));
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { Environment, ExecResult } from "../../kernel/src/index.js";
+/** The one thing a remote environment needs: a way to run a shell command somewhere else and get its output back. */
+export type RemoteRunner = (command: string, options: {
+    cwd?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}) => Promise<ExecResult>;
+/**
+ * An environment on another machine (a container, say) reached only through `run`. Files are read and written
+ * with base64 over the shell, and long commands are started detached so they can outlive a single call.
+ */
+export declare function createRemoteEnvironment(options: {
+    cwd: string;
+    run: RemoteRunner;
+}): Environment;

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

@@ -0,0 +1,120 @@
+import { randomBytes } from "node:crypto";
+import { posix } from "node:path";
+const quote = (text) => `'${text.replace(/'/g, `'\\''`)}'`;
+const CHUNK = 48_000;
+/**
+ * An environment on another machine (a container, say) reached only through `run`. Files are read and written
+ * with base64 over the shell, and long commands are started detached so they can outlive a single call.
+ */
+export function createRemoteEnvironment(options) {
+    const root = posix.resolve("/", options.cwd);
+    const workDir = posix.join(root, ".sakura", "remote");
+    const { run } = options;
+    const resolvePath = (path) => (path.startsWith("/") ? posix.normalize(path) : posix.resolve(root, path));
+    const running = new Set();
+    let counter = 0;
+    const prefix = randomBytes(3).toString("hex");
+    async function must(command) {
+        const result = await run(command, { cwd: root });
+        if (result.exitCode !== 0)
+            throw new Error(result.output.trim() || `command failed with exit code ${result.exitCode}`);
+        return result.output;
+    }
+    function spawn(command, spawnOptions) {
+        const id = `${prefix}-${++counter}`;
+        const log = posix.join(workDir, `${id}.log`);
+        const codeFile = posix.join(workDir, `${id}.code`);
+        const scriptFile = posix.join(workDir, `${id}.sh`);
+        let pid = 0;
+        let finished = false;
+        let result;
+        const script = `cd ${quote(spawnOptions.cwd ? resolvePath(spawnOptions.cwd) : root)} || exit 1\n${command}\n`;
+        const started = run(`mkdir -p ${quote(workDir)} && echo ${Buffer.from(script).toString("base64")} | base64 -d > ${quote(scriptFile)} || exit $?; ` +
+            `setsid bash -c ${quote(`bash ${quote(scriptFile)} > ${quote(log)} 2>&1; echo $? > ${quote(codeFile)}`)} > /dev/null 2>&1 & echo $!`, { cwd: root }).then((outcome) => {
+            if (outcome.exitCode === 0)
+                pid = Number.parseInt(outcome.output.trim().split("\n").at(-1) ?? "", 10) || 0;
+        });
+        const kill = () => {
+            void started.then(() => (pid > 0 ? run(`kill -TERM -- -${pid} 2>/dev/null; sleep 1; kill -KILL -- -${pid} 2>/dev/null; true`, { cwd: root }) : undefined)).catch(() => undefined);
+        };
+        spawnOptions.signal?.addEventListener("abort", kill, { once: true });
+        let done;
+        const handle = {
+            get pid() {
+                return pid;
+            },
+            outputFile: log,
+            wait: () => done,
+            kill,
+            get finished() {
+                return finished;
+            },
+        };
+        done = (async () => {
+            await started;
+            if (pid === 0) {
+                finished = true;
+                running.delete(handle);
+                return { exitCode: null, output: "the command could not be started", timedOut: false };
+            }
+            for (let attempt = 0;; attempt++) {
+                const state = await run(`if [ -f ${quote(codeFile)} ]; then cat ${quote(codeFile)}; elif kill -0 ${pid} 2>/dev/null; then echo running; else echo gone; fi`, {
+                    cwd: root,
+                });
+                const text = state.output.trim();
+                if (text !== "running") {
+                    const output = await run(`cat ${quote(log)} 2>/dev/null`, { cwd: root });
+                    const exitCode = /^\d+$/.test(text) ? Number(text) : null;
+                    finished = true;
+                    running.delete(handle);
+                    result = { exitCode, output: output.output, timedOut: false };
+                    return result;
+                }
+                await new Promise((resolve) => setTimeout(resolve, attempt < 8 ? 250 : 1000));
+            }
+        })();
+        running.add(handle);
+        return handle;
+    }
+    return {
+        cwd: root,
+        resolve: resolvePath,
+        async readFile(path) {
+            const output = await must(`set -o pipefail; base64 < ${quote(resolvePath(path))} | tr -d '\\n'`);
+            return new Uint8Array(Buffer.from(output.trim(), "base64"));
+        },
+        async writeFile(path, data) {
+            const target = resolvePath(path);
+            const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+            const temp = `${target}.af-${randomBytes(4).toString("hex")}`;
+            await must(`mkdir -p ${quote(posix.dirname(target))} && : > ${quote(temp)}`);
+            const encoded = bytes.toString("base64");
+            for (let offset = 0; offset < encoded.length; offset += CHUNK) {
+                await must(`printf %s ${quote(encoded.slice(offset, offset + CHUNK))} >> ${quote(temp)}`);
+            }
+            await must(`base64 -d < ${quote(temp)} > ${quote(target)} && rm -f ${quote(temp)}`);
+        },
+        async stat(path) {
+            const p = quote(resolvePath(path));
+            const output = (await must(`if [ -d ${p} ]; then echo dir 0; elif [ -f ${p} ]; then echo file $(wc -c < ${p}); else echo none 0; fi`)).trim();
+            const [kind, size] = output.split(/\s+/);
+            if (kind === "none")
+                return undefined;
+            return { isFile: kind === "file", isDirectory: kind === "dir", size: Number(size) || 0 };
+        },
+        async list(path) {
+            const output = await must(`ls -A1 ${quote(resolvePath(path))}`);
+            return output.split("\n").filter(Boolean).sort();
+        },
+        spawn,
+        exec: (command, execOptions) => run(command, {
+            cwd: execOptions.cwd ? resolvePath(execOptions.cwd) : root,
+            ...(execOptions.timeoutMs !== undefined ? { timeoutMs: execOptions.timeoutMs } : {}),
+            ...(execOptions.signal ? { signal: execOptions.signal } : {}),
+        }),
+        async dispose() {
+            for (const handle of [...running])
+                handle.kill();
+        },
+    };
+}

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

@@ -0,0 +1,7 @@
+/** A push-based async queue: the run pushes events, the caller iterates them. */
+export interface Channel<T> {
+    push(value: T): void;
+    end(): void;
+    iterable: AsyncIterable<T>;
+}
+export declare function createChannel<T>(): Channel<T>;

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

@@ -0,0 +1,34 @@
+export function createChannel() {
+    const buffer = [];
+    let ended = false;
+    let wake;
+    const notify = () => {
+        wake?.();
+        wake = undefined;
+    };
+    async function* iterate() {
+        let position = 0;
+        while (true) {
+            if (position < buffer.length) {
+                yield buffer[position++];
+                continue;
+            }
+            if (ended)
+                return;
+            await new Promise((resolve) => {
+                wake = resolve;
+            });
+        }
+    }
+    return {
+        push(value) {
+            buffer.push(value);
+            notify();
+        },
+        end() {
+            ended = true;
+            notify();
+        },
+        iterable: { [Symbol.asyncIterator]: iterate },
+    };
+}

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

@@ -0,0 +1,25 @@
+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;
+    /** Roughly how many recent tokens stay word for word after a compaction. */
+    keepRecentTokens: number;
+}
+export declare const defaultCompaction: CompactionConfig;
+/** A rough token count: four characters per token, a flat cost for images. */
+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;
+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. */
+    firstKeptEntryId: string;
+    /** True when the cut falls inside a turn (no user message boundary was available). */
+    splitTurn: boolean;
+}
+/**
+ * Chooses where to cut. History before the cut is summarised, the rest stays. The cut is placed at a user
+ * message where possible; it is never placed on a tool result, so a call and its results stay together.
+ * Returns undefined when there is nothing worth summarising.
+ */
+export declare function planCompaction(branch: readonly LogEntry[], config: CompactionConfig): CompactionPlan | undefined;