@inflexa-ai/harness 0.36.2 → 0.36.4

package/dist/execution/step-summary-metrics.d.ts

@@ -1,5 +1,5 @@
 /**
- * Step-summary OTel metrics — Middleware.io routing follows the global
+ * Step-summary OTel metrics — export follows the global
  * meter provider (see `harness/lib/otel.ts`).
  *
  * cortex.summary.null_count — counter, incremented when a step-summary

package/dist/execution/step-summary-metrics.js

@@ -1,5 +1,5 @@
 /**
- * Step-summary OTel metrics — Middleware.io routing follows the global
+ * Step-summary OTel metrics — export follows the global
  * meter provider (see `harness/lib/otel.ts`).
  *
  * cortex.summary.null_count — counter, incremented when a step-summary

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/lib/zod-issue-shape.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The shape of a Zod validation failure, with no value of the input in it.
+ *
+ * The span and the log of a rejected tool call may not carry the arguments of
+ * the model. A Zod `message` can quote the input, and so can the `keys` of an
+ * `unrecognized_keys` issue and the string segments of a path under a record.
+ * Thus each entry is built only from parts that the schema defines:
+ *
+ *  - the path, where a string segment is kept only when the schema declares
+ *    that key, and each other string segment becomes `*`. An array index is
+ *    kept as a number.
+ *  - the issue `code`.
+ *  - schema-side detail: the `expected` type, the `origin` and bound of a size
+ *    check, the string `format`, the divisor, the allowed literals, and the
+ *    discriminator of a union. For `unrecognized_keys`, only the count of keys.
+ *
+ * Example: `runId: invalid_type (expected string)`.
+ */
+import type { z } from "zod";
+/** Describe the issues of `error` against `schema`, one entry for each issue. */
+export declare function describeZodIssueShapes(error: z.ZodError, schema: z.ZodType): string[];

package/dist/lib/zod-issue-shape.js

@@ -0,0 +1,122 @@
+/**
+ * The shape of a Zod validation failure, with no value of the input in it.
+ *
+ * The span and the log of a rejected tool call may not carry the arguments of
+ * the model. A Zod `message` can quote the input, and so can the `keys` of an
+ * `unrecognized_keys` issue and the string segments of a path under a record.
+ * Thus each entry is built only from parts that the schema defines:
+ *
+ *  - the path, where a string segment is kept only when the schema declares
+ *    that key, and each other string segment becomes `*`. An array index is
+ *    kept as a number.
+ *  - the issue `code`.
+ *  - schema-side detail: the `expected` type, the `origin` and bound of a size
+ *    check, the string `format`, the divisor, the allowed literals, and the
+ *    discriminator of a union. For `unrecognized_keys`, only the count of keys.
+ *
+ * Example: `runId: invalid_type (expected string)`.
+ */
+/** The most issues that one failure describes. */
+const MAX_ISSUES = 10;
+/** The cap of one entry, in characters. */
+const MAX_ENTRY_CHARS = 200;
+/** Describe the issues of `error` against `schema`, one entry for each issue. */
+export function describeZodIssueShapes(error, schema) {
+    const entries = error.issues.slice(0, MAX_ISSUES).map((issue) => {
+        const detail = issueDetail(issue);
+        const entry = `${schemaPath(schema, issue.path)}: ${issue.code}${detail === undefined ? "" : ` (${detail})`}`;
+        return entry.length > MAX_ENTRY_CHARS ? `${entry.slice(0, MAX_ENTRY_CHARS - 1)}…` : entry;
+    });
+    const rest = error.issues.length - MAX_ISSUES;
+    if (rest > 0)
+        entries.push(`+${rest} more issues`);
+    return entries;
+}
+function issueDetail(issue) {
+    switch (issue.code) {
+        case "invalid_type":
+            return `expected ${issue.expected}`;
+        case "too_small":
+            return `${issue.origin} ${issue.exact === true ? "exactly" : "min"} ${issue.minimum}`;
+        case "too_big":
+            return `${issue.origin} ${issue.exact === true ? "exactly" : "max"} ${issue.maximum}`;
+        case "invalid_format":
+            return `format ${issue.format}`;
+        case "not_multiple_of":
+            return `divisor ${issue.divisor}`;
+        case "unrecognized_keys":
+            return `${issue.keys.length} keys`;
+        case "invalid_value":
+            return `expected ${issue.values.map(String).join("|")}`;
+        case "invalid_union":
+            return issue.discriminator === undefined ? undefined : `discriminator ${issue.discriminator}`;
+        default:
+            return undefined;
+    }
+}
+/** The path of an issue, with each string segment that the schema does not declare replaced by `*`. */
+function schemaPath(schema, path) {
+    if (path.length === 0)
+        return "(root)";
+    let current = schema;
+    const segments = path.map((segment) => {
+        if (typeof segment === "number") {
+            current = current === undefined ? undefined : elementOf(current, segment);
+            return String(segment);
+        }
+        const field = current === undefined || typeof segment !== "string" ? undefined : fieldOf(current, segment);
+        current = field;
+        return field === undefined ? "*" : String(segment);
+    });
+    return segments.join(".");
+}
+/** The schema of the declared field `key`, looking through wrappers and unions. */
+function fieldOf(schema, key) {
+    const def = unwrap(schema)._zod.def;
+    if (def.type === "object")
+        return Object.hasOwn(def.shape, key) ? def.shape[key] : undefined;
+    if (def.type === "union") {
+        for (const option of def.options) {
+            const field = fieldOf(option, key);
+            if (field !== undefined)
+                return field;
+        }
+    }
+    if (def.type === "intersection")
+        return fieldOf(def.left, key) ?? fieldOf(def.right, key);
+    return undefined;
+}
+function elementOf(schema, index) {
+    const def = unwrap(schema)._zod.def;
+    if (def.type === "array")
+        return def.element;
+    if (def.type === "tuple")
+        return def.items[index] ?? def.rest ?? undefined;
+    return undefined;
+}
+function unwrap(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 16; depth++) {
+        const def = current._zod.def;
+        switch (def.type) {
+            case "optional":
+            case "nullable":
+            case "default":
+            case "prefault":
+            case "nonoptional":
+            case "catch":
+            case "readonly":
+                current = def.innerType;
+                break;
+            case "pipe":
+                current = def.in;
+                break;
+            case "lazy":
+                current = def.getter();
+                break;
+            default:
+                return current;
+        }
+    }
+    return current;
+}

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>;
 /**
@@ -31,4 +39,9 @@ export declare function recordToolException(err: Error): void;
  * span. `message` is text that our tool wrote, never text from the model.
  */
 export declare function labelToolFailure(type: string, message?: string): void;
+/**
+ * Label a tool call whose input failed validation on the active `execute_tool`
+ * span. `issues` is the shape of the failure, with no value of the input.
+ */
+export declare function labelToolValidationFailure(issues: readonly string[]): void;
 export {};

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);
@@ -55,14 +69,42 @@ export function labelToolFailure(type, message) {
     if (message !== undefined)
         span.setAttribute("inflexa.tool.error", message.slice(0, TOOL_ERROR_MAX_CHARS));
 }
+/**
+ * Label a tool call whose input failed validation on the active `execute_tool`
+ * span. `issues` is the shape of the failure, with no value of the input.
+ */
+export function labelToolValidationFailure(issues) {
+    const span = trace.getActiveSpan();
+    if (span === undefined)
+        return;
+    span.setAttributes({ "error.type": "validation", "inflexa.tool.validation.issues": [...issues] });
+}
 function errorTypeOf(err) {
     const code = "code" in err ? err.code : undefined;
     if ((typeof code === "string" && code !== "") || typeof code === "number")
         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);
         }
@@ -86,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/metrics.d.ts

@@ -1,5 +1,5 @@
 /**
- * Agent-loop OTel metrics → Middleware.io.
+ * Agent-loop OTel metrics, exported through the global MeterProvider.
  *
  * Every `runAgent` completion records, keyed by `agent_id`:
  *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.

package/dist/loop/metrics.js

@@ -1,5 +1,5 @@
 /**
- * Agent-loop OTel metrics → Middleware.io.
+ * Agent-loop OTel metrics, exported through the global MeterProvider.
  *
  * Every `runAgent` completion records, keyed by `agent_id`:
  *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.

package/dist/loop/run-agent.js

@@ -3,8 +3,9 @@ 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";
 import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { stripUnansweredToolCalls } from "../memory/tool-call-integrity.js";
@@ -14,7 +15,7 @@ import { DEFAULT_REASONING } from "../providers/reasoning.js";
 import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
 import { isToolError, readToolResultImages } from "../tools/define-tool.js";
-import { labelToolFailure, recordToolException, traceAgentRun, traceToolCall } from "./genai-spans.js";
+import { labelToolFailure, labelToolValidationFailure, recordToolException, traceAgentRun, traceToolCall } from "./genai-spans.js";
 import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
 import { computeDetail, computeResultDetail } from "./tool-detail.js";
 import { toolOutcomeForOutputType } from "./tool-outcome.js";
@@ -24,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
@@ -70,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,
@@ -167,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
@@ -251,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
@@ -289,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
@@ -341,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 });
@@ -359,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
@@ -553,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;
@@ -617,8 +620,10 @@ async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
     const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
     if (repaired?.success === true)
         return execute(tu, tool, repaired.data, ctx, isFatalLoopError, encoding);
-    // The Zod text can quote the input, thus the span gets no message.
-    labelToolFailure("validation");
+    // The Zod text can quote the input, thus the span and the log get only the shape of the failure.
+    const issues = describeZodIssueShapes(parsed.error, tool.inputSchema);
+    labelToolValidationFailure(issues);
+    encoding.log.warn("tool call rejected", { tool: tool.id, toolCallId: tu.toolCallId, issues });
     return { result: errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`) };
 }
 async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {

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/tools/lib/alphafold-client.d.ts

@@ -14,8 +14,9 @@
  * identifier that does not parse as a UniProt accession or an AlphaFold DB id
  * gives 400 with an `Invalid identifier format` body. A well-formed accession
  * that AlphaFold holds no model for gives 404 with an empty object. Both are
- * the same outcome for a caller, and `isUnexpectedApiError` classifies each
- * `http_status` in the 4xx range as expected, thus one branch answers both.
+ * the same outcome for a caller, thus one branch answers both. Only these two
+ * codes mean absence. A different 4xx, such as a 403 refusal, throws, because
+ * `found: false` tells the agent to report the absence and not to retry.
  */
 import { z } from "zod";
 /**
@@ -46,7 +47,8 @@ export type AlphaFoldPrediction = z.infer<typeof AlphaFoldPredictionSchema>;
  * Fetch the AlphaFold structure prediction for one UniProt accession.
  *
  * Gives `null` when AlphaFold holds no model for the accession, and `null` for
- * an identifier it cannot parse. When the array holds more than one entry —
+ * an identifier it cannot parse. Throws on each other failure. When the array
+ * holds more than one entry —
  * the isoforms of one canonical accession — the entry whose own
  * `uniprotAccession` matches the queried accession wins. A query that names no
  * exact isoform falls back to the first entry, which AlphaFold orders

package/dist/tools/lib/alphafold-client.js

@@ -14,11 +14,12 @@
  * identifier that does not parse as a UniProt accession or an AlphaFold DB id
  * gives 400 with an `Invalid identifier format` body. A well-formed accession
  * that AlphaFold holds no model for gives 404 with an empty object. Both are
- * the same outcome for a caller, and `isUnexpectedApiError` classifies each
- * `http_status` in the 4xx range as expected, thus one branch answers both.
+ * the same outcome for a caller, thus one branch answers both. Only these two
+ * codes mean absence. A different 4xx, such as a 403 refusal, throws, because
+ * `found: false` tells the agent to report the absence and not to retry.
  */
 import { z } from "zod";
-import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
 const ALPHAFOLD_BASE = "https://alphafold.ebi.ac.uk/api/prediction";
 /**
  * One entry of the AlphaFold DB prediction array. A query by a canonical
@@ -50,7 +51,8 @@ export const AlphaFoldPredictionSchema = z.object({
  * Fetch the AlphaFold structure prediction for one UniProt accession.
  *
  * Gives `null` when AlphaFold holds no model for the accession, and `null` for
- * an identifier it cannot parse. When the array holds more than one entry —
+ * an identifier it cannot parse. Throws on each other failure. When the array
+ * holds more than one entry —
  * the isoforms of one canonical accession — the entry whose own
  * `uniprotAccession` matches the queried accession wins. A query that names no
  * exact isoform falls back to the first entry, which AlphaFold orders
@@ -60,9 +62,9 @@ export async function fetchAlphaFoldPrediction(uniprotAccession) {
     const accession = uniprotAccession.trim();
     const res = await apiFetchValidated(`${ALPHAFOLD_BASE}/${encodeURIComponent(accession)}`, z.array(AlphaFoldPredictionSchema));
     if (res.isErr()) {
-        if (isUnexpectedApiError(res.error))
-            throw new Error(describeApiError(res.error));
-        return null;
+        if (isAbsence(res.error))
+            return null;
+        throw new Error(describeApiError(res.error));
     }
     const entries = res.value;
     if (entries.length === 0)
@@ -70,3 +72,6 @@ export async function fetchAlphaFoldPrediction(uniprotAccession) {
     const exact = entries.find((entry) => entry.uniprotAccession.toUpperCase() === accession.toUpperCase());
     return exact ?? entries[0];
 }
+function isAbsence(e) {
+    return e.type === "http_status" && (e.status === 400 || e.status === 404);
+}

package/dist/tools/lib/api-utils.d.ts

@@ -48,6 +48,7 @@ export type ApiError = {
     readonly type: "invalid_response";
     readonly issues: string;
 };
+export declare const HARNESS_USER_AGENT = "inflexa-harness (+https://inflexa.ai)";
 /**
  * Fetch a URL with retry on 429/502/503/504, exponential backoff, and timeout.
  * `err` carries the structured failure; a non-ok HTTP status is reported as
@@ -61,6 +62,8 @@ export type ApiError = {
  *
  * Between two attempts the wait obeys `Retry-After` when the response carries it,
  * and every wait stays at or below `maxRetryDelayMs`.
+ *
+ * Each request sends `HARNESS_USER_AGENT`, unless `headers` sets a User-Agent.
  */
 export declare function apiFetch<T = unknown>(url: string, options?: ApiFetchOptions): ResultAsync<T, ApiError>;
 /**

package/dist/tools/lib/api-utils.js

@@ -15,6 +15,9 @@ import { sleep } from "../../lib/async-utils.js";
 // provider answers with one of them while the origin restarts, and it sends an
 // HTML body. That answer is transient, thus a retry gets the real payload.
 const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+// AlphaFold DB answers 403 to the default User-Agent of the runtime (`node`,
+// `Bun/<version>`, or none), and a descriptive value passes.
+export const HARNESS_USER_AGENT = "inflexa-harness (+https://inflexa.ai)";
 /**
  * Fetch a URL with retry on 429/502/503/504, exponential backoff, and timeout.
  * `err` carries the structured failure; a non-ok HTTP status is reported as
@@ -28,6 +31,8 @@ const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
  *
  * Between two attempts the wait obeys `Retry-After` when the response carries it,
  * and every wait stays at or below `maxRetryDelayMs`.
+ *
+ * Each request sends `HARNESS_USER_AGENT`, unless `headers` sets a User-Agent.
  */
 export function apiFetch(url, options = {}) {
     return new ResultAsync(runFetch(url, options));
@@ -92,12 +97,15 @@ function retryAfterMilliseconds(res) {
 }
 async function runFetch(url, options) {
     const { method = "GET", headers = {}, body, maxRetries = 3, retryDelayMs = 1000, maxRetryDelayMs = 30_000, sleep: wait = sleep, timeoutMs = 90_000, parseAs = "json", } = options;
+    const requestHeaders = new Headers(headers);
+    if (!requestHeaders.has("user-agent"))
+        requestHeaders.set("User-Agent", HARNESS_USER_AGENT);
     let lastError = "";
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             const res = await fetch(url, {
                 method,
-                headers,
+                headers: requestHeaders,
                 body,
                 signal: AbortSignal.timeout(timeoutMs),
             });

package/package.json

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