@gr8ful/spf 0.4.0 → 0.5.0

package/dist/core/otel.d.ts

@@ -0,0 +1,352 @@
+/**
+ * OpenTelemetry span export (v1): 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.
+ *
+ * WHAT THIS IS NOT. It is not a second source of truth and it is not in any
+ * control path. `tracer.ts` (files + SQLite, synchronous) remains THE record;
+ * this module is a tail-call fan-out off its write methods. Export can never
+ * affect a phase, a gate, or a run outcome — "agent proposes, code disposes"
+ * is untouched because export cannot dispose of anything. Nothing in here may
+ * 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.
+ *
+ * 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.)
+ *
+ * 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:
+ *   - 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
+ *     exfiltration bug.
+ *   - Agent model/coding_agent 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
+ *     src/secret.ts") and must never be exported verbatim.
+ *   - `Phase.error` is NOT exported. It is an agent- and repo-derived string.
+ *     A failed phase span carries status ERROR with no message.
+ *   - `tracer.sessionRequest`, `tracer.envelopeRow`, `tracer.processStart/End`
+ *     have deliberately NO fan-out: the operator's request text, envelope
+ *     contents, and pids are all outside the allowlist. Do not add one.
+ *
+ * SPAN MODEL. One run (adw_id) = one trace. Root span = the run. Each phase =
+ * a child span of the root, using `runner.ts`'s real `started_at`/`ended_at`.
+ * Each agent call (`agent_start`..`agent_end`, with its UsageBreakdown) = a
+ * CHILD span of its phase: a phase-only tree cannot answer "which agent call
+ * burned the tokens", which is the question this feature exists for.
+ * `tool_call` events (they carry real timing) = child spans of the open agent
+ * call where attributable, else of the phase. `handoff`/`error` become a span
+ * EVENT on the phase span, with allowlisted attributes only. `gate_pass`/
+ * `gate_fail` do NOT (see `recordGate` below, which carries the structured
+ * verdict instead). `log` is dropped outright — a console line is redundant
+ * with the phase span itself and would only crowd out `handoff`/`error` in
+ * the per-phase event cap (see BACKPRESSURE and `MAX_EVENTS_PER_SPAN`). Any
+ * event type not named above is dropped, fail-closed, by `recordEvent`.
+ *
+ * IDS ARE A BESPOKE CONVENTION, documented so nobody mistakes it for the OTel
+ * SDK's random-id behavior: trace-id = first 32 hex of sha256(adw_id),
+ * span-id = first 16 hex of sha256(a stable key — `phase_id` for a phase,
+ * `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.
+ * `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
+ * bracketing, and that is the only reason it needs reconstructing at all.
+ *
+ * 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.
+ *
+ * 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
+ * span is parented under its span-id, so an SPF run joins the CI trace that
+ * launched it instead of hanging as an orphan root. Reading `traceparent` is
+ * NOT ambient activation: with no `observability.otel` config, nothing is
+ * constructed and nothing is sent, traceparent or not. Garbage is rejected
+ * silently (see `parseTraceparent`) — a malformed variable must degrade to
+ * "own root", never to an error.
+ *
+ * LIFECYCLE (copied from `notify/notifier.ts`'s discipline). A module-level
+ * LIVE registry holds every exporter this process created; `flushAll()` is
+ * awaited in `src/cli/index.ts`'s existing `finally` block next to
+ * `notify.flushAll()`, AND `session.ts`'s signal handler runs a bounded,
+ * timeout-capped drain before its `process.exit(128+n)` (notify does NOT do
+ * that second one today — its in-flight webhooks are dropped on SIGTERM; only
+ * the otel path is fixed here, on purpose, to keep this change to one seam).
+ * Send failures log ONE line for the life of the exporter, with the endpoint
+ * and every header VALUE redacted, and are then swallowed.
+ *
+ * BACKPRESSURE. `tracer.event()` fires per tool call on a hot path, so raw
+ * promise-per-span fire-and-forget is a memory bug, not a style choice.
+ * 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.
+ *
+ * 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.
+ */
+import type { AgentConfig, EventRecord, GateReport, OTelConfig, Phase, SFConfig } from "./data_types.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. */
+export declare function spanIdFor(key: string): string;
+export interface TraceParent {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+}
+/**
+ * Strict W3C `traceparent` parse: `00-<32 hex>-<16 hex>-<2 hex>`, lowercase,
+ * exact lengths, neither id all-zero. Anything else — a wrong version, an
+ * uppercase digest, a truncated id, an empty string, unset — returns null and
+ * the run keeps its own root. Never throws, never logs: a malformed CI
+ * variable is not this module's problem to report.
+ */
+export declare function parseTraceparent(value: string | undefined | null): TraceParent | null;
+/**
+ * The two env vars CI systems actually set. Reading them is not activation —
+ * see INBOUND TRACEPARENT in the header.
+ */
+export declare function inboundTraceparent(env?: NodeJS.ProcessEnv): TraceParent | null;
+/**
+ * The configured endpoint is used AS GIVEN when it already names a path — the
+ * operator's URL is not ours to rewrite. A bare origin (`http://host:4318`,
+ * or a trailing "/") gets the standard OTLP/HTTP traces path appended, because
+ * that is the one guess with a single right answer. Returns the input
+ * unchanged if it does not parse as a URL; the config schema rejects those
+ * first, so this is only belt-and-braces for direct callers.
+ */
+export declare function resolveTracesUrl(endpoint: string): string;
+/**
+ * A printable form of the endpoint for `spf doctor`: origin + path only.
+ * Userinfo (`https://user:token@host/...`) and the query string are dropped —
+ * 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.
+ */
+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
+ * a human label built FROM THE TOOL'S ARGUMENTS ("bash: cat src/secret.ts",
+ * "read: /etc/hosts"); only the part before the first ":" is the tool's own
+ * identity. Also clipped and character-restricted so a hand-rolled event name
+ * can't smuggle a payload through as a span name.
+ */
+export declare function toolSpanName(eventName: string | undefined | null): string;
+/**
+ * Redact every secret from a log line. The endpoint and each header VALUE are
+ * passed in; `fetch` failures routinely embed the URL they attempted, and a
+ * proxy error can echo a header. One-line rule: nothing configured under
+ * `observability.otel` ever reaches a log.
+ */
+export declare function redact(message: string, secrets: Array<string | undefined>): string;
+export interface OtelExporterInit {
+    /** The validated `observability.otel` block. Its presence IS the activation switch. */
+    cfg: OTelConfig;
+    adwId: string;
+    /** The CLI chain name, from `session.ts` — allowlisted, config-declared. */
+    chainName: string;
+    /** Injectable for tests; defaults to stderr, exactly like `Notifier`'s. */
+    log?: (message: string) => void;
+    /** Injectable for tests; defaults to `process.env`. Only ever read for `traceparent`. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class OtelExporter {
+    private readonly cfg;
+    private readonly adwId;
+    private readonly chainName;
+    private readonly serviceName;
+    private readonly url;
+    private readonly log;
+    private readonly traceId;
+    /** "" unless an inbound traceparent parented this run — see INBOUND TRACEPARENT. */
+    private readonly rootParentSpanId;
+    private readonly rootSpanId;
+    private queue;
+    private dropped;
+    private droppedEvents;
+    private warnedDrops;
+    private loggedFailure;
+    private timer;
+    private timerDelay;
+    private pending;
+    /** Span events buffered until their phase span exists. Key "" = the root run span. */
+    private bufferedEvents;
+    /**
+     * Phases whose span has already gone out. Events DO arrive after a phase
+     * span is emitted — `run.finish()`'s `not_accepted` error names the last
+     * phase — and a span already on the wire cannot grow an event, so those are
+     * re-homed onto the root run span instead of accumulating in a buffer that
+     * nothing will ever drain.
+     */
+    private emittedPhases;
+    /** `<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;
+    /** agent name -> config metadata, from `recordAgentSession` (typed config, never a payload). */
+    private agentMeta;
+    private runStartedAtMs;
+    private rootEmitted;
+    constructor(init: OtelExporterInit);
+    /** `tracer.sessionStart` — only the run's clock; the engineer name is not allowlisted. */
+    recordSessionStart(startedAtIso?: string | null): void;
+    /**
+     * `tracer.event` — the one hot seam. Dispatch, in full:
+     *   phase_start/phase_end -> ignored (the phase span's own boundaries say it)
+     *   agent_start           -> open an agent call
+     *   agent_end             -> emit the agent-call child span, with usage
+     *   tool_call             -> emit a tool child span (real timing, safe name)
+     *   gate_pass/gate_fail   -> ignored HERE; `recordGate` carries the structured
+     *                            GateReport for the same gate, and doubling it
+     *                            would put two span events on every gate
+     *   handoff/error         -> a span event buffered onto the phase span
+     *   log                   -> dropped: a console line adds nothing beyond
+     *                            `spf.event.type`/`name`, and buffering it would
+     *                            crowd `handoff`/`error` out of the per-phase cap
+     *                            (see MAX_EVENTS_PER_SPAN)
+     *   anything else          -> dropped. The dispatch is fail-closed on purpose:
+     *                            a future EventRecord.type whose `name` is
+     *                            derived from agent output must not fall through
+     *                            to export by default.
+     */
+    recordEvent(record: EventRecord, eventId: string, tsIso: string): void;
+    /**
+     * `tracer.phaseUpsert` — the phase's END is the emit point (see PHASE SPANS
+     * ARE EMITTED AT PHASE END ONLY). The start-of-phase upsert has no
+     * `ended_at` and is skipped, which also makes this idempotent-ish: a
+     * re-upsert of the same finished phase re-emits a span with the SAME id, so
+     * a backend overwrites rather than duplicates.
+     */
+    recordPhase(phase: Phase): void;
+    /**
+     * `tracer.gateRow` — the verdict and its SIZE, never its content. A
+     * violation string quotes the agent's own claim and the repo's files; only
+     * the count crosses the wire.
+     */
+    recordGate(phase: Phase, gate: string, report: GateReport, attempt: number): void;
+    /**
+     * `tracer.agentSessionRow` — the typed source for an agent's model and
+     * backend. Load-bearing, not decoration: it is written BEFORE the
+     * `agent_end` event (see `agents.ts`), which is what lets the agent-call
+     * span carry model/coding_agent without ever reading the `agent_start`
+     * payload. `session_id` is NOT exported (it is a coding-agent handle, not a
+     * measure).
+     */
+    recordAgentSession(agent: AgentConfig): void;
+    /**
+     * `tracer.sessionFinish` — emits the root run span exactly once. Called
+     * twice on some paths (a failing phase finalizes, then `finish()` does), and
+     * the guard is why that is harmless.
+     */
+    recordSessionFinish(ok: boolean): void;
+    /** Queued spans and spans/events dropped so far. For tests and diagnostics. */
+    stats(): {
+        queued: number;
+        dropped: number;
+        droppedEvents: number;
+    };
+    /**
+     * 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.
+     */
+    pendingJson(): string;
+    private enqueue;
+    private schedule;
+    private track;
+    /**
+     * 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.
+     */
+    flush(isFinal?: boolean): Promise<void>;
+    /**
+     * Drain: flush, then await anything already in flight, all under one hard
+     * budget. Never throws. Called from the CLI's `finally` and from
+     * `session.ts`'s signal handler (with a tighter budget there).
+     */
+    drain(budgetMs?: number): Promise<void>;
+    private emitRootSpan;
+    private agentKey;
+    private openAgentCall;
+    private closeAgentCall;
+    /**
+     * Tool spans carry REAL elapsed time (the tracker records started_at/ended_at
+     * per call), which is the whole reason they are spans and not span events.
+     * Parented under the open agent call when one is attributable — the agent
+     * name comes from `payload.agent`, and it is used ONLY as a map lookup key,
+     * never written to an attribute, so an unexpected value yields "no parent
+     * found" rather than an exported string.
+     */
+    private emitToolSpan;
+    private bufferSpanEvent;
+    private takeBufferedEvents;
+    private payloadFor;
+    private logFailureOnce;
+}
+/**
+ * Build an exporter from `cfg.observability.otel`, or `null` when it is
+ * absent — the same optional-dependency shape as `resolveNotifier`, so every
+ * call site is `otel?.record...()` and never a conditional branch. `null` is
+ * the default for every repo that has not configured an endpoint, and no
+ * environment variable can change that (see EXPLICIT CONFIG ONLY).
+ */
+export declare function resolveOtelExporter(cfg: SFConfig, opts: {
+    adwId: string;
+    chainName: string;
+    log?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+}): OtelExporter | null;
+/**
+ * Drain every exporter this process created, under one budget. A no-op when
+ * otel is unconfigured. Called from `src/cli/index.ts`'s `finally` (next to
+ * `notify.flushAll()`) and, with a tighter budget, from `session.ts`'s signal
+ * handler. Never throws.
+ */
+export declare function flushAll(budgetMs?: number): Promise<void>;
+/** Tests only: forget every registered exporter so cases cannot leak into each other. */
+export declare function resetLiveForTest(): void;