@gr8ful/spf 0.17.0 → 0.18.0

package/dist/core/agents.d.ts

@@ -146,6 +146,12 @@ interface RunForAgents {
         envelopeRow: (phase: Phase, agent: string, outputType: string, payloadJson: string, valid: boolean, attempt: number) => Promise<void>;
         gateRow: (phase: Phase, gate: string, report: GateReport, attempt: number) => Promise<void>;
         agentSessionRow: (adwId: string, agent: AgentConfig, sessionId: string, contextTokens?: number, contextWindow?: number) => Promise<void>;
+        otel?: {
+            agentCallTraceContext: (phaseId: string, agentName: string) => {
+                traceparent: string;
+                spanId: string;
+            } | null;
+        } | null;
     };
     console: {
         agentStarted: (name: string, model: string, sessionId: string) => Promise<void>;

package/dist/core/agents.js

@@ -808,6 +808,19 @@ export async function execute(run, phase, call) {
         // WHOLE run rather than on the first call of each phase. See
         // `assertRunBudget` for why it is checked before, not after.
         assertRunBudget(run);
+        // Outbound OTel propagation (SPF's otel-sdk extension): the CURRENTLY
+        // OPEN agent-call span's own trace context, when one exists — `null`
+        // whenever `observability.otel` is unconfigured for this run (the
+        // common case, and byte-identical to before this field existed) or the
+        // exporter has no agent call open (shouldn't happen here — agent_start
+        // fires before `send()` is ever reached — but a `null` is a silent
+        // no-op either way, never an error). `otelBlock` threads the SAME
+        // endpoint/headers/service_name through so `agent_flue.ts` can install
+        // its own (separate, process-scoped) http/undici propagation without
+        // needing the whole `SFConfig` — see `data_types.ts`'s `AgentRequest.
+        // otel` doc comment.
+        const otelBlock = run.cfg.observability.otel;
+        const otelCtx = otelBlock ? (run.tracer.otel?.agentCallTraceContext(phase.phase_id, agent.name) ?? null) : null;
         const request = {
             prompt: promptText,
             system_prompt: systemText,
@@ -822,6 +835,15 @@ export async function execute(run, phase, call) {
             flue_db_path: path.join(run.data_dir, "flue.db"),
             env: agentEnv(agent),
             sandbox: spec,
+            otel: otelCtx && otelBlock
+                ? {
+                    traceparent: otelCtx.traceparent,
+                    x_request_id: otelCtx.spanId,
+                    endpoint: otelBlock.endpoint,
+                    headers: otelBlock.headers,
+                    service_name: otelBlock.service_name,
+                }
+                : undefined,
         };
         const forward = eventForwarder(run, phase, agent.name, agent.coding_agent);
         // Best-effort, fire-and-forget: these fire from a plain process-lifecycle

package/dist/core/data_types.d.ts

@@ -685,6 +685,7 @@ export declare const AgentConfigSchema: v.ObjectSchema<{
     readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly sandbox: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, undefined>, undefined>;
+    readonly lora_adapter: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
 export type AgentConfig = v.InferOutput<typeof AgentConfigSchema>;
 export declare const ConfigDefaultsSchema: v.ObjectSchema<{
@@ -756,13 +757,45 @@ export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
  * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
  * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
  * token goes; its VALUES are treated as secrets and never logged.
+ *
+ * `metrics` (default `true`) additionally gates `otel_metrics.ts`'s
+ * process-scoped meter — set `false` to keep trace export on while opting
+ * out of the metrics pipeline entirely. It has no effect on activation
+ * either way: `endpoint`'s presence is still the sole switch for BOTH
+ * signals, this field only narrows what a configured block sends.
+ *
+ * `allow_env` (default `false`) is a narrow, opt-in exception to EXPLICIT
+ * CONFIG ONLY (see `core/otel.ts`'s header): when `true` AND this block is
+ * ALREADY active (`endpoint` set here, in the file), the standard
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`/`OTEL_EXPORTER_OTLP_HEADERS` env vars may
+ * SUPPLEMENT it — e.g. a CI-injected collector token added to `headers`
+ * without checking it into the repo. It can NEVER activate export from
+ * nothing (there is no `endpoint` to fall back to when this block is absent
+ * at all — that case is unaffected by this flag either way) and a
+ * config-declared value always wins over the env on conflict. Defaults to
+ * `false` because this is still a deliberate loosening of an adversarially-
+ * reviewed, test-pinned invariant — an operator opts in per-repo.
  */
 export declare const OTelConfigSchema: v.ObjectSchema<{
     readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
     readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
     readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+    readonly metrics: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+    readonly allow_env: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
 }, undefined>;
 export type OTelConfig = v.InferOutput<typeof OTelConfigSchema>;
+/**
+ * `allow_env`'s narrow env-supplement path (see `OTelConfigSchema`'s doc
+ * comment above): called ONLY when `cfg.observability.otel` already exists
+ * with a real `endpoint` — this function never activates anything on its
+ * own and is never called when the block is absent. `OTEL_EXPORTER_OTLP_
+ * HEADERS` follows the OTel spec's env-var shape (comma-separated
+ * `key=value` pairs, URL-decoded); config-declared headers win over the env
+ * on a key collision. `OTEL_EXPORTER_OTLP_ENDPOINT`, when set, overrides
+ * `endpoint` itself — the one field this can change, since a CI runner
+ * commonly injects a different collector per job/environment.
+ */
+export declare function applyOtelEnvSupplement(otel: OTelConfig, env?: NodeJS.ProcessEnv): OTelConfig;
 /**
  * MIGRATION NOTE (BT-issue #66, 3 PRs): `observability.db` used to be ONLY a
  * bare string (a local sqlite path, defaulting to ".spf/data/spf.db"). This
@@ -868,6 +901,8 @@ export declare const ObservabilityConfigSchema: v.ObjectSchema<{
         readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
         readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
         readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+        readonly metrics: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+        readonly allow_env: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
     }, undefined>, undefined>;
 }, undefined>;
 export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema>;
@@ -1525,6 +1560,8 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
             readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
             readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+            readonly metrics: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
+            readonly allow_env: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
         }, undefined>, undefined>;
     }, undefined>, () => {
         db: string | {
@@ -1543,6 +1580,8 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 [x: string]: string;
             } | undefined;
             service_name: string;
+            metrics: boolean;
+            allow_env: boolean;
         } | undefined;
     }>;
     readonly agents: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -1561,6 +1600,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly sandbox: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["local", "opensandbox", "cloudflare"], undefined>, undefined>, undefined>;
+        readonly lora_adapter: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>, () => never[]>;
     readonly quality: v.OptionalSchema<v.ObjectSchema<{
         readonly checks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -1974,6 +2014,26 @@ export interface AgentRequest {
     env?: Record<string, string>;
     /** Absent (the default) => local(), byte-identical to before this field existed. See sandbox.ts. */
     sandbox?: SandboxSpec;
+    /**
+     * Outbound OTel trace-context propagation — set by `agents.ts`'s `send()`
+     * from `otel.ts`'s `OtelExporter.agentCallTraceContext()` ONLY when
+     * `observability.otel` is configured for this run; absent otherwise, and
+     * every backend that ignores it (`opencode` today) is byte-identical to
+     * before this field existed. `traceparent`/`x_request_id` are this call's
+     * own span context (`agent_cc.ts`'s single `spawn()` choke point turns
+     * them into `TRACEPARENT`/`ANTHROPIC_CUSTOM_HEADERS`); `endpoint`/
+     * `headers`/`service_name` are the SAME `observability.otel` block,
+     * carried through so `agent_flue.ts` can install its own (separate,
+     * process-scoped — see `otel_propagation.ts`) global http/undici
+     * propagation without needing the full `SFConfig`.
+     */
+    otel?: {
+        traceparent: string;
+        x_request_id: string;
+        endpoint: string;
+        headers?: Record<string, string>;
+        service_name: string;
+    };
 }
 /**
  * Tokens and the dollars they cost, per component, summed over a call.

package/dist/core/data_types.js

@@ -508,6 +508,13 @@ export const AgentConfigSchema = v.object({
     //   "local" -> force local for this agent
     //   null    -> same as unset (the writes/env_allowlist spelling)
     sandbox: v.optional(v.nullable(SandboxBackendSchema)),
+    // Explicit override for `otel.ts`'s `spf.lora_adapter` span attribute —
+    // the unambiguous source of truth when set. Unset (the common case) falls
+    // back to parsing `model` itself; see `loraAdapterFor()`'s own doc comment
+    // in `core/otel.ts` for the two zero-config conventions it recognizes.
+    // Purely descriptive: it does not change routing, dispatch, or which
+    // model actually serves the call — only what an OTel backend sees.
+    lora_adapter: v.optional(v.string()),
 });
 export const ConfigDefaultsSchema = v.object({
     coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "flue"),
@@ -581,12 +588,74 @@ export const ConfigDefaultsSchema = v.object({
  * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
  * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
  * token goes; its VALUES are treated as secrets and never logged.
+ *
+ * `metrics` (default `true`) additionally gates `otel_metrics.ts`'s
+ * process-scoped meter — set `false` to keep trace export on while opting
+ * out of the metrics pipeline entirely. It has no effect on activation
+ * either way: `endpoint`'s presence is still the sole switch for BOTH
+ * signals, this field only narrows what a configured block sends.
+ *
+ * `allow_env` (default `false`) is a narrow, opt-in exception to EXPLICIT
+ * CONFIG ONLY (see `core/otel.ts`'s header): when `true` AND this block is
+ * ALREADY active (`endpoint` set here, in the file), the standard
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`/`OTEL_EXPORTER_OTLP_HEADERS` env vars may
+ * SUPPLEMENT it — e.g. a CI-injected collector token added to `headers`
+ * without checking it into the repo. It can NEVER activate export from
+ * nothing (there is no `endpoint` to fall back to when this block is absent
+ * at all — that case is unaffected by this flag either way) and a
+ * config-declared value always wins over the env on conflict. Defaults to
+ * `false` because this is still a deliberate loosening of an adversarially-
+ * reviewed, test-pinned invariant — an operator opts in per-repo.
  */
 export const OTelConfigSchema = v.object({
     endpoint: v.pipe(v.string(), v.url()),
     headers: v.optional(v.record(v.string(), v.string()), undefined),
     service_name: v.optional(v.string(), "spf"),
+    metrics: v.optional(v.boolean(), true),
+    allow_env: v.optional(v.boolean(), false),
 });
+/**
+ * `allow_env`'s narrow env-supplement path (see `OTelConfigSchema`'s doc
+ * comment above): called ONLY when `cfg.observability.otel` already exists
+ * with a real `endpoint` — this function never activates anything on its
+ * own and is never called when the block is absent. `OTEL_EXPORTER_OTLP_
+ * HEADERS` follows the OTel spec's env-var shape (comma-separated
+ * `key=value` pairs, URL-decoded); config-declared headers win over the env
+ * on a key collision. `OTEL_EXPORTER_OTLP_ENDPOINT`, when set, overrides
+ * `endpoint` itself — the one field this can change, since a CI runner
+ * commonly injects a different collector per job/environment.
+ */
+export function applyOtelEnvSupplement(otel, env = process.env) {
+    if (!otel.allow_env)
+        return otel;
+    const envEndpoint = env["OTEL_EXPORTER_OTLP_ENDPOINT"];
+    const envHeadersRaw = env["OTEL_EXPORTER_OTLP_HEADERS"];
+    const envHeaders = {};
+    if (envHeadersRaw) {
+        for (const pair of envHeadersRaw.split(",")) {
+            const eq = pair.indexOf("=");
+            if (eq <= 0)
+                continue;
+            const key = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (key) {
+                try {
+                    envHeaders[key] = decodeURIComponent(value);
+                }
+                catch {
+                    envHeaders[key] = value;
+                }
+            }
+        }
+    }
+    if (!envEndpoint && Object.keys(envHeaders).length === 0)
+        return otel;
+    return {
+        ...otel,
+        endpoint: envEndpoint || otel.endpoint,
+        headers: { ...envHeaders, ...(otel.headers ?? {}) }, // config wins on conflict
+    };
+}
 /**
  * MIGRATION NOTE (BT-issue #66, 3 PRs): `observability.db` used to be ONLY a
  * bare string (a local sqlite path, defaulting to ".spf/data/spf.db"). This

package/dist/core/otel.d.ts

@@ -1,5 +1,5 @@
 /**
- * OpenTelemetry span export (v1): a config-gated, lossy, fire-and-forget
+ * OpenTelemetry span export (v2): a config-gated, lossy, fire-and-forget
  * PROJECTION of the trace SQLite already holds. Read this header before
  * changing anything here — every paragraph is a constraint that survived an
  * adversarial review, not a preference.
@@ -12,35 +12,84 @@
  * ever throw into a caller, block a caller, or be awaited by a caller other
  * than the two shutdown paths named under LIFECYCLE below.
  *
- * SPANS ONLY. No `resourceMetrics`, no `resourceLogs`. The OTLP metrics data
- * model (temporality, monotonicity, cumulative-vs-delta) is exactly where a
- * hand-rolled encoder produces numbers a backend silently misreads, and a
- * wrong cost number is worse than no cost number. Token counts and dollars
- * ride as span ATTRIBUTES instead. Do not "just add metrics" here.
+ * v2 CHANGE (SDK ENCODER SWAP). v1 hand-rolled the entire OTLP/HTTP-JSON wire
+ * format with its own `fetch()` call. v2 keeps every invariant below —
+ * public API, the deterministic sha256 id scheme, the attribute allowlist,
+ * the bounded queue, the per-run lifecycle — byte-for-byte, and replaces
+ * ONLY the encoder: spans are now plain objects that structurally satisfy
+ * `@opentelemetry/sdk-trace`'s `ReadableSpan` interface (that package's own
+ * concrete `Span`/`SpanImpl` class is NOT part of its public API surface —
+ * only the type is exported — so a duck-typed object is not a workaround,
+ * it is the intended integration point), handed to a real
+ * `@opentelemetry/exporter-trace-otlp-http` `OTLPTraceExporter` instance.
+ * `IdGenerator.generateSpanId()` takes no arguments and cannot be handed our
+ * sha256 ids any other way — this is why the SDK is used AROUND our own ids
+ * rather than asked to generate them.
+ *
+ * VERIFIED WIRE-SHAPE DIFFERENCES from the old hand-rolled encoder (proven
+ * against a real in-process OTLP/HTTP receiver in `src/test/otel.test.ts`,
+ * not assumed from docs — this was v1's #1 documented open risk):
+ *   - `intValue` is a JSON NUMBER (`{"intValue":1234}`), not a numeric
+ *     STRING. The real JSON serializer's `toAnyValue()` (`@opentelemetry/
+ *     otlp-transformer`) picks `intValue` whenever `Number.isInteger(value)`
+ *     and never stringifies it — proto3 JSON's "int64 as string" rule is a
+ *     PROTOBUF-JSON convention this exporter's plain-JSON path does not
+ *     follow. A whole-number COST (e.g. exactly `$2`) is therefore
+ *     indistinguishable on the wire from an integer attribute — a real,
+ *     accepted limitation of `number`-typed OTel attributes, not a bug
+ *     introduced here.
+ *   - `startTimeUnixNano`/`endTimeUnixNano`/event `timeUnixNano` ARE
+ *     STRINGS (`encodeAsString` — nanoseconds via `BigInt`, so no
+ *     precision loss past 2^53), matching v1's own precision-driven choice.
+ *   - trace/span ids are lowercase hex STRINGS (the JSON encoder's
+ *     `encodeSpanContext` is `identity` — our own hex ids pass straight
+ *     through), matching v1 exactly.
+ *   - a ROOT span's `parentSpanId` is OMITTED from the wire object entirely
+ *     (no key at all) rather than v1's explicit `""` — both spellings mean
+ *     "no parent" per the OTLP proto3-JSON mapping (proto3 JSON drops
+ *     zero-value/unset fields by default); `src/test/otel.test.ts` asserts
+ *     `undefined`, not `""`, for a root span now.
+ *   - extra fields the real exporter adds that v1 never had (`flags`,
+ *     `traceState`, `droppedAttributesCount`, `droppedEventsCount`,
+ *     `droppedLinksCount`, `links: []`) are additive and harmless — nothing
+ *     downstream reads a fixed field LIST, only named fields.
+ *
+ * SPANS ONLY (from THIS module's own per-run exporter). No `resourceLogs`.
+ * Metrics are now real (see `otel_metrics.ts`) but live on their own
+ * PROCESS-scoped pipeline with their own real `@opentelemetry/sdk-metrics`
+ * temporality/aggregation handling — never hand-rolled, and never mixed into
+ * this module's `resourceSpans` payload.
  *
  * EXPLICIT CONFIG ONLY. Activation requires `observability.otel.endpoint` in
  * the config file. This module NEVER reads `OTEL_EXPORTER_OTLP_ENDPOINT` or
- * any other ambient exporter variable: an unrelated shell variable inherited
- * from a CI image or a coworker's dotfiles must not be able to turn a repo's
- * telemetry egress on. (`SPF_CLAUDE_CMD` is not a precedent for the opposite:
- * that variable is SPF-namespaced and only redirects a LOCAL subprocess — it
- * moves no data off the machine.)
+ * any other ambient exporter variable AS AN ACTIVATION SWITCH: an unrelated
+ * shell variable inherited from a CI image or a coworker's dotfiles must not
+ * be able to turn a repo's telemetry egress on. `observability.otel.
+ * allow_env` (see `data_types.ts`'s `OTelConfigSchema`) is the one narrow,
+ * opt-in exception: when `true` AND the block is ALREADY active (`endpoint`
+ * set), `OTEL_EXPORTER_OTLP_ENDPOINT`/`OTEL_EXPORTER_OTLP_HEADERS` may
+ * SUPPLEMENT it (an env-injected token in CI, say) — never activate it from
+ * nothing, and config-declared values always win over the env on conflict.
+ * (`SPF_CLAUDE_CMD` is not a precedent for the opposite: that variable is
+ * SPF-namespaced and only redirects a LOCAL subprocess — it moves no data
+ * off the machine.)
  *
  * ATTRIBUTE ALLOWLIST — exfiltration is the top risk here, because
  * `EventRecord.payload` carries the repository's own source code (tool args,
  * result snippets, diffs, prompts, envelope contents, the operator's request
  * text). The allowlist, in full: phase name/kind/owner/status/seq/attempt,
- * chain name, adw_id, agent name/model/coding_agent, gate name + passed +
- * violation COUNT, token counts (UsageBreakdown fields) + costs, durations
- * (implied by span start/end), and event TYPE. Everything else is excluded by
- * construction, not by filtering:
+ * chain name, adw_id, agent name/model/coding_agent/lora_adapter, gate name +
+ * passed + violation COUNT, token counts (UsageBreakdown fields) + costs,
+ * durations (implied by span start/end), and event TYPE. Everything else is
+ * excluded by construction, not by filtering:
  *   - This module reads `EventRecord.payload` for FINITE NUMBERS ONLY (see
  *     `numOrNull`) and only under known UsageBreakdown/cost keys. A string can
  *     never reach an attribute through the payload path. Do not add a
- *     `stringValue` read from `payload` — that single line is the whole
+ *     string read from `payload` — that single line is the whole
  *     exfiltration bug.
- *   - Agent model/coding_agent come from the typed `AgentConfig` handed to
- *     `recordAgentSession` (config data), NOT from the `agent_start` payload.
+ *   - Agent model/coding_agent/lora_adapter come from the typed `AgentConfig`
+ *     handed to `recordAgentSession` (config data), NOT from the
+ *     `agent_start` payload.
  *   - Tool spans are named from `record.name`'s prefix up to the first ":"
  *     (see `toolSpanName`). The full `record.name` is a HUMAN LABEL built from
  *     real tool arguments (`agent_flue.ts`'s `labelFor` -> "bash: cat
@@ -71,7 +120,9 @@
  * `agent:<phase_id>:<agent>:<n>` for an agent call, `tool:<phase_id>:<event_id>`
  * for a tool call). Determinism means a re-export of the same run lands on the
  * same ids instead of duplicating the trace, and a child span can name its
- * parent's id without waiting for the parent to be emitted.
+ * parent's id without waiting for the parent to be emitted. UNCHANGED in v2:
+ * the SDK is used to ENCODE spans we already fully control, never to
+ * generate their ids.
  * `EventRecord.parent_id` is structurally ALWAYS EMPTY today (SPF's phases are
  * flat siblings; nothing writes nesting), so there is no recorded hierarchy to
  * mine — the parenting above is reconstructed from phase_id + agent-call
@@ -79,9 +130,9 @@
  *
  * PHASE SPANS ARE EMITTED AT PHASE END ONLY. A hung or killed phase is
  * therefore INVISIBLE to the backend (its buffered span events die with it),
- * while SQLite still shows it as `running`. Deliberate v1 trade: streaming a
- * span at phase start would require mutating an already-sent span, which OTLP
- * has no notion of. Recorded here so it is a known gap, not a surprise.
+ * while SQLite still shows it as `running`. Deliberate v1 trade, unchanged:
+ * streaming a span at phase start would require mutating an already-sent
+ * span, which OTLP has no notion of.
  *
  * INBOUND TRACEPARENT. When a valid W3C `traceparent` is present in the
  * environment, its trace-id becomes this run's trace-id and the run's root
@@ -92,6 +143,37 @@
  * silently (see `parseTraceparent`) — a malformed variable must degrade to
  * "own root", never to an error.
  *
+ * OUTBOUND PROPAGATION (new in v2). `agentCallTraceContext()` hands back the
+ * CURRENTLY OPEN agent call's own trace context (same traceId, same sha256
+ * span id already computed by `openAgentCall`) so a caller can propagate it
+ * onward — `agents.ts`'s `send()` reads it into `AgentRequest.otel`, which
+ * `agent_cc.ts`'s single `spawn()` choke point turns into `TRACEPARENT` +
+ * `ANTHROPIC_CUSTOM_HEADERS` env vars for the `claude` CLI subprocess (see
+ * that module's own header for the verified env var format). This is a
+ * READ of state this exporter already tracks for its own id scheme — it
+ * does not change what gets exported, and it is `null` (a silent no-op)
+ * whenever no agent call is currently open.
+ *
+ * LORA ADAPTER ATTRIBUTE. `loraAdapterFor()` resolves `spf.lora_adapter` —
+ * see its own doc comment for the two zero-config conventions plus the
+ * explicit `AgentConfig.lora_adapter` override, checked in that order. The
+ * attribute is omitted entirely when nothing resolves — never a blind copy
+ * of a non-LoRA model id.
+ *
+ * METRICS FAN-OUT (new in v2). `recordPhase`/`recordGate`/`closeAgentCall`
+ * additionally fan out to an OPTIONAL, PROCESS-scoped `OtelMetrics` handle
+ * (see `otel_metrics.ts`) — `spf.phase.duration`, `spf.gate.result`,
+ * `spf.tokens`, `spf.cost_usd`, `spf.agent.calls`. `resolveOtelExporter`
+ * resolves it once via `otel_metrics.resolveOtelMetrics(cfg)` and holds the
+ * reference; every OTHER call site (`tracer.ts`, `agents.ts`) is BYTE-
+ * IDENTICAL to before metrics existed. The v1 "dropped spans" resource
+ * attribute hack is GONE (a `Resource` is immutable per-exporter-instance in
+ * the real SDK — there is no home for a value that changes after
+ * construction) — dropped-span/dropped-event counts now ride as real
+ * Counters on the metrics pipeline instead, recorded once (same "once, on
+ * the final flush" cadence the warn log already used), with the warn log
+ * itself UNCHANGED as the fallback when metrics are off.
+ *
  * LIFECYCLE (copied from `notify/notifier.ts`'s discipline, with one
  * addition `notify` doesn't need — see RUN-SCOPED CLEANUP below). A
  * module-level LIVE registry holds every exporter this process created;
@@ -133,22 +215,28 @@
  * Spans go into a BOUNDED queue (`MAX_QUEUED_SPANS`, drop-OLDEST) and leave in
  * batches (`BATCH_SPANS`, or `FLUSH_INTERVAL_MS`, whichever comes first) via an
  * UNREF'D timer that can never hold the process open. Dropped spans are
- * counted, reported once as a warn line, and exported as a resource attribute
- * on the final flush so the gap is visible in the backend too. The size
- * trigger schedules a timer rather than flushing inline, which also means a
- * synchronous burst of thousands of events exercises the bound (see the queue
- * test) instead of interleaving sends.
+ * counted and reported once as a warn line (and once as a metric, when one is
+ * configured — see METRICS FAN-OUT above). The size trigger schedules a timer
+ * rather than flushing inline, which also means a synchronous burst of
+ * thousands of events exercises the bound (see the queue test) instead of
+ * interleaving sends.
  *
- * WIRE FORMAT is hand-rolled OTLP/HTTP with a JSON body — no new npm
- * dependency for an optional, lossy projection. The shape that matters:
- * `{resourceSpans:[{resource:{attributes:[KeyValue]},scopeSpans:[{scope,spans:[Span]}]}]}`,
- * every attribute value wrapped in an AnyValue (`{stringValue}`/`{intValue}`/
- * `{doubleValue}`/`{boolValue}`), trace/span ids as lowercase hex strings, and
- * every uint64 nanosecond timestamp AS A STRING (a JSON number would lose
- * precision past 2^53 and backends reject it). `src/test/otel.test.ts` pins
- * this shape against an in-process receiver.
+ * WIRE TRANSPORT is `@opentelemetry/exporter-trace-otlp-http`'s real
+ * `OTLPTraceExporter`, JSON-encoded (its default) against the resolved
+ * `/v1/traces` URL — see the VERIFIED WIRE-SHAPE DIFFERENCES note above for
+ * exactly how its bytes differ from v1's hand-rolled ones.
+ * `keepAlive: false` is passed explicitly: the real Node HTTP agent defaults
+ * `keepAlive: true`, which would hold an open socket past this exporter's own
+ * bounded `drain()` — the same "must never be the reason a `spf` process
+ * lingers" requirement the unref'd flush timer already exists for.
+ * `timeoutMillis: SEND_TIMEOUT_MS` bounds the exporter's own internal
+ * retrying transport (up to 5 attempts, capped by this same deadline across
+ * all of them — verified against `@opentelemetry/otlp-exporter-base`'s
+ * `RetryingTransport` source) to the same budget the old hand-rolled
+ * `AbortController` enforced.
  */
-import type { AgentConfig, EventRecord, GateReport, OTelConfig, Phase, SFConfig } from "./data_types.ts";
+import { type AgentConfig, type EventRecord, type GateReport, type OTelConfig, type Phase, type SFConfig } from "./data_types.ts";
+import { type OtelMetrics } from "./otel_metrics.ts";
 /** trace-id = first 32 hex of sha256(adw_id). Bespoke convention — see the header. */
 export declare function traceIdFor(adwId: string): string;
 /** span-id = first 16 hex of sha256(key), where key is a phase_id or a synthetic child key. */
@@ -186,12 +274,7 @@ export declare function resolveTracesUrl(endpoint: string): string;
  * both are places a credential is routinely smuggled into a URL.
  */
 export declare function endpointLabel(endpoint: string): string;
-/**
- * ISO-8601 -> uint64 nanoseconds AS A STRING (see WIRE FORMAT). Unparseable,
- * missing, or pre-epoch input falls back to `fallbackMs`, because a span with
- * a nonsense timestamp is rejected wholesale by most backends while a span
- * with an approximate one is still useful.
- */
+/** ISO-8601 -> uint64 nanoseconds AS A STRING. Unparseable, missing, or pre-epoch input falls back to `fallbackMs`. Kept as its own public, string-returning helper — pinned by tests since before the SDK swap. */
 export declare function nanosFromIso(iso: string | null | undefined, fallbackMs?: number): string;
 /**
  * The safe half of a `tool_call` event's name. `record.name` for a tool call is
@@ -208,6 +291,28 @@ export declare function toolSpanName(eventName: string | undefined | null): stri
  * `observability.otel` ever reaches a log.
  */
 export declare function redact(message: string, secrets: Array<string | undefined>): string;
+/**
+ * `spf.lora_adapter` — the served LoRA adapter name for this agent's model,
+ * when one can be determined. Checked in order, first match wins:
+ *   1. `agent.lora_adapter` (explicit config) — set once per agent, the
+ *      unambiguous source of truth an operator can always fall back to.
+ *   2. `provider/base:adapter` — an explicit adapter suffix after the LAST
+ *      ":" in the model id (e.g. `vllm/nemotron-base:my-lora` -> `my-lora`).
+ *   3. `provider/adapter-name` — no ":" in the model id, but the id itself
+ *      contains "-lora-" (case-insensitive) — this org's own vLLM/Switchyard
+ *      served-model naming convention (`k8s/manifests/switchyard/
+ *      configmap-routes.yaml`: "id MUST equal the name= half of the matching
+ *      --lora-modules entry", e.g. `nemotron-lora-placeholder`) — the WHOLE
+ *      model id (minus the `provider/` prefix) IS the adapter name in this
+ *      convention, since vLLM resolves LoRA adapters by served-model name,
+ *      not by a base-model-plus-suffix split.
+ * No match on any of the three -> `null`, and the attribute is omitted
+ * entirely — never a blind copy of a non-LoRA model id.
+ */
+export declare function loraAdapterFor(agent: {
+    model: string;
+    lora_adapter?: string | null;
+}): string | null;
 export interface OtelExporterInit {
     /** The validated `observability.otel` block. Its presence IS the activation switch. */
     cfg: OTelConfig;
@@ -218,6 +323,8 @@ export interface OtelExporterInit {
     log?: (message: string) => void;
     /** Injectable for tests; defaults to `process.env`. Only ever read for `traceparent`. */
     env?: NodeJS.ProcessEnv;
+    /** The process-scoped metrics handle (see `otel_metrics.ts`), or `null` when metrics are off/unconfigured. Injectable for tests. */
+    metrics?: OtelMetrics | null;
 }
 export declare class OtelExporter {
     private readonly cfg;
@@ -226,10 +333,14 @@ export declare class OtelExporter {
     private readonly serviceName;
     private readonly url;
     private readonly log;
+    private readonly metrics;
     private readonly traceId;
     /** "" unless an inbound traceparent parented this run — see INBOUND TRACEPARENT. */
     private readonly rootParentSpanId;
     private readonly rootSpanId;
+    private readonly resource;
+    private readonly scope;
+    private readonly spanExporter;
     private queue;
     private dropped;
     private droppedEvents;
@@ -248,7 +359,7 @@ export declare class OtelExporter {
      * nothing will ever drain.
      */
     private emittedPhases;
-    /** `<phase_id><agent>` -> the open agent call, for closing it and parenting tool spans. */
+    /** `<phase_id> <agent>` -> the open agent call, for closing it and parenting tool spans. */
     private openAgents;
     /** How many times an agent has been called in a phase, so a retry gets its own span id. */
     private agentCalls;
@@ -308,6 +419,17 @@ export declare class OtelExporter {
      * the guard is why that is harmless.
      */
     recordSessionFinish(ok: boolean): void;
+    /**
+     * The currently-open agent call's trace context — `null` when otel has no
+     * agent call open for this phase+agent pair right now (agent_start hasn't
+     * fired, or already closed). `agents.ts`'s `send()` reads this into
+     * `AgentRequest.otel`; a `null` here just means that field stays unset, a
+     * plain no-op for every backend that doesn't propagate it.
+     */
+    agentCallTraceContext(phaseId: string, agentName: string): {
+        traceparent: string;
+        spanId: string;
+    } | null;
     /** Queued spans and spans/events dropped so far. For tests and diagnostics. */
     stats(): {
         queued: number;
@@ -316,9 +438,11 @@ export declare class OtelExporter {
     };
     /**
      * The exact JSON body the next flush would POST, without sending or
-     * draining. This is the seam `src/test/otel.test.ts` uses to prove the
-     * allowlist holds — the assertion is on the literal bytes, so any future
-     * attribute that leaks a payload fails a test rather than a review.
+     * draining — via the SAME `JsonTraceSerializer` the real exporter uses
+     * internally, so this is not a second, possibly-diverging encoding path.
+     * This is the seam `src/test/otel.test.ts` uses to prove the allowlist
+     * holds — the assertion is on the literal bytes, so any future attribute
+     * that leaks a payload fails a test rather than a review.
      */
     pendingJson(): string;
     private enqueue;
@@ -327,7 +451,11 @@ export declare class OtelExporter {
     /**
      * Send whatever is queued. Never throws, never rejects: a failed export is a
      * single redacted log line and a swallowed error, because the alternative is
-     * an observability feature that can fail a run.
+     * an observability feature that can fail a run. `OTLPTraceExporter.export()`
+     * itself already never throws and always calls its callback exactly once
+     * (verified against `@opentelemetry/otlp-exporter-base`'s
+     * `OTLPExportDelegate.export()` source) — the try/catch here is belt-and-
+     * braces for that contract, not a load-bearing guard.
      */
     flush(isFinal?: boolean): Promise<void>;
     /**
@@ -336,6 +464,7 @@ export declare class OtelExporter {
      * `session.ts`'s signal handler (with a tighter budget there).
      */
     drain(budgetMs?: number): Promise<void>;
+    private makeSpan;
     private emitRootSpan;
     private agentKey;
     private openAgentCall;
@@ -351,7 +480,6 @@ export declare class OtelExporter {
     private emitToolSpan;
     private bufferSpanEvent;
     private takeBufferedEvents;
-    private payloadFor;
     private logFailureOnce;
 }
 /**
@@ -361,6 +489,12 @@ export declare class OtelExporter {
  * the default for every repo that has not configured an endpoint, and no
  * environment variable can change that (see EXPLICIT CONFIG ONLY).
  *
+ * Also resolves (once per process — see `otel_metrics.ts`'s own singleton
+ * guard) the shared, PROCESS-scoped `OtelMetrics` handle and holds a
+ * reference on the exporter, so `recordPhase`/`recordGate`/`closeAgentCall`
+ * can fan out to it without any OTHER call site (`tracer.ts`, `agents.ts`)
+ * needing to know metrics exist at all.
+ *
  * Registered under `opts.adwId` — the RESOLVED id (`session.ensure`'s own
  * `id`, never a caller's possibly-null `ctx.adw_id`) — which is exactly the
  * key `releaseOtelExporter` below looks it up by. A second registration