@gr8ful/spf 0.19.0 → 0.19.1

package/dist/core/ollama_provider.js

@@ -41,6 +41,9 @@
  * `type` imports below are erased at compile time (verbatimModuleSyntax) and
  * cost nothing at runtime either way.
  */
+import { context as contextApi, isSpanContextValid, trace as traceApi } from "@opentelemetry/api";
+import { isFluePropagationInstalled, X_CORRELATION_ID_HEADER, X_SPF_AGENT_HEADER } from "./otel_propagation.js";
+import { newId } from "./utils.js";
 // 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
@@ -51,6 +54,65 @@
 // 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";
+/**
+ * `OLLAMA_API_KEY`, trimmed, when the operator has set one — e.g. the
+ * Briefs gateway (Envoy AI Gateway) enforces a per-client bearer and 401s
+ * the dummy key `DUMMY_API_KEY` was designed for a bare local server that
+ * checks nothing. Falls back to the dummy exactly as before when unset, so
+ * THIS function's own return value — the resolved `Authorization` bearer —
+ * is byte-identical to pre-gateway behavior for a bare local Ollama server
+ * (the common case this module was built for). MINOR-H: that is narrower
+ * than "the whole request is unchanged" — it is not, even with
+ * `OLLAMA_API_KEY` unset: a `traceparent` (and, once `agent_flue.ts` has an
+ * adw_id/agent_name to give it, `x-correlation-id`/`x-spf-agent`) is ALWAYS
+ * sent now, gateway or no gateway (see the "Gateway headers" section below).
+ * A bare local Ollama server ignores headers it doesn't recognize, so this
+ * is harmless — just not byte-identical. Read fresh inside `resolve()` (see
+ * its call site below) — never cached — so a key exported mid-process (or
+ * changed) takes effect on the very next dispatch with no re-registration.
+ *
+ * MINOR 3: exported so `doctor.ts`'s `OLLAMA_BASE_URL reachability` probe
+ * calls this SAME function rather than reading `process.env.OLLAMA_API_KEY`
+ * raw — a prior version of that probe sent NO `Authorization` header at all
+ * when the env var was unset, which diverges from what a real dispatch
+ * sends (the dummy bearer below, always). Against a gateway that rejects a
+ * request with no `Authorization` header at all differently than one with a
+ * wrong/dummy bearer, that divergence could make doctor report reachable
+ * when a real dispatch would 401, or vice versa. Calling `ollamaApiKey()` in
+ * both places means doctor's probe and a real dispatch send byte-identical
+ * bearers for the same env state.
+ */
+export function ollamaApiKey() {
+    const key = (process.env.OLLAMA_API_KEY ?? "").trim();
+    return key || DUMMY_API_KEY;
+}
+/** Must NEVER be sent — Envoy/Switchyard own it end-to-end; a client-supplied value breaks their sampling. Exported only so tests can assert its absence by name, not a literal string. The sole surviving export of this name in the codebase — see MINOR-G in this change's review; `otel_propagation.ts` no longer has one now that `XRequestIdPropagator` is gone (BLOCKER B). */
+export const X_REQUEST_ID_HEADER = "x-request-id";
+/**
+ * A fresh W3C `traceparent` for one outbound call — used only on the NOT
+ * INSTALLED path (see the section above); when propagation IS installed,
+ * `resolve()` does not call this at all, relying entirely on the
+ * instrumentation's own per-request injection instead (this is what fixed
+ * BLOCKER A/MAJOR-C: this function used to be called unconditionally, and
+ * on the installed path it silently reused the one still-open span's
+ * traceparent for every call inside that span, which is both a duplicate
+ * header AND not actually fresh per call).
+ *
+ * Reuses the active OTel span context when one is installed and current —
+ * the same trace this call's other telemetry already belongs to — falling
+ * back to a brand-new random trace/span id pair when there is none (no span
+ * active at this exact point, e.g. a stray call before any span opened), so
+ * the gateway still gets a well-formed, per-call-unique traceparent either
+ * way. Never throws; `isSpanContextValid` is the same guard
+ * `otel_propagation.ts`'s own propagators use.
+ */
+export function freshTraceparent() {
+    const active = traceApi.getSpanContext(contextApi.active());
+    if (active && isSpanContextValid(active)) {
+        return `00-${active.traceId}-${active.spanId}-01`;
+    }
+    return `00-${newId(32)}-${newId(16)}-01`;
+}
 // 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
@@ -71,14 +133,25 @@ const DEFAULT_MAX_TOKENS = 8192;
  *
  * `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.
+ * is current AT THAT MOMENT. `registerOllamaModel` re-runs this rebuild on
+ * EVERY call now (see its own doc for why: MAJOR-D's gateway-header
+ * re-stamping needs it), so in practice a mid-process `OLLAMA_BASE_URL`
+ * change is picked up by the very next dispatch to ANY already-registered
+ * id, not just the next brand-new one.
  */
 const registeredIds = new Set();
+/**
+ * The `GatewayCallContext` each model id was MOST RECENTLY registered with
+ * — see the "Gateway headers" section above for why `x-correlation-id`/
+ * `x-spf-agent` are static per-model (when otel propagation isn't
+ * installed) rather than resolved per-call. Keyed by model id so a union
+ * re-registration (triggered by ANY registration call, new id or repeat —
+ * see `registerOllamaModel`'s MAJOR-D doc) can rebuild every
+ * already-registered id's `Model.headers` from the context it MOST
+ * RECENTLY got, rather than dropping it or freezing it at first
+ * registration.
+ */
+const registrationContext = new Map();
 // 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
@@ -96,7 +169,25 @@ export function ollamaBaseUrl() {
     const raw = (process.env.OLLAMA_BASE_URL ?? "").trim();
     return raw || "http://localhost:11434/v1";
 }
-function modelFor(id, baseUrl) {
+function modelFor(id, baseUrl, ctx) {
+    // Static per-model headers — see the "Gateway headers" section above for
+    // why `x-correlation-id`/`x-spf-agent` live here rather than in
+    // `resolve()`, and ONLY on the NOT INSTALLED path: when
+    // `isFluePropagationInstalled()` is true, `GatewayHeadersPropagator`
+    // already injects both per real request, correctly attributed per
+    // session — stamping them here too would double them up on the wire
+    // (BLOCKER A's bug, for these two headers instead of `traceparent`).
+    // Omitted entirely (no `headers` key at all) when there is nothing to
+    // stamp — propagation installed, or `ctx` absent/empty — so a caller that
+    // never passes one, or a run with otel configured, gets a `Model` with no
+    // static headers.
+    const staticHeaders = {};
+    if (!isFluePropagationInstalled()) {
+        if (ctx?.adwId)
+            staticHeaders[X_CORRELATION_ID_HEADER] = ctx.adwId;
+        if (ctx?.agentName)
+            staticHeaders[X_SPF_AGENT_HEADER] = ctx.agentName;
+    }
     return {
         id,
         name: id,
@@ -113,30 +204,55 @@ function modelFor(id, baseUrl) {
         // silently truncating requests.
         contextWindow: 0,
         maxTokens: DEFAULT_MAX_TOKENS,
+        ...(Object.keys(staticHeaders).length > 0 ? { headers: staticHeaders } : {}),
     };
 }
 /**
  * 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.
+ * id ever registered this process. NOT idempotent w.r.t. `ctx` (see MAJOR-D
+ * below) — every call re-runs the union re-registration (dynamic imports
+ * are cheap after the first, and `setProvider()` is a cheap in-memory
+ * upsert), so this id's `Model.headers` always reflect the MOST RECENT
+ * `ctx` this function was called with, not just the first. A concurrent
+ * call for the SAME id joins the in-flight registration rather than running
+ * a second one in parallel (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).
+ * but is equally safe to call again later with a new id, or the SAME id
+ * again, mid-process — a new id's union re-registration is how a second
+ * model gets added without orphaning the first (see the `registeredIds` doc
+ * above); a repeat of the SAME id is how MAJOR-D below is fixed.
+ *
+ * MAJOR-D (fixed): `ctx`, when given AND `isFluePropagationInstalled()` is
+ * false (see the "Gateway headers" section above — when it's true, these
+ * two headers come from the per-request `GatewayHeadersPropagator`
+ * instead), is stamped onto this id's `Model.headers` as
+ * `x-correlation-id`/`x-spf-agent`. A PRIOR version of this function
+ * returned immediately for an already-registered id (a false comment
+ * claimed "one spf process runs one adw_id for its whole lifetime" to
+ * justify this) — which meant every later agent/adw_id sharing a model id
+ * within one process (spf `loop`/`fanout`/`watch`, which run many adw_ids
+ * in ONE process, `fanout` concurrently) silently kept the FIRST
+ * registration's headers forever. Re-running the full registration on every
+ * call, unconditionally, fixes that for every case except one, which
+ * remains and is not silently swallowed: two flue agents dispatching
+ * CONCURRENTLY (not sequentially) to the SAME `ollama/<id>` model id race on
+ * `registrationContext`/`setProvider()` — whichever registration's
+ * `setProvider()` call lands last wins the headers BOTH calls' subsequent
+ * dispatches see, until the next registration for that id. This is a
+ * `fanout` concurrency > 1 scenario specifically (two DIFFERENT agents,
+ * same process, same model id, truly overlapping registrations) — a
+ * sequential loop/watch never hits it, since each call's `await` completes
+ * before the next one starts.
  */
-export async function registerOllamaModel(modelId) {
-    if (registeredIds.has(modelId))
-        return;
+export async function registerOllamaModel(modelId, ctx) {
     const existing = inflight.get(modelId);
     if (existing)
         return existing;
@@ -156,8 +272,9 @@ export async function registerOllamaModel(modelId) {
         // AFTER `setProvider()` below succeeds (see this function's doc).
         const ids = new Set(registeredIds);
         ids.add(modelId);
+        registrationContext.set(modelId, ctx ?? {});
         const baseUrl = ollamaBaseUrl();
-        const models = [...ids].map((id) => modelFor(id, baseUrl));
+        const models = [...ids].map((id) => modelFor(id, baseUrl, registrationContext.get(id)));
         const options = {
             id: "ollama",
             name: "Ollama (local)",
@@ -165,9 +282,37 @@ export async function registerOllamaModel(modelId) {
             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 } }),
+                    // Fresh per real dispatch (pi-ai reinvokes `resolve()` on every
+                    // `Models.stream()`/`applyAuth()` call, never caching it — see the
+                    // "Gateway headers" section above) — `apiKey` honors a real
+                    // `OLLAMA_API_KEY` when the operator set one (e.g. the Briefs
+                    // gateway's per-client bearer), falling back to the DUMMY_API_KEY
+                    // a bare keyless local server needs (see its own doc for why that
+                    // can't just be "no key needed" instead).
+                    //
+                    // `headers.traceparent` is minted here ONLY when
+                    // `isFluePropagationInstalled()` is false — checked fresh on every
+                    // call, since propagation can be installed partway through this
+                    // process's lifetime (the first ollama dispatch in a run with
+                    // otel configured registers the model BEFORE
+                    // `installFluePropagation()` runs — see `agent_flue.ts`'s `run()`
+                    // — so a later dispatch on the SAME already-registered model must
+                    // still re-check, not trust a value baked in at registration
+                    // time). When installed, `@opentelemetry/instrumentation-undici`
+                    // already injects a real, fresh `traceparent` for this exact
+                    // outbound request (see `otel_propagation.ts`); minting a second
+                    // one here would put TWO `traceparent` headers on the wire
+                    // (`UndiciInstrumentation` appends, it does not replace) — this
+                    // was BLOCKER A. `x-correlation-id`/`x-spf-agent` are NEVER set
+                    // here either way — see `Model.headers` above (not installed) and
+                    // `GatewayHeadersPropagator` (installed) for where those two
+                    // actually come from.
+                    resolve: async () => ({
+                        auth: {
+                            apiKey: ollamaApiKey(),
+                            ...(isFluePropagationInstalled() ? {} : { headers: { traceparent: freshTraceparent() } }),
+                        },
+                    }),
                 },
             },
             models,
@@ -205,4 +350,5 @@ export function resetOllamaRegistrationForTest() {
     registeredIds.clear();
     inflight.clear();
     lastProvider = undefined;
+    registrationContext.clear();
 }

package/dist/core/otel.js

@@ -407,7 +407,15 @@ export function redact(message, secrets) {
 function numOrNull(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
-/** UsageBreakdown's token fields -> attribute suffixes. Numbers only, by construction. */
+/**
+ * UsageBreakdown's token fields -> attribute suffixes. Numbers only, by
+ * construction. `billable_tokens` rides alongside `total_tokens` — the SAME
+ * split `run_dashboard.tsx`'s live spend line and `estimate.ts`'s cutoff
+ * projection now both carry (see `UsageBreakdown.billable_tokens`'s doc
+ * comment in `data_types.ts`) — so a Langfuse/OTEL consumer graphing spend
+ * against `defaults.max_run_tokens` has the metric the real ceiling check
+ * actually uses, not just the display total (cache reads included).
+ */
 const TOKEN_FIELDS = [
     ["input_tokens", "spf.tokens.input"],
     ["output_tokens", "spf.tokens.output"],
@@ -415,6 +423,7 @@ const TOKEN_FIELDS = [
     ["cache_write_tokens", "spf.tokens.cache_write"],
     ["reasoning_tokens", "spf.tokens.reasoning"],
     ["total_tokens", "spf.tokens.total"],
+    ["billable_tokens", "spf.tokens.billable"],
 ];
 const COST_FIELDS = [
     ["input_cost", "spf.cost.input"],

package/dist/core/otel_propagation.d.ts

@@ -14,8 +14,11 @@
  * `-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.
+ * instrumentations use to inject `traceparent` (and, here, the gateway's own
+ * `x-correlation-id`/`x-spf-agent` — see GatewayHeadersPropagator below;
+ * NEVER `x-request-id`, which Envoy/Switchyard own end-to-end and which a
+ * client-sent value would corrupt) 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
@@ -58,7 +61,64 @@
  * 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:
+ * can stick.
+ *
+ * BLOCKER 1 (fixed) — `resolveRootContext`'s return value NEVER becomes the
+ * active context. Verified against `@flue/opentelemetry`'s own dist
+ * (index.mjs:361 for the `chat <model>` span, :329 for the interceptor that
+ * activates it): the resolved `Context` is passed to `tracer.startSpan(...)`
+ * ONLY as `parentContext` — it supplies the new span's trace id/parent span
+ * id and is then discarded. What actually gets activated around the real
+ * dispatch is `context.with(trace.setSpan(context.active(), span), next)` —
+ * a context built from `context.active()` (whatever was active before,
+ * almost always ROOT) plus the freshly minted `span`, NOT the resolved
+ * context itself. A prior version of this module stashed the session's
+ * `adw_id`/`agent_name` as a plain context VALUE on the context
+ * `resolveFlueRootContext` returned (keyed under a private context key) and
+ * had `GatewayHeadersPropagator` read that value back at inject time — which
+ * can never work, because that exact context object is never the one made
+ * active; only its SpanContext (traceId/spanId/flags) survives, carried by
+ * the new span. Confirmed live: `scratchpad/probe_installed_real.mjs`,
+ * reproducing flue's exact two-line sequence against a real pi-ai dispatch,
+ * printed `x-correlation-id: ABSENT` / `x-spf-agent: ABSENT` before this fix.
+ *
+ * THE FIX: key the registration by TRACE ID instead of by context identity.
+ * `registerFlueSessionTrace` now ALSO records, in `traceIdRegistrations`,
+ * the trace id parsed out of the very `traceparent` it's given — the same
+ * deterministic trace id `resolveFlueRootContext` extracts and hands to
+ * `tracer.startSpan` as that span's parent, so the span it creates carries
+ * that exact trace id forward into whatever context DOES get activated.
+ * `GatewayHeadersPropagator.inject()` below reads `trace.getSpanContext(ctx)
+ * ?.traceId` — the thing that provably survives into the active context at
+ * request time — and looks IT UP in `traceIdRegistrations`, rather than
+ * trying to read a value off a context object that was never activated.
+ * One deterministic trace id per adw_id (`otel.ts:556`'s `traceIdFor(adwId)`,
+ * reused for EVERY agent call in that run — `otel.ts:737`'s
+ * `agentCallTraceContext` varies only the span id, never the trace id), and
+ * `traceIdRegistrations` is keyed on that trace id alone, not on session id
+ * or span id. So "latest registration for this trace id wins" is exact
+ * within a run when its agents run one at a time — which is how a `fanout`
+ * attempt's own agents run: `fanout.ts:448` derives each attempt its OWN
+ * adw_id, so distinct fanout attempts get distinct trace ids and cannot
+ * collide here, regardless of `fanout`'s concurrency. The one real collision
+ * this map can still see is narrower and does not happen in SPF today: TWO
+ * AGENTS OVERLAPPING INSIDE ONE adw_id — a single run dispatching a second
+ * flue agent call before the first one's `unregisterFlueSessionTrace` has
+ * run — since both share that run's one trace id, the second
+ * `registerFlueSessionTrace` call overwrites the first agent's entry in
+ * `traceIdRegistrations` while its dispatch may still be in flight, and that
+ * agent's outbound request would then carry the OTHER agent's
+ * `x-correlation-id`/`x-spf-agent` (never a wrong `adw_id`, since both
+ * belong to the same run — only the wrong `agentName`). No chain SPF ships
+ * dispatches two agents concurrently within one adw_id; this is flagged as
+ * the mechanism's honest limit, not a bug being carried forward. The SAME
+ * registration carries this session's `adw_id`/agent name (see
+ * `FlueSessionRegistration`) so a
+ * session's `x-correlation-id`/`x-spf-agent` ride the exact same "resolved
+ * once per submission, read per real HTTP call" path as `traceparent` does,
+ * via `GatewayHeadersPropagator` below, instead of the static-per-model-id
+ * fallback `ollama_provider.ts` needs when this pipeline isn't installed at
+ * all (otel unconfigured). 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
@@ -66,17 +126,42 @@
  *   - 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.
+ *     path. The same per-request injection point also carries THIS
+ *     session's `x-correlation-id`/`x-spf-agent`, correctly attributed even
+ *     when multiple sessions are concurrent in one process, AS LONG AS their
+ *     deterministic trace ids differ (their `ctx.id`s, and therefore their
+ *     registrations, are distinct) — see BLOCKER 1 above for the precise
+ *     lookup key.
  *   - 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.
+ *     trace exactly as v1 did, correlatable by `spf.adw_id`/time window.
+ *     Degraded join, never an error and never MIS-attributed; the gateway
+ *     headers for exactly this case are simply ABSENT (no fallback identity
+ *     — see `GatewayHeadersPropagator.inject()` below) rather than guessing
+ *     at whichever session happened to register most recently.
  *   - 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.
  *
+ * STATIC HEADERS STAY SUPPRESSED WHEN INSTALLED (BLOCKER 1's other half,
+ * decided AGAINST enabling): `ollama_provider.ts`'s `modelFor()` keeps
+ * omitting `Model.headers`' `x-correlation-id`/`x-spf-agent` whenever
+ * `isFluePropagationInstalled()` is true — it is NOT also stamped as a
+ * baseline alongside this propagator. Measured live
+ * (`scratchpad/probe_duplicate_header.mjs`, against the REAL
+ * `@opentelemetry/instrumentation-undici` used here): `request.addHeader(k,
+ * v)` — what that instrumentation calls for every header
+ * `propagation.inject()` returns — APPENDS a second raw header line rather
+ * than replacing one already present (undici's own `Request.addHeader` has
+ * no dedupe-by-name step); the receiving `http.IncomingMessage.headers`
+ * then comma-joins the two into one corrupted value
+ * (`"FROM_STATIC, FROM_PROPAGATOR"`), and `req.rawHeaders` shows the literal
+ * duplicate line. So when propagation is installed, THIS propagator is the
+ * sole source of `x-correlation-id`/`x-spf-agent` — never doubled up with a
+ * static value from `Model.headers` — proven on the wire by
+ * `src/test/ollama_gateway_e2e.test.ts`'s "no duplicate headers" test.
+ *
  * 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
@@ -98,33 +183,73 @@
  * 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.
+ * The Briefs gateway's own correlation headers — see `ollama_provider.ts`'s
+ * "Gateway headers" section for the full three-header contract (the third,
+ * `traceparent`, is the W3C standard one `W3CTraceContextPropagator` already
+ * injects). Defined here (not in `ollama_provider.ts`) because
+ * `GatewayHeadersPropagator` below is the thing that actually injects them
+ * onto the wire when this pipeline is installed; `ollama_provider.ts`
+ * imports these two constants rather than redeclaring them, so there is
+ * exactly one spelling of each header name in the codebase.
+ */
+export declare const X_CORRELATION_ID_HEADER = "x-correlation-id";
+export declare const X_SPF_AGENT_HEADER = "x-spf-agent";
+/**
+ * One flue session's (`ctx.id`'s) registration: the W3C `traceparent` string
+ * for SPF's deterministic agent-call span (see `registerFlueSessionTrace`),
+ * plus this session's `adw_id`/agent name — carried the SAME way, see the
+ * module header's FLUE SPANS JOIN... section for why both ride one
+ * registration rather than two separate maps.
+ */
+export interface FlueSessionRegistration {
+    traceparent: string;
+    adwId?: string;
+    agentName?: string;
+}
+/**
+ * Registers `registration` (SPF's deterministic agent-call traceparent, plus
+ * this session's adw_id/agent name — see `FlueSessionRegistration`) 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). Also indexes the SAME identity under this
+ * registration's parsed trace id (`traceIdRegistrations`) — see the module
+ * header's BLOCKER 1 section and that map's own doc for why.
  */
-export declare class XRequestIdPropagator implements TextMapPropagator {
+export declare function registerFlueSessionTrace(sessionId: string, registration: FlueSessionRegistration): void;
+/**
+ * Injects `x-correlation-id`/`x-spf-agent` by looking up the ACTIVE
+ * `Context`'s SpanContext trace id (`trace.getSpanContext(ctx)?.traceId`) in
+ * `traceIdRegistrations` — the same per-real-HTTP-call injection point
+ * `W3CTraceContextPropagator` uses for `traceparent`, and, critically, keyed
+ * on the one piece of `resolveFlueRootContext`'s return value that provably
+ * survives into that active context (see the module header's BLOCKER 1
+ * section for why a context VALUE does not). Injects NOTHING — no fallback,
+ * no last-known identity — when this exact trace id is not in the map: an
+ * unregistered/unmapped span (flue's own bookkeeping spans, or ANY span
+ * after every session has been unregistered) must not stamp a stale or
+ * unrelated session's `x-correlation-id`/`x-spf-agent` onto unrelated
+ * outbound traffic (a third-party call, a post-session straggler). A true
+ * no-op (nothing set) in that case — never throws, never invents a value.
+ * Replaces the old `XRequestIdPropagator`:
+ * `x-request-id` must NEVER reach the gateway (Envoy/Switchyard own it
+ * end-to-end; a client-sent value corrupts their own sampling) and this repo
+ * no longer has anything that wants it emitted.
+ */
+export declare class GatewayHeadersPropagator 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.
+ * a REUSED session id could collide with on a later phase. Also prunes this
+ * session's entry out of `traceIdRegistrations` (parsed fresh from the
+ * departing registration's own `traceparent`, so it removes exactly the
+ * entry this session added.
  */
 export declare function unregisterFlueSessionTrace(sessionId: string): void;
 /**
@@ -137,6 +262,13 @@ export declare function unregisterFlueSessionTrace(sessionId: string): void;
  * 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.
+ *
+ * Used by `@flue/opentelemetry` ONLY as `tracer.startSpan`'s parent
+ * argument (see the module header's BLOCKER 1 section) — the value handed
+ * back here is never itself activated, so it carries no context VALUES for
+ * `GatewayHeadersPropagator` to read; `x-correlation-id`/`x-spf-agent` are
+ * instead looked up by trace id, via `traceIdRegistrations`, which
+ * `registerFlueSessionTrace` populates independently of this function.
  */
 export declare function resolveFlueRootContext(_event: unknown, ctx: {
     id?: string;
@@ -157,3 +289,15 @@ export interface FluePropagationConfig {
 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;
+/**
+ * Whether `installFluePropagation` has actually installed the global
+ * TracerProvider/propagator/instrumentations in THIS process. Consulted by
+ * `ollama_provider.ts` (see its "Gateway headers" section) so `resolve()`/
+ * `modelFor()` know whether the instrumentation above already covers
+ * `traceparent`/`x-correlation-id`/`x-spf-agent` per real outbound call —
+ * supplying any of the three a second way when this is `true` would double
+ * it up on the wire (`UndiciInstrumentation` appends via `addHeader`, it
+ * does not replace). `false` — the common case, otel unconfigured — means
+ * `ollama_provider.ts` must supply all three itself.
+ */
+export declare function isFluePropagationInstalled(): boolean;