@gr8ful/spf 0.17.0 → 0.18.0

package/dist/core/otel_metrics.d.ts

@@ -0,0 +1,127 @@
+/**
+ * OpenTelemetry metrics export — a PROCESS-scoped sibling to `otel.ts`'s
+ * per-run span exporter, built on the real `@opentelemetry/sdk-metrics` +
+ * `@opentelemetry/exporter-metrics-otlp-http` (v1's header explained why
+ * metrics were deliberately cut from the hand-rolled encoder: "the OTLP
+ * metrics data model — temporality, monotonicity, cumulative-vs-delta — is
+ * exactly where a hand-rolled encoder produces numbers a backend silently
+ * misreads". That risk is why this module exists only now that a REAL SDK
+ * owns the encoding, never before).
+ *
+ * PROCESS-scoped, not per-run — the one significant lifecycle difference from
+ * `otel.ts`. `spf watch`'s daemon loop runs many sessions in one process, one
+ * per claimed issue; a MeterProvider created per-run would repeat the same
+ * unbounded-growth mistake `otel.ts`'s RUN-SCOPED CLEANUP note (#26) already
+ * fixed once for spans. There is exactly one `MeterProvider` for the life of
+ * the `spf` process, created lazily on first use and torn down once, from
+ * `src/cli/index.ts`'s existing `finally` block, alongside `otel.flushAll()`.
+ *
+ * SAME ACTIVATION GATE AS TRACES: `observability.otel.endpoint` must be set —
+ * no ambient `OTEL_EXPORTER_OTLP_*` env var can turn this on (see `otel.ts`'s
+ * EXPLICIT CONFIG ONLY). `observability.otel.metrics: false` additionally
+ * opts OUT of metrics while leaving trace export on; there is no way to have
+ * metrics without traces, since the gate is the trace endpoint's presence.
+ *
+ * NEVER THROWS. Every public method here follows the same discipline
+ * `otel.ts` documents at its own top: a metrics failure must never surface as
+ * a caller's exception, so every instrument call is wrapped and any error is
+ * logged at most once and then swallowed.
+ *
+ * INSTRUMENTS:
+ *   spf.tokens        (Counter, unit "token")  attrs: kind (input|output|
+ *                      cache_read|cache_write), agent, model
+ *   spf.cost_usd      (Counter, unit "USD")    attrs: agent, model
+ *   spf.phase.duration(Histogram, unit "s")    attrs: kind, owner, status
+ *   spf.gate.result   (Counter)                attrs: gate, result (pass|fail)
+ *   spf.agent.calls   (Counter)                attrs: agent, model, coding_agent
+ *   spf.otel.dropped_spans / spf.otel.dropped_span_events (Counter) — the
+ *   v1 "stamp it on the final flush's resource attribute" hack has no home in
+ *   the real SDK (a `Resource` is immutable per exporter instance); these
+ *   replace it, recorded once per exporter's lifetime, same as the warn log.
+ *
+ * WIRE TRANSPORT mirrors `otel.ts`'s trace exporter: JSON-encoded OTLP/HTTP
+ * (`OTLPMetricExporter`'s default), `keepAlive: false` so a lingering
+ * keep-alive socket can never be the reason `spf` fails to exit, aimed at
+ * `resolveMetricsUrl(otel.endpoint)` — the same collector host, `/v1/metrics`
+ * instead of `/v1/traces` (or the given path verbatim, for a collector
+ * fronted by a router that doesn't use the standard suffixes at all).
+ */
+import { type PushMetricExporter } from "@opentelemetry/sdk-metrics";
+import { type SFConfig } from "./data_types.ts";
+/**
+ * A bare origin gets `/v1/metrics` appended; an endpoint that already ends in
+ * `/v1/traces` (the documented shape for `observability.otel.endpoint`) has
+ * that suffix swapped for `/v1/metrics` — same collector host, the metrics
+ * signal's own path. Anything else (a router/proxy path that doesn't use the
+ * standard suffixes) is left exactly as given, matching `otel.ts`'s
+ * `resolveTracesUrl`'s "the operator's URL is not ours to rewrite" rule.
+ */
+export declare function resolveMetricsUrl(endpoint: string): string;
+export interface OtelMetricsInit {
+    endpoint: string;
+    headers?: Record<string, string>;
+    serviceName: string;
+    /** Injectable for tests; defaults to stderr. */
+    log?: (message: string) => void;
+    /** Injectable for tests — swap in an `InMemoryMetricExporter`/a short interval without touching the network. */
+    exporter?: PushMetricExporter;
+    exportIntervalMillis?: number;
+}
+export declare class OtelMetrics {
+    private readonly provider;
+    private readonly log;
+    private loggedFailure;
+    private readonly tokens;
+    private readonly cost;
+    private readonly phaseDuration;
+    private readonly gateResult;
+    private readonly agentCalls;
+    private readonly droppedSpans;
+    private readonly droppedSpanEvents;
+    constructor(init: OtelMetricsInit);
+    recordTokens(kind: "input" | "output" | "cache_read" | "cache_write", value: number, attrs: {
+        agent: string;
+        model: string;
+    }): void;
+    recordCost(value: number, attrs: {
+        agent: string;
+        model: string;
+    }): void;
+    recordPhaseDuration(seconds: number, attrs: {
+        kind: string;
+        owner: string;
+        status: string;
+    }): void;
+    recordGateResult(gate: string, passed: boolean): void;
+    recordAgentCall(attrs: {
+        agent: string;
+        model: string;
+        codingAgent: string;
+    }): void;
+    recordDroppedSpans(n: number): void;
+    recordDroppedSpanEvents(n: number): void;
+    /** Force an out-of-band export. Tests use this instead of waiting on `exportIntervalMillis`. Never throws. */
+    forceFlush(): Promise<void>;
+    /** Never throws. */
+    shutdown(budgetMs?: number): Promise<void>;
+    private guard;
+    private logFailureOnce;
+}
+/**
+ * Resolve (once per process) the shared metrics handle from
+ * `cfg.observability.otel`, or `null` when metrics are off — absent
+ * `endpoint` (same gate as traces) or `metrics: false`. Every call after the
+ * first, for the life of the process, returns the SAME instance regardless
+ * of what `cfg` says (this is the "exactly once, never per-issue" contract
+ * `spf watch`'s daemon loop needs — see the module header) — call
+ * `resetOtelMetricsForTest()` between test cases that need a fresh one.
+ */
+export declare function resolveOtelMetrics(cfg: SFConfig, log?: (message: string) => void): OtelMetrics | null;
+/**
+ * Shut down the shared MeterProvider, if one was ever created. A no-op when
+ * metrics were never configured. Called once, from `src/cli/index.ts`'s
+ * `finally`, alongside `otel.flushAll()`. Never throws.
+ */
+export declare function shutdownOtelMetrics(budgetMs?: number): Promise<void>;
+/** Tests only: forget the shared instance so cases cannot leak into each other. */
+export declare function resetOtelMetricsForTest(): void;

package/dist/core/otel_metrics.js

@@ -0,0 +1,221 @@
+/**
+ * OpenTelemetry metrics export — a PROCESS-scoped sibling to `otel.ts`'s
+ * per-run span exporter, built on the real `@opentelemetry/sdk-metrics` +
+ * `@opentelemetry/exporter-metrics-otlp-http` (v1's header explained why
+ * metrics were deliberately cut from the hand-rolled encoder: "the OTLP
+ * metrics data model — temporality, monotonicity, cumulative-vs-delta — is
+ * exactly where a hand-rolled encoder produces numbers a backend silently
+ * misreads". That risk is why this module exists only now that a REAL SDK
+ * owns the encoding, never before).
+ *
+ * PROCESS-scoped, not per-run — the one significant lifecycle difference from
+ * `otel.ts`. `spf watch`'s daemon loop runs many sessions in one process, one
+ * per claimed issue; a MeterProvider created per-run would repeat the same
+ * unbounded-growth mistake `otel.ts`'s RUN-SCOPED CLEANUP note (#26) already
+ * fixed once for spans. There is exactly one `MeterProvider` for the life of
+ * the `spf` process, created lazily on first use and torn down once, from
+ * `src/cli/index.ts`'s existing `finally` block, alongside `otel.flushAll()`.
+ *
+ * SAME ACTIVATION GATE AS TRACES: `observability.otel.endpoint` must be set —
+ * no ambient `OTEL_EXPORTER_OTLP_*` env var can turn this on (see `otel.ts`'s
+ * EXPLICIT CONFIG ONLY). `observability.otel.metrics: false` additionally
+ * opts OUT of metrics while leaving trace export on; there is no way to have
+ * metrics without traces, since the gate is the trace endpoint's presence.
+ *
+ * NEVER THROWS. Every public method here follows the same discipline
+ * `otel.ts` documents at its own top: a metrics failure must never surface as
+ * a caller's exception, so every instrument call is wrapped and any error is
+ * logged at most once and then swallowed.
+ *
+ * INSTRUMENTS:
+ *   spf.tokens        (Counter, unit "token")  attrs: kind (input|output|
+ *                      cache_read|cache_write), agent, model
+ *   spf.cost_usd      (Counter, unit "USD")    attrs: agent, model
+ *   spf.phase.duration(Histogram, unit "s")    attrs: kind, owner, status
+ *   spf.gate.result   (Counter)                attrs: gate, result (pass|fail)
+ *   spf.agent.calls   (Counter)                attrs: agent, model, coding_agent
+ *   spf.otel.dropped_spans / spf.otel.dropped_span_events (Counter) — the
+ *   v1 "stamp it on the final flush's resource attribute" hack has no home in
+ *   the real SDK (a `Resource` is immutable per exporter instance); these
+ *   replace it, recorded once per exporter's lifetime, same as the warn log.
+ *
+ * WIRE TRANSPORT mirrors `otel.ts`'s trace exporter: JSON-encoded OTLP/HTTP
+ * (`OTLPMetricExporter`'s default), `keepAlive: false` so a lingering
+ * keep-alive socket can never be the reason `spf` fails to exit, aimed at
+ * `resolveMetricsUrl(otel.endpoint)` — the same collector host, `/v1/metrics`
+ * instead of `/v1/traces` (or the given path verbatim, for a collector
+ * fronted by a router that doesn't use the standard suffixes at all).
+ */
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { applyOtelEnvSupplement } from "./data_types.js";
+/** Never emits on its own — `forceFlush()`/tests drive collection explicitly, so a process never waits `exportIntervalMillis` for its final data to go out. */
+const EXPORT_INTERVAL_MS = 60_000;
+const EXPORT_TIMEOUT_MS = 2_000;
+/**
+ * A bare origin gets `/v1/metrics` appended; an endpoint that already ends in
+ * `/v1/traces` (the documented shape for `observability.otel.endpoint`) has
+ * that suffix swapped for `/v1/metrics` — same collector host, the metrics
+ * signal's own path. Anything else (a router/proxy path that doesn't use the
+ * standard suffixes) is left exactly as given, matching `otel.ts`'s
+ * `resolveTracesUrl`'s "the operator's URL is not ours to rewrite" rule.
+ */
+export function resolveMetricsUrl(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        return endpoint;
+    }
+    if (url.pathname === "" || url.pathname === "/") {
+        url.pathname = "/v1/metrics";
+        return url.toString();
+    }
+    if (url.pathname.endsWith("/v1/traces")) {
+        url.pathname = url.pathname.slice(0, -"/v1/traces".length) + "/v1/metrics";
+        return url.toString();
+    }
+    return url.toString();
+}
+export class OtelMetrics {
+    provider;
+    log;
+    loggedFailure = false;
+    tokens;
+    cost;
+    phaseDuration;
+    gateResult;
+    agentCalls;
+    droppedSpans;
+    droppedSpanEvents;
+    constructor(init) {
+        this.log = init.log ?? ((m) => console.error(m));
+        const exporter = init.exporter ??
+            new OTLPMetricExporter({
+                url: resolveMetricsUrl(init.endpoint),
+                headers: init.headers,
+                timeoutMillis: EXPORT_TIMEOUT_MS,
+                keepAlive: false,
+            });
+        const reader = new PeriodicExportingMetricReader({
+            exporter,
+            exportIntervalMillis: init.exportIntervalMillis ?? EXPORT_INTERVAL_MS,
+            exportTimeoutMillis: EXPORT_TIMEOUT_MS,
+        });
+        this.provider = new MeterProvider({
+            resource: resourceFromAttributes({ "service.name": init.serviceName }),
+            readers: [reader],
+        });
+        const meter = this.provider.getMeter("spf", "1");
+        this.tokens = meter.createCounter("spf.tokens", { unit: "token", description: "Tokens spent per agent call, by kind" });
+        this.cost = meter.createCounter("spf.cost_usd", { unit: "USD", description: "Dollar cost spent per agent call" });
+        this.phaseDuration = meter.createHistogram("spf.phase.duration", { unit: "s", description: "Phase wall-clock duration" });
+        this.gateResult = meter.createCounter("spf.gate.result", { description: "Gate verdicts, pass or fail" });
+        this.agentCalls = meter.createCounter("spf.agent.calls", { description: "Agent calls completed" });
+        this.droppedSpans = meter.createCounter("spf.otel.dropped_spans", { description: "Spans dropped by the bounded queue (see otel.ts)" });
+        this.droppedSpanEvents = meter.createCounter("spf.otel.dropped_span_events", { description: "Span events dropped by the per-phase cap" });
+    }
+    recordTokens(kind, value, attrs) {
+        this.guard(() => this.tokens.add(value, { kind, agent: attrs.agent, model: attrs.model }));
+    }
+    recordCost(value, attrs) {
+        this.guard(() => this.cost.add(value, { agent: attrs.agent, model: attrs.model }));
+    }
+    recordPhaseDuration(seconds, attrs) {
+        this.guard(() => this.phaseDuration.record(seconds, { kind: attrs.kind, owner: attrs.owner, status: attrs.status }));
+    }
+    recordGateResult(gate, passed) {
+        this.guard(() => this.gateResult.add(1, { gate, result: passed ? "pass" : "fail" }));
+    }
+    recordAgentCall(attrs) {
+        this.guard(() => this.agentCalls.add(1, { agent: attrs.agent, model: attrs.model, coding_agent: attrs.codingAgent }));
+    }
+    recordDroppedSpans(n) {
+        this.guard(() => this.droppedSpans.add(n));
+    }
+    recordDroppedSpanEvents(n) {
+        this.guard(() => this.droppedSpanEvents.add(n));
+    }
+    /** Force an out-of-band export. Tests use this instead of waiting on `exportIntervalMillis`. Never throws. */
+    async forceFlush() {
+        try {
+            await this.provider.forceFlush();
+        }
+        catch (error) {
+            this.logFailureOnce(error);
+        }
+    }
+    /** Never throws. */
+    async shutdown(budgetMs = EXPORT_TIMEOUT_MS) {
+        let deadline = null;
+        const budget = new Promise((resolve) => {
+            deadline = setTimeout(resolve, budgetMs);
+            deadline.unref?.();
+        });
+        try {
+            await Promise.race([this.provider.shutdown(), budget]);
+        }
+        catch (error) {
+            this.logFailureOnce(error);
+        }
+        finally {
+            if (deadline)
+                clearTimeout(deadline);
+        }
+    }
+    guard(fn) {
+        try {
+            fn();
+        }
+        catch (error) {
+            this.logFailureOnce(error);
+        }
+    }
+    logFailureOnce(error) {
+        if (this.loggedFailure)
+            return;
+        this.loggedFailure = true;
+        const message = error instanceof Error ? error.message : String(error);
+        this.log(`spf: otel metrics failed (${message}) — metrics for this process are incomplete; runs are unaffected`);
+    }
+}
+// ── module-level lifecycle: ONE MeterProvider for the life of the process ──
+let SHARED; // undefined = not yet resolved; null = resolved-and-off
+/**
+ * Resolve (once per process) the shared metrics handle from
+ * `cfg.observability.otel`, or `null` when metrics are off — absent
+ * `endpoint` (same gate as traces) or `metrics: false`. Every call after the
+ * first, for the life of the process, returns the SAME instance regardless
+ * of what `cfg` says (this is the "exactly once, never per-issue" contract
+ * `spf watch`'s daemon loop needs — see the module header) — call
+ * `resetOtelMetricsForTest()` between test cases that need a fresh one.
+ */
+export function resolveOtelMetrics(cfg, log) {
+    if (SHARED !== undefined)
+        return SHARED;
+    const rawOtel = cfg.observability.otel;
+    if (!rawOtel || !rawOtel.endpoint || rawOtel.metrics === false) {
+        SHARED = null;
+        return null;
+    }
+    const otel = applyOtelEnvSupplement(rawOtel);
+    SHARED = new OtelMetrics({ endpoint: otel.endpoint, headers: otel.headers, serviceName: otel.service_name || "spf", log });
+    return SHARED;
+}
+/**
+ * Shut down the shared MeterProvider, if one was ever created. A no-op when
+ * metrics were never configured. Called once, from `src/cli/index.ts`'s
+ * `finally`, alongside `otel.flushAll()`. Never throws.
+ */
+export async function shutdownOtelMetrics(budgetMs) {
+    const shared = SHARED;
+    SHARED = undefined;
+    if (shared)
+        await shared.shutdown(budgetMs);
+}
+/** Tests only: forget the shared instance so cases cannot leak into each other. */
+export function resetOtelMetricsForTest() {
+    SHARED = undefined;
+}

package/dist/core/otel_propagation.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Outbound trace-context propagation for `coding_agent: flue` — the
+ * "best-effort" half of the two propagation paths this repo's OTel spike
+ * documented (`claude_code` gets `agent_cc.ts`'s single `spawn()` choke
+ * point instead; see that module).
+ *
+ * `@flue/opentelemetry`'s own docs (fetched at
+ * https://flueframework.com/docs/ecosystem/tooling/opentelemetry/, cited in
+ * this repo's phase0 spike) are explicit that `dispatch()` "does not
+ * propagate trace context currently" and that "custom header propagation to
+ * model providers is not documented" — so the literal ask ("propagate via
+ * @flue/opentelemetry") is not fully satisfiable by that package alone. What
+ * IS real and verifiable: `@opentelemetry/instrumentation-http` and
+ * `-undici` create a real client span (with a real, non-noop SpanContext)
+ * around every outbound `http`/`https`/`fetch`(undici) call made from this
+ * process, and the OTel API's global propagator is what those
+ * instrumentations use to inject `traceparent` (and, here, `x-request-id`)
+ * into that call's headers — REGARDLESS of which provider SDK issued it.
+ * This reaches every provider whose Node SDK issues requests through
+ * Node's own `http`/`https` modules or `undici` (verified: `fetch()`,
+ * `https.request()`). It does NOT reach a provider transport that bypasses
+ * both (unverified in this repo for the Anthropic/Google/Mistral SDKs'
+ * internal transports specifically — flagged, not assumed, per the spike).
+ *
+ * WHY A REAL GLOBAL TracerProvider IS REQUIRED, NOT OPTIONAL: the
+ * W3CTraceContextPropagator's `inject()` silently skips writing a
+ * `traceparent` header when the active SpanContext is INVALID
+ * (`isSpanContextValid()` false) — which is exactly what every span is when
+ * no global TracerProvider has ever been registered (the API's default is a
+ * no-op tracer). So this module registers a real (if minimal)
+ * `BasicTracerProvider` — with its own `BatchSpanProcessor` ->
+ * `OTLPTraceExporter` aimed at the SAME collector `observability.otel.
+ * endpoint` names — alongside the propagator and the two instrumentations.
+ * This also happens to be exactly what `@flue/opentelemetry`'s own docs ask
+ * for ("Configure the SDK first, then register one instrumentation
+ * instance") — Flue's own spans (`invoke_agent`, `chat <model>`,
+ * `execute_tool`) now have somewhere real to go, which they did not before.
+ *
+ * FLUE SPANS JOIN SPF's DETERMINISTIC TRACE (v3; issue #80). The naive
+ * approach — extracting SPF's agent-call traceparent into the active
+ * context around `dispatch()` — was tried and REJECTED by design review:
+ * flue's node runtime executes submissions in ONE process-lifetime claim
+ * loop (`builtin-providers ... claimLoop()`, started by the first
+ * dispatch's `finally`), whose async context is captured once at loop
+ * creation. A dispatch-time context wrap therefore joins only the FIRST
+ * flue agent in a process and silently MIS-ATTRIBUTES every later agent's
+ * spans into the first agent's trace — worse than a separate trace.
+ *
+ * The mechanism below instead uses the instrumentation's own
+ * `resolveRootContext(event, ctx)` option (typed in
+ * `@flue/opentelemetry`'s public d.mts; verified in its dist: consulted
+ * per span exactly when a span has neither an explicit parent nor an
+ * active-context SpanContext — i.e. per span, per submission, no matter
+ * what context the claim loop was captured in). SPF keeps a small
+ * instance-id -> traceparent map (`registerFlueSessionTrace`, populated by
+ * `agent_flue.ts`'s `run()` around each agent call), and the resolver
+ * matches on `ctx.id` — flue's documented "stable agent instance id during
+ * agent processing", which is the id SPF mints and hands to
+ * `init(SfAgent, { id })`. Extraction goes through the globally
+ * registered propagator against ROOT_CONTEXT, so no leaked loop context
+ * can stick. Consequences, all intended:
+ *   - Flue's spans inherit SPF's sha256 trace id, parented under the
+ *     right agent-call span PER SESSION — correct under multiple agents
+ *     per process, concurrent agents, and claim-loop restarts alike. Span
+ *     ids are SDK-random; only the trace id is shared.
+ *   - The http/undici client spans' injected `traceparent` carries the
+ *     deterministic id too, so Switchyard/vLLM hops land as descendants of
+ *     SPF's trace — parity with `claude_code`'s `ANTHROPIC_CUSTOM_HEADERS`
+ *     path. `x-request-id` stays the this-span id for request-keyed
+ *     correlation, unchanged.
+ *   - Unmapped sessions (never registered, restarted process with a
+ *     durable backlog, post-`unregister` straggler bookkeeping spans)
+ *     resolve to an unparented root — flue's spans root a separate SDK
+ *     trace exactly as v1 did, correlatable by `x-request-id`/`spf.adw_id`/
+ *     time window. Degraded join, never an error and never MIS-attributed.
+ *   - flue's internal `executionContext.traceCarrier` (typed but not on
+ *     the public `AgentDispatchRequest` surface) stays unused — noted here
+ *     as flue's own escape hatch, not something SPF reaches into.
+ *
+ * REGISTRATION TIMING. `installFluePropagation()` is called from
+ * `agent_flue.ts`'s `run()`, before `ensureRuntime()`/dispatch — i.e. before
+ * the actual outbound call, which is the only ordering that matters for
+ * `instrumentation-undici` (subscribes to `undici`'s own `diagnostics_channel`
+ * events; any registration before the request fires is picked up regardless
+ * of when `undici`/`fetch` was first imported) and, in practice, for
+ * `instrumentation-http` too (Node's `http`/`https` modules are shared,
+ * monkey-patchable singletons; a later `require("http")` elsewhere in the
+ * process still resolves to the SAME, already-patched module object). This
+ * is a real, load-bearing difference from a truly cold, "before ANY other
+ * import" registration (which would require moving this into `cli/bin.ts`,
+ * ahead of that file's own deliberately-static-import-free module graph) —
+ * documented as the honest scope of what's verified, not claimed as more.
+ *
+ * NO-OP WHEN UNCONFIGURED. Gated on the exact same `observability.otel.
+ * endpoint` presence check as `otel.ts` and `otel_metrics.ts` — no ambient
+ * `OTEL_*` env var activates any of this on its own. Idempotent: registers
+ * exactly once per process, on whichever call (across however many `flue`
+ * agent dispatches this process makes) happens to arrive first.
+ */
+import { type Context, type TextMapPropagator, type TextMapSetter } from "@opentelemetry/api";
+/** The one custom propagation field this repo adds beyond the standard W3C `traceparent`: the current span's own id, for a collector/log pipeline that correlates by request rather than by trace. */
+export declare const X_REQUEST_ID_HEADER = "x-request-id";
+/**
+ * Injects `x-request-id` from whatever span is active at the point of the
+ * outbound call — the same id that would appear as that span's `spanId` on
+ * the (separate — see the module header) Flue-side trace. One-directional:
+ * `extract()` is a pass-through, since nothing on the INBOUND side of an
+ * outbound provider call needs to read this back.
+ */
+export declare class XRequestIdPropagator implements TextMapPropagator {
+    inject(ctx: Context, carrier: unknown, setter: TextMapSetter): void;
+    extract(ctx: Context): Context;
+    fields(): string[];
+}
+/**
+ * Registers `traceparent` (SPF's deterministic agent-call span, as a W3C
+ * carrier string) as the trace root for flue spans belonging to `sessionId`
+ * — flue's instance id, minted by SPF and handed to `init(SfAgent, { id })`.
+ * Overwrites a prior registration for the same id (a same-phase retry is
+ * the same logical call; the current call wins).
+ */
+export declare function registerFlueSessionTrace(sessionId: string, traceparent: string): void;
+/**
+ * Idempotent — called from `run()`'s `finally`. Post-settlement bookkeeping
+ * spans flue mints after this point simply resolve to an unparented root
+ * (separate trace), which is preferable to leaking a registration whose id
+ * a REUSED session id could collide with on a later phase.
+ */
+export declare function unregisterFlueSessionTrace(sessionId: string): void;
+/**
+ * The `resolveRootContext` implementation handed to
+ * `createOpenTelemetryInstrumentation` — consulted per root-span creation
+ * (see the module header). Matches on `ctx.id` (flue's documented stable
+ * agent instance id during processing) and returns SPF's agent-call span
+ * as an extracted REMOTE parent, pulled from ROOT_CONTEXT so no ambient
+ * claim-loop context can leak in. Returns `undefined` (flue mints an
+ * unparented root span of its own) for an unmapped session id, a malformed
+ * traceparent, an absent ctx — and, with no global propagator installed,
+ * for everything. Exported for tests.
+ */
+export declare function resolveFlueRootContext(_event: unknown, ctx: {
+    id?: string;
+} | undefined): Context | undefined;
+export interface FluePropagationConfig {
+    endpoint: string;
+    headers?: Record<string, string>;
+    service_name: string;
+}
+/**
+ * Idempotent: the first call in this process wins; every later call
+ * (another `flue` agent dispatch, possibly with a different `cfg`) is a
+ * silent no-op, matching the "process-scoped, created exactly once" rule
+ * `otel_metrics.ts` documents for the same reason (`spf watch`'s daemon
+ * loop). Never throws — a failure to install best-effort propagation must
+ * never fail an agent dispatch.
+ */
+export declare function installFluePropagation(cfg: FluePropagationConfig | undefined | null, log?: (message: string) => void): void;
+/** Tests only: forget global installation state. Does NOT undo `setGlobalTracerProvider`/`registerInstrumentations` (the OTel API has no supported "un-register" — tests that need isolation run in a fresh process). */
+export declare function resetFluePropagationForTest(): void;