@inflexa-ai/harness 0.35.1 → 0.35.2

package/dist/execution/dbos-run-launcher.d.ts

@@ -1,7 +1,18 @@
 /**
  * DBOS realization of the `RunLauncher` seam — the single production adapter,
- * shared by every embedder. Host-neutral: it references only DBOS, which the harness
- * already depends on, so it ships in the harness.
+ * shared by every embedder. Host-neutral: it references only DBOS and the OTel
+ * API, which the harness already depends on, so it ships in the harness.
+ *
+ * A launch detaches the run from the caller's trace. The DBOS workflow span
+ * takes the active context as its parent, and the caller is a chat request
+ * (or another short-lived operation) whose span ends in milliseconds while the
+ * run lasts hours. So the launch opens a root span of its own, runs
+ * `startWorkflow` under it, and joins the two traces by a span link back to
+ * the originating span plus `inflexa.run_id` on both sides. With no
+ * TracerProvider registered every call here is a no-op on the API's
+ * non-recording span.
  */
 import type { RunLauncher } from "./run-launcher.js";
+/** Attribute carrying the run id on the originating span and on the run's root span. */
+export declare const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
 export declare function createDbosRunLauncher(): RunLauncher;

package/dist/execution/dbos-run-launcher.js

@@ -1,13 +1,38 @@
 /**
  * DBOS realization of the `RunLauncher` seam — the single production adapter,
- * shared by every embedder. Host-neutral: it references only DBOS, which the harness
- * already depends on, so it ships in the harness.
+ * shared by every embedder. Host-neutral: it references only DBOS and the OTel
+ * API, which the harness already depends on, so it ships in the harness.
+ *
+ * A launch detaches the run from the caller's trace. The DBOS workflow span
+ * takes the active context as its parent, and the caller is a chat request
+ * (or another short-lived operation) whose span ends in milliseconds while the
+ * run lasts hours. So the launch opens a root span of its own, runs
+ * `startWorkflow` under it, and joins the two traces by a span link back to
+ * the originating span plus `inflexa.run_id` on both sides. With no
+ * TracerProvider registered every call here is a no-op on the API's
+ * non-recording span.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { context, isSpanContextValid, ROOT_CONTEXT, trace } from "@opentelemetry/api";
+/** Attribute carrying the run id on the originating span and on the run's root span. */
+export const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
+const TRACER_NAME = "inflexa.harness.run-launcher";
 export function createDbosRunLauncher() {
     return {
         async launch(workflow, opts, input) {
-            await DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input);
+            const originating = trace.getSpan(context.active());
+            const links = [];
+            if (originating !== undefined && isSpanContextValid(originating.spanContext())) {
+                originating.setAttribute(ATTR_INFLEXA_RUN_ID, opts.workflowId);
+                links.push({ context: originating.spanContext() });
+            }
+            const root = trace.getTracer(TRACER_NAME).startSpan("launch run", { links, attributes: { [ATTR_INFLEXA_RUN_ID]: opts.workflowId } }, ROOT_CONTEXT);
+            try {
+                await context.with(trace.setSpan(ROOT_CONTEXT, root), () => DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input));
+            }
+            finally {
+                root.end();
+            }
         },
     };
 }

package/dist/execution/reconcile-manifest.js

@@ -23,7 +23,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { classifyWithinRoot, computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
-import { artifactReconcileDropped, lineageInputDropped } from "../lib/metrics.js";
+import { recordArtifactReconcileDropped, recordLineageInputDropped } from "../lib/metrics.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
     const logger = (input.logger ?? createNoopLogger()).named("reconcile-manifest").with({ runId, stepId, agentId });
@@ -62,7 +62,7 @@ export async function reconcileManifestWithDisk(input) {
                 logger.debug("dropping phantom entry", { path: entry.path });
                 collector.removeRecord(entry.path);
                 droppedCount++;
-                artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+                recordArtifactReconcileDropped({ agentId });
                 continue;
             }
             throw err;
@@ -75,7 +75,7 @@ export async function reconcileManifestWithDisk(input) {
             logger.debug("dropping non-file entry", { path: entry.path });
             collector.removeRecord(entry.path);
             droppedCount++;
-            artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+            recordArtifactReconcileDropped({ agentId });
             continue;
         }
         // The registration payload reads output hashes from `entries` (this
@@ -140,14 +140,14 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
         const containerPrefix = `/${resourceId}`;
         if (ref.path !== containerPrefix && !ref.path.startsWith(containerPrefix + "/")) {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, boundSite: "container-prefix" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "container-prefix" });
+            recordLineageInputDropped({ agentId, reason: "container-prefix" });
             collector.dropInput(ref);
             continue;
         }
         const hostPath = path.join(resourceRoot, ref.path.slice(containerPrefix.length + 1));
         if (hostPath !== resourceRoot && !hostPath.startsWith(resourceRoot + path.sep)) {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "workspace-root" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "workspace-root" });
+            recordLineageInputDropped({ agentId, reason: "workspace-root" });
             collector.dropInput(ref);
             continue;
         }
@@ -159,7 +159,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
         // verdict (a dangling link) falls through to the ENOENT drop below.
         if ((await classifyWithinRoot(resourceRoot, hostPath)) === "escaped") {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "realpath" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "symlink-escape" });
+            recordLineageInputDropped({ agentId, reason: "symlink-escape" });
             collector.dropInput(ref);
             continue;
         }
@@ -173,7 +173,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
                 // consumed, and the count of those is how a reader tells a noisy
                 // hook from an artifact that genuinely vanished under the step.
                 logger.warn("dropping input not present at reconcile from lineage", { ...attestation, hostPath, dropSite: "input-enoent" });
-                lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "missing" });
+                recordLineageInputDropped({ agentId, reason: "missing" });
                 collector.dropInput(ref);
                 continue;
             }
@@ -187,7 +187,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             // non-file drop above. A genuinely missing FILE (ENOENT) still fails fast
             // as drift; a directory is not drift.
             logger.debug("dropping non-file input from lineage", attestation);
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "directory" });
+            recordLineageInputDropped({ agentId, reason: "directory" });
             collector.dropInput(ref);
             continue;
         }

package/dist/lib/metrics.d.ts

@@ -4,6 +4,24 @@
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *
+ * Both carry `agent_id` (about 15 values) and never a per-step or per-run
+ * identifier: a label with unbounded values multiplies the series count.
+ *
+ * Instruments are lazy so the record site binds to whichever `MeterProvider`
+ * is globally registered at first use. The metrics API has no late-binding
+ * proxy: a meter taken at module load, before `initOtel` runs, would stay
+ * on the no-op provider for the life of the process.
  */
-export declare const artifactReconcileDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
-export declare const lineageInputDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Record one manifest entry dropped at reconcile. */
+export declare function recordArtifactReconcileDropped(args: {
+    readonly agentId: string;
+}): void;
+export type LineageInputDropReason = "container-prefix" | "workspace-root" | "symlink-escape" | "missing" | "directory";
+/** Record one tracked input read dropped from lineage at reconcile. */
+export declare function recordLineageInputDropped(args: {
+    readonly agentId: string;
+    readonly reason: LineageInputDropReason;
+}): void;
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export declare function __resetReconcileMetricsForTest(): void;

package/dist/lib/metrics.js

@@ -4,16 +4,44 @@
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *
+ * Both carry `agent_id` (about 15 values) and never a per-step or per-run
+ * identifier: a label with unbounded values multiplies the series count.
+ *
+ * Instruments are lazy so the record site binds to whichever `MeterProvider`
+ * is globally registered at first use. The metrics API has no late-binding
+ * proxy: a meter taken at module load, before `initOtel` runs, would stay
+ * on the no-op provider for the life of the process.
  */
 import { metrics } from "@opentelemetry/api";
-const meter = metrics.getMeter("cortex");
-export const artifactReconcileDropped = meter.createCounter("cortex.artifact.reconcile.dropped", {
-    description: "Manifest entries dropped because their on-disk file was missing at " +
-        "registration time (writes-then-deletes, renames). Tagged by agent_id, step_id.",
-});
-export const lineageInputDropped = meter.createCounter("cortex.artifact.reconcile.input_dropped", {
-    description: "Tracked input reads dropped from lineage at reconcile because they are " +
-        "not content-attestable files of the analysis (directory reads, " +
-        "out-of-tree resolutions, paths absent at reconcile). Tagged by " +
-        "agent_id, step_id, reason.",
-});
+let instruments;
+function getInstruments() {
+    if (instruments === undefined) {
+        const meter = metrics.getMeter("cortex");
+        instruments = {
+            artifactReconcileDropped: meter.createCounter("cortex.artifact.reconcile.dropped", {
+                description: "Manifest entries dropped because their on-disk file was missing at " +
+                    "registration time (writes-then-deletes, renames). Tagged by agent_id.",
+            }),
+            lineageInputDropped: meter.createCounter("cortex.artifact.reconcile.input_dropped", {
+                description: "Tracked input reads dropped from lineage at reconcile because they are " +
+                    "not content-attestable files of the analysis (directory reads, " +
+                    "out-of-tree resolutions, paths absent at reconcile). Tagged by " +
+                    "agent_id, reason.",
+            }),
+        };
+    }
+    return instruments;
+}
+/** Record one manifest entry dropped at reconcile. */
+export function recordArtifactReconcileDropped(args) {
+    getInstruments().artifactReconcileDropped.add(1, { agent_id: args.agentId });
+}
+/** Record one tracked input read dropped from lineage at reconcile. */
+export function recordLineageInputDropped(args) {
+    getInstruments().lineageInputDropped.add(1, { agent_id: args.agentId, reason: args.reason });
+}
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export function __resetReconcileMetricsForTest() {
+    instruments = undefined;
+}

package/dist/lib/otel.d.ts

@@ -1,14 +1,22 @@
 /**
  * OpenTelemetry SDK initialization — traces + metrics.
  *
- * Exported as `initOtel()` and called explicitly from index.ts to prevent
- * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ * 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.
  *
- * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *          is set. Custom Cortex metrics are defined in metrics.ts.
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
+ *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
+ *          metrics are defined in metrics.ts.
+ *
+ * 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
+ *           `deployment.environment.name` or override the service name without
+ *           a code change. 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,
@@ -16,16 +24,45 @@
  *        not currently wired.
  */
 import type { Logger } from "./logger.js";
+/** The SDK's own default when neither the host nor the environment says otherwise. */
+export declare const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60000;
+export interface InitOtelOptions {
+    /** Diagnostics sink; omitted falls back to no-op. */
+    readonly logger?: Logger;
+    /** `service.name` when `OTEL_SERVICE_NAME` is unset. Default `cortex`. */
+    readonly serviceName?: string;
+    /** `service.version` — the host's package version. Omitted leaves the attribute unset. */
+    readonly serviceVersion?: string;
+}
+/**
+ * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
+ * stays set for traces. Any other value (including unset) keeps the OTLP
+ * exporter, the only one the harness ships.
+ */
+export declare function metricsExportDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Export interval from `OTEL_METRIC_EXPORT_INTERVAL` (milliseconds). An unset,
+ * non-numeric, or non-positive value falls back to the 60 s default.
+ */
+export declare function metricExportIntervalMs(env?: NodeJS.ProcessEnv): number;
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
  * calls trace.getTracer() or metrics.getMeter().
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export declare function initOtel(injected?: Logger): void;
+export declare function initOtel(options?: InitOtelOptions): void;
 /**
  * Flush and shut down the OTel exporters. Called by the graceful-shutdown
  * sequence so in-flight batch spans/metrics make it to the collector
  * before the process exits. Never throws.
  */
 export declare function shutdownOtel(): Promise<void>;
+/**
+ * Test hook: shut the providers down and unregister every global the init
+ * touched, so a test can drive `initOtel` again under a different environment.
+ * Test-only.
+ */
+export declare function __resetOtelForTest(): Promise<void>;
+/** Test hook: whether `initOtel` registered a metric-exporting MeterProvider. Test-only. */
+export declare function __otelMeterProviderRegisteredForTest(): boolean;

package/dist/lib/otel.js

@@ -1,21 +1,29 @@
 /**
  * OpenTelemetry SDK initialization — traces + metrics.
  *
- * Exported as `initOtel()` and called explicitly from index.ts to prevent
- * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ * 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.
  *
- * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *          is set. Custom Cortex metrics are defined in metrics.ts.
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
+ *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
+ *          metrics are defined in metrics.ts.
+ *
+ * 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
+ *           `deployment.environment.name` or override the service name without
+ *           a code change. 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,
  *        so inbound/outbound trace-context propagation across those paths is
  *        not currently wired.
  */
-import { propagation, metrics, trace } from "@opentelemetry/api";
+import { context, propagation, metrics, trace } from "@opentelemetry/api";
 import { createNoopLogger } from "./console-logger.js";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
@@ -23,25 +31,59 @@ 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 { resourceFromAttributes } from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { 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;
 let initialized = false;
 let registeredTracerProvider;
 let registeredMeterProvider;
+/**
+ * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
+ * stays set for traces. Any other value (including unset) keeps the OTLP
+ * exporter, the only one the harness ships.
+ */
+export function metricsExportDisabled(env = process.env) {
+    return env.OTEL_METRICS_EXPORTER === "none";
+}
+/**
+ * Export interval from `OTEL_METRIC_EXPORT_INTERVAL` (milliseconds). An unset,
+ * non-numeric, or non-positive value falls back to the 60 s default.
+ */
+export function metricExportIntervalMs(env = process.env) {
+    const raw = env.OTEL_METRIC_EXPORT_INTERVAL;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_METRIC_EXPORT_INTERVAL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_METRIC_EXPORT_INTERVAL_MS;
+    return Math.floor(parsed);
+}
+function buildResource(options) {
+    const manual = {
+        [ATTR_SERVICE_NAME]: options.serviceName ?? "cortex",
+    };
+    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] }));
+}
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
  * calls trace.getTracer() or metrics.getMeter().
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export function initOtel(injected) {
+export function initOtel(options = {}) {
     if (initialized)
         return;
     initialized = true;
-    const logger = (injected ?? createNoopLogger()).named("otel");
+    const logger = (options.logger ?? createNoopLogger()).named("otel");
     // ── W3C Trace Context propagation ──────────────────────────────────
     propagation.setGlobalPropagator(new W3CTraceContextPropagator());
     const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    const resource = buildResource(options);
     // ── Traces ─────────────────────────────────────────────────────────
     // Always register a TracerProvider so trace.getTracer() returns real spans
     // with unique IDs. Without this, the OtelBridge gets no-op spans (all zeros)
@@ -52,10 +94,6 @@ export function initOtel(injected) {
             const base = endpoint.replace(/\/+$/, "");
             spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` })));
         }
-        const serviceName = process.env.OTEL_SERVICE_NAME || "cortex";
-        const resource = resourceFromAttributes({
-            [ATTR_SERVICE_NAME]: serviceName,
-        });
         const tracerProvider = new NodeTracerProvider({
             resource,
             spanProcessors,
@@ -71,20 +109,29 @@ export function initOtel(injected) {
         // `initTelemetry: () => {}` — its TUI owns stdout, so the banner corrupted
         // the screen and the whole of the harness's traces + metrics were switched
         // off to avoid it. At debug through the injected seam it costs nothing.
-        logger.debug("TracerProvider registered", { spanId: ctx.spanId, noop: isNoop, endpoint: endpoint ?? null, processors: spanProcessors.length });
+        logger.debug("TracerProvider registered", {
+            spanId: ctx.spanId,
+            noop: isNoop,
+            endpoint: endpoint ?? null,
+            processors: spanProcessors.length,
+            resource: resource.attributes,
+        });
         testSpan.end();
     }
     // ── Metrics ────────────────────────────────────────────────────────
-    if (endpoint) {
+    // With no MeterProvider registered the API's global no-op provider serves
+    // every instrument, so the record sites stay valid when export is off.
+    if (endpoint && !metricsExportDisabled()) {
         const base = endpoint.replace(/\/+$/, "");
         const metricExporter = new OTLPMetricExporter({
             url: `${base}/v1/metrics`,
         });
         const meterProvider = new MeterProvider({
+            resource,
             readers: [
                 new PeriodicExportingMetricReader({
                     exporter: metricExporter,
-                    exportIntervalMillis: 30_000,
+                    exportIntervalMillis: metricExportIntervalMs(),
                 }),
             ],
         });
@@ -105,3 +152,22 @@ export async function shutdownOtel() {
         tasks.push(registeredMeterProvider.shutdown());
     await Promise.allSettled(tasks);
 }
+/**
+ * Test hook: shut the providers down and unregister every global the init
+ * touched, so a test can drive `initOtel` again under a different environment.
+ * Test-only.
+ */
+export async function __resetOtelForTest() {
+    await shutdownOtel();
+    registeredTracerProvider = undefined;
+    registeredMeterProvider = undefined;
+    trace.disable();
+    metrics.disable();
+    context.disable();
+    propagation.disable();
+    initialized = false;
+}
+/** Test hook: whether `initOtel` registered a metric-exporting MeterProvider. Test-only. */
+export function __otelMeterProviderRegisteredForTest() {
+    return registeredMeterProvider !== undefined;
+}

package/dist/runtime/dbos.d.ts

@@ -12,6 +12,7 @@
  *
  * See `openspec/changes/harness-dbos-runtime`.
  */
+import { type DBOSConfig, type DLogger } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
 /**
@@ -31,18 +32,60 @@ export interface DbosConfig {
     /** Stable per-pod executor id (e.g. `process.env.HOSTNAME ?? "local-dev"`). */
     readonly executorId: string;
     /**
-     * SDK log verbosity (winston levels; the SDK's own default is `info`).
-     * Interactive embedders pass `warn` so the launch banner and migration
-     * chatter don't interleave with their own command output; the server root
-     * omits it and keeps the informative default.
+     * Least severe SDK record forwarded to the host's `Logger` (winston level
+     * names; the SDK's own default is `info`). The SDK's lines ride the
+     * harness `Logger` seam under `[dbos.sdk]`, so this threshold is applied by
+     * the bridge, not by the SDK. Interactive embedders pass `warn` so the
+     * launch banner and migration chatter stay out of their logs; the server
+     * root omits it and keeps the informative default.
      */
     readonly logLevel?: string;
+    /**
+     * Emit DBOS workflow and step spans on the globally registered
+     * TracerProvider, and run every workflow and step body under an active
+     * OTel context. Default `false`.
+     *
+     * DBOS installs nothing of its own here: with no OTLP endpoint of its own it
+     * probes the global provider and, when one is registered, emits under the
+     * instrumentation scope `dbos-tracer` through that provider's processors.
+     * A host that registers no provider (the CLI passes a no-op
+     * `initTelemetry`) must leave this off, otherwise the SDK installs its own
+     * `BasicTracerProvider` and every span is created and never exported.
+     *
+     * Attribute names follow the `dbos.*` semantic-convention layout
+     * (`otelAttributeFormat: "semconv"`).
+     *
+     * 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
+     * - every already-completed step re-emits a `cached=true` span on replay,
+     *   so a restart with many in-flight steps bursts spans; size
+     *   `OTEL_BSP_MAX_QUEUE_SIZE` for it
+     * - step span names embed the step, tool-use, or exec id
+     */
+    readonly tracingEnabled?: boolean;
 }
 /** DBOS lifecycle facts a host's readiness probe reports on. */
 export interface DbosState {
     launched: boolean;
     recoveryStarted: boolean;
 }
+/**
+ * Bridge the SDK's internal logger onto the harness `Logger` seam, so the
+ * SDK's own lines (`Recovering N workflows…`, migration chatter) land in the
+ * host's sink instead of on the process console. The SDK does not filter by
+ * `logLevel` before it delegates to a custom logger, so the threshold is
+ * applied here. Records arrive as strings; an `Error` arrives as its message
+ * with the stack (and cause chain) in `metadata.stack`; inside a workflow or
+ * step body `metadata.span.attributes` carries the operation context, which
+ * rides as fields.
+ */
+export declare function dbosSdkLogger(logger: Logger, logLevel: string | undefined): DLogger;
+/**
+ * The SDK config `launchDbos` sets. Pure over `DbosConfig`, so a test can
+ * assert on the mapping without a launch.
+ */
+export declare function dbosSdkConfig(config: DbosConfig, logger: Logger): DBOSConfig;
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.

package/dist/runtime/dbos.js

@@ -45,6 +45,76 @@ function systemDatabaseUrl(config) {
     const database = encodeURIComponent(config.dbName);
     return `postgresql://${user}:${password}@${host}:${port}/${database}?sslmode=${dbosSslMode(config.dbSslMode)}`;
 }
+/** Winston severity ranks, ascending verbosity — the scale `DbosConfig.logLevel` names. */
+const SDK_LOG_LEVEL_RANK = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    http: 3,
+    verbose: 4,
+    debug: 5,
+    silly: 6,
+};
+const SDK_DEFAULT_LOG_LEVEL = "info";
+/**
+ * Bridge the SDK's internal logger onto the harness `Logger` seam, so the
+ * SDK's own lines (`Recovering N workflows…`, migration chatter) land in the
+ * host's sink instead of on the process console. The SDK does not filter by
+ * `logLevel` before it delegates to a custom logger, so the threshold is
+ * applied here. Records arrive as strings; an `Error` arrives as its message
+ * with the stack (and cause chain) in `metadata.stack`; inside a workflow or
+ * step body `metadata.span.attributes` carries the operation context, which
+ * rides as fields.
+ */
+export function dbosSdkLogger(logger, logLevel) {
+    const sink = logger.named("sdk");
+    const threshold = SDK_LOG_LEVEL_RANK[logLevel ?? SDK_DEFAULT_LOG_LEVEL] ?? SDK_LOG_LEVEL_RANK[SDK_DEFAULT_LOG_LEVEL];
+    const passes = (level) => SDK_LOG_LEVEL_RANK[level] <= threshold;
+    const fields = (metadata) => {
+        const attributes = metadata?.span?.attributes;
+        const stack = metadata?.stack;
+        if (attributes === undefined && stack === undefined)
+            return undefined;
+        return { ...attributes, ...(stack !== undefined ? { stack } : {}) };
+    };
+    const message = (entry) => (typeof entry === "string" ? entry : String(entry));
+    return {
+        debug: (entry, metadata) => {
+            if (passes("debug"))
+                sink.debug(message(entry), fields(metadata));
+        },
+        info: (entry, metadata) => {
+            if (passes("info"))
+                sink.info(message(entry), fields(metadata));
+        },
+        warn: (entry, metadata) => {
+            if (passes("warn"))
+                sink.warn(message(entry), fields(metadata));
+        },
+        error: (entry, metadata) => {
+            if (passes("error"))
+                sink.error(message(entry), fields(metadata));
+        },
+    };
+}
+/**
+ * The SDK config `launchDbos` sets. Pure over `DbosConfig`, so a test can
+ * assert on the mapping without a launch.
+ */
+export function dbosSdkConfig(config, logger) {
+    return {
+        name: config.appName,
+        systemDatabaseUrl: systemDatabaseUrl(config),
+        systemDatabasePoolSize: DBOS_SYSTEM_POOL_SIZE,
+        executorID: config.executorId,
+        applicationVersion: config.applicationVersion,
+        adminPort: parseInt(config.adminPort, 10),
+        logLevel: config.logLevel,
+        logger: dbosSdkLogger(logger, config.logLevel),
+        tracingEnabled: config.tracingEnabled ?? false,
+        otelAttributeFormat: "semconv",
+    };
+}
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.
@@ -57,25 +127,17 @@ export async function launchDbos({ config, logger: injected }) {
     if (state.launched)
         return;
     const logger = injected.named("dbos");
-    const executorID = config.executorId;
-    const adminPort = parseInt(config.adminPort, 10);
-    DBOS.setConfig({
-        name: config.appName,
-        systemDatabaseUrl: systemDatabaseUrl(config),
-        systemDatabasePoolSize: DBOS_SYSTEM_POOL_SIZE,
-        executorID,
-        applicationVersion: config.applicationVersion,
-        adminPort,
-        logLevel: config.logLevel,
-    });
+    const sdkConfig = dbosSdkConfig(config, logger);
+    DBOS.setConfig(sdkConfig);
     const start = performance.now();
     await DBOS.launch();
     state.launched = true;
     state.recoveryStarted = true;
     logger.info("launched", {
-        executorID,
+        executorID: sdkConfig.executorID,
         applicationVersion: config.applicationVersion,
-        adminPort,
+        adminPort: sdkConfig.adminPort,
+        tracingEnabled: sdkConfig.tracingEnabled,
         durationMs: Math.round(performance.now() - start),
     });
 }

package/dist/workflows/metrics.d.ts

@@ -1,15 +1,10 @@
 /**
- * Workflow-side OTel metrics → Middleware.io.
+ * Workflow-side OTel metrics.
  *
- * Two signals so 3-hour runs and pause-resume cascades are observable:
  *   - cortex.workflow.parent.cancelled_children — counter, incremented once
  *     per child the fail-fast or pause cascade reaps. A baseline near 0
  *     means runs land cleanly; a spike means siblings keep colliding with
  *     a single failing step.
- *   - cortex.workflow.stream.bytes               — counter, incremented by
- *     the byte count of every UI part written onto the DBOS stream. The
- *     leading indicator for 3-hour stream growth is monotonic — a runaway
- *     emitter shows up as an unbounded slope.
  *
  * Instruments are lazy so the workflow body binds to whichever
  * `MeterProvider` is globally registered at startup.
@@ -23,15 +18,5 @@
 export declare function recordCancelledChild(args: {
     readonly cause: "fail_fast" | "budget_exceeded" | "external_cancel";
 }): void;
-/**
- * Record one UI-part write. `bytes` is the serialised JSON size of the
- * part as it lands on the stream; `kind` is the part `type` for
- * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
- * so a single emitter records once per part.
- */
-export declare function recordStreamWrite(args: {
-    readonly bytes: number;
-    readonly kind: string;
-}): void;
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export declare function __resetWorkflowMetricsForTest(): void;

package/dist/workflows/metrics.js

@@ -1,15 +1,10 @@
 /**
- * Workflow-side OTel metrics → Middleware.io.
+ * Workflow-side OTel metrics.
  *
- * Two signals so 3-hour runs and pause-resume cascades are observable:
  *   - cortex.workflow.parent.cancelled_children — counter, incremented once
  *     per child the fail-fast or pause cascade reaps. A baseline near 0
  *     means runs land cleanly; a spike means siblings keep colliding with
  *     a single failing step.
- *   - cortex.workflow.stream.bytes               — counter, incremented by
- *     the byte count of every UI part written onto the DBOS stream. The
- *     leading indicator for 3-hour stream growth is monotonic — a runaway
- *     emitter shows up as an unbounded slope.
  *
  * Instruments are lazy so the workflow body binds to whichever
  * `MeterProvider` is globally registered at startup.
@@ -23,10 +18,6 @@ function getInstruments() {
             cancelledChildren: meter.createCounter("cortex.workflow.parent.cancelled_children", {
                 description: "Children cancelled by the parent's fail-fast or pause cascade",
             }),
-            streamBytes: meter.createCounter("cortex.workflow.stream.bytes", {
-                description: "Bytes written to the parent's DBOS UI-parts stream — proxy for " + "3-hour stream growth",
-                unit: "By",
-            }),
         };
     }
     return instruments;
@@ -40,15 +31,6 @@ function getInstruments() {
 export function recordCancelledChild(args) {
     getInstruments().cancelledChildren.add(1, { cause: args.cause });
 }
-/**
- * Record one UI-part write. `bytes` is the serialised JSON size of the
- * part as it lands on the stream; `kind` is the part `type` for
- * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
- * so a single emitter records once per part.
- */
-export function recordStreamWrite(args) {
-    getInstruments().streamBytes.add(args.bytes, { kind: args.kind });
-}
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export function __resetWorkflowMetricsForTest() {
     instruments = undefined;

package/package.json

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