agent-sh 0.15.5 → 0.15.7

package/docs/usage.md

@@ -2,17 +2,17 @@
 
 ## Running agent-sh
 
-The simplest way to run agent-sh — just provide an API key and model:
+The simplest way to run agent-sh — just provide an API key:
 
 ```bash
-# Using environment variables
-OPENAI_API_KEY="your-key" agent-sh --model gpt-4o
+# DeepSeek is a built-in provider — set the key and go (defaults to deepseek-v4-flash)
+DEEPSEEK_API_KEY="your-key" agent-sh
 
-# Using CLI flags
-agent-sh --api-key "your-key" --base-url http://localhost:11434/v1 --model llama3
+# Any OpenAI-compatible endpoint via CLI flags (e.g. a local Ollama server)
+agent-sh --api-key "your-key" --base-url http://localhost:11434/v1 --model gemma4
 
 # Using npx
-npx agent-sh --api-key "$KEY" --model gpt-4o
+DEEPSEEK_API_KEY="your-key" npx agent-sh --model deepseek-v4-flash
 ```
 
 Environment variables `OPENAI_API_KEY` and `OPENAI_BASE_URL` are supported as alternatives to CLI flags.
@@ -30,13 +30,13 @@ agent-sh --backend pi
 npm run dev
 
 # Debug mode
-DEBUG=1 agent-sh --api-key "$KEY" --model gpt-4o
+DEBUG=1 DEEPSEEK_API_KEY="$KEY" agent-sh
 ```
 
 ### Subcommands
 
 ```bash
-agent-sh init                   # scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
+agent-sh init                   # scaffold ~/.agent-sh/ (settings.json + settings.example.json, extensions/ dir)
 agent-sh install <name>         # install a bundled extension (e.g. agent-sh install pi-bridge)
 agent-sh install ./path/to/ext  # install from a local path
 agent-sh uninstall <name>       # remove an installed extension
@@ -55,8 +55,8 @@ Any provider you declare under `providers` in `settings.json` is also accepted b
   "providers": {
     "my-llama": {
       "baseURL": "http://localhost:8000/v1",
-      "defaultModel": "llama-3.1-70b",
-      "models": ["llama-3.1-70b"]
+      "defaultModel": "gemma4",
+      "models": ["gemma4"]
     }
   }
 }
@@ -84,26 +84,26 @@ For unreleased changes on `main`, use the clone-and-link flow from the [Quick St
 
 agent-sh works with any OpenAI-compatible API. Here are common configurations:
 
-### OpenAI
+### DeepSeek
 
 ```bash
-export OPENAI_API_KEY="sk-..."
-agent-sh --model gpt-4o
-# or: agent-sh --model gpt-4o-mini
+export DEEPSEEK_API_KEY="sk-..."
+agent-sh   # defaults to deepseek-v4-flash
 ```
 
-### DeepSeek
+### OpenAI
 
 ```bash
-export DEEPSEEK_API_KEY="sk-..."
-agent-sh
+export OPENAI_API_KEY="sk-..."
+agent-sh --model gpt-5.4
+# or: agent-sh --model gpt-5.4-mini
 ```
 
 ### Ollama (Local)
 
 ```bash
 # No API key needed — Ollama doesn't require authentication
-agent-sh --api-key dummy --base-url http://localhost:11434/v1 --model llama3
+agent-sh --api-key dummy --base-url http://localhost:11434/v1 --model gemma4
 ```
 
 ### OpenRouter
@@ -111,7 +111,7 @@ agent-sh --api-key dummy --base-url http://localhost:11434/v1 --model llama3
 ```bash
 agent-sh --api-key "$OPENROUTER_KEY" \
   --base-url https://openrouter.ai/api/v1 \
-  --model anthropic/claude-sonnet-4-20250514
+  --model deepseek/deepseek-v4-flash
 ```
 
 ### Together AI
@@ -119,7 +119,7 @@ agent-sh --api-key "$OPENROUTER_KEY" \
 ```bash
 agent-sh --api-key "$TOGETHER_KEY" \
   --base-url https://api.together.xyz/v1 \
-  --model meta-llama/Llama-3-70b-chat-hf
+  --model deepseek-ai/DeepSeek-V3
 ```
 
 ### Groq
@@ -127,7 +127,7 @@ agent-sh --api-key "$TOGETHER_KEY" \
 ```bash
 agent-sh --api-key "$GROQ_KEY" \
   --base-url https://api.groq.com/openai/v1 \
-  --model llama-3.3-70b-versatile
+  --model deepseek-r1-distill-llama-70b
 ```
 
 ### LM Studio
@@ -135,7 +135,7 @@ agent-sh --api-key "$GROQ_KEY" \
 ```bash
 agent-sh --api-key dummy \
   --base-url http://localhost:1234/v1 \
-  --model local-model
+  --model mimo
 ```
 
 ### vLLM
@@ -143,7 +143,7 @@ agent-sh --api-key dummy \
 ```bash
 agent-sh --api-key dummy \
   --base-url http://localhost:8000/v1 \
-  --model your-model
+  --model deepseek-v4-flash
 ```
 
 ## Using agent-sh as Your Default Shell
@@ -152,7 +152,7 @@ Add to the end of your `~/.zshrc` or `~/.bashrc`:
 
 ```bash
 if [[ -z "$AGENT_SH" && $- == *i* && -t 0 ]]; then
-  exec agent-sh --api-key "$OPENAI_API_KEY" --model gpt-4o
+  exec agent-sh   # uses DEEPSEEK_API_KEY from your env (deepseek-v4-flash)
 fi
 ```
 
@@ -168,27 +168,29 @@ Instead of passing `--api-key` and `--base-url` every time, define named provide
 
 ```json
 {
-  "defaultProvider": "openai",
+  "defaultProvider": "deepseek",
   "providers": {
-    "openai": {
-      "apiKey": "$OPENAI_API_KEY",
-      "defaultModel": "gpt-4o",
-      "models": ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
-      "contextWindow": 128000
+    "deepseek": {
+      "apiKey": "$DEEPSEEK_API_KEY",
+      "defaultModel": "deepseek-v4-flash",
+      "models": ["deepseek-v4-flash", "deepseek-v4-pro"]
     },
     "ollama": {
       "apiKey": "not-needed",
       "baseURL": "http://localhost:11434/v1",
-      "defaultModel": "llama3",
-      "models": ["llama3", "mistral", "codellama"]
+      "defaultModel": "gemma4",
+      "models": [
+        "mimo",
+        { "id": "gemma4", "contextWindow": 128000, "modalities": ["text", "image"] }
+      ]
     },
     "openrouter": {
       "apiKey": "$OPENROUTER_KEY",
       "baseURL": "https://openrouter.ai/api/v1",
-      "defaultModel": "anthropic/claude-sonnet-4.5",
+      "defaultModel": "deepseek/deepseek-v4-flash",
       "models": [
-        { "id": "anthropic/claude-sonnet-4.5", "contextWindow": 200000, "reasoning": true },
-        { "id": "google/gemini-2.5-pro",       "contextWindow": 1000000 }
+        { "id": "deepseek/deepseek-v4-flash", "contextWindow": 1000000, "reasoning": true },
+        { "id": "deepseek/deepseek-v4-pro",   "contextWindow": 1048576, "reasoning": true }
       ]
     }
   }
@@ -198,32 +200,50 @@ Instead of passing `--api-key` and `--base-url` every time, define named provide
 Then just run:
 
 ```bash
-agent-sh                          # uses defaultProvider
+agent-sh                          # uses defaultProvider (deepseek)
 agent-sh --provider ollama        # use a specific provider
-agent-sh --provider openai --model gpt-4-turbo  # override the default model
+agent-sh --provider ollama --model gemma4  # override the default model
 ```
 
 The `apiKey` field supports `$ENV_VAR` and `${ENV_VAR}` syntax — variables are expanded at runtime, so you don't store secrets in the file.
 
-### Declaring the context window
-
-agent-sh adapts its auto-compaction trigger to the model's context window. There are two places to declare it:
-
-- **Provider-level `contextWindow`** — applies to every model in that provider unless a more specific value is set.
-- **Per-model `contextWindow`** (inside an entry of `models`) — overrides the provider-level value for a specific model, and also lets you tag reasoning-capable models via `reasoning: true`.
+### Declaring model capabilities
 
-If neither is set, agent-sh falls back to a conservative 60k-token default.
-
-Entries in `models` can be plain strings (just the model id, uses the provider-level `contextWindow`) or objects:
+Entries in a provider's `models` list can be plain strings (just the id) or objects that declare what the model can do. agent-sh uses these to size its context budget, cap output, route reasoning, and enable image input. Every field except `id` is optional.
 
 ```json
 "models": [
-  "gpt-4o-mini",
-  { "id": "gpt-4o",    "contextWindow": 128000 },
-  { "id": "o1-preview", "contextWindow": 128000, "reasoning": true }
+  "deepseek-v4-flash",
+  {
+    "id": "gemma4",
+    "contextWindow": 128000,
+    "maxTokens": 8192,
+    "modalities": ["text", "image"]
+  },
+  { "id": "mimo",            "reasoning": true },
+  { "id": "deepseek-v4-pro", "contextWindow": 1000000, "reasoning": true, "echoReasoning": true }
 ]
 ```
 
+| Field | Type | Default | Effect |
+|---|---|---|---|
+| `id` | `string` | — | Model identifier sent to the API (required). |
+| `contextWindow` | `number` | provider-level `contextWindow`, else `60000` | Total token budget. Drives the `/context` display and the `autoCompactThreshold` auto-compaction trigger. |
+| `maxTokens` | `number` | 40% of this model's `contextWindow` capped at `65536`, else `65536` | Max output (completion) tokens requested per turn. |
+| `reasoning` | `boolean` | `false` | Marks the model as thinking-capable, so `/thinking` levels apply to it. |
+| `modalities` | `("text" \| "image")[]` | `["text"]` | Input modalities. Include `"image"` to let the agent read image files (PNG/JPEG/GIF/WebP) with `read_file`; without it, attached images are dropped before the request. |
+| `echoReasoning` | `boolean` | `false` | Echo `reasoning_content` back on assistant turns. Required by DeepSeek's reasoner; leave off otherwise (leaky proxies may forward it to the model as malformed input). |
+
+A plain-string entry inherits the provider-level values and the defaults above. These provider-level fields apply to every model unless a per-model entry overrides them:
+
+| Provider field | Effect |
+|---|---|
+| `contextWindow` | Fallback context window for models that don't declare their own. |
+| `reasoningShape` | Borrow another registered provider's reasoning-request shape by id (e.g. `"openrouter"`). Defaults to the OpenAI-compatible shape. |
+| `echoReasoningPatterns` | Case-insensitive regex sources matched against model ids; a match defaults that model to `echoReasoning: true` (a per-model `echoReasoning` still wins). |
+
+If neither level declares a `contextWindow`, agent-sh falls back to a conservative 60k-token budget. Override that fallback globally with the `AGENT_SH_DEFAULT_CONTEXT_WINDOW` environment variable (a positive integer; ignored otherwise).
+
 ### Switching models at runtime
 
 - **`/model`** — show the current model
@@ -274,7 +294,7 @@ Switching mid-conversation preserves your conversation state — only the LLM en
 On launch, agent-sh displays a structured startup banner showing:
 
 - **Backend** — which agent backend is active (`ash`, `claude-code`, `pi`, etc.)
-- **Model** — current model with provider in brackets (e.g. `gpt-4o [openai]`)
+- **Model** — current model with provider in brackets (e.g. `deepseek-v4-flash [deepseek]`)
 - **Extensions** — loaded extensions (from CLI `-e`, settings, or `~/.agent-sh/extensions/`)
 - **Skills** — discovered skills (global + project)
 

package/examples/extensions/ashi/src/chat/assistant.ts

@@ -7,6 +7,8 @@ export type RenderBlock =
 
 export type ContentTransform = (blocks: RenderBlock[]) => RenderBlock[];
 
+const stripTrailing = (s: string): string => s.replace(/\s+$/, "");
+
 export class AssistantMessage {
   readonly node: RenderNode;
   private container: ContainerView;
@@ -23,20 +25,20 @@ export class AssistantMessage {
 
   appendText(t: string): void {
     this.buffer += t;
-    this.md.setText(this.buffer);
+    this.md.setText(stripTrailing(this.buffer));
   }
 
   appendCodeBlock(language: string, code: string): void {
     const prefix = this.buffer && !this.buffer.endsWith("\n") ? "\n" : "";
     this.buffer += `${prefix}\`\`\`${language}\n${code}\n\`\`\`\n`;
-    this.md.setText(this.buffer);
+    this.md.setText(stripTrailing(this.buffer));
   }
 
   finalize(): void {
     if (this.buffer === "") this.buffer = " ";
     const blocks = this.transform([{ type: "text", text: this.buffer }]);
     if (blocks.every((b) => b.type === "text")) {
-      this.md.setText(this.buffer);
+      this.md.setText(stripTrailing(this.buffer));
       return;
     }
     this.rebuild(blocks);
@@ -55,7 +57,7 @@ export class AssistantMessage {
         this.container.addChild(m.node);
       } else if (block.text.trim()) {
         const m = this.nodes.markdown({ paddingX: 1 });
-        m.setText(block.text);
+        m.setText(stripTrailing(block.text));
         this.container.addChild(m.node);
       }
     }

package/examples/extensions/ashi/src/compaction.ts

@@ -39,19 +39,16 @@ export function registerCompaction(
     }
 
     const older = messages.slice(0, cutIdx);
-    const kept = messages.slice(cutIdx);
     const tokensBefore = (ctx.call("conversation:estimate-prompt-tokens") as number) ?? 0;
     const customSummary = (await ctx.call("ashi:compact:build-summary", older)) as string | null | undefined;
 
     const store = getStore().current();
     await store.appendCompaction(firstKeptId, tokensBefore, customSummary ?? undefined);
-    ctx.call("conversation:replace-messages", store.buildMessages());
 
-    const keptIds = kept.map((_, i) => capture.getEntryIdAt(cutIdx + i));
-    if (keptIds.some((id) => id === null)) {
-      ctx.bus.emit("ui:error", { message: "compaction: a kept message has no on-disk entry — capture invariant broken" });
-    }
-    capture.resetTo([null, ...keptIds]);
+    // Take messages and ids from one rebuild so capture's index→id map can't drift.
+    const { messages: rebuilt, entryIds } = store.buildBranchWithIds();
+    ctx.call("conversation:replace-messages", rebuilt);
+    capture.resetTo(entryIds);
 
     const tokensAfter = (ctx.call("conversation:estimate-prompt-tokens") as number) ?? 0;
     return { before: tokensBefore, after: tokensAfter, evictedCount: older.length };

package/examples/extensions/ashi/src/frontend.ts

@@ -650,6 +650,8 @@ export function mountAshi(
     activeThinking = null;
     activeTools.clear();
     openGroup = null;
+    compactions = 0;
+    statusFooter.update({ compactions });
     clearChat();
     const branch = getStore().current().getBranch();
     const toolMap = new Map<string, ReplayEntry>();

package/examples/extensions/ashi/src/schema.ts

@@ -1,4 +1,5 @@
 import { theme } from "./theme.js";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import { highlight, supportsLanguage } from "cli-highlight";
 import type { ThemeColor } from "./theme.js";
 import type { ToolEntryConfig } from "./display-config.js";
@@ -188,6 +189,11 @@ export function renderBody(body: Body, env: Env, diff: DiffSlot): string {
 // The tail is capped even when expanded so a huge result can't flood scrollback; the agent still sees it all.
 const DEFAULT_EXPANDED_LINES = 200;
 
+function clampLines(lines: string[], width: number): string {
+  if (width <= 0) return lines.join("\n");
+  return lines.map((l) => truncateToWidth(l, width, "…")).join("\n");
+}
+
 function renderStream(buffer: string, env: Env): string {
   const display = buffer.replace(/\n+$/, "");
   if (env.expanded) {
@@ -205,14 +211,14 @@ function renderStream(buffer: string, env: Env): string {
   }
   if (env.mode === "summary") {
     if (!env.finalized) {
-      const tail = display.split("\n").slice(-2).join("\n");
+      const tail = clampLines(display.split("\n").slice(-2), env.width);
       return theme.fg("muted", tail);
     }
     return lineCountHint(buffer);
   }
   if (!display) return "";
   const lines = display.split("\n");
-  const trimmed = lines.slice(-env.previewLines).join("\n");
+  const trimmed = clampLines(lines.slice(-env.previewLines), env.width);
   const remaining = Math.max(0, lines.length - env.previewLines);
   // The preview is the tail, so the hidden lines come before it — note goes above.
   const overflow = remaining > 0

package/examples/extensions/command-suggest.ts

@@ -0,0 +1,90 @@
+/**
+ * command-suggest extension
+ *
+ * Registers the suggest_command tool. When the agent calls it, the response
+ * finishes and the user drops to the shell prompt with the command pre-typed
+ * — no copy-paste, no mode toggle, just review and press Enter.
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/command-suggest.ts
+ *
+ *   # Or install permanently:
+ *   cp examples/extensions/command-suggest.ts ~/.agent-sh/extensions/
+ */
+import type { ExtensionContext } from "agent-sh/types";
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus } = ctx;
+
+  // No shell to deliver to (e.g. ashi) — the suggestion would go nowhere.
+  if (!ctx.shell) return;
+
+  let pendingCommand: string | null = null;
+
+  // ── Tool ────────────────────────────────────────────────────────
+
+  ctx.agent?.registerTool({
+    name: "suggest_command",
+    description:
+      "Stage a shell command at the user's prompt. After this response " +
+      "completes, the command appears in their shell prompt (not inside " +
+      "agent-input mode), ready to edit or run with Enter. " +
+      "Only call this when the user is asking for a command to run, or otherwise " +
+      "signals they want one staged — e.g. \"give me the command to …\", " +
+      "\"what do I run to …\". Do NOT call it unprompted after a general question, " +
+      "an explanation, or any turn where no command was requested. " +
+      "Prefer it over telling the user to copy-paste a command. " +
+      "Only the most recent call matters. Call with an empty string to clear.",
+    input_schema: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description:
+            "The shell command to place in the user's prompt. " +
+            "Multi-line commands are collapsed to a single line.",
+        },
+      },
+      required: ["command"],
+    },
+    showOutput: true,
+
+    getDisplayInfo: () => ({ icon: "⏎" }),
+
+    formatCall: (args) => {
+      const cmd = (args.command as string).trim();
+      if (!cmd) return "(clear suggestion)";
+      return cmd.length > 60 ? cmd.slice(0, 57) + "..." : cmd;
+    },
+
+    async execute(args) {
+      const cmd = (args.command as string).trim();
+      if (!cmd) {
+        pendingCommand = null;
+        return { content: "Cleared pending command suggestion.", exitCode: 0, isError: false };
+      }
+      // Collapse newlines to spaces so the command stays on one readline buffer.
+      pendingCommand = cmd.replace(/\n/g, " ");
+      return {
+        content: `Will suggest at shell prompt: ${pendingCommand}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+  });
+
+  // ── Injection hook ──────────────────────────────────────────────
+
+  // Replace the default handler — which re-enters agent-input mode when sticky —
+  // so a pending command lands at a fresh shell prompt instead. The "\n" leads
+  // the same PTY write so the new prompt appears before the command text fills it.
+  ctx.advise("shell:on-processing-redraw", (next) => {
+    if (pendingCommand) {
+      const cmd = pendingCommand;
+      pendingCommand = null;
+      bus.emit("shell:pty-write", { data: "\n" + cmd });
+    } else {
+      next();
+    }
+  });
+}

package/examples/extensions/solarized-theme.ts

@@ -23,5 +23,16 @@ export default function activate(ctx: ShellContext) {
     errorBg:       "\x1b[48;2;42;30;30m",   // base03 with red tint
     successBgEmph: "\x1b[48;2;20;70;50m",   // stronger green tint
     errorBgEmph:   "\x1b[48;2;70;30;30m",   // stronger red tint
+
+    mdHeading:         "\x1b[38;2;181;137;0m",  // yellow (#b58900)
+    mdLink:            "\x1b[38;2;38;139;210m", // blue (#268bd2)
+    mdLinkUrl:         "\x1b[38;2;88;110;117m", // base01 (#586e75)
+    mdCode:            "\x1b[38;2;42;161;152m", // cyan (#2aa198)
+    mdCodeBlock:       "\x1b[38;2;133;153;0m",  // green (#859900)
+    mdCodeBlockBorder: "\x1b[38;2;88;110;117m", // base01 (#586e75)
+    mdQuote:           "\x1b[38;2;88;110;117m", // base01 (#586e75)
+    mdQuoteBorder:     "\x1b[38;2;88;110;117m", // base01 (#586e75)
+    mdHr:              "\x1b[38;2;88;110;117m", // base01 (#586e75)
+    mdListBullet:      "\x1b[38;2;38;139;210m", // blue (#268bd2)
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "A composable agent runtime — pair any frontend with any agent backend over one shared extension layer",
   "type": "module",
   "workspaces": [
@@ -73,6 +73,10 @@
       "types": "./dist/agent/types.d.ts",
       "default": "./dist/agent/types.js"
     },
+    "./skills": {
+      "types": "./dist/agent/skills.d.ts",
+      "default": "./dist/agent/skills.js"
+    },
     "./store": {
       "types": "./dist/agent/store.d.ts",
       "default": "./dist/agent/store.js"
@@ -109,10 +113,6 @@
       "types": "./dist/agent/token-budget.d.ts",
       "default": "./dist/agent/token-budget.js"
     },
-    "./agent/history-file": {
-      "types": "./dist/agent/history-file.d.ts",
-      "default": "./dist/agent/history-file.js"
-    },
     "./agent/nuclear-form": {
       "types": "./dist/agent/nuclear-form.d.ts",
       "default": "./dist/agent/nuclear-form.js"

package/src/agent/agent-loop.ts

@@ -971,12 +971,9 @@ export class AgentLoop implements AgentBackend {
         // tool-heavy workloads.
         const target = Math.floor(threshold * 0.25);
         const result = await this.compactWithHooks(target, 1);
-        if (!result) {
-          // Auto-compact fired but nothing was evictable. This can happen
-          // in short conversations with heavy tool output where the pin
-          // fraction consumes all turns. Log it so it's not silent.
+        if (result) {
           this.bus.emit("ui:info", {
-            message: `[auto-compact] above threshold (${totalEstimate.toLocaleString()} > ${threshold.toLocaleString()}) but nothing to evict — conversation may be too short`,
+            message: `(auto-compacted: ~${result.before.toLocaleString()} → ~${result.after.toLocaleString()} tokens, evicted ${result.evictedCount})`,
           });
         }
         cachedSystemPrompt = undefined;

package/src/agent/extensions/rolling-history/index.ts

@@ -111,32 +111,44 @@ export default function activate(ctx: ExtensionContext): void {
     name: TOOL_NAME,
     displayName: "recall",
     description:
-      "Browse, search, or expand evicted conversation turns. " +
-      "Use when you need context from earlier in the conversation that was compacted away. " +
-      "Search is regex-based and covers both summaries and full body text. " +
-      "If search doesn't find what you expect, try broader/shorter terms or browse to scan the timeline.",
+      "Browse, search, or expand the persistent conversation memory — all captured turns across this and recent sessions. " +
+      "Use when you need context from prior turns or past sessions that may no longer be in the active window. " +
+      "Search accepts a regex pattern (e.g. 'foo|bar') and falls back to literal matching if the pattern is invalid. " +
+      "Covers both summaries and full body text. " +
+      "If search doesn't find what you expect, try broader/shorter terms or browse to scan the timeline. " +
+      "Use offset for pagination on both browse and search.",
     input_schema: {
       type: "object",
       properties: {
         action: {
           type: "string",
           enum: ["browse", "search", "expand"],
-          description: "browse: list evicted turns, search: regex search, expand: show full turn",
+          description: "browse: list recent captured turns, search: regex search across memory, expand: show full turn body",
         },
-        query: { type: "string", description: "Search query (for action=search)" },
+        query: { type: "string", description: "Search pattern — a regex (e.g. 'foo|bar') or literal text (for action=search)" },
         turn_id: { type: "string", description: "Turn ID to expand (for action=expand)" },
+        offset: {
+          type: "number",
+          description: "Skip first N results; for browse, start at this entry offset; for search, skip first N hits. Default 0.",
+        },
+        limit: {
+          type: "number",
+          description: "Max entries to return for browse (default 25) or search (default 30).",
+        },
       },
       required: ["action"],
     },
     execute: async (args) => {
       const action = args.action as string;
+      const offset = (args.offset as number) ?? 0;
+      const limit = (args.limit as number) ?? (action === "search" ? 30 : 25);
       let content: string;
       if (action === "search") {
-        content = await recallSearch(summaryStore, (args.query as string) ?? "");
+        content = await recallSearch(summaryStore, (args.query as string) ?? "", offset, limit);
       } else if (action === "expand") {
         content = await recallExpand(summaryStore, args.turn_id as string);
       } else {
-        content = await recallBrowse(summaryStore);
+        content = await recallBrowse(summaryStore, offset, limit);
       }
       return { content, exitCode: 0, isError: false };
     },

package/src/agent/extensions/rolling-history/recall.ts

@@ -76,7 +76,12 @@ async function findCacheChild(store: Store, parentId: string): Promise<RecallCac
   return null;
 }
 
-export async function recallSearch(store: Store, query: string): Promise<string> {
+export async function recallSearch(
+  store: Store,
+  query: string,
+  offset = 0,
+  maxResults = 30,
+): Promise<string> {
   if (!query.trim()) return "No query provided.";
   const regex = buildSearchRegex(query);
   const hits: string[] = [];
@@ -106,8 +111,13 @@ export async function recallSearch(store: Store, query: string): Promise<string>
 
   if (hits.length === 0) return `No results found for "${query}".`;
   const total = hits.length;
-  const summary = `Found ${total} match${total === 1 ? "" : "es"} for "${query}"`;
-  return `${summary}\n\n${hits.slice(0, 30).join("\n\n")}`;
+  const paged = hits.slice(offset, offset + maxResults);
+  const range =
+    offset > 0 || paged.length < total
+      ? ` (showing ${offset + 1}–${offset + paged.length} of ${total})`
+      : "";
+  const summary = `Found ${total} match${total === 1 ? "" : "es"} for "${query}"${range}`;
+  return `${summary}\n\n${paged.join("\n\n")}`;
 }
 
 export async function recallExpand(store: Store, id: string): Promise<string> {
@@ -124,8 +134,19 @@ export async function recallExpand(store: Store, id: string): Promise<string> {
   return `${header}\n\n(no expanded content available — recall cache may have been cleared)`;
 }
 
-export async function recallBrowse(store: Store, limit = 25): Promise<string> {
-  const lines = await readSummaryLines(store, limit);
-  if (lines.length === 0) return "No conversation history.";
-  return ["Recent summary entries:", ...lines.map((l) => `  ${l}`)].join("\n");
+export async function recallBrowse(
+  store: Store,
+  offset = 0,
+  limit = 25,
+): Promise<string> {
+  const overRead = Math.max(limit * 3, offset + limit);
+  const allLines = await readSummaryLines(store, overRead);
+  if (allLines.length === 0) return "No conversation history.";
+  const end = Math.min(offset + limit, allLines.length);
+  const paged = allLines.slice(offset, end);
+  const range =
+    offset > 0 || end < allLines.length
+      ? ` (entries ${offset + 1}–${end} of ${allLines.length} shown)`
+      : "";
+  return [`Recent summary entries${range}:`, ...paged.map((l) => `  ${l}`)].join("\n");
 }