@gr8ful/spf 0.18.0 → 0.19.1

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;

package/dist/core/otel_propagation.js

@@ -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
@@ -108,56 +193,124 @@ import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trac
 import { createOpenTelemetryInstrumentation } from "@flue/opentelemetry";
 import { instrument } from "@flue/runtime";
 import { resolveTracesUrl } from "./otel.js";
-/** 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 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 const X_CORRELATION_ID_HEADER = "x-correlation-id";
+export const X_SPF_AGENT_HEADER = "x-spf-agent";
+/**
+ * Instance-id -> registration backing `resolveFlueRootContext` — see the
+ * module header for the full mechanism and WHY this is a map consulted per
+ * span rather than a dispatch-time context wrap (flue's single claim loop
+ * makes the latter mis-attribute every agent after the first). One entry per
+ * in-flight `agent_flue.run()` call.
+ */
+const flueSessionTraces = new Map();
+/**
+ * Trace id -> gateway identity, keyed on the deterministic trace id parsed
+ * out of a registration's OWN `traceparent` (see `traceIdFromTraceparent`) —
+ * see the module header's BLOCKER 1 section for why this, and not a context
+ * VALUE, is the lookup `GatewayHeadersPropagator` uses. Populated by
+ * `registerFlueSessionTrace`, pruned by `unregisterFlueSessionTrace`. A
+ * trace id collision here (two DIFFERENT registrations sharing one trace id)
+ * is not expected in practice — trace ids are SPF's deterministic per-adw_id
+ * ids — but if it ever happened, the later `registerFlueSessionTrace` call
+ * would simply win, matching this map's own "current call wins" rule.
  */
-export class XRequestIdPropagator {
+const traceIdRegistrations = new Map();
+/**
+ * Parses the W3C `traceId` segment out of a `traceparent` string via a real
+ * `propagation.extract`/`getSpanContext` round trip — the SAME extraction
+ * `resolveFlueRootContext` performs, so "the trace id we index
+ * `traceIdRegistrations` under" and "the trace id a span parented via this
+ * `traceparent` actually carries" are provably the same value, not two
+ * independent parses that could drift. Returns `undefined` for a malformed
+ * `traceparent` (mirrors `resolveFlueRootContext`'s own malformed-input
+ * handling) rather than throwing.
+ */
+function traceIdFromTraceparent(traceparent) {
+    const extracted = propagation.extract(ROOT_CONTEXT, { traceparent }, defaultTextMapGetter);
+    const spanContext = traceApi.getSpanContext(extracted);
+    return spanContext && isSpanContextValid(spanContext) ? spanContext.traceId : undefined;
+}
+/**
+ * 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 function registerFlueSessionTrace(sessionId, registration) {
+    flueSessionTraces.set(sessionId, registration);
+    const identity = { adwId: registration.adwId, agentName: registration.agentName };
+    const traceId = traceIdFromTraceparent(registration.traceparent);
+    if (traceId)
+        traceIdRegistrations.set(traceId, identity);
+}
+/**
+ * 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 class GatewayHeadersPropagator {
     inject(ctx, carrier, setter) {
         const spanContext = traceApi.getSpanContext(ctx);
-        if (!spanContext || !isSpanContextValid(spanContext))
+        const registration = spanContext && traceIdRegistrations.get(spanContext.traceId);
+        if (!registration)
             return;
-        setter.set(carrier, X_REQUEST_ID_HEADER, spanContext.spanId);
+        if (registration.adwId)
+            setter.set(carrier, X_CORRELATION_ID_HEADER, registration.adwId);
+        if (registration.agentName)
+            setter.set(carrier, X_SPF_AGENT_HEADER, registration.agentName);
     }
     extract(ctx) {
         return ctx;
     }
     fields() {
-        return [X_REQUEST_ID_HEADER];
+        return [X_CORRELATION_ID_HEADER, X_SPF_AGENT_HEADER];
     }
 }
-/**
- * Instance-id -> agent-call traceparent registrations backing
- * `resolveFlueRootContext` — see the module header for the full mechanism
- * and WHY this is a map consulted per span rather than a dispatch-time
- * context wrap (flue's single claim loop makes the latter mis-attribute
- * every agent after the first). One entry per in-flight `agent_flue.run()`
- * call.
- */
-const flueSessionTraces = new Map();
-/**
- * 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 function registerFlueSessionTrace(sessionId, traceparent) {
-    flueSessionTraces.set(sessionId, traceparent);
-}
 /**
  * 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 function unregisterFlueSessionTrace(sessionId) {
+    const registration = flueSessionTraces.get(sessionId);
     flueSessionTraces.delete(sessionId);
+    if (!registration)
+        return;
+    const traceId = traceIdFromTraceparent(registration.traceparent);
+    if (traceId)
+        traceIdRegistrations.delete(traceId);
 }
 /**
  * The `resolveRootContext` implementation handed to
@@ -169,14 +322,23 @@ export function unregisterFlueSessionTrace(sessionId) {
  * 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 function resolveFlueRootContext(_event, ctx) {
-    const traceparent = ctx?.id ? flueSessionTraces.get(ctx.id) : undefined;
-    if (!traceparent)
+    const registration = ctx?.id ? flueSessionTraces.get(ctx.id) : undefined;
+    if (!registration)
         return undefined;
-    const extracted = propagation.extract(ROOT_CONTEXT, { traceparent }, defaultTextMapGetter);
+    const extracted = propagation.extract(ROOT_CONTEXT, { traceparent: registration.traceparent }, defaultTextMapGetter);
     const spanContext = traceApi.getSpanContext(extracted);
-    return spanContext && isSpanContextValid(spanContext) ? extracted : undefined;
+    if (!spanContext || !isSpanContextValid(spanContext))
+        return undefined;
+    return extracted;
 }
 let installed = false;
 let flueInstrumented = false;
@@ -200,7 +362,7 @@ export function installFluePropagation(cfg, log = (m) => console.error(m)) {
             });
             traceApi.setGlobalTracerProvider(provider);
             contextApi.setGlobalContextManager(new AsyncHooksContextManager().enable());
-            propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new XRequestIdPropagator()] }));
+            propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new GatewayHeadersPropagator()] }));
             registerInstrumentations({ instrumentations: [new HttpInstrumentation(), new UndiciInstrumentation()] });
             // Set AFTER the fallible registrations above: on a construction-time
             // throw, the next call must be free to retry — latching `installed`
@@ -223,3 +385,17 @@ export function resetFluePropagationForTest() {
     installed = false;
     flueInstrumented = false;
 }
+/**
+ * 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 function isFluePropagationInstalled() {
+    return installed;
+}

package/dist/core/permissions.d.ts

@@ -73,6 +73,21 @@ export declare function permitted(p: string, agent: AgentConfig, cfg: SFConfig):
  * Detection alone would leave the repo holding the unauthorized change while
  * reporting a failure, so anything the agent introduced outside its allowlist
  * is rolled back before the phase dies. What it cannot undo, it names.
+ *
+ * `defaults.read_only_ignore` carves out one exception to "names, fails" —
+ * but only where `isSafeToIgnore` says restoring is actually possible (see
+ * its own doc comment): a TRUE read-only agent (`writes: []`) that churned
+ * a lockfile that was CLEAN before this phase. That one case is STILL
+ * rolled back unconditionally like any other breach — an ignored path is
+ * never left standing — it just does not, on its own, fail the phase.
+ * Everything else `isIgnorableChurn` alone would have matched (a dirty-before
+ * path, an agent that reverted uncommitted work, a write-restricted rather
+ * than read-only agent) falls through to the real-breach path below instead.
+ * `onIgnored`, when given, is called once with every safely-ignored path
+ * before returning, so a caller with a logger (`agents.ts`'s `execute()`)
+ * can print the one required info line — this module has no logger of its
+ * own to call (`RunLike` is only `repo_root`/`cfg`), so the caller does the
+ * printing.
  */
-export declare function enforce(run: RunLike, _phase: unknown, agent: AgentConfig, before: Record<string, string>): string[];
+export declare function enforce(run: RunLike, _phase: unknown, agent: AgentConfig, before: Record<string, string>, onIgnored?: (paths: string[]) => void): string[];
 export {};