@gr8ful/spf 0.17.0 → 0.19.0

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