@powerhousedao/ph-clint-observability 0.1.0-dev.69

package/README.md

@@ -0,0 +1,58 @@
+# @powerhousedao/ph-clint-observability
+
+OpenTelemetry + Sentry observability plugin for ph-clint CLIs.
+
+## Install
+
+```sh
+pnpm add @powerhousedao/ph-clint-observability
+```
+
+Then in your CLI's `defineCli` call:
+
+```ts
+import { defineCli } from '@powerhousedao/ph-clint';
+import { observability } from '@powerhousedao/ph-clint-observability';
+
+defineCli({
+  // ...
+  lifecycle: [observability()],
+});
+```
+
+## Configuration
+
+Two env vars (auto-derived from the framework's `{CLINAME}_{FIELD_NAME}` convention):
+
+- `{CLINAME}_SENTRY_DSN` — Sentry DSN. If unset, Sentry is not initialized.
+- `{CLINAME}_OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP HTTP base endpoint for traces and metrics. If unset, OTel is not initialized.
+
+When neither is set, the plugin contributes identity wraps (zero overhead) and writes one log line on startup.
+
+## Runtime opt-in
+
+When at least one destination is configured, the plugin prompts the end-user on first run for telemetry consent. Consent is persisted to `~/.ph/<cliname>/observability-consent.json`. Non-interactive runs default to denied.
+
+To revoke or re-prompt, delete or edit that file:
+
+```jsonc
+{ "consent": "denied", "promptedAt": "..." }
+```
+
+## Local development receiver
+
+```sh
+pnpm telemetry:dev
+```
+
+Runs a small OTLP HTTP receiver on `127.0.0.1:4318` and announces the env var to set so your CLI sends telemetry there. Incoming spans and metrics are pretty-printed to stdout.
+
+## What's instrumented
+
+- `framework.bootstrap` — retroactive span covering the pre-config boot window (using `LifecycleInitContext.bootTimings`).
+- `command.execute` — span + `clint.command.executions` counter (result: success|error).
+- `agent.stream` + child `llm.call` — span + token-usage attributes + `clint.agent.stream.duration` histogram.
+- `tool.execute` — span + `clint.tool.executions` counter.
+- `routine.iteration` — span + `clint.routine.iterations` counter.
+
+No auto-instrumentation; no monkey-patching of Node stdlib. The framework's own seams provide all visibility.

package/dist/consent.d.ts

@@ -0,0 +1,34 @@
+import type { Readable, Writable } from 'node:stream';
+export type ConsentValue = 'unknown' | 'granted' | 'denied';
+export interface ConsentRecord {
+    consent: ConsentValue;
+    promptedAt: string | null;
+}
+/**
+ * Read the consent record. Returns `{ consent: 'unknown', promptedAt: null }`
+ * when the file doesn't exist or is malformed (we treat ambiguity as
+ * not-yet-asked rather than denied, so a corrupted file re-prompts on next
+ * interactive run).
+ */
+export declare function readConsent(userStoreFolder: string): Promise<ConsentRecord>;
+export declare function writeConsent(userStoreFolder: string, record: ConsentRecord): Promise<void>;
+/**
+ * Truncate a Sentry DSN to host+project for display. A DSN looks like
+ * `https://<publicKey>@<host>/<projectId>`. Stripping the public key avoids
+ * leaking secret-shaped data into the prompt text.
+ */
+export declare function safeDsnDisplay(dsn: string): string;
+export interface PromptOptions {
+    cliName: string;
+    sentryDsn?: string;
+    otelEndpoint?: string;
+    input?: Readable;
+    output?: Writable;
+}
+/**
+ * Ask the end-user whether to enable telemetry. Returns 'granted' or 'denied'.
+ *
+ * Default answer (empty input or anything not starting with y/Y) is 'denied' —
+ * opt-in stance per privacy norms.
+ */
+export declare function promptForConsent(opts: PromptOptions): Promise<ConsentValue>;

package/dist/consent.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+const FILENAME = 'observability-consent.json';
+/**
+ * Read the consent record. Returns `{ consent: 'unknown', promptedAt: null }`
+ * when the file doesn't exist or is malformed (we treat ambiguity as
+ * not-yet-asked rather than denied, so a corrupted file re-prompts on next
+ * interactive run).
+ */
+export async function readConsent(userStoreFolder) {
+    const filePath = path.join(userStoreFolder, FILENAME);
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.consent === 'granted' || parsed.consent === 'denied' || parsed.consent === 'unknown') {
+            return {
+                consent: parsed.consent,
+                promptedAt: typeof parsed.promptedAt === 'string' ? parsed.promptedAt : null,
+            };
+        }
+    }
+    catch {
+        // ENOENT or malformed JSON → fall through to unknown
+    }
+    return { consent: 'unknown', promptedAt: null };
+}
+export async function writeConsent(userStoreFolder, record) {
+    await fs.mkdir(userStoreFolder, { recursive: true });
+    const filePath = path.join(userStoreFolder, FILENAME);
+    await fs.writeFile(filePath, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Truncate a Sentry DSN to host+project for display. A DSN looks like
+ * `https://<publicKey>@<host>/<projectId>`. Stripping the public key avoids
+ * leaking secret-shaped data into the prompt text.
+ */
+export function safeDsnDisplay(dsn) {
+    try {
+        const u = new URL(dsn);
+        return `${u.protocol}//${u.host}${u.pathname}`;
+    }
+    catch {
+        return '(invalid DSN)';
+    }
+}
+/**
+ * Ask the end-user whether to enable telemetry. Returns 'granted' or 'denied'.
+ *
+ * Default answer (empty input or anything not starting with y/Y) is 'denied' —
+ * opt-in stance per privacy norms.
+ */
+export async function promptForConsent(opts) {
+    const rl = readline.createInterface({
+        input: opts.input ?? process.stdin,
+        output: opts.output ?? process.stdout,
+    });
+    try {
+        const destinations = [];
+        if (opts.sentryDsn)
+            destinations.push(`  • Sentry → ${safeDsnDisplay(opts.sentryDsn)}`);
+        if (opts.otelEndpoint)
+            destinations.push(`  • OpenTelemetry → ${opts.otelEndpoint}`);
+        const lines = [
+            '',
+            `${opts.cliName} can share observability data with the following destinations:`,
+            ...destinations,
+            '',
+        ].join('\n');
+        (opts.output ?? process.stdout).write(lines);
+        const answer = (await rl.question('Enable telemetry? (y/N) ')).trim();
+        return /^y(es)?$/i.test(answer) ? 'granted' : 'denied';
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/dev-server.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+interface CliArgs {
+    cliName: string;
+    port: number;
+    host: string;
+}
+export declare function parseCliArgs(argv: string[]): CliArgs;
+export declare function envPrefix(cliName: string): string;
+export interface DevServerOptions {
+    cliName: string;
+    port: number;
+    host: string;
+    /** Where to write logs. Defaults to process.stdout. */
+    out?: NodeJS.WritableStream;
+}
+export interface DevServerHandle {
+    url: string;
+    port: number;
+    close: () => Promise<void>;
+}
+/**
+ * Start the receiver and return a handle for tests / programmatic use. The
+ * server listens until `close()` is called or the process exits.
+ */
+export declare function startDevServer(opts: DevServerOptions): Promise<DevServerHandle>;
+export {};

package/dist/dev-server.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * ph-telemetry-dev — local OTLP HTTP receiver for dev work.
+ *
+ * Inspired by the deleted service-announcer pattern: prints the endpoint to
+ * stdout so the dev knows what env var to set in another terminal before
+ * running their CLI.
+ *
+ * Receives OTel OTLP HTTP at /v1/traces and /v1/metrics. JSON payloads
+ * (OTEL_EXPORTER_OTLP_PROTOCOL=http/json on the sender side) are
+ * pretty-printed; protobuf payloads show byte length only.
+ */
+import http from 'node:http';
+import { parseArgs } from 'node:util';
+export function parseCliArgs(argv) {
+    const { values } = parseArgs({
+        args: argv.slice(2),
+        options: {
+            'cli-name': { type: 'string' },
+            port: { type: 'string', default: '4318' },
+            host: { type: 'string', default: '127.0.0.1' },
+        },
+    });
+    return {
+        cliName: values['cli-name'] ?? 'mycli',
+        port: Number(values.port),
+        host: values.host ?? '127.0.0.1',
+    };
+}
+export function envPrefix(cliName) {
+    return cliName.toUpperCase().replace(/-/g, '_');
+}
+/**
+ * Start the receiver and return a handle for tests / programmatic use. The
+ * server listens until `close()` is called or the process exits.
+ */
+export async function startDevServer(opts) {
+    const out = opts.out ?? process.stdout;
+    const server = http.createServer((req, res) => {
+        if (req.url === '/v1/traces' || req.url === '/v1/metrics') {
+            const chunks = [];
+            req.on('data', (c) => chunks.push(c));
+            req.on('end', () => {
+                const body = Buffer.concat(chunks);
+                const kind = req.url === '/v1/traces' ? 'TRACE' : 'METRIC';
+                try {
+                    const json = JSON.parse(body.toString('utf-8'));
+                    out.write(`[${kind}] ${JSON.stringify(json, null, 2)}\n`);
+                }
+                catch {
+                    out.write(`[${kind}] ${body.length} bytes (protobuf — set OTEL_EXPORTER_OTLP_PROTOCOL=http/json for readable output)\n`);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/x-protobuf' });
+                res.end();
+            });
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port, opts.host, () => resolve());
+    });
+    const addr = server.address();
+    const actualPort = typeof addr === 'object' && addr ? addr.port : opts.port;
+    const url = `http://${opts.host}:${actualPort}`;
+    const upper = envPrefix(opts.cliName);
+    out.write(`\nph-telemetry-dev — local OTLP receiver listening on ${url}\n\n`);
+    out.write('Point your CLI at this receiver by exporting:\n');
+    out.write(`  ${upper}_OTEL_EXPORTER_OTLP_ENDPOINT=${url}\n\n`);
+    out.write('Optional (for readable trace payloads):\n');
+    out.write('  OTEL_EXPORTER_OTLP_PROTOCOL=http/json\n\n');
+    return {
+        url,
+        port: actualPort,
+        close: () => new Promise((resolve, reject) => server.close((err) => err ? reject(err) : resolve())),
+    };
+}
+/* istanbul ignore next -- entry-point bootstrap; exercised by manual `pnpm telemetry:dev` */
+async function main() {
+    const args = parseCliArgs(process.argv);
+    const handle = await startDevServer(args);
+    process.once('SIGINT', () => { void handle.close().then(() => process.exit(0)); });
+    process.once('SIGTERM', () => { void handle.close().then(() => process.exit(0)); });
+}
+// Only run main when invoked as a script (not when imported by tests).
+/* istanbul ignore next */
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((err) => {
+        process.stderr.write(`ph-telemetry-dev: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { observability, observabilityConfigSchema } from './plugin.js';
+export type { ObservabilityOptions, ObservabilityConfig } from './plugin.js';
+export type { ConsentValue, ConsentRecord } from './consent.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { observability, observabilityConfigSchema } from './plugin.js';

package/dist/otel.d.ts

@@ -0,0 +1,24 @@
+import type { Tracer, Meter } from '@opentelemetry/api';
+export interface OtelInitInput {
+    endpoint: string;
+    serviceName: string;
+    version: string;
+    sentryEnabled: boolean;
+}
+export interface OtelHandle {
+    tracer: Tracer;
+    meter: Meter;
+    shutdown: () => Promise<void>;
+}
+/**
+ * Dynamic-imported OpenTelemetry NodeSDK init. No auto-instrumentation:
+ * the framework's wrap registry provides all instrumentation points, so
+ * there is zero monkey-patching of Node stdlib. The SDK loads, sets up
+ * BatchSpanProcessor + PeriodicExportingMetricReader against the configured
+ * OTLP HTTP endpoint, and stops.
+ *
+ * If Sentry is also enabled, SentrySpanProcessor is added so spans flow to
+ * both Tempo/OTLP backend AND Sentry — single source, two sinks, matching
+ * trace IDs.
+ */
+export declare function initOtel(opts: OtelInitInput): Promise<OtelHandle>;

package/dist/otel.js

@@ -0,0 +1,57 @@
+function stripTrailingSlash(s) {
+    return s.replace(/\/$/, '');
+}
+/**
+ * Dynamic-imported OpenTelemetry NodeSDK init. No auto-instrumentation:
+ * the framework's wrap registry provides all instrumentation points, so
+ * there is zero monkey-patching of Node stdlib. The SDK loads, sets up
+ * BatchSpanProcessor + PeriodicExportingMetricReader against the configured
+ * OTLP HTTP endpoint, and stops.
+ *
+ * If Sentry is also enabled, SentrySpanProcessor is added so spans flow to
+ * both Tempo/OTLP backend AND Sentry — single source, two sinks, matching
+ * trace IDs.
+ */
+export async function initOtel(opts) {
+    const [{ NodeSDK }, { OTLPTraceExporter }, { OTLPMetricExporter }, sdkMetrics, sdkTraceBase, resourcesMod, semconv, apiMod,] = await Promise.all([
+        import('@opentelemetry/sdk-node'),
+        import('@opentelemetry/exporter-trace-otlp-http'),
+        import('@opentelemetry/exporter-metrics-otlp-http'),
+        import('@opentelemetry/sdk-metrics'),
+        import('@opentelemetry/sdk-trace-base'),
+        import('@opentelemetry/resources'),
+        import('@opentelemetry/semantic-conventions'),
+        import('@opentelemetry/api'),
+    ]);
+    const base = stripTrailingSlash(opts.endpoint);
+    const resource = resourcesMod.resourceFromAttributes({
+        [semconv.ATTR_SERVICE_NAME]: opts.serviceName,
+        [semconv.ATTR_SERVICE_VERSION]: opts.version,
+    });
+    const spanProcessors = [
+        new sdkTraceBase.BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` })),
+    ];
+    if (opts.sentryEnabled) {
+        const { SentrySpanProcessor } = await import('@sentry/opentelemetry');
+        // SentrySpanProcessor extends SpanProcessor but its declared type from
+        // @sentry/opentelemetry can drift from the host @opentelemetry/sdk-trace-base
+        // version. Cast is intentional — confirmed working at runtime.
+        spanProcessors.push(new SentrySpanProcessor());
+    }
+    const metricReader = new sdkMetrics.PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter({ url: `${base}/v1/metrics` }),
+        exportIntervalMillis: 5000,
+    });
+    const sdk = new NodeSDK({
+        resource,
+        spanProcessors,
+        metricReader,
+        // instrumentations: intentionally NOT specified — no auto-instrumentation.
+    });
+    sdk.start();
+    return {
+        tracer: apiMod.trace.getTracer(opts.serviceName, opts.version),
+        meter: apiMod.metrics.getMeter(opts.serviceName, opts.version),
+        shutdown: () => sdk.shutdown(),
+    };
+}

package/dist/plugin.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import type { LifecycleHook } from '@powerhousedao/ph-clint';
+import { type ConsentValue } from './consent.js';
+export interface ObservabilityOptions {
+    /**
+     * Override the consent prompter — primarily a test hook. Returns the
+     * desired consent value (granted/denied). When omitted, the plugin uses
+     * `promptForConsent` against `process.stdin` and `process.stdout`.
+     */
+    promptOverride?: (input: {
+        cliName: string;
+        sentryDsn?: string;
+        otelEndpoint?: string;
+    }) => Promise<ConsentValue>;
+}
+export declare const observabilityConfigSchema: z.ZodObject<{
+    sentryDsn: z.ZodOptional<z.ZodString>;
+    otelExporterOtlpEndpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ObservabilityConfig = z.infer<typeof observabilityConfigSchema>;
+/**
+ * The observability LifecycleHook factory. Register with:
+ *
+ *   defineCli({ lifecycle: [observability()] })
+ *
+ * Reads `sentryDsn` and `otelExporterOtlpEndpoint` from the resolved config
+ * (via the merged schema fragment above). When neither is configured, returns
+ * no contributions — identity wraps everywhere, zero overhead, one info log.
+ *
+ * When a destination is configured, asks the end-user for consent on first
+ * run (interactive TTY only), persisting the decision to
+ * `~/.ph/<cliname>/observability-consent.json`.
+ */
+export declare function observability(opts?: ObservabilityOptions): LifecycleHook;

package/dist/plugin.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { readConsent, writeConsent, promptForConsent } from './consent.js';
+export const observabilityConfigSchema = z.object({
+    sentryDsn: z.string().url().optional()
+        .describe('Sentry DSN. If unset, Sentry is not initialized.'),
+    otelExporterOtlpEndpoint: z.string().url().optional()
+        .describe('OTLP HTTP endpoint for traces and metrics. If unset, OTel is not initialized.'),
+});
+/**
+ * The observability LifecycleHook factory. Register with:
+ *
+ *   defineCli({ lifecycle: [observability()] })
+ *
+ * Reads `sentryDsn` and `otelExporterOtlpEndpoint` from the resolved config
+ * (via the merged schema fragment above). When neither is configured, returns
+ * no contributions — identity wraps everywhere, zero overhead, one info log.
+ *
+ * When a destination is configured, asks the end-user for consent on first
+ * run (interactive TTY only), persisting the decision to
+ * `~/.ph/<cliname>/observability-consent.json`.
+ */
+export function observability(opts = {}) {
+    return {
+        name: 'observability',
+        configSchema: observabilityConfigSchema,
+        async onInit(ctx) {
+            const sentryDsn = ctx.config.sentryDsn;
+            const otelEndpoint = ctx.config.otelExporterOtlpEndpoint;
+            if (!sentryDsn && !otelEndpoint) {
+                ctx.log.info('[observability] No destinations configured. Identity wraps active.');
+                return {};
+            }
+            // ── Consent gate ──────────────────────────────────────────────
+            let consent = (await readConsent(ctx.userStoreFolder)).consent;
+            if (consent === 'unknown') {
+                if (ctx.isInteractive) {
+                    consent = opts.promptOverride
+                        ? await opts.promptOverride({ cliName: ctx.cliName, sentryDsn, otelEndpoint })
+                        : await promptForConsent({ cliName: ctx.cliName, sentryDsn, otelEndpoint });
+                    await writeConsent(ctx.userStoreFolder, { consent, promptedAt: new Date().toISOString() });
+                }
+                else {
+                    // Non-interactive runs default to denied (safer for CI). Persist so
+                    // subsequent interactive runs can re-prompt by editing the file.
+                    consent = 'denied';
+                    await writeConsent(ctx.userStoreFolder, { consent: 'denied', promptedAt: new Date().toISOString() });
+                    ctx.log.info(`[observability] Telemetry destinations configured but no consent recorded. ` +
+                        `Defaulting to denied for non-interactive run. Edit ${ctx.userStoreFolder}/observability-consent.json to opt in.`);
+                    return {};
+                }
+            }
+            if (consent === 'denied') {
+                ctx.log.info(`[observability] Telemetry destinations configured but consent denied. ` +
+                    `Edit ${ctx.userStoreFolder}/observability-consent.json to opt in.`);
+                return {};
+            }
+            // consent === 'granted' — initialize SDKs and contribute wraps.
+            const { initSentry } = await import('./sentry.js');
+            const { initOtel } = await import('./otel.js');
+            const { buildMetricInstruments, buildWraps, emitBootstrapSpan } = await import('./wraps.js');
+            const sentry = sentryDsn ? await initSentry({ dsn: sentryDsn, release: ctx.cliVersion }) : null;
+            const otel = otelEndpoint
+                ? await initOtel({
+                    endpoint: otelEndpoint,
+                    serviceName: ctx.cliName,
+                    version: ctx.cliVersion,
+                    sentryEnabled: sentry !== null,
+                })
+                : null;
+            const metricInstruments = buildMetricInstruments(otel, ctx.cliName, ctx.cliVersion);
+            const wraps = buildWraps(metricInstruments, sentry);
+            // Retroactive bootstrap span — only useful when OTel is producing real spans.
+            if (otel) {
+                try {
+                    emitBootstrapSpan(otel, ctx.bootTimings);
+                }
+                catch (err) {
+                    ctx.log.debug(`[observability] failed to emit bootstrap span: ${err.message}`);
+                }
+            }
+            return {
+                contribute: wraps,
+                shutdown: async () => {
+                    if (otel)
+                        await otel.shutdown();
+                    if (sentry)
+                        await sentry.flush();
+                },
+            };
+        },
+    };
+}

package/dist/sentry.d.ts

@@ -0,0 +1,22 @@
+export interface SentryInitInput {
+    dsn: string;
+    release?: string;
+}
+export interface SentryHandle {
+    captureException: (err: unknown) => void;
+    flush: (timeoutMs?: number) => Promise<boolean>;
+}
+/**
+ * Dynamic-imported Sentry initialization. Loaded only when a SENTRY_DSN-equivalent
+ * is configured — keeps the SDK out of memory when telemetry is off.
+ *
+ * Default integrations and Sentry's own OTel setup are disabled:
+ *   - defaultIntegrations: false  → no console patching, no HTTP breadcrumbs,
+ *                                   no Express integration, no global uncaught
+ *                                   handlers we didn't ask for.
+ *   - integrations: []             → explicit empty list.
+ *   - skipOpenTelemetrySetup: true → our otel.ts owns the tracer + meter
+ *                                    providers; SentrySpanProcessor bridges
+ *                                    spans to Sentry from there.
+ */
+export declare function initSentry(opts: SentryInitInput): Promise<SentryHandle>;

package/dist/sentry.js

@@ -0,0 +1,27 @@
+/**
+ * Dynamic-imported Sentry initialization. Loaded only when a SENTRY_DSN-equivalent
+ * is configured — keeps the SDK out of memory when telemetry is off.
+ *
+ * Default integrations and Sentry's own OTel setup are disabled:
+ *   - defaultIntegrations: false  → no console patching, no HTTP breadcrumbs,
+ *                                   no Express integration, no global uncaught
+ *                                   handlers we didn't ask for.
+ *   - integrations: []             → explicit empty list.
+ *   - skipOpenTelemetrySetup: true → our otel.ts owns the tracer + meter
+ *                                    providers; SentrySpanProcessor bridges
+ *                                    spans to Sentry from there.
+ */
+export async function initSentry(opts) {
+    const Sentry = await import('@sentry/node');
+    Sentry.init({
+        dsn: opts.dsn,
+        release: opts.release,
+        defaultIntegrations: false,
+        integrations: [],
+        skipOpenTelemetrySetup: true,
+    });
+    return {
+        captureException: (err) => { Sentry.captureException(err); },
+        flush: (timeoutMs = 2000) => Sentry.flush(timeoutMs),
+    };
+}

package/dist/wraps.d.ts

@@ -0,0 +1,24 @@
+import { type Counter, type Histogram } from '@opentelemetry/api';
+import type { BootTimings, WrapRegistry } from '@powerhousedao/ph-clint';
+import type { OtelHandle } from './otel.js';
+import type { SentryHandle } from './sentry.js';
+export interface MetricInstruments {
+    llmTokens: Counter;
+    toolExecutions: Counter;
+    routineIterations: Counter;
+    commandExecutions: Counter;
+    agentStreamDuration: Histogram;
+}
+export declare function buildMetricInstruments(otel: OtelHandle | null, cliName: string, version: string): MetricInstruments;
+/**
+ * Build the four wrap implementations for the framework's WrapRegistry.
+ * Returns partial — when a slot is omitted, the framework's composition
+ * falls through to identity.
+ */
+export declare function buildWraps(metrics: MetricInstruments, _sentry: SentryHandle | null): Partial<WrapRegistry>;
+/**
+ * Emit a retroactive `framework.bootstrap` span covering the pre-config boot
+ * window. OTel accepts past `startTime` and per-event timestamps so the span
+ * lands in the right position on the trace timeline.
+ */
+export declare function emitBootstrapSpan(otel: OtelHandle, bootTimings: BootTimings): void;

package/dist/wraps.js

@@ -0,0 +1,155 @@
+import { context as otelContext, metrics as otelMetrics, trace, SpanStatusCode } from '@opentelemetry/api';
+export function buildMetricInstruments(otel, cliName, version) {
+    // getMeter() returns a no-op meter when no MeterProvider has been registered,
+    // so this is safe even when OTel is off — the counters/histograms become
+    // no-ops too.
+    const meter = otel?.meter ?? otelMetrics.getMeter(cliName, version);
+    return {
+        llmTokens: meter.createCounter('clint.llm.tokens', {
+            description: 'LLM token usage by kind (prompt|completion) and model.',
+        }),
+        toolExecutions: meter.createCounter('clint.tool.executions', {
+            description: 'Tool invocations by tool name and result.',
+        }),
+        routineIterations: meter.createCounter('clint.routine.iterations', {
+            description: 'Routine loop iterations.',
+        }),
+        commandExecutions: meter.createCounter('clint.command.executions', {
+            description: 'Command dispatches by command id and result.',
+        }),
+        agentStreamDuration: meter.createHistogram('clint.agent.stream.duration', {
+            description: 'Agent stream() duration in milliseconds.',
+            unit: 'ms',
+        }),
+    };
+}
+/**
+ * Build the four wrap implementations for the framework's WrapRegistry.
+ * Returns partial — when a slot is omitted, the framework's composition
+ * falls through to identity.
+ */
+export function buildWraps(metrics, _sentry) {
+    const tracer = trace.getTracer('ph-clint');
+    const command = async (id, inner) => {
+        const span = tracer.startSpan('command.execute', { attributes: { 'command.id': id } });
+        const start = Date.now();
+        try {
+            const result = await inner();
+            metrics.commandExecutions.add(1, { command: id, result: 'success' });
+            span.setAttribute('command.duration_ms', Date.now() - start);
+            return result;
+        }
+        catch (err) {
+            metrics.commandExecutions.add(1, { command: id, result: 'error' });
+            span.recordException(err);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+            span.setAttribute('command.duration_ms', Date.now() - start);
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    };
+    const agentStream = (inner, attrs) => {
+        return async function* (prompt, opts) {
+            const streamSpan = tracer.startSpan('agent.stream', {
+                attributes: { 'agent.id': attrs.agentId },
+            });
+            const llmSpan = tracer.startSpan('llm.call', undefined, trace.setSpan(otelContext.active(), streamSpan));
+            const start = Date.now();
+            let result = 'success';
+            try {
+                for await (const chunk of inner(prompt, opts)) {
+                    const u = chunk;
+                    if (u && u.usage) {
+                        const m = u.model ?? 'unknown';
+                        if (typeof u.usage.promptTokens === 'number') {
+                            llmSpan.setAttribute('llm.tokens.prompt', u.usage.promptTokens);
+                            metrics.llmTokens.add(u.usage.promptTokens, { kind: 'prompt', model: m });
+                        }
+                        if (typeof u.usage.completionTokens === 'number') {
+                            llmSpan.setAttribute('llm.tokens.completion', u.usage.completionTokens);
+                            metrics.llmTokens.add(u.usage.completionTokens, { kind: 'completion', model: m });
+                        }
+                        if (typeof u.usage.totalTokens === 'number') {
+                            llmSpan.setAttribute('llm.tokens.total', u.usage.totalTokens);
+                        }
+                        llmSpan.setAttribute('llm.model', m);
+                    }
+                    yield chunk;
+                }
+            }
+            catch (err) {
+                result = 'error';
+                streamSpan.recordException(err);
+                streamSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                llmSpan.recordException(err);
+                llmSpan.setStatus({ code: SpanStatusCode.ERROR });
+                throw err;
+            }
+            finally {
+                llmSpan.end();
+                const duration = Date.now() - start;
+                metrics.agentStreamDuration.record(duration, { result, 'agent.id': attrs.agentId });
+                streamSpan.end();
+            }
+        };
+    };
+    const tool = (name, t) => {
+        return {
+            ...t,
+            execute: async (args) => {
+                const span = tracer.startSpan('tool.execute', { attributes: { 'tool.name': name } });
+                const start = Date.now();
+                try {
+                    const result = await t.execute(args);
+                    metrics.toolExecutions.add(1, { tool: name, result: 'success' });
+                    span.setAttribute('tool.duration_ms', Date.now() - start);
+                    return result;
+                }
+                catch (err) {
+                    metrics.toolExecutions.add(1, { tool: name, result: 'error' });
+                    span.recordException(err);
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                    span.setAttribute('tool.duration_ms', Date.now() - start);
+                    throw err;
+                }
+                finally {
+                    span.end();
+                }
+            },
+        };
+    };
+    const routineIteration = async (attrs, inner) => {
+        const span = tracer.startSpan('routine.iteration', { attributes: { 'routine.index': attrs.index } });
+        const start = Date.now();
+        try {
+            const result = await inner();
+            metrics.routineIterations.add(1);
+            span.setAttribute('routine.duration_ms', Date.now() - start);
+            return result;
+        }
+        catch (err) {
+            span.recordException(err);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    };
+    return { command, agentStream, tool, routineIteration };
+}
+/**
+ * Emit a retroactive `framework.bootstrap` span covering the pre-config boot
+ * window. OTel accepts past `startTime` and per-event timestamps so the span
+ * lands in the right position on the trace timeline.
+ */
+export function emitBootstrapSpan(otel, bootTimings) {
+    const span = otel.tracer.startSpan('framework.bootstrap', {
+        startTime: new Date(bootTimings.bootStartedAt),
+    });
+    span.addEvent('config.resolved', {}, new Date(bootTimings.configResolvedAt));
+    span.addEvent('lifecycle.init.started', {}, new Date(bootTimings.lifecycleInitStartedAt));
+    span.end();
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@powerhousedao/ph-clint-observability",
+  "version": "0.1.0-dev.69",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "ph-telemetry-dev": "./dist/dev-server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test:types": "tsc --noEmit",
+    "test": "pnpm test:types && NODE_OPTIONS='--experimental-vm-modules' jest --coverage --maxWorkers=4"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.205.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.205.0",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/sdk-metrics": "^2.0.1",
+    "@opentelemetry/sdk-node": "^0.205.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/semantic-conventions": "^1.36.0",
+    "@sentry/node": "^8.50.0",
+    "@sentry/opentelemetry": "^8.50.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@powerhousedao/ph-clint": "^0.1.0-dev.69"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.3.0",
+    "@types/node": "^25.5.2",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.9",
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  }
+}