agentic-pi 0.2.3 → 0.2.5

package/README.md

@@ -246,6 +246,114 @@ When skipped (no keys / `--no-web-search`), `status: "skipped"` carries a
 (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`.
+
+### 10. Optional OpenTelemetry export via `--otel`
+
+agentic-pi can export **traces and metrics** for its run to any OTLP-compatible
+collector, using the standard OpenTelemetry JS SDK and the standard `OTEL_*`
+environment variables. This is meant for orchestrators (e.g. lastlight) that
+forward `OTEL_*` config into a sandboxed agentic-pi process so Pi's own activity
+shows up in their observability stack.
+
+**Off unless explicitly enabled.** Enablement precedence (highest first):
+
+1. `--no-otel` → force-disabled (wins over everything).
+2. `--otel` → enabled.
+3. env `AGENTIC_PI_OTEL_ENABLED=1` (when neither flag is passed) → enabled.
+4. otherwise → disabled.
+
+A bare `OTEL_EXPORTER_OTLP_ENDPOINT` does **not** enable telemetry on its own —
+enablement is always intentional. Configure the destination with the usual
+`OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` /
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (etc.) variables, or `--otel-endpoint` as a
+base-URL escape hatch.
+
+**Span tree** (one-shot run → a short-lived root span is correct):
+
+```
+agentic_pi.session                 (root; gen_ai.conversation.id = sessionId)
+└── agentic_pi.turn
+    ├── chat <model>               (per assistant message; tokens, cost, finish reason)
+    └── execute_tool <name>        (per tool call; status, duration)
+```
+
+**Metrics**: `gen_ai.client.token.usage`, `gen_ai.client.operation.duration`,
+`agentic_pi.cost.usd`, `agentic_pi.tool.duration`, `agentic_pi.tool.invocations`,
+`agentic_pi.tool.failures`, `agentic_pi.turns`. Attribute names follow the OTEL
+GenAI semantic conventions where stable, namespaced under `agentic_pi.*` otherwise.
+
+**Metadata-only by default.** Raw prompt/message/tool-result content is **never**
+exported unless you pass `--otel-include-content` (or set
+`AGENTIC_PI_OTEL_INCLUDE_CONTENT=1`), in which case content is bounded and
+truncated. Metric dimensions are always metadata (bounded cardinality).
+
+**Trace correlation.** If a W3C `TRACEPARENT` env var is present, the session
+span is parented to it, so a sandboxed agentic-pi run correlates with the
+caller's trace across the process/container boundary.
+
+**Safe by default.** Telemetry never affects the run's exit code, never writes to
+stdout/stderr (SDK diagnostics route to the warning channel), and degrades to a
+warning if the collector is unreachable. When requested, a final
+`extension_status` event mirrors the others:
+
+```jsonl
+{"type":"extension_status","extension":"telemetry","status":"configured","includeContent":false,"sessionId":"…","timestamp":"…"}
+```
+
+A silent default run (no `--otel`) emits no telemetry event at all.
+
+```bash
+# Export to a local collector (e.g. otel-desktop-viewer, Jaeger, Grafana Alloy)
+echo "summarize the repo" | OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+  node dist/cli.js run --model openai/gpt-5.4-nano --otel --no-session
+```
+
 ## When to use this
 
 - You have an orchestrator that calls a coding agent once per workflow
@@ -261,8 +369,9 @@ surface as a warning before the run starts.
 - 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
 
@@ -307,7 +416,14 @@ GITHUB_TOKEN=ghp_…
 | `--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. |
+| `--otel` | Enable OpenTelemetry traces + metrics export. Off by default. Requires an OTLP endpoint via `OTEL_EXPORTER_OTLP_ENDPOINT` (or `--otel-endpoint`). See section 10. |
+| `--no-otel` | Force-disable OTEL even if `AGENTIC_PI_OTEL_ENABLED=1`. |
+| `--otel-include-content` | Attach prompt/message/tool content to spans (bounded + truncated). Default: metadata-only. |
+| `--otel-service-name <n>` | Override `OTEL_SERVICE_NAME` (default: `agentic-pi`). |
+| `--otel-endpoint <url>` | Override `OTEL_EXPORTER_OTLP_ENDPOINT` base URL. |
 
 Reads the prompt from stdin. Emits JSONL on stdout. Exits 0 on `agent_end`,
 1 on fatal error.
@@ -319,6 +435,7 @@ Reads the prompt from stdin. Emits JSONL on stdout. Exits 0 on `agent_end`,
 {"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":"…"}
@@ -399,6 +516,7 @@ console.log(result.records.length);      // full event log
 | `sandbox` | `{backend, status}` \| `undefined` | Mirror of the `sandbox_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. |
 
@@ -450,6 +568,7 @@ which walks `test/` for `*.test.ts`.
 | `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 |
@@ -521,6 +640,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

@@ -76,6 +76,36 @@ export interface RunConfig {
      * 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";
+    /**
+     * OpenTelemetry traces + metrics export. Tri-state:
+     *   - `true`  (`--otel`)    → enabled.
+     *   - `false` (`--no-otel`) → force-disabled (wins over env).
+     *   - `undefined` (unset)   → enabled iff env AGENTIC_PI_OTEL_ENABLED is truthy.
+     * Off by default. Requires an OTLP endpoint via OTEL_EXPORTER_OTLP_ENDPOINT
+     * (or `--otel-endpoint`). Standard OTEL_* env vars are honored by the SDK.
+     */
+    otel?: boolean;
+    /**
+     * Export raw prompt/message/tool content on spans (bounded + truncated).
+     * Default: false (metadata-only). Set via `--otel-include-content` or env
+     * AGENTIC_PI_OTEL_INCLUDE_CONTENT.
+     */
+    otelIncludeContent?: boolean;
+    /** Override OTEL_SERVICE_NAME (default: "agentic-pi"). */
+    otelServiceName?: string;
+    /** Override OTEL_EXPORTER_OTLP_ENDPOINT (escape hatch; prefer the env var). */
+    otelEndpoint?: string;
 }
 export declare function printHelp(): void;
 export declare function parseArgs(argv: string[]): RunConfig;

package/dist/args.js

@@ -43,6 +43,22 @@ Flags:
   --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.
+  --otel                     Enable OpenTelemetry traces + metrics export.
+                              Off by default. Requires an OTLP endpoint via
+                              OTEL_EXPORTER_OTLP_ENDPOINT (or --otel-endpoint).
+                              Honors standard OTEL_* env vars. Can also be
+                              enabled with AGENTIC_PI_OTEL_ENABLED=1.
+  --no-otel                  Force-disable OTEL even if AGENTIC_PI_OTEL_ENABLED
+                              is set (highest precedence).
+  --otel-include-content     Attach prompt/message/tool content to spans
+                              (bounded + truncated). Default: metadata-only.
+  --otel-service-name <n>    Override OTEL_SERVICE_NAME (default: agentic-pi).
+  --otel-endpoint <url>      Override OTEL_EXPORTER_OTLP_ENDPOINT base URL.
   --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).
@@ -64,6 +80,7 @@ export function parseArgs(argv) {
         dangerouslySkipPermissions: false,
         sandbox: "none",
         webSearch: true,
+        fileSearch: true,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -176,6 +193,40 @@ export function parseArgs(argv) {
                 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 "--otel":
+                config.otel = true;
+                break;
+            case "--no-otel":
+                config.otel = false;
+                break;
+            case "--otel-include-content":
+                config.otelIncludeContent = true;
+                break;
+            case "--otel-service-name": {
+                const v = next().trim();
+                if (!v)
+                    throw new Error("--otel-service-name requires a value");
+                config.otelServiceName = v;
+                break;
+            }
+            case "--otel-endpoint": {
+                const v = next().trim();
+                if (!v)
+                    throw new Error("--otel-endpoint requires a value");
+                config.otelEndpoint = 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":"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"}
+{"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/run.d.ts

@@ -90,6 +90,31 @@ export interface RunOptions {
      * payload (the agent can recover).
      */
     webSearchMaxCalls?: number;
+    /**
+     * File-search extension (FFF) toggle. Default: `true` — bundled and
+     * enabled for every run. Set to `false` 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). The `PI_FFF_MODE` env var, if set, wins.
+     */
+    fileSearchMode?: "override" | "tools-only" | "tools-and-ui";
+    /**
+     * Enable OTEL traces + metrics export. Default: `false` (or env
+     * `AGENTIC_PI_OTEL_ENABLED=1`). `false` here force-disables. Requires an
+     * OTLP endpoint via `OTEL_EXPORTER_OTLP_ENDPOINT` or `otelEndpoint`.
+     * Standard `OTEL_*` env vars are honored by the SDK. Sandbox/env-driven
+     * callers can leave this unset and rely on `AGENTIC_PI_OTEL_ENABLED`.
+     */
+    otel?: boolean;
+    /** Attach bounded raw content to spans. Default: `false` (metadata-only). */
+    otelIncludeContent?: boolean;
+    /** Override OTEL service name (default: "agentic-pi"). */
+    otelServiceName?: string;
+    /** Override the OTLP endpoint base URL (escape hatch; prefer the env var). */
+    otelEndpoint?: string;
     /**
      * Called for every emitted JSONL record in order. Same shape that the
      * CLI writes to stdout, with `sessionId` and `timestamp` already injected.
@@ -170,6 +195,23 @@ export interface RunResult {
         toolCount: number;
         maxCalls?: number;
     };
+    fileSearch?: {
+        status: "configured" | "skipped";
+        reason?: string;
+        message?: string;
+        mode?: string;
+        toolCount: number;
+    };
+    /**
+     * Mirror of the telemetry `extension_status` line. Present only when OTEL
+     * was requested (enabled or explicitly disabled); absent on a default run.
+     */
+    telemetry?: {
+        status: "configured" | "skipped";
+        reason?: string;
+        message?: string;
+        includeContent?: boolean;
+    };
     /** Every JSONL record the run emitted, in order. */
     records: EmitterRecord[];
     /** Warnings that would have gone to stderr in CLI mode. */

package/dist/run.js

@@ -49,6 +49,12 @@ export async function run(options) {
         webSearch: options.webSearch ?? true,
         webSearchProvider: options.webSearchProvider,
         webSearchMaxCalls: options.webSearchMaxCalls,
+        fileSearch: options.fileSearch ?? true,
+        fileSearchMode: options.fileSearchMode,
+        otel: options.otel,
+        otelIncludeContent: options.otelIncludeContent,
+        otelServiceName: options.otelServiceName,
+        otelEndpoint: options.otelEndpoint,
     };
     const collector = new CollectorSink(options.onEvent);
     const sink = options.extraSink
@@ -106,6 +112,23 @@ function buildResult(exitCode, records, warnings) {
                         maxCalls: r.maxCalls,
                     };
                 }
+                else if (r.extension === "file-search") {
+                    result.fileSearch = {
+                        status: r.status,
+                        reason: r.reason,
+                        message: r.message,
+                        mode: r.mode,
+                        toolCount: r.toolCount ?? 0,
+                    };
+                }
+                else if (r.extension === "telemetry") {
+                    result.telemetry = {
+                        status: r.status,
+                        reason: r.reason,
+                        message: r.message,
+                        includeContent: r.includeContent,
+                    };
+                }
                 break;
             case "message_end": {
                 // Accumulate assistant text. Pi's message structure:

package/dist/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}