@poncho-ai/harness 0.33.0 → 0.33.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.33.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.33.1 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,8 +8,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 334.17 KB
-ESM ⚡️ Build success in 152ms
+ESM dist/index.js 335.08 KB
+ESM ⚡️ Build success in 167ms
 DTS Build start
-DTS ⚡️ Build success in 7104ms
+DTS ⚡️ Build success in 7028ms
 DTS dist/index.d.ts 33.55 KB

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @poncho-ai/harness
 
+## 0.33.1
+
+### Patch Changes
+
+- [`d8fe87c`](https://github.com/cesr/poncho-ai/commit/d8fe87c68d42878829422750f98e3c70a425e3e3) Thanks [@cesr](https://github.com/cesr)! - fix: OTLP trace exporter reliability and error visibility
+  - Use provider instance directly instead of global `trace.getTracer()` to avoid silent failure when another library registers a tracer provider first
+  - Append `/v1/traces` to base OTLP endpoints so users can pass either the base URL or the full signal-specific URL
+  - Surface HTTP status code and response body on export failures
+  - Enable OTel diagnostic logger at WARN level for internal SDK errors
+
 ## 0.33.0
 
 ### Minor Changes

package/dist/index.js

@@ -5343,7 +5343,7 @@ var createSubagentTools = (manager) => [
 ];
 
 // src/harness.ts
-import { trace, context as otelContext, SpanStatusCode, SpanKind } from "@opentelemetry/api";
+import { trace, context as otelContext, SpanStatusCode, SpanKind, diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 
@@ -5357,10 +5357,15 @@ function sanitizeEventForLog(event) {
     return value;
   });
 }
+var TRACES_PATH = "/v1/traces";
+function ensureTracesPath(url) {
+  if (url.endsWith(TRACES_PATH)) return url;
+  return url.replace(/\/+$/, "") + TRACES_PATH;
+}
 function normalizeOtlp(opt) {
   if (!opt) return void 0;
-  if (typeof opt === "string") return opt ? { url: opt } : void 0;
-  return opt.url ? opt : void 0;
+  if (typeof opt === "string") return opt ? { url: ensureTracesPath(opt) } : void 0;
+  return opt.url ? { ...opt, url: ensureTracesPath(opt.url) } : void 0;
 }
 var TelemetryEmitter = class {
   config;
@@ -5414,7 +5419,10 @@ var TelemetryEmitter = class {
           ]
         })
       });
-    } catch {
+    } catch (err) {
+      console.warn(
+        `[poncho][telemetry] OTLP log delivery failed: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
   }
 };
@@ -5507,6 +5515,16 @@ var ToolDispatcher = class {
 };
 
 // src/harness.ts
+function formatOtlpError(err) {
+  if (!(err instanceof Error)) return String(err);
+  const parts = [];
+  const code = err.code;
+  if (code != null) parts.push(`HTTP ${code}`);
+  if (err.message) parts.push(err.message);
+  const data = err.data;
+  if (data) parts.push(data);
+  return parts.join(" \u2014 ") || "unknown error";
+}
 var now = () => Date.now();
 var FIRST_CHUNK_TIMEOUT_MS = 9e4;
 var MAX_TRANSIENT_STEP_RETRIES = 1;
@@ -6603,6 +6621,7 @@ var AgentHarness = class _AgentHarness {
     const telemetryEnabled = config?.telemetry?.enabled !== false;
     const otlpConfig = telemetryEnabled ? normalizeOtlp(config?.telemetry?.otlp) : void 0;
     if (otlpConfig) {
+      diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.WARN);
       const exporter = new OTLPTraceExporter({
         url: otlpConfig.url,
         headers: otlpConfig.headers
@@ -6615,7 +6634,7 @@ var AgentHarness = class _AgentHarness {
       provider2.register();
       this.otlpTracerProvider = provider2;
       this.hasOtlpExporter = true;
-      console.info(`[poncho][telemetry] OTLP exporter active \u2192 ${otlpConfig.url}`);
+      console.info(`[poncho][telemetry] OTLP trace exporter active \u2192 ${otlpConfig.url}`);
     }
   }
   async buildBrowserStoragePersistence(config, sessionId) {
@@ -6761,17 +6780,13 @@ var AgentHarness = class _AgentHarness {
     await this.mcpBridge?.stopLocalServers();
     if (this.otlpSpanProcessor) {
       await this.otlpSpanProcessor.shutdown().catch((err) => {
-        console.warn(
-          `[poncho][telemetry] OTLP span processor shutdown error: ${err instanceof Error ? err.message : String(err)}`
-        );
+        console.warn(`[poncho][telemetry] OTLP span processor shutdown error: ${formatOtlpError(err)}`);
       });
       this.otlpSpanProcessor = void 0;
     }
     if (this.otlpTracerProvider) {
       await this.otlpTracerProvider.shutdown().catch((err) => {
-        console.warn(
-          `[poncho][telemetry] OTLP tracer provider shutdown error: ${err instanceof Error ? err.message : String(err)}`
-        );
+        console.warn(`[poncho][telemetry] OTLP tracer provider shutdown error: ${formatOtlpError(err)}`);
       });
       this.otlpTracerProvider = void 0;
     }
@@ -6785,8 +6800,8 @@ var AgentHarness = class _AgentHarness {
    * child spans (LLM calls via AI SDK, tool execution) group under one trace.
    */
   async *runWithTelemetry(input) {
-    if (this.hasOtlpExporter) {
-      const tracer = trace.getTracer("gen_ai");
+    if (this.hasOtlpExporter && this.otlpTracerProvider) {
+      const tracer = this.otlpTracerProvider.getTracer("gen_ai");
       const agentName = this.parsedAgent?.frontmatter.name ?? "agent";
       const rootSpan = tracer.startSpan(`invoke_agent ${agentName}`, {
         kind: SpanKind.INTERNAL,
@@ -6815,7 +6830,9 @@ var AgentHarness = class _AgentHarness {
         rootSpan.end();
         try {
           await this.otlpSpanProcessor?.forceFlush();
-        } catch {
+        } catch (err) {
+          const detail = formatOtlpError(err);
+          console.warn(`[poncho][telemetry] OTLP span flush failed: ${detail}`);
         }
       }
     } else {
@@ -7684,8 +7701,8 @@ ${textContent}` };
           return;
         }
         const toolSpans = /* @__PURE__ */ new Map();
-        if (this.hasOtlpExporter) {
-          const tracer = trace.getTracer("gen_ai");
+        if (this.hasOtlpExporter && this.otlpTracerProvider) {
+          const tracer = this.otlpTracerProvider.getTracer("gen_ai");
           for (const call of approvedCalls) {
             const toolDef = this.dispatcher.get(call.name);
             toolSpans.set(call.id, tracer.startSpan(`execute_tool ${call.name}`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/harness.ts

@@ -37,10 +37,22 @@ import { createSkillTools, normalizeScriptPolicyPath } from "./skill-tools.js";
 import { createSearchTools } from "./search-tools.js";
 import { createSubagentTools } from "./subagent-tools.js";
 import type { SubagentManager } from "./subagent-manager.js";
-import { trace, context as otelContext, SpanStatusCode, SpanKind } from "@opentelemetry/api";
+import { trace, context as otelContext, SpanStatusCode, SpanKind, diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { normalizeOtlp } from "./telemetry.js";
+
+/** Extract useful details from OTLPExporterError (has .code + .data) or plain Error. */
+function formatOtlpError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  const parts: string[] = [];
+  const code = (err as { code?: number }).code;
+  if (code != null) parts.push(`HTTP ${code}`);
+  if (err.message) parts.push(err.message);
+  const data = (err as { data?: string }).data;
+  if (data) parts.push(data);
+  return parts.join(" — ") || "unknown error";
+}
 import {
   isSiblingScriptsPattern,
   matchesRelativeScriptPattern,
@@ -1346,6 +1358,7 @@ export class AgentHarness {
     const telemetryEnabled = config?.telemetry?.enabled !== false;
     const otlpConfig = telemetryEnabled ? normalizeOtlp(config?.telemetry?.otlp) : undefined;
     if (otlpConfig) {
+      diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.WARN);
       const exporter = new OTLPTraceExporter({
         url: otlpConfig.url,
         headers: otlpConfig.headers,
@@ -1358,7 +1371,7 @@ export class AgentHarness {
       provider.register();
       this.otlpTracerProvider = provider;
       this.hasOtlpExporter = true;
-      console.info(`[poncho][telemetry] OTLP exporter active → ${otlpConfig.url}`);
+      console.info(`[poncho][telemetry] OTLP trace exporter active → ${otlpConfig.url}`);
     }
   }
 
@@ -1523,21 +1536,13 @@ export class AgentHarness {
     await this.mcpBridge?.stopLocalServers();
     if (this.otlpSpanProcessor) {
       await this.otlpSpanProcessor.shutdown().catch((err) => {
-        console.warn(
-          `[poncho][telemetry] OTLP span processor shutdown error: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
+        console.warn(`[poncho][telemetry] OTLP span processor shutdown error: ${formatOtlpError(err)}`);
       });
       this.otlpSpanProcessor = undefined;
     }
     if (this.otlpTracerProvider) {
       await this.otlpTracerProvider.shutdown().catch((err) => {
-        console.warn(
-          `[poncho][telemetry] OTLP tracer provider shutdown error: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
+        console.warn(`[poncho][telemetry] OTLP tracer provider shutdown error: ${formatOtlpError(err)}`);
       });
       this.otlpTracerProvider = undefined;
     }
@@ -1553,8 +1558,8 @@ export class AgentHarness {
    * child spans (LLM calls via AI SDK, tool execution) group under one trace.
    */
   async *runWithTelemetry(input: RunInput): AsyncGenerator<AgentEvent> {
-    if (this.hasOtlpExporter) {
-      const tracer = trace.getTracer("gen_ai");
+    if (this.hasOtlpExporter && this.otlpTracerProvider) {
+      const tracer = this.otlpTracerProvider.getTracer("gen_ai");
       const agentName = this.parsedAgent?.frontmatter.name ?? "agent";
 
       const rootSpan = tracer.startSpan(`invoke_agent ${agentName}`, {
@@ -1586,7 +1591,10 @@ export class AgentHarness {
         rootSpan.end();
         try {
           await this.otlpSpanProcessor?.forceFlush();
-        } catch { /* best-effort */ }
+        } catch (err: unknown) {
+          const detail = formatOtlpError(err);
+          console.warn(`[poncho][telemetry] OTLP span flush failed: ${detail}`);
+        }
       }
     } else {
       yield* this.run(input);
@@ -2642,8 +2650,8 @@ ${boundedMainMemory.trim()}`
       // OTel GenAI execute_tool spans for tool call visibility in traces
       type OtelSpan = ReturnType<ReturnType<typeof trace.getTracer>["startSpan"]>;
       const toolSpans = new Map<string, OtelSpan>();
-      if (this.hasOtlpExporter) {
-        const tracer = trace.getTracer("gen_ai");
+      if (this.hasOtlpExporter && this.otlpTracerProvider) {
+        const tracer = this.otlpTracerProvider.getTracer("gen_ai");
         for (const call of approvedCalls) {
           const toolDef = this.dispatcher.get(call.name);
           toolSpans.set(call.id, tracer.startSpan(`execute_tool ${call.name}`, {

package/src/telemetry.ts

@@ -18,10 +18,26 @@ export interface OtlpConfig {
 
 export type OtlpOption = string | OtlpConfig;
 
+const TRACES_PATH = "/v1/traces";
+
+/**
+ * Ensures the OTLP URL points to the trace-ingest endpoint.
+ *
+ * Users typically configure the *base* OTLP endpoint (e.g.
+ * `https://gateway.example.com/api/v1/otlp`) but `OTLPTraceExporter` uses
+ * the `url` constructor option as-is — it only appends `/v1/traces`
+ * automatically when reading from the `OTEL_EXPORTER_OTLP_ENDPOINT` env var.
+ * Without this fixup traces are POSTed to the wrong path and silently lost.
+ */
+function ensureTracesPath(url: string): string {
+  if (url.endsWith(TRACES_PATH)) return url;
+  return url.replace(/\/+$/, "") + TRACES_PATH;
+}
+
 export function normalizeOtlp(opt: OtlpOption | undefined): OtlpConfig | undefined {
   if (!opt) return undefined;
-  if (typeof opt === "string") return opt ? { url: opt } : undefined;
-  return opt.url ? opt : undefined;
+  if (typeof opt === "string") return opt ? { url: ensureTracesPath(opt) } : undefined;
+  return opt.url ? { ...opt, url: ensureTracesPath(opt.url) } : undefined;
 }
 
 export interface TelemetryConfig {
@@ -87,8 +103,12 @@ export class TelemetryEmitter {
           ],
         }),
       });
-    } catch {
-      // Ignore telemetry delivery failures.
+    } catch (err) {
+      console.warn(
+        `[poncho][telemetry] OTLP log delivery failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
     }
   }
 

package/test/telemetry.test.ts

@@ -1,5 +1,42 @@
 import { describe, expect, it, vi } from "vitest";
-import { TelemetryEmitter } from "../src/telemetry.js";
+import { TelemetryEmitter, normalizeOtlp } from "../src/telemetry.js";
+
+describe("normalizeOtlp", () => {
+  it("appends /v1/traces to a base URL string", () => {
+    expect(normalizeOtlp("https://gateway.example.com/api/v1/otlp")).toEqual({
+      url: "https://gateway.example.com/api/v1/otlp/v1/traces",
+    });
+  });
+
+  it("does not double-append when URL already ends with /v1/traces", () => {
+    expect(normalizeOtlp("https://api.honeycomb.io/v1/traces")).toEqual({
+      url: "https://api.honeycomb.io/v1/traces",
+    });
+  });
+
+  it("strips trailing slashes before appending", () => {
+    expect(normalizeOtlp("https://gateway.example.com/")).toEqual({
+      url: "https://gateway.example.com/v1/traces",
+    });
+  });
+
+  it("appends /v1/traces to object config", () => {
+    expect(
+      normalizeOtlp({
+        url: "https://gateway.example.com/otlp",
+        headers: { Authorization: "Bearer tok" },
+      }),
+    ).toEqual({
+      url: "https://gateway.example.com/otlp/v1/traces",
+      headers: { Authorization: "Bearer tok" },
+    });
+  });
+
+  it("returns undefined for falsy input", () => {
+    expect(normalizeOtlp(undefined)).toBeUndefined();
+    expect(normalizeOtlp("")).toBeUndefined();
+  });
+});
 
 describe("telemetry emitter", () => {
   it("delegates to custom handler when configured", async () => {
@@ -14,7 +51,7 @@ describe("telemetry emitter", () => {
     global.fetch = vi.fn().mockRejectedValue(new Error("network down"));
 
     const emitter = new TelemetryEmitter({
-      otlp: "https://otel.example.com/v1/logs",
+      otlp: "https://otel.example.com/v1/traces",
     });
 
     await expect(