@runtypelabs/flue-otel 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,576 @@
+import { Tracer } from '@opentelemetry/api';
+
+/**
+ * The Flue observation surface this package reads, declared structurally.
+ *
+ * ## Why these are hand-declared rather than imported from `@flue/runtime`
+ *
+ * Two reasons, and the second is the load-bearing one.
+ *
+ * 1. `@flue/runtime` is a PEER dependency with no dev counterpart: its tree is
+ *    ~43 packages, and pulling it into the root lockfile for type resolution
+ *    alone is the cost this monorepo already refuses for `examples/flue-persona`
+ *    (root `CLAUDE.md`, "examples/* is deliberately NOT a pnpm workspace").
+ *
+ * 2. The package supports BOTH the 1.x and 2.x lines from one entry point, and
+ *    their declarations are not the same type. 1.x has `run_start`/`run_end`,
+ *    envelope `runId`/`dispatchId`, and `FlueObservationDetail.toolType`; 2.x
+ *    removes all of those and adds `toolcall_delta`, the `submission_*` family,
+ *    and `FlueErrorInfo.meta`/`.stack`. Importing EITHER line's types would make
+ *    the compiler enforce a shape the other line does not have. What this
+ *    package actually consumes is the INTERSECTION — the observation plane Flue
+ *    publishes as stable — so that is what is declared here.
+ *
+ * ## What is safe to read
+ *
+ * Flue's published stability boundary (flueframework.com/docs/reference/events)
+ * covers the event type names, the envelope/correlation fields, and the
+ * normalized `turn_request` / `turn` / `tool_*` / `task` / `operation` /
+ * `compaction` / `log` / `submission_settled` payloads. It EXPLICITLY excludes
+ * `AgentMessage`, which appears on `message_start` / `message_end` /
+ * `turn_messages` / `agent_end` — so none of those four are read here, and the
+ * type below does not even name the field. That exclusion is why the stock
+ * projection survived the 1.x → 2.x rewrite unchanged, and it is the same
+ * reason this one will.
+ *
+ * Fields the two lines disagree on are declared OPTIONAL and probed at runtime
+ * (`compat.ts`), never version-compared.
+ */
+/** Correlation fields stamped onto every delivered observation. */
+interface FlueEventEnvelope {
+    /** Durable event-format version. `3` on both supported lines. */
+    v?: number;
+    eventIndex?: number;
+    timestamp?: string;
+    instanceId?: string;
+    submissionId?: string;
+    agentName?: string;
+    conversationId?: string;
+    session?: string;
+    parentSession?: string;
+    taskId?: string;
+    harness?: string;
+    operationId?: string;
+    turnId?: string;
+}
+/** Token counts and cost for one model turn. Byte-identical on both lines. */
+interface FluePromptUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+/** The non-content half of a model request. */
+interface FlueModelRequestInfo {
+    providerId?: string;
+    providerName?: string;
+    requestedModel?: string;
+    api?: string;
+    serverAddress?: string;
+    serverPort?: number;
+    reasoningLevel?: string;
+    maxTokens?: number;
+    temperature?: number;
+    contextCompacted?: true;
+}
+/**
+ * The request's payload half. Only `tools` is read, and only for its PRESENCE:
+ * `runtype.tools.reported` is the assertion "my tool set is complete", which
+ * needs to know the array exists, not what is in it. Message content is
+ * deliberately untouched in this release — see the README's content section.
+ */
+interface FlueModelRequestInput {
+    tools?: unknown[];
+}
+interface FlueModelRequest extends FlueModelRequestInfo {
+    input?: FlueModelRequestInput;
+}
+interface FlueModelResponse {
+    responseId?: string;
+    responseModel?: string;
+    usage?: FluePromptUsage;
+    finishReason?: string;
+    /** 2.x only. The provider's raw finish value before normalization. */
+    providerFinishReason?: string;
+    error?: FlueErrorInfo;
+}
+/**
+ * Classified error details on a live observation.
+ *
+ * `stack` is declared so the type is honest about what arrives, and is NEVER
+ * read: it exposes filesystem paths and deployment layout, which is exactly the
+ * class of value a vendor package landing in a healthcare stack must not put on
+ * a wire the customer did not opt into. Flue's own durable serializers drop it
+ * for the same reason.
+ */
+interface FlueErrorInfo {
+    type?: string;
+    name?: string;
+    message?: string;
+    stack?: string;
+    meta?: Record<string, unknown>;
+}
+/** 1.x-only implementation-class axis; absent on 2.x. */
+type FlueToolSemanticType = 'function' | 'extension' | 'datastore';
+/** Who INITIATED a tool call. Present on both lines. NOT a tool class. */
+type FlueToolOrigin = 'model' | 'caller' | 'framework' | 'adapter';
+/**
+ * The per-observation detail sidecar. Every field is optional on both lines;
+ * `toolType` exists only on 1.x, which is what `compat.ts` probes for.
+ */
+interface FlueObservationDetail {
+    origin?: FlueToolOrigin;
+    toolType?: FlueToolSemanticType;
+    toolCallId?: string;
+    errorInfo?: FlueErrorInfo;
+}
+/**
+ * The event variants this package acts on. Every other variant Flue emits is
+ * ignored, which is why they are not declared: an unhandled `type` falls
+ * through the projection's switch untouched.
+ */
+type FlueEventVariant = {
+    type: 'operation_start';
+    operationId: string;
+    operationKind: string;
+} | {
+    type: 'operation';
+    operationId: string;
+    operationKind: string;
+    durationMs?: number;
+    isError?: boolean;
+    error?: unknown;
+    usage?: FluePromptUsage;
+} | {
+    type: 'task_start';
+    taskId: string;
+    prompt?: string;
+    agent?: string;
+} | {
+    type: 'task';
+    taskId: string;
+    agent?: string;
+    isError?: boolean;
+    result?: unknown;
+} | {
+    type: 'compaction_start';
+    reason?: string;
+    estimatedTokens?: number;
+} | {
+    type: 'compaction';
+    isError?: boolean;
+    error?: unknown;
+    usage?: FluePromptUsage;
+} | {
+    type: 'turn_request';
+    turnId: string;
+    purpose?: string;
+    request: FlueModelRequest;
+} | {
+    type: 'turn';
+    turnId: string;
+    purpose?: string;
+    durationMs?: number;
+    request?: FlueModelRequestInfo;
+    response: FlueModelResponse;
+    isError?: boolean;
+} | {
+    type: 'tool_start';
+    toolName: string;
+    toolCallId: string;
+} | {
+    type: 'tool';
+    toolName: string;
+    toolCallId: string;
+    isError?: boolean;
+    result?: unknown;
+    durationMs?: number;
+} | {
+    type: 'submission_settled';
+    submissionId: string;
+    outcome: string;
+} | {
+    type: string;
+};
+/** One delivered observation: an event, its envelope, and its detail sidecar. */
+type FlueObservation = FlueEventVariant & FlueEventEnvelope & FlueObservationDetail;
+/**
+ * Context handed to `observe()` alongside each observation. Only its presence
+ * matters here — the fields this package needs all live on the envelope.
+ */
+interface FlueEventContext {
+    readonly id?: string;
+    readonly agentName?: string;
+}
+/** W3C trace context offered by the host on a detached execution. */
+interface FlueTraceCarrier {
+    traceparent: string;
+    tracestate?: string;
+}
+/**
+ * The operation the interceptor wraps. `coordinator` exists on 2.x only; the
+ * open arm makes an unknown future kind fall through rather than crash.
+ */
+type FlueExecutionOperation = {
+    type: 'agent';
+    operationId: string;
+    operationKind?: string;
+} | {
+    type: 'model';
+    turnId: string;
+} | {
+    type: 'tool';
+    toolCallId: string;
+    toolName?: string;
+} | {
+    type: 'task';
+    taskId: string;
+} | {
+    type: 'coordinator';
+    phase?: string;
+} | {
+    type: string;
+};
+interface FlueExecutionContext {
+    eventContext?: FlueEventContext;
+    instanceId?: string;
+    submissionId?: string;
+    agentName?: string;
+    conversationId?: string;
+    harness?: string;
+    session?: string;
+    operationId?: string;
+    turnId?: string;
+    taskId?: string;
+    traceCarrier?: FlueTraceCarrier;
+}
+type FlueObservationSubscriber = (observation: FlueObservation, ctx: FlueEventContext) => void | Promise<void>;
+type FlueExecutionInterceptor = <T>(operation: FlueExecutionOperation, ctx: FlueExecutionContext, next: () => Promise<T>) => Promise<T>;
+/**
+ * The third-party instrumentation contract, identical on both supported lines.
+ * `instrument(instrumentation)` from the bare `@flue/runtime` barrel installs
+ * one of these.
+ */
+interface FlueInstrumentation {
+    key?: symbol;
+    observe: FlueObservationSubscriber;
+    interceptor: FlueExecutionInterceptor;
+    dispose(): void | Promise<void>;
+}
+
+/**
+ * Flue observations → span intents. PURE: no `@opentelemetry/api`, no clock, no
+ * I/O. `spans.ts` is the only module that touches a `Tracer`.
+ *
+ * The split is what makes the emit contract testable. Every attribute this
+ * package puts on the wire is decided here, from a synthesized observation, and
+ * asserted in `tests/projection.test.ts` against both the 1.x and 2.x shapes —
+ * so a mapping regression is a unit-test failure rather than something only a
+ * live export against a real agent would show.
+ *
+ * ## What is emitted, and why exactly this
+ *
+ * The read side is `packages/execution-ingest/src/otel-trace-ingest-service.ts`.
+ * What it reads is this module's specification, so each choice below is a
+ * consequence of a rule stated there:
+ *
+ * - **`invoke_agent` is the ENVELOPE and there is exactly one per trace.**
+ *   `selectEnvelopeSpan` takes the first ARRAY-order `invoke_agent` span, and
+ *   array order is exporter-controlled. A second one — which stock
+ *   `@flue/opentelemetry` opens for every `task` delegation — is therefore a
+ *   coin flip over which invocation bounds the run, whose status closes it, and
+ *   (via `resolveTraceAgentId`'s span-level source) which agent it files under.
+ *   So a delegated sub-agent gets a `flue.task` span with NO
+ *   `gen_ai.operation.name`, and the delegation itself is reported where it
+ *   actually belongs: as the `execute_tool` span for the `task` tool, typed
+ *   `subagent`. Stock does the opposite — it suppresses that tool span and
+ *   opens the nested `invoke_agent` — which is the one place this projection
+ *   deliberately diverges from it.
+ *
+ * - **Usage is rolled up ONTO the envelope, summed from `turn` leaves.**
+ *   `projectUsage` prefers an envelope roll-up precisely because a
+ *   `BatchSpanProcessor` flushes children before their parent, so the batch
+ *   carrying the terminal may hold no model calls at all. Flue's own docs say
+ *   to sum model-turn leaves rather than the `operation` roll-up, because
+ *   nested duration and usage values overlap. Both point the same way: sum
+ *   `turn.response.usage`, put the total on `invoke_agent`.
+ *
+ * - **The envelope carries the model.** Stock puts none there, which left the
+ *   envelope's log record showing no model at all; the server-side normalizer
+ *   now lifts one, but only for traces it recognizes as Flue's. Emitting it
+ *   directly is F1 and costs one attribute. Both ids come off the SAME turn, so
+ *   the request-model fallback can never price one call's served model against
+ *   another's requested one.
+ *
+ * - **`runtype.turn.index` / `runtype.iteration` ARE derived here, and are not
+ *   derivable at ingest.** The server-side normalizer deliberately refuses
+ *   them: Flue puts no absolute ordinal on the wire, and ranking opaque turn
+ *   ids ranks whatever the export batch happened to carry — a five-turn run
+ *   whose closing batch holds two turns would be recorded as two iterations.
+ *   In-process the count is exact, because we see every `turn_request` in
+ *   order. This is the clearest thing this package buys that a normalizer
+ *   structurally cannot.
+ */
+
+/** Attribute values OTLP can carry. Deliberately narrower than OTel's type. */
+type SpanAttributes = Record<string, string | number | boolean | string[]>;
+/** Where a span sits relative to the process boundary. */
+type ProjectedSpanKind = 'internal' | 'client';
+interface OpenSpanIntent {
+    kind: 'open';
+    /** Stable identity for the span; the driver keys its live-span map on it. */
+    ref: string;
+    name: string;
+    spanKind: ProjectedSpanKind;
+    /**
+     * The span this one nests under, when the projection knows it. Absent means
+     * "use whatever is active" — which, inside Flue's interceptor, is the
+     * enclosing span, so the driver's fallback repairs chains the correlation
+     * fields cannot express (a task nested inside another task, most notably).
+     */
+    parentRef?: string;
+    /** Flue's own event timestamp, ISO-8601. Spans stay on the runtime's clock. */
+    startTime?: string;
+    attributes: SpanAttributes;
+    /**
+     * Drop this span entirely rather than start it as the root of a new trace.
+     *
+     * Set on framework bookkeeping that only means anything INSIDE a run —
+     * `flue.operation shell` and `flue.compaction`. Both can occur outside one:
+     * `session.shell()` and `session.compact()` are public host APIs, and Flue
+     * intercepts only `prompt` and `skill` operations, so neither has a parent
+     * span or an active context to inherit.
+     *
+     * Started as a root, such a span becomes the ONLY span in its trace — and
+     * ingest's `selectEnvelopeSpan` falls back to the first parentless span when
+     * a trace carries no agent invocation, so it would be read as the envelope
+     * of a run and write a phantom execution row for every host-initiated shell
+     * command. This is the same reasoning `index.ts` applies to `coordinator`
+     * operations, applied to the other two paths that reach the same state.
+     */
+    requiresParent?: boolean;
+}
+interface UpdateSpanIntent {
+    kind: 'update';
+    ref: string;
+    attributes: SpanAttributes;
+}
+interface CloseSpanIntent {
+    kind: 'close';
+    ref: string;
+    endTime?: string;
+    /**
+     * Present when the span failed. Carries the error TYPE and the exception
+     * class NAME only — never a message and never a stack. Both are content: a
+     * provider error message routinely quotes the prompt back, and a stack
+     * exposes filesystem paths and deployment layout. This release emits no
+     * content at all, so neither is read.
+     */
+    error?: {
+        type: string;
+        exceptionType?: string;
+    };
+}
+type SpanIntent = OpenSpanIntent | UpdateSpanIntent | CloseSpanIntent;
+interface FlueProjectionOptions {
+    /**
+     * Runtype agent id per Flue agent name, e.g. `{ triage: 'agent_01j...' }`.
+     *
+     * Stamped on the ENVELOPE span as `runtype.agent.id` — the ratified second
+     * attribution placement, for the one shape a `Resource` cannot express: a
+     * single process running several Runtype agents. A single-agent deployment
+     * should set the resource attribute instead (see
+     * {@link runtypeFlueResourceAttributes} and the README recipe), which the
+     * ingest reader prefers.
+     *
+     * A delegated sub-agent is deliberately NOT attributed separately: its work
+     * runs inside the delegating agent's trace, and one trace is one execution.
+     */
+    agents?: Record<string, string>;
+}
+/**
+ * Resource attributes for the customer's `Resource`. Exported rather than set
+ * internally because this package owns none of the SDK: the provider, the
+ * processor, the exporter and the resource are all the application's, and a
+ * library that reached into them would fight whatever the customer already runs.
+ */
+declare function runtypeFlueResourceAttributes(resource?: {
+    agentId?: string | null;
+}): SpanAttributes;
+
+/**
+ * The attribute vocabulary this instrumentation emits: the GenAI semantic
+ * conventions plus Runtype's ratified `runtype.*` extension names.
+ *
+ * ## Why the literals are inlined rather than imported
+ *
+ * The canonical home for the `runtype.*` names is
+ * `packages/shared/src/otlp-runtype-semconv.ts`, and this module is a
+ * CONSUMER of that contract, never a fork of it. But `@runtypelabs/shared` is
+ * `private: true` and is not published to npm, while this package is — so a
+ * runtime import would resolve in the monorepo and fail for every customer who
+ * installs `@runtypelabs/flue-otel` from the registry.
+ *
+ * The discipline that keeps a copy from becoming a fork is
+ * `tests/contract.test.ts`: a DEV-ONLY cross-import that asserts every literal
+ * here is identical to the shared module's. A rename on either side is a red
+ * build, in the same PR, which is the only mechanism that actually holds. It is
+ * the same posture `examples/flue-persona` uses for the unified SSE vocabulary.
+ *
+ * Exact strings are load-bearing: a misspelled attribute fails no build — it
+ * silently empties a column of every ingested run.
+ */
+/**
+ * GenAI semantic-convention attribute names. Mirrors the subset of
+ * `packages/shared/src/gen-ai-semconv.ts` this instrumentation can populate
+ * from Flue's STABLE observation plane.
+ */
+declare const GEN_AI: {
+    readonly operationName: "gen_ai.operation.name";
+    readonly providerName: "gen_ai.provider.name";
+    readonly agentName: "gen_ai.agent.name";
+    readonly conversationId: "gen_ai.conversation.id";
+    readonly requestModel: "gen_ai.request.model";
+    readonly responseModel: "gen_ai.response.model";
+    readonly responseId: "gen_ai.response.id";
+    readonly requestStream: "gen_ai.request.stream";
+    readonly reasoningLevel: "gen_ai.request.reasoning.level";
+    readonly maxTokens: "gen_ai.request.max_tokens";
+    readonly temperature: "gen_ai.request.temperature";
+    readonly finishReasons: "gen_ai.response.finish_reasons";
+    readonly usageInputTokens: "gen_ai.usage.input_tokens";
+    readonly usageOutputTokens: "gen_ai.usage.output_tokens";
+    readonly usageCacheReadTokens: "gen_ai.usage.cache_read.input_tokens";
+    readonly usageCacheCreationTokens: "gen_ai.usage.cache_creation.input_tokens";
+    readonly toolName: "gen_ai.tool.name";
+    readonly toolCallId: "gen_ai.tool.call.id";
+    readonly toolType: "gen_ai.tool.type";
+    readonly conversationCompacted: "gen_ai.conversation.compacted";
+    readonly errorType: "error.type";
+    readonly serverAddress: "server.address";
+    readonly serverPort: "server.port";
+};
+/**
+ * Runtype's extension vocabulary. Placement is part of the contract and the
+ * reader enforces it — see the `RUNTYPE_ATTRIBUTES` doc block in the shared
+ * module for which level each name belongs on.
+ */
+declare const RUNTYPE: {
+    readonly agentId: "runtype.agent.id";
+    readonly schemaVersion: "runtype.schema.version";
+    readonly adapterName: "runtype.adapter.name";
+    readonly adapterVersion: "runtype.adapter.version";
+    readonly executionId: "runtype.execution.id";
+    readonly iteration: "runtype.iteration";
+    readonly stopReason: "runtype.stop_reason";
+    readonly toolsReported: "runtype.tools.reported";
+    readonly toolType: "runtype.tool.type";
+    readonly turnId: "runtype.turn.id";
+    readonly turnIndex: "runtype.turn.index";
+};
+/**
+ * `runtype.tool.type` values — the closed domain that drives display and
+ * grader routing. Mirrors `RUNTYPE_TOOL_TYPES` in the shared module; only the
+ * members this instrumentation can honestly assert are ever emitted (see
+ * `projection.ts`).
+ */
+declare const RUNTYPE_TOOL_TYPES: readonly ["flow", "mcp", "builtin", "custom", "external", "advisor", "subagent", "local", "data_connection", "search"];
+type RuntypeToolType = (typeof RUNTYPE_TOOL_TYPES)[number];
+/**
+ * Terminal stop reasons, in Runtype's own wire vocabulary
+ * (`wireStopReasonSchema` in `packages/shared/src/utils/sse-event-schemas.ts`).
+ * `runtype.stop_reason` is written to the run row verbatim, so an invented
+ * value would render in the dashboard as a real fact.
+ */
+declare const RUNTYPE_STOP_REASONS: readonly ["end_turn", "max_tool_calls", "length", "content_filter", "error", "unknown"];
+type RuntypeStopReason = (typeof RUNTYPE_STOP_REASONS)[number];
+/** The version of the `runtype.*` vocabulary this package was built against. */
+declare const RUNTYPE_SCHEMA_VERSION = "1";
+/** What this package reports itself as in `runtype.adapter.name`. */
+declare const ADAPTER_NAME = "@runtypelabs/flue-otel";
+/** What this package reports itself as in `runtype.adapter.version`. */
+declare const ADAPTER_VERSION: string;
+
+/**
+ * `@runtypelabs/flue-otel` — Runtype's OpenTelemetry instrumentation for Flue
+ * agents.
+ *
+ * Install it with Flue's `instrument()` and every agent run becomes a trace of
+ * GenAI-semconv spans carrying Runtype's `runtype.*` extension vocabulary, so
+ * the run lands in Runtype at `t2-runtype` fidelity — full parity with a native
+ * run — instead of the generic tier a stock export reaches.
+ *
+ * ```ts
+ * import { instrument } from '@flue/runtime'
+ * import { createRuntypeFlueInstrumentation } from '@runtypelabs/flue-otel'
+ *
+ * const stop = instrument(createRuntypeFlueInstrumentation())
+ * ```
+ *
+ * ## What it is not
+ *
+ * It owns **no** OpenTelemetry SDK. There is no `@opentelemetry/sdk-*`
+ * dependency, no provider, no exporter, no sampler, no flush. The application
+ * configures those, this package writes spans through whatever is registered,
+ * and the README carries the twelve-line recipe for a process that has none
+ * yet. That is deliberate: a vendor package that installs its own tracing
+ * pipeline fights the one the customer already runs, and in a stack exporting
+ * to two backends it silently wins one of those fights.
+ *
+ * It also emits **no content** in this release — no prompts, no completions, no
+ * tool arguments or results, no error messages, no stack traces. Only
+ * identifiers, structure and metrics reach the wire. Content is a later,
+ * explicitly opted-in increment; until then the safety story needs no
+ * qualifiers, which is the right default for a package landing inside a
+ * PHI-bearing process.
+ *
+ * ## Composing with other instrumentations
+ *
+ * Flue's `instrument()` composes — an error reporter and a tracer can subscribe
+ * side by side — and this instrumentation carries its own `key`, so installing
+ * it never replaces `@flue/opentelemetry`.
+ *
+ * **Point exactly one instrumentation at Runtype.** If both this package and a
+ * stock `@flue/opentelemetry` export to the same Runtype endpoint, ingest sees
+ * two `invoke_agent` spans for one run and the usage DOUBLES. Running both is
+ * fine when they export to different backends.
+ */
+
+/**
+ * The instrumentation key. Distinct from stock's
+ * `Symbol.for('@flue/opentelemetry')` so `instrument()` treats the two as
+ * different subscribers and composes them rather than replacing one.
+ */
+declare const RUNTYPE_FLUE_INSTRUMENTATION_KEY: unique symbol;
+interface RuntypeFlueInstrumentationOptions extends FlueProjectionOptions {
+    /**
+     * Where spans are written. Defaults to the globally registered provider's
+     * tracer, which is what an application that called `setGlobalTracerProvider`
+     * (or `NodeSDK.start()`) already has. Pass one explicitly to route Runtype's
+     * spans through a provider separate from the rest of the process.
+     */
+    tracer?: Tracer;
+}
+/**
+ * Build the instrumentation. Install it with Flue's `instrument()`, which
+ * returns a disposer.
+ *
+ * The returned object implements the FULL `FlueInstrumentation` contract, not
+ * just `observe`. The `interceptor` half is not optional in practice: it is
+ * what makes each span the OTel ACTIVE context around the real agent, model and
+ * tool work, so the platform's own HTTP and database spans nest inside the run
+ * instead of landing in a separate trace — and it is the only place Flue offers
+ * `executionContext.traceCarrier`, the W3C context that joins a dispatched run
+ * to the trace that started it.
+ */
+declare function createRuntypeFlueInstrumentation(options?: RuntypeFlueInstrumentationOptions): FlueInstrumentation;
+
+export { ADAPTER_NAME, ADAPTER_VERSION, type FlueInstrumentation, type FlueProjectionOptions, GEN_AI, RUNTYPE, RUNTYPE_FLUE_INSTRUMENTATION_KEY, RUNTYPE_SCHEMA_VERSION, RUNTYPE_STOP_REASONS, RUNTYPE_TOOL_TYPES, type RuntypeFlueInstrumentationOptions, type RuntypeStopReason, type RuntypeToolType, type SpanAttributes, type SpanIntent, createRuntypeFlueInstrumentation, runtypeFlueResourceAttributes };