@yagni-app/code-staging 1.0.0-staging.1180.1 → 1.0.0-staging.1183.1

package/README.md

@@ -171,6 +171,43 @@ Credentials live in `~/.yagni-code/profiles/<name>.json` (mode `0600`); the acti
 environment is recorded in `~/.yagni-code/config.json`. A pre-profiles
 `~/.yagni-code/credentials.json` is migrated automatically on first run.
 
+### OTel export (opt-in)
+
+Point sessions at **your own** OpenTelemetry collector (Datadog Agent, Grafana
+Alloy, an OTLP-native backend) and every session — including `/go` stage
+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
+- **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
+  the workspace picks it up at launch — nothing to install or configure on
+  developer machines. Header values are encrypted at rest server-side and the
+  launch-time copy is cached at mode `0600`, the same posture as your device
+  token. Or,
+- commit `{ "otel": { "endpoint": "http://<collector>:4317" } }` to the repo's
+  `.pi/settings.json` so one repo's sessions export without per-machine setup.
+
+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.
+
+Two things are enforced and not configurable:
+
+- **Metadata only.** Token counts, cost, tier, finish reasons, and tool-call
+  ids export; prompt and response text never do — a settings file or env var
+  asking for content capture is overridden.
+- **Cost is your contracted rate.** `pi.cost.usd` is computed from your
+  workspace's tier rate card, and the exported model name is the opaque tier
+  id (`advanced`, `peak`, …), so traces never fingerprint the backing model.
+
 Device tokens are revocable from both ends: `yagni logout` revokes the current
 one, and a workspace admin can list every connected device and revoke any token
 from the web app (Settings, YAGNI Code, Connected devices). Tokens are stored
@@ -196,6 +233,11 @@ precisely:
   third-party crash service, so we can fix the crash before you have to report
   it. Disable with `YAGNI_DISABLE_CRASH_REPORTS=1`.
 
+A third flow exists only when you turn it on: **OTel export** (above) sends
+session *metadata* — never prompt or response text — to a collector **you**
+configure and operate. It is off unless an OTLP endpoint is set, and YAGNI
+never receives these traces.
+
 ## Troubleshooting
 
 - **`Not logged in to environment "<name>" … Run \`yagni login\` first.`** — no

package/dist/cli.js

@@ -27,6 +27,7 @@ import { login } from "./login.js";
 import { logout } from "./logout.js";
 import { tokenCommand } from "./token.js";
 import { buildLaunch } from "./launch.js";
+import { resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { parseOutputFormat, parseJsonEvents, buildResultObject, readGuardianEvents, } from "./outputFormat.js";
 import { feedbackCommand } from "./feedback.js";
 import { runDoctor } from "./doctor.js";
@@ -245,6 +246,16 @@ async function runDefault(passthroughArgs) {
     catch {
         compat = { argv: [], env: {} };
     }
+    // OTel export: load pi-otel only when an OTLP endpoint is configured — the
+    // user's env, the workspace's admin-set config (fetched fail-soft, cached),
+    // or the repo's .pi/settings.json, in that order. undefined keeps the
+    // launch untouched. See otel.ts for the policy.
+    const otel = await resolveOtelLaunchWithWorkspace({
+        env: process.env,
+        cwd: process.cwd(),
+        creds,
+        profileName: profile.name,
+    });
     // buildLaunch runs the token-expiry preflight: it throws (with an actionable
     // login prompt) on an already-expired token so we never spawn a session that
     // immediately 401s, and returns non-fatal warnings (e.g. expiry approaching).
@@ -265,6 +276,7 @@ async function runDefault(passthroughArgs) {
             cliVersion: cliVersion(),
             baseEnv: process.env,
             ...(seededHideThinking ? { hideThinkingSeeded: true } : {}),
+            ...(otel ? { otel } : {}),
         });
     }
     catch (err) {
@@ -435,6 +447,14 @@ async function runWorktreeLaunch(passthroughArgs, worktreeName, loadSessionWorkt
     catch {
         compat = { argv: [], env: {} };
     }
+    // OTel gate reads the WORKTREE's .pi/settings.json — that is the session's
+    // cwd, so a repo-committed otel config applies to its worktrees too.
+    const otel = await resolveOtelLaunchWithWorkspace({
+        env: process.env,
+        cwd: result.worktreePath,
+        creds,
+        profileName: profile.name,
+    });
     let plan;
     try {
         plan = buildLaunch(creds, remainingArgs, {
@@ -447,6 +467,7 @@ async function runWorktreeLaunch(passthroughArgs, worktreeName, loadSessionWorkt
             stateDir: credentialsDir(),
             cliVersion: cliVersion(),
             baseEnv: process.env,
+            ...(otel ? { otel } : {}),
         });
     }
     catch (err) {

package/dist/doctor.d.ts

@@ -13,6 +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 { type Profile } from "./profiles.js";
 export type CheckStatus = "ok" | "warn" | "fail";
 export interface CheckResult {
@@ -60,6 +61,12 @@ export declare function checkCliUpdate(probe: {
     latest: string | null;
 }): CheckResult;
 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 —
+ * most machines have no collector, and that is the healthy default.
+ */
+export declare function checkOtelExport(config: OtelLaunchConfig | undefined): CheckResult;
 /** What the Windows bash probe found (pi needs a bash — Git Bash — on win32). */
 export interface BashProbe {
     found: boolean;

package/dist/doctor.js

@@ -17,6 +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 { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
 // ── Pure check builders ─────────────────────────────────────────────────────
@@ -198,6 +199,32 @@ export function checkGh(onPath) {
         required: false,
     };
 }
+/**
+ * Advisory OTel-export line: says whether sessions will stream traces to an
+ * OTLP collector, and from which config source. Never flips the exit code —
+ * most machines have no collector, and that is the healthy default.
+ */
+export function checkOtelExport(config) {
+    if (!config) {
+        return {
+            name: "otel export (optional)",
+            status: "ok",
+            detail: "off (no OTLP endpoint configured)",
+            required: false,
+        };
+    }
+    const source = config.source === "env"
+        ? "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,
+    };
+}
 export function checkBash(probe) {
     if (!probe.found) {
         return {
@@ -379,6 +406,12 @@ export async function gatherChecks(deps = {}) {
     checks.push(checkBackend(backend));
     checks.push(checkStateDir(probeStateDir()));
     checks.push(checkGh(ghOnPath()));
+    checks.push(checkOtelExport(await resolveOtelLaunchWithWorkspace({
+        env: process.env,
+        cwd: process.cwd(),
+        creds: profile.token ? { baseUrl: profile.baseUrl, token: profile.token } : null,
+        profileName: profile.name,
+    })));
     return checks;
 }
 /**

package/dist/extension/pipeline/invocation.d.ts

@@ -65,9 +65,16 @@ export declare function buildStageInvocation(stage: PipelineStage, ctx: {
  * `yagni` provider) before a stage passthrough. Mirrors buildLaunch's
  * `userChoseProvider` guard so a passthrough that already chose a provider is
  * left untouched.
+ *
+ * `otelExtensionPath` (absent on a non-exporting launch) additionally loads
+ * pi-otel so child LLM spend is traced too — stage children are the bulk of a
+ * /go run's cost, and an OTel export that misses them undercounts. The path
+ * arrives via `YAGNI_OTEL_EXTENSION_PATH` from the launcher's gate (see the
+ * CLI's otel.ts); the capture-mode and endpoint env rides the inherited env.
  */
 export declare function groundedChildArgv(stageArgv: string[], opts: {
     piCli: string;
     extensionPath: string;
+    otelExtensionPath?: string;
 }): string[];
 //# sourceMappingURL=invocation.d.ts.map

package/dist/extension/pipeline/invocation.js

@@ -84,6 +84,12 @@ export function buildStageInvocation(stage, ctx) {
  * `yagni` provider) before a stage passthrough. Mirrors buildLaunch's
  * `userChoseProvider` guard so a passthrough that already chose a provider is
  * left untouched.
+ *
+ * `otelExtensionPath` (absent on a non-exporting launch) additionally loads
+ * pi-otel so child LLM spend is traced too — stage children are the bulk of a
+ * /go run's cost, and an OTel export that misses them undercounts. The path
+ * arrives via `YAGNI_OTEL_EXTENSION_PATH` from the launcher's gate (see the
+ * CLI's otel.ts); the capture-mode and endpoint env rides the inherited env.
  */
 export function groundedChildArgv(stageArgv, opts) {
     const userChoseProvider = stageArgv.includes("--provider");
@@ -91,6 +97,7 @@ export function groundedChildArgv(stageArgv, opts) {
         opts.piCli,
         "-e",
         opts.extensionPath,
+        ...(opts.otelExtensionPath ? ["-e", opts.otelExtensionPath] : []),
         ...(userChoseProvider ? [] : ["--provider", "yagni"]),
         ...stageArgv,
     ];

package/dist/extension/pipeline/runner.d.ts

@@ -32,6 +32,7 @@ export interface RunStageDeps {
     resolveChild?: () => {
         piCli: string;
         extensionPath: string;
+        otelExtensionPath?: string;
     };
     /** Optional environment for spawned child stages. Defaults to Node's inherited env. */
     env?: NodeJS.ProcessEnv;

package/dist/extension/pipeline/runner.js

@@ -61,11 +61,19 @@ async function defaultWritePrompt(body) {
 /**
  * Default child resolution: the parent process IS pi (so `process.argv[1]` is
  * pi's cli), and our compiled extension entry sits one dir up from this module.
+ *
+ * `otelExtensionPath` comes from `YAGNI_OTEL_EXTENSION_PATH`, set by the
+ * launcher only when an OTLP endpoint is configured (see the CLI's otel.ts) —
+ * children then load pi-otel so their LLM spend is traced. Guarded with
+ * existsSync so a stale env value degrades to an untraced child, never a
+ * child that fails to boot.
  */
 function defaultResolveChild() {
     const piCli = process.argv[1] ?? "pi";
     const extensionPath = fileURLToPath(new URL("../index.js", import.meta.url));
-    return { piCli, extensionPath };
+    const otelPath = process.env.YAGNI_OTEL_EXTENSION_PATH;
+    const otelExtensionPath = otelPath && fs.existsSync(otelPath) ? otelPath : undefined;
+    return { piCli, extensionPath, ...(otelExtensionPath ? { otelExtensionPath } : {}) };
 }
 const EMPTY_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 /** Truncate to PER_TASK_OUTPUT_CAP bytes, never exceeding the cap. */
@@ -116,8 +124,12 @@ export async function runStage(stage, ctx, deps) {
             lens: ctx.lens,
             ...(tierCap ? { tierCap } : {}),
         });
-        const { piCli, extensionPath } = resolveChild();
-        const argv = groundedChildArgv(passthrough, { piCli, extensionPath });
+        const { piCli, extensionPath, otelExtensionPath } = resolveChild();
+        const argv = groundedChildArgv(passthrough, {
+            piCli,
+            extensionPath,
+            ...(otelExtensionPath ? { otelExtensionPath } : {}),
+        });
         // Fold events into a fixed-size accumulator as they stream — never retain
         // the full array (that OOMs on a verbose stage; YAG-317 follow-up).
         const acc = newEventAccumulator();

package/dist/goHeadless.d.ts

@@ -15,6 +15,7 @@
  * runs locally and what the fleet executes are the same binary and the same
  * pipeline.
  */
+import { type OtelLaunchConfig } from "./otel.js";
 /** Mirrors HEADLESS_GO_EXIT in the extension; duplicated to keep the packages independent. */
 export declare const GO_EXIT: {
     readonly verified: 0;
@@ -64,6 +65,8 @@ export declare function buildHeadlessChildEnv(opts: {
     workspaceId?: string;
     cliVersion?: string;
     sessionId?: string;
+    /** Resolved OTel export config; stage children load pi-otel when present. */
+    otel?: OtelLaunchConfig;
 }): NodeJS.ProcessEnv;
 /**
  * Run `yagni go`. Returns the process exit code: 0 only on a verified

package/dist/goHeadless.js

@@ -20,6 +20,7 @@ import { mkdirSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { agentDirEnvVar } from "./branding.js";
 import { agentDir, credentialsDir } from "./credentials.js";
+import { otelChildEnv, resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { credentialsFromProfile, profilePath, readActiveProfile } from "./profiles.js";
 import { resolveHeadlessGoPath, resolvePiCliPath } from "./paths.js";
 /** Mirrors HEADLESS_GO_EXIT in the extension; duplicated to keep the packages independent. */
@@ -54,6 +55,9 @@ export function buildHeadlessChildEnv(opts) {
         PI_CODING_AGENT_DIR: piAgentDir,
         PI_SKIP_VERSION_CHECK: "1",
         PI_TELEMETRY: "0",
+        // OTel export: pin metadata-only capture and forward pi-otel's path so
+        // every stage child spawns with it (see otel.ts for the policy).
+        ...(opts.otel ? otelChildEnv(opts.otel, opts.baseEnv) : {}),
     };
 }
 /**
@@ -88,6 +92,14 @@ export async function goCommand(args, deps = {}, cliVersion) {
         writeErr(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`yagni login\` first.`);
         return GO_EXIT.usage;
     }
+    // Same OTel gate as an interactive launch — a headless /go run's stage
+    // children are LLM spend too, and the pilot's cost A/B needs to see them.
+    const otel = await resolveOtelLaunchWithWorkspace({
+        env: baseEnv,
+        cwd: deps.cwd ?? process.cwd(),
+        creds: { baseUrl, token },
+        profileName: profile.name,
+    });
     const childEnv = buildHeadlessChildEnv({
         baseEnv,
         token,
@@ -96,6 +108,7 @@ export async function goCommand(args, deps = {}, cliVersion) {
         ...(profile.expiresAt ? { expiresAt: profile.expiresAt } : {}),
         ...(profile.workspaceId ? { workspaceId: profile.workspaceId } : {}),
         ...(cliVersion ? { cliVersion } : {}),
+        ...(otel ? { otel } : {}),
     });
     // The hermetic agent dir must exist before a stage child tries to read it.
     try {

package/dist/launch.d.ts

@@ -6,6 +6,7 @@
  * defaults the provider to `yagni`.
  */
 import type { Credentials } from "./credentials.js";
+import { type OtelLaunchConfig } from "./otel.js";
 export interface LaunchPlan {
     env: NodeJS.ProcessEnv;
     argv: string[];
@@ -92,6 +93,13 @@ export interface BuildLaunchOptions {
      * override the token, base URL, or hermetic agent dir.
      */
     extraEnv?: Record<string, string>;
+    /**
+     * Resolved OTel export config (see `otel.ts`). When present, the session
+     * loads pi-otel alongside our extension and the env pins metadata-only
+     * capture; absent means no OTLP endpoint is configured and the launch is
+     * byte-for-byte what it was before OTel support existed.
+     */
+    otel?: OtelLaunchConfig;
 }
 export declare function buildLaunch(creds: Credentials | null, passthroughArgs: string[], opts: BuildLaunchOptions): LaunchPlan;
 //# sourceMappingURL=launch.d.ts.map

package/dist/launch.js

@@ -7,6 +7,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { agentDirEnvVar } from "./branding.js";
+import { otelChildEnv } from "./otel.js";
 import { PAD_X_ENV, resolvePadX } from "./padding.js";
 import { ENGINEERING_PRACTICE_SECTION, promptEnrichmentDisabled } from "./promptEnrichment.js";
 /**
@@ -105,6 +106,10 @@ export function buildLaunch(creds, passthroughArgs, opts) {
         // the editor (which the launcher pads by seeding editorPaddingX). The
         // footer can't read pi's settings, so the value crosses over env.
         [PAD_X_ENV]: String(resolvePadX()),
+        // OTel export (gated in otel.ts): pin metadata-only capture and forward
+        // pi-otel's path so /go stage children and subagents load it too. Placed
+        // after baseEnv on purpose — the capture pin must beat a user env override.
+        ...(opts.otel ? otelChildEnv(opts.otel, opts.baseEnv ?? {}) : {}),
     };
     // Always load our extension. Default the provider to `yagni` unless the user
     // explicitly chose one (so power users can still point pi elsewhere).
@@ -125,6 +130,7 @@ export function buildLaunch(creds, passthroughArgs, opts) {
     const argv = [
         "-e",
         opts.extensionPath,
+        ...(opts.otel ? ["-e", opts.otel.extensionPath] : []),
         ...(userChoseProvider ? [] : ["--provider", "yagni"]),
         ...(userChoseModel ? [] : ["--model", "advanced"]),
         ...(enrichmentOff ? [] : ["--append-system-prompt", ENGINEERING_PRACTICE_SECTION]),

package/dist/otel.d.ts

@@ -0,0 +1,150 @@
+/**
+ * OTel export wiring (Updater pilot ask): bake the `pi-otel` extension into
+ * every launch so a workspace can stream session traces — token usage, cost,
+ * model tier, tool calls — to its own OTLP collector (e.g. Datadog) without
+ * anyone hand-installing an extension.
+ *
+ * Three deliberate policies, all enforced here rather than left to defaults:
+ *
+ * 1. GATED, not always-on. pi-otel ships `enabled: true` pointed at
+ *    `localhost:4317`, so loading it unconditionally would have every session
+ *    probing a collector nobody runs. We only pass the extension to pi when an
+ *    OTLP endpoint is actually configured: `OTEL_EXPORTER_OTLP_ENDPOINT` in the
+ *    environment, or `otel.endpoint` in the repo's committed `.pi/settings.json`
+ *    (the file pi-otel itself reads, so teams can configure once per repo).
+ *
+ * 2. METADATA-ONLY, enforced. Cost, tokens, model, finish reasons and tool-call
+ *    ids export; prompt and response text never do. `PI_OTEL_CAPTURE_CONTENT`
+ *    is pinned in the child env, and env beats settings in pi-otel's own
+ *    precedence — a repo settings file asking for "full" is overridden, not
+ *    honored. Session content leaving the machine is a contract change, not a
+ *    config knob.
+ *
+ * 3. Cost is the customer's SELL rate. pi-otel exports pi's `usage.cost.total`
+ *    verbatim (as `pi.cost.usd`), and pi computes that from the catalog's
+ *    tier rates (YAG-381) — so the collector sees contracted prices, and the
+ *    exported model name is the opaque tier id, never the backing model.
+ *
+ * Everything here is fail-soft: telemetry must never block a launch, so a
+ * missing package or unreadable settings file resolves to "disabled".
+ */
+import { readFileSync } from "node:fs";
+/**
+ * Env var carrying the resolved pi-otel entry path to /go stage children and
+ * subagents: they build their own pi argv inside pi-extension-yagni (which
+ * cannot import this package), so the path crosses over env. The extension
+ * reads the same literal in `pipeline/runner.ts`.
+ */
+export declare const OTEL_EXTENSION_PATH_ENV = "YAGNI_OTEL_EXTENSION_PATH";
+/** The service name a collector sees unless the user set their own. */
+export declare const DEFAULT_OTEL_SERVICE_NAME = "yagni-code";
+export interface OtelLaunchConfig {
+    /** Absolute path to pi-otel's extension entry. */
+    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).
+     */
+    source: "env" | "workspace" | "project-settings";
+    /** The configured OTLP endpoint (for doctor display; env for workspace source). */
+    endpoint: string;
+    /** Workspace-configured OTLP protocol (workspace source only). */
+    protocol?: string;
+    /** Workspace-configured collector headers (workspace source only; carries secrets). */
+    headers?: Record<string, string>;
+    /** Workspace-configured service name (workspace source only). */
+    serviceName?: string;
+}
+/**
+ * The `otel` block a workspace admin configures in the web app, as served on
+ * GET /api/yagni-code/models (decrypted headers included — this is the same
+ * trust boundary as the YAGNI_TOKEN that fetched it).
+ */
+export interface WorkspaceOtelConfig {
+    enabled: boolean;
+    endpoint: string;
+    protocol?: string;
+    serviceName?: string | null;
+    headers?: Record<string, string>;
+}
+/**
+ * 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).
+ */
+export declare function resolveOtelLaunch(opts: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /** Injectable seams for tests. */
+    resolveExtension?: () => string;
+    readFile?: typeof readFileSync;
+}): OtelLaunchConfig | undefined;
+/**
+ * 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;
+/**
+ * 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
+ * when the user has not chosen their own.
+ *
+ * A "workspace"-sourced config additionally delivers the admin-set endpoint,
+ * protocol, and collector headers over the standard OTel env vars — but any
+ * of those the USER already set in their own environment wins (local env >
+ * workspace config), so an engineer can point one session at a scratch
+ * collector without an admin change.
+ */
+export declare function otelChildEnv(config: OtelLaunchConfig, baseEnv: NodeJS.ProcessEnv): Record<string, string>;
+export interface WorkspaceOtelFetchDeps {
+    fetchImpl?: typeof fetch;
+    cacheDir?: string;
+    timeoutMs?: number;
+}
+/**
+ * Resolve the workspace's admin-set OTel config: one fail-soft GET of the
+ * catalog endpoint (which carries the additive `otel` block), cached on disk
+ * per profile so a slow or offline backend degrades to last-known config
+ * instead of a launch stall.
+ *
+ * Cache semantics matter for revocation: a SUCCESSFUL response without an
+ * otel block means the admin disabled or removed the config, so the cache is
+ * DELETED — only a network/HTTP failure falls back to it. Otherwise turning
+ * export off in the web app would leave every laptop exporting (with a stale
+ * collector key) until the cache happened to be overwritten.
+ *
+ * The cache lives under the credentials dir at mode 0600 — the same posture
+ * as the profile token files, which is the right comparison: the cached
+ * headers carry the collector key, the profile carries the YAGNI token.
+ */
+export declare function fetchWorkspaceOtel(creds: {
+    baseUrl: string;
+    token: string;
+}, profileName: string, deps?: WorkspaceOtelFetchDeps): Promise<WorkspaceOtelConfig | null>;
+/**
+ * Full launch-time resolution, all three 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.
+ *   3. workspace config        — admin-set in the web app, fetched/cached.
+ *   4. repo `.pi/settings.json` — committed per-repo config.
+ *
+ * `creds` absent (not logged in — doctor on a fresh machine) skips source 3.
+ */
+export declare function resolveOtelLaunchWithWorkspace(opts: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    creds?: {
+        baseUrl: string;
+        token: string;
+    } | null;
+    profileName?: string;
+    resolveExtension?: () => string;
+    readFile?: typeof readFileSync;
+    fetchDeps?: WorkspaceOtelFetchDeps;
+    fetchWorkspace?: typeof fetchWorkspaceOtel;
+}): Promise<OtelLaunchConfig | undefined>;
+//# sourceMappingURL=otel.d.ts.map

package/dist/otel.js

@@ -0,0 +1,291 @@
+/**
+ * OTel export wiring (Updater pilot ask): bake the `pi-otel` extension into
+ * every launch so a workspace can stream session traces — token usage, cost,
+ * model tier, tool calls — to its own OTLP collector (e.g. Datadog) without
+ * anyone hand-installing an extension.
+ *
+ * Three deliberate policies, all enforced here rather than left to defaults:
+ *
+ * 1. GATED, not always-on. pi-otel ships `enabled: true` pointed at
+ *    `localhost:4317`, so loading it unconditionally would have every session
+ *    probing a collector nobody runs. We only pass the extension to pi when an
+ *    OTLP endpoint is actually configured: `OTEL_EXPORTER_OTLP_ENDPOINT` in the
+ *    environment, or `otel.endpoint` in the repo's committed `.pi/settings.json`
+ *    (the file pi-otel itself reads, so teams can configure once per repo).
+ *
+ * 2. METADATA-ONLY, enforced. Cost, tokens, model, finish reasons and tool-call
+ *    ids export; prompt and response text never do. `PI_OTEL_CAPTURE_CONTENT`
+ *    is pinned in the child env, and env beats settings in pi-otel's own
+ *    precedence — a repo settings file asking for "full" is overridden, not
+ *    honored. Session content leaving the machine is a contract change, not a
+ *    config knob.
+ *
+ * 3. Cost is the customer's SELL rate. pi-otel exports pi's `usage.cost.total`
+ *    verbatim (as `pi.cost.usd`), and pi computes that from the catalog's
+ *    tier rates (YAG-381) — so the collector sees contracted prices, and the
+ *    exported model name is the opaque tier id, never the backing model.
+ *
+ * Everything here is fail-soft: telemetry must never block a launch, so a
+ * missing package or unreadable settings file resolves to "disabled".
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { credentialsDir } from "./credentials.js";
+/**
+ * Env var carrying the resolved pi-otel entry path to /go stage children and
+ * subagents: they build their own pi argv inside pi-extension-yagni (which
+ * cannot import this package), so the path crosses over env. The extension
+ * reads the same literal in `pipeline/runner.ts`.
+ */
+export const OTEL_EXTENSION_PATH_ENV = "YAGNI_OTEL_EXTENSION_PATH";
+/** The service name a collector sees unless the user set their own. */
+export const DEFAULT_OTEL_SERVICE_NAME = "yagni-code";
+/**
+ * Read `otel.endpoint` from the repo's `.pi/settings.json`, the project-level
+ * file pi-otel itself resolves config from. Returns undefined on any problem —
+ * a malformed settings file must not block a launch (pi-otel will surface its
+ * own complaint in-session).
+ */
+function projectOtelEndpoint(cwd, readFile) {
+    try {
+        const raw = readFile(join(cwd, ".pi", "settings.json"), "utf8");
+        const parsed = JSON.parse(String(raw));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const otel = parsed.otel;
+        if (typeof otel !== "object" || otel === null)
+            return undefined;
+        const endpoint = otel.endpoint;
+        return typeof endpoint === "string" && endpoint.trim() !== "" ? endpoint.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Truthy per pi-otel's own convention for PI_OTEL_DISABLED. */
+function envDisabled(env) {
+    return env.PI_OTEL_DISABLED === "1" || env.PI_OTEL_DISABLED === "true";
+}
+/**
+ * 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).
+ */
+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)
+        return undefined;
+    let extensionPath;
+    try {
+        extensionPath = (opts.resolveExtension ?? resolveOtelExtensionPath)();
+    }
+    catch {
+        return undefined;
+    }
+    return envEndpoint
+        ? { extensionPath, source: "env", endpoint: envEndpoint }
+        : { extensionPath, source: "project-settings", endpoint: settingsEndpoint };
+}
+/**
+ * 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 function resolveOtelExtensionPath() {
+    const path = fileURLToPath(import.meta.resolve("pi-otel"));
+    if (!existsSync(path)) {
+        throw new Error(`pi-otel entry not found at ${path}`);
+    }
+    return path;
+}
+/**
+ * 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
+ * when the user has not chosen their own.
+ *
+ * A "workspace"-sourced config additionally delivers the admin-set endpoint,
+ * protocol, and collector headers over the standard OTel env vars — but any
+ * of those the USER already set in their own environment wins (local env >
+ * workspace config), so an engineer can point one session at a scratch
+ * collector without an admin change.
+ */
+export function otelChildEnv(config, baseEnv) {
+    const workspace = {};
+    if (config.source === "workspace") {
+        if (!baseEnv.OTEL_EXPORTER_OTLP_ENDPOINT) {
+            workspace.OTEL_EXPORTER_OTLP_ENDPOINT = config.endpoint;
+        }
+        if (config.protocol && !baseEnv.OTEL_EXPORTER_OTLP_PROTOCOL) {
+            workspace.OTEL_EXPORTER_OTLP_PROTOCOL = config.protocol;
+        }
+        if (config.headers && Object.keys(config.headers).length > 0 && !baseEnv.OTEL_EXPORTER_OTLP_HEADERS) {
+            workspace.OTEL_EXPORTER_OTLP_HEADERS = Object.entries(config.headers)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(",");
+        }
+        if (config.serviceName && !baseEnv.OTEL_SERVICE_NAME) {
+            workspace.OTEL_SERVICE_NAME = config.serviceName;
+        }
+    }
+    return {
+        ...workspace,
+        [OTEL_EXTENSION_PATH_ENV]: config.extensionPath,
+        PI_OTEL_CAPTURE_CONTENT: "metadata_only",
+        ...(baseEnv.OTEL_SERVICE_NAME || workspace.OTEL_SERVICE_NAME
+            ? {}
+            : { OTEL_SERVICE_NAME: DEFAULT_OTEL_SERVICE_NAME }),
+    };
+}
+// ── Workspace-configured export (admin sets it once in the web app) ─────────
+/** How long the launcher waits on the config fetch before falling back to the
+ * on-disk cache. Launch latency is user-facing; telemetry config is not worth
+ * more than this. */
+const WORKSPACE_FETCH_TIMEOUT_MS = 1_500;
+function workspaceCachePath(profileName, dir) {
+    // Profile names are already path-safe (they name profile JSON files).
+    return join(dir, "otel", `${profileName}.json`);
+}
+function parseWorkspaceOtel(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const o = raw;
+    if (o.enabled !== true || typeof o.endpoint !== "string" || o.endpoint.trim() === "") {
+        return null;
+    }
+    const headers = {};
+    if (typeof o.headers === "object" && o.headers !== null) {
+        for (const [k, v] of Object.entries(o.headers)) {
+            if (typeof v === "string")
+                headers[k] = v;
+        }
+    }
+    return {
+        enabled: true,
+        endpoint: o.endpoint.trim(),
+        ...(typeof o.protocol === "string" ? { protocol: o.protocol } : {}),
+        ...(typeof o.serviceName === "string" && o.serviceName ? { serviceName: o.serviceName } : {}),
+        headers,
+    };
+}
+/**
+ * Resolve the workspace's admin-set OTel config: one fail-soft GET of the
+ * catalog endpoint (which carries the additive `otel` block), cached on disk
+ * per profile so a slow or offline backend degrades to last-known config
+ * instead of a launch stall.
+ *
+ * Cache semantics matter for revocation: a SUCCESSFUL response without an
+ * otel block means the admin disabled or removed the config, so the cache is
+ * DELETED — only a network/HTTP failure falls back to it. Otherwise turning
+ * export off in the web app would leave every laptop exporting (with a stale
+ * collector key) until the cache happened to be overwritten.
+ *
+ * The cache lives under the credentials dir at mode 0600 — the same posture
+ * as the profile token files, which is the right comparison: the cached
+ * headers carry the collector key, the profile carries the YAGNI token.
+ */
+export async function fetchWorkspaceOtel(creds, profileName, deps = {}) {
+    const cacheDir = deps.cacheDir ?? credentialsDir();
+    const cachePath = workspaceCachePath(profileName, cacheDir);
+    const doFetch = deps.fetchImpl ?? fetch;
+    let body;
+    try {
+        const res = await doFetch(`${creds.baseUrl}/api/yagni-code/models`, {
+            method: "GET",
+            headers: { authorization: `Bearer ${creds.token}` },
+            signal: AbortSignal.timeout(deps.timeoutMs ?? WORKSPACE_FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        body = await res.json();
+    }
+    catch {
+        // Network/HTTP failure → last-known config (or nothing). Fail-soft by
+        // design: the fallback is visible via `yagni doctor`, not a launch error.
+        return readWorkspaceOtelCache(cachePath);
+    }
+    const config = parseWorkspaceOtel(body?.otel);
+    try {
+        if (config) {
+            mkdirSync(join(cacheDir, "otel"), { recursive: true, mode: 0o700 });
+            writeFileSync(cachePath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+        }
+        else {
+            rmSync(cachePath, { force: true });
+        }
+    }
+    catch {
+        // Cache maintenance is best-effort; the fresh result still applies.
+    }
+    return config;
+}
+function readWorkspaceOtelCache(cachePath) {
+    try {
+        return parseWorkspaceOtel(JSON.parse(readFileSync(cachePath, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Full launch-time resolution, all three 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.
+ *   3. workspace config        — admin-set in the web app, fetched/cached.
+ *   4. repo `.pi/settings.json` — committed per-repo config.
+ *
+ * `creds` absent (not logged in — doctor on a fresh machine) skips source 3.
+ */
+export async function resolveOtelLaunchWithWorkspace(opts) {
+    const { env, cwd } = 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()) {
+        return resolveOtelLaunch({
+            env,
+            cwd,
+            ...(opts.resolveExtension ? { resolveExtension: opts.resolveExtension } : {}),
+            ...(opts.readFile ? { readFile: opts.readFile } : {}),
+        });
+    }
+    // Source 3: workspace config.
+    if (opts.creds?.token && opts.profileName) {
+        const workspace = await (opts.fetchWorkspace ?? fetchWorkspaceOtel)({ baseUrl: opts.creds.baseUrl, token: opts.creds.token }, opts.profileName, opts.fetchDeps ?? {});
+        if (workspace) {
+            let extensionPath;
+            try {
+                extensionPath = (opts.resolveExtension ?? resolveOtelExtensionPath)();
+            }
+            catch {
+                return undefined;
+            }
+            return {
+                extensionPath,
+                source: "workspace",
+                endpoint: workspace.endpoint,
+                ...(workspace.protocol ? { protocol: workspace.protocol } : {}),
+                ...(workspace.serviceName ? { serviceName: workspace.serviceName } : {}),
+                ...(workspace.headers && Object.keys(workspace.headers).length > 0
+                    ? { headers: workspace.headers }
+                    : {}),
+            };
+        }
+    }
+    // Source 4: repo-committed settings.
+    return resolveOtelLaunch({
+        env,
+        cwd,
+        ...(opts.resolveExtension ? { resolveExtension: opts.resolveExtension } : {}),
+        ...(opts.readFile ? { readFile: opts.readFile } : {}),
+    });
+}
+//# sourceMappingURL=otel.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.0.0-staging.1180.1",
+  "version": "1.0.0-staging.1183.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)",
@@ -36,9 +36,10 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.1",
     "@earendil-works/pi-tui": "0.84.1",
+    "pi-otel": "0.1.0",
     "smol-toml": "^1.8.0",
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "1db89538911e63de0e383aad36bd707e947140d9"
+  "yagniSourceSha": "723499f455c038162f0ddb3bc886e7e3c55b07f5"
 }