@mingchuno/agent-workflows 0.4.0 → 0.5.0

package/dist/src/recovery.d.ts

@@ -2,6 +2,11 @@ import type { Project } from "./config.js";
 import { type HostingAdapter, type RunRecord, type Workspace } from "./domain.js";
 import type { Store } from "./store.js";
 export declare const publicationSteps: readonly string[];
+interface WorkflowStep {
+    functionID: number;
+    name?: string;
+    error?: unknown;
+}
 export declare function recoveryUnavailable(run: RunRecord): string | undefined;
 /** Hash execution inputs without reading credential environment values. */
 export declare function executionFingerprint(project: Project, workflowVersion: string, signal?: AbortSignal): Promise<string>;
@@ -14,6 +19,19 @@ interface RecoveryDependencies {
     workflowVersion: string;
     signal?: AbortSignal;
 }
-/** Read-only checks shared by admission and the first non-replayed operation. */
-export declare function verifyPublicationRecovery(run: RunRecord, dependencies: RecoveryDependencies): Promise<void>;
+/** Verify checkpoint history and live state before persisting recovery intent. */
+export declare function verifyPublicationRecoveryAdmission(run: RunRecord, checkpoints: {
+    status: {
+        status: string;
+        applicationVersion?: string;
+    } | null | undefined;
+    steps: readonly WorkflowStep[] | undefined;
+    applicationVersion: string;
+}, dependencies: RecoveryDependencies): Promise<string[]>;
+interface RecoveryStartDependencies extends RecoveryDependencies {
+    store: Pick<Store, "invocations" | "project" | "patchRun">;
+    signal: AbortSignal;
+}
+/** Revalidate a recovered Execution at its first non-replayed step. */
+export declare function resumePublicationExecution(run: RunRecord, workflowId: string, stepId: number, dependencies: RecoveryStartDependencies): Promise<void>;
 export {};

package/dist/src/recovery.js

@@ -6,11 +6,38 @@ import { verifyEvidence } from "./evidence.js";
 import { projectPrompts } from "./prompts.js";
 import { assertProcessesStopped } from "./runtime/ownership.js";
 import { command } from "./runtime/process.js";
+const recoveryGatePollIntervalMs = 100;
 export const publicationSteps = [
     "push",
     "change-request",
     "review-publication",
 ];
+/** Prove that a fork will replay only completed publication checkpoints. */
+function completedPublicationCheckpoints(run, status, steps, applicationVersion) {
+    if (!status || !["SUCCESS", "ERROR"].includes(status.status))
+        throw new Error("Source execution has not finished");
+    if (status.applicationVersion !== applicationVersion)
+        throw new Error("Workflow version changed; use retry");
+    const failed = steps?.find((step) => step.functionID === run.executions?.at(-1)?.failedStep);
+    if (!failed?.error || failed.name !== run.phase)
+        throw new Error("Failed publication checkpoint is unavailable");
+    const prefix = steps.filter((step) => step.functionID < failed.functionID);
+    if (prefix.length !== failed.functionID ||
+        prefix.some((step, index) => step.error || step.functionID !== index) ||
+        !prefix.some((step) => step.name === "commit"))
+        throw new Error("Completed publication checkpoints are unavailable");
+    return prefix.map((step) => step.name);
+}
+/** Check the identity of the first step that DBOS did not replay. */
+function verifyPublicationExecutionStart(run, workflowId, stepId) {
+    const execution = run.executions?.at(-1);
+    if (!execution?.recoveryOf)
+        return;
+    if (execution.id !== workflowId)
+        throw new BlockedError("Execution has been superseded");
+    if (stepId < execution.startStep)
+        throw new BlockedError("A reused checkpoint is missing; recovery refused");
+}
 export function recoveryUnavailable(run) {
     if (run.outcome !== "failed")
         return "Only failed publication runs can be recovered";
@@ -47,8 +74,29 @@ export async function executionFingerprint(project, workflowVersion, signal) {
     }))
         .digest("hex");
 }
+/** Verify checkpoint history and live state before persisting recovery intent. */
+export async function verifyPublicationRecoveryAdmission(run, checkpoints, dependencies) {
+    const completedSteps = completedPublicationCheckpoints(run, checkpoints.status, checkpoints.steps, checkpoints.applicationVersion);
+    await verifyPublicationRecovery(run, dependencies);
+    return completedSteps;
+}
+/** Revalidate a recovered Execution at its first non-replayed step. */
+export async function resumePublicationExecution(run, workflowId, stepId, dependencies) {
+    verifyPublicationExecutionStart(run, workflowId, stepId);
+    while (true) {
+        dependencies.signal.throwIfAborted();
+        const state = await dependencies.store.project(dependencies.project.id);
+        if (state.blocked)
+            throw new BlockedError(state.blocked);
+        if (!state.paused)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, recoveryGatePollIntervalMs));
+    }
+    await dependencies.store.patchRun(run.id, { outcome: "running" });
+    await verifyPublicationRecovery(run, dependencies);
+}
 /** Read-only checks shared by admission and the first non-replayed operation. */
-export async function verifyPublicationRecovery(run, dependencies) {
+async function verifyPublicationRecovery(run, dependencies) {
     const { project, workspace, hosting, store, stateDirectory, workflowVersion, signal, } = dependencies;
     if (run.checkout !== project.checkout)
         throw new BlockedError("Configured checkout differs from the recorded run checkout");

package/dist/src/runner.d.ts

@@ -43,12 +43,16 @@ export declare class Runner {
     private recordWorkflowFailure;
     private execute;
     private executeOwned;
+    private checkExecutionStart;
+    private recordExecutionFailure;
     pause(projectId: string): Promise<void>;
     private initializeExecution;
     resume(projectId: string): Promise<void>;
     stop(runId: string): Promise<void>;
-    retry(runId: string, commandId?: string): Promise<string>;
+    retry(runId: string, commandId?: string, options?: {
+        refreshIssue?: boolean;
+    }): Promise<string>;
     recover(runId: string, commandId?: string): Promise<string>;
-    private checkRecoveryState;
+    private projectForRun;
     shutdown(): Promise<void>;
 }

package/dist/src/runner.js

@@ -8,11 +8,12 @@ import { BlockedError, isBlockedError, } from "./domain.js";
 import { assertEvidenceDirectory } from "./evidence.js";
 import { defaultWorkflow, Operations } from "./operations.js";
 import { projectPrompts } from "./prompts.js";
-import { executionFingerprint, verifyPublicationRecovery } from "./recovery.js";
+import { executionFingerprint, resumePublicationExecution, verifyPublicationRecoveryAdmission, } from "./recovery.js";
 import { createQueuedRun } from "./run-record.js";
 import { assertProcessesStopped, CheckoutOwnership, } from "./runtime/ownership.js";
 import { createRedactor, runtimeLogger } from "./runtime/redaction.js";
 import { Store } from "./store.js";
+import { selectValidation } from "./validation-selection.js";
 import { ExistingCheckout } from "./workspace.js";
 const runnerPollIntervalMs = 100;
 const shutdownPollIntervalMs = 20;
@@ -180,6 +181,8 @@ export class Runner {
                     await this.stop(request.target);
                 else if (request.kind === "retry")
                     await this.retry(request.target, request.id);
+                else if (request.kind === "retry-refresh")
+                    await this.retry(request.target, request.id, { refreshIssue: true });
                 else if (request.kind === "recover")
                     await this.recover(request.target, request.id);
                 else
@@ -281,9 +284,7 @@ export class Runner {
         const run = await DBOS.runStep(() => this.initializeExecution(runId), {
             name: "load-run",
         });
-        const project = this.config.projects.find((p) => p.id === run.projectId);
-        if (!project)
-            throw new Error("Project removed from configuration");
+        const project = this.projectForRun(run);
         const workspace = this.options.workspace ?? new ExistingCheckout();
         let recoveryChecked = false;
         const operations = new Operations(runId, {
@@ -300,30 +301,7 @@ export class Runner {
             beforeStep: async () => {
                 if (recoveryChecked)
                     return;
-                const current = await this.store.run(runId);
-                const execution = current.executions?.at(-1);
-                if (!execution?.recoveryOf) {
-                    await this.store.patchRun(runId, { outcome: "running" });
-                    recoveryChecked = true;
-                    return;
-                }
-                if (execution.id !== DBOS.workflowID)
-                    throw new BlockedError("Execution has been superseded");
-                if (DBOS.stepID < execution.startStep)
-                    throw new BlockedError("A reused checkpoint is missing; recovery refused");
-                // This runs inside the first non-replayed step, so copied start-gate
-                // checkpoints cannot bypass today's pause or checkout checks.
-                while (true) {
-                    controller.signal.throwIfAborted();
-                    const state = await this.store.project(project.id);
-                    if (state.blocked)
-                        throw new BlockedError(state.blocked);
-                    if (!state.paused)
-                        break;
-                    await new Promise((resolve) => setTimeout(resolve, runnerPollIntervalMs));
-                }
-                await this.store.patchRun(runId, { outcome: "running" });
-                await this.checkRecoveryState(current, project, controller.signal);
+                await this.checkExecutionStart(runId, project, controller.signal);
                 recoveryChecked = true;
             },
         });
@@ -348,31 +326,50 @@ export class Runner {
             }, { name: "terminal-check" });
         }
         catch (error) {
-            await DBOS.runStep(async () => {
-                let unsafe = false;
-                try {
-                    await workspace.check(project);
-                }
-                catch {
-                    unsafe = true;
-                }
-                const outcome = controller.signal.aborted
-                    ? "cancelled"
-                    : isBlockedError(error)
-                        ? "blocked"
-                        : "failed";
-                await this.store.patchRun(runId, {
-                    outcome,
-                    error: this.redact(String(error)),
-                });
-                if (unsafe || isBlockedError(error))
-                    await this.store.blockProject(project.id, `Run ${runId} requires recovery: ${this.redact(String(error))}`);
-            }, { name: "record-failure", retriesAllowed: false });
+            await DBOS.runStep(() => this.recordExecutionFailure(runId, project, workspace, controller, error), { name: "record-failure", retriesAllowed: false });
         }
         finally {
             this.controllers.delete(runId);
         }
     }
+    async checkExecutionStart(runId, project, signal) {
+        const current = await this.store.run(runId);
+        const execution = current.executions?.at(-1);
+        if (!execution?.recoveryOf) {
+            await this.store.patchRun(runId, { outcome: "running" });
+            return;
+        }
+        // The first non-replayed step must check today's pause and checkout state.
+        await resumePublicationExecution(current, DBOS.workflowID, DBOS.stepID, {
+            project,
+            signal,
+            store: this.store,
+            workspace: this.options.workspace ?? new ExistingCheckout(),
+            hosting: this.hosting.get(project.id),
+            stateDirectory: this.config.stateDirectory,
+            workflowVersion: this.options.workflowVersion ?? "phase1-v2",
+        });
+    }
+    async recordExecutionFailure(runId, project, workspace, controller, error) {
+        let unsafe = false;
+        try {
+            await workspace.check(project);
+        }
+        catch {
+            unsafe = true;
+        }
+        const outcome = controller.signal.aborted
+            ? "cancelled"
+            : isBlockedError(error)
+                ? "blocked"
+                : "failed";
+        await this.store.patchRun(runId, {
+            outcome,
+            error: this.redact(String(error)),
+        });
+        if (unsafe || isBlockedError(error))
+            await this.store.blockProject(project.id, `Run ${runId} requires recovery: ${this.redact(String(error))}`);
+    }
     async pause(projectId) {
         await this.store.project(projectId);
         await this.store.setProject(projectId, { paused: true });
@@ -381,9 +378,7 @@ export class Runner {
         const run = await this.store.run(runId);
         if (run.executions?.length)
             return run;
-        const project = this.config.projects.find((item) => item.id === run.projectId);
-        if (!project)
-            throw new Error("Project removed from configuration");
+        this.projectForRun(run);
         return this.store.patchRun(runId, {
             executions: [
                 {
@@ -421,20 +416,33 @@ export class Runner {
         if (run.outcome === "running")
             throw new BlockedError("No local process ownership for this running workflow");
     }
-    async retry(runId, commandId) {
+    async retry(runId, commandId, options = {}) {
         return this.store.admitRetry(runId, {
             commandId,
             checkSafety: async (previous) => {
                 if (this.controllers.has(runId))
                     throw new Error("Work has not stopped");
-                const project = this.config.projects.find((p) => p.id === previous.projectId);
-                if (!project)
-                    throw new Error("Project removed from configuration");
+                const project = this.projectForRun(previous);
                 await assertProcessesStopped(resolve(this.config.stateDirectory, runId));
                 await (this.options.workspace ?? new ExistingCheckout()).check(project);
+                let issue;
+                if (options.refreshIssue) {
+                    const hosting = this.hosting.get(project.id) ?? this.options.hosting(project);
+                    const current = await hosting.getIssue(previous.issue.number);
+                    if (current.id !== previous.issue.id ||
+                        current.number !== previous.issue.number ||
+                        current.url !== previous.issue.url)
+                        throw new Error("Refreshed issue identity differs from the run");
+                    if (!current.open ||
+                        !project.labels.every((label) => current.labels.includes(label)))
+                        throw new Error("Refreshed issue is closed or missing required labels");
+                    selectValidation(current.body, project);
+                    issue = current;
+                }
                 return {
                     checkout: project.checkout,
                     branchTemplate: project.branchTemplate,
+                    issue,
                 };
             },
         });
@@ -449,40 +457,30 @@ export class Runner {
                     throw new Error("Publication recovery currently supports the default workflow only");
                 if (this.controllers.has(runId))
                     throw new Error("Work has not stopped");
-                const project = this.config.projects.find((item) => item.id === run.projectId);
-                if (!project)
-                    throw new Error("Project removed from configuration");
+                const project = this.projectForRun(run);
                 const execution = run.executions.at(-1);
                 const status = await DBOS.getWorkflowStatus(execution.id);
-                if (!status || !["SUCCESS", "ERROR"].includes(status.status))
-                    throw new Error("Source execution has not finished");
-                if (status.applicationVersion !==
-                    `${this.config.id}-${this.options.workflowVersion ?? "phase1-v2"}`)
-                    throw new Error("Workflow version changed; use retry");
                 const steps = await DBOS.listWorkflowSteps(execution.id);
-                const failed = steps?.find((step) => step.functionID === execution.failedStep);
-                if (!failed?.error || failed.name !== run.phase)
-                    throw new Error("Failed publication checkpoint is unavailable");
-                const prefix = steps.filter((step) => step.functionID < failed.functionID);
-                if (prefix.length !== failed.functionID ||
-                    prefix.some((step, index) => step.error || step.functionID !== index) ||
-                    !prefix.some((step) => step.name === "commit"))
-                    throw new Error("Completed publication checkpoints are unavailable");
-                await this.checkRecoveryState(run, project);
-                return prefix.map((step) => step.name);
+                return verifyPublicationRecoveryAdmission(run, {
+                    status,
+                    steps,
+                    applicationVersion: `${this.config.id}-${this.options.workflowVersion ?? "phase1-v2"}`,
+                }, {
+                    project,
+                    store: this.store,
+                    workspace: this.options.workspace ?? new ExistingCheckout(),
+                    hosting: this.hosting.get(project.id),
+                    stateDirectory: this.config.stateDirectory,
+                    workflowVersion: this.options.workflowVersion ?? "phase1-v2",
+                });
             },
         });
     }
-    async checkRecoveryState(run, project, signal) {
-        await verifyPublicationRecovery(run, {
-            project,
-            signal,
-            store: this.store,
-            workspace: this.options.workspace ?? new ExistingCheckout(),
-            hosting: this.hosting.get(project.id),
-            stateDirectory: this.config.stateDirectory,
-            workflowVersion: this.options.workflowVersion ?? "phase1-v2",
-        });
+    projectForRun(run) {
+        const project = this.config.projects.find((item) => item.id === run.projectId);
+        if (!project)
+            throw new Error("Project removed from configuration");
+        return project;
     }
     async shutdown() {
         this.stopping = true;

package/dist/src/runtime/process.d.ts

@@ -10,6 +10,7 @@ export interface CommandOptions {
     captureOutput?: boolean;
     strictUtf8?: boolean;
     onOutput?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
 }
 export interface CommandResult {
     stdout: string;

package/dist/src/runtime/process.js

@@ -64,8 +64,12 @@ export function command(executable, args, options) {
                 const value = decoders[target].decode(chunk, {
                     stream: chunk !== undefined,
                 });
-                if (value)
-                    options.onOutput?.(value);
+                if (value) {
+                    if (target === "stderr" && options.onStderr)
+                        options.onStderr(value);
+                    else
+                        options.onOutput?.(value);
+                }
                 if (options.captureOutput !== false) {
                     if (target === "stdout")
                         stdout += value;

package/dist/src/store.d.ts

@@ -1,5 +1,5 @@
 import { Pool } from "pg";
-import type { RunRecord } from "./domain.js";
+import type { Issue, RunRecord } from "./domain.js";
 export interface EventRecord {
     sequence: number;
     runId: string | null;
@@ -41,6 +41,7 @@ interface RetryAdmission {
     checkSafety: (previous: RunRecord) => Promise<{
         checkout: string;
         branchTemplate: string;
+        issue?: Issue;
     }>;
 }
 interface RecoveryAdmission {
@@ -88,12 +89,13 @@ export declare class Store {
     saveInvocation(record: InvocationRecord): Promise<void>;
     invocations(runId: string): Promise<InvocationRecord[]>;
     emit(runId: string | null, kind: string, payload: unknown): Promise<void>;
+    private event;
     events(after?: number, runId?: string): Promise<EventRecord[]>;
     subscribe(listener: (event: EventRecord) => void, options?: {
         after?: number;
         intervalMs?: number;
     }): () => void;
-    request(kind: "pause" | "resume" | "stop" | "retry" | "recover", target: string): Promise<string>;
+    request(kind: "pause" | "resume" | "stop" | "retry" | "retry-refresh" | "recover", target: string): Promise<string>;
     commands(): Promise<Array<{
         id: string;
         kind: string;

package/dist/src/store.js

@@ -88,41 +88,51 @@ export class Store {
         return state;
     }
     async setProject(id, change) {
-        const { projects } = tables;
-        if (change.paused !== undefined || change.blocked !== undefined) {
-            await this.db
-                .update(projects)
-                .set(change)
-                .where(and(eq(projects.scope, this.scope), eq(projects.id, id)));
-        }
-        await this.emit(null, "project", { id, ...change });
+        await this.db.transaction(async (tx) => {
+            const { projects } = tables;
+            if (change.paused !== undefined || change.blocked !== undefined) {
+                await tx
+                    .update(projects)
+                    .set(change)
+                    .where(and(eq(projects.scope, this.scope), eq(projects.id, id)));
+            }
+            await tx
+                .insert(tables.events)
+                .values(this.event(null, "project", { id, ...change }));
+        });
     }
     async insertRun(run) {
-        const { runs } = tables;
-        const inserted = await this.db
-            .insert(runs)
-            .values({
-            scope: this.scope,
-            id: run.id,
-            taskKey: run.taskKey,
-            attempt: run.attempt,
-            record: redactValue(run, this.redact),
-        })
-            .onConflictDoNothing()
-            .returning({ id: runs.id });
-        if (inserted.length)
-            await this.emit(run.id, "run", run);
-        return inserted.length > 0;
+        return this.db.transaction(async (tx) => {
+            const { runs } = tables;
+            const inserted = await tx
+                .insert(runs)
+                .values({
+                scope: this.scope,
+                id: run.id,
+                taskKey: run.taskKey,
+                attempt: run.attempt,
+                record: redactValue(run, this.redact),
+            })
+                .onConflictDoNothing()
+                .returning({ id: runs.id });
+            if (inserted.length)
+                await tx.insert(tables.events).values(this.event(run.id, "run", run));
+            return inserted.length > 0;
+        });
     }
     async blockProject(id, reason) {
-        const { projects } = tables;
-        const updated = await this.db
-            .update(projects)
-            .set({ blocked: this.redact(reason) })
-            .where(and(eq(projects.scope, this.scope), eq(projects.id, id), isNull(projects.blocked)))
-            .returning({ id: projects.id });
-        if (updated.length)
-            await this.emit(null, "project", { id, blocked: reason });
+        await this.db.transaction(async (tx) => {
+            const { projects } = tables;
+            const updated = await tx
+                .update(projects)
+                .set({ blocked: this.redact(reason) })
+                .where(and(eq(projects.scope, this.scope), eq(projects.id, id), isNull(projects.blocked)))
+                .returning({ id: projects.id });
+            if (updated.length)
+                await tx
+                    .insert(tables.events)
+                    .values(this.event(null, "project", { id, blocked: reason }));
+        });
     }
     /**
      * Admit a retry and its events atomically. Safety checks run under the project
@@ -177,7 +187,7 @@ export class Store {
                 taskKey: previous.taskKey,
                 attempt,
                 retryOf: previous.id,
-                issue: previous.issue,
+                issue: target.issue ?? previous.issue,
                 now,
                 branchTemplate: target.branchTemplate,
             });
@@ -329,7 +339,7 @@ export class Store {
         const { runs } = tables;
         const change = { ...patch, updatedAt: new Date().toISOString() };
         const predicate = and(eq(runs.scope, this.scope), eq(runs.id, id));
-        const record = await this.db.transaction(async (tx) => {
+        return this.db.transaction(async (tx) => {
             // Serialize read/merge/write so concurrent patches cannot lose fields.
             const [row] = await tx
                 .select({ record: runs.record })
@@ -354,27 +364,30 @@ export class Store {
                     execution.finishedAt = change.updatedAt;
             }
             await tx.update(runs).set({ record: merged }).where(predicate);
+            await tx.insert(tables.events).values(this.event(id, "run", change));
             return merged;
         });
-        await this.emit(id, "run", change);
-        return record;
     }
     async saveInvocation(record) {
-        const { invocations } = tables;
-        const persisted = redactValue(record, this.redact);
-        await this.db
-            .insert(invocations)
-            .values({
-            scope: this.scope,
-            id: record.id,
-            runId: record.runId,
-            record: persisted,
-        })
-            .onConflictDoUpdate({
-            target: invocations.id,
-            set: { record: persisted },
+        await this.db.transaction(async (tx) => {
+            const { invocations } = tables;
+            const persisted = redactValue(record, this.redact);
+            await tx
+                .insert(invocations)
+                .values({
+                scope: this.scope,
+                id: record.id,
+                runId: record.runId,
+                record: persisted,
+            })
+                .onConflictDoUpdate({
+                target: invocations.id,
+                set: { record: persisted },
+            });
+            await tx
+                .insert(tables.events)
+                .values(this.event(record.runId, "invocation", record));
         });
-        await this.emit(record.runId, "invocation", record);
     }
     async invocations(runId) {
         const { invocations } = tables;
@@ -387,7 +400,12 @@ export class Store {
             .sort((a, b) => a.startedAt.localeCompare(b.startedAt));
     }
     async emit(runId, kind, payload) {
-        await this.db.insert(tables.events).values({
+        await this.db
+            .insert(tables.events)
+            .values(this.event(runId, kind, payload));
+    }
+    event(runId, kind, payload) {
+        return {
             scope: this.scope,
             runId,
             kind,
@@ -395,7 +413,7 @@ export class Store {
             payload: new SQL([
                 new Param(JSON.stringify(redactValue(payload, this.redact))),
             ]),
-        });
+        };
     }
     async events(after = 0, runId) {
         const { events } = tables;

package/dist/src/tui/data.d.ts

@@ -9,7 +9,7 @@ export interface MonitorSource {
     request: Store["request"];
     commands: Store["commands"];
 }
-export type MonitorAction = "pause" | "resume" | "stop" | "retry" | "recover";
+export type MonitorAction = "pause" | "resume" | "stop" | "retry" | "retry-refresh" | "recover";
 export declare function useMonitorData(source: MonitorSource, selection: {
     projectId?: string;
     runId?: string;

package/dist/src/tui/dialogs.js

@@ -32,6 +32,7 @@ const helpPages = [
             ["p", "Pause or resume project intake"],
             ["s", "Stop selected run"],
             ["r", "Retry as a new run"],
+            ["R", "Retry with the current hosted issue"],
             ["c", "Recover failed publication"],
             ["[ / ]", "Inspect previous or next step event"],
             ["End", "Follow latest step event"],