@inflexa-ai/harness 0.36.3 → 0.37.0

package/dist/contracts/message.d.ts

@@ -74,4 +74,19 @@ export interface CortexMessage {
      * zero is a figure, thus it stays a value and it never reads as an absence.
      */
     durationMs?: number;
+    /**
+     * Who sent this message — the identity the host named at the append site.
+     * Carried on a `user` message only: `role` already names the sender of a
+     * reply, and the harness holds no per-turn model name at the store boundary.
+     * Absent means that nothing recorded a sender.
+     */
+    author?: string;
+    /**
+     * When the store wrote this message: the START time of the append
+     * transaction, thus every message of one append carries the same value and
+     * no order holds between two appends. An ISO 8601 string rather than a
+     * `Date`, because the wire shape is JSON. Absent means that no stored row
+     * backs the message — a live surface builds one before anything is written.
+     */
+    createdAt?: string;
 }

package/dist/lib/otel-spans.d.ts

@@ -5,7 +5,7 @@
  * DBOS names a workflow span after the registered workflow and a step span
  * after the step function, and it runs each body under its span, so every
  * child (a step, a patched fetch, a pg query) sits under the workflow span.
- * Three shapes of that output are noise in a trace store, and each is stopped
+ * Four shapes of that output are noise in a trace store, and each is stopped
  * in the process, before export, rather than in a collector downstream. The
  * decisions live where the workflows and steps are written; this module holds
  * the mechanism only:
@@ -23,9 +23,21 @@
  *   name itself is untouched: DBOS compares it against the recorded name on
  *   replay and throws `DBOSUnexpectedStepError` on a mismatch, so a rename
  *   would break every workflow in flight across a deploy.
+ * - A step whose span only repeats the spans under it runs inside
+ *   `passThroughSpan(name, ...)`. `HarnessTracerProvider` gives that span as
+ *   a pass-through: it records nothing, and each child attaches to the span
+ *   that was active when the step started. `passThroughTracer` applies the
+ *   same mechanism to a tracer that a library takes as an option.
+ *
+ * A pass-through is the only way to omit a span in the middle of a tree. The
+ * SDK fixes the parent of a child when the child starts, so a processor that
+ * drops the span at `onEnd` leaves its children with a parent that was never
+ * exported. A sampler is no better: `ParentBased` sampling gives the children
+ * the same decision, and they are not recorded either.
  */
-import { type Attributes, type Context } from "@opentelemetry/api";
+import { type Attributes, type Context, type SpanOptions, type Tracer, type TracerOptions } from "@opentelemetry/api";
 import { type ReadableSpan, type Sampler, type Span, type SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 /**
  * Declare a registered DBOS workflow untraced: no root span for it is
  * recorded, and no child span under it. Call it next to the
@@ -60,6 +72,48 @@ export declare const ATTR_INFLEXA_ATTEMPT = "inflexa.attempt";
  * leaves a missing or non-recording span alone.
  */
 export declare function stableSpan(dbosName: string, name: string, attributes: Attributes): void;
+/**
+ * Send a request to sandbox-server with the active trace context in its
+ * headers and with tracing suppressed, so the host's HTTP instrumentation
+ * writes no client span. Sandbox-server records no spans and echoes the exec
+ * request's `traceparent` on its callbacks to the host, so a client span would
+ * show the host calling itself; the step span around the call already covers it.
+ */
+export declare function untracedFetch(fetchImpl: typeof fetch, url: string, init: RequestInit & {
+    headers: Record<string, string>;
+}): Promise<Response>;
+/**
+ * Decides whether the span that `startSpan` is about to start passes through.
+ * `context` is the parent context of that span.
+ */
+export type PassThroughRule = (name: string, options: SpanOptions, context: Context) => boolean;
+/**
+ * Wrap `tracer` so that a span that `passesThrough` selects is not written.
+ * In its place the tracer gives `trace.wrapSpanContext` of the parent span
+ * context. That span records nothing, and a span started under it becomes a
+ * child of the parent. A span with no valid parent, or a span that asks to be
+ * a root, starts as usual, because a pass-through there would make each child
+ * a root of its own trace.
+ */
+export declare function passThroughTracer(tracer: Tracer, passesThrough: PassThroughRule): Tracer;
+/**
+ * Run `fn` so that a span named `name` that starts inside it is a
+ * pass-through: `HarnessTracerProvider` writes no span for it, and the
+ * children of that span attach to the span that is active now. Wrap the call
+ * that starts the span, for example a `DBOS.runStep` with the step name
+ * `name`. A span with a different name starts as usual.
+ */
+export declare function passThroughSpan<T>(name: string, fn: () => T): T;
+/**
+ * The TracerProvider of the harness. Each tracer that it gives obeys
+ * `passThroughSpan`. The API keeps the first provider that is registered, and
+ * DBOS asks the API for its tracer at each span, so the rule applies to the
+ * DBOS step spans only because this provider is the registered one.
+ */
+export declare class HarnessTracerProvider extends NodeTracerProvider {
+    private readonly passThroughTracers;
+    getTracer(name: string, version?: string, options?: TracerOptions): Tracer;
+}
 /**
  * Sits in front of the exporting processor and forwards every span except a
  * replayed one (`cached=true`), which it drops at `onEnd`.

package/dist/lib/otel-spans.js

@@ -5,7 +5,7 @@
  * DBOS names a workflow span after the registered workflow and a step span
  * after the step function, and it runs each body under its span, so every
  * child (a step, a patched fetch, a pg query) sits under the workflow span.
- * Three shapes of that output are noise in a trace store, and each is stopped
+ * Four shapes of that output are noise in a trace store, and each is stopped
  * in the process, before export, rather than in a collector downstream. The
  * decisions live where the workflows and steps are written; this module holds
  * the mechanism only:
@@ -23,9 +23,22 @@
  *   name itself is untouched: DBOS compares it against the recorded name on
  *   replay and throws `DBOSUnexpectedStepError` on a mismatch, so a rename
  *   would break every workflow in flight across a deploy.
+ * - A step whose span only repeats the spans under it runs inside
+ *   `passThroughSpan(name, ...)`. `HarnessTracerProvider` gives that span as
+ *   a pass-through: it records nothing, and each child attaches to the span
+ *   that was active when the step started. `passThroughTracer` applies the
+ *   same mechanism to a tracer that a library takes as an option.
+ *
+ * A pass-through is the only way to omit a span in the middle of a tree. The
+ * SDK fixes the parent of a child when the child starts, so a processor that
+ * drops the span at `onEnd` leaves its children with a parent that was never
+ * exported. A sampler is no better: `ParentBased` sampling gives the children
+ * the same decision, and they are not recorded either.
  */
-import { trace } from "@opentelemetry/api";
+import { context, createContextKey, propagation, trace, } from "@opentelemetry/api";
+import { suppressTracing } from "@opentelemetry/core";
 import { ParentBasedSampler, SamplingDecision, } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 /**
  * Names of the DBOS workflows whose traces are not recorded. A registering
  * module adds its own name at registration, which runs at boot inside
@@ -92,6 +105,84 @@ export function stableSpan(dbosName, name, attributes) {
     span.updateName(name);
     span.setAttributes(attributes);
 }
+/**
+ * Send a request to sandbox-server with the active trace context in its
+ * headers and with tracing suppressed, so the host's HTTP instrumentation
+ * writes no client span. Sandbox-server records no spans and echoes the exec
+ * request's `traceparent` on its callbacks to the host, so a client span would
+ * show the host calling itself; the step span around the call already covers it.
+ */
+export function untracedFetch(fetchImpl, url, init) {
+    const active = context.active();
+    const headers = { ...init.headers };
+    propagation.inject(active, headers);
+    return context.with(suppressTracing(active), () => fetchImpl(url, { ...init, headers }));
+}
+/**
+ * Wrap `tracer` so that a span that `passesThrough` selects is not written.
+ * In its place the tracer gives `trace.wrapSpanContext` of the parent span
+ * context. That span records nothing, and a span started under it becomes a
+ * child of the parent. A span with no valid parent, or a span that asks to be
+ * a root, starts as usual, because a pass-through there would make each child
+ * a root of its own trace.
+ */
+export function passThroughTracer(tracer, passesThrough) {
+    return new PassThroughTracer(tracer, passesThrough);
+}
+class PassThroughTracer {
+    inner;
+    passesThrough;
+    constructor(inner, passesThrough) {
+        this.inner = inner;
+        this.passesThrough = passesThrough;
+    }
+    startSpan(name, options = {}, parentContext = context.active()) {
+        const parent = options.root === true ? undefined : trace.getSpanContext(parentContext);
+        if (parent !== undefined && trace.isSpanContextValid(parent) && this.passesThrough(name, options, parentContext)) {
+            return trace.wrapSpanContext(parent);
+        }
+        return this.inner.startSpan(name, options, parentContext);
+    }
+    // The inner tracer cannot take this call: its own `startActiveSpan` calls its own `startSpan`, past the rule.
+    startActiveSpan(name, ...rest) {
+        const fn = rest[rest.length - 1];
+        const options = rest.length > 1 ? rest[0] : {};
+        const parentContext = (rest.length > 2 ? rest[1] : undefined) ?? context.active();
+        const span = this.startSpan(name, options, parentContext);
+        return context.with(trace.setSpan(parentContext, span), () => fn(span));
+    }
+}
+/** The name of the span that the enclosing `passThroughSpan` declared. */
+const PASS_THROUGH_SPAN_NAME = createContextKey("inflexa.pass_through_span_name");
+/**
+ * Run `fn` so that a span named `name` that starts inside it is a
+ * pass-through: `HarnessTracerProvider` writes no span for it, and the
+ * children of that span attach to the span that is active now. Wrap the call
+ * that starts the span, for example a `DBOS.runStep` with the step name
+ * `name`. A span with a different name starts as usual.
+ */
+export function passThroughSpan(name, fn) {
+    return context.with(context.active().setValue(PASS_THROUGH_SPAN_NAME, name), fn);
+}
+const declaredPassThrough = (name, _options, parentContext) => parentContext.getValue(PASS_THROUGH_SPAN_NAME) === name;
+/**
+ * The TracerProvider of the harness. Each tracer that it gives obeys
+ * `passThroughSpan`. The API keeps the first provider that is registered, and
+ * DBOS asks the API for its tracer at each span, so the rule applies to the
+ * DBOS step spans only because this provider is the registered one.
+ */
+export class HarnessTracerProvider extends NodeTracerProvider {
+    passThroughTracers = new WeakMap();
+    getTracer(name, version, options) {
+        const tracer = super.getTracer(name, version, options);
+        let wrapped = this.passThroughTracers.get(tracer);
+        if (wrapped === undefined) {
+            wrapped = passThroughTracer(tracer, declaredPassThrough);
+            this.passThroughTracers.set(tracer, wrapped);
+        }
+        return wrapped;
+    }
+}
 /**
  * Sits in front of the exporting processor and forwards every span except a
  * replayed one (`cached=true`), which it drops at `onEnd`.

package/dist/lib/otel.d.ts

@@ -4,13 +4,15 @@
  * Exported as `initOtel()` and called explicitly from the host's boot sequence
  * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
- * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *         is set. The provider carries the span policy of otel-spans.ts: the
- *         root span of a workflow declared with `untracedWorkflow` is not
- *         recorded (and its children with it), a replayed `cached=true` span
- *         is dropped before export, and a step body that calls `stableSpan`
- *         is exported under a stable name with its id in an `inflexa.*`
- *         attribute.
+ * Traces: HarnessTracerProvider exports to OTLP when
+ *         OTEL_EXPORTER_OTLP_ENDPOINT is set. The provider carries the span
+ *         policy of otel-spans.ts: the root span of a workflow declared with
+ *         `untracedWorkflow` is not recorded (and its children with it), a
+ *         replayed `cached=true` span is dropped before export, a step body
+ *         that calls `stableSpan` is exported under a stable name with its id
+ *         in an `inflexa.*` attribute, and a span declared with
+ *         `passThroughSpan` is not written, its children attached to its
+ *         parent.
  *
  * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
  *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
@@ -21,11 +23,13 @@
  *          to their record sites. Every instrument binds lazily to the
  *          provider registered here.
  *
- * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
- *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);
- *           the environment wins on a conflict, so a deployment can set
+ * Resource: the SDK's default resource (`telemetry.sdk.*`), under the host's
+ *           `serviceName` / `serviceVersion`, under the SDK env detector
+ *           (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`). A later layer
+ *           wins on a conflict, so a deployment can set
  *           `deployment.environment.name` or override the service name without
- *           a code change. Traces and metrics share the one resource.
+ *           a code change, and the default `unknown_service` name never
+ *           reaches an export. Traces and metrics share the one resource.
  *
  * Note: OTEL's instrumentation-http patches node:http but does not cover
  *        Hono's request handling or Node 22's undici-based globalThis.fetch,

package/dist/lib/otel.js

@@ -4,13 +4,15 @@
  * Exported as `initOtel()` and called explicitly from the host's boot sequence
  * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
- * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *         is set. The provider carries the span policy of otel-spans.ts: the
- *         root span of a workflow declared with `untracedWorkflow` is not
- *         recorded (and its children with it), a replayed `cached=true` span
- *         is dropped before export, and a step body that calls `stableSpan`
- *         is exported under a stable name with its id in an `inflexa.*`
- *         attribute.
+ * Traces: HarnessTracerProvider exports to OTLP when
+ *         OTEL_EXPORTER_OTLP_ENDPOINT is set. The provider carries the span
+ *         policy of otel-spans.ts: the root span of a workflow declared with
+ *         `untracedWorkflow` is not recorded (and its children with it), a
+ *         replayed `cached=true` span is dropped before export, a step body
+ *         that calls `stableSpan` is exported under a stable name with its id
+ *         in an `inflexa.*` attribute, and a span declared with
+ *         `passThroughSpan` is not written, its children attached to its
+ *         parent.
  *
  * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
  *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
@@ -21,11 +23,13 @@
  *          to their record sites. Every instrument binds lazily to the
  *          provider registered here.
  *
- * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
- *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);
- *           the environment wins on a conflict, so a deployment can set
+ * Resource: the SDK's default resource (`telemetry.sdk.*`), under the host's
+ *           `serviceName` / `serviceVersion`, under the SDK env detector
+ *           (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`). A later layer
+ *           wins on a conflict, so a deployment can set
  *           `deployment.environment.name` or override the service name without
- *           a code change. Traces and metrics share the one resource.
+ *           a code change, and the default `unknown_service` name never
+ *           reaches an export. Traces and metrics share the one resource.
  *
  * Note: OTEL's instrumentation-http patches node:http but does not cover
  *        Hono's request handling or Node 22's undici-based globalThis.fetch,
@@ -34,14 +38,13 @@
  */
 import { context, propagation, metrics, trace } from "@opentelemetry/api";
 import { createNoopLogger } from "./console-logger.js";
-import { createHarnessSampler, DbosSpanProcessor } from "./otel-spans.js";
+import { createHarnessSampler, DbosSpanProcessor, HarnessTracerProvider } from "./otel-spans.js";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { detectResources, envDetector, resourceFromAttributes } from "@opentelemetry/resources";
+import { defaultResource, detectResources, envDetector, resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 /** The SDK's own default when neither the host nor the environment says otherwise. */
 export const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60_000;
@@ -75,9 +78,13 @@ function buildResource(options) {
     };
     if (options.serviceVersion)
         manual[ATTR_SERVICE_VERSION] = options.serviceVersion;
-    // `merge` gives precedence to the argument: the environment overrides the
-    // host's values, which is the OTel SDK convention for env configuration.
-    return resourceFromAttributes(manual).merge(detectResources({ detectors: [envDetector] }));
+    // `merge` gives precedence to the argument. A provider that gets an explicit
+    // resource does not add the SDK default itself, so it is the bottom layer here.
+    // The environment overrides the host's values, which is the OTel SDK
+    // convention for env configuration.
+    return defaultResource()
+        .merge(resourceFromAttributes(manual))
+        .merge(detectResources({ detectors: [envDetector] }));
 }
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
@@ -104,7 +111,7 @@ export function initOtel(options = {}) {
             const base = endpoint.replace(/\/+$/, "");
             spanProcessors.push(new DbosSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` }))));
         }
-        const tracerProvider = new NodeTracerProvider({
+        const tracerProvider = new HarnessTracerProvider({
             resource,
             sampler: createHarnessSampler(),
             spanProcessors,

package/dist/loop/genai-spans.d.ts

@@ -4,6 +4,11 @@
  * SDK traces the model calls (`providers/ai-sdk.ts`). It never sees the loop or
  * the tools, because the harness runs both itself.
  *
+ * The root of a turn opens its own trace, and a link carries it back to the run.
+ * A run lasts hours and writes tens of thousands of spans, thus one trace of a
+ * whole run passes the size limit of the trace store and no reader can follow
+ * it. `inflexa.run_id` holds the turns of one run together.
+ *
  * An `execute_tool` span is ERROR when our code fails the call. A failure that a
  * tool returns as data, for example a sandbox command that exits non-zero, is
  * normal iteration of the agent, and its span stays OK.
@@ -17,8 +22,11 @@ interface AgentRun {
         readonly cappedOut: boolean;
     };
 }
-/** Run one agent loop under an `invoke_agent` span. */
-export declare function traceAgentRun<T extends AgentRun>(agentName: string, session: AgentSession, run: () => Promise<T>): Promise<T>;
+/**
+ * Run one agent loop under an `invoke_agent` span. A turn root starts a new
+ * trace; a loop under a turn stays in the trace of that turn.
+ */
+export declare function traceAgentRun<T extends AgentRun>(agentName: string, session: AgentSession, turnRoot: boolean, run: () => Promise<T>): Promise<T>;
 /** Run one tool call under an `execute_tool` span that records how the call ended. */
 export declare function traceToolCall<T>(call: Pick<ToolCallPart, "toolName" | "toolCallId">, run: () => Promise<T>, outcomeOf: (value: T) => ToolOutcome): Promise<T>;
 /**

package/dist/loop/genai-spans.js

@@ -4,15 +4,29 @@
  * SDK traces the model calls (`providers/ai-sdk.ts`). It never sees the loop or
  * the tools, because the harness runs both itself.
  *
+ * The root of a turn opens its own trace, and a link carries it back to the run.
+ * A run lasts hours and writes tens of thousands of spans, thus one trace of a
+ * whole run passes the size limit of the trace store and no reader can follow
+ * it. `inflexa.run_id` holds the turns of one run together.
+ *
  * An `execute_tool` span is ERROR when our code fails the call. A failure that a
  * tool returns as data, for example a sandbox command that exits non-zero, is
  * normal iteration of the agent, and its span stays OK.
  */
-import { SpanStatusCode, trace } from "@opentelemetry/api";
-/** Run one agent loop under an `invoke_agent` span. */
-export function traceAgentRun(agentName, session, run) {
-    const attributes = { "gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": agentName, ...runFrameAttributes(session) };
-    return withSpan(`invoke_agent ${agentName}`, attributes, async (span) => {
+import { context, SpanStatusCode, trace, TraceFlags } from "@opentelemetry/api";
+import { isTracingSuppressed } from "@opentelemetry/core";
+/**
+ * Run one agent loop under an `invoke_agent` span. A turn root starts a new
+ * trace; a loop under a turn stays in the trace of that turn.
+ */
+export function traceAgentRun(agentName, session, turnRoot, run) {
+    const attributes = {
+        "gen_ai.operation.name": "invoke_agent",
+        "gen_ai.agent.name": agentName,
+        ...conversationAttributes(session),
+        ...runFrameAttributes(session),
+    };
+    return withSpan(`invoke_agent ${agentName}`, turnRoot ? turnRootOptions(attributes) : { attributes }, async (span) => {
         const result = await run();
         span.setAttributes({ "gen_ai.response.finish_reasons": [result.finish.reason], "inflexa.agent.capped_out": result.finish.cappedOut });
         return result;
@@ -21,7 +35,7 @@ export function traceAgentRun(agentName, session, run) {
 /** Run one tool call under an `execute_tool` span that records how the call ended. */
 export function traceToolCall(call, run, outcomeOf) {
     const attributes = { "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": call.toolName, "gen_ai.tool.call.id": call.toolCallId };
-    return withSpan(`execute_tool ${call.toolName}`, attributes, async (span) => {
+    return withSpan(`execute_tool ${call.toolName}`, { attributes }, async (span) => {
         const value = await run();
         const outcome = outcomeOf(value);
         span.setAttribute("inflexa.tool.outcome", outcome);
@@ -71,8 +85,26 @@ function errorTypeOf(err) {
         return String(code);
     return err.name === "" ? "_OTHER" : err.name;
 }
-function withSpan(name, attributes, run) {
-    return trace.getTracer("@inflexa-ai/harness").startActiveSpan(name, { attributes }, async (span) => {
+/**
+ * The options of a turn root. `root: true` drops the parent before the sampler
+ * runs, thus the sampler takes its root branch and a decision from above is
+ * lost. A turn under suppressed tracing, or under a trace that is not sampled
+ * (an untraced workflow), therefore keeps its parent and stays unrecorded.
+ */
+function turnRootOptions(attributes) {
+    const active = context.active();
+    if (isTracingSuppressed(active))
+        return { attributes };
+    const ambient = trace.getSpanContext(active);
+    if (ambient === undefined || !trace.isSpanContextValid(ambient))
+        return { root: true, attributes };
+    if ((ambient.traceFlags & TraceFlags.SAMPLED) === 0)
+        return { attributes };
+    // The span that started the turn: the workflow span of the run, or the request span.
+    return { root: true, links: [{ context: ambient, attributes: { "inflexa.link.kind": "caller" } }], attributes };
+}
+function withSpan(name, options, run) {
+    return trace.getTracer("@inflexa-ai/harness").startActiveSpan(name, options, async (span) => {
         try {
             return await run(span);
         }
@@ -96,3 +128,7 @@ function runFrameAttributes({ runFrame }) {
         return {};
     return { "inflexa.run_id": runFrame.runId, ...(runFrame.stepId === undefined ? {} : { "inflexa.step_id": runFrame.stepId }) };
 }
+/** The thread is the conversation. The analysis is not: it holds many threads. */
+function conversationAttributes({ scope }) {
+    return scope.threadId === undefined ? {} : { "gen_ai.conversation.id": scope.threadId };
+}

package/dist/loop/run-agent.js

@@ -3,7 +3,7 @@ import { jsonSchema, tool as aiTool, } from "ai";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
-import { ATTR_INFLEXA_TOOL_USE_ID, stableSpan } from "../lib/otel-spans.js";
+import { ATTR_INFLEXA_TOOL_USE_ID, passThroughSpan, stableSpan } from "../lib/otel-spans.js";
 import { ResultError } from "../lib/result.js";
 import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
@@ -25,11 +25,17 @@ export const DEFAULT_STEP_NAME_FORMATTER = {
     llm: (i) => `llm-${i}`,
     tool: (name, id) => `tool-${name}-${id}`,
 };
+/** A run that receives no turn accumulator is the turn's root. See `RunAgentOptions.turnUsage`. */
+const isTurnRoot = (opts) => opts.turnUsage === undefined;
 export function runAgent(agent, initial, session, opts) {
-    return traceAgentRun(agent.id, session, () => runAgentLoop(agent, initial, session, opts));
+    return traceAgentRun(agent.id, session, isTurnRoot(opts), () => runAgentLoop(agent, initial, session, opts));
 }
 async function runAgentLoop(agent, initial, session, opts) {
     const { provider, signal, emit, runStep } = opts;
+    // The step of a model call or a tool call writes no span. The `chat` span and
+    // the `execute_tool` span under it describe the call already, and they attach
+    // to the `invoke_agent` span of this run.
+    const callStep = (name, fn) => passThroughSpan(name, () => runStep(name, fn));
     const formatStepName = opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER;
     const configuredFatalLoopError = opts.isFatalLoopError ?? (() => false);
     // AbortError is control flow, not a tool failure. Always compose it with the
@@ -71,7 +77,7 @@ async function runAgentLoop(agent, initial, session, opts) {
     // descendant loop folds into, and it is the only loop entitled to report a
     // turn total. Descendants receive the root's object and mutate it in place.
     const turnUsage = opts.turnUsage ?? {};
-    const isTurnRoot = opts.turnUsage === undefined;
+    const turnRoot = isTurnRoot(opts);
     const toolCtx = (tu) => ({
         invocationId: tu.toolCallId,
         session,
@@ -168,7 +174,7 @@ async function runAgentLoop(agent, initial, session, opts) {
     /** The rollups this loop stamps on its finish — each absent when nothing reported. */
     const finishUsage = () => ({
         ...(hasReportedUsage(usage) ? { usage: { ...usage } } : {}),
-        ...(isTurnRoot && hasReportedUsage(turnUsage) ? { turnUsage: { ...turnUsage } } : {}),
+        ...(turnRoot && hasReportedUsage(turnUsage) ? { turnUsage: { ...turnUsage } } : {}),
     });
     // The user said no. A subsequent model call would only let the agent argue
     // with the decision, or spend a call acknowledging it; the denial tool result
@@ -252,7 +258,7 @@ async function runAgentLoop(agent, initial, session, opts) {
             reasoning,
         };
         const llmStepName = formatStepName.llm(i);
-        const reply = await resultStep(runStep)(llmStepName, () => provider.chat(request, session, signal));
+        const reply = await resultStep(callStep)(llmStepName, () => provider.chat(request, session, signal));
         accountForCall(reply, llmStepName);
         if (reply.finishReason === "aborted") {
             // An interrupted turn keeps whatever the model produced before the cut, but
@@ -290,7 +296,7 @@ async function runAgentLoop(agent, initial, session, opts) {
             for (const [idx, tu] of earlier.entries()) {
                 await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(earlierDetails[idx]) });
             }
-            const { results, durations, resultDetails } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
+            const { results, durations, resultDetails } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, callStep, formatStepName.tool, encoding);
             const errored = await settleRound(earlier, results, earlierDetails, resultDetails, durations);
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
             // The trailing call was never dispatched, but it reaches the model as an error
@@ -342,7 +348,7 @@ async function runAgentLoop(agent, initial, session, opts) {
         for (const [idx, tu] of toolCalls.entries()) {
             await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(details[idx]) });
         }
-        const { results, durations, resultDetails } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
+        const { results, durations, resultDetails } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, callStep, formatStepName.tool, encoding);
         const errored = await settleRound(toolCalls, results, details, resultDetails, durations);
         if (errored.length > 0)
             log.debug("tool results returned errors", { iteration: i, tools: errored });
@@ -360,7 +366,7 @@ async function runAgentLoop(agent, initial, session, opts) {
     // because it is the one call whose write is pure waste, and the
     // cache_write_tokens counter is what makes that waste visible.
     const wrapUpStepName = formatStepName.llm(agent.maxIterations);
-    const wrapUp = await resultStep(runStep)(wrapUpStepName, () => provider.chat({ system: agent.systemPrompt, messages: withPromptCacheBreakpoint(messages, promptCache), tools: {}, toolChoice: "none", reasoning }, session, signal));
+    const wrapUp = await resultStep(callStep)(wrapUpStepName, () => provider.chat({ system: agent.systemPrompt, messages: withPromptCacheBreakpoint(messages, promptCache), tools: {}, toolChoice: "none", reasoning }, session, signal));
     accountForCall(wrapUp, wrapUpStepName);
     if (wrapUp.finishReason === "aborted") {
         // An abort during the tool-less wrap-up is still the user cutting the turn — the
@@ -554,11 +560,7 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
     }
     await Promise.all(stepTools.map(({ tu, idx }) => {
         const startedAt = performance.now();
-        const stepName = toolStepName(tu.toolName, tu.toolCallId);
-        return runStep(stepName, () => {
-            stableSpan(stepName, `tool:${tu.toolName}`, { [ATTR_INFLEXA_TOOL_USE_ID]: tu.toolCallId });
-            return dispatch(tu);
-        }).then((settled) => {
+        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatch(tu)).then((settled) => {
             durations[idx] = elapsedMs(startedAt);
             const dispatched = readDispatchedStep(settled);
             results[idx] = dispatched.result;

package/dist/memory/conversation-display-replay.js

@@ -23,7 +23,20 @@ export function storedMessagesToCortex(messages) {
     let append = null;
     for (const row of messages) {
         if (row.displayEnvelope) {
-            append = conversationUIToCortexMessages(row.displayEnvelope.messages);
+            // The author and the creation time are facts about the ROW, the same as
+            // the rollup below, and the projection holds neither. Both ride the row
+            // that opens the append, and the author reaches the `user` messages
+            // alone, because `role` already names the sender of a reply. Spread
+            // conditionally: an absent value must leave no key, or a consumer that
+            // spreads the message acquires one that overwrites a real value. `Date`
+            // does not survive the JSON crossing typed, hence the ISO string here.
+            const createdAt = row.createdAt === undefined ? {} : { createdAt: row.createdAt.toISOString() };
+            const author = row.author === undefined ? {} : { author: row.author };
+            append = conversationUIToCortexMessages(row.displayEnvelope.messages).map((message) => ({
+                ...message,
+                ...createdAt,
+                ...(message.role === "user" ? author : {}),
+            }));
             out.push(...append);
         }
         // The reported rollup of the turn and its duration both ride the model row that

package/dist/memory/thread-history.d.ts

@@ -55,6 +55,20 @@ export interface StoredMessage {
      * reported no quantity still reads back with the duration that it took.
      */
     readonly durationMs?: number;
+    /**
+     * Who sent the user message of the append this row OPENED — present only on a
+     * genuine-user-start row of a turn appended with one. A row written before the
+     * column existed carries none, because no sender was ever recorded for it.
+     */
+    readonly author?: string;
+    /**
+     * When the store wrote this row: the START time of the append transaction,
+     * thus every row of one append holds the same value, and `seq` alone orders
+     * rows. The read sets it on every row, because the column is `NOT NULL`. It is
+     * optional because a fake or a fixture builds a `StoredMessage` with no row
+     * behind it.
+     */
+    readonly createdAt?: Date;
 }
 /**
  * One atomic append: the exact provider-facing history, the display projection of
@@ -86,6 +100,16 @@ export interface ConversationTurn {
      * reported no quantity still keeps the duration that it took.
      */
     readonly turnDurationMs?: number;
+    /**
+     * Who sent the user message of this turn — the identity the host holds at the
+     * append site. Stored on the FIRST row of the append, and only when that row
+     * is a genuine user start: that row also carries the display projection, thus
+     * the write and the transcript replay read one row under one rule. A record
+     * append opens on a synthetic row, so it stores no author however a caller
+     * spreads one in. The value is NUL-stripped on the way in, the same as the
+     * envelope, because a `text` parameter carrying 0x00 fails the statement.
+     */
+    readonly author?: string;
 }
 /**
  * The append a host uses to record out-of-band work in a thread — an analysis

package/dist/memory/thread-history.js

@@ -181,7 +181,7 @@ export const EVICTION_BLOCK_TURNS = 4;
  */
 export function createThreadHistory(pool, logger) {
     function appendTurn(threadId, turn) {
-        const { modelMessages: messages, displayMessages, turnUsage, turnDurationMs } = turn;
+        const { modelMessages: messages, displayMessages, turnUsage, turnDurationMs, author } = turn;
         if (messages.length === 0)
             return okVoid();
         // The display projection rides the append's FIRST row, so one SELECT of a
@@ -206,6 +206,13 @@ export function createThreadHistory(pool, logger) {
         // the turn. -1 (a turn that persisted no reply — an abort before any output)
         // matches no index below, so nothing is written and the append still succeeds.
         const lastAssistantRow = messages.reduce((last, m, i) => (m.role === "assistant" ? i : last), -1);
+        // The author rides the row the display projection rides, and only when that
+        // row is a message a person actually sent — an assistant row, a tool row,
+        // and the synthetic opening row of a record append are not. NUL is dropped
+        // rather than refused: a 0x00 byte in a `text` parameter fails the
+        // statement, and one byte in a label would roll the whole turn back.
+        const turnAuthor = author === undefined ? null : stripNulCharacters(author);
+        const authorRow = messages[0] !== undefined && isGenuineUserStart(messages[0]) ? 0 : -1;
         return withTransaction(pool, "thread-history.appendTurn", (client) => 
         // Serialize concurrent appends on this thread — without the lock, two
         // transactions can both read the same MAX(seq) and collide on the
@@ -224,14 +231,15 @@ export function createThreadHistory(pool, logger) {
         // `message_envelope::json`, never `::jsonb`; `display_envelope` and
         // `reported_usage::jsonb`, never `::json` — see the column comments
         // in the state-init DDL.
-        `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, reported_usage, turn_duration_ms)
-                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6::jsonb, $7)
+        `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, reported_usage, turn_duration_ms, author)
+                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6::jsonb, $7, $8)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
                            display_envelope = EXCLUDED.display_envelope,
                            tokens = EXCLUDED.tokens,
                            reported_usage = EXCLUDED.reported_usage,
-                           turn_duration_ms = EXCLUDED.turn_duration_ms`, [
+                           turn_duration_ms = EXCLUDED.turn_duration_ms,
+                           author = EXCLUDED.author`, [
             threadId,
             startSeq + i,
             serializeEnvelope(message),
@@ -239,6 +247,7 @@ export function createThreadHistory(pool, logger) {
             countTokens(message.content),
             i === lastAssistantRow ? rollup : null,
             i === lastAssistantRow ? duration : null,
+            i === authorRow ? turnAuthor : null,
         ])).map(() => undefined)), okVoid()))
             .andThen(() => 
         // Thread listings sort on `cortex_analysis_threads.updated_at`, and
@@ -368,12 +377,14 @@ export function createThreadHistory(pool, logger) {
         // `seq::text AS seq` output alias (Postgres resolves an unqualified
         // ORDER BY name to the output column), sorting the bigint as text:
         // "10" before "2". The qualified name forces the bigint column.
-        `SELECT seq::text AS seq, message_envelope, display_envelope, reported_usage, turn_duration_ms::text AS turn_duration_ms
+        `SELECT seq::text AS seq, message_envelope, display_envelope, reported_usage, turn_duration_ms::text AS turn_duration_ms, author, created_at
          FROM messages WHERE thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
         // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
         // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
-        // The duration obeys the same rule, and it reads from its own column.
+        // The duration and the author obey the same rule, each from its own column.
+        // The creation time is unconditional: its column is NOT NULL, thus it has no
+        // absence to represent.
         const stored = await Promise.all(rows.map(async (r) => {
             const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
             const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
@@ -384,6 +395,8 @@ export function createThreadHistory(pool, logger) {
                 ...(displayEnvelope ? { displayEnvelope } : {}),
                 ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
                 ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
+                ...(r.author === null ? {} : { author: r.author }),
+                createdAt: r.created_at,
             };
         }));
         return groupTurns(stored, (row) => isGenuineUserStart(row.message));

package/dist/providers/ai-sdk.js

@@ -5,9 +5,11 @@ import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { OpenTelemetry } from "@ai-sdk/otel";
 import { APICallError } from "@ai-sdk/provider";
 import { retryWithExponentialBackoff } from "@ai-sdk/provider-utils";
+import { trace } from "@opentelemetry/api";
 import { ResultAsync, err, ok } from "neverthrow";
 import { scopeWorkloadId } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { passThroughTracer } from "../lib/otel-spans.js";
 import { classifyProviderError, RequestTimeoutError, toProviderError } from "./errors.js";
 /**
  * The harness-owned retry envelope. The AI SDK's built-in retry exposes only a
@@ -414,6 +416,10 @@ function abortedStreamFailure(signal, reason, requestTimeoutMs) {
         return new RequestTimeoutError(requestTimeoutMs);
     return new Error(reason ?? "The provider aborted the stream.");
 }
+/** The `gen_ai.operation.name` of the operation span and of the step span that the AI SDK opens around each `chat` span. */
+function isSdkWrapperSpan(operation) {
+    return operation === "invoke_agent" || operation === "agent_step";
+}
 export function createAiSdkProvider(deps) {
     const capabilities = {
         toolCalling: deps.capabilities?.toolCalling ?? true,
@@ -435,8 +441,12 @@ export function createAiSdkProvider(deps) {
     // Each model call emits OpenTelemetry GenAI spans through the AI SDK, with no
     // prompt or completion text on them. The integration rides on each call
     // instead of the global registry, so the harness never traces the embedder's
-    // own AI SDK calls.
-    const telemetry = { integrations: new OpenTelemetry(), recordInputs: false, recordOutputs: false };
+    // own AI SDK calls. Of the SDK spans only `chat` is written. The operation
+    // span and the step span around it repeat what `chat` and the span of the
+    // caller (the loop's `invoke_agent`) say already. Thus they pass through, and
+    // `chat` attaches to the span of the caller.
+    const tracer = passThroughTracer(trace.getTracer("gen_ai"), (_name, options) => isSdkWrapperSpan(options.attributes?.["gen_ai.operation.name"]));
+    const telemetry = { integrations: new OpenTelemetry({ tracer }), recordInputs: false, recordOutputs: false };
     routeSdkWarningsTo(logger);
     /**
      * Record a call that the envelope gave up on.

package/dist/runtime/dbos.d.ts

@@ -57,9 +57,10 @@ export interface DbosConfig {
      *
      * The harness TracerProvider shapes what the SDK emits (`lib/otel-spans.ts`):
      * a workflow declared with `untracedWorkflow` is not recorded, a replayed
-     * `cached=true` span is dropped before export, and a step body that calls
+     * `cached=true` span is dropped before export, a step body that calls
      * `stableSpan` is exported under a stable name with its id in an
-     * `inflexa.*` attribute. The step name DBOS records is unchanged.
+     * `inflexa.*` attribute, and the step of an agent-loop model call or tool
+     * call writes no span. The step name DBOS records is unchanged.
      *
      * Known SDK behavior a host must plan for: a recovered workflow starts a
      * new root trace, with no link to the trace of the original execution.

package/dist/sandbox/await-exec.js

@@ -55,7 +55,7 @@
  * varied between replays would desynchronise the recorded function-ID sequence.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
-import { ATTR_INFLEXA_ATTEMPT, ATTR_INFLEXA_EXEC_ID, stableSpan } from "../lib/otel-spans.js";
+import { ATTR_INFLEXA_ATTEMPT, ATTR_INFLEXA_EXEC_ID, stableSpan, untracedFetch } from "../lib/otel-spans.js";
 import { digestBody } from "./digest.js";
 import { signCallback, verifyCallback } from "./hmac.js";
 import { createEscalationPolicy, probeLiveness, syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
@@ -105,7 +105,7 @@ async function pullExecResult(fetchImpl, ref, execId) {
         // cached result is replayed without re-executing the body.
         const reqTimestamp = Math.floor(Date.now() / 1000);
         const reqSignature = signCallback({ execId, body: "", timestamp: reqTimestamp, secret: ref.callbackSecret });
-        const res = await fetchImpl(`http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}`, {
+        const res = await untracedFetch(fetchImpl, `http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}`, {
             method: "GET",
             headers: {
                 "x-sandbox-signature": reqSignature,
@@ -272,7 +272,7 @@ async function pollExecOnce(fetchImpl, ref, execId, cursor) {
         // replayed without re-executing the body.
         const reqTimestamp = Math.floor(Date.now() / 1000);
         const reqSignature = signCallback({ execId, body: "", timestamp: reqTimestamp, secret: ref.callbackSecret });
-        const res = await fetchImpl(`http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}?since=${cursor}`, {
+        const res = await untracedFetch(fetchImpl, `http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}?since=${cursor}`, {
             method: "GET",
             headers: {
                 "x-sandbox-signature": reqSignature,

package/dist/sandbox/submit-exec.js

@@ -17,7 +17,7 @@
  * untouched.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
-import { ATTR_INFLEXA_EXEC_ID, stableSpan } from "../lib/otel-spans.js";
+import { ATTR_INFLEXA_EXEC_ID, stableSpan, untracedFetch } from "../lib/otel-spans.js";
 import { EXEC_STREAM_BYTE_CAP } from "../tools/workspace/result-bounds.js";
 import { signCallback } from "./hmac.js";
 const SUBMIT_HTTP_TIMEOUT_MS = 30_000;
@@ -33,7 +33,7 @@ async function postExec(fetchImpl, ref, body) {
         const raw = JSON.stringify(body);
         const timestamp = Math.floor(Date.now() / 1000);
         const signature = signCallback({ execId: body.execId, body: raw, timestamp, secret: ref.callbackSecret });
-        const res = await fetchImpl(`http://${ref.host}:${ref.port}/exec`, {
+        const res = await untracedFetch(fetchImpl, `http://${ref.host}:${ref.port}/exec`, {
             method: "POST",
             headers: {
                 "content-type": "application/json",

package/dist/state/init.js

@@ -270,6 +270,13 @@ CREATE INDEX IF NOT EXISTS idx_cortex_regulatory_chunks_metadata
 -- Nullable with no default: absent means that nobody measured the turn, and a
 -- zero would claim that a turn took no time. A row written before this column
 -- existed is absent for the same reason, thus the migration needs no backfill.
+--
+-- author names the identity that sent the user message of a turn, as the host
+-- knew it at the append site. It is written on the genuine-user-start row of an
+-- append only -- the row that carries display_envelope -- and never on an
+-- assistant, tool, or synthetic row. Nullable with no default and no backfill:
+-- absent means that no sender was recorded, which is the honest value both for a
+-- row that predates the column and for a turn appended without one.
 CREATE TABLE IF NOT EXISTS messages (
   thread_id     TEXT NOT NULL,
   seq           BIGINT NOT NULL,
@@ -282,6 +289,7 @@ CREATE TABLE IF NOT EXISTS messages (
   tokens        INTEGER NOT NULL,
   reported_usage JSONB,
   turn_duration_ms BIGINT,
+  author        TEXT,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   PRIMARY KEY (thread_id, seq)
 );
@@ -547,6 +555,9 @@ export async function initCortexState(pool, injected) {
                 // and every earlier message reads back with no duration — which is the
                 // honest value, because nobody measured those turns.
                 "ALTER TABLE messages ADD COLUMN IF NOT EXISTS turn_duration_ms BIGINT",
+                // Who sent the user message of the turn (see the CREATE TABLE comment).
+                // Purely additive: nullable with no default, thus the column rewrites no row.
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS author TEXT",
                 // Demote an existing JSONB envelope column to JSON (see the CREATE
                 // TABLE comment). Type-guarded because ALTER ... TYPE rewrites the
                 // whole table and this runs at every boot; scoped to

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.36.3",
+    "version": "0.37.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",