@a5c-ai/genty-platform 5.1.1-staging.0007199a1cb2

package/dist/observability/auditExport.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Audit Export (GAP-OBS-007).
+ *
+ * Collects governance decisions and journal events from a run directory
+ * and exports them as structured audit logs in JSON, CSV, or Markdown.
+ */
+export interface AuditRecord {
+    timestamp: string;
+    actor: string;
+    action: string;
+    resource: string;
+    outcome: string;
+    metadata?: Record<string, unknown>;
+}
+export type AuditExportFormat = 'json' | 'csv' | 'markdown';
+/**
+ * Serialize audit records to the requested format.
+ */
+export declare function exportAuditLog(records: AuditRecord[], format: AuditExportFormat): string;
+/**
+ * Read governance-decisions.jsonl and journal.jsonl from a run directory
+ * and return them as AuditRecord[].
+ */
+export declare function collectAuditRecords(runDir: string): AuditRecord[];
+//# sourceMappingURL=auditExport.d.ts.map

package/dist/observability/auditExport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditExport.d.ts","sourceRoot":"","sources":["../../src/observability/auditExport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAM5D;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CASR;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CA4CjE"}

package/dist/observability/auditExport.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Audit Export (GAP-OBS-007).
+ *
+ * Collects governance decisions and journal events from a run directory
+ * and exports them as structured audit logs in JSON, CSV, or Markdown.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportAuditLog = exportAuditLog;
+exports.collectAuditRecords = collectAuditRecords;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+/**
+ * Serialize audit records to the requested format.
+ */
+function exportAuditLog(records, format) {
+    switch (format) {
+        case 'json':
+            return JSON.stringify(records, null, 2);
+        case 'csv':
+            return exportCsv(records);
+        case 'markdown':
+            return exportMarkdown(records);
+    }
+}
+// ---------------------------------------------------------------------------
+// Collect
+// ---------------------------------------------------------------------------
+/**
+ * Read governance-decisions.jsonl and journal.jsonl from a run directory
+ * and return them as AuditRecord[].
+ */
+function collectAuditRecords(runDir) {
+    const records = [];
+    // governance-decisions.jsonl
+    const govPath = (0, node_path_1.join)(runDir, 'governance-decisions.jsonl');
+    if ((0, node_fs_1.existsSync)(govPath)) {
+        const lines = (0, node_fs_1.readFileSync)(govPath, 'utf8').trim().split('\n').filter(Boolean);
+        for (const line of lines) {
+            const parsed = JSON.parse(line);
+            records.push({
+                timestamp: String(parsed.timestamp ?? new Date().toISOString()),
+                actor: String(parsed.actor ?? 'governance'),
+                action: String(parsed.action ?? parsed.type ?? 'decision'),
+                resource: String(parsed.resource ?? parsed.target ?? ''),
+                outcome: String(parsed.outcome ?? parsed.result ?? ''),
+                metadata: typeof parsed.metadata === 'object' && parsed.metadata != null
+                    ? parsed.metadata
+                    : undefined,
+            });
+        }
+    }
+    // journal.jsonl
+    const journalPath = (0, node_path_1.join)(runDir, 'journal.jsonl');
+    if ((0, node_fs_1.existsSync)(journalPath)) {
+        const lines = (0, node_fs_1.readFileSync)(journalPath, 'utf8').trim().split('\n').filter(Boolean);
+        for (const line of lines) {
+            const parsed = JSON.parse(line);
+            records.push({
+                timestamp: String(parsed.timestamp ?? parsed.ts ?? new Date().toISOString()),
+                actor: String(parsed.actor ?? parsed.agent ?? 'system'),
+                action: String(parsed.action ?? parsed.event ?? parsed.type ?? 'journal'),
+                resource: String(parsed.resource ?? parsed.taskId ?? ''),
+                outcome: String(parsed.outcome ?? parsed.status ?? ''),
+                metadata: typeof parsed.metadata === 'object' && parsed.metadata != null
+                    ? parsed.metadata
+                    : undefined,
+            });
+        }
+    }
+    // Sort chronologically
+    records.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    return records;
+}
+// ---------------------------------------------------------------------------
+// Internal formatters
+// ---------------------------------------------------------------------------
+function escapeCsvField(value) {
+    if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+function exportCsv(records) {
+    const header = 'timestamp,actor,action,resource,outcome,metadata';
+    const rows = records.map((r) => [
+        escapeCsvField(r.timestamp),
+        escapeCsvField(r.actor),
+        escapeCsvField(r.action),
+        escapeCsvField(r.resource),
+        escapeCsvField(r.outcome),
+        escapeCsvField(r.metadata ? JSON.stringify(r.metadata) : ''),
+    ].join(','));
+    return [header, ...rows].join('\n');
+}
+function exportMarkdown(records) {
+    const lines = [
+        '| Timestamp | Actor | Action | Resource | Outcome |',
+        '|-----------|-------|--------|----------|---------|',
+    ];
+    for (const r of records) {
+        lines.push(`| ${r.timestamp} | ${r.actor} | ${r.action} | ${r.resource} | ${r.outcome} |`);
+    }
+    return lines.join('\n');
+}

package/dist/observability/contextIntrospection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Context introspection — capture, compare, and report on the runtime
+ * context visible to an agent at any point during a run (OBS-005).
+ *
+ * A "context snapshot" is a lightweight record of what information
+ * the agent currently has access to (variables, loaded files, tools,
+ * etc.). Diffing two snapshots reveals context drift over time.
+ */
+export interface ContextEntry {
+    key: string;
+    value: string;
+    source: string;
+}
+export interface ContextSnapshot {
+    snapshotId: string;
+    capturedAt: string;
+    entries: ContextEntry[];
+}
+export interface ContextDiff {
+    added: ContextEntry[];
+    removed: ContextEntry[];
+    changed: Array<{
+        key: string;
+        before: string;
+        after: string;
+    }>;
+}
+/**
+ * Create a new context snapshot from a set of key-value entries.
+ */
+export declare function captureContext(snapshotId: string, entries: ContextEntry[], now?: string): ContextSnapshot;
+/**
+ * Compare two context snapshots and return the differences.
+ */
+export declare function diffContexts(before: ContextSnapshot, after: ContextSnapshot): ContextDiff;
+/**
+ * Format a context diff into a human-readable report.
+ */
+export declare function formatContextReport(diff: ContextDiff): string;
+//# sourceMappingURL=contextIntrospection.d.ts.map

package/dist/observability/contextIntrospection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextIntrospection.d.ts","sourceRoot":"","sources":["../../src/observability/contextIntrospection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,EAAE,KAAK,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACJ;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,EAAE,EACvB,GAAG,CAAC,EAAE,MAAM,GACX,eAAe,CAMjB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,eAAe,GACrB,WAAW,CAiCb;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CA6B7D"}

package/dist/observability/contextIntrospection.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Context introspection — capture, compare, and report on the runtime
+ * context visible to an agent at any point during a run (OBS-005).
+ *
+ * A "context snapshot" is a lightweight record of what information
+ * the agent currently has access to (variables, loaded files, tools,
+ * etc.). Diffing two snapshots reveals context drift over time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureContext = captureContext;
+exports.diffContexts = diffContexts;
+exports.formatContextReport = formatContextReport;
+// ---------------------------------------------------------------------------
+// Capture
+// ---------------------------------------------------------------------------
+/**
+ * Create a new context snapshot from a set of key-value entries.
+ */
+function captureContext(snapshotId, entries, now) {
+    return {
+        snapshotId,
+        capturedAt: now ?? new Date().toISOString(),
+        entries: [...entries],
+    };
+}
+// ---------------------------------------------------------------------------
+// Diff
+// ---------------------------------------------------------------------------
+/**
+ * Compare two context snapshots and return the differences.
+ */
+function diffContexts(before, after) {
+    const beforeMap = new Map();
+    for (const entry of before.entries) {
+        beforeMap.set(entry.key, entry);
+    }
+    const afterMap = new Map();
+    for (const entry of after.entries) {
+        afterMap.set(entry.key, entry);
+    }
+    const added = [];
+    const removed = [];
+    const changed = [];
+    // Find added and changed
+    for (const [key, afterEntry] of afterMap) {
+        const beforeEntry = beforeMap.get(key);
+        if (!beforeEntry) {
+            added.push(afterEntry);
+        }
+        else if (beforeEntry.value !== afterEntry.value) {
+            changed.push({ key, before: beforeEntry.value, after: afterEntry.value });
+        }
+    }
+    // Find removed
+    for (const [key, beforeEntry] of beforeMap) {
+        if (!afterMap.has(key)) {
+            removed.push(beforeEntry);
+        }
+    }
+    return { added, removed, changed };
+}
+// ---------------------------------------------------------------------------
+// Report
+// ---------------------------------------------------------------------------
+/**
+ * Format a context diff into a human-readable report.
+ */
+function formatContextReport(diff) {
+    const lines = [];
+    if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) {
+        return 'No context changes.';
+    }
+    if (diff.added.length > 0) {
+        lines.push(`Added (${diff.added.length}):`);
+        for (const entry of diff.added) {
+            lines.push(`  + ${entry.key} = ${entry.value} [${entry.source}]`);
+        }
+    }
+    if (diff.removed.length > 0) {
+        lines.push(`Removed (${diff.removed.length}):`);
+        for (const entry of diff.removed) {
+            lines.push(`  - ${entry.key} = ${entry.value} [${entry.source}]`);
+        }
+    }
+    if (diff.changed.length > 0) {
+        lines.push(`Changed (${diff.changed.length}):`);
+        for (const c of diff.changed) {
+            lines.push(`  ~ ${c.key}: ${c.before} -> ${c.after}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/observability/failureTriage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Failure triage view — read failed effects from a run directory,
+ * classify their severity, and produce a structured triage report
+ * with suggested remediation actions (GAP-UX-009).
+ */
+export type FailureSeverity = 'fatal' | 'recoverable' | 'warning';
+export interface FailureEntry {
+    effectId: string;
+    kind: string;
+    error: string;
+    timestamp: string;
+    severity: FailureSeverity;
+}
+export interface TriageReport {
+    failures: FailureEntry[];
+    summary: string;
+    suggestedActions: string[];
+}
+/**
+ * Read failed effects from a run's journal and classify them into
+ * a triage report.
+ */
+export declare function triageFailures(runDir: string): Promise<TriageReport>;
+/**
+ * Render a triage report as a human-readable text block.
+ */
+export declare function formatTriageReport(report: TriageReport): string;
+//# sourceMappingURL=failureTriage.d.ts.map

package/dist/observability/failureTriage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureTriage.d.ts","sourceRoot":"","sources":["../../src/observability/failureTriage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAmCD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA+D1E;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA6B/D"}

package/dist/observability/failureTriage.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Failure triage view — read failed effects from a run directory,
+ * classify their severity, and produce a structured triage report
+ * with suggested remediation actions (GAP-UX-009).
+ */
+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.triageFailures = triageFailures;
+exports.formatTriageReport = formatTriageReport;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+const FATAL_PATTERNS = [
+    /ENOSPC/i,
+    /out of memory/i,
+    /segmentation fault/i,
+    /permission denied/i,
+    /EACCES/i,
+];
+const WARNING_PATTERNS = [
+    /timeout/i,
+    /rate limit/i,
+    /retry/i,
+    /transient/i,
+];
+function classifySeverity(error) {
+    for (const pattern of FATAL_PATTERNS) {
+        if (pattern.test(error))
+            return 'fatal';
+    }
+    for (const pattern of WARNING_PATTERNS) {
+        if (pattern.test(error))
+            return 'warning';
+    }
+    return 'recoverable';
+}
+// ---------------------------------------------------------------------------
+// Triage builder
+// ---------------------------------------------------------------------------
+/**
+ * Read failed effects from a run's journal and classify them into
+ * a triage report.
+ */
+async function triageFailures(runDir) {
+    const journalPath = path.join(runDir, 'journal.jsonl');
+    let journalLines = [];
+    try {
+        const raw = await node_fs_1.promises.readFile(journalPath, 'utf-8');
+        journalLines = raw.split('\n').filter((l) => l.trim().length > 0);
+    }
+    catch {
+        return {
+            failures: [],
+            summary: 'No journal found.',
+            suggestedActions: [],
+        };
+    }
+    const failures = [];
+    for (const line of journalLines) {
+        let evt;
+        try {
+            evt = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (evt.type !== 'EFFECT_FAILED')
+            continue;
+        const effectId = typeof evt.data.effectId === 'string' ? evt.data.effectId : 'unknown';
+        const kind = typeof evt.data.kind === 'string' ? evt.data.kind : 'unknown';
+        const error = typeof evt.data.error === 'string'
+            ? evt.data.error
+            : typeof evt.data.message === 'string'
+                ? evt.data.message
+                : 'Unknown error';
+        failures.push({
+            effectId,
+            kind,
+            error,
+            timestamp: evt.recordedAt,
+            severity: classifySeverity(error),
+        });
+    }
+    const fatalCount = failures.filter((f) => f.severity === 'fatal').length;
+    const recoverableCount = failures.filter((f) => f.severity === 'recoverable').length;
+    const warningCount = failures.filter((f) => f.severity === 'warning').length;
+    const summary = failures.length === 0
+        ? 'No failures detected.'
+        : `${failures.length} failure(s): ${fatalCount} fatal, ${recoverableCount} recoverable, ${warningCount} warning.`;
+    const suggestedActions = [];
+    if (fatalCount > 0) {
+        suggestedActions.push('Investigate fatal errors before resuming — these likely require manual intervention.');
+    }
+    if (recoverableCount > 0) {
+        suggestedActions.push('Recoverable errors may succeed on retry. Consider resuming the run.');
+    }
+    if (warningCount > 0) {
+        suggestedActions.push('Warnings (timeout/rate-limit) may resolve with backoff. Check external service status.');
+    }
+    return { failures, summary, suggestedActions };
+}
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+/**
+ * Render a triage report as a human-readable text block.
+ */
+function formatTriageReport(report) {
+    const lines = [];
+    const divider = '─'.repeat(50);
+    lines.push(divider);
+    lines.push('  Failure Triage Report');
+    lines.push(divider);
+    lines.push(`  ${report.summary}`);
+    lines.push('');
+    if (report.failures.length > 0) {
+        for (const f of report.failures) {
+            const tag = f.severity === 'fatal' ? 'FATAL' : f.severity === 'warning' ? 'WARN ' : 'RECOV';
+            lines.push(`  [${tag}] ${f.effectId} (${f.kind})`);
+            lines.push(`         ${f.error}`);
+            lines.push(`         at ${f.timestamp}`);
+        }
+        lines.push('');
+    }
+    if (report.suggestedActions.length > 0) {
+        lines.push('  Suggested Actions:');
+        for (const action of report.suggestedActions) {
+            lines.push(`    - ${action}`);
+        }
+    }
+    lines.push(divider);
+    return lines.join('\n');
+}

package/dist/observability/health.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Run Health Model (GAP-STATE-008).
+ *
+ * Computes a point-in-time health snapshot from journal events.
+ * Pure function — no file I/O, takes events as input.
+ */
+import type { JournalEvent } from "../types";
+import type { RunHealthSnapshot, HealthConfig } from "./types";
+interface HealthOptions {
+    config?: Partial<HealthConfig>;
+    /** Override "now" for testing. */
+    now?: number;
+}
+/**
+ * Compute a health snapshot from an array of journal events.
+ */
+export declare function computeRunHealthFromEvents(events: JournalEvent[], options?: HealthOptions): RunHealthSnapshot;
+export {};
+//# sourceMappingURL=health.d.ts.map

package/dist/observability/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/observability/health.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EACV,iBAAiB,EAGjB,YAAY,EACb,MAAM,SAAS,CAAC;AAiBjB,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,iBAAiB,CAiInB"}

package/dist/observability/health.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Run Health Model (GAP-STATE-008).
+ *
+ * Computes a point-in-time health snapshot from journal events.
+ * Pure function — no file I/O, takes events as input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRunHealthFromEvents = computeRunHealthFromEvents;
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    stuckThresholdMs: 300_000, // 5 minutes
+    degradedErrorRate: 0.3,
+    failedErrorRate: 0.7,
+    maxPendingAge: 600_000, // 10 minutes
+};
+/**
+ * Compute a health snapshot from an array of journal events.
+ */
+function computeRunHealthFromEvents(events, options) {
+    const config = { ...DEFAULT_CONFIG, ...options?.config };
+    const now = options?.now ?? Date.now();
+    // Track effects
+    const requestedAt = new Map(); // effectId → timestamp ms
+    const resolvedEffects = new Set();
+    let failedEffects = 0;
+    let totalLatency = 0;
+    let latencyCount = 0;
+    let lastActivityAt = null;
+    let hasRunFailed = false;
+    const iterations = new Set();
+    for (const event of events) {
+        lastActivityAt = event.recordedAt;
+        const ts = new Date(event.recordedAt).getTime();
+        if (event.type === "RUN_FAILED") {
+            hasRunFailed = true;
+        }
+        if (event.type === "EFFECT_REQUESTED") {
+            const effectId = typeof event.data.effectId === "string" ? event.data.effectId : undefined;
+            if (effectId) {
+                requestedAt.set(effectId, ts);
+            }
+            const iteration = typeof event.data.iteration === "number" ? event.data.iteration : undefined;
+            if (iteration != null) {
+                iterations.add(iteration);
+            }
+        }
+        if (event.type === "EFFECT_RESOLVED") {
+            const effectId = typeof event.data.effectId === "string" ? event.data.effectId : undefined;
+            if (effectId) {
+                resolvedEffects.add(effectId);
+                const reqTs = requestedAt.get(effectId);
+                if (reqTs != null) {
+                    totalLatency += ts - reqTs;
+                    latencyCount++;
+                }
+                const status = typeof event.data.status === "string" ? event.data.status : undefined;
+                if (status === "error") {
+                    failedEffects++;
+                }
+            }
+        }
+    }
+    // Compute metrics
+    const totalEffects = requestedAt.size;
+    const resolvedCount = resolvedEffects.size;
+    const pendingCount = totalEffects - resolvedCount;
+    const errorRate = resolvedCount > 0 ? failedEffects / resolvedCount : 0;
+    const avgEffectLatencyMs = latencyCount > 0 ? Math.round(totalLatency / latencyCount) : 0;
+    // Oldest pending effect age
+    let oldestPendingAgeMs = 0;
+    for (const [effectId, reqTs] of requestedAt) {
+        if (!resolvedEffects.has(effectId)) {
+            const age = now - reqTs;
+            if (age > oldestPendingAgeMs) {
+                oldestPendingAgeMs = age;
+            }
+        }
+    }
+    const metrics = {
+        errorRate,
+        avgEffectLatencyMs,
+        pendingCount,
+        oldestPendingAgeMs,
+        iterationCount: iterations.size,
+        lastActivityAt,
+        totalEffects,
+        resolvedEffects: resolvedCount,
+        failedEffects,
+    };
+    // Determine status and issues
+    const issues = [];
+    let status = "healthy";
+    if (hasRunFailed) {
+        status = "failed";
+        issues.push("Run failed: RUN_FAILED event detected");
+    }
+    else if (errorRate >= config.failedErrorRate && resolvedCount > 0) {
+        status = "failed";
+        issues.push(`High error rate: ${(errorRate * 100).toFixed(1)}% exceeds failed threshold (${(config.failedErrorRate * 100).toFixed(1)}%)`);
+    }
+    else if (lastActivityAt != null &&
+        now - new Date(lastActivityAt).getTime() > config.stuckThresholdMs &&
+        pendingCount > 0) {
+        status = "stuck";
+        const idleMs = now - new Date(lastActivityAt).getTime();
+        issues.push(`Run stuck: no activity for ${Math.round(idleMs / 1000)}s (threshold: ${Math.round(config.stuckThresholdMs / 1000)}s)`);
+    }
+    else if (errorRate >= config.degradedErrorRate && resolvedCount > 0) {
+        status = "degraded";
+        issues.push(`Elevated error rate: ${(errorRate * 100).toFixed(1)}% exceeds degraded threshold (${(config.degradedErrorRate * 100).toFixed(1)}%)`);
+    }
+    // Additional issues (additive, don't change status)
+    if (oldestPendingAgeMs > config.maxPendingAge &&
+        status !== "failed") {
+        issues.push(`Oldest pending effect age: ${Math.round(oldestPendingAgeMs / 1000)}s exceeds max pending age (${Math.round(config.maxPendingAge / 1000)}s)`);
+        if (status === "healthy") {
+            status = "degraded";
+        }
+    }
+    return {
+        status,
+        metrics,
+        issues,
+        computedAt: new Date(now).toISOString(),
+    };
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Re-export shim — canonical implementation lives in @a5c-ai/genty-runtime.
+ * Internal agent-platform consumers continue to import via relative paths
+ * through this barrel file.
+ */
+export { buildPhaseTimeline, buildPhaseTimelineFromEvents, computeRunHealthFromEvents, getRunHealthSnapshot, getOrchestrationStatus, getPendingWorkItems, type OrchestrationStatus, type OrchestrationPhase, type PendingWorkItem, type PhaseTimeline, type PhaseEntry, type PhaseName, type Milestone, type IterationTimeline, type RunHealthSnapshot, type RunHealthStatus, type RunHealthMetrics, type HealthConfig, registerWebhook, unregisterWebhook, listWebhooks, buildWebhookEvent, evaluateAlertLevel, filterRegistrations, type AlertLevel, type WebhookEventType, type WebhookRegistration, type WebhookEvent, type WebhookDeliveryResult, type WebhookRegistry, type WebhookRegistrationInput, WEBHOOK_SCHEMA_VERSION, } from "@a5c-ai/genty-runtime/observability";
+export { capturePromptPlan, updatePlanProgress, formatPlanSummary, type PlanStep, type PlanStepStatus, type PromptPlan, type PlanSummary, } from './promptPlan';
+export { captureContext, diffContexts, formatContextReport, type ContextEntry, type ContextSnapshot, type ContextDiff, } from './contextIntrospection';
+export { buildResumeDashboard, formatDashboardText, type ResumeDashboardData, type StepSummary, } from './resumeDashboard';
+export { triageFailures, formatTriageReport, type FailureEntry, type FailureSeverity, type TriageReport, } from './failureTriage';
+export { exportAuditLog, collectAuditRecords, type AuditRecord, type AuditExportFormat, } from './auditExport';
+export { summarizeProgress, formatProgressText, formatProgressJson, type ProgressSummary, } from './progressSummarizer';
+export { FeatureFlagStore, AnalyticsCollector, type FeatureFlag, type FeatureFlagContext, type AnalyticsEvent, } from './analytics';
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,sBAAsB,GACvB,MAAM,qCAAqC,CAAC;AAG7C,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC"}