@a5c-ai/genty-platform 5.1.1-staging.00ceebd28cf2

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 "@a5c-ai/babysitter-sdk";
+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,wBAAwB,CAAC;AAC3D,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"}

package/dist/observability/index.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsCollector = exports.FeatureFlagStore = exports.formatProgressJson = exports.formatProgressText = exports.summarizeProgress = exports.collectAuditRecords = exports.exportAuditLog = exports.formatTriageReport = exports.triageFailures = exports.formatDashboardText = exports.buildResumeDashboard = exports.formatContextReport = exports.diffContexts = exports.captureContext = exports.formatPlanSummary = exports.updatePlanProgress = exports.capturePromptPlan = exports.WEBHOOK_SCHEMA_VERSION = exports.filterRegistrations = exports.evaluateAlertLevel = exports.buildWebhookEvent = exports.listWebhooks = exports.unregisterWebhook = exports.registerWebhook = exports.getPendingWorkItems = exports.getOrchestrationStatus = exports.getRunHealthSnapshot = exports.computeRunHealthFromEvents = exports.buildPhaseTimelineFromEvents = exports.buildPhaseTimeline = void 0;
+/**
+ * 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.
+ */
+var observability_1 = require("@a5c-ai/genty-runtime/observability");
+Object.defineProperty(exports, "buildPhaseTimeline", { enumerable: true, get: function () { return observability_1.buildPhaseTimeline; } });
+Object.defineProperty(exports, "buildPhaseTimelineFromEvents", { enumerable: true, get: function () { return observability_1.buildPhaseTimelineFromEvents; } });
+Object.defineProperty(exports, "computeRunHealthFromEvents", { enumerable: true, get: function () { return observability_1.computeRunHealthFromEvents; } });
+Object.defineProperty(exports, "getRunHealthSnapshot", { enumerable: true, get: function () { return observability_1.getRunHealthSnapshot; } });
+Object.defineProperty(exports, "getOrchestrationStatus", { enumerable: true, get: function () { return observability_1.getOrchestrationStatus; } });
+Object.defineProperty(exports, "getPendingWorkItems", { enumerable: true, get: function () { return observability_1.getPendingWorkItems; } });
+Object.defineProperty(exports, "registerWebhook", { enumerable: true, get: function () { return observability_1.registerWebhook; } });
+Object.defineProperty(exports, "unregisterWebhook", { enumerable: true, get: function () { return observability_1.unregisterWebhook; } });
+Object.defineProperty(exports, "listWebhooks", { enumerable: true, get: function () { return observability_1.listWebhooks; } });
+Object.defineProperty(exports, "buildWebhookEvent", { enumerable: true, get: function () { return observability_1.buildWebhookEvent; } });
+Object.defineProperty(exports, "evaluateAlertLevel", { enumerable: true, get: function () { return observability_1.evaluateAlertLevel; } });
+Object.defineProperty(exports, "filterRegistrations", { enumerable: true, get: function () { return observability_1.filterRegistrations; } });
+Object.defineProperty(exports, "WEBHOOK_SCHEMA_VERSION", { enumerable: true, get: function () { return observability_1.WEBHOOK_SCHEMA_VERSION; } });
+// Prompt plan (OBS-003)
+var promptPlan_1 = require("./promptPlan");
+Object.defineProperty(exports, "capturePromptPlan", { enumerable: true, get: function () { return promptPlan_1.capturePromptPlan; } });
+Object.defineProperty(exports, "updatePlanProgress", { enumerable: true, get: function () { return promptPlan_1.updatePlanProgress; } });
+Object.defineProperty(exports, "formatPlanSummary", { enumerable: true, get: function () { return promptPlan_1.formatPlanSummary; } });
+// Context introspection (OBS-005)
+var contextIntrospection_1 = require("./contextIntrospection");
+Object.defineProperty(exports, "captureContext", { enumerable: true, get: function () { return contextIntrospection_1.captureContext; } });
+Object.defineProperty(exports, "diffContexts", { enumerable: true, get: function () { return contextIntrospection_1.diffContexts; } });
+Object.defineProperty(exports, "formatContextReport", { enumerable: true, get: function () { return contextIntrospection_1.formatContextReport; } });
+// Resume dashboard (GAP-UX-008)
+var resumeDashboard_1 = require("./resumeDashboard");
+Object.defineProperty(exports, "buildResumeDashboard", { enumerable: true, get: function () { return resumeDashboard_1.buildResumeDashboard; } });
+Object.defineProperty(exports, "formatDashboardText", { enumerable: true, get: function () { return resumeDashboard_1.formatDashboardText; } });
+// Failure triage (GAP-UX-009)
+var failureTriage_1 = require("./failureTriage");
+Object.defineProperty(exports, "triageFailures", { enumerable: true, get: function () { return failureTriage_1.triageFailures; } });
+Object.defineProperty(exports, "formatTriageReport", { enumerable: true, get: function () { return failureTriage_1.formatTriageReport; } });
+// Audit export (GAP-OBS-007)
+var auditExport_1 = require("./auditExport");
+Object.defineProperty(exports, "exportAuditLog", { enumerable: true, get: function () { return auditExport_1.exportAuditLog; } });
+Object.defineProperty(exports, "collectAuditRecords", { enumerable: true, get: function () { return auditExport_1.collectAuditRecords; } });
+// Progress summarization (GAP-OBS-008)
+var progressSummarizer_1 = require("./progressSummarizer");
+Object.defineProperty(exports, "summarizeProgress", { enumerable: true, get: function () { return progressSummarizer_1.summarizeProgress; } });
+Object.defineProperty(exports, "formatProgressText", { enumerable: true, get: function () { return progressSummarizer_1.formatProgressText; } });
+Object.defineProperty(exports, "formatProgressJson", { enumerable: true, get: function () { return progressSummarizer_1.formatProgressJson; } });
+// Analytics and feature flags (GAP-OBS-006)
+var analytics_1 = require("./analytics");
+Object.defineProperty(exports, "FeatureFlagStore", { enumerable: true, get: function () { return analytics_1.FeatureFlagStore; } });
+Object.defineProperty(exports, "AnalyticsCollector", { enumerable: true, get: function () { return analytics_1.AnalyticsCollector; } });

package/dist/observability/progressSummarizer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent Progress Summarization (GAP-OBS-008).
+ *
+ * Reads run state (journal, task statuses) and produces a compact progress
+ * summary with step counts, active agents, estimated completion, and highlights.
+ */
+export interface ProgressSummary {
+    totalSteps: number;
+    completedSteps: number;
+    failedSteps: number;
+    activeAgents: string[];
+    estimatedCompletion: number | null;
+    highlights: string[];
+}
+/**
+ * Read a run directory's journal and state to produce a progress summary.
+ */
+export declare function summarizeProgress(runDir: string): ProgressSummary;
+/**
+ * Render a progress summary as compact human-readable text.
+ */
+export declare function formatProgressText(summary: ProgressSummary): string;
+/**
+ * Render a progress summary as structured JSON string.
+ */
+export declare function formatProgressJson(summary: ProgressSummary): string;
+//# sourceMappingURL=progressSummarizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"progressSummarizer.d.ts","sourceRoot":"","sources":["../../src/observability/progressSummarizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAiBD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CA8DjE;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAyBnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAEnE"}

package/dist/observability/progressSummarizer.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Agent Progress Summarization (GAP-OBS-008).
+ *
+ * Reads run state (journal, task statuses) and produces a compact progress
+ * summary with step counts, active agents, estimated completion, and highlights.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeProgress = summarizeProgress;
+exports.formatProgressText = formatProgressText;
+exports.formatProgressJson = formatProgressJson;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Summarize
+// ---------------------------------------------------------------------------
+/**
+ * Read a run directory's journal and state to produce a progress summary.
+ */
+function summarizeProgress(runDir) {
+    const events = loadJournalEvents(runDir);
+    const stateData = loadRunState(runDir);
+    const taskStatuses = new Map();
+    const agentSet = new Set();
+    const highlights = [];
+    // Process journal events to track task statuses and active agents
+    for (const evt of events) {
+        const taskId = evt.taskId ?? '';
+        const status = evt.status ?? evt.event ?? evt.type ?? '';
+        const agent = evt.agent ?? evt.actor ?? '';
+        if (taskId) {
+            taskStatuses.set(taskId, status);
+        }
+        if (agent && isActiveStatus(status)) {
+            agentSet.add(agent);
+        }
+        if (agent && isTerminalStatus(status)) {
+            agentSet.delete(agent);
+        }
+        if (evt.message && isHighlightWorthy(status)) {
+            highlights.push(evt.message);
+        }
+    }
+    // Also inspect run state for task counts if available
+    if (stateData.tasks && Array.isArray(stateData.tasks)) {
+        for (const task of stateData.tasks) {
+            if (task.id && task.status) {
+                taskStatuses.set(task.id, task.status);
+            }
+        }
+    }
+    let totalSteps = 0;
+    let completedSteps = 0;
+    let failedSteps = 0;
+    for (const status of taskStatuses.values()) {
+        totalSteps++;
+        if (isCompletedStatus(status))
+            completedSteps++;
+        if (isFailedStatus(status))
+            failedSteps++;
+    }
+    const estimatedCompletion = totalSteps > 0
+        ? Math.round((completedSteps / totalSteps) * 100)
+        : null;
+    return {
+        totalSteps,
+        completedSteps,
+        failedSteps,
+        activeAgents: Array.from(agentSet),
+        estimatedCompletion,
+        highlights: highlights.slice(-5), // keep last 5 highlights
+    };
+}
+// ---------------------------------------------------------------------------
+// Format
+// ---------------------------------------------------------------------------
+/**
+ * Render a progress summary as compact human-readable text.
+ */
+function formatProgressText(summary) {
+    const lines = [];
+    const pct = summary.estimatedCompletion != null
+        ? ` (${summary.estimatedCompletion}%)`
+        : '';
+    lines.push(`Progress: ${summary.completedSteps}/${summary.totalSteps} steps completed${pct}`);
+    if (summary.failedSteps > 0) {
+        lines.push(`Failed: ${summary.failedSteps} steps`);
+    }
+    if (summary.activeAgents.length > 0) {
+        lines.push(`Active agents: ${summary.activeAgents.join(', ')}`);
+    }
+    if (summary.highlights.length > 0) {
+        lines.push('Highlights:');
+        for (const h of summary.highlights) {
+            lines.push(`  - ${h}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Render a progress summary as structured JSON string.
+ */
+function formatProgressJson(summary) {
+    return JSON.stringify(summary, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function loadJournalEvents(runDir) {
+    const journalPath = (0, node_path_1.join)(runDir, 'journal.jsonl');
+    if (!(0, node_fs_1.existsSync)(journalPath))
+        return [];
+    const raw = (0, node_fs_1.readFileSync)(journalPath, 'utf8').trim();
+    if (!raw)
+        return [];
+    return raw.split('\n').map((line) => JSON.parse(line));
+}
+function loadRunState(runDir) {
+    const statePath = (0, node_path_1.join)(runDir, 'state.json');
+    if (!(0, node_fs_1.existsSync)(statePath))
+        return {};
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(statePath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function isActiveStatus(status) {
+    return ['running', 'in-progress', 'active', 'task-started'].includes(status);
+}
+function isTerminalStatus(status) {
+    return ['completed', 'done', 'failed', 'error', 'task-completed', 'task-failed'].includes(status);
+}
+function isCompletedStatus(status) {
+    return ['completed', 'done', 'passed', 'task-completed'].includes(status);
+}
+function isFailedStatus(status) {
+    return ['failed', 'error', 'task-failed'].includes(status);
+}
+function isHighlightWorthy(status) {
+    return ['completed', 'done', 'failed', 'error', 'milestone', 'task-completed', 'task-failed'].includes(status);
+}

package/dist/observability/promptPlan.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Prompt plan capture and tracking (OBS-003).
+ *
+ * Records a planned sequence of steps before execution begins, then
+ * updates progress as each step completes. Useful for comparing the
+ * "intended plan" against what actually happened in a run.
+ */
+export type PlanStepStatus = 'pending' | 'in-progress' | 'completed' | 'skipped' | 'failed';
+export interface PlanStep {
+    id: string;
+    label: string;
+    status: PlanStepStatus;
+    startedAt?: string;
+    completedAt?: string;
+    error?: string;
+}
+export interface PromptPlan {
+    planId: string;
+    title: string;
+    steps: PlanStep[];
+    capturedAt: string;
+    updatedAt: string;
+}
+/**
+ * Create a new prompt plan from a list of step labels.
+ * All steps start in `pending` status.
+ */
+export declare function capturePromptPlan(planId: string, title: string, stepLabels: string[], now?: string): PromptPlan;
+/**
+ * Update the status of a step within a plan. Returns a new PromptPlan
+ * (immutable update).
+ */
+export declare function updatePlanProgress(plan: PromptPlan, stepId: string, status: PlanStepStatus, opts?: {
+    error?: string;
+    now?: string;
+}): PromptPlan;
+export interface PlanSummary {
+    planId: string;
+    title: string;
+    total: number;
+    completed: number;
+    failed: number;
+    skipped: number;
+    pending: number;
+    inProgress: number;
+    formatted: string;
+}
+/**
+ * Produce a summary snapshot for a prompt plan.
+ */
+export declare function formatPlanSummary(plan: PromptPlan): PlanSummary;
+//# sourceMappingURL=promptPlan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"promptPlan.d.ts","sourceRoot":"","sources":["../../src/observability/promptPlan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5F,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAAE,EACpB,GAAG,CAAC,EAAE,MAAM,GACX,UAAU,CAaZ;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,UAAU,CAmBZ;AAMD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CA0C/D"}