sakura-agent 0.1.0 → 0.1.2

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,45 @@
+import type { RemoteRunner } from "./remote.js";
+import type { RemoteStreamer } from "./remote-stream.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;
+    /**
+     * How many commands may be running over the connection at once (default 8). A server accepts only so many sessions on one connection (sshd's
+     * MaxSessions is 10 unless changed) and refuses the rest, so the others wait here for a free place. A command that runs in the background keeps its place.
+     * Two of the places are kept for short jobs (reading a file, stopping a command), so at most this number minus two commands run at once.
+     */
+    maxSessions?: number;
+}
+export interface SshConnection {
+    /** Runs a command on the remote machine over the connection. Rejects with RemoteConnectionError when ssh could not reach it. */
+    run: RemoteRunner;
+    /** Runs a command as a streamed child of the connection: its output arrives as it is produced and the child ends when the command does. */
+    stream: RemoteStreamer;
+    /** The directory on this machine that holds the socket of the connection (for diagnostics and tests). */
+    readonly socketDirectory: string;
+    /** 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 it is NOT made again: commands are run with ControlMaster=no and ProxyCommand=false, so an ssh that finds no live master has nowhere to
+ * go and fails at once (by default, ssh_config(5) says, a client that cannot use the socket makes a connection of its own, silently and with a new login).
+ * The result is a RemoteConnectionError that tells the caller to stop and report it.
+ */
+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>;