agentic-pi 0.2.3 → 0.2.5

package/dist/runner.js

@@ -10,15 +10,20 @@
  * an `onWarn` callback for the same reason — so library consumers never
  * see `process.stderr` writes they didn't ask for.
  */
-import { AuthStorage, ModelRegistry, SessionManager, createAgentSession, } from "@earendil-works/pi-coding-agent";
+import { AuthStorage, DefaultResourceLoader, ModelRegistry, SessionManager, createAgentSession, getAgentDir, } from "@earendil-works/pi-coding-agent";
 import { Emitter } from "./emitter.js";
 import { loadGitHubExtension, isMisconfigurationSkip } from "./extensions/github/index.js";
 import { loadWebSearchExtension, isMisconfigurationSkip as isWebSearchMisconfig, } from "./extensions/web-search/index.js";
+import { loadFileSearchExtension, isMisconfigurationSkip as isFileSearchMisconfig, } from "./extensions/file-search/index.js";
 import { resolveModel } from "./models.js";
 import { buildSandbox } from "./sandbox/index.js";
 import { ensureImage, ImageLoaderError } from "./sandbox/images/loader.js";
+import { createTelemetry, resolveTelemetryConfig } from "./telemetry/index.js";
 export async function runOnce(config, prompt, deps) {
     const warn = deps.onWarn ?? (() => undefined);
+    // Resolved up front so the telemetry extension_status can be emitted in the
+    // same block as the others. Off unless explicitly enabled (see resolver).
+    const telemetryConfig = resolveTelemetryConfig(config, process.env);
     const authStorage = AuthStorage.create();
     const modelRegistry = ModelRegistry.create(authStorage);
     const model = resolveModel(config.model, modelRegistry);
@@ -56,6 +61,24 @@ export async function runOnce(config, prompt, deps) {
         // WEB_SEARCH_PROVIDER to override". Soft warning, not a misconfig.
         warn(`web-search: ${webSearch.message}`);
     }
+    // File-search extension (FFF). Bundled, default-on. Unlike github /
+    // web-search it doesn't contribute customTools — it's a full Pi
+    // extension loaded through the resource loader below. Here we only
+    // resolve the package and decide the mode; load failures are
+    // non-fatal (the agent falls back to Pi's built-in find/grep).
+    const fileSearch = loadFileSearchExtension({
+        fileSearch: config.fileSearch,
+        fileSearchMode: config.fileSearchMode,
+    });
+    // pi-fff reads its mode from the PI_FFF_MODE env in SDK mode (there is
+    // no CLI flag source). Publish the resolved mode, but never clobber an
+    // explicit operator-set value.
+    if (fileSearch.status === "configured" && fileSearch.mode && !process.env.PI_FFF_MODE) {
+        process.env.PI_FFF_MODE = fileSearch.mode;
+    }
+    if (isFileSearchMisconfig(fileSearch)) {
+        warn(`file-search extension disabled (${fileSearch.reason}): ${fileSearch.message ?? ""}`);
+    }
     // Compose the env for the sandbox VM. Order (later wins):
     //   1. Auto-injected GITHUB_TOKEN/GH_TOKEN from a minted installation
     //      token (when sandbox=gondolin AND github extension is configured).
@@ -135,6 +158,32 @@ export async function runOnce(config, prompt, deps) {
     const noToolsMode = config.noBuiltinTools ? "builtin" :
         sandbox.suppressBuiltins ? "builtin" :
             undefined;
+    // Build the resource loader ourselves so we can inject the bundled
+    // pi-fff extension via additionalExtensionPaths while preserving Pi's
+    // default discovery (~/.pi/agent + project .pi). Mirrors the loader
+    // createAgentSession would build by default (same cwd + agentDir).
+    const agentDir = getAgentDir();
+    const resourceLoader = new DefaultResourceLoader({
+        cwd: config.cwd,
+        agentDir,
+        additionalExtensionPaths: fileSearch.packageDir ? [fileSearch.packageDir] : [],
+    });
+    await resourceLoader.reload();
+    // A load failure (e.g. missing native binary for this platform) is
+    // collected, not thrown — downgrade to a skip and warn so the run
+    // continues on Pi's built-in find/grep.
+    if (fileSearch.status === "configured" && fileSearch.packageDir) {
+        const loadError = resourceLoader
+            .getExtensions()
+            .errors.find((e) => e.path.startsWith(fileSearch.packageDir));
+        if (loadError) {
+            fileSearch.status = "skipped";
+            fileSearch.reason = "resolve-failed";
+            fileSearch.message = `pi-fff failed to load: ${loadError.error}`;
+            fileSearch.toolNames = [];
+            warn(`file-search extension disabled (resolve-failed): ${loadError.error}`);
+        }
+    }
     const { session } = await createAgentSession({
         cwd: config.cwd,
         model,
@@ -142,10 +191,21 @@ export async function runOnce(config, prompt, deps) {
         sessionManager,
         authStorage,
         modelRegistry,
+        resourceLoader,
         tools: config.tools,
         noTools: noToolsMode,
         customTools: [...sandbox.customTools, ...github.customTools, ...webSearch.customTools],
     });
+    // Telemetry observes the raw event stream below. Built after the session so
+    // it can stamp spans with the real sessionId. When disabled this is a cheap
+    // no-op that imports no OTEL SDK; init failures degrade to a skip + warning.
+    const telemetry = await createTelemetry({
+        config: telemetryConfig,
+        sessionId: session.sessionId,
+        model: config.model,
+        sandboxBackend: sandbox.backend,
+        onWarn: warn,
+    });
     const emitter = new Emitter({
         sessionId: session.sessionId,
         cwd: config.cwd,
@@ -176,9 +236,32 @@ export async function runOnce(config, prompt, deps) {
         toolCount: webSearch.toolNames.length,
         maxCalls: webSearch.maxCalls,
     });
+    emitter.event({
+        type: "extension_status",
+        extension: "file-search",
+        status: fileSearch.status,
+        reason: fileSearch.reason,
+        message: fileSearch.message,
+        mode: fileSearch.mode,
+        toolCount: fileSearch.toolNames.length,
+    });
+    // Only surfaced when telemetry was actually requested (enabled, or explicitly
+    // --no-otel). A silent default run emits nothing here, so the existing JSONL
+    // fixtures stay valid (AGENTS.md rule #2).
+    if (telemetryConfig.enabled || telemetryConfig.reason === "disabled-by-flag") {
+        emitter.event({
+            type: "extension_status",
+            extension: "telemetry",
+            status: telemetry.status,
+            reason: telemetry.reason,
+            message: telemetry.message,
+            includeContent: telemetryConfig.includeContent,
+        });
+    }
     let sawError = false;
     let agentEndSeen = false;
     const unsubscribe = session.subscribe((event) => {
+        telemetry.onEvent(event);
         emitter.event(event);
         if (event.type === "tool_execution_end" && event.isError) {
             sawError = true;
@@ -196,6 +279,8 @@ export async function runOnce(config, prompt, deps) {
             error: { name: err.name, message: err.message },
         });
         unsubscribe();
+        telemetry.recordFatal(err);
+        await telemetry.shutdown();
         session.dispose();
         await sandbox.close();
         return 1;
@@ -204,6 +289,7 @@ export async function runOnce(config, prompt, deps) {
     // does not carry per-event token/cost; lastlight reads this terminal event.
     try {
         const stats = session.getSessionStats();
+        telemetry.recordSessionStats(stats);
         emitter.event({
             type: "usage_snapshot",
             stats: {
@@ -223,6 +309,7 @@ export async function runOnce(config, prompt, deps) {
         });
     }
     unsubscribe();
+    await telemetry.shutdown();
     session.dispose();
     await sandbox.close();
     if (sawError && !agentEndSeen)

package/dist/runner.js.map

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

package/dist/telemetry/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Telemetry enablement + content-gating resolution.
+ *
+ * Pure and SDK-free on purpose: no `@opentelemetry/*` imports here, so the
+ * precedence rules are trivially unit-testable and importing this module
+ * costs nothing on the common (telemetry-disabled) path.
+ */
+/** Inputs the resolver reads off `RunConfig` (kept structural to avoid a cycle). */
+export interface TelemetryConfigInput {
+    /** Tri-state: true = --otel, false = --no-otel, undefined = env decides. */
+    otel?: boolean;
+    /** Export raw prompt/message/tool content (bounded). Default false. */
+    otelIncludeContent?: boolean;
+    /** Override OTEL_SERVICE_NAME. */
+    otelServiceName?: string;
+    /** Override OTEL_EXPORTER_OTLP_ENDPOINT. */
+    otelEndpoint?: string;
+}
+export type TelemetrySkipReason = "not-enabled" | "disabled-by-flag";
+export interface TelemetryConfig {
+    enabled: boolean;
+    /** Why telemetry is off (only set when `enabled` is false). */
+    reason?: TelemetrySkipReason;
+    /** Whether raw content may be attached to spans. */
+    includeContent: boolean;
+    /** Resolved service name (flag > OTEL_SERVICE_NAME > default applied at init). */
+    serviceName?: string;
+    /** Explicit OTLP endpoint override (flag); env is honored by the SDK directly. */
+    endpoint?: string;
+}
+type Env = Record<string, string | undefined>;
+/**
+ * Resolve whether telemetry is enabled and how content is treated.
+ *
+ * Enablement precedence (highest first):
+ *   1. `--no-otel` (otel === false)        → disabled, reason "disabled-by-flag".
+ *   2. `--otel` (otel === true)            → enabled.
+ *   3. env `AGENTIC_PI_OTEL_ENABLED` truthy → enabled.
+ *   4. otherwise                           → disabled, reason "not-enabled".
+ *
+ * A bare `OTEL_EXPORTER_OTLP_ENDPOINT` does NOT enable telemetry: the spec is
+ * "off unless explicitly enabled", and many environments export `OTEL_*`
+ * globally. Enablement must be intentional.
+ *
+ * Content gating: on iff `--otel-include-content` OR env
+ * `AGENTIC_PI_OTEL_INCLUDE_CONTENT` is truthy. Default is metadata-only.
+ */
+export declare function resolveTelemetryConfig(cfg: TelemetryConfigInput, env: Env): TelemetryConfig;
+/** Cap on a single content attribute's length when content export is enabled. */
+export declare const MAX_CONTENT_CHARS = 4096;
+/**
+ * Render a value for a content-gated span attribute.
+ *
+ * Returns `undefined` when content export is off (the attribute is then simply
+ * never set). When on, stringifies and truncates to {@link MAX_CONTENT_CHARS}
+ * with a marker so oversized prompts/results don't bloat OTLP payloads.
+ */
+export declare function redact(value: unknown, includeContent: boolean): string | undefined;
+export {};

package/dist/telemetry/config.js

@@ -0,0 +1,70 @@
+/**
+ * Telemetry enablement + content-gating resolution.
+ *
+ * Pure and SDK-free on purpose: no `@opentelemetry/*` imports here, so the
+ * precedence rules are trivially unit-testable and importing this module
+ * costs nothing on the common (telemetry-disabled) path.
+ */
+function isTruthy(v) {
+    if (v === undefined)
+        return false;
+    const s = v.trim().toLowerCase();
+    return s === "1" || s === "true" || s === "yes" || s === "on";
+}
+/**
+ * Resolve whether telemetry is enabled and how content is treated.
+ *
+ * Enablement precedence (highest first):
+ *   1. `--no-otel` (otel === false)        → disabled, reason "disabled-by-flag".
+ *   2. `--otel` (otel === true)            → enabled.
+ *   3. env `AGENTIC_PI_OTEL_ENABLED` truthy → enabled.
+ *   4. otherwise                           → disabled, reason "not-enabled".
+ *
+ * A bare `OTEL_EXPORTER_OTLP_ENDPOINT` does NOT enable telemetry: the spec is
+ * "off unless explicitly enabled", and many environments export `OTEL_*`
+ * globally. Enablement must be intentional.
+ *
+ * Content gating: on iff `--otel-include-content` OR env
+ * `AGENTIC_PI_OTEL_INCLUDE_CONTENT` is truthy. Default is metadata-only.
+ */
+export function resolveTelemetryConfig(cfg, env) {
+    const includeContent = cfg.otelIncludeContent === true || isTruthy(env.AGENTIC_PI_OTEL_INCLUDE_CONTENT);
+    const serviceName = cfg.otelServiceName ?? env.OTEL_SERVICE_NAME;
+    const endpoint = cfg.otelEndpoint;
+    const base = { includeContent, serviceName, endpoint };
+    if (cfg.otel === false) {
+        return { ...base, enabled: false, reason: "disabled-by-flag" };
+    }
+    if (cfg.otel === true || isTruthy(env.AGENTIC_PI_OTEL_ENABLED)) {
+        return { ...base, enabled: true };
+    }
+    return { ...base, enabled: false, reason: "not-enabled" };
+}
+/** Cap on a single content attribute's length when content export is enabled. */
+export const MAX_CONTENT_CHARS = 4096;
+/**
+ * Render a value for a content-gated span attribute.
+ *
+ * Returns `undefined` when content export is off (the attribute is then simply
+ * never set). When on, stringifies and truncates to {@link MAX_CONTENT_CHARS}
+ * with a marker so oversized prompts/results don't bloat OTLP payloads.
+ */
+export function redact(value, includeContent) {
+    if (!includeContent)
+        return undefined;
+    if (value === undefined || value === null)
+        return undefined;
+    const str = typeof value === "string" ? value : safeStringify(value);
+    if (str.length <= MAX_CONTENT_CHARS)
+        return str;
+    return `${str.slice(0, MAX_CONTENT_CHARS)}…[truncated ${str.length - MAX_CONTENT_CHARS} chars]`;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/telemetry/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/telemetry/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8BH,SAAS,QAAQ,CAAC,CAAqB;IACrC,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAClC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAyB,EACzB,GAAQ;IAER,MAAM,cAAc,GAClB,GAAG,CAAC,kBAAkB,KAAK,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IACnF,MAAM,WAAW,GAAG,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,iBAAiB,CAAC;IACjE,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC;IAElC,MAAM,IAAI,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;IAEvD,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QACvB,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACpC,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AAC5D,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,cAAuB;IAC5D,IAAI,CAAC,cAAc;QAAE,OAAO,SAAS,CAAC;IACtC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,GAAG,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACrE,IAAI,GAAG,CAAC,MAAM,IAAI,iBAAiB;QAAE,OAAO,GAAG,CAAC;IAChD,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,eAAe,GAAG,CAAC,MAAM,GAAG,iBAAiB,SAAS,CAAC;AAClG,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Telemetry lifecycle entry point.
+ *
+ * `createTelemetry()` returns a {@link TelemetryHandle} the runner drives with
+ * the raw Pi event stream. When telemetry is disabled (the common case) it
+ * returns a cheap no-op handle and imports NO OpenTelemetry SDK — the heavy
+ * `@opentelemetry/sdk-*` packages are pulled in via a dynamic `import("./sdk.js")`
+ * only on the enabled path, so a default run pays ~zero cost.
+ *
+ * Nothing here writes to `process.stdout`/`process.stderr`: SDK diagnostics are
+ * routed to the `onWarn` callback (see `sdk.ts`), preserving the library
+ * contract that `run()` never touches those streams.
+ */
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { TelemetryConfig } from "./config.js";
+import type { SessionStatsLike } from "./mapper.js";
+export type { TelemetryConfig, TelemetrySkipReason } from "./config.js";
+export { resolveTelemetryConfig } from "./config.js";
+export interface TelemetryHandle {
+    /** Whether the OTEL pipeline is live. */
+    status: "configured" | "skipped";
+    /** Why it is skipped (or "init-failed" when enabled but setup threw). */
+    reason?: string;
+    message?: string;
+    /** Feed every raw Pi session event, in order. No-op when skipped. */
+    onEvent(event: AgentSessionEvent): void;
+    /** Decorate the root span with terminal aggregate stats. No-op when skipped. */
+    recordSessionStats(stats: SessionStatsLike): void;
+    /** Mark the run as fatally errored before shutdown. No-op when skipped. */
+    recordFatal(err: Error): void;
+    /** Flush + shut down exporters. Always resolves; never throws. */
+    shutdown(): Promise<void>;
+}
+export interface CreateTelemetryDeps {
+    config: TelemetryConfig;
+    sessionId: string;
+    /** "provider/model_id" — split into gen_ai.system + gen_ai.request.model. */
+    model: string;
+    sandboxBackend: string;
+    onWarn: (message: string) => void;
+    /** Defaults to process.env; injected by tests. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Build a telemetry handle from the resolved config. Async because the enabled
+ * path dynamically imports the OTEL SDK. Initialization failures degrade to a
+ * skipped handle with a warning — telemetry never breaks the run.
+ */
+export declare function createTelemetry(deps: CreateTelemetryDeps): Promise<TelemetryHandle>;

package/dist/telemetry/index.js

@@ -0,0 +1,45 @@
+/**
+ * Telemetry lifecycle entry point.
+ *
+ * `createTelemetry()` returns a {@link TelemetryHandle} the runner drives with
+ * the raw Pi event stream. When telemetry is disabled (the common case) it
+ * returns a cheap no-op handle and imports NO OpenTelemetry SDK — the heavy
+ * `@opentelemetry/sdk-*` packages are pulled in via a dynamic `import("./sdk.js")`
+ * only on the enabled path, so a default run pays ~zero cost.
+ *
+ * Nothing here writes to `process.stdout`/`process.stderr`: SDK diagnostics are
+ * routed to the `onWarn` callback (see `sdk.ts`), preserving the library
+ * contract that `run()` never touches those streams.
+ */
+export { resolveTelemetryConfig } from "./config.js";
+function noopHandle(reason, message) {
+    return {
+        status: "skipped",
+        reason,
+        message,
+        onEvent: () => undefined,
+        recordSessionStats: () => undefined,
+        recordFatal: () => undefined,
+        shutdown: async () => undefined,
+    };
+}
+/**
+ * Build a telemetry handle from the resolved config. Async because the enabled
+ * path dynamically imports the OTEL SDK. Initialization failures degrade to a
+ * skipped handle with a warning — telemetry never breaks the run.
+ */
+export async function createTelemetry(deps) {
+    if (!deps.config.enabled) {
+        return noopHandle(deps.config.reason);
+    }
+    try {
+        const { startTelemetrySdk } = await import("./sdk.js");
+        return startTelemetrySdk(deps);
+    }
+    catch (err) {
+        const message = err.message;
+        deps.onWarn(`telemetry: initialization failed (${message}); continuing without OTEL`);
+        return noopHandle("init-failed", message);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AA6BrD,SAAS,UAAU,CAAC,MAAe,EAAE,OAAgB;IACnD,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,MAAM;QACN,OAAO;QACP,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS;QACxB,kBAAkB,EAAE,GAAG,EAAE,CAAC,SAAS;QACnC,WAAW,EAAE,GAAG,EAAE,CAAC,SAAS;QAC5B,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS;KAChC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAyB;IAC7D,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACzB,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACvD,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAI,GAAa,CAAC,OAAO,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,qCAAqC,OAAO,4BAA4B,CAAC,CAAC;QACtF,OAAO,UAAU,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC"}

package/dist/telemetry/mapper.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Translates Pi's raw session event stream into an OpenTelemetry span tree
+ * plus metrics.
+ *
+ * Span tree (one-shot run → short-lived, so a real root span is correct):
+ *
+ *   agentic_pi.session                 (root)
+ *   └── agentic_pi.turn                 (per turn_start/turn_end)
+ *       ├── chat <model>                (per assistant message_start→message_end)
+ *       └── execute_tool <name>         (per tool_execution_start→end, keyed by toolCallId)
+ *
+ * Spans and metrics are both sourced from the SAME per-message / per-tool
+ * events (never from the aggregate session stats), so they agree and nothing
+ * is double-counted. Aggregate stats only decorate the root span.
+ *
+ * Every public method is defensive: missing/out-of-order pairs warn once and
+ * never throw — a telemetry glitch must never break the run.
+ */
+import { type Context, type Meter, type Tracer } from "@opentelemetry/api";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+/** Terminal aggregate stats (subset of Pi's SessionStats) for root decoration. */
+export interface SessionStatsLike {
+    tokens?: {
+        input?: number;
+        output?: number;
+        total?: number;
+    };
+    cost?: number;
+}
+export interface SpanMapperDeps {
+    tracer: Tracer;
+    meter: Meter;
+    /** Inbound parent context (extracted traceparent) or ROOT_CONTEXT. */
+    rootParentContext: Context;
+    sessionId: string;
+    /** gen_ai.system (provider, e.g. "openai"). */
+    genAiSystem: string;
+    /** gen_ai.request.model (model id, e.g. "gpt-5.4-nano"). */
+    requestModel: string;
+    sandboxBackend: string;
+    includeContent: boolean;
+    onWarn: (message: string) => void;
+    /** Milliseconds clock seam (tests inject a deterministic one). */
+    now?: () => number;
+}
+export declare class SpanMapper {
+    private readonly d;
+    private readonly now;
+    private readonly inst;
+    private rootSpan?;
+    private rootCtx;
+    private turnSpan?;
+    private turnCtx?;
+    private turnIndex;
+    private llm?;
+    private readonly toolSpans;
+    private ended;
+    private warnedUnknownTool;
+    constructor(deps: SpanMapperDeps);
+    onEvent(event: AgentSessionEvent): void;
+    /** Decorate the root span with terminal aggregate stats (reconciliation only). */
+    recordSessionStats(stats: SessionStatsLike): void;
+    /** Mark the root span as errored (called before shutdown on the fatal path). */
+    recordFatal(err: Error): void;
+    /** Close any still-open spans (ERROR) and end the root. Idempotent. */
+    end(): void;
+    private ensureRoot;
+    private parentCtx;
+    private onTurnStart;
+    private onTurnEnd;
+    private onMessageStart;
+    private onMessageEnd;
+    private onToolStart;
+    private onToolEnd;
+    private onAgentEnd;
+    private setAndMeasureToken;
+    private abandonTurn;
+    private assistantText;
+    private buildInstruments;
+}