@llm4ts/runner 2.29.0 → 2.30.0

package/dist/Otel.js

@@ -0,0 +1,140 @@
+// OpenTelemetry export (ADR 0026): Effect's own OTLP tracer and metrics
+// exporters over core's fetch client, so a run can show up in Phoenix,
+// Langfuse, SigNoz or any collector with no SDK and no new dependency.
+// The standard OTEL_* variables are the truth; `--otel` is the laptop case.
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as OtlpExporter from "effect/observability/OtlpExporter";
+import * as OtlpMetrics from "effect/observability/OtlpMetrics";
+import * as OtlpSerialization from "effect/observability/OtlpSerialization";
+import * as OtlpTracer from "effect/observability/OtlpTracer";
+import { packageVersion } from "./Package.js";
+export const phoenixTracesUrl = "http://localhost:6006/v1/traces";
+const truthy = (value) => /^(on|1|true|yes)$/iu.test(value?.trim() ?? "");
+const falsy = (value) => /^(off|0|false|no)$/iu.test(value?.trim() ?? "");
+/**
+ * Off unless asked. An OTLP endpoint in the environment wins and is used as
+ * the standard variables say; `LLM4TS_OTEL=on` alone means a local Phoenix,
+ * traces only. `OTEL_SDK_DISABLED` or `LLM4TS_OTEL=off` switch everything off.
+ */
+export const otelConfig = (environment) => {
+    if (truthy(environment.OTEL_SDK_DISABLED) || falsy(environment.LLM4TS_OTEL)) {
+        return { mode: "off" };
+    }
+    // Under the test runner the exporter's sleeps run on a TestClock nobody
+    // advances, so its final flush would wait forever: a developer with
+    // LLM4TS_OTEL=on in the shell must still get a green suite.
+    if (environment.VITEST !== undefined) {
+        return { mode: "off" };
+    }
+    const endpoint = environment.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim() ||
+        environment.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    if (endpoint !== undefined && endpoint.length > 0) {
+        return { mode: "env", endpoint };
+    }
+    return truthy(environment.LLM4TS_OTEL)
+        ? { mode: "phoenix", tracesUrl: phoenixTracesUrl }
+        : { mode: "off" };
+};
+/** The run end may wait this long for the last batch; the event drain waits the same. */
+export const flushTimeout = Duration.seconds(3);
+/** This runner's version, for `service.version`. */
+export const runnerVersion = packageVersion;
+const resourceOf = (resource) => ({
+    serviceName: "llm4ts",
+    serviceVersion: resource.serviceVersion,
+    attributes: { "openinference.project.name": resource.project }
+});
+/**
+ * The exporter for `config`: nothing when off; traces only for Phoenix;
+ * traces and metrics from the standard variables for a generic endpoint.
+ * Logs are never exported. Export errors are the exporter's to swallow; the
+ * run never fails on them.
+ */
+export const otelLayer = (config, resource, 
+/** What the standard variables are read from in env mode (the run's environment). */
+environment = process.env) => {
+    switch (config.mode) {
+        case "off":
+            // The exporter's no-op flusher: nothing to export, nothing to flush.
+            return OtlpExporter.layerFlusher;
+        case "phoenix":
+            return OtlpTracer.layer({
+                url: config.tracesUrl,
+                resource: resourceOf(resource),
+                shutdownTimeout: flushTimeout
+            }).pipe(Layer.provide(OtlpSerialization.layerJson), Layer.provide(FetchHttpClient.layer));
+        case "env":
+            // The standard variables are read from the run's own environment, with
+            // the two exporter defaults an endpoint implies; the process env is
+            // never written.
+            return Layer.mergeAll(OtlpTracer.layerFromConfig({ resource: resourceOf(resource) }), OtlpMetrics.layerFromConfig({ resource: resourceOf(resource) })).pipe(Layer.provide(OtlpSerialization.layerJson), Layer.provide(FetchHttpClient.layer), Layer.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord({
+                ...environment,
+                ...otelEnvironmentDefaults(config, environment)
+            }))));
+    }
+};
+/**
+ * `layerFromConfig` exports nothing unless `OTEL_TRACES_EXPORTER` names
+ * `otlp`; an endpoint in the environment is the operator's intent, so the
+ * layer reads its variables with that default (and the metrics one) added
+ * when they are unset.
+ */
+export const otelEnvironmentDefaults = (config, environment) => config.mode !== "env"
+    ? {}
+    : {
+        ...(environment.OTEL_TRACES_EXPORTER === undefined ? { OTEL_TRACES_EXPORTER: "otlp" } : {}),
+        ...(environment.OTEL_METRICS_EXPORTER === undefined
+            ? { OTEL_METRICS_EXPORTER: "otlp" }
+            : {})
+    };
+export const otelSummary = (config) => {
+    switch (config.mode) {
+        case "off":
+            return undefined;
+        case "phoenix":
+            return `otel → Phoenix at ${config.tracesUrl} (traces)`;
+        case "env":
+            return `otel → ${config.endpoint} (traces + metrics, OTEL_* variables)`;
+    }
+};
+/**
+ * The one warning a run prints when export is on and nothing answers at the
+ * endpoint (spec §9): the exporter itself only logs at debug level and drops
+ * the batch. Nothing when off or when the endpoint answered.
+ */
+export const otelWarning = (config, answers) => {
+    if (config.mode === "off" || answers !== false) {
+        return undefined;
+    }
+    const where = config.mode === "phoenix" ? config.tracesUrl : config.endpoint;
+    return (`⚠ otel: nothing answers at ${where} — spans will be dropped (the run is unaffected)` +
+        (config.mode === "phoenix"
+            ? "; start Phoenix with `docker run -p 6006:6006 arizephoenix/phoenix:latest`"
+            : ""));
+};
+/** The doctor's line: `answers` is the probe's result, undefined when export is off. */
+export const otelDoctorLine = (config, answers) => {
+    switch (config.mode) {
+        case "off":
+            return "otel: off (LLM4TS_OTEL=on for a local Phoenix, or OTEL_EXPORTER_OTLP_ENDPOINT)";
+        case "phoenix":
+        case "env": {
+            const where = config.mode === "phoenix" ? `Phoenix at ${config.tracesUrl}` : config.endpoint;
+            return `otel: ${where} — ${answers === true
+                ? "endpoint answers"
+                : "endpoint does not answer (spans will be dropped, the run is unaffected)"}`;
+        }
+    }
+};
+/** Whether anything listens at the endpoint: any HTTP answer counts, a refused connection does not. */
+export const probeOtelEndpoint = (config) => config.mode === "off"
+    ? Effect.succeed(undefined)
+    : Effect.tryPromise(() => fetch(config.mode === "phoenix" ? config.tracesUrl : config.endpoint, {
+        method: "OPTIONS",
+        signal: AbortSignal.timeout(1_500)
+    })).pipe(Effect.as(true), Effect.orElseSucceed(() => false));
+//# sourceMappingURL=Otel.js.map

package/dist/Otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Otel.js","sourceRoot":"","sources":["../src/Otel.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,4EAA4E;AAC5E,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,eAAe,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,YAAY,MAAM,mCAAmC,CAAA;AACjE,OAAO,KAAK,WAAW,MAAM,kCAAkC,CAAA;AAC/D,OAAO,KAAK,iBAAiB,MAAM,wCAAwC,CAAA;AAC3E,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAO7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,iCAAiC,CAAA;AAEjE,MAAM,MAAM,GAAG,CAAC,KAAyB,EAAW,EAAE,CACpD,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;AACjD,MAAM,KAAK,GAAG,CAAC,KAAyB,EAAW,EAAE,CACnD,sBAAsB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,WAAyD,EAC7C,EAAE;IACd,IAAI,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5E,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;IACxB,CAAC;IACD,wEAAwE;IACxE,oEAAoE;IACpE,4DAA4D;IAC5D,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;IACxB,CAAC;IACD,MAAM,QAAQ,GACZ,WAAW,CAAC,kCAAkC,EAAE,IAAI,EAAE;QACtD,WAAW,CAAC,2BAA2B,EAAE,IAAI,EAAE,CAAA;IACjD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CAAC,WAAW,CAAC;QACpC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE;QAClD,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;AACrB,CAAC,CAAA;AAQD,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAE/C,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAAW,cAAc,CAAA;AAEnD,MAAM,UAAU,GAAG,CAAC,QAAsB,EAAE,EAAE,CAAC,CAAC;IAC9C,WAAW,EAAE,QAAQ;IACrB,cAAc,EAAE,QAAQ,CAAC,cAAc;IACvC,UAAU,EAAE,EAAE,4BAA4B,EAAE,QAAQ,CAAC,OAAO,EAAE;CAC/D,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,MAAkB,EAClB,QAAsB;AACtB,qFAAqF;AACrF,cAA4D,OAAO,CAAC,GAAG,EACpC,EAAE;IACrC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,qEAAqE;YACrE,OAAO,YAAY,CAAC,YAAY,CAAA;QAClC,KAAK,SAAS;YACZ,OAAO,UAAU,CAAC,KAAK,CAAC;gBACtB,GAAG,EAAE,MAAM,CAAC,SAAS;gBACrB,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC;gBAC9B,eAAe,EAAE,YAAY;aAC9B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAA;QAC3F,KAAK,KAAK;YACR,uEAAuE;YACvE,oEAAoE;YACpE,iBAAiB;YACjB,OAAO,KAAK,CAAC,QAAQ,CACnB,UAAU,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAC9D,WAAW,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,CAChE,CAAC,IAAI,CACJ,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAC1C,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,EACpC,KAAK,CAAC,OAAO,CACX,cAAc,CAAC,KAAK,CAClB,cAAc,CAAC,aAAa,CAAC;gBAC3B,GAAG,WAAW;gBACd,GAAG,uBAAuB,CAAC,MAAM,EAAE,WAAW,CAAC;aAChD,CAAC,CACH,CACF,CACF,CAAA;IACL,CAAC;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,MAAkB,EAClB,WAAyD,EACvB,EAAE,CACpC,MAAM,CAAC,IAAI,KAAK,KAAK;IACnB,CAAC,CAAC,EAAE;IACJ,CAAC,CAAC;QACE,GAAG,CAAC,WAAW,CAAC,oBAAoB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3F,GAAG,CAAC,WAAW,CAAC,qBAAqB,KAAK,SAAS;YACjD,CAAC,CAAC,EAAE,qBAAqB,EAAE,MAAM,EAAE;YACnC,CAAC,CAAC,EAAE,CAAC;KACR,CAAA;AAEP,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAkB,EAAsB,EAAE;IACpE,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,OAAO,SAAS,CAAA;QAClB,KAAK,SAAS;YACZ,OAAO,qBAAqB,MAAM,CAAC,SAAS,WAAW,CAAA;QACzD,KAAK,KAAK;YACR,OAAO,UAAU,MAAM,CAAC,QAAQ,uCAAuC,CAAA;IAC3E,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,MAAkB,EAClB,OAA4B,EACR,EAAE;IACtB,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;QAC/C,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAA;IAC5E,OAAO,CACL,8BAA8B,KAAK,kDAAkD;QACrF,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS;YACxB,CAAC,CAAC,4EAA4E;YAC9E,CAAC,CAAC,EAAE,CAAC,CACR,CAAA;AACH,CAAC,CAAA;AAED,wFAAwF;AACxF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAkB,EAAE,OAA4B,EAAU,EAAE;IACzF,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,OAAO,gFAAgF,CAAA;QACzF,KAAK,SAAS,CAAC;QACf,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAA;YAC5F,OAAO,SAAS,KAAK,MACnB,OAAO,KAAK,IAAI;gBACd,CAAC,CAAC,kBAAkB;gBACpB,CAAC,CAAC,yEACN,EAAE,CAAA;QACJ,CAAC;IACH,CAAC;AACH,CAAC,CAAA;AAED,uGAAuG;AACvG,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAkB,EAAsC,EAAE,CAC1F,MAAM,CAAC,IAAI,KAAK,KAAK;IACnB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;IAC3B,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,CACrB,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE;QACpE,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC;KACnC,CAAC,CACH,CAAC,IAAI,CACJ,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EACf,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAClC,CAAA"}

package/dist/Package.d.ts

@@ -1,2 +1,3 @@
 export declare const packageName = "@llm4ts/runner";
+export declare const packageVersion: string;
 //# sourceMappingURL=Package.d.ts.map

package/dist/Package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Package.d.ts","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,mBAAmB,CAAA"}
+{"version":3,"file":"Package.d.ts","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,WAAW,mBAAmB,CAAA;AAC3C,eAAO,MAAM,cAAc,EAAE,MAAyB,CAAA"}

package/dist/Package.js

@@ -1,2 +1,7 @@
+import { createRequire } from "node:module";
+import * as Schema from "effect/Schema";
+const Manifest = Schema.Struct({ version: Schema.String });
+const manifest = Schema.decodeUnknownSync(Manifest)(createRequire(import.meta.url)("../package.json"));
 export const packageName = "@llm4ts/runner";
+export const packageVersion = manifest.version;
 //# sourceMappingURL=Package.js.map

package/dist/Package.js.map

@@ -1 +1 @@
-{"version":3,"file":"Package.js","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,gBAAgB,CAAA"}
+{"version":3,"file":"Package.js","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;AAE1D,MAAM,QAAQ,GAAG,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CACjD,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAClD,CAAA;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,gBAAgB,CAAA;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAW,QAAQ,CAAC,OAAO,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/runner",
-  "version": "2.29.0",
+  "version": "2.30.0",
   "description": "Node runner, CLI, terminal, and MCP composition for llm4ts",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,7 @@
     "./NodeProcessExecutor": "./dist/NodeProcessExecutor.js",
     "./NodeTemporaryFiles": "./dist/NodeTemporaryFiles.js",
     "./NodeWorkspace": "./dist/NodeWorkspace.js",
+    "./Otel": "./dist/Otel.js",
     "./NodeRuntime": "./dist/NodeRuntime.js",
     "./Packs": "./dist/Packs.js",
     "./Profile": "./dist/Profile.js",
@@ -68,8 +69,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "2.29.0",
-    "@llm4ts/flow": "2.29.0"
+    "@llm4ts/core": "2.30.0",
+    "@llm4ts/flow": "2.30.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/Doctor.ts

@@ -11,6 +11,7 @@ import {
   geminiBridgePort as bridgePort,
   piModelsConfig as parsePiModels
 } from "./PiModels.ts"
+import { otelConfig, otelDoctorLine, probeOtelEndpoint, type OtelConfig } from "./Otel.ts"
 
 const credentialKeys = [
   "OPENAI_API_KEY",
@@ -220,65 +221,75 @@ export const makeDoctorProgram = (
     nodePlainFileStore,
     process.cwd(),
     environment
-  )
-): Effect.Effect<string> =>
-  Effect.map(Effect.all([registry.healthCheckAll, nodeCheck]), ([statuses, node]) => {
-    const lines: Array<string> = []
-    lines.push("llm4ts doctor")
-    lines.push("")
-    lines.push("connectors:")
-    const sorted = Array.from(statuses.entries()).sort(([a], [b]) => a.value.localeCompare(b.value))
-    for (const [id, status] of sorted) {
-      lines.push(statusLine(id.value, status))
-    }
-    lines.push("")
-    lines.push("credentials:")
-    for (const key of credentialKeys) {
-      const value = environment[key]
-      lines.push(`  ${value === undefined || value.length === 0 ? "✖" : "✔"} ${key}`)
-    }
-    lines.push("")
-    lines.push("gates:")
-    lines.push(
-      ...wrap(
-        `${node._tag === "Mismatch" || node._tag === "NoNode" ? "✖" : "✔"} ${node.summary}`,
-        78,
-        "  "
-      )
-    )
-
-    // Connector prerequisites the environment must carry BEFORE a run: shown
-    // when the connector is selected or the machine has its CLI, because that
-    // is exactly when a missing one turns into a confusing mid-run failure.
-    const coder = selectedCoder(environment)
-    const geminiRelevant =
-      coder.startsWith("gemini") ||
-      Array.from(statuses.keys()).some(
-        (id) =>
-          id.value === ConnectorIds.GeminiCli.value || id.value === ConnectorIds.GeminiApi.value
+  ),
+  /** Whether the OTLP endpoint answers (ADR 0026); the network probe by default. */
+  probeOtel: (config: OtelConfig) => Effect.Effect<boolean | undefined> = probeOtelEndpoint
+): Effect.Effect<string> => {
+  const otel = otelConfig(environment)
+  return Effect.map(
+    Effect.all([registry.healthCheckAll, nodeCheck, probeOtel(otel)]),
+    ([statuses, node, otelAnswers]) => {
+      const lines: Array<string> = []
+      lines.push("llm4ts doctor")
+      lines.push("")
+      lines.push("connectors:")
+      const sorted = Array.from(statuses.entries()).sort(([a], [b]) =>
+        a.value.localeCompare(b.value)
       )
-    const bridge = geminiBridgePrerequisites(environment, readPiModelsJson())
-    if (geminiRelevant || bridge !== undefined) {
+      for (const [id, status] of sorted) {
+        lines.push(statusLine(id.value, status))
+      }
       lines.push("")
-      lines.push("prerequisites:")
-      const pushReport = (label: string, report: PrerequisiteReport): void => {
-        lines.push(`  ${report.satisfied ? "✔" : "?"} ${label}: ${report.summary}`)
-        if (report.hint !== undefined) {
-          lines.push(...wrap(report.hint, 78, "      "))
+      lines.push("credentials:")
+      for (const key of credentialKeys) {
+        const value = environment[key]
+        lines.push(`  ${value === undefined || value.length === 0 ? "✖" : "✔"} ${key}`)
+      }
+      lines.push("")
+      lines.push("gates:")
+      lines.push(
+        ...wrap(
+          `${node._tag === "Mismatch" || node._tag === "NoNode" ? "✖" : "✔"} ${node.summary}`,
+          78,
+          "  "
+        )
+      )
+
+      // Connector prerequisites the environment must carry BEFORE a run: shown
+      // when the connector is selected or the machine has its CLI, because that
+      // is exactly when a missing one turns into a confusing mid-run failure.
+      const coder = selectedCoder(environment)
+      const geminiRelevant =
+        coder.startsWith("gemini") ||
+        Array.from(statuses.keys()).some(
+          (id) =>
+            id.value === ConnectorIds.GeminiCli.value || id.value === ConnectorIds.GeminiApi.value
+        )
+      const bridge = geminiBridgePrerequisites(environment, readPiModelsJson())
+      if (geminiRelevant || bridge !== undefined) {
+        lines.push("")
+        lines.push("prerequisites:")
+        const pushReport = (label: string, report: PrerequisiteReport): void => {
+          lines.push(`  ${report.satisfied ? "✔" : "?"} ${label}: ${report.summary}`)
+          if (report.hint !== undefined) {
+            lines.push(...wrap(report.hint, 78, "      "))
+          }
+          for (const line of report.detail ?? []) {
+            lines.push(`      ${line}`)
+          }
         }
-        for (const line of report.detail ?? []) {
-          lines.push(`      ${line}`)
+        if (geminiRelevant) {
+          pushReport("gemini", geminiPrerequisites(environment))
+        }
+        if (bridge !== undefined) {
+          pushReport("pi-gemini-bridge", bridge)
         }
       }
-      if (geminiRelevant) {
-        pushReport("gemini", geminiPrerequisites(environment))
-      }
-      if (bridge !== undefined) {
-        pushReport("pi-gemini-bridge", bridge)
-      }
-    }
 
-    lines.push("")
-    lines.push(`coder: ${coder}`)
-    return `${lines.join("\n")}\n`
-  })
+      lines.push("")
+      lines.push(otelDoctorLine(otel, otelAnswers))
+      lines.push(`coder: ${coder}`)
+      return `${lines.join("\n")}\n`
+    }
+  )
+}

package/src/FlowArgs.ts

@@ -34,6 +34,8 @@ environment:
   LLM4TS_VERBOSITY        terminal verbosity: quiet|normal|verbose
   LLM4TS_UI               tree: the full-screen agent tree (ADR 0022; q returns to the classic view)
   LLM4TS_TRANSCRIPT       on: record each seat's input and output under .llm4ts/transcripts/
+  LLM4TS_OTEL             on: export spans over OTLP (a local Phoenix at localhost:6006 unless OTEL_* says otherwise)
+  LLM4TS_OTEL_CONTENT     on|full: prompts, replies and tool I/O travel too (off by default)
   OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY
                           credentials for API providers
 

package/src/FlowRunner.ts

@@ -58,7 +58,18 @@ import {
 } from "@llm4ts/flow/FlowEvents"
 import { FlowContext, type ContextOptions, type FlowContextShape } from "@llm4ts/flow/FlowContext"
 import { makeFlowRecorder, type RunOutcome } from "@llm4ts/flow/FlowRecorder"
-import { timedJudgment, timedSeat, withTimedRole } from "@llm4ts/flow/Timing"
+import { timedJudgment, timedSeat, withTimedRole, type TimedSeatOptions } from "@llm4ts/flow/Timing"
+import { attr, otelContent, withKindSpan } from "@llm4ts/flow/Spans"
+import * as Tracer from "effect/Tracer"
+import { basename } from "node:path"
+import {
+  otelConfig,
+  otelWarning,
+  probeOtelEndpoint,
+  otelLayer,
+  otelSummary,
+  runnerVersion
+} from "./Otel.ts"
 import { transcriptSeat, type TranscriptSink } from "@llm4ts/flow/Transcript"
 import { nodeTranscriptFiles, nodeTranscriptSink, transcriptsWanted } from "./Transcripts.ts"
 import { idleAfterFrom } from "./AgentTree.ts"
@@ -362,6 +373,13 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
   const runEnvironment = options.environment ?? process.env
   const estimateOptions = estimatedUsageOptionsFromEnv(runEnvironment)
   const meterUsage = options.estimateUsage ?? !switchedOff(runEnvironment.LLM4TS_ESTIMATE_USAGE)
+  // Every seat's spans (ADR 0026): content only when asked, an estimate on a
+  // call the backend reports no usage for, and who served it when known.
+  const seatOptions = (executor?: Effect.Effect<string | undefined>): TimedSeatOptions => ({
+    content: otelContent(runEnvironment),
+    ...(meterUsage ? { estimate: estimateOptions } : {}),
+    ...(executor === undefined ? {} : { executor })
+  })
   const metered = (service: LlmServiceShape): Effect.Effect<LlmServiceShape> =>
     meterUsage
       ? Effect.map(makeEstimatedUsageMeter(service, estimateOptions), (meter) => meter.service)
@@ -490,18 +508,26 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
   ): FlowContextShape =>
     FlowContext.of({
       // Every call is timed on the lane's events, under its role.
-      reasoning: recorded(timedSeat(seats.reasoning, laneEvents, "reasoning"), lane, "reasoning"),
+      reasoning: recorded(
+        timedSeat(seats.reasoning, laneEvents, "reasoning", seatOptions()),
+        lane,
+        "reasoning"
+      ),
       coder: {
         ...seats.coder,
-        ...recorded(timedSeat(seats.coder, laneEvents, "coder"), lane, "coder")
+        ...recorded(timedSeat(seats.coder, laneEvents, "coder", seatOptions()), lane, "coder")
       },
       judgment: timedJudgment(seats.judgment, laneEvents),
-      judge: recorded(timedSeat(seats.judge, laneEvents, "judgment"), lane, "judgment"),
+      judge: recorded(
+        timedSeat(seats.judge, laneEvents, "judgment", seatOptions()),
+        lane,
+        "judgment"
+      ),
       git: makeGitTool(dependencies.process, workDir, laneEvents),
       hosting: makeGitHubTool(dependencies.process, workDir, laneEvents),
       events: laneEvents,
       reviewers: seats.reviewers.map((reviewer) =>
-        recorded(timedSeat(reviewer, laneEvents, "reviewer"), lane, "reviewer")
+        recorded(timedSeat(reviewer, laneEvents, "reviewer", seatOptions()), lane, "reviewer")
       ),
       coderCapabilities: seats.coder.capabilities,
       userPrompt: options.userPrompt,
@@ -671,7 +697,8 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
               label
             }),
             laneEvents,
-            role
+            role,
+            seatOptions()
           ),
           lane,
           role
@@ -709,7 +736,7 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
         return FlowContext.of({
           reasoning: view.forRole(rebind ? "planner" : "reviewer"),
           coder: recorded(
-            timedSeat(held.service, laneEvents, "coder"),
+            timedSeat(held.service, laneEvents, "coder", seatOptions(held.executor)),
             lane,
             "coder",
             held.executor
@@ -811,6 +838,9 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
   const environment = options.environment ?? process.env
   const verbosity = options.verbosity ?? "Normal"
   const persistRun = options.persistRun ?? true
+  // OpenTelemetry export (ADR 0026): decided from the environment, built once
+  // per run, flushed when the run's scope closes.
+  const otel = otelConfig(environment)
   const tracePath =
     options.tracePath ??
     (persistRun ? join(options.workDir, ".llm4ts", `trace-${startedAt}.jsonl`) : undefined)
@@ -867,6 +897,16 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
         )
       )
     }
+    const where = otelSummary(otel)
+    if (where !== undefined) {
+      yield* surface.log(palette.info(where))
+      // One warning, at the start, when nothing listens: the exporter itself
+      // drops batches quietly. The probe is bounded (1.5s) and runs once.
+      const warning = otelWarning(otel, yield* probeOtelEndpoint(otel))
+      if (warning !== undefined) {
+        yield* surface.log(palette.warn(warning))
+      }
+    }
   }
   const recorder =
     tracePath === undefined
@@ -925,7 +965,32 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
     tracePath === undefined
       ? bundle.context
       : { ...bundle.context, trace: { runId: bundle.runId, path: tracePath } }
-  return yield* body(context).pipe(
+  const runAttributes: Record<string, unknown> = {
+    [attr.run]: bundle.runId,
+    [attr.session]: bundle.runId,
+    ...(environment.LLM4TS_FLOW === undefined ? {} : { [attr.flow]: environment.LLM4TS_FLOW })
+  }
+  // The run is a CHAIN span every other span descends from or links to; its
+  // attributes ride on all of them. Effect's own function spans stay
+  // unsampled so an exported trace shows the flow, not the call stack.
+  const traced = withKindSpan(
+    "run",
+    { kind: "CHAIN", attributes: runAttributes },
+    Object.entries(runAttributes).reduce(
+      (acc, [key, value]) => Effect.annotateSpans(key, value)(acc),
+      body(context)
+    )
+  ).pipe(
+    Effect.provideService(Tracer.MinimumTraceLevel, otel.mode === "off" ? "All" : "None"),
+    Effect.provide(
+      otelLayer(
+        otel,
+        { serviceVersion: runnerVersion, project: basename(options.workDir) },
+        environment
+      )
+    )
+  )
+  return yield* traced.pipe(
     Effect.provideService(FlowContext, context),
     Effect.andThen((value) => Effect.as(enforceBudget, value)),
     Effect.ensuring(