agentic-pi 0.2.2 → 0.2.4

package/README.md

@@ -42,8 +42,8 @@ single line you parse.
 
 Pi explicitly does not support MCP. agentic-pi ships a native Pi extension
 exposing **31 GitHub tools** ported from lastlight's `mcp-github-app`:
-clone/push, issues, PRs, reviews, labels, search. Tools are registered with
-the `github_` prefix to match opencode's MCP-server-name convention.
+clone/push, issues, PRs, reviews, labels, search. Tool names are prefixed
+with `github_`.
 
 Auth is opinionated: **GitHub App credentials preferred**, static
 `GITHUB_TOKEN` only as a low-trust fallback. JWT-minted installation tokens
@@ -81,38 +81,29 @@ The `extension_status` JSONL event always reports `status`, `reason`,
 `message`, `profile`, and `toolCount` so the orchestrator can log the
 outcome programmatically without parsing stderr.
 
-### 5. Models named the way opencode names them
+### 5. Model selection
 
-`--model provider/id` accepts the exact string format opencode used
-(`openai/gpt-5.5`, `anthropic/claude-opus-4-5`, etc.). Credentials come from
-environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
-`OPENROUTER_API_KEY`) or Pi's `~/.pi/agent/auth.json` if you've logged in
-interactively. Provider/id mapping is delegated to `@earendil-works/pi-ai`'s
-`getModel()`.
+`--model provider/id` (e.g. `anthropic/claude-opus-4-5`, `openai/gpt-4o`).
+Credentials come from environment variables (`OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`) or Pi's `~/.pi/agent/auth.json`
+if you've logged in interactively. Provider/id mapping is delegated to
+`@earendil-works/pi-ai`'s `getModel()`.
 
 `--thinking <level>` maps directly to Pi's `thinkingLevel`
 (`off`/`minimal`/`low`/`medium`/`high`/`xhigh`). Per-provider effort is
 handled by Pi.
 
-### 6. Things accepted but ignored for caller-side compatibility
-
-- `--dangerously-skip-permissions` — Pi has no permission prompts to skip
-  ("run in a container" is Pi's design stance). The flag is accepted so a
-  caller that previously spawned opencode does not need to strip it.
-- `--variant <level>` — alias for `--thinking`.
-
-### 7. Defaults that match a containerized sandbox
+### 6. Defaults that match a containerized sandbox
 
 - **`--no-session`** is intended to be the default in sandboxed runs (state
   lives outside the container).
 - **Built-in tools** (read, write, edit, bash, grep, find, ls) are enabled
   by default. Add `--no-builtin-tools` if you want a GitHub-only agent.
 - **`AGENTS.md`** in the working directory is auto-loaded as the agent's
-  system prompt — same convention Pi and opencode share. Drop your
-  workflow's `AGENTS.md` into the mounted workspace and the agent picks it
-  up.
+  system prompt — same convention Pi uses. Drop your workflow's
+  `AGENTS.md` into the mounted workspace and the agent picks it up.
 
-### 8. Optional micro-VM sandboxing via `--sandbox gondolin`
+### 7. Optional micro-VM sandboxing via `--sandbox gondolin`
 
 By default Pi's file and bash tools run on the host. Pass `--sandbox gondolin`
 and they get routed through a per-run [Gondolin](https://github.com/earendil-works/gondolin)
@@ -195,14 +186,120 @@ The **App PEM is never copied into the VM** — only the resulting token,
 which is short-lived. User-supplied `--sandbox-env GITHUB_TOKEN=…`
 overrides the auto-injected value if you need to scope down further.
 
+### 8. Safe web search via the `web-search` extension
+
+agentic-pi can register two native Pi tools — `web_search` and `web_fetch` —
+so the agent can do general-purpose research. Backed by a configurable
+provider:
+
+| Provider | API key env var | Native content extraction |
+| --- | --- | --- |
+| Tavily (default) | `TAVILY_API_KEY` | yes (search + extract) |
+| Exa | `EXA_API_KEY` | yes (search + contents) |
+| Brave Search | `BRAVE_SEARCH_API_KEY` | no — `web_fetch` falls back to a safe HTML→text extractor |
+
+**Auto-enable.** When at least one API key env var is present, the
+extension is configured automatically. With multiple keys set, priority is
+**Tavily → Exa → Brave**; override with `--web-search-provider` or the
+`WEB_SEARCH_PROVIDER` env var. Pass `--no-web-search` to suppress the
+tools entirely.
+
+**Host-process egress.** Both tools run in the agentic-pi process, **not**
+inside the Gondolin guest. That means:
+
+- The provider API host is **not** added to the Gondolin egress
+  allowlist, and the API key is **never** injected into the VM.
+- Behavior is identical under `--sandbox=none`, `--sandbox=gondolin`, and
+  when agentic-pi itself is containerized. The host's own network policy
+  controls reachability to the provider + arbitrary http(s) URLs.
+
+**Safety rails (built-in, non-configurable in v1).**
+
+| Rail | Default |
+| --- | --- |
+| URL scheme allowlist | `http`, `https` only (`web_fetch`) |
+| Request timeout | 15 s |
+| Max response bytes | 1 MiB (streamed, aborted on overflow) |
+| Max redirects | 3 (scheme re-checked at each hop) |
+| Content-type gate (`web_fetch`) | `text/*`, `application/(xhtml+xml\|xml\|json)` |
+| Max search results | 10 (regardless of `max_results` arg) |
+| Extracted text cap | ~200 KiB |
+| HTML cleaning | `<script>`, `<style>`, `<noscript>`, `<iframe>`, comments stripped before extraction |
+| Per-run call budget | 30 combined `web_search` + `web_fetch` calls (override with `--web-search-max-calls`) |
+
+When the call budget is hit, further invocations return a structured
+rate-limit error result so the agent can recover; the run is **not**
+aborted.
+
+**No SSRF blocking.** Loopback / private IP ranges are **not** blocked by
+default. Operators who care should run agentic-pi behind their own
+egress firewall.
+
+**Event stream.** A second `extension_status` event mirrors GitHub's:
+
+```jsonl
+{"type":"extension_status","extension":"web-search","status":"configured","provider":"tavily","toolCount":2,"maxCalls":30,"sessionId":"…","timestamp":"…"}
+```
+
+When skipped (no keys / `--no-web-search`), `status: "skipped"` carries a
+`reason` of `disabled-by-flag` or `no-credentials`. Misconfigurations
+(explicit provider whose key is missing, or an unknown provider name)
+surface as a warning before the run starts.
+
+### 9. Default file search via FFF
+
+agentic-pi bundles [`@ff-labs/pi-fff`](https://github.com/dmtrKovalenko/fff/tree/main/packages/pi-fff)
+— a Rust-backed, git-aware, frecency-ranked, SIMD-accelerated fuzzy file/content
+search — as the **default** file-search backend. It ships as a dependency and is
+loaded for **every** run with no per-host `pi install` required.
+
+**`override` mode by default.** FFF registers under Pi's built-in tool names
+(`find`, `grep`, `multi_grep`), transparently replacing the built-ins. The agent
+gets faster, git-aware search with zero prompt changes. Switch behaviour with
+`--file-search-mode`:
+
+| Mode | Tool names | Notes |
+| --- | --- | --- |
+| `override` (default) | `find`, `grep`, `multi_grep` | Transparent replacement of Pi's built-ins. |
+| `tools-only` | `fffind`, `ffgrep`, `fff-multi-grep` | Added alongside Pi's built-ins; the agent chooses. |
+| `tools-and-ui` | same as `tools-only` | Adds `@`-mention autocomplete — useless headless; not recommended. |
+
+The CLI flag maps to FFF's `PI_FFF_MODE` env var. An explicit `PI_FFF_MODE` in the
+environment wins over the flag. Pass `--no-file-search` to disable FFF entirely and
+fall back to Pi's built-in `find`/`grep`.
+
+**Host-process execution.** Like web search, FFF runs in the agentic-pi process,
+**not** inside the Gondolin guest. Under `--sandbox gondolin`, `read`/`write`/`edit`/
+`bash` route through the VM while `find`/`grep` (FFF) run host-side against the
+bind-mounted workspace. Paths align (cwd is the mount), and FFF only touches the
+local filesystem — no egress or secret exposure.
+
+**Native binary.** FFF is a native Rust library (`@ff-labs/fff-node`) shipped as
+prebuilt per-platform binaries (`fff-bin-linux-x64-gnu`/`-musl`, `darwin`, `win32`).
+npm auto-selects the correct one at install time. In containers, run `npm install`
+on the target platform — do **not** copy `node_modules` across glibc↔musl.
+
+**Safe by default.** If pi-fff can't be resolved or its native binary fails to load
+on the platform, the run is **not** aborted — file search skips with
+`reason: "resolve-failed"` (surfaced as a warning) and the agent falls back to Pi's
+built-in `find`/`grep`.
+
+**Event stream.** A third `extension_status` event mirrors the others:
+
+```jsonl
+{"type":"extension_status","extension":"file-search","status":"configured","mode":"override","toolCount":3,"sessionId":"…","timestamp":"…"}
+```
+
+When disabled or unavailable, `status: "skipped"` carries a `reason` of
+`disabled-by-flag` or `resolve-failed`.
+
 ## When to use this
 
 - You have an orchestrator that calls a coding agent once per workflow
   phase, in a container, and parses a JSONL stream.
-- You used to call `opencode run --format json` and want a less-opaque
-  replacement built on a more hackable substrate.
 - You need GitHub repo operations available to the agent without standing
   up an MCP server.
+- You want safe, sandbox-mode-agnostic web search available to the agent.
 
 ## When **not** to use this
 
@@ -211,8 +308,9 @@ overrides the auto-injected value if you need to scope down further.
 - You want generic MCP support. Pi has none by design and agentic-pi inherits
   that decision; only the GitHub tool surface is built-in.
 - You want a different tool surface (Linear, GitLab, internal APIs). Fork the
-  `extensions/github/` directory as a template, not as a runtime plugin
-  system — agentic-pi does not (yet) load arbitrary external extensions.
+  `extensions/github/` directory as a template. agentic-pi bundles specific Pi
+  extensions (GitHub, web search, FFF file search) but does not (yet) load
+  arbitrary operator-supplied extensions as a runtime plugin system.
 
 ## Usage
 
@@ -245,16 +343,21 @@ GITHUB_TOKEN=ghp_…
 | --- | --- |
 | `--model <provider/id>` | Required. e.g. `anthropic/claude-opus-4-5`, `openai/gpt-4o`. |
 | `--thinking <level>` | `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh`. |
-| `--variant <level>` | Alias for `--thinking`. |
 | `--profile <name>` | `read` \| `issues-write` \| `review-write` \| `repo-write`. Omit to disable GitHub tools entirely. |
 | `--cwd <path>` | Working directory for the agent. Default: `$PWD`. |
 | `--no-session` | Ephemeral run — do not persist session jsonl. Recommended in sandboxed containers. |
 | `--session-dir <path>` | Override session storage location. |
 | `--no-builtin-tools` | Disable Pi's `read,write,edit,bash,grep,find,ls`. |
 | `--tools <a,b,c>` | Explicit tool allowlist (combined with profile if set). |
-| `--sandbox <none\|gondolin>` | Route `read`/`write`/`edit`/`bash` through a sandbox backend. Default `none`. `gondolin` boots a QEMU micro-VM mounting cwd at `/workspace`. Requires QEMU on the host; native-only (not Docker-in-Docker). See section 8. |
+| `--sandbox <none\|gondolin>` | Route `read`/`write`/`edit`/`bash` through a sandbox backend. Default `none`. `gondolin` boots a QEMU micro-VM mounting cwd at `/workspace`. Requires QEMU on the host; native-only (not Docker-in-Docker). See section 7. |
 | `--sandbox-env KEY=VAL` | Inject env var into the sandbox VM (repeatable). Ignored when `--sandbox=none`. Auto-injects a minted `GITHUB_TOKEN`/`GH_TOKEN` when `--profile` is also active. |
-| `--dangerously-skip-permissions` | Accepted for caller-side compatibility. No-op. |
+| `--allow-host <host>` | Add host to the sandbox HTTP egress allowlist (repeatable). Ignored when `--sandbox=none`. |
+| `--no-network` | Disable sandbox HTTP egress entirely. Ignored when `--sandbox=none`. |
+| `--web-search-provider <p>` | Force web-search provider: `tavily` \| `brave` \| `exa`. Default: auto-detect by env. See section 8. |
+| `--no-web-search` | Disable the web-search extension (no `web_search`/`web_fetch` tools). |
+| `--no-file-search` | Disable the bundled FFF file-search extension; fall back to Pi's built-in `find`/`grep`. |
+| `--file-search-mode <m>` | FFF mode: `override` (default) \| `tools-only` \| `tools-and-ui`. Overridden by the `PI_FFF_MODE` env var. See section 9. |
+| `--web-search-max-calls <n>` | Cap combined `web_search` + `web_fetch` calls per run. Default: 30. |
 
 Reads the prompt from stdin. Emits JSONL on stdout. Exits 0 on `agent_end`,
 1 on fatal error.
@@ -265,6 +368,8 @@ Reads the prompt from stdin. Emits JSONL on stdout. Exits 0 on `agent_end`,
 {"type":"session","version":3,"id":"<uuid>","timestamp":"…","cwd":"…"}
 {"type":"sandbox_status","backend":"none","status":{"backend":"none"},"sessionId":"<uuid>","timestamp":"…"}
 {"type":"extension_status","extension":"github","status":"configured","profile":"read","toolCount":18,"sessionId":"<uuid>","timestamp":"…"}
+{"type":"extension_status","extension":"web-search","status":"configured","provider":"tavily","toolCount":2,"maxCalls":30,"sessionId":"<uuid>","timestamp":"…"}
+{"type":"extension_status","extension":"file-search","status":"configured","mode":"override","toolCount":3,"sessionId":"<uuid>","timestamp":"…"}
 {"type":"agent_start","sessionId":"<uuid>","timestamp":"…"}
 {"type":"turn_start","sessionId":"<uuid>","timestamp":"…"}
 {"type":"message_start","message":{…},"sessionId":"<uuid>","timestamp":"…"}
@@ -343,7 +448,9 @@ console.log(result.records.length);      // full event log
 | `messages` | `unknown[]` | Full Pi message array from `agent_end`. |
 | `stats` | `{userMessages, assistantMessages, toolCalls, toolResults, tokens: {input, output, cacheRead, cacheWrite, total}, cost}` \| `undefined` | Token + cost rollup. |
 | `sandbox` | `{backend, status}` \| `undefined` | Mirror of the `sandbox_status` event. |
-| `github` | `{status, reason, profile, toolCount}` \| `undefined` | Mirror of the `extension_status` event. |
+| `github` | `{status, reason, profile, toolCount}` \| `undefined` | Mirror of the GitHub `extension_status` event. |
+| `webSearch` | `{status, reason, provider, toolCount, maxCalls}` \| `undefined` | Mirror of the web-search `extension_status` event. |
+| `fileSearch` | `{status, reason, mode, toolCount}` \| `undefined` | Mirror of the FFF file-search `extension_status` event. |
 | `records` | `EmitterRecord[]` | Every JSONL record in order. Same shape that the CLI writes. |
 | `warnings` | `string[]` | Warnings that would have gone to stderr in CLI mode. |
 
@@ -394,6 +501,8 @@ which walks `test/` for `*.test.ts`.
 | `test/models.test.ts` | `provider/id` parsing including openrouter triple-slash | — |
 | `test/extensions/github/profiles.test.ts` | Profile → tool allowlist (counts, superset structure, scope tiering) | — |
 | `test/extensions/github/credentials.test.ts` | `assertSafeToken` and `credentialsFilePath` validation | — |
+| `test/extensions/web-search/*.test.ts` | Provider selection, extension wiring, safe-fetch rails, HTML extraction, rate limiter, per-provider normalization (all with injected `fetchImpl`) | — |
+| `test/extensions/file-search/index.test.ts` | FFF extension wiring: mode → tool names, package resolution, disabled-by-flag + resolve-failed skips | — |
 | `test/sandbox/preflight.test.ts` | Preflight returns a structured ok\|error result | — |
 | `test/run.integration.test.ts` | Programmatic `run()`: RunResult populated, onEvent fires for every record, **child-process check confirms zero stdout/stderr leak from library** | `OPENAI_API_KEY` not set |
 | `test/run-sandbox.integration.test.ts` | `run({ sandbox: "gondolin" })` boots a VM, agent's `write` tool produces a host file via the mount | `OPENAI_API_KEY` not set OR QEMU/preflight unavailable |
@@ -465,6 +574,8 @@ src/
     credentials.ts             git credential-store file writer (mode 600)
     profiles.ts                4 profiles → tool name allowlists
     tools.ts                   31 defineTool() registrations
+  extensions/file-search/
+    index.ts                   loadFileSearchExtension() — resolves bundled @ff-labs/pi-fff
   sandbox/
     index.ts                   buildSandbox(backend) dispatcher
     preflight.ts               QEMU + accelerator detection (refuses to start if hung)

package/dist/args.d.ts

@@ -60,6 +60,33 @@ export interface RunConfig {
      * entirely. Ignored when `sandbox === "none"`.
      */
     allowedHttpHosts?: string[] | null;
+    /**
+     * Web-search extension toggle. Default: true (auto-enables when a
+     * provider API key env var is present). Pass `--no-web-search` to
+     * force-disable.
+     */
+    webSearch: boolean;
+    /**
+     * Explicit web-search provider. Overrides auto-detection by env var.
+     * Set via `--web-search-provider <tavily|brave|exa>`.
+     */
+    webSearchProvider?: string;
+    /**
+     * Per-run cap on combined web_search + web_fetch calls. Default: 30.
+     * Set via `--web-search-max-calls <n>`.
+     */
+    webSearchMaxCalls?: number;
+    /**
+     * File-search extension (FFF) toggle. Default: true — bundled and
+     * enabled for every run. Pass `--no-file-search` to fall back to Pi's
+     * built-in find/grep.
+     */
+    fileSearch: boolean;
+    /**
+     * FFF mode. Default: "override" (FFF replaces built-in find/grep under
+     * the same names). Set via `--file-search-mode <override|tools-only|tools-and-ui>`.
+     */
+    fileSearchMode?: "override" | "tools-only" | "tools-and-ui";
 }
 export declare function printHelp(): void;
 export declare function parseArgs(argv: string[]): RunConfig;

package/dist/args.js

@@ -34,6 +34,20 @@ Flags:
                               Ignored when --sandbox=none.
   --no-network               Disable HTTP egress from the sandbox entirely.
                               Ignored when --sandbox=none.
+  --web-search-provider <p>  Force a web-search provider: tavily | brave | exa.
+                              Default: auto-detect from env (Tavily > Exa > Brave).
+                              Provider's API key env var must be set:
+                              TAVILY_API_KEY, EXA_API_KEY, or BRAVE_SEARCH_API_KEY.
+  --no-web-search            Disable the web-search extension entirely
+                              (web_search / web_fetch tools not registered).
+  --web-search-max-calls <n> Cap combined web_search + web_fetch calls per run.
+                              Default: 30. When exceeded, further calls return a
+                              structured error result.
+  --no-file-search           Disable the bundled FFF file-search extension; fall
+                              back to Pi's built-in find/grep.
+  --file-search-mode <m>     FFF mode: override | tools-only | tools-and-ui.
+                              Default: override (FFF replaces built-in find/grep
+                              under the same names). Overridden by PI_FFF_MODE env.
   --sandbox-image <name>     Image to boot when --sandbox=gondolin. Values:
                               'default' (recommended) — bundled agentic-pi-dev image
                                 with git/gh/node/python/rust baked in (auto-downloaded).
@@ -54,6 +68,8 @@ export function parseArgs(argv) {
         noBuiltinTools: false,
         dangerouslySkipPermissions: false,
         sandbox: "none",
+        webSearch: true,
+        fileSearch: true,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -147,6 +163,36 @@ export function parseArgs(argv) {
             case "--no-network":
                 config.allowedHttpHosts = null;
                 break;
+            case "--no-web-search":
+                config.webSearch = false;
+                break;
+            case "--web-search-provider": {
+                const v = next().trim();
+                if (!v)
+                    throw new Error("--web-search-provider requires a value");
+                config.webSearchProvider = v;
+                break;
+            }
+            case "--web-search-max-calls": {
+                const v = next();
+                const n = Number(v);
+                if (!Number.isFinite(n) || Math.floor(n) !== n || n < 1) {
+                    throw new Error(`--web-search-max-calls must be a positive integer (got '${v}')`);
+                }
+                config.webSearchMaxCalls = n;
+                break;
+            }
+            case "--no-file-search":
+                config.fileSearch = false;
+                break;
+            case "--file-search-mode": {
+                const v = next();
+                if (v !== "override" && v !== "tools-only" && v !== "tools-and-ui") {
+                    throw new Error(`invalid --file-search-mode '${v}'. Expected: override | tools-only | tools-and-ui`);
+                }
+                config.fileSearchMode = v;
+                break;
+            }
             case "-h":
             case "--help":
                 printHelp();

package/dist/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2DH,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCtB,CAAC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,MAAM,GAAc;QACxB,KAAK,EAAE,EAAE;QACT,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,SAAS,EAAE,KAAK;QAChB,cAAc,EAAE,KAAK;QACrB,0BAA0B,EAAE,KAAK;QACjC,OAAO,EAAE,MAAM;KAChB,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,IAAI,GAAG,GAAW,EAAE;YACxB,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACpB,IAAI,CAAC,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,mBAAmB,CAAC,CAAC;YACrE,OAAO,CAAC,CAAC;QACX,CAAC,CAAC;QACF,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,SAAS,CAAC;YACf,KAAK,IAAI;gBACP,MAAM,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC;gBACtB,MAAM;YACR,KAAK,YAAY,CAAC;YAClB,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;gBACjB,IAAI,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,EAAE,CAAC,CAAC;gBACpD,CAAC;gBACD,MAAM,CAAC,QAAQ,GAAG,CAA0B,CAAC;gBAC7C,MAAM;YACR,CAAC;YACD,KAAK,WAAW;gBACd,MAAM,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;gBACxB,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC;gBACpB,MAAM;YACR,KAAK,cAAc;gBACjB,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;gBACxB,MAAM;YACR,KAAK,eAAe;gBAClB,MAAM,CAAC,UAAU,GAAG,IAAI,EAAE,CAAC;gBAC3B,MAAM;YACR,KAAK,oBAAoB;gBACvB,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;gBAC7B,MAAM;YACR,KAAK,SAAS;gBACZ,MAAM,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACtE,MAAM;YACR,KAAK,gCAAgC;gBACnC,MAAM,CAAC,0BAA0B,GAAG,IAAI,CAAC;gBACzC,MAAM;YACR,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;gBACjB,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;oBACrC,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,8BAA8B,CAAC,CAAC;gBACzE,CAAC;gBACD,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;gBACnB,MAAM;YACR,CAAC;YACD,KAAK,iBAAiB,CAAC,CAAC,CAAC;gBACvB,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;gBACjB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACnB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;gBAChE,CAAC;gBACD,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC;gBACxB,MAAM;YACR,CAAC;YACD,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;gBACjB,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC1B,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;oBACX,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,IAAI,CAAC,CAAC;gBAChE,CAAC;gBACD,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3B,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;gBAC5B,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC1C,MAAM,IAAI,KAAK,CAAC,6DAA6D,GAAG,IAAI,CAAC,CAAC;gBACxF,CAAC;gBACD,MAAM,CAAC,UAAU,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC;gBACjE,MAAM;YACR,CAAC;YACD,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;gBACxB,IAAI,CAAC,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;gBAClE,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;oBAClC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,IAAI,CAAC,CAAC;gBACtE,CAAC;gBACD,gEAAgE;gBAChE,gEAAgE;gBAChE,+DAA+D;gBAC/D,gEAAgE;gBAChE,kEAAkE;gBAClE,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClF,MAAM,CAAC,gBAAgB,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;gBACtC,MAAM;YACR,CAAC;YACD,KAAK,cAAc;gBACjB,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC;gBAC/B,MAAM;YACR,KAAK,IAAI,CAAC;YACV,KAAK,QAAQ;gBACX,SAAS,EAAE,CAAC;gBACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB;gBACE,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,uCAAuC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/extensions/file-search/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * File-search extension entry point.
+ *
+ * Bundles FFF (`@ff-labs/pi-fff`) — a Rust-backed, git-aware,
+ * frecency-ranked fuzzy file/content search — as agentic-pi's default
+ * file-search backend, so every run gets it without a per-host
+ * `pi install`.
+ *
+ * Unlike the `github` and `web-search` extensions, this one does NOT
+ * contribute a `customTools` array. pi-fff is a full Pi extension
+ * (registers tools + an `@`-mention enhancer via an ExtensionFactory), so
+ * it is loaded through Pi's resource loader, not the SDK's `customTools`
+ * channel. This module's job is to:
+ *
+ *   1. Resolve the installed pi-fff package directory (the value the
+ *      runner hands to `DefaultResourceLoader.additionalExtensionPaths`).
+ *   2. Decide the FFF mode the runner publishes via the `PI_FFF_MODE` env.
+ *
+ * Mirrors the other extensions' "safe by default" contract: if the
+ * package can't be resolved (missing / incompatible native binary), we
+ * skip with a reason rather than aborting the run, and the agent falls
+ * back to Pi's built-in `find`/`grep`.
+ */
+/** FFF mode. `override` replaces Pi's built-in find/grep under the same names. */
+export type FileSearchMode = "override" | "tools-only" | "tools-and-ui";
+export declare const VALID_FILE_SEARCH_MODES: FileSearchMode[];
+export declare const DEFAULT_FILE_SEARCH_MODE: FileSearchMode;
+export type FileSearchSkipReason = "disabled-by-flag" | "resolve-failed";
+export interface FileSearchExtensionConfig {
+    /** When false, the extension is force-skipped (disabled-by-flag). Default: true. */
+    fileSearch?: boolean;
+    /** FFF mode. Default: "override". */
+    fileSearchMode?: FileSearchMode;
+    /**
+     * Resolver override (injected by tests). Returns the absolute path to the
+     * installed `@ff-labs/pi-fff` package directory, or throws.
+     */
+    resolvePackageDir?: () => string;
+}
+export interface FileSearchExtensionResult {
+    status: "configured" | "skipped";
+    reason?: FileSearchSkipReason;
+    message?: string;
+    /** The FFF mode in effect (echoed for observability). */
+    mode?: FileSearchMode;
+    /**
+     * Absolute path to the pi-fff package directory. The runner passes this
+     * to `DefaultResourceLoader.additionalExtensionPaths`. Undefined when
+     * skipped.
+     */
+    packageDir?: string;
+    /**
+     * Tool names the agent will see, derived from `mode` (for the
+     * `extension_status` event only — the tools themselves are registered by
+     * pi-fff, not here).
+     */
+    toolNames: string[];
+}
+export declare function loadFileSearchExtension(config?: FileSearchExtensionConfig): FileSearchExtensionResult;
+/**
+ * True if the skip is something the user almost certainly wants surfaced
+ * as a warning. A resolve failure means file search was meant to work but
+ * the install/binary is broken; `disabled-by-flag` is an explicit choice
+ * and stays silent.
+ */
+export declare function isMisconfigurationSkip(result: FileSearchExtensionResult): boolean;

package/dist/extensions/file-search/index.js

@@ -0,0 +1,86 @@
+/**
+ * File-search extension entry point.
+ *
+ * Bundles FFF (`@ff-labs/pi-fff`) — a Rust-backed, git-aware,
+ * frecency-ranked fuzzy file/content search — as agentic-pi's default
+ * file-search backend, so every run gets it without a per-host
+ * `pi install`.
+ *
+ * Unlike the `github` and `web-search` extensions, this one does NOT
+ * contribute a `customTools` array. pi-fff is a full Pi extension
+ * (registers tools + an `@`-mention enhancer via an ExtensionFactory), so
+ * it is loaded through Pi's resource loader, not the SDK's `customTools`
+ * channel. This module's job is to:
+ *
+ *   1. Resolve the installed pi-fff package directory (the value the
+ *      runner hands to `DefaultResourceLoader.additionalExtensionPaths`).
+ *   2. Decide the FFF mode the runner publishes via the `PI_FFF_MODE` env.
+ *
+ * Mirrors the other extensions' "safe by default" contract: if the
+ * package can't be resolved (missing / incompatible native binary), we
+ * skip with a reason rather than aborting the run, and the agent falls
+ * back to Pi's built-in `find`/`grep`.
+ */
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+export const VALID_FILE_SEARCH_MODES = [
+    "override",
+    "tools-only",
+    "tools-and-ui",
+];
+export const DEFAULT_FILE_SEARCH_MODE = "override";
+/** Tool names FFF exposes per mode (see @ff-labs/pi-fff src/index.ts). */
+function toolNamesForMode(mode) {
+    return mode === "override"
+        ? ["find", "grep", "multi_grep"]
+        : ["fffind", "ffgrep", "fff-multi-grep"];
+}
+function defaultResolvePackageDir() {
+    // Resolve relative to this module so it works regardless of the
+    // consumer's cwd. `@ff-labs/pi-fff/package.json` is always present; its
+    // directory is what the loader's package resolver reads the `pi`
+    // manifest from.
+    const require = createRequire(import.meta.url);
+    return dirname(require.resolve("@ff-labs/pi-fff/package.json"));
+}
+export function loadFileSearchExtension(config = {}) {
+    if (config.fileSearch === false) {
+        return {
+            status: "skipped",
+            reason: "disabled-by-flag",
+            message: "file search disabled via --no-file-search",
+            toolNames: [],
+        };
+    }
+    const mode = config.fileSearchMode ?? DEFAULT_FILE_SEARCH_MODE;
+    const resolve = config.resolvePackageDir ?? defaultResolvePackageDir;
+    let packageDir;
+    try {
+        packageDir = resolve();
+    }
+    catch (err) {
+        return {
+            status: "skipped",
+            reason: "resolve-failed",
+            message: `could not resolve @ff-labs/pi-fff: ${err.message}`,
+            mode,
+            toolNames: [],
+        };
+    }
+    return {
+        status: "configured",
+        mode,
+        packageDir,
+        toolNames: toolNamesForMode(mode),
+    };
+}
+/**
+ * True if the skip is something the user almost certainly wants surfaced
+ * as a warning. A resolve failure means file search was meant to work but
+ * the install/binary is broken; `disabled-by-flag` is an explicit choice
+ * and stays silent.
+ */
+export function isMisconfigurationSkip(result) {
+    return result.status === "skipped" && result.reason === "resolve-failed";
+}
+//# sourceMappingURL=index.js.map

package/dist/extensions/file-search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/extensions/file-search/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,MAAM,CAAC,MAAM,uBAAuB,GAAqB;IACvD,UAAU;IACV,YAAY;IACZ,cAAc;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAmB,UAAU,CAAC;AAoCnE,0EAA0E;AAC1E,SAAS,gBAAgB,CAAC,IAAoB;IAC5C,OAAO,IAAI,KAAK,UAAU;QACxB,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC;QAChC,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,wBAAwB;IAC/B,gEAAgE;IAChE,wEAAwE;IACxE,iEAAiE;IACjE,iBAAiB;IACjB,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,SAAoC,EAAE;IAEtC,IAAI,MAAM,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QAChC,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,kBAAkB;YAC1B,OAAO,EAAE,2CAA2C;YACpD,SAAS,EAAE,EAAE;SACd,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,cAAc,IAAI,wBAAwB,CAAC;IAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,iBAAiB,IAAI,wBAAwB,CAAC;IAErE,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,OAAO,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,gBAAgB;YACxB,OAAO,EAAE,sCAAuC,GAAa,CAAC,OAAO,EAAE;YACvE,IAAI;YACJ,SAAS,EAAE,EAAE;SACd,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,YAAY;QACpB,IAAI;QACJ,UAAU;QACV,SAAS,EAAE,gBAAgB,CAAC,IAAI,CAAC;KAClC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAiC;IACtE,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,gBAAgB,CAAC;AAC3E,CAAC"}

package/dist/extensions/web-search/extract.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal HTML → readable text extractor. No dependencies.
+ *
+ * Approach:
+ *   1. Strip <script>, <style>, <noscript>, <iframe>, and HTML comments
+ *      so the agent never sees code or hidden trackers.
+ *   2. Replace block-level tags with newlines so paragraphs stay separated.
+ *   3. Drop all other tags.
+ *   4. Decode the common named entities and any &#NN; / &#xHH; numeric
+ *      escapes.
+ *   5. Collapse runs of whitespace; cap output at MAX_BYTES.
+ *
+ * Not a Readability-style content-only extractor — for that, use Tavily or
+ * Exa's native extraction, which the provider clients invoke directly.
+ */
+export declare const EXTRACT_MAX_BYTES: number;
+export declare function extractTitle(html: string): string | undefined;
+export declare function htmlToText(html: string, maxBytes?: number): string;