@runtypelabs/flue-otel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runtype Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# @runtypelabs/flue-otel
+
+OpenTelemetry instrumentation for [Flue](https://flueframework.com) agents that
+reports runs to [Runtype](https://runtype.com) at full fidelity.
+
+Install it with Flue's `instrument()`, point an OTLP exporter at Runtype, and
+every agent run appears in your Runtype dashboard as a first-class execution —
+with the model, token counts, cost, loop iterations, tool calls and stop reason
+that a native Runtype run has.
+
+```bash
+npm install @runtypelabs/flue-otel @opentelemetry/api
+```
+
+```ts
+import { instrument } from '@flue/runtime'
+import { createRuntypeFlueInstrumentation } from '@runtypelabs/flue-otel'
+
+const stopInstrumenting = instrument(createRuntypeFlueInstrumentation())
+```
+
+Works on **both** Flue lines — `>=1.0.0-beta.9` and 2.x — from one entry point.
+
+## Already exporting Flue traces to Runtype? Read this first
+
+Two things change, and one of them is a regression, so decide before you install:
+
+- **Replace your stock instrumentation, do not add to it.** Flue's
+  `instrument()` composes, and this package carries its own key, so calling both
+  is possible and silently wrong: Runtype receives two `invoke_agent` spans for
+  one run and the **token counts and cost double**. Point exactly one Flue
+  instrumentation at a given Runtype endpoint.
+- **You will lose the transcript.** Stock `@flue/opentelemetry` exports content
+  by default, so your runs currently carry prompts and completions. This release
+  exports none (below), which also means **eval capture from these runs stops
+  working**. In exchange the runs gain loop structure, an accurate iteration
+  count, a stop reason, and priced usage. If the transcript is what you rely on,
+  stay on stock until content ships.
+
+## It emits no content
+
+This release puts **no prompts, completions, tool arguments, tool results, error
+messages or stack traces on the wire.** Only identifiers, structure and metrics.
+
+That is deliberate and it is the default we intend to keep earning: a package
+that lands inside your process should not start shipping your users' text
+somewhere because you installed it. Content export is a later, explicitly
+opt-in increment. Until it exists, there is nothing to configure and nothing to
+audit — the spans carry model ids, token counts, durations, tool _names_, and
+correlation ids.
+
+Two consequences worth knowing:
+
+- Your Runtype executions will show timing, cost, iteration counts and the tool
+  call sequence, but **no transcript**. Eval capture from an external run needs
+  content and is not available yet.
+- If you also run stock `@flue/opentelemetry`, note that it treats calling
+  `instrument()` as consent to export content by default. That is a different
+  choice, not a bug — but it is worth checking before you point it at a
+  third-party backend.
+
+## It brings no OpenTelemetry SDK
+
+This package depends on `@opentelemetry/api` and nothing else. It creates no
+provider, no exporter, no sampler, no resource, and it never flushes. Your
+application owns all of that, and this instrumentation writes through whatever
+you have registered.
+
+If you already run OpenTelemetry, you are done after the `instrument()` call
+above — add the resource attributes below so Runtype knows which agent the runs
+belong to.
+
+### If you have no OpenTelemetry setup yet
+
+```ts
+import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import { instrument } from '@flue/runtime'
+import {
+  createRuntypeFlueInstrumentation,
+  runtypeFlueResourceAttributes,
+} from '@runtypelabs/flue-otel'
+
+const provider = new NodeTracerProvider({
+  resource: resourceFromAttributes({
+    'service.name': 'my-agent',
+    // Which Runtype agent these runs file under, plus adapter provenance.
+    ...runtypeFlueResourceAttributes({ agentId: process.env.RUNTYPE_AGENT_ID }),
+  }),
+  spanProcessors: [
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({
+        url: 'https://api.runtype.com/v1/otel/v1/traces',
+        headers: { Authorization: `Bearer ${process.env.RUNTYPE_API_KEY}` },
+      })
+    ),
+  ],
+})
+// `register()` also installs the context manager, WITHOUT WHICH nothing nests:
+// the OTel API's default is a no-op that makes every span a trace root.
+provider.register()
+
+instrument(createRuntypeFlueInstrumentation())
+
+// Flush before the process exits — see "Shutdown" below. This is not optional.
+process.on('beforeExit', () => void provider.shutdown())
+```
+
+You will also need `@opentelemetry/sdk-trace-node`,
+`@opentelemetry/exporter-trace-otlp-http` and `@opentelemetry/resources`.
+
+## Shutdown is yours, and it matters
+
+A `BatchSpanProcessor` flushes children before their parents. A process that
+exits without `forceFlush()` or `shutdown()` therefore tends to lose the
+**closing `invoke_agent` span specifically** — and a run whose envelope never
+arrives is recorded as still in flight, permanently.
+
+Wire the shutdown. In a serverless handler, `await provider.forceFlush()` before
+returning.
+
+Flue's `instrument()` returns a disposer. Calling it ends any span still open as
+`interrupted`, which is what you want on an unclean exit — but it does not
+flush, because the exporter is not ours to flush.
+
+## Attribution: which Runtype agent owns the run
+
+Runtype resolves the owning agent in this order:
+
+1. the `runtype.agent.id` **resource** attribute (what
+   `runtypeFlueResourceAttributes({ agentId })` sets) — preferred;
+2. the `x-runtype-agent-id` request header on the exporter;
+3. the `runtype.agent.id` attribute on the run's `invoke_agent` span.
+
+The first two describe a whole process, so they are the right answer when it
+runs one Runtype agent. **One process running several Runtype agents** cannot
+express that in a shared resource, which is what the third placement is for:
+
+```ts
+createRuntypeFlueInstrumentation({
+  agents: {
+    triage: 'agent_01jabc...', // keyed by the Flue agent's name
+    billing: 'agent_01jxyz...',
+  },
+})
+```
+
+A delegated sub-agent is deliberately **not** attributed separately. Its work
+runs inside the delegating agent's trace, and one trace is one execution.
+
+> **One agent invocation per trace.** Runtype's model is that one trace is one
+> execution, and spans inherit whatever OTel context is active. So if an
+> enclosing span is active while two agent invocations run — an HTTP server span
+> from auto-instrumentation is the usual way this happens — both land in the
+> same trace, and Runtype either merges them into one execution (dropping the
+> second run's usage and stop reason) or, when they claim different
+> `runtype.agent.id` values through the `agents` map above with no resource
+> attribute and no header to fall back on, rejects the trace as
+> `ambiguous_agent_attribution` and writes nothing.
+>
+> If you dispatch several agent invocations inside one request or job, start
+> each one in its own trace, or attribute at the resource level with one process
+> per agent. Flue's own `dispatch(...)` does not propagate trace context, so a
+> plain dispatch is already its own trace.
+
+## Composing with other instrumentations
+
+Flue's `instrument()` composes — an error reporter and a tracer subscribe side
+by side — and this package carries its own key, so installing it never replaces
+`@flue/opentelemetry`.
+
+> **Point exactly one instrumentation at Runtype.** If this package and a stock
+> `@flue/opentelemetry` both export to the same Runtype endpoint, Runtype sees
+> two `invoke_agent` spans for one run and the **token counts double**. Running
+> both is fine when they export to different backends.
+
+## What it emits
+
+| Span                                                           | When                               | Carries                                                                                                                                                                                        |
+| -------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `invoke_agent <agent>`                                         | one per agent invocation           | the run's model, summed token usage, `runtype.stop_reason`, `runtype.tools.reported`, the highest loop iteration, `runtype.execution.id`, and `runtype.agent.id` when `agents` names the agent |
+| `chat <model>`                                                 | one per model turn                 | provider, request/response model, finish reason, per-turn usage, `runtype.turn.id` / `.turn.index` / `.iteration`                                                                              |
+| `execute_tool <tool>`                                          | one per tool call                  | `gen_ai.tool.name`, `gen_ai.tool.call.id`, the loop position it belongs to, and `runtype.tool.type` when the tool's class is actually known                                                    |
+| `flue.task <agent>`, `flue.compaction`, `flue.operation shell` | delegation, compaction, host shell | correlation ids only — these are framework structure, not agent invocations                                                                                                                    |
+
+Every span also carries the `flue.*` correlation attributes stock
+`@flue/opentelemetry` emits, so dashboards you have already built keep working.
+
+### Two places it deliberately says nothing
+
+- **`runtype.tool.type` for an ordinary tool.** Flue's `origin` field classifies
+  who _initiated_ a call (`model` for every model-requested tool, whoever wrote
+  it), not what the tool _is_. Mapping it would fill the column with a value
+  that means nothing on that axis. Only a genuine class fact is emitted: a
+  sub-agent delegation, and a 1.x `datastore` tool.
+- **A stop reason it cannot determine.** A run that ended mid-tool-call reports
+  `unknown` rather than guessing between a turn cap, a tool cap and a host
+  abort.
+
+An absent attribute costs one column. A wrong one renders as a measurement.
+
+## Deriving from Flue's stable surface only
+
+Everything here comes from the observations Flue publishes as stable — event
+type names, envelope and correlation fields, and the normalized `turn_request` /
+`turn` / `tool_*` / `task` / `operation` / `compaction` / `submission_settled`
+payloads.
+
+Nothing reads `AgentMessage`, which Flue documents as explicitly unstable and
+which rides `message_start`, `message_end`, `turn_messages` and `agent_end`.
+That exclusion is why one entry point serves both the 1.x and 2.x lines: the
+observation plane was essentially frozen across Flue's major rewrite, and the
+handful of fields that did change are probed rather than version-compared.
+
+## License
+
+MIT