@ouro.bot/cli 0.1.0-alpha.993 → 0.1.0-alpha.994

package/changelog.json

@@ -1,6 +1,13 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.994",
+      "changes": [
+        "Every agent wakes up with a home kit: paths start in its own home, ls, fetch_url for reading web pages (local and private addresses refused), read, grep, glob and shell that cap their output and say how to see the rest, and multi-edit. The Butler also gets ls, fetch_url, note and diary_write.",
+        "Shell guards follow the new start directory: git inside an agent's home stays with sync, and cd -, ~- and ~+ count as directories the guard cannot follow."
+      ]
+    },
     {
       "version": "0.1.0-alpha.993",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.993",
+  "runtimeVersion": "0.1.0-alpha.994",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.ouro/tool-profiles.json

@@ -2,7 +2,7 @@
   "version": 2,
   "profiles": {
     "sanctuary-owner": {
-      "version": 18,
+      "version": 19,
       "contextScopes": [
         "household.status",
         "household.policy",
@@ -53,7 +53,11 @@
         "edit_file",
         "glob",
         "grep",
+        "ls",
         "web_search",
+        "fetch_url",
+        "note",
+        "diary_write",
         "search_facts",
         "consult_diary",
         "consult_notes",
@@ -148,7 +152,7 @@
       ]
     },
     "sanctuary-agent-peer": {
-      "version": 8,
+      "version": 9,
       "toolNames": [
         "external_event_disposition",
         "query_active_work",
@@ -192,6 +196,7 @@
         "glob",
         "grep",
         "web_search",
+        "fetch_url",
         "search_facts",
         "consult_diary",
         "consult_notes",

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.993</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.994</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/daemon/sanctuary-acceptance-harness.js

@@ -60,7 +60,7 @@ function exactSanctuaryContainmentProfileBoundaries(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
     const boundaries = value;
-    const versions = { "sanctuary-owner": 18, "sanctuary-household": 5, "sanctuary-event": 4 };
+    const versions = { "sanctuary-owner": 19, "sanctuary-household": 5, "sanctuary-event": 4 };
     if (!(0, node_util_1.isDeepStrictEqual)(Object.keys(boundaries).sort(), Object.keys(versions).sort()))
         return false;
     const packageRoot = path.resolve(__dirname, "../../../deploy/unraid/sanctuary.ouro");

package/dist/repertoire/guardrails.js

@@ -65,7 +65,7 @@ const REASONS = {
     needsTrustForWrite: "i'd need a closer friend to vouch for you before i can write files outside my home.",
 };
 // --- read-only tools that never need guardrails ---
-const READ_ONLY_TOOLS = new Set(["read_file", "glob", "grep"]);
+const READ_ONLY_TOOLS = new Set(["read_file", "ls", "glob", "grep"]);
 // --- protected path detection ---
 const PROTECTED_PATH_SEGMENTS = [
     ".git/",
@@ -391,13 +391,13 @@ function friendsShellWriteRefused(command, agentRoot) {
 // A command can name one of this agent's folders by an absolute path, by ~/ or $HOME/, or relative to wherever it cd's (or
 // git -C's) first. Each word whose path has a part exactly `<name>` is resolved against every directory the command could be
 // working in, lexically and canonically, and counts when it lands in this agent's <name>/.
-const UNFOLLOWABLE_WORKING_DIRECTORY = /(?:^|[\s;&|(`])(?:pushd|popd)(?:\s|$)|(?:^|[\s;&|(`])cd\s+(?:--|["']?\$)|\s-C\s*["']?\$|(?:^|[\s;&|(`/])(?:sh|bash|zsh|dash|ksh)\s+(?:-\w+\s+)*-\w*c\b/;
+const UNFOLLOWABLE_WORKING_DIRECTORY = /(?:^|[\s;&|(`])(?:pushd|popd)(?:\s|$)|(?:^|[\s;&|(`])cd\s+(?:--|["']?\$)|\s-C\s*["']?\$|(?:^|[\s;&|(`=<>])~[^/\s]|(?:^|[\s;&|(`/])(?:sh|bash|zsh|dash|ksh)\s+(?:-\w+\s+)*-\w*c\b/;
 /** Words of a shell command that name a path whose part is exactly `name`, wherever they sit (code and quotes included). */
 function namedFolderWords(command, name) {
     const part = new RegExp(`(?:^|/)${name}(?:/|$)`);
     return command.split(/[\s'"=();|&<>`]+/).filter((token) => part.test(token));
 }
-function commandMentionsAgentFolder(command, words, agentRoot, name) {
+function commandMentionsAgentFolder(command, words, agentRoot, name, startIn = [process.cwd()]) {
     const lexicalFolder = path.resolve(agentRoot, name);
     if (globOrExpansionCouldReach(command, lexicalFolder, agentRoot))
         return true;
@@ -419,7 +419,7 @@ function commandMentionsAgentFolder(command, words, agentRoot, name) {
         return true;
     const folders = [lexicalFolder, path.join(canonicalize(path.resolve(agentRoot)), name)];
     // Every directory the command could be working in: where the shell starts, and each cd target, from each earlier one.
-    const cwds = [process.cwd()];
+    const cwds = [...startIn];
     for (const [index, word] of words.entries()) {
         // `git -C <dir>` works in <dir> just as `cd <dir>` does.
         if (words[index - 1] !== "cd" && words[index - 1] !== "-C")
@@ -442,7 +442,7 @@ function productShellWriteRefused(command, agentRoot) {
     if (!agentRoot)
         return false;
     try {
-        return protectedFolderShellWriteRefused(command, (words) => commandMentionsAgentFolder(command, words, agentRoot, "product"));
+        return protectedFolderShellWriteRefused(command, (words) => commandMentionsAgentFolder(command, words, agentRoot, "product", [path.resolve(agentRoot)]));
     }
     catch {
         // The filesystem could not say where a path that names product/ lands: refuse rather than guess.
@@ -451,13 +451,15 @@ function productShellWriteRefused(command, agentRoot) {
 }
 // --- structural guardrail checks (always on, all trust levels) ---
 function checkReadBeforeWrite(toolName, args, context) {
+    // The file tools start relative paths in the agent's home and record what they read by absolute path.
+    const target = (p) => path.isAbsolute(p) || !context.agentRoot ? p : path.resolve(context.agentRoot, p);
     if (toolName === "edit_file") {
-        const filePath = args.path || "";
+        const filePath = target(args.path || "");
         if (!context.readPaths.has(filePath))
             return deny(REASONS.readBeforeEdit);
     }
     if (toolName === "write_file") {
-        const filePath = args.path || "";
+        const filePath = target(args.path || "");
         if (context.readPaths.has(filePath))
             return allow;
         if (!fs.existsSync(filePath))
@@ -1472,7 +1474,8 @@ function unknownShellWord(word) {
     return word.includes(SHELL_PARAMETER_MARKER) || word.includes(SHELL_ARRAY_EXPANSION) || /[*?[\]{}]/.test(word);
 }
 function shellPathWord(word) {
-    return word === undefined || unknownShellWord(word) ? null : expandHome(word);
+    // ~-, ~+ and ~user expand to directories this guard cannot know (the previous one, the current one, another home).
+    return word === undefined || unknownShellWord(word) || /^~[^/]/.test(word) ? null : expandHome(word);
 }
 function noteGitAssignment(token, scan, known) {
     const assignment = token.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s);
@@ -1664,8 +1667,11 @@ function bundleGitRefused(command, agentRoot) {
             return true;
         if (scan.calls.length === 0)
             return false;
-        // Every directory the command could be working in: where the shell starts, and each change, from each earlier one.
-        const cwds = [process.cwd()];
+        // Every directory the command could be working in: where the shell starts (the agent's home), and each change, from each earlier one.
+        // `cd /abs && ...` with nothing that can run apart from the cd succeeding: the rest never runs in the home.
+        const chained = /^\s*cd\s+\/[^\s;&|<>$`'"\\()]*\s*&&(.*)$/s.exec(command);
+        const startsAway = chained !== null && !/[;&|\n`$()<>]/.test(chained[1].replace(/&&/g, ""));
+        const cwds = startsAway ? [] : [path.resolve(agentRoot)];
         for (const target of scan.cwdTargets) {
             if (target === null)
                 cwds.push(null);
@@ -1697,25 +1703,29 @@ function bundleGitRefused(command, agentRoot) {
     }
 }
 // --- the sync key's directory, closed to the read-only file tools ---
-/** The directories read_file, glob and grep would read for these arguments, as the tools resolve them. */
-function readToolTargets(toolName, args) {
-    const local = (p) => path.isAbsolute(p) ? p : path.resolve((0, identity_1.getRepoRoot)(), p);
-    if (toolName === "read_file")
-        return [{ target: local(args.path ?? ""), recursive: false }];
+/**
+ * The directories read_file, glob and grep would read for these arguments. A relative path starts in the agent's home;
+ * the repo root and the process directory are checked too, so a tool that resolves differently still cannot reach the key.
+ */
+function readToolTargets(toolName, args, agentRoot) {
+    const home = agentRoot ? [agentRoot] : [];
+    const local = (p) => path.isAbsolute(p) ? [p] : [...home, (0, identity_1.getRepoRoot)()].map((base) => path.resolve(base, p));
+    if (toolName === "read_file" || toolName === "ls")
+        return local(args.path ?? "").map((target) => ({ target, recursive: false }));
     if (toolName === "grep")
-        return [{ target: local(args.path ?? ""), recursive: true }];
-    const cwd = args.cwd ? local(args.cwd) : process.cwd();
+        return local(args.path ?? "").map((target) => ({ target, recursive: true }));
+    const cwds = args.cwd ? local(args.cwd) : [...home, process.cwd()];
     // The part of the pattern before its first glob segment is a directory the glob reads.
     const segments = (args.pattern ?? "").split("/");
     const firstGlob = segments.findIndex((segment) => /[*?[\]{}()!]/.test(segment));
     const literal = (firstGlob < 0 ? segments : segments.slice(0, firstGlob)).join("/");
-    return [{ target: cwd, recursive: false }, { target: path.resolve(cwd, literal || "."), recursive: false }];
+    return cwds.flatMap((cwd) => [{ target: cwd, recursive: false }, { target: path.resolve(cwd, literal || "."), recursive: false }]);
 }
-function syncSecretReadRefused(toolName, args) {
+function syncSecretReadRefused(toolName, args, agentRoot) {
     try {
         const lexical = path.resolve((0, sync_1.syncSecretDir)());
         const secrets = [lexical, canonicalize(lexical)];
-        return readToolTargets(toolName, args).some(({ target, recursive }) => [target, canonicalize(target)].some((form) => secrets.some((secret) => form === secret || form.startsWith(`${secret}${path.sep}`) || (recursive && (form === path.parse(form).root || secret.startsWith(`${form}${path.sep}`))))));
+        return readToolTargets(toolName, args, agentRoot).some(({ target, recursive }) => [target, canonicalize(target)].some((form) => secrets.some((secret) => form === secret || form.startsWith(`${secret}${path.sep}`) || (recursive && (form === path.parse(form).root || secret.startsWith(`${form}${path.sep}`))))));
     }
     catch {
         return true;
@@ -1738,7 +1748,7 @@ function guardInvocation(toolName, args, context) {
     });
     // Read-only tools skip the structural and trust guardrails; only the sync key's directory is closed to them.
     if (READ_ONLY_TOOLS.has(toolName))
-        return syncSecretReadRefused(toolName, args) ? deny(REASONS.unreadablePath) : allow;
+        return syncSecretReadRefused(toolName, args, context.agentRoot) ? deny(REASONS.unreadablePath) : allow;
     // Layer 1: structural guardrails (always on)
     const structuralResult = checkStructuralGuardrails(toolName, args, context);
     if (!structuralResult.allowed)

package/dist/repertoire/shell-sessions.js

@@ -14,6 +14,7 @@ const MAX_OUTPUT_LINES = 200;
 function spawnBackgroundShell(command, owner) {
     const id = (0, crypto_1.randomUUID)();
     const proc = (0, child_process_1.spawn)("sh", ["-c", command], {
+        cwd: owner.agentRoot,
         stdio: ["pipe", "pipe", "pipe"],
     });
     const session = {

package/dist/repertoire/tool-limits.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIP_DIRS = exports.TOOL_MAX_CHARS = exports.TOOL_MAX_LINES = void 0;
+exports.looksBinary = looksBinary;
+exports.cutNotice = cutNotice;
+const runtime_1 = require("../nerves/runtime");
+/** What one home tool shows at most. Kept under the engine's 32,000-character cap so a tool's own notice is what the model sees. */
+exports.TOOL_MAX_LINES = 2000;
+exports.TOOL_MAX_CHARS = 30_000;
+exports.SKIP_DIRS = [".git", "node_modules"];
+const BINARY_SNIFF_BYTES = 8192;
+/** True when the first 8 KB holds a NUL byte, which text never does. */
+function looksBinary(buffer) {
+    return buffer.subarray(0, BINARY_SNIFF_BYTES).includes(0);
+}
+/** Record that a tool cut its output short, and return the notice for the model. */
+function cutNotice(tool, notice, meta = {}) {
+    (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.tool_output_cut", message: `${tool} cut its output short`, meta: { tool, ...meta } });
+    return notice;
+}

package/dist/repertoire/tools-base.js

@@ -5,6 +5,7 @@ exports.routineActionDenied = routineActionDenied;
 const runtime_1 = require("../nerves/runtime");
 const tools_files_1 = require("./tools-files");
 const tools_shell_1 = require("./tools-shell");
+const tools_web_1 = require("./tools-web");
 const tools_notes_1 = require("./tools-notes");
 const tools_record_1 = require("./tools-record");
 const tools_bridge_1 = require("./tools-bridge");
@@ -60,6 +61,7 @@ exports.editFileReadTracker = new Set();
 exports.baseToolDefinitions = [
     ...tools_files_1.fileToolDefinitions,
     ...tools_shell_1.shellToolDefinitions,
+    ...tools_web_1.webToolDefinitions,
     ...tools_notes_1.notesToolDefinitions,
     ...tools_record_1.recordToolDefinitions,
     ...tools_bridge_1.bridgeToolDefinitions,

package/dist/repertoire/tools-files.js

@@ -42,6 +42,10 @@ const file_state_1 = require("../mind/file-state");
 const scrutiny_1 = require("../mind/scrutiny");
 const tools_base_1 = require("./tools-base");
 const guardrails_1 = require("./guardrails");
+const tool_limits_1 = require("./tool-limits");
+const LIST_CAP = 500;
+const GREP_MAX_MATCHES = 100;
+const GREP_MAX_LINE_CHARS = 500;
 /** The psyche edit note for a write that landed on one of the agent's identity files, or "" for any other file. */
 function psycheNoteFor(resolvedPath, ctx) {
     try {
@@ -57,12 +61,28 @@ function psycheNoteFor(resolvedPath, ctx) {
         return "";
     }
 }
-function resolveLocalToolPath(targetPath) {
+/** Relative paths start in the agent's home (its bundle); absolute paths are used as given. */
+function resolveLocalToolPath(targetPath, ctx) {
     if (!path.isAbsolute(targetPath)) {
-        return path.resolve((0, identity_1.getRepoRoot)(), targetPath);
+        return path.resolve(ctx?.agentRoot ?? (0, identity_1.getAgentRoot)(), targetPath);
     }
     return targetPath;
 }
+function homeOf(ctx) {
+    return ctx?.agentRoot ?? (0, identity_1.getAgentRoot)();
+}
+/** Keep the whole lines that fit the line and character caps. A first line over the character cap is cut to it. */
+function fitLines(lines) {
+    const kept = [];
+    let chars = 0;
+    for (const line of lines.slice(0, tool_limits_1.TOOL_MAX_LINES)) {
+        if (chars + line.length + 1 > tool_limits_1.TOOL_MAX_CHARS)
+            break;
+        kept.push(line);
+        chars += line.length + 1;
+    }
+    return kept.length > 0 || lines.length === 0 ? kept : [lines[0].slice(0, tool_limits_1.TOOL_MAX_CHARS)];
+}
 function buildContextDiff(lines, changeStart, changeEnd, contextSize = 3) {
     const start = Math.max(0, changeStart - contextSize);
     const end = Math.min(lines.length, changeEnd + contextSize);
@@ -74,47 +94,69 @@ function buildContextDiff(lines, changeStart, changeEnd, contextSize = 3) {
     }
     return result.join("\n");
 }
+/** A file's bytes, whatever readFileSync handed back (a stubbed reader may return a string). */
+function asBuffer(raw) {
+    return Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+}
 exports.fileToolDefinitions = [
     {
         tool: {
             type: "function",
             function: {
                 name: "read_file",
-                description: "Read file contents. Results include line numbers. Use offset/limit for large files -- don't read the whole thing if you only need a section. Use this tool before editing any file. When reading code, read enough context to understand the surrounding logic, not just the target line.",
+                description: "Read a file in your home, with a relative path or an absolute one. Shows up to 2000 lines or 30,000 characters and tells you the offset to read on from; binary files are not shown.",
                 parameters: {
                     type: "object",
                     properties: {
                         path: { type: "string" },
                         offset: { type: "number", description: "1-based line number to start reading from" },
                         limit: { type: "number", description: "maximum number of lines to return" },
+                        char_offset: { type: "number", description: "1-based character to start from within the first line shown, to read on through a line over 30,000 characters" },
                     },
                     required: ["path"],
                 },
             },
         },
-        handler: (a) => {
-            const resolvedPath = resolveLocalToolPath(a.path);
-            const content = fs.readFileSync(resolvedPath, "utf-8");
+        handler: (a, ctx) => {
+            const resolvedPath = resolveLocalToolPath(a.path, ctx);
+            const raw = asBuffer(fs.readFileSync(resolvedPath));
+            if ((0, tool_limits_1.looksBinary)(raw))
+                return `[binary file, ${raw.length} bytes; not shown]`;
+            const full = raw.toString("utf-8");
+            // A final newline ends the last line; it is not another, empty line.
+            const endsWithNewline = full.endsWith("\n");
+            const lines = (endsWithNewline ? full.slice(0, -1) : full).split("\n");
             tools_base_1.editFileReadTracker.add(resolvedPath);
             const offset = a.offset ? parseInt(a.offset, 10) : undefined;
             const limit = a.limit ? parseInt(a.limit, 10) : undefined;
+            const charStart = a.char_offset ? Math.max(0, parseInt(a.char_offset, 10) - 1) : 0;
+            const start = offset ? offset - 1 : 0;
+            const wanted = lines.slice(start, limit !== undefined ? start + limit : undefined);
+            const firstLine = wanted.length > 0 ? wanted[0].slice(charStart) : "";
+            const kept = fitLines(wanted.length > 0 ? [firstLine, ...wanted.slice(1)] : wanted);
+            // The first line alone is over the character cap: show its next stretch and say where to continue.
+            const firstLineCut = kept.length === 1 && wanted.length > 0 && kept[0].length < firstLine.length;
+            const text = kept.join("\n") + (!firstLineCut && start + kept.length >= lines.length && endsWithNewline && kept.length > 0 ? "\n" : "");
+            const whole = offset === undefined && limit === undefined && charStart === 0 && !firstLineCut && kept.length === wanted.length;
             // Record in file state cache for staleness detection
             try {
                 const mtime = fs.statSync(resolvedPath).mtimeMs;
-                const readContent = (offset === undefined && limit === undefined)
-                    ? content
-                    : content.split("\n").slice(offset ? offset - 1 : 0, limit !== undefined ? (offset ? offset - 1 : 0) + limit : undefined).join("\n");
-                file_state_1.fileStateCache.record(resolvedPath, readContent, mtime, offset, limit);
+                if (whole)
+                    file_state_1.fileStateCache.record(resolvedPath, text, mtime);
+                else
+                    file_state_1.fileStateCache.record(resolvedPath, text, mtime, start + 1, kept.length);
             }
             catch {
                 // stat failed -- skip cache recording
             }
-            if (offset === undefined && limit === undefined)
-                return content;
-            const lines = content.split("\n");
-            const start = offset ? offset - 1 : 0;
-            const end = limit !== undefined ? start + limit : lines.length;
-            return lines.slice(start, end).join("\n");
+            if (firstLineCut) {
+                const shownTo = charStart + kept[0].length;
+                return `${text}\n${(0, tool_limits_1.cutNotice)("read_file", `[line ${start + 1} is ${wanted[0].length} characters; characters ${charStart + 1}-${shownTo} shown; read on with offset=${start + 1} and char_offset=${shownTo + 1}]`, { path: resolvedPath })}`;
+            }
+            if (kept.length === wanted.length)
+                return text;
+            const last = start + kept.length;
+            return `${text}\n${(0, tool_limits_1.cutNotice)("read_file", `[lines ${start + 1}-${last} of ${lines.length} shown; read on with offset=${last + 1}]`, { path: resolvedPath })}`;
         },
         summaryKeys: ["path"],
     },
@@ -123,7 +165,7 @@ exports.fileToolDefinitions = [
             type: "function",
             function: {
                 name: "write_file",
-                description: "Prefer this tool for creating new files or fully replacing existing ones. You MUST read an existing file with read_file before overwriting it. Prefer edit_file for modifying existing files -- it only sends the diff. Do not create documentation files (*.md, README) by default; only do so when explicitly asked or when documentation is clearly part of the requested change.",
+                description: "Prefer this tool for creating new files or fully replacing existing ones. You MUST read an existing file with read_file before overwriting it. Prefer edit_file for modifying existing files -- it only sends the diff.",
                 parameters: {
                     type: "object",
                     properties: { path: { type: "string" }, content: { type: "string" } },
@@ -132,7 +174,7 @@ exports.fileToolDefinitions = [
             },
         },
         handler: (a, ctx) => {
-            const resolvedPath = resolveLocalToolPath(a.path);
+            const resolvedPath = resolveLocalToolPath(a.path, ctx);
             fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
             fs.writeFileSync(resolvedPath, a.content, "utf-8");
             (0, scrutiny_1.trackModifiedFile)(resolvedPath);
@@ -162,7 +204,7 @@ exports.fileToolDefinitions = [
             },
         },
         handler: (a, ctx) => {
-            const resolvedPath = resolveLocalToolPath(a.path);
+            const resolvedPath = resolveLocalToolPath(a.path, ctx);
             if (!tools_base_1.editFileReadTracker.has(resolvedPath)) {
                 return `error: you must read the file with read_file before editing it. call read_file on ${a.path} first.`;
             }
@@ -227,26 +269,50 @@ exports.fileToolDefinitions = [
         summaryKeys: ["path"],
         riskProfile: { mutates: "durable_state_write", risk: "high", reason: "edits file contents" },
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "ls",
+                description: "List a directory in your home (default: home itself), one entry per line; directories end in /, files show their size. Shows at most 500 entries.",
+                parameters: { type: "object", properties: { path: { type: "string", description: "directory to list (defaults to your home)" } } },
+            },
+        },
+        handler: (a, ctx) => {
+            const dir = a.path ? resolveLocalToolPath(a.path, ctx) : homeOf(ctx);
+            const names = fs.readdirSync(dir).sort();
+            const lines = names.slice(0, LIST_CAP).map((name) => {
+                const info = fs.statSync(path.join(dir, name), { throwIfNoEntry: false });
+                return info?.isDirectory() ? `${name}/` : `${name}  ${info?.size ?? 0}`;
+            });
+            if (names.length > LIST_CAP)
+                lines.push((0, tool_limits_1.cutNotice)("ls", `[${LIST_CAP} of ${names.length} entries shown; pass a subdirectory path to see the rest]`, { path: dir }));
+            return lines.length > 0 ? lines.join("\n") : "(empty)";
+        },
+        summaryKeys: ["path"],
+    },
     {
         tool: {
             type: "function",
             function: {
                 name: "glob",
-                description: "Find files matching a glob pattern, sorted alphabetically. Use this instead of shell commands like `find` or `ls`. For broad exploratory searches that would require multiple rounds of globbing and grepping, consider using claude or coding_spawn.",
+                description: "Find files in your home matching a glob pattern, sorted. Skips .git and node_modules and shows at most 500 matches.",
                 parameters: {
                     type: "object",
                     properties: {
-                        pattern: { type: "string", description: "glob pattern (e.g. **/*.ts)" },
-                        cwd: { type: "string", description: "directory to search from (defaults to process.cwd())" },
+                        pattern: { type: "string", description: "glob pattern (e.g. **/*.md)" },
+                        cwd: { type: "string", description: "directory to search from (defaults to your home)" },
                     },
                     required: ["pattern"],
                 },
             },
         },
-        handler: (a) => {
-            const cwd = a.cwd ? resolveLocalToolPath(a.cwd) : process.cwd();
-            const matches = fg.globSync(a.pattern, { cwd, dot: true });
-            return matches.sort().join("\n");
+        handler: (a, ctx) => {
+            const cwd = a.cwd ? resolveLocalToolPath(a.cwd, ctx) : homeOf(ctx);
+            const matches = fg.globSync(a.pattern, { cwd, dot: true, ignore: tool_limits_1.SKIP_DIRS.map((d) => `**/${d}/**`) }).sort();
+            if (matches.length <= LIST_CAP)
+                return matches.join("\n");
+            return [...matches.slice(0, LIST_CAP), (0, tool_limits_1.cutNotice)("glob", `[${LIST_CAP} of ${matches.length} matches shown; narrow the pattern or cwd]`, { pattern: a.pattern })].join("\n");
         },
         summaryKeys: ["pattern", "cwd"],
     },
@@ -255,41 +321,64 @@ exports.fileToolDefinitions = [
             type: "function",
             function: {
                 name: "grep",
-                description: "Search file contents for lines matching a regex pattern. Searches recursively in directories. Use this instead of shell commands like `grep` or `rg`. Returns matching lines with file path and line numbers. Use context_lines for surrounding context. Use include to filter file types (e.g., '*.ts').",
+                description: "Search file contents in your home for a regex, with file path and line numbers; skips .git, node_modules and binary files. Shows at most 100 matches and tells you to narrow the search when it stops.",
                 parameters: {
                     type: "object",
                     properties: {
                         pattern: { type: "string", description: "regex pattern to search for" },
-                        path: { type: "string", description: "file or directory to search" },
+                        path: { type: "string", description: "file or directory to search (defaults to your home)" },
                         context_lines: { type: "number", description: "number of surrounding context lines (default 0)" },
-                        include: { type: "string", description: "glob filter to limit searched files (e.g. *.ts)" },
+                        include: { type: "string", description: "glob filter to limit searched files (e.g. *.md)" },
+                        ignore_case: { type: "boolean", description: "match without regard to case" },
+                        files_only: { type: "boolean", description: "list only the names of files that match" },
                     },
-                    required: ["pattern", "path"],
+                    required: ["pattern"],
                 },
             },
         },
-        handler: (a) => {
-            const targetPath = resolveLocalToolPath(a.path);
-            const regex = new RegExp(a.pattern);
+        handler: (a, ctx) => {
+            const targetPath = a.path ? resolveLocalToolPath(a.path, ctx) : homeOf(ctx);
+            const regex = new RegExp(a.pattern, a.ignore_case ? "i" : "");
             const contextLines = parseInt(a.context_lines || "0", 10);
             const includeGlob = a.include || undefined;
+            const filesOnly = Boolean(a.files_only);
+            let matchCount = 0;
+            let stopped = false;
+            const clipLine = (line) => line.length > GREP_MAX_LINE_CHARS ? `${line.slice(0, GREP_MAX_LINE_CHARS - 3)}...` : line;
+            const home = homeOf(ctx);
+            // Paths inside the home are shown relative to it.
+            const shown = (filePath) => {
+                const relative = path.relative(home, filePath);
+                return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : filePath;
+            };
             function searchFile(filePath) {
-                let content;
+                let buffer;
                 try {
-                    content = fs.readFileSync(filePath, "utf-8");
+                    buffer = asBuffer(fs.readFileSync(filePath));
                 }
                 catch {
                     return [];
                 }
-                const lines = content.split("\n");
+                if ((0, tool_limits_1.looksBinary)(buffer))
+                    return [];
+                const lines = buffer.toString("utf-8").split("\n");
                 const matchIndices = new Set();
                 for (let i = 0; i < lines.length; i++) {
-                    if (regex.test(lines[i])) {
-                        matchIndices.add(i);
+                    if (!regex.test(lines[i]))
+                        continue;
+                    if (matchCount >= GREP_MAX_MATCHES) {
+                        stopped = true;
+                        break;
                     }
+                    matchCount++;
+                    matchIndices.add(i);
+                    if (filesOnly)
+                        break;
                 }
                 if (matchIndices.size === 0)
                     return [];
+                if (filesOnly)
+                    return [shown(filePath)];
                 const outputIndices = new Set();
                 for (const idx of matchIndices) {
                     const start = Math.max(0, idx - contextLines);
@@ -298,18 +387,7 @@ exports.fileToolDefinitions = [
                         outputIndices.add(i);
                     }
                 }
-                const sortedIndices = [...outputIndices].sort((a, b) => a - b);
-                const results = [];
-                for (const idx of sortedIndices) {
-                    const lineNum = idx + 1;
-                    if (matchIndices.has(idx)) {
-                        results.push(`${filePath}:${lineNum}: ${lines[idx]}`);
-                    }
-                    else {
-                        results.push(`-${filePath}:${lineNum}: ${lines[idx]}`);
-                    }
-                }
-                return results;
+                return [...outputIndices].sort((x, y) => x - y).map((idx) => `${matchIndices.has(idx) ? "" : "-"}${shown(filePath)}:${idx + 1}: ${clipLine(lines[idx])}`);
             }
             function collectFiles(dirPath) {
                 const files = [];
@@ -324,7 +402,8 @@ exports.fileToolDefinitions = [
                     for (const entry of entries) {
                         const fullPath = path.join(dir, entry.name);
                         if (entry.isDirectory()) {
-                            walk(fullPath);
+                            if (!tool_limits_1.SKIP_DIRS.includes(entry.name))
+                                walk(fullPath);
                         }
                         else if (entry.isFile()) {
                             files.push(fullPath);
@@ -344,18 +423,21 @@ exports.fileToolDefinitions = [
             const stat = fs.statSync(targetPath, { throwIfNoEntry: false });
             if (!stat)
                 return "";
-            if (stat.isFile()) {
-                return searchFile(targetPath).join("\n");
-            }
-            let files = collectFiles(targetPath);
-            if (includeGlob) {
-                files = files.filter((f) => matchesGlob(f, includeGlob));
+            let files = [targetPath];
+            if (!stat.isFile()) {
+                files = collectFiles(targetPath);
+                if (includeGlob)
+                    files = files.filter((f) => matchesGlob(f, includeGlob));
             }
-            const allResults = [];
+            const results = [];
             for (const file of files) {
-                allResults.push(...searchFile(file));
+                results.push(...searchFile(file));
+                if (stopped)
+                    break;
             }
-            return allResults.join("\n");
+            if (stopped)
+                results.push((0, tool_limits_1.cutNotice)("grep", `[stopped at ${GREP_MAX_MATCHES} matches; narrow the pattern or path]`, { pattern: a.pattern }));
+            return results.join("\n");
         },
         summaryKeys: ["pattern", "path", "include"],
     },

package/dist/repertoire/tools-shell.js

@@ -1,11 +1,81 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shellToolDefinitions = void 0;
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const shell_sessions_1 = require("./shell-sessions");
 const identity_1 = require("../heart/identity");
 const runtime_1 = require("../nerves/runtime");
 const tool_arguments_1 = require("./tool-arguments");
+const tool_limits_1 = require("./tool-limits");
+const MAX_BUFFER = 16 * 1024 * 1024;
+/** The agent's home, or the process directory for a legacy caller that has no agent. */
+function shellHome(ctx) {
+    try {
+        return ctx?.agentRoot ?? (0, identity_1.getAgentRoot)();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+/**
+ * Keep the last 2000 lines or 30,000 characters of a command's output. When something is cut, the whole output
+ * is saved under the home's state/tool-output folder (owner-only) and the notice names that file.
+ */
+function tailWithNotice(output, home) {
+    const body = output.endsWith("\n") ? output.slice(0, -1) : output;
+    const lines = body.split("\n");
+    let tail = lines.slice(-tool_limits_1.TOOL_MAX_LINES).join("\n");
+    if (tail.length > tool_limits_1.TOOL_MAX_CHARS) {
+        tail = tail.slice(tail.length - tool_limits_1.TOOL_MAX_CHARS);
+        const firstBreak = tail.indexOf("\n");
+        if (firstBreak >= 0)
+            tail = tail.slice(firstBreak + 1);
+    }
+    if (tail.length === body.length)
+        return output;
+    const dir = path.join(home, "state", "tool-output");
+    const file = path.join(dir, `${Date.now()}-${(0, crypto_1.randomBytes)(3).toString("hex")}.txt`);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, output, { mode: 0o600 });
+    const shown = tail.split("\n").length;
+    return `${(0, tool_limits_1.cutNotice)("shell", `[output cut to its last ${shown} of ${lines.length} lines; full output saved to ${file}; read_file it with an offset]`, { file })}\n${tail}`;
+}
 function shellOwner(ctx) {
     (0, tool_arguments_1.assertRelationshipToolOwner)(ctx);
     const agentName = ctx?.agentName ?? (0, identity_1.getAgentName)();
@@ -17,7 +87,7 @@ exports.shellToolDefinitions = [
             type: "function",
             function: {
                 name: "shell",
-                description: "Run a shell command and return stdout/stderr. Each call starts in the runtime's working directory; cd does not persist between calls. Use dedicated tools instead of shell when available: read_file instead of cat, edit_file instead of sed, glob instead of find, grep instead of grep/rg. Reserve shell for operations that genuinely need the shell: installing packages, running builds/tests, git operations, process management. Be careful with destructive commands -- consider reversibility before running. If a command fails, read the error output before retrying with a different approach.",
+                description: "Run a shell command in your home; cd does not persist between calls. Keeps the last 2000 lines or 30,000 characters of output and saves the full output to a file it names when it cuts.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -84,15 +154,20 @@ exports.shellToolDefinitions = [
             }
             const baseTimeout = requestedTimeout > 0 ? requestedTimeout : configDefault;
             const timeout = Math.min(baseTimeout, MAX_TIMEOUT);
-            const output = await new Promise((resolve, reject) => {
-                const child = (0, child_process_1.exec)(a.command, { encoding: "utf-8", timeout }, (error, stdout, stderr) => {
-                    if (error)
-                        reject(Object.assign(error, { stdout, stderr }));
+            const home = shellHome(ctx);
+            const raw = await new Promise((resolve, reject) => {
+                const child = (0, child_process_1.exec)(a.command, { encoding: "utf-8", timeout, cwd: home, maxBuffer: MAX_BUFFER }, (error, stdout, stderr) => {
+                    if (error) {
+                        // A failing command's output gets the same tail cap and saved file.
+                        error.message = tailWithNotice(error.message, home);
+                        reject(Object.assign(error, { stdout: tailWithNotice(stdout, home), stderr: tailWithNotice(stderr, home) }));
+                    }
                     else
                         resolve(stdout);
                 });
                 child.stdin?.end();
             });
+            const output = tailWithNotice(raw, home);
             if (destructivePatterns.length > 0) {
                 return `${output}\n\n--- destructive pattern detected: ${destructivePatterns.join(", ")} ---`;
             }

package/dist/repertoire/tools-web.js

@@ -0,0 +1,230 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webToolDefinitions = exports.webTestHooks = void 0;
+exports.isPrivateAddress = isPrivateAddress;
+exports.htmlToText = htmlToText;
+const promises_1 = require("node:dns/promises");
+const http = __importStar(require("node:http"));
+const https = __importStar(require("node:https"));
+const node_net_1 = require("node:net");
+const runtime_1 = require("../nerves/runtime");
+const tool_limits_1 = require("./tool-limits");
+const MAX_REDIRECTS = 5;
+/** Test hook: the request deadline. */
+exports.webTestHooks = { timeoutMs: 20_000 };
+const MAX_DOWNLOAD_BYTES = 2 * 1024 * 1024;
+function ipv4Private(a, b, c) {
+    return a === 0 || a === 10 || a === 127 || a >= 224
+        || (a === 100 && b >= 64 && b <= 127)
+        || (a === 169 && b === 254)
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 192 && b === 0 && c === 0)
+        || (a === 198 && (b === 18 || b === 19));
+}
+function ipv6Groups(ip) {
+    const [left, right] = ip.split("%")[0].split("::");
+    const head = left ? left.split(":") : [];
+    const tail = right ? right.split(":") : [];
+    const gap = right === undefined ? [] : Array(8 - head.length - tail.length).fill("0");
+    return [...head, ...gap, ...tail].map((p) => parseInt(p, 16));
+}
+/** True for loopback, private, link-local, CGNAT, multicast and other addresses that are not on the public internet. */
+function isPrivateAddress(ip) {
+    if ((0, node_net_1.isIP)(ip) === 4) {
+        const [a, b, c] = ip.split(".").map(Number);
+        return ipv4Private(a, b, c);
+    }
+    const g = ipv6Groups(ip);
+    const embeddedV4 = ipv4Private(g[6] >> 8, g[6] & 255, g[7] >> 8);
+    if (g.slice(0, 5).every((n) => n === 0) && (g[5] === 0 || g[5] === 0xffff))
+        return embeddedV4;
+    if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every((n) => n === 0))
+        return embeddedV4;
+    return (g[0] & 0xffc0) === 0xfe80 || (g[0] & 0xffc0) === 0xfec0 || (g[0] & 0xfe00) === 0xfc00 || (g[0] & 0xff00) === 0xff00;
+}
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'", nbsp: " " };
+function decodeEntities(text) {
+    return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, body) => {
+        if (body[0] !== "#")
+            return ENTITIES[body.toLowerCase()] ?? whole;
+        const code = body[1].toLowerCase() === "x" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+        return code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+    });
+}
+/** Readable text from HTML: the title first, script/style/nav dropped, block tags as line breaks, entities decoded. */
+function htmlToText(html) {
+    const title = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html)?.[1];
+    const body = html
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/<(script|style|nav|noscript|head|title)\b[\s\S]*?<\/\1>/gi, "")
+        .replace(/<\/?(p|div|br|li|ul|ol|h[1-6]|tr|table|section|article|header|footer|main|pre|blockquote|form)\b[^>]*>/gi, "\n")
+        .replace(/<[^>]+>/g, "");
+    const text = decodeEntities(body).split("\n").map((l) => l.replace(/[ \t]+/g, " ").trim()).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    const heading = title ? decodeEntities(title).replace(/\s+/g, " ").trim() : "";
+    return heading ? `${heading}\n\n${text}`.trim() : text;
+}
+class RefusedError extends Error {
+    constructor(hostname, address) {
+        super(`refused: ${hostname} resolves to a private or local address (${address})`);
+    }
+}
+/** A person in the family circle, not an agent: they may fetch addresses inside the house. */
+function isFamilyHuman(ctx) {
+    const friend = ctx?.context?.friend;
+    return friend?.kind === "human" && friend.trustLevel === "family";
+}
+/** Resolves the name, refuses private addresses, and hands the socket the address that was checked. */
+function checkedLookup(exempt) {
+    return (hostname, options, callback) => {
+        (0, promises_1.lookup)(hostname, { all: true }).then((records) => {
+            const bad = exempt ? undefined : records.map((r) => r.address).find(isPrivateAddress);
+            if (bad)
+                return callback(new RefusedError(hostname, bad), "", 4);
+            if (options.all)
+                return callback(null, records);
+            return callback(null, records[0].address, records[0].family);
+        }, (error) => callback(error, "", 4));
+    };
+}
+function get(url, exempt, signal) {
+    const lib = url.protocol === "https:" ? https : http;
+    return new Promise((resolve, reject) => {
+        const req = lib.request(url, {
+            method: "GET", signal, lookup: checkedLookup(exempt),
+            headers: { "user-agent": "ouro-agent/1.0", accept: "text/html,text/plain,application/json;q=0.9,*/*;q=0.5" },
+        }, resolve);
+        req.on("error", reject);
+        req.end();
+    });
+}
+async function readCapped(response) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response) {
+        chunks.push(chunk);
+        size += chunk.length;
+        if (size >= MAX_DOWNLOAD_BYTES) {
+            response.destroy();
+            break;
+        }
+    }
+    return { bytes: Buffer.concat(chunks).subarray(0, MAX_DOWNLOAD_BYTES), cut: size >= MAX_DOWNLOAD_BYTES };
+}
+async function fetchPage(rawUrl, offset, exempt) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return `error: not a valid URL: ${rawUrl}`;
+    }
+    const signal = AbortSignal.timeout(exports.webTestHooks.timeoutMs);
+    for (let hop = 0;; hop++) {
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return `error: only http and https URLs can be fetched, not ${url.protocol}`;
+        const literal = url.hostname.replace(/^\[|\]$/g, "");
+        if (!exempt && (0, node_net_1.isIP)(literal) && isPrivateAddress(literal))
+            return `error: ${new RefusedError(url.hostname, literal).message}`;
+        const response = await get(url, exempt, signal);
+        const status = response.statusCode;
+        const location = response.headers.location;
+        if (status >= 300 && status < 400 && location) {
+            response.destroy();
+            if (hop >= MAX_REDIRECTS)
+                return `error: more than ${MAX_REDIRECTS} redirects fetching ${rawUrl}`;
+            url = new URL(location, url);
+            continue;
+        }
+        if (status === 204) {
+            response.destroy();
+            return "(no content: HTTP 204)";
+        }
+        if (status < 200 || status >= 300) {
+            response.destroy();
+            return `error: HTTP ${status} fetching ${url.href}`;
+        }
+        const type = (response.headers["content-type"] ?? "text/plain").split(";")[0].trim().toLowerCase();
+        const isHtml = type === "text/html" || type === "application/xhtml+xml";
+        if (!isHtml && !type.startsWith("text/") && !type.includes("json") && !type.endsWith("xml")) {
+            response.destroy();
+            return `[content type ${type}; not shown]`;
+        }
+        const { bytes, cut } = await readCapped(response);
+        const decoded = new TextDecoder().decode(bytes);
+        const text = isHtml ? htmlToText(decoded) : decoded;
+        const end = Math.min(text.length, offset + tool_limits_1.TOOL_MAX_CHARS);
+        const page = text.slice(offset, end);
+        const notes = [];
+        if (end < text.length)
+            notes.push(`[characters ${offset}-${end} of ${text.length}; read on with offset=${end}]`);
+        if (cut)
+            notes.push("[download cut at 2 MB]");
+        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.fetch_url", message: "fetched a web page", meta: { host: url.hostname, status, chars: text.length, cut } });
+        return notes.length > 0 ? `${page}\n${notes.join("\n")}` : page;
+    }
+}
+exports.webToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "fetch_url",
+                description: "Read a web page (http or https) as text; HTML is turned into readable text, and local or private addresses are refused. Shows up to 30,000 characters and tells you the offset to read on from; downloads stop at 2 MB and the request times out after 20 seconds.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        url: { type: "string" },
+                        offset: { type: "number", description: "character offset to start from, as given in a read-on notice" },
+                    },
+                    required: ["url"],
+                },
+            },
+        },
+        handler: async (a, ctx) => {
+            try {
+                return await fetchPage(a.url, a.offset ? Math.max(0, parseInt(a.offset, 10) || 0) : 0, isFamilyHuman(ctx));
+            }
+            catch (error) {
+                if (error instanceof RefusedError)
+                    return `error: ${error.message}`;
+                const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+                return timedOut ? `error: timed out after ${exports.webTestHooks.timeoutMs / 1000} seconds fetching ${a.url}` : `error: could not fetch ${a.url}: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+        summaryKeys: ["url"],
+    },
+];

package/dist/repertoire/tools.js

@@ -85,6 +85,7 @@ exports.SANCTUARY_OWNER_ADDITIONS = new Set([
     "shell", "shell_status", "shell_tail", "read_file", "write_file", "edit_file", "glob", "grep",
     "web_search", "search_facts", "consult_diary", "consult_notes", "get_friend_note",
     "session_summary", "query_session", "set_reasoning_effort", "restart_runtime", "revive_sense",
+    "ls", "fetch_url", "note", "diary_write",
 ]);
 /** The bundle sync tools, granted to the Sanctuary owner alone. */
 const SANCTUARY_OWNER_SYNC_TOOLS = new Set(["bundle_push", "bundle_pull_rebase"]);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.993",
+  "version": "0.1.0-alpha.994",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.993",
+      "version": "0.1.0-alpha.994",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.993",
+  "version": "0.1.0-alpha.994",
   "engines": {
     "node": ">=22"
   },