@gr8ful/spf 0.18.0 → 0.19.1

package/dist/core/issues/provider.d.ts

@@ -311,6 +311,29 @@ export interface IssueAuthoringProvider {
      * roll-up, refine cannot function without authoring at all.
      */
     listChildren(parent: Issue): Promise<Issue[]>;
+    /**
+     * Best-effort: relate a freshly published tree's ROOT issue back to the
+     * spec issue (`specId`) it was refined FROM — `core/refine.ts`'s
+     * `publish()` calls this once per root node (a node with no `parent` of
+     * its own within the refined tree) when it was given a `specIssueId`.
+     *
+     * Deliberately NOT `linkChild`: that method sets the tracker's
+     * HIERARCHY field (Jira's `parent`, GitHub's sub-issues API), and a
+     * spec's own issue type (Story by default — `JiraIssueTypeMapSchema.spec`)
+     * frequently cannot legally PARENT a root node's type in Jira's
+     * issue-type hierarchy — see `JiraProvider`'s own doc comment on
+     * `publishSpecs()` for the same constraint. `linkToSpec` uses a plain,
+     * symmetric issue-to-issue reference instead (Jira's generic "issue
+     * link"), which has no such hierarchy restriction.
+     *
+     * OPTIONAL, not every tracker needs one: GitHub already gets a native,
+     * visible cross-reference for free the moment `renderBody`'s "## Parent"
+     * section renders a plain "#N" in the body — GitHub auto-links same-repo
+     * issue mentions into a real timeline "referenced this issue" event, no
+     * API call required. Jira does not do this for plain text, which is why
+     * `JiraProvider` implements this and `GitHubProvider` does not.
+     */
+    linkToSpec?(specId: string, issue: Issue): Promise<void>;
 }
 /**
  * Structural, not nominal: checks for the three methods rather than

package/dist/core/loop.d.ts

@@ -106,7 +106,35 @@ export interface LedgerAttempt {
     error: string | null;
     /** HEAD's short sha after a successful (exit 0) iteration — unchanged from the previous attempt's if this iteration committed nothing new, which is exactly what `isStuck` below looks for. `null` only for an errored or non-accepted (nonzero exit) attempt, where nothing was checked out to read. */
     commit_sha: string | null;
+    /**
+     * Kept for backward compatibility with ledger rows written before
+     * `billable_tokens` (below) existed — on a row this old, `tokens` is the
+     * DISPLAY total (`sessions.total_tokens`, cache reads included), the only
+     * figure that era ever recorded. On every row written since, this field
+     * and `billable_tokens` are set to the SAME (billable) value; they only
+     * ever diverge across that one-time boundary, never within a single
+     * write. `cumulativeSpend` is what actually reads either — see its own
+     * doc comment for the precedence.
+     */
     tokens: number;
+    /**
+     * The BILLABLE figure (input + cache-write + output) — what
+     * `--max-tokens`/`overCumulativeBudget` is SUPPOSED to compare against,
+     * same metric `defaults.max_run_tokens` uses within one chain run (see
+     * `UsageBreakdown.billable_tokens`'s doc comment, `data_types.ts`). NOT
+     * the display total (`sessions.total_tokens`, cache reads included) —
+     * `cli/commands/loop.ts`'s readback reads `session.billable_tokens`,
+     * falling back to `total_tokens` only for a SESSION row that predates
+     * that sqlite column being populated.
+     *
+     * `undefined` on any LEDGER row written before this field existed — a
+     * genuinely old-format row, not a free ($0) iteration. `cumulativeSpend`
+     * falls back to `tokens` for exactly that row (the only figure it has,
+     * a display total it cannot retroactively convert), and
+     * `hasLegacyTokenRows` is what a caller uses to warn once that a ceiling
+     * check is now mixing metrics across the ledger's own history.
+     */
+    billable_tokens?: number;
     cost: number;
     failures: string[];
     started_at: string;
@@ -151,13 +179,22 @@ export declare function newLedger(input: {
 export declare function resolveGoalId(explicit: string | undefined): string;
 export interface CumulativeBudget {
     maxCost?: number;
+    /** `--max-tokens` — checked against BILLABLE tokens (see `LedgerAttempt.billable_tokens`'s own doc comment), the same metric `defaults.max_run_tokens` checks per-call inside one chain run. */
     maxTokens?: number;
 }
 export declare function cumulativeSpend(attempts: LedgerAttempt[]): {
     cost: number;
     tokens: number;
 };
-/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. */
+/**
+ * True when the ledger holds at least one attempt written before
+ * `billable_tokens` existed — `cumulativeSpend` is then silently mixing a
+ * display-total figure (that row's `tokens`) into a sum whose newer rows
+ * are billable. Used to print a one-time operator warning rather than let
+ * that mismatch pass unremarked; see `runLoop`'s call site.
+ */
+export declare function hasLegacyTokenRows(attempts: LedgerAttempt[]): boolean;
+/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. `spend.tokens` must already be BILLABLE tokens (see `LedgerAttempt.tokens`) — this function just compares, it does not know which metric it was handed. */
 export declare function overCumulativeBudget(budget: CumulativeBudget, spend: {
     cost: number;
     tokens: number;
@@ -185,6 +222,7 @@ export interface IterationResult {
     error: string | null;
     /** `null` when nothing was committed this iteration (a no-op, or a throw before any commit). */
     commit_sha: string | null;
+    /** BILLABLE tokens — see `LedgerAttempt.tokens`'s own doc comment; `runIteration` (`cli/commands/loop.ts`) reads this straight from `LedgerAttempt`, so the two must stay the same metric. */
     tokens: number;
     cost: number;
     /** `null` when the iteration errored or exited non-zero — the stop check only ever runs against a chain that accepted its own work, same as `fixLoop` only re-verifies after a phase that didn't already throw. */

package/dist/core/loop.js

@@ -132,10 +132,30 @@ export function newLedger(input) {
 export function resolveGoalId(explicit) {
     return explicit ?? newId(8);
 }
+/**
+ * Per-attempt token figure for budget purposes: `billable_tokens` where the
+ * row has it, else `tokens` (an old-format row, predating that field — see
+ * `LedgerAttempt.billable_tokens`'s own doc comment). Never the other way
+ * around: a new row's `tokens` happens to equal its `billable_tokens` today,
+ * but `billable_tokens` is the one this function trusts on purpose.
+ */
+function tokensForBudget(a) {
+    return a.billable_tokens ?? a.tokens;
+}
 export function cumulativeSpend(attempts) {
-    return attempts.reduce((acc, a) => ({ cost: acc.cost + a.cost, tokens: acc.tokens + a.tokens }), { cost: 0, tokens: 0 });
+    return attempts.reduce((acc, a) => ({ cost: acc.cost + a.cost, tokens: acc.tokens + tokensForBudget(a) }), { cost: 0, tokens: 0 });
 }
-/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. */
+/**
+ * True when the ledger holds at least one attempt written before
+ * `billable_tokens` existed — `cumulativeSpend` is then silently mixing a
+ * display-total figure (that row's `tokens`) into a sum whose newer rows
+ * are billable. Used to print a one-time operator warning rather than let
+ * that mismatch pass unremarked; see `runLoop`'s call site.
+ */
+export function hasLegacyTokenRows(attempts) {
+    return attempts.some((a) => a.billable_tokens === undefined);
+}
+/** Whether the goal-scoped ceiling is already exhausted going into the NEXT iteration — a stronger, ledger-wide check than any single iteration's own budget. `spend.tokens` must already be BILLABLE tokens (see `LedgerAttempt.tokens`) — this function just compares, it does not know which metric it was handed. */
 export function overCumulativeBudget(budget, spend) {
     if (budget.maxCost !== undefined && spend.cost >= budget.maxCost)
         return true;
@@ -207,6 +227,13 @@ export async function runLoop(deps) {
     if (existing) {
         deps.log(`loop: resuming goal ${deps.goalId} — ${existing.attempts.length} attempt(s) already recorded`);
     }
+    // One-time info line, not a per-iteration one: legacy rows already IN the
+    // ledger (from a resumed goal) do not change count as this run proceeds,
+    // so there is nothing to re-warn about after the first check.
+    if (deps.budget.maxTokens !== undefined && hasLegacyTokenRows(ledger.attempts)) {
+        deps.log(`loop: goal ${deps.goalId} — ledger has attempt(s) recorded before billable-token tracking; ` +
+            "--max-tokens falls back to their display-total token count for those rows (see LedgerAttempt.billable_tokens)");
+    }
     let lastVerdict = ledger.attempts.length > 0 ? { passed: false, failures: ledger.attempts[ledger.attempts.length - 1].failures, artifacts: [] } : null;
     for (let i = ledger.attempts.length + 1; i <= deps.max; i++) {
         if (overCumulativeBudget(deps.budget, cumulativeSpend(ledger.attempts))) {
@@ -244,7 +271,11 @@ export async function runLoop(deps) {
             exit_code: result.exit_code,
             error: result.error,
             commit_sha: result.commit_sha,
+            // Every row written from here on sets both to the same (billable)
+            // value — see `LedgerAttempt.tokens`/`billable_tokens`'s doc comments
+            // for why they only ever diverge on an old-format row.
             tokens: result.tokens,
+            billable_tokens: result.tokens,
             cost: result.cost,
             failures,
             started_at: startedAt,

package/dist/core/ollama_provider.d.ts

@@ -42,28 +42,111 @@
  * cost nothing at runtime either way.
  */
 import type { Provider } from "@earendil-works/pi-ai";
+/**
+ * `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 declare function ollamaApiKey(): string;
+/** SPF-side identity for one LLM call, as far as `registerOllamaModel`'s caller can supply it. Both fields optional — an absent one simply omits its header. */
+export interface GatewayCallContext {
+    /** The run's adw_id — sent as `x-correlation-id` so the gateway groups this run's calls. */
+    adwId?: string;
+    /** The SPF agent name — sent as `x-spf-agent`. */
+    agentName?: string;
+}
+/** 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 declare 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 declare function freshTraceparent(): string;
 /** Exported so `doctor.ts`'s reachability probe agrees with what a real dispatch resolves to — see its call site for why a `??`/`||` mismatch here matters. */
 export declare function ollamaBaseUrl(): string;
 /**
  * Registers `modelId` (the part after `ollama/` in an agent's `model`
  * config) with Flue's provider registry, alongside every other `ollama/*`
- * id ever registered this process. Idempotent: a repeat of an already-seen
- * id is a no-op — no re-registration, no re-import. A concurrent call for
- * the SAME id joins the in-flight registration rather than returning early
- * (see `inflight`'s doc); `registeredIds` itself is only ever updated AFTER
- * `setProvider()` succeeds, so a failed attempt (a bad install, a bundler
- * that can't resolve the deep `.lazy` subpath, a future validation error)
- * leaves the id unregistered and eligible for a real retry — not
- * permanently and misleadingly marked "done" while nothing is actually
- * registered.
+ * 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 declare function registerOllamaModel(modelId: string): Promise<void>;
+export declare function registerOllamaModel(modelId: string, ctx?: GatewayCallContext): Promise<void>;
 /** Test-only: the most recently constructed provider object (see `lastProvider`'s doc). */
 export declare function providerForTest(): Provider<"openai-completions"> | undefined;
 /** Test-only: forgets accumulated ids so test files don't leak into each other. Does not touch Flue's own registry — pair with `resetModelsForTests()` from `@flue/runtime/internal`. */

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"],