@ory/argus 0.13.9 → 1.0.0

package/dist/otel/otlp.js

@@ -1,385 +0,0 @@
-"use strict";
-/**
- * OTLP exporter — SDK-backed.
- *
- * Bridges our internal `TraceSpan` records into the official OpenTelemetry
- * SDK exporters from `@opentelemetry/exporter-trace-otlp-http` and
- * `@opentelemetry/exporter-trace-otlp-proto`. Each completed `TraceSpan`
- * is converted to a `ReadableSpan` shape and handed to the SDK exporter,
- * which serializes (JSON or protobuf) and POSTs to an OTLP HTTP endpoint.
- *
- * Standard OTel env vars consumed by `otlpExporterFromEnv()`. Each one has
- * an `ORY_OTLP_*`-prefixed alias that is consulted as a fallback when the
- * standard name is unset. Some harnesses (notably Claude Code) sanitize the
- * env passed to hook subprocesses and drop every `OTEL_*` var, so the dev
- * launcher mirrors each setting under the Ory prefix to survive the strip.
- *
- *   Standard name                          Ory-prefixed fallback
- *   ─────────────────────────────────────  ─────────────────────────────────
- *   OTEL_EXPORTER_OTLP_ENDPOINT            ORY_OTLP_ENDPOINT
- *   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT     ORY_OTLP_TRACES_ENDPOINT
- *   OTEL_EXPORTER_OTLP_HEADERS             ORY_OTLP_HEADERS
- *   OTEL_EXPORTER_OTLP_TRACES_HEADERS      ORY_OTLP_TRACES_HEADERS
- *   OTEL_EXPORTER_OTLP_PROTOCOL            ORY_OTLP_PROTOCOL
- *   OTEL_EXPORTER_OTLP_TRACES_PROTOCOL     ORY_OTLP_TRACES_PROTOCOL
- *   OTEL_SERVICE_NAME                      ORY_OTLP_SERVICE_NAME
- *   OTEL_RESOURCE_ATTRIBUTES               ORY_OTLP_RESOURCE_ATTRIBUTES
- *
- * Failures are swallowed (callers receive a resolved Promise) so trace
- * export can never break the agent session. Transport errors surface
- * through the `onError` callback.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OtlpExporter = void 0;
-exports.otlpExporterFromEnv = otlpExporterFromEnv;
-exports.readEnvWithAlias = readEnvWithAlias;
-exports.parseKeyValueList = parseKeyValueList;
-exports.toReadableSpan = toReadableSpan;
-const api_1 = require("@opentelemetry/api");
-const core_1 = require("@opentelemetry/core");
-const resources_1 = require("@opentelemetry/resources");
-const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
-const exporter_trace_otlp_proto_1 = require("@opentelemetry/exporter-trace-otlp-proto");
-const TRACES_PATH = "/v1/traces";
-const SCOPE = {
-    name: "ory-agent-plugins",
-};
-/**
- * OTLP exporter that delegates wire-format serialization and HTTP transport
- * to the official `@opentelemetry/exporter-trace-otlp-*` SDK exporters.
- */
-class OtlpExporter {
-    endpoint;
-    protocol;
-    headers;
-    resource;
-    delegate;
-    onError;
-    inFlight = new Set();
-    constructor(opts) {
-        this.endpoint = opts.endpoint;
-        this.protocol = opts.protocol ?? "http/protobuf";
-        this.headers = { ...(opts.headers ?? {}) };
-        this.resource = (0, resources_1.resourceFromAttributes)(stripUndefined(opts.resource ?? {}));
-        this.onError = opts.onError ?? (() => undefined);
-        this.delegate =
-            opts.sdkExporter ??
-                buildSdkExporter(this.endpoint, this.protocol, this.headers, opts.timeoutMs);
-    }
-    export(spans) {
-        if (spans.length === 0)
-            return Promise.resolve();
-        const readables = spans.map((s) => toReadableSpan(s, this.resource));
-        const promise = new Promise((resolve) => {
-            try {
-                this.delegate.export(readables, (result) => {
-                    if (result.code !== core_1.ExportResultCode.SUCCESS) {
-                        this.onError(result.error ?? new Error("OTLP export failed"));
-                    }
-                    resolve();
-                });
-            }
-            catch (err) {
-                // Defensive — SDK exporter contract says export() must not throw,
-                // but we honor our own contract regardless.
-                this.onError(err);
-                resolve();
-            }
-        });
-        this.inFlight.add(promise);
-        promise.finally(() => this.inFlight.delete(promise));
-        return promise;
-    }
-    async shutdown() {
-        // Drain in-flight exports first. Subprocess hooks (claude-code, codex,
-        // gemini-cli) call process.exit() the instant they hand back stdout —
-        // without this drain the underlying HTTP request is killed mid-flight
-        // and spans never reach the collector even though the NDJSON file
-        // already contains them.
-        if (this.inFlight.size > 0) {
-            await Promise.allSettled([...this.inFlight]);
-        }
-        try {
-            await this.delegate.shutdown();
-        }
-        catch (err) {
-            this.onError(err);
-        }
-    }
-}
-exports.OtlpExporter = OtlpExporter;
-function buildSdkExporter(endpoint, protocol, headers, timeoutMs) {
-    const config = {
-        url: endpoint,
-        headers,
-        timeoutMillis: timeoutMs ?? 5_000,
-    };
-    return protocol === "http/json"
-        ? new exporter_trace_otlp_http_1.OTLPTraceExporter(config)
-        : new exporter_trace_otlp_proto_1.OTLPTraceExporter(config);
-}
-// ─── Factory ───────────────────────────────────────────────────────
-/**
- * Build an OtlpExporter from process env. Returns undefined when no
- * endpoint is configured or the requested protocol is unsupported.
- */
-function otlpExporterFromEnv(opts) {
-    const env = opts.env ?? process.env;
-    const endpoint = resolveEndpoint(env);
-    if (!endpoint)
-        return undefined;
-    const protocol = resolveProtocol(env, opts.onError);
-    if (!protocol)
-        return undefined;
-    const headers = mergeHeaders(parseKeyValueList(readEnvWithAlias(env, "OTEL_EXPORTER_OTLP_HEADERS")), parseKeyValueList(readEnvWithAlias(env, "OTEL_EXPORTER_OTLP_TRACES_HEADERS")));
-    const resource = {
-        "service.name": readEnvWithAlias(env, "OTEL_SERVICE_NAME") ??
-            `ory-agent-plugin-${opts.harness}`,
-        "service.namespace": "ory.agent_plugins",
-        "ory.harness": opts.harness,
-        "process.pid": process.pid,
-        "process.runtime.name": "nodejs",
-        "process.runtime.version": process.version,
-    };
-    if (opts.hostname)
-        resource["host.name"] = opts.hostname;
-    if (opts.user)
-        resource["host.user"] = opts.user;
-    if (opts.pluginVersion)
-        resource["service.version"] = opts.pluginVersion;
-    if (opts.cwd)
-        resource["process.cwd"] = opts.cwd;
-    if (opts.gitBranch)
-        resource["ory.git.branch"] = opts.gitBranch;
-    if (opts.gitCommit)
-        resource["ory.git.commit"] = opts.gitCommit;
-    for (const [k, v] of Object.entries(parseKeyValueList(readEnvWithAlias(env, "OTEL_RESOURCE_ATTRIBUTES")))) {
-        resource[k] = v;
-    }
-    return new OtlpExporter({
-        endpoint,
-        protocol,
-        headers,
-        resource,
-        onError: opts.onError,
-    });
-}
-function resolveEndpoint(env) {
-    // ORY_OTLP_*-prefixed aliases survive harnesses (e.g. Claude Code) that
-    // sanitize the env passed to hook subprocesses and drop OTEL_*-prefixed
-    // vars. The standard OTel name still wins when present.
-    const tracesUrl = readEnvWithAlias(env, "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT");
-    if (tracesUrl)
-        return tracesUrl;
-    const base = readEnvWithAlias(env, "OTEL_EXPORTER_OTLP_ENDPOINT");
-    if (!base)
-        return undefined;
-    return base.replace(/\/+$/, "") + TRACES_PATH;
-}
-function resolveProtocol(env, onError) {
-    const raw = (readEnvWithAlias(env, "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL") ??
-        readEnvWithAlias(env, "OTEL_EXPORTER_OTLP_PROTOCOL") ??
-        "http/protobuf")
-        .trim()
-        .toLowerCase();
-    if (raw === "http/protobuf" || raw === "http/json")
-        return raw;
-    onError?.(new Error(`OTEL_EXPORTER_OTLP_PROTOCOL=${raw} not supported (only http/protobuf and http/json). Skipping OTel export.`));
-    return undefined;
-}
-/**
- * Standard OTel env var name → Ory-prefixed fallback. Standard wins when set;
- * the alias is consulted only when the standard name is empty/missing. The
- * historical `ORY_OTLP_ENDPOINT` alias for `OTEL_EXPORTER_OTLP_ENDPOINT` is
- * preserved verbatim for compatibility with existing dev-launcher envs.
- */
-const ORY_ENV_ALIAS = {
-    OTEL_EXPORTER_OTLP_ENDPOINT: "ORY_OTLP_ENDPOINT",
-    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "ORY_OTLP_TRACES_ENDPOINT",
-    OTEL_EXPORTER_OTLP_HEADERS: "ORY_OTLP_HEADERS",
-    OTEL_EXPORTER_OTLP_TRACES_HEADERS: "ORY_OTLP_TRACES_HEADERS",
-    OTEL_EXPORTER_OTLP_PROTOCOL: "ORY_OTLP_PROTOCOL",
-    OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: "ORY_OTLP_TRACES_PROTOCOL",
-    OTEL_SERVICE_NAME: "ORY_OTLP_SERVICE_NAME",
-    OTEL_RESOURCE_ATTRIBUTES: "ORY_OTLP_RESOURCE_ATTRIBUTES",
-};
-/**
- * Read an OTel env var, falling back to its `ORY_OTLP_*`-prefixed alias when
- * the standard name is unset. Trims whitespace and treats empty strings as
- * absent so a propagated-but-blank var doesn't shadow the alias.
- */
-function readEnvWithAlias(env, standardName) {
-    const primary = env[standardName]?.trim();
-    if (primary)
-        return primary;
-    const aliasName = ORY_ENV_ALIAS[standardName];
-    if (!aliasName)
-        return undefined;
-    const alias = env[aliasName]?.trim();
-    return alias || undefined;
-}
-// ─── Env parsing helpers ───────────────────────────────────────────
-/**
- * Parse the OTel `k=v,k2=v2` env-var format. Values may be URL-encoded.
- */
-function parseKeyValueList(raw) {
-    const out = {};
-    if (!raw)
-        return out;
-    for (const pair of raw.split(",")) {
-        const trimmed = pair.trim();
-        if (!trimmed)
-            continue;
-        const eq = trimmed.indexOf("=");
-        if (eq <= 0)
-            continue;
-        const key = trimmed.slice(0, eq).trim();
-        const value = trimmed.slice(eq + 1).trim();
-        if (!key)
-            continue;
-        out[key] = safeDecodeURIComponent(value);
-    }
-    return out;
-}
-function safeDecodeURIComponent(value) {
-    try {
-        return decodeURIComponent(value);
-    }
-    catch {
-        return value;
-    }
-}
-function mergeHeaders(...sources) {
-    const out = {};
-    for (const src of sources) {
-        for (const [k, v] of Object.entries(src)) {
-            out[k.toLowerCase()] = v;
-        }
-    }
-    return out;
-}
-// ─── TraceSpan → ReadableSpan conversion ───────────────────────────
-/**
- * Convert our internal `TraceSpan` record to an OTel SDK `ReadableSpan`.
- * Exported for tests; the OTLP exporters consume this shape directly.
- */
-function toReadableSpan(span, resource) {
-    // OTLP wire format expects 32-hex traceId / 16-hex spanId. Our internal
-    // IDs are shorter (hashed session prefix + random suffix), so pad with
-    // leading zeros to canonical width.
-    const traceId = padHex(span.traceId, 32);
-    const spanId = padHex(span.spanId, 16);
-    const ctx = {
-        traceId,
-        spanId,
-        traceFlags: 1, // sampled
-        isRemote: false,
-    };
-    const parentSpanContext = span.parentSpanId
-        ? {
-            traceId,
-            spanId: padHex(span.parentSpanId, 16),
-            traceFlags: 1,
-            isRemote: false,
-        }
-        : undefined;
-    const startTime = isoToHrTime(span.startedAt);
-    const endTime = isoToHrTime(span.endedAt);
-    const attributes = {
-        "ory.event": span.event,
-        "ory.span.status": span.status,
-        "ory.duration_ms": span.durationMs,
-    };
-    if (span.sessionId)
-        attributes["ory.session_id"] = span.sessionId;
-    for (const [k, v] of Object.entries(flattenAttributes(span.attributes ?? {}))) {
-        attributes[k] = v;
-    }
-    return {
-        name: span.event,
-        kind: api_1.SpanKind.INTERNAL,
-        spanContext: () => ctx,
-        parentSpanContext,
-        startTime,
-        endTime,
-        status: toOtelStatus(span.status),
-        attributes,
-        links: [],
-        events: [],
-        duration: hrTimeSubtract(endTime, startTime),
-        ended: true,
-        resource,
-        instrumentationScope: SCOPE,
-        droppedAttributesCount: 0,
-        droppedEventsCount: 0,
-        droppedLinksCount: 0,
-    };
-}
-function toOtelStatus(status) {
-    switch (status) {
-        case "ok":
-            return { code: api_1.SpanStatusCode.OK };
-        case "error":
-            return { code: api_1.SpanStatusCode.ERROR, message: "error" };
-        case "denied":
-            return { code: api_1.SpanStatusCode.ERROR, message: "denied" };
-        case "skipped":
-        default:
-            return { code: api_1.SpanStatusCode.UNSET };
-    }
-}
-function isoToHrTime(iso) {
-    const ms = Date.parse(iso);
-    if (!Number.isFinite(ms))
-        return [0, 0];
-    const seconds = Math.trunc(ms / 1000);
-    const nanos = (ms - seconds * 1000) * 1_000_000;
-    return [seconds, nanos];
-}
-function hrTimeSubtract(a, b) {
-    let sec = a[0] - b[0];
-    let nanos = a[1] - b[1];
-    if (nanos < 0) {
-        sec -= 1;
-        nanos += 1_000_000_000;
-    }
-    if (sec < 0) {
-        return [0, 0];
-    }
-    return [sec, nanos];
-}
-function padHex(hex, length) {
-    const lower = hex.toLowerCase().replace(/[^0-9a-f]/g, "");
-    if (lower.length >= length)
-        return lower.slice(-length);
-    return lower.padStart(length, "0");
-}
-function flattenAttributes(attrs) {
-    const out = {};
-    for (const [key, value] of Object.entries(attrs)) {
-        if (value === null || value === undefined)
-            continue;
-        if (typeof value === "string" ||
-            typeof value === "number" ||
-            typeof value === "boolean") {
-            out[key] = value;
-            continue;
-        }
-        try {
-            out[key] = JSON.stringify(value);
-        }
-        catch {
-            /* skip un-serializable values */
-        }
-    }
-    return out;
-}
-function stripUndefined(source) {
-    const out = {};
-    for (const [k, v] of Object.entries(source)) {
-        if (v === undefined)
-            continue;
-        out[k] = v;
-    }
-    return out;
-}

package/dist/tracer.d.ts

@@ -1,190 +0,0 @@
-/**
- * Distributed tracing for Ory agent plugin hooks.
- *
- * Replaces simple audit logging with structured, correlated trace spans.
- * Every plugin resolves to the same unified TraceEvent classification —
- * there is no plugin-specific output.
- *
- * Key concepts:
- *   - **TraceEvent**: A canonical event type (e.g. "tool.invoke", "permission.check").
- *   - **TraceSpan**: A completed unit of work with timing and status.
- *   - **ActiveSpan**: An in-flight span that must be `.end()`-ed.
- *   - **Tracer**: EventEmitter that collects spans, writes NDJSON, and
- *     supports live watching via the "span" event.
- *
- * Trace correlation: call `tracer.setContext()` with a traceId derived
- * from the session ID so all spans within the same agent session share
- * a single trace, even across separate hook process invocations.
- */
-import { EventEmitter } from "node:events";
-import type { SpanExporter } from "./otel/exporter.js";
-export type TraceEvent = "session.start" | "session.end" | "session.verify" | "user.auth" | "user.prompt" | "user.interaction" | "agent.auth" | "oauth2.introspect" | "oauth2.login" | "oauth2.refresh" | "permission.check" | "permission.batch_check" | "permission.observe_deny" | "tool.invoke" | "tool.complete" | "tool.block" | "tool.fail" | "turn.stop" | "subagent.start" | "subagent.stop" | "notification" | "compaction" | "relationship.create" | "relationship.delete" | "relationship.patch" | "hook.receive" | "hook.passthrough" | "config.resolve";
-export type SpanStatus = "ok" | "error" | "denied" | "skipped";
-export interface TraceSpan {
-    traceId: string;
-    spanId: string;
-    parentSpanId?: string;
-    event: TraceEvent;
-    status: SpanStatus;
-    startedAt: string;
-    endedAt: string;
-    durationMs: number;
-    harness: string;
-    hostname: string;
-    user: string;
-    pid: number;
-    cwd: string;
-    pluginVersion: string;
-    nodeVersion: string;
-    /** Git branch of `cwd` if it is a git working tree. */
-    gitBranch?: string;
-    /** Short git SHA of HEAD in `cwd` if it is a git working tree. */
-    gitCommit?: string;
-    sessionId?: string;
-    attributes?: Record<string, unknown>;
-}
-export interface SpanOptions {
-    traceId?: string;
-    parentSpanId?: string;
-    sessionId?: string;
-    attributes?: Record<string, unknown>;
-}
-export declare class ActiveSpan {
-    readonly traceId: string;
-    readonly spanId: string;
-    readonly parentSpanId: string | undefined;
-    readonly event: TraceEvent;
-    readonly startedAt: string;
-    readonly sessionId: string | undefined;
-    private readonly startMs;
-    private _ended;
-    private readonly tracer;
-    private readonly baseAttributes;
-    /** @internal — use `tracer.startSpan()` instead. */
-    constructor(tracer: Tracer, event: TraceEvent, opts: SpanOptions & {
-        resolvedTraceId: string;
-    });
-    get ended(): boolean;
-    /**
-     * Complete the span. Returns the recorded TraceSpan.
-     */
-    end(status: SpanStatus, attributes?: Record<string, unknown>): TraceSpan;
-}
-export interface TracerOptions {
-    harness: string;
-    traceFile?: string;
-    /**
-     * Optional span exporter (e.g. OTLP/HTTP). Each completed span is
-     * dispatched fire-and-forget; the tracer never awaits the export and
-     * exporter failures must not throw.
-     */
-    exporter?: SpanExporter;
-}
-export interface TracerContext {
-    traceId?: string;
-    spanId?: string;
-    sessionId?: string;
-}
-/**
- * Process-level metadata captured once per Tracer and emitted on every span.
- * These values are constant for the lifetime of the process.
- */
-export interface ProcessMetadata {
-    hostname: string;
-    user: string;
-    pid: number;
-    cwd: string;
-    pluginVersion: string;
-    nodeVersion: string;
-    gitBranch?: string;
-    gitCommit?: string;
-}
-/**
- * Returns a record of attributes to merge into every span's attribute
- * bag at span-end. Used by `OryAgentClient` to inject the current
- * `userSubject` / `agentSubject` onto every span without each handler
- * having to remember to attach them. Must not throw and should be cheap;
- * it is invoked on every span.
- */
-export type SpanAttributeEnricher = () => Record<string, unknown> | undefined;
-export declare class Tracer extends EventEmitter {
-    readonly harness: string;
-    readonly processMetadata: ProcessMetadata;
-    private readonly traceFile;
-    private readonly _spans;
-    private _context;
-    private _exporter;
-    private _enricher;
-    constructor(opts: TracerOptions);
-    /** Backwards-compatible accessors for the most common metadata fields. */
-    get hostname(): string;
-    get user(): string;
-    /**
-     * Set the ambient context. Subsequent spans inherit traceId,
-     * parentSpanId, and sessionId from the context unless overridden.
-     */
-    setContext(ctx: TracerContext): void;
-    clearContext(): void;
-    get context(): Readonly<TracerContext>;
-    /**
-     * Start a span that must be completed with `.end(status)`.
-     * Use this for operations with meaningful duration (API calls, etc.).
-     */
-    startSpan(event: TraceEvent, opts?: SpanOptions): ActiveSpan;
-    /**
-     * Record a completed span in one call. Use this for instantaneous
-     * events (tool invoked, tool blocked, etc.).
-     */
-    record(event: TraceEvent, status: SpanStatus, opts?: SpanOptions): TraceSpan;
-    /** All recorded spans in this process. */
-    spans(): ReadonlyArray<TraceSpan>;
-    /**
-     * Attach (or replace) the span exporter. Useful when constructing
-     * the tracer before env-driven configuration has resolved.
-     */
-    setExporter(exporter: SpanExporter | null): void;
-    get exporter(): SpanExporter | null;
-    /**
-     * Install (or replace) an attribute enricher. The enricher is invoked
-     * on every span at end-time and its return value is merged into the
-     * span's attributes (with caller-supplied attributes taking precedence).
-     * Pass `null` to clear.
-     */
-    setAttributeEnricher(enricher: SpanAttributeEnricher | null): void;
-    /** @internal — invoked by `ActiveSpan.end()`. Never throws. */
-    _callEnricher(): Record<string, unknown> | undefined;
-    /**
-     * Flush any pending exports. Call before the host process exits so
-     * the OTLP HTTP request has a chance to complete.
-     */
-    shutdown(): Promise<void>;
-    /** @internal — called by ActiveSpan.end() */
-    _record(span: TraceSpan): void;
-    private dispatchExport;
-    private writeToFile;
-}
-/**
- * Derive a stable trace ID from a session ID so all hook invocations
- * within the same agent session correlate automatically.
- */
-export declare function deriveTraceId(sessionId: string): string;
-/**
- * Parse a W3C traceparent header. Format:
- *   `<version>-<traceId 32hex>-<parentSpanId 16hex>-<flags 2hex>`
- * Returns undefined for malformed or "all-zero" traceparents.
- */
-export declare function parseTraceparent(raw: string | undefined): {
-    traceId: string;
-    parentSpanId: string;
-} | undefined;
-/**
- * Format a single TraceSpan for terminal display.
- */
-export declare function formatSpan(span: TraceSpan): string;
-/**
- * Watch a trace file for new spans and invoke `callback` for each one.
- * Returns a cleanup function that stops watching.
- *
- * If the file does not yet exist, polling waits for it to appear.
- */
-export declare function watchTraceFile(filePath: string, callback: (span: TraceSpan) => void): () => void;