sakura-agent 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,130 @@
+import type { ChatCompat } from "../../llm/src/index.js";
+import type { CompactionConfig, ContextStatus, Environment, GoalRecord, LlmClient, Plugin, Prompts, RunHandle, RunOptions, ThinkingLevel, Tool, UsageTotals, UserInput } from "../../kernel/src/index.js";
+import type { AgentDefinition } from "../../plugins/agents/src/index.js";
+import type { McpServerConfig, McpServerStatus } from "../../plugins/toolset/src/index.js";
+import type { RewindableLog } from "../../session/src/index.js";
+import type { WakeSetting } from "./wake.js";
+type BuiltinToolName = "read" | "write" | "edit" | "bash";
+export interface ModelConfig {
+    /** Base URL without /chat/completions, for example https://api.deepseek.com */
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    contextWindow: number;
+    compat?: Partial<ChatCompat>;
+    headers?: Record<string, string>;
+}
+export interface AgentConfig {
+    /** A provider to talk to, or a ready-made client (for tests). */
+    model: ModelConfig | LlmClient;
+    cwd?: string;
+    /**
+     * Keep the file tools inside `cwd`: a read, write, edit or list of anything outside it is refused with an error the model sees, however the path is written
+     * (absolute, `..`, a link). For an agent with no shell tool this is the whole boundary, and no review is needed. A shell command can still reach anything,
+     * so with `bash` use it together with the review plugin. Only for the default local environment: build `createLocalEnvironment(cwd, { confine: true })` yourself
+     * for anything else (giving both is an error).
+     */
+    confine?: boolean;
+    /** The tools the model gets: names of the built-in ones (default all four) and tools you wrote. A kind of sub-agent that lists tool names gets only those, whoever registered them. */
+    tools?: Array<BuiltinToolName | Tool>;
+    /** After this many milliseconds a running shell command is moved to the background (default 120000). */
+    bashSoftTimeoutMs?: number;
+    /** How long a command the model starts with `background: true` is watched before it is left to run (default 1000), so that one that fails at once is reported as failed. */
+    bashBackgroundGraceMs?: number;
+    /** Defaults to corePlugins(). Safety plugins (review, redaction, sub-agents) are never in the default set. May contain bundles and plugins that say what they require; see compose(). */
+    plugins?: Plugin[];
+    /** Replaces the generated system prompt. */
+    system?: string;
+    /** Rules added to the generated system prompt, after the built-in ones. Sub-agents get them too. Not used when `system` replaces the prompt. */
+    rules?: string[];
+    /** Write the conversation to this JSONL file; without it the conversation lives in memory only. */
+    sessionFile?: string;
+    thinking?: ThinkingLevel;
+    maxTokens?: number;
+    goal?: {
+        objective: string;
+        verify?: string;
+    };
+    compaction?: false | Partial<CompactionConfig>;
+    prompts?: Partial<Prompts>;
+    environment?: Environment;
+    now?: () => number;
+    /**
+     * Wakes the agent by itself. When background work ends (a command moved to the background, a background sub-agent) and no run is going,
+     * a run is started so the agent hears about it; `onRun` receives each such run (to show its events). While work is still pending and the agent
+     * is quiet, it is woken once after `cacheCheckMs` (default 4 minutes, a little under the prompt cache lifetime) to check, and then left alone until something ends.
+     * The agent can also ask for it: `bash` takes `wake: true` or `wake: false` for one command, which wins over this setting for that command. With no `wake` here,
+     * a command that asked to wake the agent still does, and its run is not shown to anyone (the log has all of it). The check before the cache expires needs this setting.
+     */
+    wake?: WakeSetting;
+    /**
+     * MCP servers, started once when the agent is created (a server that fails is left out and shows in `agent.mcp`). Their tools are named mcp__<server>__<tool>.
+     * `expose`: "direct" declares every tool to the model; "search" lists only tool_search and tool_call; "codemode" lists only run_code, a script that can call the
+     * tools (each call goes through the review plugin when one is installed). The default is "direct" up to 10 tools and "search" above.
+     */
+    mcp?: {
+        servers: Record<string, McpServerConfig>;
+        expose?: "direct" | "search" | "codemode";
+        timeoutMs?: number;
+    };
+    /** Turns on sub-agents (delegate, agent_view, agent_stop). Off unless this is given. */
+    subAgents?: {
+        agents?: AgentDefinition[];
+        maxRegistered?: number;
+        maxRunning?: number;
+        /**
+         * Plugins (by name) that sub-agents do not get. Every other plugin of the agent is shared with its sub-agents, so review and redaction
+         * cannot be bypassed by delegating. Default: agents (no nesting), limits (a sub-agent has its own turn limit), context and tools (a sub-agent starts fresh).
+         */
+        notInherited?: string[];
+        /** Models by name, for sub-agent definitions that name one (`AgentDefinition.model`). A definition whose model is not in the table uses the parent's model. */
+        models?: Record<string, ModelConfig | LlmClient>;
+    };
+}
+export interface Agent {
+    /**
+     * Starts, resumes or follows up. See Kernel.run. `{ compact: true }` compacts the conversation first, whatever its size: `agent.run(undefined, { compact: true })`
+     * is "compact now", and the `compaction` event of the run says it was done.
+     */
+    run(input?: UserInput, options?: RunOptions): RunHandle;
+    queue(text: string): void;
+    steer(text: string): void;
+    cancel(): void;
+    log: RewindableLog;
+    /** Goes back to an earlier point of the conversation (an entry id from `log.branch()`, or null for the very start); what is said next starts a new branch. */
+    rewindTo(entryId: string | null): void;
+    /**
+     * Writes the conversation up to an earlier point (an entry id from `log.branch()`; left out, up to now) as a new session file, which is a session of
+     * its own: open it with `createAgent({ ...config, sessionFile: path })`. This session is not changed, and both can go on. A turn is not cut in two:
+     * the results of the tool calls of the last message copied come with it. Fails if the file exists.
+     */
+    fork(path: string, upTo?: string): Promise<void>;
+    /** What is waiting to be told to the agent and which background work it is waiting for. A host can use it to decide whether to start a run. */
+    pending(): {
+        signals: string[];
+        watching: string[];
+    };
+    /** The goal of the conversation, as the session file says it is (active, blocked or complete); undefined when there is none. */
+    goal(): Promise<GoalRecord | undefined>;
+    /** Sets the goal, replacing an earlier one; the next run is checked against it before it may stop. Part of the session, so it survives reopening and fork. Fails while a run is active. */
+    setGoal(goal: {
+        objective: string;
+        verify?: string;
+    }): Promise<void>;
+    /** Ends the goal (it counts as complete). Fails while a run is active. */
+    clearGoal(): Promise<void>;
+    /** How full the conversation is now: tokens used, the model's window, what is free, and where compaction starts (undefined when it is off). */
+    context(): Promise<ContextStatus>;
+    /** What the conversation has spent so far (tokens and replies), counted from the log, so it includes earlier runs of the same session file. */
+    usage(): Promise<UsageTotals>;
+    /** How each MCP server did when the agent was created (for the person running it; the model is not told). Empty without `mcp`. */
+    mcp: Record<string, McpServerStatus>;
+    /** Releases the session file lock. */
+    close(): Promise<void>;
+}
+/** 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 declare function corePlugins(): Plugin[];
+export declare function createAgent(config: AgentConfig): Promise<Agent>;
+export { buildSystemPrompt } from "./system-prompt.js";
+export { bundle, compose, CompositionError } from "./compose.js";
+export type { Composable } from "./compose.js";

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

@@ -0,0 +1,161 @@
+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 { CODEMODE_TOOL, 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, forkLog, openFileLog } from "../../session/src/index.js";
+import { compose } from "./compose.js";
+import { restrictTools } from "./restrict-tools.js";
+import { buildSystemPrompt } from "./system-prompt.js";
+import { createWaker } from "./wake.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 isClient = (model) => "stream" in model;
+export async function createAgent(config) {
+    const cwd = config.cwd ?? process.cwd();
+    if (config.confine && config.environment)
+        throw new Error("confine applies to the default local environment; for your own environment build it with createLocalEnvironment(cwd, { confine: true })");
+    const env = config.environment ?? createLocalEnvironment(cwd, config.confine ? { confine: true } : {});
+    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 = (config.tools ?? ["read", "write", "edit", "bash"]).map((entry) => (typeof entry === "string" ? builtinTools([entry], { bash: bashOptions })[0] : entry));
+    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 } : {}),
+            // an image path that a tool returned is a path in the environment, which may be another machine
+            resolveImage: async (ref, mediaType) => `data:${mediaType};base64,${Buffer.from(await env.readFile(ref)).toString("base64")}`,
+        });
+    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,
+            ...(env.description !== undefined ? { description: env.description } : {}),
+            ...(config.rules ? { rules: config.rules } : {}),
+        });
+    // 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 reviewer = plugins.find((plugin) => typeof plugin.authorize === "function");
+    const authorize = reviewer?.authorize;
+    if (mcpTools.length > 0 && expose === "codemode") {
+        plugins.push(codemodePlugin({ catalog: mcpTools, ...(authorize ? { authorize } : {}) }));
+        // every call a script makes is reviewed one by one, so the script as a whole is not reviewed again
+        reviewer?.exempt?.(CODEMODE_TOOL);
+    }
+    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: [...(definition.tools ? restrictTools(inherited, definition.tools) : inherited), ...(maxTurns !== undefined ? [limitsPlugin({ maxTurns })] : [])],
+                ...(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 } : {}),
+        onSignal: (_log, _text, options) => waker.signalled(options),
+        ...(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;
+    const waker = createWaker({
+        setting: config.wake,
+        pending: () => kernel.pending(log),
+        start: (input) => start(input),
+        busy: () => active !== undefined,
+    });
+    function start(input, options) {
+        waker.started();
+        const handle = kernel.run(log, input, options);
+        active = handle;
+        const ended = (cancelled) => {
+            if (active === handle)
+                active = undefined;
+            waker.ended(cancelled);
+        };
+        void handle.result.then((result) => ended(result.reason === "cancelled"), () => ended(false));
+        return handle;
+    }
+    return {
+        log,
+        mcp: connection?.status ?? {},
+        rewindTo: (entryId) => log.rewindTo(entryId),
+        fork: async (path, upTo) => {
+            await forkLog(log, path, { cwd: env.cwd, ...(upTo !== undefined ? { upTo } : {}), ...(fileLog ? { sessionId: fileLog.header.id } : {}) });
+        },
+        pending: () => kernel.pending(log),
+        goal: () => kernel.goal(log),
+        setGoal: (goal) => kernel.setGoal(log, goal),
+        clearGoal: () => kernel.clearGoal(log),
+        context: () => kernel.context(log),
+        usage: () => kernel.usage(log),
+        run: (input, options) => start(input, options),
+        queue: (text) => active?.queue(text),
+        steer: (text) => active?.steer(text),
+        cancel: () => active?.cancel(),
+        close: async () => {
+            waker.close();
+            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/restrict-tools.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "../../kernel/src/index.js";
+/**
+ * The plugins as a sub-agent with a limited tool list sees them: a tool a plugin registers is kept only if its name is on the list, the same rule
+ * that applies to the built-in tools. Everything else about the plugins stays as it is.
+ */
+export declare function restrictTools(plugins: readonly Plugin[], allowed: readonly string[]): Plugin[];

package/dist/packages/agent/src/restrict-tools.js

@@ -0,0 +1,11 @@
+/**
+ * The plugins as a sub-agent with a limited tool list sees them: a tool a plugin registers is kept only if its name is on the list, the same rule
+ * that applies to the built-in tools. Everything else about the plugins stays as it is.
+ */
+export function restrictTools(plugins, allowed) {
+    const names = new Set(allowed);
+    return plugins.map((plugin) => ({
+        ...plugin,
+        setup: (api) => plugin.setup({ ...api, registerTool: (tool) => (names.has(tool.name) ? api.registerTool(tool) : undefined) }),
+    }));
+}

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

@@ -0,0 +1,15 @@
+import type { Tool } from "../../kernel/src/index.js";
+export interface SystemPromptOptions {
+    tools: readonly Tool[];
+    cwd: string;
+    platform: string;
+    /**
+     * What the environment says about where the tools run (Environment.description). When there is one, it takes the place of the platform line,
+     * because the platform of this machine is then not where the commands run.
+     */
+    description?: 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}\n${options.description !== undefined ? `Where your tools run: ${options.description}` : `Platform: ${options.platform}`}\n</environment>`,
+    ]
+        .filter((section) => section !== "")
+        .join("\n\n");
+}

package/dist/packages/agent/src/wake.d.ts

@@ -0,0 +1,41 @@
+import type { RunHandle } from "../../kernel/src/index.js";
+/** What the application can ask for. */
+export interface WakeSetting {
+    /** Receives every run the agent starts by itself, to show its events. */
+    onRun(handle: RunHandle): void;
+    /** How long a quiet agent with work still under way is left before it is woken once to check on it (default 4 minutes, a little under the prompt cache lifetime). */
+    cacheCheckMs?: number;
+}
+export interface WakerOptions {
+    /** The application's setting; with none, the agent is woken only for work that asked for it. */
+    setting: WakeSetting | undefined;
+    /** What the kernel says is waiting: notices the agent has not been told yet, and work that is still under way. */
+    pending(): {
+        signals: string[];
+        watching: string[];
+    };
+    /** Starts a run on the agent's conversation. With no input it tells the agent what is waiting. */
+    start(input?: string): RunHandle;
+    /** Whether a run is going now. */
+    busy(): boolean;
+}
+/**
+ * When the agent starts a run by itself. It decides three things and keeps the state they need in one place:
+ *   - when background work ends and the agent is quiet, a run starts so that it hears about it, if the application asked for that in general or the work asked
+ *     for it in particular (the work's own wish wins);
+ *   - a quiet agent with work still under way is woken once to check on it before the prompt cache expires, then left alone until something ends;
+ *   - after a run that was cancelled nothing starts by itself: whoever cancelled wanted it to stop, and what is waiting is told in the next run.
+ */
+export interface Waker {
+    /** Background work ended. `options.wake` is what that work asked for; left out, the application's setting decides. */
+    signalled(options?: {
+        wake?: boolean;
+    }): void;
+    /** A run is starting. It tells the agent everything that is waiting. */
+    started(): void;
+    /** A run ended. */
+    ended(cancelled: boolean): void;
+    /** No more runs by itself. */
+    close(): void;
+}
+export declare function createWaker(options: WakerOptions): Waker;

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

@@ -0,0 +1,71 @@
+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.`;
+/** The run of an agent that woke itself when the application gave no setting: nobody shows it, the log has all of it. */
+async function drain(handle) {
+    for await (const _event of handle.events)
+        void _event;
+}
+export function createWaker(options) {
+    const { setting } = options;
+    let timer;
+    let closed = false;
+    let checkUsed = false; // the one check per quiet period has been made
+    let owed = false; // something that asked to wake the agent ended, and no run has told it yet
+    function wakeWith(input) {
+        if (closed || options.busy())
+            return;
+        const handle = options.start(input);
+        if (setting)
+            setting.onRun(handle);
+        else
+            void drain(handle);
+    }
+    return {
+        signalled(wish) {
+            if (!(wish?.wake ?? setting !== undefined))
+                return;
+            clearTimeout(timer);
+            checkUsed = false;
+            owed = true;
+            wakeWith(); // while a run is going, it delivers the notice itself or `ended` does
+        },
+        started() {
+            owed = false;
+        },
+        ended(cancelled) {
+            if (closed)
+                return;
+            if (cancelled) {
+                owed = false;
+                clearTimeout(timer);
+                return;
+            }
+            const pending = options.pending();
+            if (pending.signals.length > 0 && (setting || owed)) {
+                wakeWith();
+                return;
+            }
+            if (pending.signals.length === 0)
+                owed = false;
+            if (!setting)
+                return; // the check before the cache expires is the application's to ask for
+            if (pending.watching.length === 0 || checkUsed)
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                const now = options.pending();
+                if (now.signals.length > 0)
+                    return wakeWith();
+                if (now.watching.length === 0)
+                    return;
+                checkUsed = true;
+                wakeWith(checkInput(now.watching));
+            }, setting.cacheCheckMs ?? CACHE_CHECK_MS);
+            timer.unref();
+        },
+        close() {
+            closed = true;
+            clearTimeout(timer);
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+/** Thrown when a confined environment is asked for something outside its working directory. */
+export declare class OutsideDirectoryError extends Error {
+    readonly path: string;
+    readonly root: string;
+    constructor(path: string, root: string);
+}
+/** Whether an absolute, normalised path is the root or below it, by text ("/work-evil" is not inside "/work"). */
+export declare const isInside: (root: string, path: string) => boolean;
+/**
+ * Where a path really is, following links, for a path that may not exist yet: the real location of its deepest existing ancestor, plus the
+ * names below it. A link that points nowhere is not followed blindly (writing through it would create its target): it counts as outside.
+ */
+export declare function realLocation(path: string, root: string): Promise<string>;

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

@@ -0,0 +1,40 @@
+import { lstat, realpath } from "node:fs/promises";
+import { basename, dirname, resolve, sep } from "node:path";
+/** Thrown when a confined environment is asked for something outside its working directory. */
+export class OutsideDirectoryError extends Error {
+    path;
+    root;
+    constructor(path, root) {
+        super(`${path} is outside the working directory ${root}`);
+        this.name = "OutsideDirectoryError";
+        this.path = path;
+        this.root = root;
+    }
+}
+/** Whether an absolute, normalised path is the root or below it, by text ("/work-evil" is not inside "/work"). */
+export const isInside = (root, path) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+/**
+ * Where a path really is, following links, for a path that may not exist yet: the real location of its deepest existing ancestor, plus the
+ * names below it. A link that points nowhere is not followed blindly (writing through it would create its target): it counts as outside.
+ */
+export async function realLocation(path, root) {
+    const below = [];
+    let current = path;
+    while (true) {
+        try {
+            return resolve(await realpath(current), ...below.reverse());
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw error;
+            if (await lstat(current).then(() => true, () => false))
+                throw new OutsideDirectoryError(path, root); // a dangling link
+            const parent = dirname(current);
+            if (parent === current)
+                throw error;
+            below.push(basename(current));
+            current = parent;
+        }
+    }
+}

package/dist/packages/env/src/connect-ssh.d.ts

@@ -0,0 +1,33 @@
+import type { RemoteRunner } from "./remote.js";
+export interface SshOptions {
+    /** What to connect to: a name from ~/.ssh/config, or user@host. Authentication, keys and host keys are whatever ssh is set up to do. */
+    host: string;
+    port?: number;
+    identityFile?: string;
+    /** Extra ssh options, written as `-o Name=value` (ProxyJump, StrictHostKeyChecking, ...). */
+    options?: Record<string, string>;
+    /** Seconds to wait for a connection to be made (default 15). */
+    connectTimeoutSec?: number;
+    /** The ssh program to run (default "ssh"). */
+    ssh?: string;
+}
+export interface SshConnection {
+    /** Runs a command on the remote machine over the connection. Rejects with RemoteConnectionError when ssh could not reach it. */
+    run: RemoteRunner;
+    /** Hangs up and removes what was made on this machine. Safe to call more than once. */
+    close(): Promise<void>;
+}
+/**
+ * Opens one connection to the machine and runs every command over it. The first ssh logs in (once) and stays in the background; each later ssh finds it
+ * through a socket in a directory of ours and only starts a new process on the other side, so a command costs milliseconds and not a login. If the
+ * connection dies, the next command makes a new one by itself. Nothing is promised about the connection: when it cannot be reached, the command's
+ * result is a RemoteConnectionError and the caller says so.
+ */
+export declare function connectSsh(options: SshOptions): Promise<SshConnection>;
+/** What the model is told about where its tools run, over ssh. */
+export declare function describeSsh(host: string, cwd: string): string;
+/** An environment whose tools run on another machine over ssh. Close it (or dispose of the agent) to hang up. */
+export declare function createSshEnvironment(options: SshOptions & {
+    cwd: string;
+    workDir?: string;
+}): Promise<import("../../kernel/src/index.js").Environment>;