@ory/argus 0.14.0 → 1.0.0

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;

package/dist/tracer.js

@@ -1,481 +0,0 @@
-"use strict";
-/**
- * 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.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Tracer = exports.ActiveSpan = void 0;
-exports.deriveTraceId = deriveTraceId;
-exports.parseTraceparent = parseTraceparent;
-exports.formatSpan = formatSpan;
-exports.watchTraceFile = watchTraceFile;
-const node_events_1 = require("node:events");
-const node_child_process_1 = require("node:child_process");
-const node_crypto_1 = require("node:crypto");
-const fs = __importStar(require("node:fs"));
-const os = __importStar(require("node:os"));
-const path = __importStar(require("node:path"));
-// ─── ActiveSpan ────────────────────────────────────────────────────
-class ActiveSpan {
-    traceId;
-    spanId;
-    parentSpanId;
-    event;
-    startedAt;
-    sessionId;
-    startMs;
-    _ended = false;
-    tracer;
-    baseAttributes;
-    /** @internal — use `tracer.startSpan()` instead. */
-    constructor(tracer, event, opts) {
-        this.tracer = tracer;
-        this.event = event;
-        this.traceId = opts.resolvedTraceId;
-        this.spanId = generateSpanId();
-        this.parentSpanId = opts.parentSpanId;
-        this.sessionId = opts.sessionId;
-        this.startedAt = new Date().toISOString();
-        this.startMs = performance.now();
-        this.baseAttributes = opts.attributes;
-    }
-    get ended() {
-        return this._ended;
-    }
-    /**
-     * Complete the span. Returns the recorded TraceSpan.
-     */
-    end(status, attributes) {
-        if (this._ended) {
-            throw new Error(`Span ${this.spanId} (${this.event}) already ended`);
-        }
-        this._ended = true;
-        const durationMs = Math.round(performance.now() - this.startMs);
-        // Pull enricher attributes (e.g. userSubject / agentSubject from the
-        // client's principals) at span-end so every span gets them, including
-        // direct `tracer.record(...)` calls from plugin handlers.
-        const enriched = this.tracer._callEnricher();
-        const merged = enriched || this.baseAttributes || attributes
-            ? { ...enriched, ...this.baseAttributes, ...attributes }
-            : undefined;
-        const meta = this.tracer.processMetadata;
-        const span = {
-            traceId: this.traceId,
-            spanId: this.spanId,
-            ...(this.parentSpanId ? { parentSpanId: this.parentSpanId } : {}),
-            event: this.event,
-            status,
-            startedAt: this.startedAt,
-            endedAt: new Date().toISOString(),
-            durationMs,
-            harness: this.tracer.harness,
-            hostname: meta.hostname,
-            user: meta.user,
-            pid: meta.pid,
-            cwd: meta.cwd,
-            pluginVersion: meta.pluginVersion,
-            nodeVersion: meta.nodeVersion,
-            ...(meta.gitBranch ? { gitBranch: meta.gitBranch } : {}),
-            ...(meta.gitCommit ? { gitCommit: meta.gitCommit } : {}),
-            ...(this.sessionId ? { sessionId: this.sessionId } : {}),
-            ...(merged && Object.keys(merged).length > 0
-                ? { attributes: merged }
-                : {}),
-        };
-        this.tracer._record(span);
-        return span;
-    }
-}
-exports.ActiveSpan = ActiveSpan;
-class Tracer extends node_events_1.EventEmitter {
-    harness;
-    processMetadata;
-    traceFile;
-    _spans = [];
-    _context = {};
-    _exporter;
-    _enricher = null;
-    constructor(opts) {
-        super();
-        this.harness = opts.harness;
-        this.processMetadata = resolveProcessMetadata();
-        this.traceFile = opts.traceFile ?? null;
-        this._exporter = opts.exporter ?? null;
-        // Seed default context from W3C traceparent if present so spans
-        // stitch into upstream OTel traces (e.g. CI, sidecar collectors).
-        const upstream = parseTraceparent(process.env.TRACEPARENT);
-        if (upstream) {
-            this._context = {
-                traceId: upstream.traceId,
-                spanId: upstream.parentSpanId,
-            };
-        }
-    }
-    /** Backwards-compatible accessors for the most common metadata fields. */
-    get hostname() {
-        return this.processMetadata.hostname;
-    }
-    get user() {
-        return this.processMetadata.user;
-    }
-    // ─── Context ───────────────────────────────────────────────────
-    /**
-     * Set the ambient context. Subsequent spans inherit traceId,
-     * parentSpanId, and sessionId from the context unless overridden.
-     */
-    setContext(ctx) {
-        this._context = { ...ctx };
-    }
-    clearContext() {
-        this._context = {};
-    }
-    get context() {
-        return this._context;
-    }
-    // ─── Span Creation ─────────────────────────────────────────────
-    /**
-     * Start a span that must be completed with `.end(status)`.
-     * Use this for operations with meaningful duration (API calls, etc.).
-     */
-    startSpan(event, opts) {
-        const resolvedTraceId = opts?.traceId ?? this._context.traceId ?? generateTraceId();
-        return new ActiveSpan(this, event, {
-            resolvedTraceId,
-            parentSpanId: opts?.parentSpanId ?? this._context.spanId,
-            sessionId: opts?.sessionId ?? this._context.sessionId,
-            attributes: opts?.attributes,
-        });
-    }
-    /**
-     * Record a completed span in one call. Use this for instantaneous
-     * events (tool invoked, tool blocked, etc.).
-     */
-    record(event, status, opts) {
-        const span = this.startSpan(event, opts);
-        return span.end(status);
-    }
-    // ─── Query ─────────────────────────────────────────────────────
-    /** All recorded spans in this process. */
-    spans() {
-        return this._spans;
-    }
-    // ─── Internal ──────────────────────────────────────────────────
-    /**
-     * Attach (or replace) the span exporter. Useful when constructing
-     * the tracer before env-driven configuration has resolved.
-     */
-    setExporter(exporter) {
-        this._exporter = exporter;
-    }
-    get exporter() {
-        return this._exporter;
-    }
-    /**
-     * 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) {
-        this._enricher = enricher;
-    }
-    /** @internal — invoked by `ActiveSpan.end()`. Never throws. */
-    _callEnricher() {
-        if (!this._enricher)
-            return undefined;
-        try {
-            const out = this._enricher();
-            if (!out || Object.keys(out).length === 0)
-                return undefined;
-            return out;
-        }
-        catch {
-            // Enricher contract: never throw. Swallow defensively.
-            return undefined;
-        }
-    }
-    /**
-     * Flush any pending exports. Call before the host process exits so
-     * the OTLP HTTP request has a chance to complete.
-     */
-    async shutdown() {
-        if (!this._exporter)
-            return;
-        try {
-            await this._exporter.shutdown();
-        }
-        catch {
-            /* exporter contract: never throw */
-        }
-    }
-    /** @internal — called by ActiveSpan.end() */
-    _record(span) {
-        this._spans.push(span);
-        this.emit("span", span);
-        this.writeToFile(span);
-        this.dispatchExport(span);
-    }
-    dispatchExport(span) {
-        if (!this._exporter)
-            return;
-        // Fire-and-forget: never await, never throw. The exporter contract
-        // guarantees its returned Promise resolves even on transport error.
-        void this._exporter.export([span]).catch(() => undefined);
-    }
-    writeToFile(span) {
-        if (!this.traceFile)
-            return;
-        const dir = path.dirname(this.traceFile);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        fs.appendFileSync(this.traceFile, JSON.stringify(span) + "\n");
-    }
-}
-exports.Tracer = Tracer;
-// ─── Trace ID Helpers ──────────────────────────────────────────────
-/**
- * Derive a stable trace ID from a session ID so all hook invocations
- * within the same agent session correlate automatically.
- */
-function deriveTraceId(sessionId) {
-    return (0, node_crypto_1.createHash)("sha256").update(sessionId).digest("hex").slice(0, 16);
-}
-function generateSpanId() {
-    return (0, node_crypto_1.randomBytes)(8).toString("hex");
-}
-function generateTraceId() {
-    return (0, node_crypto_1.randomBytes)(8).toString("hex");
-}
-function resolveHostname() {
-    try {
-        return os.hostname();
-    }
-    catch {
-        return "unknown";
-    }
-}
-function resolveUser() {
-    try {
-        return os.userInfo().username;
-    }
-    catch {
-        return process.env.USER ?? process.env.USERNAME ?? "unknown";
-    }
-}
-function resolveCwd() {
-    try {
-        return process.cwd();
-    }
-    catch {
-        return "unknown";
-    }
-}
-function resolvePluginVersion() {
-    // Walks up from this file's directory to the nearest package.json. The
-    // tracer ships with @ory/argus, so the closest package.json
-    // is always the core package.
-    try {
-        let dir = __dirname;
-        for (let i = 0; i < 5; i++) {
-            const candidate = path.join(dir, "package.json");
-            if (fs.existsSync(candidate)) {
-                const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
-                if (pkg.version)
-                    return pkg.version;
-            }
-            const parent = path.dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-    }
-    catch {
-        /* fall through */
-    }
-    return "unknown";
-}
-function resolveGitInfo(cwd) {
-    // Best-effort: short-timeout git calls. Skipped silently when git is
-    // unavailable or `cwd` is not a working tree.
-    const exec = (args) => {
-        try {
-            return (0, node_child_process_1.execFileSync)("git", args, {
-                cwd,
-                timeout: 250,
-                stdio: ["ignore", "pipe", "ignore"],
-                encoding: "utf8",
-            }).trim() || undefined;
-        }
-        catch {
-            return undefined;
-        }
-    };
-    const gitBranch = exec(["rev-parse", "--abbrev-ref", "HEAD"]);
-    const gitCommit = exec(["rev-parse", "--short", "HEAD"]);
-    return {
-        ...(gitBranch ? { gitBranch } : {}),
-        ...(gitCommit ? { gitCommit } : {}),
-    };
-}
-function resolveProcessMetadata() {
-    const cwd = resolveCwd();
-    return {
-        hostname: resolveHostname(),
-        user: resolveUser(),
-        pid: process.pid,
-        cwd,
-        pluginVersion: resolvePluginVersion(),
-        nodeVersion: process.version,
-        ...resolveGitInfo(cwd),
-    };
-}
-/**
- * Parse a W3C traceparent header. Format:
- *   `<version>-<traceId 32hex>-<parentSpanId 16hex>-<flags 2hex>`
- * Returns undefined for malformed or "all-zero" traceparents.
- */
-function parseTraceparent(raw) {
-    if (!raw)
-        return undefined;
-    const match = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i.exec(raw.trim());
-    if (!match)
-        return undefined;
-    const traceId = match[2].toLowerCase();
-    const parentSpanId = match[3].toLowerCase();
-    if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
-        return undefined;
-    return { traceId, parentSpanId };
-}
-// ─── Live Watch ────────────────────────────────────────────────────
-const STATUS_ICONS = {
-    ok: "\x1b[32m✓\x1b[0m",
-    error: "\x1b[31m✗\x1b[0m",
-    denied: "\x1b[31m⊘\x1b[0m",
-    skipped: "\x1b[33m─\x1b[0m",
-};
-const EVENT_PAD = 22;
-/**
- * Format a single TraceSpan for terminal display.
- */
-function formatSpan(span) {
-    const time = span.startedAt.slice(11, 23); // HH:MM:SS.mmm
-    const icon = STATUS_ICONS[span.status];
-    const event = span.event.padEnd(EVENT_PAD);
-    const traceShort = `\x1b[2m[${span.traceId.slice(0, 8)}]\x1b[0m`;
-    const parts = [];
-    // Duration (skip for instant spans)
-    if (span.durationMs > 0) {
-        parts.push(`\x1b[2m${span.durationMs}ms\x1b[0m`);
-    }
-    // Key attributes
-    if (span.attributes) {
-        const a = span.attributes;
-        if (a.toolName)
-            parts.push(`tool=${a.toolName}`);
-        if (a.allowed !== undefined)
-            parts.push(`allowed=${a.allowed}`);
-        if (a.sessionId)
-            parts.push(`session=${a.sessionId}`);
-        if (a.identityId)
-            parts.push(`identity=${a.identityId}`);
-        if (a.clientId)
-            parts.push(`client=${a.clientId}`);
-        if (a.error)
-            parts.push(`\x1b[31merror=${a.error}\x1b[0m`);
-    }
-    if (span.sessionId && !parts.some((p) => p.startsWith("session="))) {
-        parts.push(`session=${span.sessionId}`);
-    }
-    const detail = parts.length > 0 ? " " + parts.join(" ") : "";
-    return `\x1b[2m${time}\x1b[0m ${event} ${traceShort} ${icon}${detail}`;
-}
-/**
- * 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.
- */
-function watchTraceFile(filePath, callback) {
-    let offset = 0;
-    function poll() {
-        try {
-            if (!fs.existsSync(filePath))
-                return;
-            const stat = fs.statSync(filePath);
-            if (stat.size <= offset)
-                return;
-            const fd = fs.openSync(filePath, "r");
-            try {
-                const buf = Buffer.alloc(stat.size - offset);
-                fs.readSync(fd, buf, 0, buf.length, offset);
-                offset = stat.size;
-                const lines = buf.toString().split("\n").filter(Boolean);
-                for (const line of lines) {
-                    try {
-                        callback(JSON.parse(line));
-                    }
-                    catch {
-                        /* skip malformed lines */
-                    }
-                }
-            }
-            finally {
-                fs.closeSync(fd);
-            }
-        }
-        catch {
-            /* file may be mid-write */
-        }
-    }
-    poll(); // read existing content
-    const timer = setInterval(poll, 200);
-    return () => clearInterval(timer);
-}

package/dist/watch-sandbox.d.ts

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-/**
- * Live trace watcher for the dev sandbox.
- *
- * Tails the NDJSON trace file produced by `pnpm dev:<harness>` and prints
- * a colorized line per span as they arrive. Run in a second terminal
- * alongside the dev launcher.
- */
-export {};