@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/observation/artifact.test.js

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { buildTraceReceipt, exportObservationSession, getTraceDirectory } from './artifact.js';
+import { ObservationSession } from './session.js';
+describe('observation artifact', () => {
+    let baseDir;
+    beforeEach(() => {
+        baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-trace-'));
+    });
+    afterEach(() => {
+        fs.rmSync(baseDir, { recursive: true, force: true });
+    });
+    it('writes artifacts under profile-scoped trace directory', () => {
+        const session = new ObservationSession({
+            id: 'trace-1',
+            scope: {
+                contextId: 'work',
+                session: 'site:demo',
+                site: 'demo',
+                command: 'demo/run',
+                adapterSourcePath: '/tmp/clis/demo/run.js',
+            },
+            now: () => 1_700_000_000_000,
+        });
+        session.record({ stream: 'action', name: 'command', phase: 'start' });
+        session.record({ stream: 'screenshot', format: 'png', data: Buffer.from('png-bytes').toString('base64'), label: 'final' });
+        session.record({
+            stream: 'network',
+            url: 'https://api.test/data?token=secret',
+            method: 'GET',
+            status: 500,
+            requestHeaders: { authorization: 'Bearer secret' },
+            responseBody: { ok: false },
+        });
+        session.record({ stream: 'console', level: 'error', text: 'boom password=supersecret' });
+        const result = exportObservationSession(session, { baseDir, error: new Error('failed') });
+        expect(result.dir).toBe(getTraceDirectory('work', 'trace-1', baseDir));
+        expect(fs.existsSync(path.join(result.dir, 'trace.jsonl'))).toBe(true);
+        expect(fs.existsSync(path.join(result.dir, 'network.jsonl'))).toBe(true);
+        expect(fs.existsSync(path.join(result.dir, 'console.jsonl'))).toBe(true);
+        expect(fs.existsSync(result.receiptPath)).toBe(true);
+        expect(fs.readFileSync(path.join(result.dir, 'screenshots', '0001.png'), 'utf-8')).toBe('png-bytes');
+        const trace = fs.readFileSync(path.join(result.dir, 'trace.jsonl'), 'utf-8');
+        expect(trace).toContain('token=[REDACTED]');
+        expect(trace).toContain('"authorization":"[REDACTED]"');
+        expect(trace).not.toContain('supersecret');
+        const summary = fs.readFileSync(result.summaryPath, 'utf-8');
+        expect(summary).toContain('schemaVersion: 1');
+        expect(summary).toContain('webcmdVersion:');
+        expect(summary).toContain('expiresAt:');
+        expect(summary).toContain('status: failure');
+        expect(summary).toContain('contextId: "work"');
+        expect(summary).toContain('adapterSourcePath: "/tmp/clis/demo/run.js"');
+        expect(summary).toContain('adapterSourcePathExists: false');
+        expect(summary).toContain('## Failed Network');
+        expect(summary).toContain('500 GET https://api.test/data?token=[REDACTED]');
+        expect(summary).toContain('network: 1');
+        const receipt = JSON.parse(fs.readFileSync(result.receiptPath, 'utf-8'));
+        expect(receipt).toMatchObject({
+            schemaVersion: 1,
+            webcmdVersion: expect.any(String),
+            traceId: 'trace-1',
+            traceDir: result.dir,
+            summaryPath: result.summaryPath,
+            receiptPath: result.receiptPath,
+            status: 'failure',
+            expiresAt: expect.any(String),
+            scope: {
+                contextId: 'work',
+                session: 'site:demo',
+                site: 'demo',
+                command: 'demo/run',
+                adapterSourcePath: '/tmp/clis/demo/run.js',
+            },
+            error: { message: 'failed' },
+        });
+    });
+    it('builds a compact trace receipt', () => {
+        const receipt = buildTraceReceipt({
+            traceId: 'trace-1',
+            dir: '/tmp/webcmd/profiles/work/traces/trace-1',
+            summaryPath: '/tmp/webcmd/profiles/work/traces/trace-1/summary.md',
+            receiptPath: '/tmp/webcmd/profiles/work/traces/trace-1/receipt.json',
+        }, 'failure', new Error('failed with token=secret'), {
+            createdAt: '2026-05-03T00:00:00.000Z',
+            retentionPolicy: { maxAgeDays: 7 },
+        });
+        expect(receipt).toMatchObject({
+            schemaVersion: 1,
+            webcmdVersion: expect.any(String),
+            traceId: 'trace-1',
+            traceDir: '/tmp/webcmd/profiles/work/traces/trace-1',
+            receiptPath: '/tmp/webcmd/profiles/work/traces/trace-1/receipt.json',
+            status: 'failure',
+            expiresAt: '2026-05-10T00:00:00.000Z',
+        });
+        expect(receipt.error?.message).toContain('token=[REDACTED]');
+    });
+    it('prunes older traces after export while protecting the exported trace', () => {
+        const oldTraceDir = getTraceDirectory('work', 'old-trace', baseDir);
+        fs.mkdirSync(oldTraceDir, { recursive: true });
+        fs.writeFileSync(path.join(oldTraceDir, 'receipt.json'), JSON.stringify({
+            createdAt: '2026-04-01T00:00:00.000Z',
+        }), 'utf-8');
+        fs.writeFileSync(path.join(oldTraceDir, 'trace.jsonl'), '{}\n', 'utf-8');
+        const session = new ObservationSession({
+            id: 'new-trace',
+            scope: { contextId: 'work', session: 'site:demo' },
+            now: () => Date.parse('2026-05-03T00:00:00.000Z'),
+        });
+        session.record({ stream: 'action', name: 'command', phase: 'start' });
+        const result = exportObservationSession(session, {
+            baseDir,
+            retentionPolicy: { maxAgeDays: 365, maxCountPerProfile: 1, maxBytesPerProfile: '500MB' },
+        });
+        expect(fs.existsSync(oldTraceDir)).toBe(false);
+        expect(fs.existsSync(result.dir)).toBe(true);
+    });
+});

package/dist/src/observation/events.d.ts

@@ -0,0 +1,89 @@
+export type ObservationStream = 'action' | 'network' | 'console' | 'screenshot' | 'state' | 'error';
+export interface ObservationScope {
+    contextId?: string;
+    session: string;
+    target?: string;
+    site?: string;
+    command?: string;
+    adapterSourcePath?: string;
+}
+interface BaseObservationEvent {
+    id: string;
+    ts: number;
+    stream: ObservationStream;
+}
+export interface ActionObservationEvent extends BaseObservationEvent {
+    stream: 'action';
+    name: string;
+    phase?: 'start' | 'end' | 'error';
+    data?: Record<string, unknown>;
+}
+export interface NetworkObservationEvent extends BaseObservationEvent {
+    stream: 'network';
+    url: string;
+    method?: string;
+    status?: number;
+    contentType?: string;
+    size?: number;
+    requestHeaders?: Record<string, unknown>;
+    responseHeaders?: Record<string, unknown>;
+    requestBody?: unknown;
+    responseBody?: unknown;
+}
+export interface ConsoleObservationEvent extends BaseObservationEvent {
+    stream: 'console';
+    level: string;
+    text: string;
+    source?: string;
+}
+export interface ScreenshotObservationEvent extends BaseObservationEvent {
+    stream: 'screenshot';
+    format: 'png' | 'jpeg';
+    data: string;
+    label?: string;
+}
+export interface StateObservationEvent extends BaseObservationEvent {
+    stream: 'state';
+    url?: string | null;
+    target?: string;
+    snapshot?: unknown;
+    label?: string;
+}
+export interface ErrorObservationEvent extends BaseObservationEvent {
+    stream: 'error';
+    code?: string;
+    message: string;
+    stack?: string;
+    hint?: string;
+}
+export type ObservationEvent = ActionObservationEvent | NetworkObservationEvent | ConsoleObservationEvent | ScreenshotObservationEvent | StateObservationEvent | ErrorObservationEvent;
+export type ObservationEventInput = ObservationEvent extends infer T ? T extends ObservationEvent ? Omit<T, 'id' | 'ts'> & Partial<Pick<T, 'id' | 'ts'>> : never : never;
+export interface ObservationExportResult {
+    traceId: string;
+    dir: string;
+    summaryPath: string;
+    receiptPath: string;
+    receipt: ObservationTraceReceipt;
+}
+export type ObservationExportStatus = 'success' | 'failure';
+export interface ObservationTraceReceipt {
+    schemaVersion: 1;
+    webcmdVersion: string;
+    traceId: string;
+    traceDir: string;
+    summaryPath: string;
+    receiptPath: string;
+    status: ObservationExportStatus;
+    createdAt: string;
+    /** Advisory only; actual deletion is governed by current trace retention budgets. */
+    expiresAt?: string;
+    scope?: ObservationScope;
+    error?: {
+        name?: string;
+        code?: string;
+        message: string;
+        hint?: string;
+        exitCode?: number;
+    };
+}
+export {};

package/dist/src/observation/events.js

@@ -0,0 +1 @@
+export {};

package/dist/src/observation/index.d.ts

@@ -0,0 +1,7 @@
+export * from './events.js';
+export * from './ring-buffer.js';
+export * from './redaction.js';
+export * from './session.js';
+export * from './manager.js';
+export * from './artifact.js';
+export * from './retention.js';

package/dist/src/observation/index.js

@@ -0,0 +1,7 @@
+export * from './events.js';
+export * from './ring-buffer.js';
+export * from './redaction.js';
+export * from './session.js';
+export * from './manager.js';
+export * from './artifact.js';
+export * from './retention.js';

package/dist/src/observation/manager.d.ts

@@ -0,0 +1,9 @@
+import { ObservationSession, type ObservationSessionOptions } from './session.js';
+import type { ObservationScope } from './events.js';
+export declare class ObservationManager {
+    private readonly sessions;
+    start(opts: ObservationSessionOptions): ObservationSession;
+    get(id: string): ObservationSession | undefined;
+    stop(id: string): ObservationSession | undefined;
+    findByScope(scope: ObservationScope): ObservationSession[];
+}

package/dist/src/observation/manager.js

@@ -0,0 +1,27 @@
+import { ObservationSession } from './session.js';
+export class ObservationManager {
+    sessions = new Map();
+    start(opts) {
+        const session = new ObservationSession(opts);
+        this.sessions.set(session.id, session);
+        return session;
+    }
+    get(id) {
+        return this.sessions.get(id);
+    }
+    stop(id) {
+        const session = this.sessions.get(id);
+        this.sessions.delete(id);
+        return session;
+    }
+    findByScope(scope) {
+        return [...this.sessions.values()].filter((session) => scopeMatches(session.scope, scope));
+    }
+}
+function scopeMatches(actual, expected) {
+    return actual.session === expected.session
+        && (expected.contextId === undefined || actual.contextId === expected.contextId)
+        && (expected.target === undefined || actual.target === expected.target)
+        && (expected.site === undefined || actual.site === expected.site)
+        && (expected.command === undefined || actual.command === expected.command);
+}

package/dist/src/observation/manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/observation/manager.test.js

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { ObservationManager } from './manager.js';
+describe('ObservationManager', () => {
+    it('indexes sessions by id and scope', () => {
+        const manager = new ObservationManager();
+        const work = manager.start({ id: 'work-1', scope: { contextId: 'work', session: 'site:x', target: 'tab-1' } });
+        manager.start({ id: 'personal-1', scope: { contextId: 'personal', session: 'site:x', target: 'tab-2' } });
+        expect(manager.get('work-1')).toBe(work);
+        expect(manager.findByScope({ contextId: 'work', session: 'site:x' }).map((session) => session.id)).toEqual(['work-1']);
+        expect(manager.stop('work-1')).toBe(work);
+        expect(manager.get('work-1')).toBeUndefined();
+    });
+});

package/dist/src/observation/redaction.d.ts

@@ -0,0 +1,11 @@
+export interface RedactionOptions {
+    allowlist?: string[];
+    maxStringLength?: number;
+    maxDepth?: number;
+    maxArrayItems?: number;
+    maxObjectFields?: number;
+}
+export declare function redactUrl(url: string): string;
+export declare function redactHeaders(headers: Record<string, unknown> | undefined, opts?: RedactionOptions): Record<string, unknown> | undefined;
+export declare function redactText(text: string, opts?: RedactionOptions): string;
+export declare function redactValue(value: unknown, opts?: RedactionOptions, keyHint?: string, depth?: number): unknown;

package/dist/src/observation/redaction.js

@@ -0,0 +1,81 @@
+const DEFAULT_REDACTION = '[REDACTED]';
+const SENSITIVE_HEADER_NAMES = new Set([
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'proxy-authorization',
+    'x-api-key',
+    'x-auth-token',
+    'x-csrf-token',
+    'x-xsrf-token',
+]);
+const SENSITIVE_FIELD_PATTERN = /(password|passwd|pwd|token|secret|authorization|cookie|set-cookie|api[_-]?key|access[_-]?token|refresh[_-]?token|session[_-]?id|csrf|xsrf)/i;
+const SENSITIVE_URL_PARAMS = /([?&])(token|key|secret|password|auth|access_token|api_key|session_id|csrf|xsrf)=[^&]*/gi;
+export function redactUrl(url) {
+    return url.replace(SENSITIVE_URL_PARAMS, '$1$2=[REDACTED]');
+}
+export function redactHeaders(headers, opts = {}) {
+    if (!headers)
+        return headers;
+    const allow = new Set((opts.allowlist ?? []).map((key) => key.toLowerCase()));
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        const lower = key.toLowerCase();
+        out[key] = SENSITIVE_HEADER_NAMES.has(lower) && !allow.has(lower)
+            ? DEFAULT_REDACTION
+            : redactValue(value, opts, key);
+    }
+    return out;
+}
+export function redactText(text, opts = {}) {
+    const max = opts.maxStringLength ?? 50_000;
+    let out = text
+        .replace(/Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi, 'Bearer [REDACTED]')
+        .replace(/(["'])(password|passwd|pwd|token|secret|api_key|apikey|access_token|session_id)\1\s*:\s*(["'])(.*?)\3/gi, '$1$2$1:$3[REDACTED]$3')
+        .replace(/(token|secret|password|api_key|apikey|access_token|session_id)[=:]\s*['"]?[^'"\s,;}&]+['"]?/gi, '$1=[REDACTED]')
+        .replace(/(cookie[=:]\s*)[^\n;]{3,}/gi, '$1[REDACTED]')
+        .replace(/eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, '[REDACTED_JWT]');
+    if (out.length > max)
+        out = out.slice(0, max) + `\n...[truncated, ${out.length - max} chars omitted]`;
+    return out;
+}
+export function redactValue(value, opts = {}, keyHint, depth = 0) {
+    const allow = new Set((opts.allowlist ?? []).map((key) => key.toLowerCase()));
+    if (keyHint && SENSITIVE_FIELD_PATTERN.test(keyHint) && !allow.has(keyHint.toLowerCase())) {
+        return DEFAULT_REDACTION;
+    }
+    if (typeof value === 'string') {
+        return keyHint === 'url' ? redactUrl(value) : redactText(value, opts);
+    }
+    if (value === null || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    const maxDepth = opts.maxDepth ?? 5;
+    if (depth >= maxDepth)
+        return '[truncated: max depth reached]';
+    if (Array.isArray(value)) {
+        const max = opts.maxArrayItems ?? 100;
+        const items = value.slice(0, max).map((item) => redactValue(item, opts, undefined, depth + 1));
+        if (value.length > max)
+            items.push(`[truncated, ${value.length - max} items omitted]`);
+        return items;
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value);
+        const max = opts.maxObjectFields ?? 100;
+        const out = {};
+        for (const [key, child] of entries.slice(0, max)) {
+            if (key.toLowerCase() === 'url' && typeof child === 'string')
+                out[key] = redactUrl(child);
+            else if (key.toLowerCase().includes('headers') && child && typeof child === 'object' && !Array.isArray(child)) {
+                out[key] = redactHeaders(child, opts);
+            }
+            else {
+                out[key] = redactValue(child, opts, key, depth + 1);
+            }
+        }
+        if (entries.length > max)
+            out.__truncated__ = `[${entries.length - max} fields omitted]`;
+        return out;
+    }
+    return value;
+}

package/dist/src/observation/redaction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/observation/redaction.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { redactHeaders, redactUrl, redactValue } from './redaction.js';
+describe('observation redaction', () => {
+    it('redacts sensitive headers by default', () => {
+        expect(redactHeaders({
+            authorization: 'Bearer secret-token',
+            cookie: 'sid=abc',
+            'set-cookie': 'sid=abc',
+            accept: 'application/json',
+        })).toEqual({
+            authorization: '[REDACTED]',
+            cookie: '[REDACTED]',
+            'set-cookie': '[REDACTED]',
+            accept: 'application/json',
+        });
+    });
+    it('redacts sensitive url query params', () => {
+        expect(redactUrl('https://x.test/api?token=abc&ok=1&password=secret'))
+            .toBe('https://x.test/api?token=[REDACTED]&ok=1&password=[REDACTED]');
+    });
+    it('redacts password and token fields recursively', () => {
+        expect(redactValue({
+            user: 'alice',
+            password: 'secret',
+            nested: { access_token: 'abc123456789', value: 'safe' },
+        })).toEqual({
+            user: 'alice',
+            password: '[REDACTED]',
+            nested: { access_token: '[REDACTED]', value: 'safe' },
+        });
+    });
+});

package/dist/src/observation/retention.d.ts

@@ -0,0 +1,32 @@
+export interface TraceRetentionPolicyInput {
+    maxAgeDays?: number;
+    maxCountPerProfile?: number;
+    maxBytesPerProfile?: string | number;
+}
+export interface ResolvedTraceRetentionPolicy {
+    maxAgeDays: number;
+    maxAgeMs: number;
+    maxCountPerProfile: number;
+    maxBytesPerProfile: number;
+}
+export interface TraceRetentionPruneResult {
+    scanned: number;
+    deleted: string[];
+    kept: string[];
+    totalBytesBefore: number;
+    totalBytesAfter: number;
+}
+export declare const DEFAULT_TRACE_RETENTION_POLICY: {
+    maxAgeDays: number;
+    maxCountPerProfile: number;
+    maxBytesPerProfile: string;
+};
+export declare function parseByteSize(value: string | number): number;
+export declare function resolveTraceRetentionPolicy(input?: TraceRetentionPolicyInput): ResolvedTraceRetentionPolicy;
+export declare function traceExpiresAt(createdAt: string, policyInput?: TraceRetentionPolicyInput): string;
+export declare function pruneTraceArtifacts(tracesDir: string, opts?: {
+    policy?: TraceRetentionPolicyInput;
+    protectedTraceDirs?: string[];
+    now?: () => number;
+    warn?: (message: string) => void;
+}): TraceRetentionPruneResult;

package/dist/src/observation/retention.js

@@ -0,0 +1,160 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { log } from '../logger.js';
+export const DEFAULT_TRACE_RETENTION_POLICY = {
+    maxAgeDays: 7,
+    maxCountPerProfile: 20,
+    maxBytesPerProfile: '500MB',
+};
+const BYTES_UNITS = {
+    B: 1,
+    KB: 1024,
+    MB: 1024 ** 2,
+    GB: 1024 ** 3,
+};
+export function parseByteSize(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value < 0)
+            throw new Error(`Invalid byte size: ${value}`);
+        return Math.floor(value);
+    }
+    const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$/i);
+    if (!match)
+        throw new Error(`Invalid byte size: ${value}`);
+    const amount = Number(match[1]);
+    const unit = (match[2] ?? 'B').toUpperCase();
+    return Math.floor(amount * BYTES_UNITS[unit]);
+}
+export function resolveTraceRetentionPolicy(input = {}) {
+    const maxAgeDays = input.maxAgeDays ?? DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays;
+    const maxCountPerProfile = input.maxCountPerProfile ?? DEFAULT_TRACE_RETENTION_POLICY.maxCountPerProfile;
+    if (!Number.isFinite(maxAgeDays) || maxAgeDays < 0)
+        throw new Error(`Invalid trace maxAgeDays: ${maxAgeDays}`);
+    if (!Number.isInteger(maxCountPerProfile) || maxCountPerProfile < 0) {
+        throw new Error(`Invalid trace maxCountPerProfile: ${maxCountPerProfile}`);
+    }
+    return {
+        maxAgeDays,
+        maxAgeMs: maxAgeDays * 24 * 60 * 60 * 1000,
+        maxCountPerProfile,
+        maxBytesPerProfile: parseByteSize(input.maxBytesPerProfile ?? DEFAULT_TRACE_RETENTION_POLICY.maxBytesPerProfile),
+    };
+}
+export function traceExpiresAt(createdAt, policyInput = {}) {
+    const policy = resolveTraceRetentionPolicy(policyInput);
+    const createdAtMs = Date.parse(createdAt);
+    const base = Number.isFinite(createdAtMs) ? createdAtMs : Date.now();
+    return new Date(base + policy.maxAgeMs).toISOString();
+}
+export function pruneTraceArtifacts(tracesDir, opts = {}) {
+    const warn = opts.warn ?? ((message) => log.warn(`[trace] ${message}`));
+    const policy = resolveTraceRetentionPolicy(opts.policy);
+    const now = opts.now ?? Date.now;
+    const protectedDirs = new Set((opts.protectedTraceDirs ?? []).map((dir) => path.resolve(dir)));
+    const entries = readTraceEntries(tracesDir, protectedDirs, warn);
+    const totalBytesBefore = entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+    const deleted = new Set();
+    const sorted = [...entries].sort((a, b) => a.createdAtMs - b.createdAtMs || a.dir.localeCompare(b.dir));
+    const cutoff = now() - policy.maxAgeMs;
+    for (const entry of sorted) {
+        if (!entry.protected && entry.createdAtMs < cutoff)
+            deleted.add(entry.dir);
+    }
+    let remaining = sorted.filter((entry) => !deleted.has(entry.dir));
+    while (remaining.length > policy.maxCountPerProfile) {
+        const victim = remaining.find((entry) => !entry.protected);
+        if (!victim)
+            break;
+        deleted.add(victim.dir);
+        remaining = remaining.filter((entry) => entry.dir !== victim.dir);
+    }
+    let remainingBytes = remaining.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+    while (remainingBytes > policy.maxBytesPerProfile) {
+        const victim = remaining.find((entry) => !entry.protected);
+        if (!victim)
+            break;
+        deleted.add(victim.dir);
+        remaining = remaining.filter((entry) => entry.dir !== victim.dir);
+        remainingBytes -= victim.sizeBytes;
+    }
+    const deletedDirs = [];
+    for (const dir of sorted.map((entry) => entry.dir).filter((dir) => deleted.has(dir))) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            deletedDirs.push(dir);
+        }
+        catch (err) {
+            warn(`Failed to prune trace artifact ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const keptEntries = entries.filter((entry) => !deletedDirs.includes(entry.dir));
+    return {
+        scanned: entries.length,
+        deleted: deletedDirs,
+        kept: keptEntries.map((entry) => entry.dir),
+        totalBytesBefore,
+        totalBytesAfter: keptEntries.reduce((sum, entry) => sum + entry.sizeBytes, 0),
+    };
+}
+function readTraceEntries(tracesDir, protectedDirs, warn) {
+    let names;
+    try {
+        names = fs.readdirSync(tracesDir);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return [];
+        warn(`Failed to list trace artifacts in ${tracesDir}: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        const dir = path.join(tracesDir, name);
+        try {
+            const stat = fs.statSync(dir);
+            if (!stat.isDirectory())
+                continue;
+            entries.push({
+                dir,
+                createdAtMs: readCreatedAtMs(dir, stat.mtimeMs),
+                sizeBytes: directorySize(dir),
+                protected: protectedDirs.has(path.resolve(dir)),
+            });
+        }
+        catch (err) {
+            if (!isEnoent(err)) {
+                warn(`Failed to inspect trace artifact ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return entries;
+}
+function readCreatedAtMs(dir, fallbackMs) {
+    try {
+        const receipt = JSON.parse(fs.readFileSync(path.join(dir, 'receipt.json'), 'utf-8'));
+        if (typeof receipt.createdAt === 'string') {
+            const parsed = Date.parse(receipt.createdAt);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    catch {
+        // Older or hand-edited trace directories may not have a receipt.
+    }
+    return fallbackMs;
+}
+function directorySize(dir) {
+    let total = 0;
+    for (const name of fs.readdirSync(dir)) {
+        const item = path.join(dir, name);
+        const stat = fs.lstatSync(item);
+        if (stat.isDirectory())
+            total += directorySize(item);
+        else
+            total += stat.size;
+    }
+    return total;
+}
+function isEnoent(err) {
+    return typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT';
+}

package/dist/src/observation/retention.test.d.ts

@@ -0,0 +1 @@
+export {};