vgxness 0.1.0

package/dist/runs/run-insights.js

@@ -0,0 +1,145 @@
+const insightSafety = { executableResume: false, executorInvoked: false, operationExecuted: false, writesProviderConfig: false, createsSandbox: false, createsWorktree: false };
+export function buildRunInsights(run) {
+    const resumePlan = buildResumePlan(run);
+    return {
+        runId: run.id,
+        timeline: buildTimeline(run),
+        debug: buildDebugSummary(run),
+        resumePlan,
+        safety: insightSafety,
+    };
+}
+export function buildRunOperatorResumePlan(run) {
+    const insights = buildRunInsights(run);
+    const pendingApprovals = run.approvals.filter((approval) => approval.status === 'pending');
+    const activeAttempts = run.operationAttempts.filter((attempt) => attempt.status === 'reserved');
+    const failedAttempts = run.operationAttempts.filter((attempt) => attempt.status === 'failed');
+    return {
+        run: {
+            id: run.id,
+            project: run.project,
+            status: run.status,
+            ...(run.outcome === undefined ? {} : { outcome: run.outcome }),
+            ...(run.outcomeReason === undefined ? {} : { outcomeReason: run.outcomeReason }),
+            workflow: run.workflow,
+            phase: run.phase,
+        },
+        debug: insights.debug,
+        resumePlan: insights.resumePlan,
+        latestCheckpoint: insights.resumePlan.latestCheckpoint ?? null,
+        blockers: insights.resumePlan.blockers,
+        pendingApprovals,
+        activeAttempts,
+        failedAttempts,
+        manualNextCommands: buildManualNextCommands(run.id, insights.resumePlan.latestCheckpoint?.id, pendingApprovals),
+        evidenceReferences: buildEvidenceReferences(run.id, insights.resumePlan.latestCheckpoint?.id, pendingApprovals, activeAttempts, failedAttempts, insights.debug),
+        safety: insightSafety,
+    };
+}
+function buildTimeline(run) {
+    const entries = [{ id: `${run.id}:created`, type: 'run-created', timestamp: run.createdAt, order: 0, sourceOrder: 0, label: 'Run created', evidence: { runId: run.id, status: run.status } }];
+    for (const event of run.events)
+        entries.push({ id: event.id, type: 'event', timestamp: event.createdAt, order: 0, sourceOrder: event.sequence, label: event.title, evidence: { kind: event.kind, payload: event.payload } });
+    for (const checkpoint of run.checkpoints)
+        entries.push({ id: checkpoint.id, type: 'checkpoint', timestamp: checkpoint.createdAt, order: 0, sourceOrder: checkpoint.sequence, label: `Checkpoint: ${checkpoint.label}`, evidence: { checkpointId: checkpoint.id, sequence: checkpoint.sequence, state: checkpoint.state } });
+    for (const approval of run.approvals)
+        entries.push({ id: approval.id, type: 'approval', timestamp: approval.resolvedAt ?? approval.requestedAt, order: 0, sourceOrder: 0, label: `Approval ${approval.status}`, evidence: approvalEvidence(approval) });
+    for (const attempt of run.operationAttempts)
+        entries.push({ id: attempt.id, type: 'operation-attempt', timestamp: attempt.completedAt ?? attempt.updatedAt, order: 0, sourceOrder: attempt.attemptSequence, label: `Operation ${attempt.status}: ${attempt.category} ${attempt.operation}`, evidence: attemptEvidence(attempt) });
+    if (run.outcome !== undefined || isTerminal(run.status))
+        entries.push({ id: `${run.id}:outcome`, type: 'outcome', timestamp: run.completedAt ?? latestTimestamp(entries, run.updatedAt), order: 0, sourceOrder: Number.MAX_SAFE_INTEGER, label: `Run ${run.status}`, evidence: { status: run.status, outcome: run.outcome ?? null, outcomeReason: run.outcomeReason ?? null } });
+    return entries
+        .sort((left, right) => left.timestamp.localeCompare(right.timestamp) || typeRank(left.type) - typeRank(right.type) || left.sourceOrder - right.sourceOrder || left.id.localeCompare(right.id))
+        .map(({ sourceOrder: _sourceOrder, ...entry }, order) => ({ ...entry, order }));
+}
+function buildDebugSummary(run) {
+    const evidence = [];
+    if (run.outcomeReason !== undefined)
+        evidence.push({ source: 'outcome', message: run.outcomeReason });
+    for (const attempt of run.operationAttempts.filter((item) => item.status === 'failed')) {
+        evidence.push({ source: 'operation-attempt', relatedId: attempt.id, message: `Failed attempt ${attempt.category} ${attempt.operation}: ${readErrorMessage(attempt.error)}` });
+    }
+    if (run.operationAttempts.some((attempt) => attempt.status === 'failed'))
+        return { cause: 'operation-failed', summary: 'A recorded operation attempt failed. Treat this as the likely cause, not proof of root cause.', evidence, recommendedAction: 'Inspect the failed operation evidence, fix the underlying issue, then consider a manual restart from the latest safe checkpoint.' };
+    if (run.approvals.some((approval) => approval.status === 'pending'))
+        return { cause: 'pending-approval', summary: 'The run is waiting on recorded human approval.', evidence: pendingApprovalEvidence(run), recommendedAction: 'Resolve the pending approval or inspect debug details before retrying.' };
+    if (run.status === 'blocked')
+        return { cause: 'blocked', summary: 'The run is blocked by recorded status or outcome evidence.', evidence: evidence.length === 0 ? [{ source: 'status', message: 'Run status is blocked' }] : evidence, recommendedAction: 'Inspect blockers and resolve the recorded constraint before starting another run.' };
+    if (run.status === 'completed')
+        return { cause: 'completed', summary: 'The run completed successfully.', evidence: evidence.length === 0 ? [{ source: 'status', message: 'Run status is completed' }] : evidence, recommendedAction: 'No resume action is recommended for a completed run.' };
+    if (!isTerminal(run.status))
+        return { cause: 'still-running', summary: 'The run has not reached a terminal outcome yet.', evidence: [{ source: 'status', message: `Run status is ${run.status}` }], recommendedAction: 'Wait for the run to finish or inspect live run events.' };
+    return { cause: 'insufficient-evidence', summary: 'The run stopped without enough recorded evidence to classify a cause.', evidence, recommendedAction: 'Inspect the timeline and raw recorded details before deciding on a manual restart.' };
+}
+function buildResumePlan(run) {
+    const latestCheckpoint = findLatestCheckpoint(run);
+    const blockers = [];
+    if (latestCheckpoint === undefined)
+        blockers.push({ code: 'no-checkpoint', message: 'No recorded checkpoint is available for manual resume consideration.' });
+    for (const approval of run.approvals.filter((item) => item.status === 'pending'))
+        blockers.push({ code: 'pending-approval', message: 'A pending approval must be resolved first.', relatedId: approval.id });
+    for (const attempt of run.operationAttempts.filter((item) => item.status === 'reserved'))
+        blockers.push({ code: 'active-attempt', message: 'An active reserved operation attempt is already in progress.', relatedId: attempt.id });
+    if (!isTerminal(run.status))
+        blockers.push({ code: 'run-still-active', message: `Run status is ${run.status}; wait for a stopped state before resume planning.` });
+    if (run.status === 'completed')
+        blockers.push({ code: 'already-completed', message: 'Completed runs do not need resume.' });
+    if (run.status === 'blocked')
+        blockers.push({ code: 'blocked-run', message: 'Blocked runs require inspection before manual resume consideration.' });
+    const plan = { resumable: blockers.length === 0, executable: false, blockers, recommendedAction: blockers.length === 0 ? 'Review the latest safe checkpoint and manually decide whether to start a new run from that state.' : 'Resolve blockers or inspect debug details before considering a manual restart.' };
+    if (latestCheckpoint !== undefined)
+        plan.latestCheckpoint = { id: latestCheckpoint.id, label: latestCheckpoint.label, sequence: latestCheckpoint.sequence, createdAt: latestCheckpoint.createdAt, state: latestCheckpoint.state };
+    return plan;
+}
+function findLatestCheckpoint(run) {
+    const byId = run.latestCheckpointId === undefined ? undefined : run.checkpoints.find((checkpoint) => checkpoint.id === run.latestCheckpointId);
+    return byId ?? [...run.checkpoints].sort((left, right) => right.sequence - left.sequence || right.createdAt.localeCompare(left.createdAt))[0];
+}
+function approvalEvidence(approval) {
+    return { approvalId: approval.id, status: approval.status, decisionEventId: approval.decisionEventId, resolvedBy: approval.resolvedBy ?? null, resolutionReason: approval.resolutionReason ?? null };
+}
+function attemptEvidence(attempt) {
+    return { attemptId: attempt.id, status: attempt.status, category: attempt.category, operation: attempt.operation, operationMetadata: attempt.operationMetadata, output: attempt.output ?? null, error: attempt.error ?? null };
+}
+function pendingApprovalEvidence(run) {
+    return run.approvals.filter((approval) => approval.status === 'pending').map((approval) => ({ source: 'approval', relatedId: approval.id, message: 'Approval is pending' }));
+}
+function buildManualNextCommands(runId, checkpointId, pendingApprovals) {
+    return [
+        `vgxness runs get --id ${runId}`,
+        `vgxness runs timeline --id ${runId}`,
+        `vgxness runs debug --id ${runId}`,
+        `vgxness runs resume-plan --id ${runId}`,
+        ...manualApprovalCommands(runId, pendingApprovals),
+        checkpointId === undefined
+            ? 'No checkpoint is recorded; inspect the run details before deciding on manual recovery.'
+            : `Review checkpoint ${checkpointId} manually before starting any new run.`,
+    ];
+}
+function manualApprovalCommands(runId, pendingApprovals) {
+    if (pendingApprovals.length === 0)
+        return [];
+    return [`vgxness runs approvals --run ${runId}`, ...pendingApprovals.map((approval) => `vgxness runs retry-check --approval ${approval.id}`)];
+}
+function buildEvidenceReferences(runId, checkpointId, pendingApprovals, activeAttempts, failedAttempts, debug) {
+    return [
+        `run:${runId}`,
+        ...(checkpointId === undefined ? [] : [`checkpoint:${checkpointId}`]),
+        ...pendingApprovals.map((approval) => `approval:${approval.id}`),
+        ...activeAttempts.map((attempt) => `attempt:${attempt.id}`),
+        ...failedAttempts.map((attempt) => `attempt:${attempt.id}`),
+        ...debug.evidence.map((item) => `debug:${item.relatedId ?? item.message}`),
+    ];
+}
+function readErrorMessage(error) {
+    return typeof error === 'object' && error !== null && !Array.isArray(error) && typeof error.message === 'string' ? error.message : 'recorded error unavailable';
+}
+function isTerminal(status) {
+    return status === 'completed' || status === 'failed' || status === 'blocked' || status === 'cancelled';
+}
+function typeRank(type) {
+    return ['run-created', 'checkpoint', 'approval', 'operation-attempt', 'event', 'outcome'].indexOf(type);
+}
+function latestTimestamp(entries, fallback) {
+    return entries.reduce((latest, entry) => entry.timestamp > latest ? entry.timestamp : latest, fallback);
+}