@runtypelabs/flue-otel 0.4.0 → 0.5.1

package/README.md

@@ -10,9 +10,11 @@ token usage, cost, loop iterations, tool calls and stop reason.
 - Works with Flue `>=1.0.0-beta.9` and 2.x from one entry point.
 - Depends on `@opentelemetry/api` only. It brings no SDK, provider, exporter or
   sampler; it writes through whatever your application has registered.
-- Emits identifiers, structure and metrics by default. No prompts, completions,
-  tool arguments, tool results, error messages or stack traces reach the wire
-  unless you opt in; the one opt-in is [tool content](#tool-content).
+- Emits everything Runtype can show by default: identifiers, structure,
+  metrics, the transcript, the system prompt, and tool arguments and results.
+  Every content kind has its own off switch, and `content: false` sends shape
+  and cost only; see [Content](#content). Error messages and stack traces never
+  reach the wire.
 
 Full guide: [Instrumenting a Flue agent](https://docs.runtype.com/developer-guides/guides/flue-instrumentation).
 
@@ -85,11 +87,11 @@ process.on('beforeExit', () => void provider.shutdown())
 
 `createRuntypeFlueInstrumentation(options?)` accepts:
 
-| Option    | Type                     | Purpose                                                                                                                                                                      |
-| --------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agents`  | `Record<string, string>` | Runtype agent id per Flue agent name, e.g. `{ triage: 'agent_01j...' }`. Stamped as `runtype.agent.id` on that agent's `invoke_agent` span. See [Attribution](#attribution). |
-| `tracer`  | `Tracer`                 | Where spans are written. Defaults to `trace.getTracer('@runtypelabs/flue-otel')` on the global provider. Pass one to route Runtype spans through a separate provider.        |
-| `content` | `FlueContentOptions`     | Opt in to tool arguments and results on `execute_tool` spans. Off by default. See [Tool content](#tool-content).                                                             |
+| Option    | Type                          | Purpose                                                                                                                                                                      |
+| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents`  | `Record<string, string>`      | Runtype agent id per Flue agent name, e.g. `{ triage: 'agent_01j...' }`. Stamped as `runtype.agent.id` on that agent's `invoke_agent` span. See [Attribution](#attribution). |
+| `tracer`  | `Tracer`                      | Where spans are written. Defaults to `trace.getTracer('@runtypelabs/flue-otel')` on the global provider. Pass one to route Runtype spans through a separate provider.        |
+| `content` | `FlueContentOptions \| false` | Transcript, system prompt, tool arguments and results. All on by default; switch kinds off individually, or pass `false` for none. See [Content](#content).                  |
 
 The returned object implements Flue's full `FlueInstrumentation` contract:
 `observe` (builds spans from Flue's observation stream), `interceptor` (makes
@@ -111,7 +113,7 @@ subscriber. Its key is exported as `RUNTYPE_FLUE_INSTRUMENTATION_KEY`.
   version produced a trace even when the resource is not wired; the resource
   placement still wins where both are present.
 - `GEN_AI` and `RUNTYPE`: the attribute-name constants this package emits by
-  default; `GEN_AI_CONTENT`: the two it emits under the `content` opt-in.
+  default; `GEN_AI_CONTENT`: the five content attributes it emits unless switched off.
 - `DEFAULT_CONTENT_MAX_CHARS` and `INGEST_CONTENT_ATTRIBUTE_CEILING`: the
   content size defaults, see [Tool content](#tool-content).
 - `RUNTYPE_STOP_REASONS`, `RUNTYPE_TOOL_TYPES`, `RUNTYPE_SCHEMA_VERSION`,
@@ -188,7 +190,7 @@ backends.
 | -------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `invoke_agent <agent>`                                         | once per agent invocation               | `gen_ai.agent.name`, `gen_ai.conversation.id`, the run's request/response model, summed token usage across every turn (`gen_ai.usage.*`), `runtype.stop_reason`, `runtype.tools.reported`, the highest loop iteration (`runtype.iteration`), `runtype.execution.id`, and `runtype.agent.id` when `agents` names the agent                                                                                                                                     |
 | `chat <model>`                                                 | once per model turn                     | `gen_ai.provider.name`, request/response model, response id, finish reason, per-turn usage, request parameters (`max_tokens`, `temperature`, reasoning level, server address), `runtype.turn.id` / `runtype.turn.index` / `runtype.iteration`, and `runtype.provider.finish_reason` / `runtype.gateway.log_id` when the provider records them (Workers AI attaches both — the gateway log id is a pointer to that exact request in your AI Gateway dashboard) |
-| `execute_tool <tool>`                                          | once per model-requested tool call      | `gen_ai.tool.name`, `gen_ai.tool.call.id`, the loop position it belongs to, `gen_ai.tool.type` (`function`) for every tool except a sub-agent delegation, and `runtype.tool.type` when the tool's class is known, and `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` only under the [`content`](#tool-content) opt-in                                                                                                                               |
+| `execute_tool <tool>`                                          | once per model-requested tool call      | `gen_ai.tool.name`, `gen_ai.tool.call.id`, the loop position it belongs to, `gen_ai.tool.type` (`function`) for every tool except a sub-agent delegation, and `runtype.tool.type` when the tool's class is known, and `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` unless [`content`](#tool-content) switches them off                                                                                                                            |
 | `flue.task <agent>`, `flue.compaction`, `flue.operation shell` | delegation, compaction, host shell call | correlation ids only; framework structure, not agent invocations                                                                                                                                                                                                                                                                                                                                                                                              |
 
 Every span also carries Flue's own `flue.*` correlation attributes
@@ -229,25 +231,58 @@ Rules the projection follows:
 
 An absent attribute costs one column. A wrong one renders as a measurement.
 
-## Tool content
+## Content
 
-By default an `execute_tool` span says which tool ran and how long it took, and
-Runtype's trace view shows its card as "No tool content in this trace". To see
-arguments and results on that card, opt in:
+Everything under `content` is **on by default** and independent: with no
+option at all a run lands in Runtype with its transcript, system prompt, and
+every tool's arguments and results — which is what lets Runtype show the
+conversation and capture it as a replayable eval case. Two families:
+[tool content](#tool-content) on `execute_tool` spans, and
+[messages](#messages) on the `invoke_agent` envelope. Set a switch to `false`
+to drop that one kind, or pass `content: false` to send shape and cost only.
 
 ```ts
 createRuntypeFlueInstrumentation({
   content: {
-    toolArguments: true, // gen_ai.tool.call.arguments, set when the span opens
-    toolResults: true, // gen_ai.tool.call.result, set just before the span ends
+    toolArguments: true,
+    toolResults: true,
+    inputMessages: true,
+    outputMessages: true,
+    systemInstructions: false, // the one most deployments turn off: large, and rarely per-run
+    maxChars: 65_536,
+    redact: (value, context) =>
+      context.kind === 'arguments' && context.toolName === 'delegate' ? undefined : value,
+  },
+})
+
+// Shape and cost only, no content of any kind:
+createRuntypeFlueInstrumentation({ content: false })
+```
+
+Content makes spans large. Runtype admits at most 384 KiB of content per span
+and 2 MiB per export request, and rejects a request over 8 MiB whole; past the
+2 MiB mark the remaining runs in that request land without their transcript.
+With content on, set your `BatchSpanProcessor`'s `maxExportBatchSize` so one
+request stays under those bounds — 16 to 32 spans for chatty agents, 64 for
+short runs — and watch `contentDropCount` on ingested runs.
+
+### Tool content
+
+An `execute_tool` span carries the call's arguments and result, so Runtype's
+trace view shows them on the tool card. To drop either:
+
+```ts
+createRuntypeFlueInstrumentation({
+  content: {
+    toolArguments: false, // gen_ai.tool.call.arguments, set when the span opens
+    toolResults: false, // gen_ai.tool.call.result, set just before the span ends
     maxChars: 65_536, // per value, marker included; this is the default
-    redact: (value, { kind, toolName }) => value, // optional; return undefined to drop
+    redact: (value, { kind, toolName }) => value, // optional; narrow on kind, then toolName
   },
 })
 ```
 
-Each switch is independent and defaults to off, so `{}` changes nothing. The
-values come from Flue's stable `tool_start.args` and `tool.result` payloads
+The values come from Flue's stable `tool_start.args` and `tool.result` payloads
 (2.x's `effectiveResult`, what the model was actually shown, when present).
 
 The attribute names are the GenAI semconv `gen_ai.tool.call.arguments` and
@@ -278,23 +313,103 @@ Ceilings worth knowing, because they decide what Runtype keeps:
   the whole batch (envelope and usage included, not only the content). With
   both switches on, set `maxExportBatchSize` to something like 64.
 
-What is still never sent, whatever you set:
+What tool content never carries, whatever you set:
 
 - **A failed tool's result.** On both Flue lines it is commonly the error
   payload, and error messages stay off the wire. The span still closes with its
   error type and exception class name.
 - **The host's own shell call** (`session.shell()`), which is not a tool row.
-- **Prompts and completions.** They live on `AgentMessage`, which Flue marks
-  unstable. This package will read them once Flue exposes a stable shape. One
-  edge to know: a delegation to a sub-agent is a tool call, and its
-  **arguments carry the prompt handed to that sub-agent**. If that matters for
-  your deployment, drop it with `redact` (return `undefined` when `toolName`
-  is the delegation tool).
-
-`redact` runs on the raw value before encoding, so it can address fields by
-name; it receives `{ kind: 'arguments' | 'result', toolName }`. Returning
-`undefined` drops the attribute for that call. If it throws, the attribute is
-dropped and the span is otherwise unaffected.
+
+One edge to know: a delegation to a sub-agent is a tool call, and its
+**arguments carry the prompt handed to that sub-agent**. If that matters for
+your deployment, drop it with `redact` (return `undefined` when `toolName` is
+the delegation tool).
+
+### Messages
+
+Three switches govern the conversation itself on the `invoke_agent` span, which
+is the span Runtype reads a run's transcript and final output from. All three
+are on unless switched off:
+
+```ts
+createRuntypeFlueInstrumentation({
+  content: {
+    inputMessages: true, // gen_ai.input.messages
+    outputMessages: true, // gen_ai.output.messages
+    systemInstructions: false, // gen_ai.system_instructions
+  },
+})
+```
+
+- **`inputMessages`** is the conversation the run was given, read from Flue's
+  normalized `turn_request.request.input.messages`: the first agent turn's
+  history, plus any `kind: 'user'` message delivered mid-run that a later
+  turn's history carries. The run's own assistant rows are not repeated here —
+  the tool spans and `outputMessages` carry them — and a turn after a
+  compaction, which sees a summary in place of the conversation, never
+  replaces an earlier capture (Flue does not flag such a request, so the
+  `compaction` observation and the summary row it puts first are the signal).
+  One copy per run, on the envelope. It lands on
+  the run as its transcript and is the seed eval capture freezes a case from.
+- **`outputMessages`** is the assistant text of the _last_ agent turn that
+  produced any, read from `turn.response.output`. A final step that only called
+  tools does not clear an earlier answer, and a failed turn's output is never
+  read. Runtype projects it onto the run's final output.
+- **`systemInstructions`** is `turn_request.request.input.systemPrompt`,
+  sent as one text part (`[{ type: 'text', content }]`) so a prompt that happens
+  to be valid JSON is never re-read as data. It is usually the largest value a
+  run carries and rarely differs between runs, so it is the switch most
+  deployments turn off; Runtype prepends it to the transcript as a `system` row.
+
+Messages are encoded as the GenAI semconv structured-message shape,
+`[{ role, parts: [{ type: 'text', content }] }]`, and they are **text parts
+only**: a `toolResult` message, a tool-call part, a thinking part and an image
+part are dropped, as is any `system` row Flue put in the history (that is what
+`systemInstructions` is for). A Flue **signal** — the steering Flue delivers to
+the model as a user message (`<signal type="…">…</signal>` deliveries and
+`dispatch()` inputs, `useAgentFinish` continuations, stream recovery, the
+compaction summary) — is exported as a `system` row, verbatim with its framing,
+so it is never read as something the user said and the reader sees exactly what
+the model saw. Recognition is a text-shape test on Flue's exact framing (one
+element with a leading `type` attribute, body on its own lines, one text part),
+so it can only _reduce_ misclassification: HTML elements that conventionally
+lead with `type` (`<script>`, `<style>`, `<button>`, …) and multi-part messages
+always stay user rows, but a user message that exactly reproduces the framing
+with another tag lands as a `system` row. Tool content has its own switches
+above; the
+rest is never exported. `AgentMessage`, which Flue marks unstable, is still
+never read — the `Llm*` request and response payloads are byte-identical on
+1.x and 2.x.
+
+Over `maxChars`, a message list drops its **oldest** messages whole first, so
+the newest messages survive; a lone message that still does not fit has its
+text cut with the truncation marker, and the JSON stays valid either way. The
+system prompt is cut inside its text part. Because all three share one span,
+each is additionally capped at a third of ingest's per-span ceiling
+(128 KiB), whatever `maxChars` says — as a tool's arguments and result are each
+capped at half of it (192 KiB); at the default ceiling everything fits
+comfortably.
+
+### Redaction
+
+`redact` runs on every content value before encoding and truncation. It
+receives the value and a context:
+
+- `{ kind: 'arguments' | 'result', toolName }` with the raw Flue payload;
+- `{ kind: 'input_messages' | 'output_messages' }` with the projected message
+  array (`[{ role, parts: [{ type: 'text', content }] }]`; `{ role, content }`
+  with a string or Flue-style `{ type: 'text', text }` parts is accepted back);
+- `{ kind: 'system_instructions' }` with the prompt string; return a string or
+  text parts (`[{ type: 'text', content | text }]`) — anything else emits
+  nothing, because ingest would discard it silently.
+
+`toolName` is present on the tool kinds and `undefined` on the others, so a
+hook written for 0.4 — `({ kind, toolName }) => …` — keeps compiling; narrow on
+`kind` before relying on it.
+
+Return the value to keep it, a replacement to substitute it, or `undefined` to
+drop that one attribute. If it throws, the attribute is dropped and the span is
+otherwise unaffected.
 
 ## Flue compatibility
 

package/dist/index.cjs

@@ -78,49 +78,193 @@ function mapSettlementOutcome(outcome) {
   return void 0;
 }
 
+// src/messages.ts
+var ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant"]);
+var FLUE_ROLES = /* @__PURE__ */ new Set(["user", "assistant"]);
+var SIGNAL_MESSAGE = /^<([A-Za-z_][\w.-]*) type="[^"]*"[^>]*>\n[\s\S]*\n<\/\1>$/;
+var COMPACTION_SUMMARY_PREFIX = '<compaction type="context_summary"';
+var HTML_TYPED_TAGS = /* @__PURE__ */ new Set([
+  "a",
+  "button",
+  "embed",
+  "input",
+  "link",
+  "menu",
+  "object",
+  "ol",
+  "script",
+  "source",
+  "style",
+  "ul"
+]);
+function projectFlueMessages(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const entry of value) {
+    const message = projectFlueMessage(entry);
+    if (message) out.push(message);
+  }
+  return out;
+}
+function projectFlueMessage(value) {
+  if (!isRecord(value)) return void 0;
+  const role = value.role;
+  if (typeof role !== "string" || !FLUE_ROLES.has(role)) return void 0;
+  const text = flueMessageText(value.content);
+  if (text === "") return void 0;
+  if (role === "user" && isFlueSignal(value.content, text)) {
+    return { role: "system", parts: [{ type: "text", content: text }] };
+  }
+  return { role, parts: [{ type: "text", content: text }] };
+}
+function isFlueSignal(content, text) {
+  if (!isSingleText(content)) return false;
+  const signal = SIGNAL_MESSAGE.exec(text);
+  return signal !== null && !HTML_TYPED_TAGS.has(signal[1].toLowerCase());
+}
+function isSingleText(content) {
+  if (typeof content === "string") return true;
+  return Array.isArray(content) && content.length === 1;
+}
+function flueMessageText(content) {
+  return contentMessageText({ content });
+}
+function normalizeContentMessages(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const entry of value) {
+    if (!isRecord(entry)) continue;
+    const role = entry.role;
+    if (typeof role !== "string" || !ROLES.has(role)) continue;
+    const text = contentMessageText(entry);
+    if (text === "") continue;
+    out.push({ role, parts: [{ type: "text", content: text }] });
+  }
+  return out;
+}
+function contentTextOf(value) {
+  if (typeof value === "string") return value;
+  return Array.isArray(value) ? contentMessageText({ parts: value }) : "";
+}
+function contentMessageText(message) {
+  if (typeof message.content === "string") return message.content;
+  const parts = Array.isArray(message.parts) ? message.parts : Array.isArray(message.content) ? message.content : [];
+  const texts = [];
+  for (const part of parts) {
+    if (!isRecord(part) || part.type !== "text") continue;
+    const text = typeof part.content === "string" && part.content.length > 0 ? part.content : typeof part.text === "string" && part.text.length > 0 ? part.text : "";
+    if (text !== "") texts.push(text);
+  }
+  return texts.join("\n");
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 // src/content.ts
 var DEFAULT_CONTENT_MAX_CHARS = 65536;
 var INGEST_CONTENT_ATTRIBUTE_CEILING = 262144;
-function resolveContentPolicy(options) {
+var INGEST_CONTENT_SPAN_CEILING = 393216;
+function resolveContentPolicy(setting) {
+  const options = setting === false ? void 0 : setting;
+  const on = (value) => setting !== false && value !== false;
   const requested = options?.maxChars;
   const maxChars = typeof requested === "number" && Number.isFinite(requested) && requested > 0 ? Math.min(Math.floor(requested), INGEST_CONTENT_ATTRIBUTE_CEILING) : DEFAULT_CONTENT_MAX_CHARS;
   return {
-    toolArguments: options?.toolArguments === true,
-    toolResults: options?.toolResults === true,
+    toolArguments: on(options?.toolArguments),
+    toolResults: on(options?.toolResults),
+    inputMessages: on(options?.inputMessages),
+    outputMessages: on(options?.outputMessages),
+    systemInstructions: on(options?.systemInstructions),
     maxChars,
+    envelopeMaxChars: Math.min(maxChars, Math.floor(INGEST_CONTENT_SPAN_CEILING / 3)),
+    toolMaxChars: Math.min(maxChars, Math.floor(INGEST_CONTENT_SPAN_CEILING / 2)),
     redact: options?.redact
   };
 }
 function encodeContentValue(value, policy, context3) {
   if (value === void 0) return void 0;
-  let redacted = value;
-  if (policy.redact) {
-    try {
-      redacted = policy.redact(value, context3);
-    } catch {
-      return void 0;
-    }
-    if (redacted === void 0) return void 0;
-  }
-  if (context3.kind === "arguments") return encodeArguments(redacted, policy.maxChars);
+  const redacted = applyRedact(value, policy, context3);
+  if (redacted === void 0) return void 0;
+  if (context3.kind === "arguments") return encodeArguments(redacted, policy.toolMaxChars);
   const encoded = stringify(redacted);
   if (encoded === void 0) return void 0;
-  return truncate(encoded, policy.maxChars);
+  return truncate(encoded, policy.toolMaxChars);
+}
+function encodeMessagesValue(messages, policy, kind) {
+  if (messages.length === 0) return void 0;
+  const redacted = applyRedact(messages, policy, { kind });
+  if (redacted === void 0) return void 0;
+  const all = normalizeContentMessages(redacted);
+  if (all.length === 0) return void 0;
+  const maxChars = policy.envelopeMaxChars;
+  const perMessage = all.length > 1 ? Math.floor((maxChars - 3) / 2) : maxChars - 2;
+  const encoded = [];
+  for (const message of all) {
+    const one = JSON.stringify(message);
+    encoded.push(one.length <= perMessage ? one : encodeTruncatedMessage(message, perMessage) ?? "");
+  }
+  let start = all.length;
+  let total = 2;
+  while (start > 0) {
+    const length = encoded[start - 1].length + (start < all.length ? 1 : 0);
+    if (total + length > maxChars) break;
+    total += length;
+    start -= 1;
+  }
+  const kept = encoded.slice(start).filter((one) => one !== "");
+  if (kept.length === 0) return void 0;
+  return "[" + kept.join(",") + "]";
+}
+function encodeSystemInstructionsValue(value, policy) {
+  if (value.length === 0) return void 0;
+  const redacted = applyRedact(value, policy, { kind: "system_instructions" });
+  if (redacted === void 0) return void 0;
+  const text = contentTextOf(redacted);
+  if (text.length === 0) return void 0;
+  return encodeTextParts(text, policy.envelopeMaxChars);
+}
+function encodeTruncatedMessage(message, maxChars) {
+  const text = message.parts.map((part) => part.content).join("\n");
+  return fitJson(
+    (cut) => JSON.stringify({ role: message.role, parts: [{ type: "text", content: cut }] }),
+    text,
+    maxChars
+  );
+}
+function encodeTextParts(text, maxChars) {
+  return fitJson((cut) => JSON.stringify([{ type: "text", content: cut }]), text, maxChars);
+}
+function fitJson(wrap, text, maxChars) {
+  let encoded = wrap(text);
+  if (encoded.length <= maxChars) return encoded;
+  const shell = wrap("").length;
+  let budget = maxChars - shell;
+  for (let round = 0; round < 8; round += 1) {
+    if (budget <= truncationMarker(text.length).length) return void 0;
+    const cut = truncate(text, budget);
+    encoded = wrap(cut);
+    if (encoded.length <= maxChars) return encoded;
+    const rescaled = Math.floor(budget * (maxChars - shell) / (encoded.length - shell));
+    budget = Math.min(budget - 1, rescaled);
+  }
+  return void 0;
+}
+function applyRedact(value, policy, context3) {
+  if (!policy.redact) return value;
+  try {
+    return policy.redact(value, context3);
+  } catch {
+    return void 0;
+  }
 }
 function encodeArguments(value, maxChars) {
   const shaped = isPlainObject(value) ? value : { value };
   const encoded = stringify(shaped);
   if (encoded === void 0) return void 0;
   if (encoded.length <= maxChars) return encoded;
-  let budget = maxChars - TRUNCATED_WRAPPER_OVERHEAD;
-  for (let round = 0; round < 8 && budget > 0; round += 1) {
-    const wrapped = JSON.stringify({ truncated: truncate(encoded, budget) });
-    if (wrapped.length <= maxChars) return wrapped;
-    budget -= wrapped.length - maxChars;
-  }
-  return JSON.stringify({ truncated: truncate(encoded, Math.max(0, budget)) });
+  return fitJson((cut) => JSON.stringify({ truncated: cut }), encoded, maxChars);
 }
-var TRUNCATED_WRAPPER_OVERHEAD = 16;
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -154,7 +298,7 @@ function isHighSurrogate(code) {
 }
 
 // package.json
-var version = "0.4.0";
+var version = "0.5.1";
 
 // src/semconv.ts
 var GEN_AI = {
@@ -183,6 +327,9 @@ var GEN_AI = {
   serverPort: "server.port"
 };
 var GEN_AI_CONTENT = {
+  inputMessages: "gen_ai.input.messages",
+  outputMessages: "gen_ai.output.messages",
+  systemInstructions: "gen_ai.system_instructions",
   toolCallArguments: "gen_ai.tool.call.arguments",
   toolCallResult: "gen_ai.tool.call.result"
 };
@@ -336,9 +483,6 @@ function createFlueProjection(options = {}) {
           ...isEnvelope ? { [GEN_AI.operationName]: GEN_AI_OPERATION_INVOKE_AGENT } : {},
           ...isEnvelope && event.agentName ? { [GEN_AI.agentName]: event.agentName } : {},
           ...isEnvelope && event.conversationId ? { [GEN_AI.conversationId]: event.conversationId } : {},
-          // The execution id LIFTS the tier and is claim-checked at ingest like
-          // any inbound id; it does not key the row, which stays derived from
-          // the trace id.
           ...isEnvelope && event.submissionId ? { [RUNTYPE.executionId]: event.submissionId } : {},
           ...isEnvelope && agentId ? { [RUNTYPE.agentId]: agentId } : {},
           // WHY(README.md): the resource placement is the customer's to wire and is routinely skipped.
@@ -402,9 +546,7 @@ function createFlueProjection(options = {}) {
       {
         kind: "open",
         ref,
-        // Deliberately NOT `invoke_agent`: see this module's header. A second
-        // agent-invocation span in the trace is a coin flip over which one
-        // becomes the run's envelope.
+        // WHY(packages/flue-otel/src/projection.ts): Use a task span, not invoke_agent; one trace is persisted as one execution.
         name: agent ? `flue.task ${agent}` : "flue.task",
         spanKind: "internal",
         ...parentRef ? { parentRef } : {},
@@ -444,8 +586,6 @@ function createFlueProjection(options = {}) {
         ref,
         name: "flue.compaction",
         spanKind: "internal",
-        // `session.compact()` is callable by the host outside any turn, and a
-        // `compact` operation is not intercepted, so this can be parentless.
         requiresParent: true,
         ...parentRef ? { parentRef } : {},
         ...event.timestamp ? { startTime: event.timestamp } : {},
@@ -459,6 +599,11 @@ function createFlueProjection(options = {}) {
   function onCompactionEnd(event) {
     const ref = compactionKey(event);
     if (!open.has(ref)) return [];
+    if (!event.taskId) {
+      const envelope = resolveEnvelopeRef(event);
+      const state = envelope ? envelopes.get(envelope) : void 0;
+      if (state) state.compacted = true;
+    }
     const intents = sweepDescendants(ref, event.timestamp);
     intents.push(
       closeIntent(ref, event, readBoolean(event, "isError") === true, readErrorInfo(event))
@@ -510,6 +655,7 @@ function createFlueProjection(options = {}) {
       if (!envelope.modelPinned && purpose === "agent")
         envelope.requestModel = request.requestedModel;
       if (Array.isArray(request.input?.tools)) envelope.toolsReported = true;
+      if (position?.atEnvelopeScope) captureInput(envelope, request);
     }
     return [
       {
@@ -555,20 +701,16 @@ function createFlueProjection(options = {}) {
       if (purpose === "agent" && response.finishReason) {
         envelope.lastFinishReason = response.finishReason;
       }
+      if (content.outputMessages && purpose === "agent" && !event.taskId && !isError) {
+        const output = projectFlueMessage(response.output);
+        if (output?.role === "assistant") envelope.outputMessage = output;
+      }
     }
     const attributes = {
       ...response.responseModel ? { [GEN_AI.responseModel]: response.responseModel } : {},
       ...response.responseId ? { [GEN_AI.responseId]: response.responseId } : {},
       ...response.finishReason ? { [GEN_AI.finishReasons]: [response.finishReason] } : {},
       ...usageAttributes(response.usage),
-      // Provider-diagnostic pointers, emitted only when Flue actually provides
-      // them. Both are optional and provider-dependent (Workers AI attaches
-      // both today); an absent value costs one column, a synthesized one would
-      // render as a measurement. `gatewayLogId` is a pointer to the content
-      // without shipping the content — a customer can click through to that
-      // exact request in their own AI Gateway dashboard. `providerFinishReason`
-      // is the provider's exact finish value before normalization, which our
-      // `GEN_AI.finishReasons` above deliberately hides.
       ...response.providerFinishReason ? { [RUNTYPE.providerFinishReason]: response.providerFinishReason } : {},
       ...response.gatewayLogId ? { [RUNTYPE.gatewayLogId]: response.gatewayLogId } : {}
     };
@@ -599,8 +741,6 @@ function createFlueProjection(options = {}) {
           ref,
           name: "flue.operation shell",
           spanKind: "internal",
-          // `session.shell()` is callable by the host outside any turn, and a
-          // `shell` operation is not intercepted, so this can be parentless.
           requiresParent: true,
           ...parentRef ? { parentRef } : {},
           ...event.timestamp ? { startTime: event.timestamp } : {},
@@ -632,10 +772,6 @@ function createFlueProjection(options = {}) {
           [GEN_AI.toolName]: toolName,
           [GEN_AI.toolCallId]: toolCallId,
           ...args !== void 0 ? { [GEN_AI_CONTENT.toolCallArguments]: args } : {},
-          // The semconv `gen_ai.tool.type` domain is the transport-level one
-          // (`function` / `extension` / `datastore`); a sub-agent delegation is
-          // not a plain function call, so it is left unclaimed there while
-          // `runtype.tool.type` says what it actually is.
           ...isDelegation ? {} : { [GEN_AI.toolType]: "function" },
           ...toolType ? { [RUNTYPE.toolType]: toolType } : {},
           ...event.origin ? { [FLUE.toolOrigin]: event.origin } : {},
@@ -694,10 +830,43 @@ function createFlueProjection(options = {}) {
       } : {},
       ...stopReason ? { [RUNTYPE.stopReason]: stopReason } : {},
       ...envelope.toolsReported ? { [RUNTYPE.toolsReported]: true } : {},
-      // The highest loop position reached. Ingest records `max + 1` as the run's
-      // iteration count, so the envelope alone reports it correctly even when
-      // the batch carrying the model turns flushed earlier.
-      ...envelope.maxIteration !== null ? { [RUNTYPE.iteration]: envelope.maxIteration } : {}
+      ...envelope.maxIteration !== null ? { [RUNTYPE.iteration]: envelope.maxIteration } : {},
+      ...envelopeContentAttributes(envelope)
+    };
+  }
+  function captureInput(envelope, request) {
+    const input = request.input;
+    if (envelope.inputRaw && (envelope.compacted || isCompactedHistory(input?.messages))) return;
+    if (content.inputMessages && Array.isArray(input?.messages) && input.messages.length > 0) {
+      envelope.inputRaw = input.messages;
+      envelope.inputBaseCount ??= input.messages.length;
+    }
+    if (content.systemInstructions && typeof input?.systemPrompt === "string") {
+      envelope.systemInstructions = input.systemPrompt;
+    }
+  }
+  function isCompactedHistory(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) return false;
+    const first = messages[0];
+    if (!first || first.role !== "user") return false;
+    return flueMessageText(first.content).startsWith(COMPACTION_SUMMARY_PREFIX);
+  }
+  function projectInput(envelope) {
+    const raw = envelope.inputRaw ?? [];
+    const base = envelope.inputBaseCount ?? raw.length;
+    return [
+      ...projectFlueMessages(raw.slice(0, base)),
+      ...projectFlueMessages(raw.slice(base)).filter((message) => message.role !== "assistant")
+    ];
+  }
+  function envelopeContentAttributes(envelope) {
+    const input = envelope.inputRaw ? encodeMessagesValue(projectInput(envelope), content, "input_messages") : void 0;
+    const system = envelope.systemInstructions ? encodeSystemInstructionsValue(envelope.systemInstructions, content) : void 0;
+    const output = envelope.outputMessage ? encodeMessagesValue([envelope.outputMessage], content, "output_messages") : void 0;
+    return {
+      ...input !== void 0 ? { [GEN_AI_CONTENT.inputMessages]: input } : {},
+      ...system !== void 0 ? { [GEN_AI_CONTENT.systemInstructions]: system } : {},
+      ...output !== void 0 ? { [GEN_AI_CONTENT.outputMessages]: output } : {}
     };
   }
   function resolveEnvelopeRef(event) {
@@ -817,9 +986,7 @@ function positionAttributes(position) {
   return {
     ...position.turnId ? { [RUNTYPE.turnId]: position.turnId } : {},
     [RUNTYPE.turnIndex]: position.index,
-    // Only the root agent's loop has an ITERATION. A delegated sub-agent's
-    // turns would otherwise inflate the run's iteration count, which ingest
-    // computes as the highest position across every span in the trace.
+    // WHY(packages/flue-otel/src/projection.ts): Do not stamp delegated turns with root iteration positions; they would inflate the run iteration count.
     ...position.atEnvelopeScope ? { [RUNTYPE.iteration]: position.index } : {}
   };
 }
@@ -845,9 +1012,6 @@ function closeIntent(ref, event, isError, errorInfo) {
     ...isError ? {
       error: {
         type: errorInfo?.type ?? "_OTHER",
-        // The class NAME only. `errorInfo.message` and `.stack` are content
-        // and this release emits none: a provider message routinely quotes
-        // the prompt back, and a stack ships filesystem layout.
         ...errorInfo?.name ? { exceptionType: errorInfo.name } : {}
       }
     } : {}