@yagni-app/code-staging 1.0.5-staging.1241.1 → 1.0.6-staging.1244.1

package/README.md

@@ -179,11 +179,16 @@ children and subagents — emits a per-prompt span tree: interaction → LLM
 request → tool calls, following the OTel GenAI semantic conventions. Nothing is
 exported unless you configure an endpoint.
 
-Enable it one of three ways (first match wins):
-
-- `OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector>:4317` in the environment
-  (a personal override — handy for pointing one session at a scratch
-  collector), or
+Enable it one of four ways (first match wins):
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT=…` in the environment (a personal override —
+  handy for pointing one session at a scratch collector), or
+- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=…` in the environment — the per-signal
+  form Claude Code setups use (e.g.
+  `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.datadoghq.com/v1/traces`
+  with `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf`); the launcher
+  bridges it to the generic var pi-otel reads, so a Claude Code OTel env
+  lights up YAGNI Code traces with no extra config, or
 - **workspace settings** (the zero-setup path): a workspace admin sets the
   endpoint, protocol, and any collector headers (e.g. a Datadog API key) once
   in the web app under Settings → YAGNI Code → Trace export. Every session in
@@ -197,7 +202,26 @@ Enable it one of three ways (first match wins):
 Standard OTel env vars are honored (`OTEL_EXPORTER_OTLP_PROTOCOL`,
 `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_SERVICE_NAME` — defaults to `yagni-code`),
 and `PI_OTEL_DISABLED=1` is the kill switch. `yagni doctor` shows the current
-export state.
+export state and probes the endpoint live (unreachable → a warning with a
+hint, never an exit-code flip).
+
+Two recipes for common collectors:
+
+- **Datadog, direct SaaS (no agent):** endpoint
+  `https://otlp.datadoghq.com/v1/traces` (US1; other sites have their own
+  host — `otlp.us3.datadoghq.com`, `otlp.us5.datadoghq.com`,
+  `otlp.datadoghq.eu`, `otlp.ap1.datadoghq.com`), protocol `http/protobuf`
+  (Datadog's direct trace intake does not accept gRPC), header
+  `dd-api-key=<your Datadog API key>`. Use the full path, not `/v1/` — the
+  endpoint is passed through verbatim, no path is appended for you.
+- **Datadog Agent:** endpoint `http://<agent-host>:4317`, protocol `grpc`, no
+  key (the agent forwards with its own). OTLP ingest ships in the agent but
+  is off by default — enable it with
+  `otlp_config.receiver.protocols.grpc.endpoint: 0.0.0.0:4317` in
+  `datadog.yaml`.
+- **Grafana Cloud:** endpoint `https://otlp-gateway-prod-…-0.grafana.net:443/otlp`,
+  protocol `http/protobuf`, header `authorization=<the raw MTgx… value>` (the
+  `Basic ` scheme is added for you).
 
 Two things are enforced and not configurable:
 

package/dist/doctor.d.ts

@@ -13,7 +13,7 @@
  * Advisory checks (loose perms, missing `gh`) never flip the exit code.
  */
 import { type TokenExpiryStatus } from "./launch.js";
-import { type OtelLaunchConfig } from "./otel.js";
+import { probeOtelEndpoint, type OtelLaunchConfig } from "./otel.js";
 import { type Profile } from "./profiles.js";
 export type CheckStatus = "ok" | "warn" | "fail";
 export interface CheckResult {
@@ -63,10 +63,15 @@ export declare function checkCliUpdate(probe: {
 export declare function checkGh(onPath: boolean): CheckResult;
 /**
  * Advisory OTel-export line: says whether sessions will stream traces to an
- * OTLP collector, and from which config source. Never flips the exit code —
+ * OTLP collector, from which config source, and — when a collector is
+ * configured — whether the endpoint answers TCP right now (scheme-default
+ * ports included: https with no port probes 443). Never flips the exit code —
  * most machines have no collector, and that is the healthy default.
  */
-export declare function checkOtelExport(config: OtelLaunchConfig | undefined): CheckResult;
+export declare function checkOtelExport(config: OtelLaunchConfig | undefined, deps?: {
+    probeEndpoint?: typeof probeOtelEndpoint;
+    probeTimeoutMs?: number;
+}): Promise<CheckResult>;
 /** Config-only MCP snapshot (no connections — health checks live in `mcp list`/`get`). */
 export interface McpProbe {
     /** YAGNI_CODE_MCP_DISABLED kill-switch is active. */

package/dist/doctor.js

@@ -17,7 +17,7 @@ import { delimiter, join } from "node:path";
 import { credentialsDir } from "./credentials.js";
 import { currentCliVersion, fetchLatestVersion, isNewerVersion } from "./upgrade.js";
 import { classifyTokenExpiry } from "./launch.js";
-import { resolveOtelLaunchWithWorkspace } from "./otel.js";
+import { probeOtelEndpoint, resolveOtelLaunchWithWorkspace, } from "./otel.js";
 import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
 import { resolveMcpConfigPath } from "./mcpCommand.js";
@@ -202,10 +202,12 @@ export function checkGh(onPath) {
 }
 /**
  * Advisory OTel-export line: says whether sessions will stream traces to an
- * OTLP collector, and from which config source. Never flips the exit code —
+ * OTLP collector, from which config source, and — when a collector is
+ * configured — whether the endpoint answers TCP right now (scheme-default
+ * ports included: https with no port probes 443). Never flips the exit code —
  * most machines have no collector, and that is the healthy default.
  */
-export function checkOtelExport(config) {
+export async function checkOtelExport(config, deps = {}) {
     if (!config) {
         return {
             name: "otel export (optional)",
@@ -215,16 +217,41 @@ export function checkOtelExport(config) {
         };
     }
     const source = config.source === "env"
-        ? "OTEL_EXPORTER_OTLP_ENDPOINT"
+        ? (config.envVar ?? "OTEL_EXPORTER_OTLP_ENDPOINT")
         : config.source === "workspace"
             ? "workspace settings"
             : ".pi/settings.json";
-    return {
-        name: "otel export (optional)",
-        status: "ok",
-        detail: `on → ${config.endpoint} (${source}, metadata-only)`,
-        required: false,
-    };
+    const base = `on → ${config.endpoint} (${source}, metadata-only)`;
+    const doProbe = deps.probeEndpoint ?? probeOtelEndpoint;
+    try {
+        const reachable = await doProbe(config.endpoint, deps.probeTimeoutMs ?? 1_000);
+        return reachable
+            ? {
+                name: "otel export (optional)",
+                status: "ok",
+                detail: `${base}, TCP reachable`,
+                required: false,
+            }
+            : {
+                name: "otel export (optional)",
+                status: "warn",
+                detail: `${base}, endpoint not reachable`,
+                hint: "the collector is down, unreachable from this machine, or the URL is wrong — traces will not export until it answers",
+                required: false,
+            };
+    }
+    catch {
+        // The probe itself errored (not "endpoint down" — the check could not
+        // run). Distinct from a verified-healthy line so nobody reads an
+        // unverified config as checked-and-good.
+        return {
+            name: "otel export (optional)",
+            status: "warn",
+            detail: `${base}, reachability probe failed`,
+            hint: "the reachability check could not run (network error) — export is configured but unverified; traces may still export normally",
+            required: false,
+        };
+    }
 }
 /**
  * Advisory (never required) MCP line: reports config health without connecting
@@ -489,7 +516,7 @@ export async function gatherChecks(deps = {}) {
     checks.push(checkStateDir(probeStateDir()));
     checks.push(checkGh(ghOnPath()));
     checks.push(checkMcpConfig(await probeMcp()));
-    checks.push(checkOtelExport(await resolveOtelLaunchWithWorkspace({
+    checks.push(await checkOtelExport(await resolveOtelLaunchWithWorkspace({
         env: process.env,
         cwd: process.cwd(),
         creds: profile.token ? { baseUrl: profile.baseUrl, token: profile.token } : null,

package/dist/otel.d.ts

@@ -43,13 +43,23 @@ export interface OtelLaunchConfig {
     extensionPath: string;
     /**
      * Where the enablement signal came from. "workspace" additionally carries
-     * protocol/headers/serviceName, delivered as env to the session (the other
-     * sources leave those to whatever the user/repo already configured).
+     * protocol/headers/serviceName, delivered as env to the session; "env" may
+     * carry a protocol when the endpoint arrived via the per-signal
+     * `OTEL_EXPORTER_OTLP_TRACES_(ENDPOINT|PROTOCOL)` bridge (pi-otel reads only
+     * the generic var, so the child env translates); "project-settings" leaves
+     * those to whatever the user/repo already configured.
      */
     source: "env" | "workspace" | "project-settings";
+    /**
+     * The env var the endpoint actually came from — the generic
+     * `OTEL_EXPORTER_OTLP_ENDPOINT` or the per-signal
+     * `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`. Doctor surfaces it so a user who set
+     * the per-signal var sees their own var named, not the generic one.
+     */
+    envVar?: "OTEL_EXPORTER_OTLP_ENDPOINT" | "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
     /** The configured OTLP endpoint (for doctor display; env for workspace source). */
     endpoint: string;
-    /** Workspace-configured OTLP protocol (workspace source only). */
+    /** OTLP protocol: workspace config, or a per-signal env bridge. */
     protocol?: string;
     /** Workspace-configured collector headers (workspace source only; carries secrets). */
     headers?: Record<string, string>;
@@ -72,6 +82,15 @@ export interface WorkspaceOtelConfig {
  * Decide whether this launch exports OTel traces, and with which pi-otel entry.
  * Returns undefined when export stays off: no endpoint configured anywhere,
  * `PI_OTEL_DISABLED` set, or the pi-otel package unresolvable (never fatal).
+ *
+ * Env sources, in precedence order: the generic `OTEL_EXPORTER_OTLP_ENDPOINT`,
+ * then the per-signal `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`. pi-otel only reads
+ * the generic var, so the per-signal one (the standard OTel env shape, and
+ * what Claude Code setups configure — e.g. Updater's) is bridged: the traces
+ * endpoint becomes the generic one, and a per-signal TRACES_PROTOCOL carries
+ * over the same way. Logs/metrics per-signal vars are deliberately NOT read:
+ * sessions export traces only, and pi-otel's metrics/logs signals are opt-in
+ * elsewhere.
  */
 export declare function resolveOtelLaunch(opts: {
     env: NodeJS.ProcessEnv;
@@ -80,13 +99,21 @@ export declare function resolveOtelLaunch(opts: {
     resolveExtension?: () => string;
     readFile?: typeof readFileSync;
 }): OtelLaunchConfig | undefined;
-/**
- * Absolute path to pi-otel's extension entry (its package main IS the pi
+/** Absolute path to pi-otel's extension entry (its package main IS the pi
  * extension entry, `dist/index.js`). Resolved ESM-native like `paths.ts` does
  * for pi itself. Throws when the package is missing — callers treat that as
  * "export off", not an error.
  */
 export declare function resolveOtelExtensionPath(): string;
+/**
+ * TCP reachability probe for an OTLP endpoint URL, with scheme-default ports:
+ * WHATWG `URL` strips `:443`/`:80` as defaults, so an https endpoint with no
+ * port probes 443 (the agentless SaaS shape). Returns false on any parse or
+ * connect failure — reachability is advisory, never fatal. Mirrors the probe
+ * inside (patched) pi-otel but lives here so `doctor` can use it without
+ * importing the extension's SDK graph.
+ */
+export declare function probeOtelEndpoint(endpoint: string, timeoutMs?: number): Promise<boolean>;
 /**
  * The env keys an OTel-exporting child must carry. `PI_OTEL_CAPTURE_CONTENT`
  * is pinned unconditionally (policy 2 above); the service name only fills in
@@ -125,10 +152,12 @@ export declare function fetchWorkspaceOtel(creds: {
     token: string;
 }, profileName: string, deps?: WorkspaceOtelFetchDeps): Promise<WorkspaceOtelConfig | null>;
 /**
- * Full launch-time resolution, all three sources in precedence order:
+ * Full launch-time resolution, all four sources in precedence order:
  *
  *   1. `PI_OTEL_DISABLED`      — personal kill switch, beats everything.
- *   2. env `OTEL_EXPORTER_OTLP_ENDPOINT` — the user's own setup, untouched.
+ *   2. env `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
+ *                              — the user's own setup, untouched (generic wins
+ *                              over per-signal).
  *   3. workspace config        — admin-set in the web app, fetched/cached.
  *   4. repo `.pi/settings.json` — committed per-repo config.
  *

package/dist/otel.js

@@ -29,6 +29,7 @@
  * missing package or unreadable settings file resolves to "disabled".
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createConnection } from "node:net";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { credentialsDir } from "./credentials.js";
@@ -71,16 +72,25 @@ function envDisabled(env) {
  * Decide whether this launch exports OTel traces, and with which pi-otel entry.
  * Returns undefined when export stays off: no endpoint configured anywhere,
  * `PI_OTEL_DISABLED` set, or the pi-otel package unresolvable (never fatal).
+ *
+ * Env sources, in precedence order: the generic `OTEL_EXPORTER_OTLP_ENDPOINT`,
+ * then the per-signal `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`. pi-otel only reads
+ * the generic var, so the per-signal one (the standard OTel env shape, and
+ * what Claude Code setups configure — e.g. Updater's) is bridged: the traces
+ * endpoint becomes the generic one, and a per-signal TRACES_PROTOCOL carries
+ * over the same way. Logs/metrics per-signal vars are deliberately NOT read:
+ * sessions export traces only, and pi-otel's metrics/logs signals are opt-in
+ * elsewhere.
  */
 export function resolveOtelLaunch(opts) {
     const { env, cwd } = opts;
     if (envDisabled(env))
         return undefined;
     const envEndpoint = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
-    const settingsEndpoint = envEndpoint
-        ? undefined
-        : projectOtelEndpoint(cwd, opts.readFile ?? readFileSync);
-    if (!envEndpoint && !settingsEndpoint)
+    const tracesEndpoint = env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim();
+    const usingPerSignal = !envEndpoint && !!tracesEndpoint;
+    const settingsEndpoint = envEndpoint || tracesEndpoint ? undefined : projectOtelEndpoint(cwd, opts.readFile ?? readFileSync);
+    if (!envEndpoint && !tracesEndpoint && !settingsEndpoint)
         return undefined;
     let extensionPath;
     try {
@@ -89,12 +99,28 @@ export function resolveOtelLaunch(opts) {
     catch {
         return undefined;
     }
-    return envEndpoint
-        ? { extensionPath, source: "env", endpoint: envEndpoint }
-        : { extensionPath, source: "project-settings", endpoint: settingsEndpoint };
+    if (envEndpoint) {
+        return {
+            extensionPath,
+            source: "env",
+            envVar: "OTEL_EXPORTER_OTLP_ENDPOINT",
+            endpoint: envEndpoint,
+        };
+    }
+    if (usingPerSignal) {
+        return {
+            extensionPath,
+            source: "env",
+            envVar: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+            endpoint: tracesEndpoint,
+            ...(env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL?.trim()
+                ? { protocol: env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL.trim() }
+                : {}),
+        };
+    }
+    return { extensionPath, source: "project-settings", endpoint: settingsEndpoint };
 }
-/**
- * Absolute path to pi-otel's extension entry (its package main IS the pi
+/** Absolute path to pi-otel's extension entry (its package main IS the pi
  * extension entry, `dist/index.js`). Resolved ESM-native like `paths.ts` does
  * for pi itself. Throws when the package is missing — callers treat that as
  * "export off", not an error.
@@ -106,6 +132,45 @@ export function resolveOtelExtensionPath() {
     }
     return path;
 }
+/**
+ * TCP reachability probe for an OTLP endpoint URL, with scheme-default ports:
+ * WHATWG `URL` strips `:443`/`:80` as defaults, so an https endpoint with no
+ * port probes 443 (the agentless SaaS shape). Returns false on any parse or
+ * connect failure — reachability is advisory, never fatal. Mirrors the probe
+ * inside (patched) pi-otel but lives here so `doctor` can use it without
+ * importing the extension's SDK graph.
+ */
+export async function probeOtelEndpoint(endpoint, timeoutMs = 1_000) {
+    let host;
+    let port;
+    try {
+        const u = new URL(endpoint);
+        host = u.hostname;
+        port = u.port
+            ? Number(u.port)
+            : u.protocol === "https:"
+                ? 443
+                : u.protocol === "http:"
+                    ? 80
+                    : null;
+    }
+    catch {
+        return false;
+    }
+    if (!host || !port)
+        return false;
+    return new Promise((resolve) => {
+        const sock = createConnection({ host, port });
+        const done = (ok) => {
+            sock.destroy();
+            resolve(ok);
+        };
+        sock.setTimeout(timeoutMs);
+        sock.once("connect", () => done(true));
+        sock.once("timeout", () => done(false));
+        sock.once("error", () => done(false));
+    });
+}
 /**
  * The env keys an OTel-exporting child must carry. `PI_OTEL_CAPTURE_CONTENT`
  * is pinned unconditionally (policy 2 above); the service name only fills in
@@ -135,6 +200,17 @@ export function otelChildEnv(config, baseEnv) {
             workspace.OTEL_SERVICE_NAME = config.serviceName;
         }
     }
+    else if (config.source === "env" && config.protocol) {
+        // The per-signal bridge: the endpoint came from
+        // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (+ TRACES_PROTOCOL), which pi-otel
+        // does not read — deliver them as the generic vars the extension resolves.
+        if (!baseEnv.OTEL_EXPORTER_OTLP_ENDPOINT) {
+            workspace.OTEL_EXPORTER_OTLP_ENDPOINT = config.endpoint;
+        }
+        if (!baseEnv.OTEL_EXPORTER_OTLP_PROTOCOL) {
+            workspace.OTEL_EXPORTER_OTLP_PROTOCOL = config.protocol;
+        }
+    }
     return {
         ...workspace,
         [OTEL_EXTENSION_PATH_ENV]: config.extensionPath,
@@ -235,10 +311,12 @@ function readWorkspaceOtelCache(cachePath) {
     }
 }
 /**
- * Full launch-time resolution, all three sources in precedence order:
+ * Full launch-time resolution, all four sources in precedence order:
  *
  *   1. `PI_OTEL_DISABLED`      — personal kill switch, beats everything.
- *   2. env `OTEL_EXPORTER_OTLP_ENDPOINT` — the user's own setup, untouched.
+ *   2. env `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
+ *                              — the user's own setup, untouched (generic wins
+ *                              over per-signal).
  *   3. workspace config        — admin-set in the web app, fetched/cached.
  *   4. repo `.pi/settings.json` — committed per-repo config.
  *
@@ -249,7 +327,7 @@ export async function resolveOtelLaunchWithWorkspace(opts) {
     if (envDisabled(env))
         return undefined;
     // Source 2: the user's own env config short-circuits — no fetch needed.
-    if (env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim()) {
+    if (env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim() || env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim()) {
         return resolveOtelLaunch({
             env,
             cwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.0.5-staging.1241.1",
+  "version": "1.0.6-staging.1244.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -42,5 +42,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "9328192141ab3d96cbeb324d748df1e571fe5eb2"
+  "yagniSourceSha": "09cd57add6ba5c3028cc4f971459d5c7f9d4da97"
 }