@yagni-app/code 1.0.0 → 1.0.1

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/dist/outputFormat.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `--output-format` support for headless/print mode (YAG-593).
+ *
+ * The launcher parses `--output-format` out of argv (pi doesn't know about it),
+ * maps it to pi's `--mode json` internally, and post-processes pi's NDJSON
+ * event stream into a single JSON result object — mirroring Claude Code's
+ * `--output-format json` shape.
+ */
+export type OutputFormat = "text" | "json" | "stream-json";
+/**
+ * Strip `--output-format <value>` (or `--output-format=<value>`) from argv.
+ * Returns the format and the remaining args (with the flag removed).
+ * Unknown values fall back to "text" with a stderr warning.
+ */
+export declare function parseOutputFormat(argv: string[], writeErr?: (line: string) => void): {
+    format: OutputFormat;
+    remainingArgs: string[];
+};
+export interface ToolUsed {
+    name: string;
+    is_error: boolean;
+}
+export interface GuardianReview {
+    outcome: string;
+    duration_ms?: number;
+    tier?: string;
+    /** True when the command was blocked (ask in headless or deny). */
+    blocked?: boolean;
+}
+export interface ResultObject {
+    type: "result";
+    subtype: "success" | "error_during_execution";
+    result: string;
+    is_error: boolean;
+    duration_ms: number;
+    num_turns: number;
+    session_id: string;
+    total_cost_usd: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        total_tokens: number;
+    };
+    tools_used: ToolUsed[];
+    guardian_reviews: GuardianReview[];
+    stop_reason: string | null;
+}
+interface ParsedEvent {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Parse raw NDJSON text (pi's --mode json stdout) into an array of event objects.
+ * Skips blank lines. Fail-soft: unparseable lines are skipped.
+ */
+export declare function parseJsonEvents(raw: string): ParsedEvent[];
+/**
+ * Build the single JSON result object from collected pi events and Guardian
+ * events. Pure — no I/O.
+ *
+ * @param events     NDJSON event objects from pi's --mode json stdout
+ * @param guardian   Guardian review entries from the error sink
+ * @param durationMs Wall-clock time measured by the launcher
+ * @param verbose    When true, returns the raw events array instead of a single object
+ */
+export declare function buildResultObject(opts: {
+    events: ParsedEvent[];
+    guardianEvents?: GuardianReview[];
+    durationMs: number;
+    verbose?: boolean;
+}): ResultObject | ParsedEvent[];
+/**
+ * Read Guardian review events from the error sink JSONL, filtered by
+ * YAGNI_SESSION_ID. The error sink is written by the extension during the
+ * session; this reads it post-run. Fail-soft: returns [] on any error.
+ */
+export declare function readGuardianEvents(yagniSessionId: string, opts?: {
+    homeDir?: string;
+    now?: Date;
+}): GuardianReview[];
+export {};
+//# sourceMappingURL=outputFormat.d.ts.map