sakura-agent 0.1.0 → 0.1.1

package/dist/packages/llm/src/chat/retry.js

@@ -5,7 +5,7 @@ export const defaultRetry = {
     baseDelayMs: 500,
     maxDelayMs: 32_000,
     maxServerDelayMs: 60_000,
-    maxStallRetries: 1,
+    maxStallRetries: 4,
     sleep: (ms, signal) => new Promise((resolve, reject) => {
         if (signal.aborted)
             return reject(Object.assign(new Error("aborted"), { name: "AbortError" }));

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

@@ -16,8 +16,13 @@ async function* watchIdle(source, ms, cancel) {
             const stalled = new Promise((resolve) => {
                 timer = setTimeout(() => resolve("stalled"), ms);
             });
-            const result = await Promise.race([next, stalled]);
-            clearTimeout(timer);
+            let result;
+            try {
+                result = await Promise.race([next, stalled]);
+            }
+            finally {
+                clearTimeout(timer); // also when the read fails (a cancel, a broken connection): a timer left running keeps the process alive
+            }
             if (result === "stalled") {
                 cancel();
                 throw new StalledStreamError(Math.round(ms / 1000));

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

@@ -21,6 +21,7 @@ export interface ContextPlugin extends Plugin {
 /**
  * Puts project instructions (AGENTS.md) at the start of the conversation as a pinned message, once.
  * They survive compaction and are not summarised. Only the AGENTS.md name is understood; there is no
- * parent-directory search, no per-directory loading and no @path includes.
+ * parent-directory search, no per-directory loading and no @path includes. A changed file replaces the instructions after the next compaction;
+ * a file that is removed or emptied does not take them back.
  */
 export declare function contextPlugin(options?: ContextOptions): ContextPlugin;

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

@@ -13,7 +13,8 @@ async function readSource(env, source, maxBytes) {
 /**
  * Puts project instructions (AGENTS.md) at the start of the conversation as a pinned message, once.
  * They survive compaction and are not summarised. Only the AGENTS.md name is understood; there is no
- * parent-directory search, no per-directory loading and no @path includes.
+ * parent-directory search, no per-directory loading and no @path includes. A changed file replaces the instructions after the next compaction;
+ * a file that is removed or emptied does not take them back.
  */
 export function contextPlugin(options = {}) {
     const fileName = options.fileName ?? "AGENTS.md";

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

@@ -8,7 +8,10 @@ export interface Budget {
     maxTokens?: number;
     /** Stop after this much spend in the session; needs `prices`. */
     maxCostUsd?: number;
-    /** Stop a single run that has been going this long. */
+    /**
+     * Stop a single run that has been going this long. This is checked at the end of each turn, not during one: a turn that is under way (a model
+     * request, a command) finishes first, and what stops those is their own limits. So it is a budget, not a hard deadline.
+     */
     maxRunSeconds?: number;
 }
 export interface LimitsOptions extends Budget {

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

@@ -20,6 +20,9 @@ export interface RedactionPlugin extends Plugin {
  * Keeps secrets away from the model. Every request is scanned; secrets become stable placeholders, and the model's
  * reply (text and tool arguments) gets the real values back before anything runs or is saved. If scanning fails the
  * request is not sent. Off unless you add it.
+ *
+ * It protects what is sent to the model provider, not what is stored here: the log (the session file), the events and any trace keep the real values,
+ * because the tools need them and a resumed session is read from the log. Use `scrub` on anything you export or share.
  */
 export declare function redactionPlugin(options?: RedactionOptions): RedactionPlugin;
 export type { SecretRule } from "./engine.js";

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

@@ -9,6 +9,9 @@ const MAX_REMEMBERED = 5000;
  * Keeps secrets away from the model. Every request is scanned; secrets become stable placeholders, and the model's
  * reply (text and tool arguments) gets the real values back before anything runs or is saved. If scanning fails the
  * request is not sent. Off unless you add it.
+ *
+ * It protects what is sent to the model provider, not what is stored here: the log (the session file), the events and any trace keep the real values,
+ * because the tools need them and a resumed session is read from the log. Use `scrub` on anything you export or share.
  */
 export function redactionPlugin(options = {}) {
     const engine = createEngine({ ...(options.key ? { key: options.key } : {}), ...(options.rules ? { rules: options.rules } : {}) });

package/dist/packages/plugins/redaction/src/rules.gen.js

@@ -1,4 +1,4 @@
-// Generated by scripts/gen-secret-rules.py from the gitleaks rule table.
+// Generated from the gitleaks rule table.
 // gitleaks: https://github.com/gitleaks/gitleaks, MIT License, Copyright (c) 2019 Zachary Rice.
 // The licence text is in licenses/gitleaks-MIT.txt. Do not edit by hand.
 export const gitleaksRules = [

package/dist/packages/plugins/review/src/chain.d.ts

@@ -13,6 +13,8 @@ export interface ReviewContext {
     log: Log;
     signal: AbortSignal;
     tool(name: string): Tool | undefined;
+    /** The working directory the call runs in. Paths that leave it are not waved through as read-only. */
+    cwd?: string;
 }
 /** One link of the chain. `pass` hands the call to the next link. */
 export interface Authorizer {

package/dist/packages/plugins/review/src/chain.js

@@ -1,3 +1,4 @@
+import { describeFailure } from "../../../kernel/src/index.js";
 /**
  * Asks each authorizer in turn. The first answer that is not `pass` wins. The chain always ends in an answer:
  * if every authorizer passes (or one fails), the call is denied. An empty chain is the caller's choice to skip review.
@@ -11,7 +12,7 @@ export async function runChain(authorizers, call, context) {
         catch (error) {
             return {
                 kind: "deny",
-                reason: `The safety check '${authorizer.name}' failed (${error instanceof Error ? error.message : String(error)}), so the action was not allowed.`,
+                reason: `The safety check '${authorizer.name}' failed (${describeFailure(error)}), so the action was not allowed.`,
                 decidedBy: authorizer.name,
             };
         }

package/dist/packages/plugins/review/src/hard-rules.d.ts

@@ -1,7 +1,13 @@
 import type { Authorizer } from "./chain.js";
+/** Whether a word contains a variable or command substitution, so what it stands for cannot be told from the text. */
+export declare function mayExpand(word: string): boolean;
+export declare function mayLeaveDirectory(word: string, cwd: string | undefined): boolean;
 export declare function mentionsSensitivePath(text: string): boolean;
 /**
  * Deterministic rules, no model: read-only calls are allowed, catastrophic ones are refused, everything else
  * is passed on. Reading credentials counts as sensitive and is passed on instead of allowed.
  */
+export declare function createHardRules(options?: {
+    directoryRules?: boolean;
+}): Authorizer;
 export declare const hardRules: Authorizer;

package/dist/packages/plugins/review/src/hard-rules.js

@@ -1,3 +1,4 @@
+import { posix } from "node:path";
 import { parseShell } from "./shell.js";
 const READ_ONLY = new Set([
     "ls",
@@ -88,6 +89,31 @@ const CATASTROPHIC = [
     [new RegExp(`${RUNS}(shutdown|reboot|halt|poweroff)(\\s|[);&|]|$)`), "shutting the machine down"],
     [/(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(sh|bash|zsh|dash|ksh|python3?|perl|ruby|node)\b/, "running downloaded code without looking at it"],
 ];
+/**
+ * Whether a word of a command may point outside the working directory, or cannot be told. Such a word sends a read-only call on to the
+ * next link (the reviewer) instead of waving it through. Only the text is read: a symbolic link inside the directory is not followed.
+ */
+const optionValue = (word) => (word.startsWith("-") ? (word.includes("=") ? word.slice(word.indexOf("=") + 1) : "") : word);
+/** Whether a word contains a variable or command substitution, so what it stands for cannot be told from the text. */
+export function mayExpand(word) {
+    return /[$`]/.test(optionValue(word));
+}
+export function mayLeaveDirectory(word, cwd) {
+    const value = optionValue(word);
+    if (value === "")
+        return false;
+    if (/[$`]/.test(value) || value.startsWith("~"))
+        return true;
+    if (value.startsWith("/")) {
+        if (cwd === undefined)
+            return true;
+        const root = posix.normalize(cwd).replace(/\/+$/, "");
+        const target = posix.normalize(value);
+        return !(target === root || target.startsWith(`${root}/`));
+    }
+    const target = posix.normalize(value);
+    return target === ".." || target.startsWith("../");
+}
 export function mentionsSensitivePath(text) {
     return SENSITIVE.test(text);
 }
@@ -95,29 +121,36 @@ export function mentionsSensitivePath(text) {
  * Deterministic rules, no model: read-only calls are allowed, catastrophic ones are refused, everything else
  * is passed on. Reading credentials counts as sensitive and is passed on instead of allowed.
  */
-export const hardRules = {
-    name: "hard-rules",
-    async review(call, { tool }) {
-        const args = (typeof call.args === "object" && call.args !== null ? call.args : {});
-        if (call.name === "bash" || tool(call.name)?.effect === "exec") {
-            const command = typeof args.command === "string" ? args.command : "";
-            for (const [pattern, what] of CATASTROPHIC) {
-                if (pattern.test(command))
-                    return { kind: "deny", reason: `This command looks like ${what}. It is never allowed.` };
+export function createHardRules(options = {}) {
+    const directoryRules = options.directoryRules !== false;
+    return {
+        name: "hard-rules",
+        async review(call, { tool, cwd }) {
+            const outside = (word) => (directoryRules ? mayLeaveDirectory(word, cwd) : mayExpand(word));
+            const args = (typeof call.args === "object" && call.args !== null ? call.args : {});
+            if (call.name === "bash" || tool(call.name)?.effect === "exec") {
+                const command = typeof args.command === "string" ? args.command : "";
+                for (const [pattern, what] of CATASTROPHIC) {
+                    if (pattern.test(command))
+                        return { kind: "deny", reason: `This command looks like ${what}. It is never allowed.` };
+                }
+                const parsed = parseShell(command);
+                if (parsed.complex || parsed.writesFile || parsed.commands.length === 0)
+                    return { kind: "pass" };
+                if (!parsed.commands.every(commandIsReadOnly))
+                    return { kind: "pass" };
+                if (mentionsSensitivePath(command))
+                    return { kind: "pass" };
+                if (parsed.commands.some((words) => words.slice(1).some(outside)))
+                    return { kind: "pass" };
+                return { kind: "allow", reason: "read-only command" };
             }
-            const parsed = parseShell(command);
-            if (parsed.complex || parsed.writesFile || parsed.commands.length === 0)
-                return { kind: "pass" };
-            if (!parsed.commands.every(commandIsReadOnly))
-                return { kind: "pass" };
-            if (mentionsSensitivePath(command))
-                return { kind: "pass" };
-            return { kind: "allow", reason: "read-only command" };
-        }
-        if (tool(call.name)?.effect === "read") {
-            const path = typeof args.path === "string" ? args.path : "";
-            return mentionsSensitivePath(path) ? { kind: "pass" } : { kind: "allow", reason: "read-only tool" };
-        }
-        return { kind: "pass" };
-    },
-};
+            if (tool(call.name)?.effect === "read") {
+                const path = typeof args.path === "string" ? args.path : "";
+                return mentionsSensitivePath(path) || outside(path) ? { kind: "pass" } : { kind: "allow", reason: "read-only tool" };
+            }
+            return { kind: "pass" };
+        },
+    };
+}
+export const hardRules = createHardRules();

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

@@ -16,6 +16,12 @@ export interface ReviewOptions {
     /** The model that reviews. Usually the same one as the agent's. */
     llm: LlmClient;
     policy?: PolicyInput;
+    /**
+     * By default a read-only command or tool that points outside the working directory is not allowed by the hard rules but sent to the reviewer.
+     * `false` removes that rule, for an application where the agent works on the whole machine and has no working directory in that sense. The other rules
+     * stay: commands that write, expansions the text cannot show, credentials and the catastrophic patterns.
+     */
+    directoryRules?: boolean;
     /** Extra authorizers, asked after the hard rules and before the reviewer. */
     authorizers?: Authorizer[];
     timeoutMs?: number;
@@ -27,6 +33,8 @@ export interface AuthorizeContext {
     log: Log;
     signal: AbortSignal;
     tool(name: string): Tool | undefined;
+    /** The working directory the call runs in (optional; without it any absolute path counts as outside). */
+    cwd?: string;
 }
 export interface ReviewPlugin extends Plugin {
     /**
@@ -36,6 +44,11 @@ export interface ReviewPlugin extends Plugin {
     authorize(call: ToolCall, context: AuthorizeContext): Promise<Extract<Decision, {
         kind: "allow" | "deny";
     }>>;
+    /**
+     * Stops the loop from reviewing calls to this tool itself. For a tool that only runs other tools and has each of them reviewed through `authorize`
+     * (code mode's `run_code`), so one script is not reviewed twice. `createAgent` does this for code mode; a plugin wired by hand is reviewed as a whole unless told.
+     */
+    exempt(toolName: string): void;
 }
 /**
  * Automatic review of tool calls, with nobody to ask: hard rules, then any extra authorizers, then a reviewer

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

@@ -1,5 +1,5 @@
 import { runChain } from "./chain.js";
-import { hardRules } from "./hard-rules.js";
+import { createHardRules } from "./hard-rules.js";
 import { resolvePolicy } from "./policy.js";
 import { createReviewer } from "./reviewer.js";
 const stable = (value) => JSON.stringify(value, (_key, inner) => (inner && typeof inner === "object" && !Array.isArray(inner) ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => a.localeCompare(b))) : inner));
@@ -13,7 +13,7 @@ export function reviewPlugin(options) {
     const states = new WeakMap();
     const fresh = () => ({ verdicts: new Map(), recent: [], consecutive: 0, tripped: false });
     const reviewer = createReviewer({ llm: options.llm, policy, ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}) });
-    const chain = [hardRules, ...(options.authorizers ?? []), reviewer];
+    const chain = [createHardRules({ directoryRules: options.directoryRules !== false }), ...(options.authorizers ?? []), reviewer];
     function record(state, refused) {
         state.recent.push(refused);
         if (state.recent.length > (options.breaker?.window?.size ?? 50))
@@ -24,6 +24,7 @@ export function reviewPlugin(options) {
             state.tripped = true;
     }
     let emit = () => undefined;
+    const exempted = new Set();
     async function authorize(call, context) {
         const state = states.get(context.log) ?? fresh();
         states.set(context.log, state);
@@ -31,13 +32,15 @@ export function reviewPlugin(options) {
             return { kind: "deny", reason: "Too many actions were refused in this run, so further actions are blocked until the owner looks at it." };
         const key = `${call.name}\u0000${stable(call.args)}`;
         const cached = state.verdicts.get(key);
-        const result = cached ? { ...cached, decidedBy: "cache" } : await runChain(chain, call, { log: context.log, signal: context.signal, tool: context.tool });
+        const result = cached
+            ? { ...cached, decidedBy: "cache" }
+            : await runChain(chain, call, { log: context.log, signal: context.signal, tool: context.tool, ...(context.cwd !== undefined ? { cwd: context.cwd } : {}) });
         if (!cached) {
             if (result.decidedBy === "reviewer")
                 state.verdicts.set(key, { kind: result.kind, reason: result.reason });
             record(state, result.kind === "deny");
         }
-        emit({ kind: "review", tool: call.name, outcome: result.kind, decidedBy: result.decidedBy, reason: result.reason });
+        emit({ kind: "review", tool: call.name, callId: call.id, outcome: result.kind, decidedBy: result.decidedBy, reason: result.reason });
         if (result.kind === "allow")
             return { kind: "allow" };
         return { kind: "deny", reason: `${result.reason} Do not try the same action again; choose another approach, or tell the user what you need.` };
@@ -46,12 +49,13 @@ export function reviewPlugin(options) {
         name: "review",
         compensates: "models act without anyone checking the risky ones",
         authorize,
+        exempt: (toolName) => void exempted.add(toolName),
         async prepare({ log }) {
             states.set(log, fresh()); // decisions are remembered within one run only
         },
         setup(api) {
             emit = api.emit;
-            api.on("tool.before", (call, context) => authorize(call, context));
+            api.on("tool.before", (call, context) => exempted.has(call.name) ? undefined : authorize(call, { log: context.log, signal: context.signal, tool: context.tool, cwd: context.env.cwd }));
             api.on("turn.end", ({ log }) => (states.get(log)?.tripped ? { pause: "approval" } : undefined));
         },
     };

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

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

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

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