sakura-agent 0.1.0 → 0.1.1

package/THIRD_PARTY_NOTICES.md

@@ -1,63 +1,13 @@
 # Third-party notices
 
-This file registers every piece of third-party code that is copied, ported, or
-vendored into this repository. Entries under "Copied or ported" are the authoritative list; the
-"Planned sources" table lists upstream projects we may still borrow from.
+Sakura borrows from a few other projects. Where code or text was copied or adapted, the source file says so in its header, and the licence text is kept in `licenses/`.
 
-Rule: borrowing a design idea does not need an entry. Copying or porting code
-(including translating it to another language) does. Each ported file must carry
-a header comment naming its source, and a check script must fail the build when a
-ported file has no header (planned for milestone M0).
+| Project | Licence | What Sakura took |
+|---|---|---|
+| [Pi](https://github.com/badlogic/pi-mono) (Mario Zechner) | MIT | The edit-matching code in `packages/plugins/tools/src/edit-match.ts`, and the wording of the `read`, `write`, `edit` and `bash` tool descriptions, adapted. The structure and some rules of the system prompt follow Pi's. |
+| [gitleaks](https://github.com/gitleaks/gitleaks) (Zachary Rice) | MIT | The secret-detection rules in `packages/plugins/redaction/src/rules.gen.ts`, converted to TypeScript. |
+| [OpenAI Codex](https://github.com/openai/codex) | Apache-2.0 | Ideas only: some task-execution principles in the system prompt, reworded. No code or text is copied. |
 
-## Copied or ported
+Dependency: [`quickjs-emscripten`](https://github.com/justjake/quickjs-emscripten) (MIT) runs the code-mode scripts. It is installed from npm, not copied.
 
-### packages/plugins/tools/src/edit-match.ts
-- Source: Pi (`pi-mono`), path `packages/coding-agent/src/core/tools/edit-diff.ts`, source snapshot dated 2026-10-04 (npm 1.5.0 was current at the time)
-- Licence: MIT
-- Copyright: Copyright (c) 2025 Mario Zechner
-- Changes: removed the diff-rendering helpers and the file-system and `diff` package imports; restructured into one `applyEdits` function; kept the fuzzy matching, line-ending handling, overlap detection, line-preserving replacement and the error messages
-- Licence text: `licenses/pi-mono-MIT.txt`
-
-### packages/plugins/tools/src/builtin/{read,write,edit,bash}.ts (tool descriptions)
-- Source: Pi (`pi-mono`), `packages/coding-agent/src/core/tools/{read,write,edit,bash}.ts` (description texts); the implementations are written fresh
-- Licence: MIT
-- Copyright: Copyright (c) 2025 Mario Zechner
-- Changes: shortened and reworded for our tool contracts (timeouts, non-interactive commands)
-- Licence text: `licenses/pi-mono-MIT.txt`
-
-### packages/agent/src/system-prompt.ts (rule texts)
-- Source: Pi (`pi-mono`) `packages/coding-agent/src/core/system-prompt.ts` and tool prompt snippets (structure and some rules); OpenAI Codex `codex-rs/protocol/src/prompts/base_instructions/default.md` (task-execution, validation and final-message principles)
-- Licence: Pi MIT; Codex Apache-2.0
-- Copyright: Copyright (c) 2025 Mario Zechner (Pi); OpenAI (Codex)
-- Changes: principles condensed and reworded into 11 general rules plus per-tool rules; no text copied verbatim from Codex; Pi's section layout (preamble, tools, rules, environment) followed
-- Licence text: `licenses/pi-mono-MIT.txt`, `licenses/codex-Apache-2.0.txt`
-
-### packages/plugins/redaction/src/rules.gen.ts (generated)
-- Source: gitleaks (`gitleaks/gitleaks`), `config/gitleaks.toml`, source snapshot dated 2026-11-06. The public workspace includes the generated rule table.
-- Licence: MIT
-- Copyright: Copyright (c) 2019 Zachary Rice
-- Changes: converted by `scripts/gen-secret-rules.py` into TypeScript data (regular expressions translated to JavaScript, 22 of 221 rules skipped because they do not translate; allowlists not used)
-- Licence text: `licenses/gitleaks-MIT.txt`
-
-## Planned sources (not yet copied)
-
-| Source | Licence | Upstream | Intended use | Status |
-|---|---|---|---|---|
-| Pi (`pi-mono`) | MIT, copyright Mario Zechner | `earendil-works/pi` | Edit-tool matching and the read/write/edit/bash tool descriptions are now ported (see below); system-prompt structure may follow; mcp client and codemode ideas | partly copied (see below) |
-| Magpie | MIT | `yetone/magpie` | Design reference for redaction (stable placeholders, streaming restore, fail closed). Not a code port any more (decision: only the essence) | not copied |
-| gitleaks | MIT (Zachary Rice) | `gitleaks/gitleaks` | Rule table converted for the redaction plugin (see above) | copied (see above) |
-| Codex | Apache-2.0 | `openai/codex` | Design reference (guardian reviewer, goal, compaction); base-instructions principles adapted into our system prompt (`protocol/src/prompts/base_instructions/default.md`), with changes noted. Other prompt texts are written fresh; if any text or code is copied, add an entry and keep the Apache-2.0 notice | not copied |
-| A2A | Apache-2.0 | `a2aproject/A2A` | Possible future protocol reference | not copied |
-| `quickjs-emscripten` | MIT (Fabrice Bellard's QuickJS, Jake Teton-Landis's bindings; checked on npm, all 7 installed packages report MIT) | npm | Runtime dependency of `packages/plugins/toolset` (codemode sandbox). Not copied, only installed. `quickjs-wasi` was the other candidate (also MIT), not used | dependency |
-| Mastra | not verified (GitHub reports NOASSERTION) | `mastra-ai/mastra` | Design reference only. **Do not copy code until the licence is read.** | not copied |
-
-## Entry format (use when code is actually copied or ported)
-
-```
-### <file or component in this repo>
-- Source: <repository URL>, path <path>, commit <hash>
-- Licence: <SPDX id>
-- Copyright: <holder, year>
-- Changes: <what was changed or translated>
-- Licence text: <path to the full licence text kept in this repository>
-```
+Licence texts: `licenses/pi-mono-MIT.txt`, `licenses/gitleaks-MIT.txt`, `licenses/codex-Apache-2.0.txt`.

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

@@ -1,8 +1,10 @@
 import type { ChatCompat } from "../../llm/src/index.js";
-import type { CompactionConfig, Environment, LlmClient, Plugin, Prompts, RunHandle, ThinkingLevel, UserInput } from "../../kernel/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;
@@ -16,15 +18,25 @@ export interface AgentConfig {
     /** A provider to talk to, or a ready-made client (for tests). */
     model: ModelConfig | LlmClient;
     cwd?: string;
-    tools?: Array<"read" | "write" | "edit" | "bash">;
+    /**
+     * 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, sandbox, sub-agents) are never in the default set. May contain bundles and plugins that say what they require; see compose(). */
+    /** 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;
@@ -41,15 +53,14 @@ export interface AgentConfig {
      * 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?: {
-        onRun(handle: RunHandle): void;
-        cacheCheckMs?: number;
-    };
+    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, where read-only
-     * tools can be called from a script. The default is "direct" up to 10 tools and "search" above.
+     * `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>;
@@ -71,14 +82,41 @@ export interface AgentConfig {
     };
 }
 export interface Agent {
-    /** Starts, resumes or follows up. See Kernel.run. */
-    run(input?: UserInput): RunHandle;
+    /**
+     * 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. */

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

@@ -3,24 +3,26 @@ 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 { 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, openFileLog } from "../../session/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 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);
+    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");
@@ -28,7 +30,7 @@ export async function createAgent(config) {
         ...(config.bashSoftTimeoutMs !== undefined ? { softTimeoutMs: config.bashSoftTimeoutMs } : {}),
         ...(config.bashBackgroundGraceMs !== undefined ? { backgroundGraceMs: config.bashBackgroundGraceMs } : {}),
     };
-    const tools = builtinTools(config.tools, { bash: bashOptions });
+    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
@@ -39,11 +41,20 @@ export async function createAgent(config) {
             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 });
+    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"]);
@@ -51,9 +62,13 @@ export async function createAgent(config) {
     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")
+    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) {
@@ -65,7 +80,7 @@ export async function createAgent(config) {
                 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,
+                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 } : {}),
@@ -90,7 +105,7 @@ export async function createAgent(config) {
         ...(config.maxTokens !== undefined ? { maxTokens: config.maxTokens } : {}),
         ...(thinking !== undefined ? { thinking } : {}),
         ...(config.now ? { now: config.now } : {}),
-        ...(config.wake ? { onSignal: () => onBackgroundEnd() } : {}),
+        onSignal: (_log, _text, options) => waker.signalled(options),
         ...(config.compaction !== undefined ? { compaction: config.compaction } : {}),
         ...(config.goal ? { goal: config.goal } : {}),
         ...(config.prompts ? { prompts: config.prompts } : {}),
@@ -98,63 +113,43 @@ export async function createAgent(config) {
     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);
+    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;
-        void handle.result.finally(() => {
+        const ended = (cancelled) => {
             if (active === handle)
                 active = undefined;
-            afterRun();
-        });
+            waker.ended(cancelled);
+        };
+        void handle.result.then((result) => ended(result.reason === "cancelled"), () => ended(false));
         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),
+        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 () => {
-            closed = true;
-            clearTimeout(timer);
+            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()));

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

@@ -3,6 +3,11 @@ 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[];
 }

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

@@ -42,7 +42,7 @@ export function buildSystemPrompt(options) {
         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>`,
+        `<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>;