@gr8ful/spf 0.3.0 → 0.5.0

package/dist/core/ollama_provider.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Ollama registration for the Flue backend (agent_flue.ts).
+ *
+ * Neither pi-ai nor Flue ship a built-in "ollama" provider — Ollama is
+ * reached through the OpenAI-compatible `/v1/chat/completions` surface it
+ * serves locally, registered the same way any self-hosted OpenAI-compatible
+ * endpoint would be: `createProvider()` + Flue's `setProvider()`. Three
+ * constraints below came out of a live spike (raw logs under
+ * scratchpad/ollama-spike) and would look like accidental complexity to a
+ * future maintainer without this note, so each is called out where it bites.
+ *
+ * EXACT VERSION PIN — see package.json's `@earendil-works/pi-ai: "0.83.0"`
+ * (no caret). `@flue/runtime@2.0.3` itself depends on `^0.83.0`; pinning our
+ * own dependency to the exact same version lets npm dedupe both into ONE
+ * physical copy of pi-ai in node_modules. A newer 0.83.x/0.84.x would still
+ * satisfy flue's range, but npm would then keep two-or-three separate copies
+ * side by side — and the `Provider`/`Model` values this file hands to
+ * `setProvider()` must be instances `@flue/runtime`'s OWN copy of pi-ai
+ * recognizes, or registration silently never reaches the registry flue's
+ * `resolveModel()` actually reads from. Verified live: with the exact pin,
+ * dedupe holds and registration is visible to flue's registry immediately.
+ *
+ * LAZY IMPORT — every symbol used here is loaded via dynamic `import()`
+ * inside `registerOllamaModel`, never at this module's top level. This is
+ * NOT a load-time saving, and the reasoning below is the measured truth, not
+ * the "avoid eagerly loading pi-ai's runtime for non-ollama runs" story that
+ * comment used to tell: `agent_flue.ts` already imports `@flue/runtime/node`
+ * unconditionally, and that import ALONE already pulls in pi-ai's full
+ * runtime (auth flows, every provider's model-catalog JSON, OAuth machinery)
+ * for every SPF run, ollama or not. Measured live: `await
+ * import("@flue/runtime/node")` costs 183ms / 38 pi-ai module-cache entries
+ * by itself; the subsequent `await import("@earendil-works/pi-ai")` costs
+ * 0ms / 0 additional entries, and `await
+ * import("@earendil-works/pi-ai/api/openai-completions.lazy")` costs 1ms / 0
+ * additional entries — pi-ai is already resident by the time either dynamic
+ * import here runs. The real reason to keep the dynamic form is narrower:
+ * it keeps this module's ollama-only symbols — especially the deep
+ * `api/openai-completions.lazy` subpath — off the module graph of anything
+ * that merely imports `agent_flue.ts` for `resolveModel()` (as `doctor.ts`
+ * and `interview.ts` both do) without ever dispatching an ollama call.
+ * `type` imports below are erased at compile time (verbatimModuleSyntax) and
+ * cost nothing at runtime either way.
+ */
+import type { Provider } from "@earendil-works/pi-ai";
+/** Exported so `doctor.ts`'s reachability probe agrees with what a real dispatch resolves to — see its call site for why a `??`/`||` mismatch here matters. */
+export declare function ollamaBaseUrl(): string;
+/**
+ * Registers `modelId` (the part after `ollama/` in an agent's `model`
+ * config) with Flue's provider registry, alongside every other `ollama/*`
+ * id ever registered this process. Idempotent: a repeat of an already-seen
+ * id is a no-op — no re-registration, no re-import. A concurrent call for
+ * the SAME id joins the in-flight registration rather than returning early
+ * (see `inflight`'s doc); `registeredIds` itself is only ever updated AFTER
+ * `setProvider()` succeeds, so a failed attempt (a bad install, a bundler
+ * that can't resolve the deep `.lazy` subpath, a future validation error)
+ * leaves the id unregistered and eligible for a real retry — not
+ * permanently and misleadingly marked "done" while nothing is actually
+ * registered.
+ *
+ * Must complete before the FIRST Flue dispatch that names this model
+ * (agent_flue.ts's `run()` awaits this before `ensureRuntime()`/`start()`),
+ * but is equally safe to call again later with a new id mid-process — that
+ * later call's union re-registration is exactly how a second model gets
+ * added without orphaning the first (see the `registeredIds` doc above).
+ */
+export declare function registerOllamaModel(modelId: string): Promise<void>;
+/** Test-only: the most recently constructed provider object (see `lastProvider`'s doc). */
+export declare function providerForTest(): Provider<"openai-completions"> | undefined;
+/** Test-only: forgets accumulated ids so test files don't leak into each other. Does not touch Flue's own registry — pair with `resetModelsForTests()` from `@flue/runtime/internal`. */
+export declare function resetOllamaRegistrationForTest(): void;

package/dist/core/ollama_provider.js

@@ -0,0 +1,208 @@
+/**
+ * Ollama registration for the Flue backend (agent_flue.ts).
+ *
+ * Neither pi-ai nor Flue ship a built-in "ollama" provider — Ollama is
+ * reached through the OpenAI-compatible `/v1/chat/completions` surface it
+ * serves locally, registered the same way any self-hosted OpenAI-compatible
+ * endpoint would be: `createProvider()` + Flue's `setProvider()`. Three
+ * constraints below came out of a live spike (raw logs under
+ * scratchpad/ollama-spike) and would look like accidental complexity to a
+ * future maintainer without this note, so each is called out where it bites.
+ *
+ * EXACT VERSION PIN — see package.json's `@earendil-works/pi-ai: "0.83.0"`
+ * (no caret). `@flue/runtime@2.0.3` itself depends on `^0.83.0`; pinning our
+ * own dependency to the exact same version lets npm dedupe both into ONE
+ * physical copy of pi-ai in node_modules. A newer 0.83.x/0.84.x would still
+ * satisfy flue's range, but npm would then keep two-or-three separate copies
+ * side by side — and the `Provider`/`Model` values this file hands to
+ * `setProvider()` must be instances `@flue/runtime`'s OWN copy of pi-ai
+ * recognizes, or registration silently never reaches the registry flue's
+ * `resolveModel()` actually reads from. Verified live: with the exact pin,
+ * dedupe holds and registration is visible to flue's registry immediately.
+ *
+ * LAZY IMPORT — every symbol used here is loaded via dynamic `import()`
+ * inside `registerOllamaModel`, never at this module's top level. This is
+ * NOT a load-time saving, and the reasoning below is the measured truth, not
+ * the "avoid eagerly loading pi-ai's runtime for non-ollama runs" story that
+ * comment used to tell: `agent_flue.ts` already imports `@flue/runtime/node`
+ * unconditionally, and that import ALONE already pulls in pi-ai's full
+ * runtime (auth flows, every provider's model-catalog JSON, OAuth machinery)
+ * for every SPF run, ollama or not. Measured live: `await
+ * import("@flue/runtime/node")` costs 183ms / 38 pi-ai module-cache entries
+ * by itself; the subsequent `await import("@earendil-works/pi-ai")` costs
+ * 0ms / 0 additional entries, and `await
+ * import("@earendil-works/pi-ai/api/openai-completions.lazy")` costs 1ms / 0
+ * additional entries — pi-ai is already resident by the time either dynamic
+ * import here runs. The real reason to keep the dynamic form is narrower:
+ * it keeps this module's ollama-only symbols — especially the deep
+ * `api/openai-completions.lazy` subpath — off the module graph of anything
+ * that merely imports `agent_flue.ts` for `resolveModel()` (as `doctor.ts`
+ * and `interview.ts` both do) without ever dispatching an ollama call.
+ * `type` imports below are erased at compile time (verbatimModuleSyntax) and
+ * cost nothing at runtime either way.
+ */
+// Ollama has no auth of its own — `pi-ai`'s auth resolution always calls
+// `getClientApiKey()` before a dispatch, and that call throws "No API key
+// for provider: ollama" if the resolved key is falsy (verified live: the
+// upstream-documented `auth: { apiKey: {} }` recipe, with no `resolve()` or a
+// resolver returning no key, throws exactly that at the FIRST dispatch, not
+// at registration). There is no supported way to mark a provider as needing
+// no key at all — the value below is a placeholder pi-ai never actually
+// sends anywhere Ollama would look at it: Ollama's OpenAI-compatible server
+// does not check the Authorization header's contents.
+const DUMMY_API_KEY = "ollama-local-unused";
+// Advisory only: pi-ai's `openai-completions` api reads this per REQUEST via
+// its own `options.maxTokens`, not from `Model.maxTokens` directly — the
+// field here only feeds Flue's compaction-reserve sizing (moot in practice
+// since `contextWindow: 0` below disables threshold compaction, matching
+// agent_flue.ts's own `context_window: 0`). Kept generous since Ollama
+// enforces nothing against it.
+const DEFAULT_MAX_TOKENS = 8192;
+/**
+ * Every `ollama/<id>` model id a `registerOllamaModel` call has ever
+ * SUCCEEDED in registering, in call order. `setProvider()` REPLACES the
+ * named provider's entire model list on every call — it is not additive —
+ * so this Set is what lets each call re-register the FULL union instead of
+ * just the newest id. Without it: register "a", then "b", and "a" becomes an
+ * unknown model id at its next dispatch (verified live: "Unknown model ID …
+ * for provider \"ollama\""), because the second `setProvider()` call
+ * replaced the first provider object — the one whose `models` list still
+ * had "a" — outright.
+ *
+ * `OLLAMA_BASE_URL` is read fresh (via `ollamaBaseUrl()`) at each
+ * registration call, and the whole union is re-registered at whatever URL
+ * is current AT THAT MOMENT — so a mid-process env change applies unevenly:
+ * ids already registered keep the base URL they were registered under until
+ * the NEXT new id triggers a fresh union re-registration, which then
+ * re-points every id at once. Deliberate: a single local server for the
+ * whole process is the supported case, and this asymmetry only bites a
+ * per-agent override, which isn't.
+ */
+const registeredIds = new Set();
+// Registrations currently in flight, keyed by model id — lets a second
+// caller for the SAME id that arrives before the first `await` resolves
+// join that in-progress registration instead of returning immediately with
+// nothing registered yet (which would let it dispatch before `setProvider()`
+// has actually run).
+const inflight = new Map();
+// The most recently constructed provider object, kept only so tests can
+// inspect its auth/model shape directly — this Flue version's public
+// surface (`@flue/runtime/internal`) exports `setProvider`/`hasProvider`/
+// `resolveModel` but no `getProvider`, so there is no other way to read a
+// registered provider's `auth` back out of Flue's own registry.
+let lastProvider;
+/** Exported so `doctor.ts`'s reachability probe agrees with what a real dispatch resolves to — see its call site for why a `??`/`||` mismatch here matters. */
+export function ollamaBaseUrl() {
+    const raw = (process.env.OLLAMA_BASE_URL ?? "").trim();
+    return raw || "http://localhost:11434/v1";
+}
+function modelFor(id, baseUrl) {
+    return {
+        id,
+        name: id,
+        api: "openai-completions",
+        provider: "ollama",
+        baseUrl,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        // Disables Flue's threshold-based compaction outright — there's no
+        // reliable catalog of context windows for arbitrary local Ollama models,
+        // and agent_flue.ts already treats 0 as "unknown, don't compact" for its
+        // own reported `context_window`. Verified live to be a safe no-op, not
+        // silently truncating requests.
+        contextWindow: 0,
+        maxTokens: DEFAULT_MAX_TOKENS,
+    };
+}
+/**
+ * Registers `modelId` (the part after `ollama/` in an agent's `model`
+ * config) with Flue's provider registry, alongside every other `ollama/*`
+ * id ever registered this process. Idempotent: a repeat of an already-seen
+ * id is a no-op — no re-registration, no re-import. A concurrent call for
+ * the SAME id joins the in-flight registration rather than returning early
+ * (see `inflight`'s doc); `registeredIds` itself is only ever updated AFTER
+ * `setProvider()` succeeds, so a failed attempt (a bad install, a bundler
+ * that can't resolve the deep `.lazy` subpath, a future validation error)
+ * leaves the id unregistered and eligible for a real retry — not
+ * permanently and misleadingly marked "done" while nothing is actually
+ * registered.
+ *
+ * Must complete before the FIRST Flue dispatch that names this model
+ * (agent_flue.ts's `run()` awaits this before `ensureRuntime()`/`start()`),
+ * but is equally safe to call again later with a new id mid-process — that
+ * later call's union re-registration is exactly how a second model gets
+ * added without orphaning the first (see the `registeredIds` doc above).
+ */
+export async function registerOllamaModel(modelId) {
+    if (registeredIds.has(modelId))
+        return;
+    const existing = inflight.get(modelId);
+    if (existing)
+        return existing;
+    const promise = (async () => {
+        // Deliberately dynamic, not top-level, imports — see the module doc's
+        // "LAZY IMPORT" note. `@flue/runtime/internal` is cheap either way
+        // (it's already reachable from `@flue/runtime`/`@flue/runtime/node`,
+        // which agent_flue.ts imports unconditionally); pi-ai's own package is
+        // the one this module keeps off other modules' graphs.
+        const [{ createProvider }, { openAICompletionsApi }, { setProvider }] = await Promise.all([
+            import("@earendil-works/pi-ai"),
+            import("@earendil-works/pi-ai/api/openai-completions.lazy"),
+            import("@flue/runtime/internal"),
+        ]);
+        // Built from a local candidate set, not `registeredIds` itself — the id
+        // being registered right now isn't committed to `registeredIds` until
+        // AFTER `setProvider()` below succeeds (see this function's doc).
+        const ids = new Set(registeredIds);
+        ids.add(modelId);
+        const baseUrl = ollamaBaseUrl();
+        const models = [...ids].map((id) => modelFor(id, baseUrl));
+        const options = {
+            id: "ollama",
+            name: "Ollama (local)",
+            baseUrl,
+            auth: {
+                apiKey: {
+                    name: "Ollama (keyless)",
+                    // See DUMMY_API_KEY above for why this can't just report "no key
+                    // needed" — pi-ai's dispatch path requires a truthy resolved key.
+                    resolve: async () => ({ auth: { apiKey: DUMMY_API_KEY } }),
+                },
+            },
+            models,
+            api: openAICompletionsApi(),
+        };
+        // NOT `start({ providers: [...] })` — per @flue/runtime's own node/index
+        // typings, that option REPLACES the runtime's entire default provider
+        // set (every pi-ai built-in), which would silently drop
+        // anthropic/openai/etc. for every agent, not just ollama ones.
+        // `setProvider()` is the additive (per-id) primitive; it upserts this
+        // one id and leaves every other already-registered provider untouched.
+        const provider = createProvider(options);
+        setProvider(provider);
+        lastProvider = provider;
+        // Only commit to the Set once `setProvider()` has actually run —
+        // see this function's doc for why ordering this after, not before,
+        // matters.
+        for (const id of ids)
+            registeredIds.add(id);
+    })();
+    inflight.set(modelId, promise);
+    try {
+        await promise;
+    }
+    finally {
+        inflight.delete(modelId);
+    }
+}
+/** Test-only: the most recently constructed provider object (see `lastProvider`'s doc). */
+export function providerForTest() {
+    return lastProvider;
+}
+/** Test-only: forgets accumulated ids so test files don't leak into each other. Does not touch Flue's own registry — pair with `resetModelsForTests()` from `@flue/runtime/internal`. */
+export function resetOllamaRegistrationForTest() {
+    registeredIds.clear();
+    inflight.clear();
+    lastProvider = undefined;
+}

package/dist/core/otel.d.ts

@@ -0,0 +1,352 @@
+/**
+ * OpenTelemetry span export (v1): a config-gated, lossy, fire-and-forget
+ * PROJECTION of the trace SQLite already holds. Read this header before
+ * changing anything here — every paragraph is a constraint that survived an
+ * adversarial review, not a preference.
+ *
+ * WHAT THIS IS NOT. It is not a second source of truth and it is not in any
+ * control path. `tracer.ts` (files + SQLite, synchronous) remains THE record;
+ * this module is a tail-call fan-out off its write methods. Export can never
+ * affect a phase, a gate, or a run outcome — "agent proposes, code disposes"
+ * is untouched because export cannot dispose of anything. Nothing in here may
+ * ever throw into a caller, block a caller, or be awaited by a caller other
+ * than the two shutdown paths named under LIFECYCLE below.
+ *
+ * SPANS ONLY. No `resourceMetrics`, no `resourceLogs`. The OTLP metrics data
+ * model (temporality, monotonicity, cumulative-vs-delta) is exactly where a
+ * hand-rolled encoder produces numbers a backend silently misreads, and a
+ * wrong cost number is worse than no cost number. Token counts and dollars
+ * ride as span ATTRIBUTES instead. Do not "just add metrics" here.
+ *
+ * EXPLICIT CONFIG ONLY. Activation requires `observability.otel.endpoint` in
+ * the config file. This module NEVER reads `OTEL_EXPORTER_OTLP_ENDPOINT` or
+ * any other ambient exporter variable: an unrelated shell variable inherited
+ * from a CI image or a coworker's dotfiles must not be able to turn a repo's
+ * telemetry egress on. (`SPF_CLAUDE_CMD` is not a precedent for the opposite:
+ * that variable is SPF-namespaced and only redirects a LOCAL subprocess — it
+ * moves no data off the machine.)
+ *
+ * ATTRIBUTE ALLOWLIST — exfiltration is the top risk here, because
+ * `EventRecord.payload` carries the repository's own source code (tool args,
+ * result snippets, diffs, prompts, envelope contents, the operator's request
+ * text). The allowlist, in full: phase name/kind/owner/status/seq/attempt,
+ * chain name, adw_id, agent name/model/coding_agent, gate name + passed +
+ * violation COUNT, token counts (UsageBreakdown fields) + costs, durations
+ * (implied by span start/end), and event TYPE. Everything else is excluded by
+ * construction, not by filtering:
+ *   - This module reads `EventRecord.payload` for FINITE NUMBERS ONLY (see
+ *     `numOrNull`) and only under known UsageBreakdown/cost keys. A string can
+ *     never reach an attribute through the payload path. Do not add a
+ *     `stringValue` read from `payload` — that single line is the whole
+ *     exfiltration bug.
+ *   - Agent model/coding_agent come from the typed `AgentConfig` handed to
+ *     `recordAgentSession` (config data), NOT from the `agent_start` payload.
+ *   - Tool spans are named from `record.name`'s prefix up to the first ":"
+ *     (see `toolSpanName`). The full `record.name` is a HUMAN LABEL built from
+ *     real tool arguments (`agent_flue.ts`'s `labelFor` -> "bash: cat
+ *     src/secret.ts") and must never be exported verbatim.
+ *   - `Phase.error` is NOT exported. It is an agent- and repo-derived string.
+ *     A failed phase span carries status ERROR with no message.
+ *   - `tracer.sessionRequest`, `tracer.envelopeRow`, `tracer.processStart/End`
+ *     have deliberately NO fan-out: the operator's request text, envelope
+ *     contents, and pids are all outside the allowlist. Do not add one.
+ *
+ * SPAN MODEL. One run (adw_id) = one trace. Root span = the run. Each phase =
+ * a child span of the root, using `runner.ts`'s real `started_at`/`ended_at`.
+ * Each agent call (`agent_start`..`agent_end`, with its UsageBreakdown) = a
+ * CHILD span of its phase: a phase-only tree cannot answer "which agent call
+ * burned the tokens", which is the question this feature exists for.
+ * `tool_call` events (they carry real timing) = child spans of the open agent
+ * call where attributable, else of the phase. `handoff`/`error` become a span
+ * EVENT on the phase span, with allowlisted attributes only. `gate_pass`/
+ * `gate_fail` do NOT (see `recordGate` below, which carries the structured
+ * verdict instead). `log` is dropped outright — a console line is redundant
+ * with the phase span itself and would only crowd out `handoff`/`error` in
+ * the per-phase event cap (see BACKPRESSURE and `MAX_EVENTS_PER_SPAN`). Any
+ * event type not named above is dropped, fail-closed, by `recordEvent`.
+ *
+ * IDS ARE A BESPOKE CONVENTION, documented so nobody mistakes it for the OTel
+ * SDK's random-id behavior: trace-id = first 32 hex of sha256(adw_id),
+ * span-id = first 16 hex of sha256(a stable key — `phase_id` for a phase,
+ * `agent:<phase_id>:<agent>:<n>` for an agent call, `tool:<phase_id>:<event_id>`
+ * for a tool call). Determinism means a re-export of the same run lands on the
+ * same ids instead of duplicating the trace, and a child span can name its
+ * parent's id without waiting for the parent to be emitted.
+ * `EventRecord.parent_id` is structurally ALWAYS EMPTY today (SPF's phases are
+ * flat siblings; nothing writes nesting), so there is no recorded hierarchy to
+ * mine — the parenting above is reconstructed from phase_id + agent-call
+ * bracketing, and that is the only reason it needs reconstructing at all.
+ *
+ * PHASE SPANS ARE EMITTED AT PHASE END ONLY. A hung or killed phase is
+ * therefore INVISIBLE to the backend (its buffered span events die with it),
+ * while SQLite still shows it as `running`. Deliberate v1 trade: streaming a
+ * span at phase start would require mutating an already-sent span, which OTLP
+ * has no notion of. Recorded here so it is a known gap, not a surprise.
+ *
+ * INBOUND TRACEPARENT. When a valid W3C `traceparent` is present in the
+ * environment, its trace-id becomes this run's trace-id and the run's root
+ * span is parented under its span-id, so an SPF run joins the CI trace that
+ * launched it instead of hanging as an orphan root. Reading `traceparent` is
+ * NOT ambient activation: with no `observability.otel` config, nothing is
+ * constructed and nothing is sent, traceparent or not. Garbage is rejected
+ * silently (see `parseTraceparent`) — a malformed variable must degrade to
+ * "own root", never to an error.
+ *
+ * LIFECYCLE (copied from `notify/notifier.ts`'s discipline). A module-level
+ * LIVE registry holds every exporter this process created; `flushAll()` is
+ * awaited in `src/cli/index.ts`'s existing `finally` block next to
+ * `notify.flushAll()`, AND `session.ts`'s signal handler runs a bounded,
+ * timeout-capped drain before its `process.exit(128+n)` (notify does NOT do
+ * that second one today — its in-flight webhooks are dropped on SIGTERM; only
+ * the otel path is fixed here, on purpose, to keep this change to one seam).
+ * Send failures log ONE line for the life of the exporter, with the endpoint
+ * and every header VALUE redacted, and are then swallowed.
+ *
+ * BACKPRESSURE. `tracer.event()` fires per tool call on a hot path, so raw
+ * promise-per-span fire-and-forget is a memory bug, not a style choice.
+ * Spans go into a BOUNDED queue (`MAX_QUEUED_SPANS`, drop-OLDEST) and leave in
+ * batches (`BATCH_SPANS`, or `FLUSH_INTERVAL_MS`, whichever comes first) via an
+ * UNREF'D timer that can never hold the process open. Dropped spans are
+ * counted, reported once as a warn line, and exported as a resource attribute
+ * on the final flush so the gap is visible in the backend too. The size
+ * trigger schedules a timer rather than flushing inline, which also means a
+ * synchronous burst of thousands of events exercises the bound (see the queue
+ * test) instead of interleaving sends.
+ *
+ * WIRE FORMAT is hand-rolled OTLP/HTTP with a JSON body — no new npm
+ * dependency for an optional, lossy projection. The shape that matters:
+ * `{resourceSpans:[{resource:{attributes:[KeyValue]},scopeSpans:[{scope,spans:[Span]}]}]}`,
+ * every attribute value wrapped in an AnyValue (`{stringValue}`/`{intValue}`/
+ * `{doubleValue}`/`{boolValue}`), trace/span ids as lowercase hex strings, and
+ * every uint64 nanosecond timestamp AS A STRING (a JSON number would lose
+ * precision past 2^53 and backends reject it). `src/test/otel.test.ts` pins
+ * this shape against an in-process receiver.
+ */
+import type { AgentConfig, EventRecord, GateReport, OTelConfig, Phase, SFConfig } from "./data_types.ts";
+/** trace-id = first 32 hex of sha256(adw_id). Bespoke convention — see the header. */
+export declare function traceIdFor(adwId: string): string;
+/** span-id = first 16 hex of sha256(key), where key is a phase_id or a synthetic child key. */
+export declare function spanIdFor(key: string): string;
+export interface TraceParent {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+}
+/**
+ * Strict W3C `traceparent` parse: `00-<32 hex>-<16 hex>-<2 hex>`, lowercase,
+ * exact lengths, neither id all-zero. Anything else — a wrong version, an
+ * uppercase digest, a truncated id, an empty string, unset — returns null and
+ * the run keeps its own root. Never throws, never logs: a malformed CI
+ * variable is not this module's problem to report.
+ */
+export declare function parseTraceparent(value: string | undefined | null): TraceParent | null;
+/**
+ * The two env vars CI systems actually set. Reading them is not activation —
+ * see INBOUND TRACEPARENT in the header.
+ */
+export declare function inboundTraceparent(env?: NodeJS.ProcessEnv): TraceParent | null;
+/**
+ * The configured endpoint is used AS GIVEN when it already names a path — the
+ * operator's URL is not ours to rewrite. A bare origin (`http://host:4318`,
+ * or a trailing "/") gets the standard OTLP/HTTP traces path appended, because
+ * that is the one guess with a single right answer. Returns the input
+ * unchanged if it does not parse as a URL; the config schema rejects those
+ * first, so this is only belt-and-braces for direct callers.
+ */
+export declare function resolveTracesUrl(endpoint: string): string;
+/**
+ * A printable form of the endpoint for `spf doctor`: origin + path only.
+ * Userinfo (`https://user:token@host/...`) and the query string are dropped —
+ * both are places a credential is routinely smuggled into a URL.
+ */
+export declare function endpointLabel(endpoint: string): string;
+/**
+ * ISO-8601 -> uint64 nanoseconds AS A STRING (see WIRE FORMAT). Unparseable,
+ * missing, or pre-epoch input falls back to `fallbackMs`, because a span with
+ * a nonsense timestamp is rejected wholesale by most backends while a span
+ * with an approximate one is still useful.
+ */
+export declare function nanosFromIso(iso: string | null | undefined, fallbackMs?: number): string;
+/**
+ * The safe half of a `tool_call` event's name. `record.name` for a tool call is
+ * a human label built FROM THE TOOL'S ARGUMENTS ("bash: cat src/secret.ts",
+ * "read: /etc/hosts"); only the part before the first ":" is the tool's own
+ * identity. Also clipped and character-restricted so a hand-rolled event name
+ * can't smuggle a payload through as a span name.
+ */
+export declare function toolSpanName(eventName: string | undefined | null): string;
+/**
+ * Redact every secret from a log line. The endpoint and each header VALUE are
+ * passed in; `fetch` failures routinely embed the URL they attempted, and a
+ * proxy error can echo a header. One-line rule: nothing configured under
+ * `observability.otel` ever reaches a log.
+ */
+export declare function redact(message: string, secrets: Array<string | undefined>): string;
+export interface OtelExporterInit {
+    /** The validated `observability.otel` block. Its presence IS the activation switch. */
+    cfg: OTelConfig;
+    adwId: string;
+    /** The CLI chain name, from `session.ts` — allowlisted, config-declared. */
+    chainName: string;
+    /** Injectable for tests; defaults to stderr, exactly like `Notifier`'s. */
+    log?: (message: string) => void;
+    /** Injectable for tests; defaults to `process.env`. Only ever read for `traceparent`. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class OtelExporter {
+    private readonly cfg;
+    private readonly adwId;
+    private readonly chainName;
+    private readonly serviceName;
+    private readonly url;
+    private readonly log;
+    private readonly traceId;
+    /** "" unless an inbound traceparent parented this run — see INBOUND TRACEPARENT. */
+    private readonly rootParentSpanId;
+    private readonly rootSpanId;
+    private queue;
+    private dropped;
+    private droppedEvents;
+    private warnedDrops;
+    private loggedFailure;
+    private timer;
+    private timerDelay;
+    private pending;
+    /** Span events buffered until their phase span exists. Key "" = the root run span. */
+    private bufferedEvents;
+    /**
+     * Phases whose span has already gone out. Events DO arrive after a phase
+     * span is emitted — `run.finish()`'s `not_accepted` error names the last
+     * phase — and a span already on the wire cannot grow an event, so those are
+     * re-homed onto the root run span instead of accumulating in a buffer that
+     * nothing will ever drain.
+     */
+    private emittedPhases;
+    /** `<phase_id><agent>` -> the open agent call, for closing it and parenting tool spans. */
+    private openAgents;
+    /** How many times an agent has been called in a phase, so a retry gets its own span id. */
+    private agentCalls;
+    /** agent name -> config metadata, from `recordAgentSession` (typed config, never a payload). */
+    private agentMeta;
+    private runStartedAtMs;
+    private rootEmitted;
+    constructor(init: OtelExporterInit);
+    /** `tracer.sessionStart` — only the run's clock; the engineer name is not allowlisted. */
+    recordSessionStart(startedAtIso?: string | null): void;
+    /**
+     * `tracer.event` — the one hot seam. Dispatch, in full:
+     *   phase_start/phase_end -> ignored (the phase span's own boundaries say it)
+     *   agent_start           -> open an agent call
+     *   agent_end             -> emit the agent-call child span, with usage
+     *   tool_call             -> emit a tool child span (real timing, safe name)
+     *   gate_pass/gate_fail   -> ignored HERE; `recordGate` carries the structured
+     *                            GateReport for the same gate, and doubling it
+     *                            would put two span events on every gate
+     *   handoff/error         -> a span event buffered onto the phase span
+     *   log                   -> dropped: a console line adds nothing beyond
+     *                            `spf.event.type`/`name`, and buffering it would
+     *                            crowd `handoff`/`error` out of the per-phase cap
+     *                            (see MAX_EVENTS_PER_SPAN)
+     *   anything else          -> dropped. The dispatch is fail-closed on purpose:
+     *                            a future EventRecord.type whose `name` is
+     *                            derived from agent output must not fall through
+     *                            to export by default.
+     */
+    recordEvent(record: EventRecord, eventId: string, tsIso: string): void;
+    /**
+     * `tracer.phaseUpsert` — the phase's END is the emit point (see PHASE SPANS
+     * ARE EMITTED AT PHASE END ONLY). The start-of-phase upsert has no
+     * `ended_at` and is skipped, which also makes this idempotent-ish: a
+     * re-upsert of the same finished phase re-emits a span with the SAME id, so
+     * a backend overwrites rather than duplicates.
+     */
+    recordPhase(phase: Phase): void;
+    /**
+     * `tracer.gateRow` — the verdict and its SIZE, never its content. A
+     * violation string quotes the agent's own claim and the repo's files; only
+     * the count crosses the wire.
+     */
+    recordGate(phase: Phase, gate: string, report: GateReport, attempt: number): void;
+    /**
+     * `tracer.agentSessionRow` — the typed source for an agent's model and
+     * backend. Load-bearing, not decoration: it is written BEFORE the
+     * `agent_end` event (see `agents.ts`), which is what lets the agent-call
+     * span carry model/coding_agent without ever reading the `agent_start`
+     * payload. `session_id` is NOT exported (it is a coding-agent handle, not a
+     * measure).
+     */
+    recordAgentSession(agent: AgentConfig): void;
+    /**
+     * `tracer.sessionFinish` — emits the root run span exactly once. Called
+     * twice on some paths (a failing phase finalizes, then `finish()` does), and
+     * the guard is why that is harmless.
+     */
+    recordSessionFinish(ok: boolean): void;
+    /** Queued spans and spans/events dropped so far. For tests and diagnostics. */
+    stats(): {
+        queued: number;
+        dropped: number;
+        droppedEvents: number;
+    };
+    /**
+     * The exact JSON body the next flush would POST, without sending or
+     * draining. This is the seam `src/test/otel.test.ts` uses to prove the
+     * allowlist holds — the assertion is on the literal bytes, so any future
+     * attribute that leaks a payload fails a test rather than a review.
+     */
+    pendingJson(): string;
+    private enqueue;
+    private schedule;
+    private track;
+    /**
+     * Send whatever is queued. Never throws, never rejects: a failed export is a
+     * single redacted log line and a swallowed error, because the alternative is
+     * an observability feature that can fail a run.
+     */
+    flush(isFinal?: boolean): Promise<void>;
+    /**
+     * Drain: flush, then await anything already in flight, all under one hard
+     * budget. Never throws. Called from the CLI's `finally` and from
+     * `session.ts`'s signal handler (with a tighter budget there).
+     */
+    drain(budgetMs?: number): Promise<void>;
+    private emitRootSpan;
+    private agentKey;
+    private openAgentCall;
+    private closeAgentCall;
+    /**
+     * Tool spans carry REAL elapsed time (the tracker records started_at/ended_at
+     * per call), which is the whole reason they are spans and not span events.
+     * Parented under the open agent call when one is attributable — the agent
+     * name comes from `payload.agent`, and it is used ONLY as a map lookup key,
+     * never written to an attribute, so an unexpected value yields "no parent
+     * found" rather than an exported string.
+     */
+    private emitToolSpan;
+    private bufferSpanEvent;
+    private takeBufferedEvents;
+    private payloadFor;
+    private logFailureOnce;
+}
+/**
+ * Build an exporter from `cfg.observability.otel`, or `null` when it is
+ * absent — the same optional-dependency shape as `resolveNotifier`, so every
+ * call site is `otel?.record...()` and never a conditional branch. `null` is
+ * the default for every repo that has not configured an endpoint, and no
+ * environment variable can change that (see EXPLICIT CONFIG ONLY).
+ */
+export declare function resolveOtelExporter(cfg: SFConfig, opts: {
+    adwId: string;
+    chainName: string;
+    log?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+}): OtelExporter | null;
+/**
+ * Drain every exporter this process created, under one budget. A no-op when
+ * otel is unconfigured. Called from `src/cli/index.ts`'s `finally` (next to
+ * `notify.flushAll()`) and, with a tighter budget, from `session.ts`'s signal
+ * handler. Never throws.
+ */
+export declare function flushAll(budgetMs?: number): Promise<void>;
+/** Tests only: forget every registered exporter so cases cannot leak into each other. */
+export declare function resetLiveForTest(): void;