@mingchuno/agent-workflows 0.3.0 → 0.5.0

package/dist/src/invocation.js

@@ -8,8 +8,46 @@ import { verifyEvidence } from "./evidence.js";
 import { resolveStagePrompt, sha256 } from "./prompts.js";
 const maxInvocationAttempts = 2;
 /** One logical stage; only returned format errors admit a second response attempt. */
-export async function invokeStage({ run, name, stage, task, stepId, dependencies, saveImplementationSnapshot, acceptContribution, }) {
-    const { store, project, agents, signal, workspace, redact } = dependencies;
+export async function invokeStage(execution) {
+    const { run, name, stepId, dependencies } = execution;
+    const directory = join(dependencies.artifacts, run.id);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, `stage-${name}-${stepId}.log`);
+    const executionId = run.executions?.at(-1)?.id ?? run.id;
+    await dependencies.store.patchRun(run.id, {
+        stageLogs: [
+            ...(run.stageLogs ?? []).filter((item) => item.executionId !== executionId || item.step !== name),
+            { executionId, step: name, path },
+        ],
+    });
+    const note = (message) => appendFile(path, `${new Date().toISOString()} ${dependencies.redact(message)}\n`, { mode: 0o600 });
+    try {
+        await note(`Preparing ${name} agent stage`);
+        const prepared = await prepareStage(execution, note);
+        await note(`Agent preflight passed: ${prepared.profile.provider}`);
+        let attempt = { number: 1, correction: "" };
+        while (attempt.number <= maxInvocationAttempts) {
+            await note(`Starting invocation ${attempt.number}`);
+            const result = await invokeAttempt(execution, prepared, attempt);
+            if (result.kind === "completed") {
+                await note(`${name} agent stage completed`);
+                return result.output;
+            }
+            attempt = {
+                number: attempt.number + 1,
+                correction: result.correction,
+                contribution: result.contribution,
+            };
+        }
+        throw new Error("Format correction exhausted");
+    }
+    catch (error) {
+        await note(`Failed: ${String(error)}`);
+        throw error;
+    }
+}
+async function refusePreviousInvocations(execution) {
+    const { run, name, stepId, dependencies: { store }, } = execution;
     const previous = (await store.invocations(run.id)).filter((item) => item.stepId === stepId);
     if (previous.length) {
         for (const record of previous) {
@@ -23,11 +61,10 @@ export async function invokeStage({ run, name, stage, task, stepId, dependencies
         }
         throw new BlockedError(`Interrupted agent stage ${name}; inspect existing sessions before explicit retry`);
     }
-    if (!run.snapshot)
-        throw new BlockedError("Missing workspace snapshot");
-    await workspace.verify(project, run.snapshot);
-    if (task.evidence)
-        await verifyEvidence(task.evidence);
+}
+function prepareRequest(execution) {
+    const { run, stage, task, dependencies } = execution;
+    const { project } = dependencies;
     const resolved = resolveStagePrompt(stage, task.defaultPrompt, dependencies.promptBaseDirectory);
     const outputSchema = task.outputContract
         ? z.toJSONSchema(task.outputContract)
@@ -44,6 +81,19 @@ export async function invokeStage({ run, name, stage, task, stepId, dependencies
         contract,
     ].join("\n\n");
     const profile = resolveProfile(project.agent, stage.profile);
+    return { resolved, outputSchema, fullPrompt, profile };
+}
+async function prepareStage(execution, note) {
+    const { run, stage, task, dependencies } = execution;
+    const { project, agents, signal, workspace } = dependencies;
+    await refusePreviousInvocations(execution);
+    if (!run.snapshot)
+        throw new BlockedError("Missing workspace snapshot");
+    await workspace.verify(project, run.snapshot);
+    if (task.evidence)
+        await verifyEvidence(task.evidence);
+    const request = prepareRequest(execution);
+    const { profile } = request;
     const adapter = agents[profile.provider];
     if (!adapter)
         throw new Error(`Missing agent adapter ${profile.provider}`);
@@ -52,115 +102,162 @@ export async function invokeStage({ run, name, stage, task, stepId, dependencies
         signal,
         AbortSignal.timeout(stage.timeoutMs),
     ]);
+    await note(`Validating ${profile.provider} agent profile`);
     const effective = await adapter.validate(profile, invocationSignal);
     const directory = join(dependencies.artifacts, run.id);
     await mkdir(directory, { recursive: true, mode: 0o700 });
-    let correction = "";
-    let pendingContribution;
-    for (let attempt = 1; attempt <= maxInvocationAttempts; attempt++) {
+    return {
+        ...request,
+        adapter,
+        effective,
+        deadline,
+        invocationSignal,
+        directory,
+    };
+}
+async function invokeAttempt(execution, prepared, attempt) {
+    const { run, name, task, stepId, dependencies } = execution;
+    const { store, project, workspace, redact } = dependencies;
+    const { profile, effective, resolved, outputSchema, fullPrompt, directory, invocationSignal, } = prepared;
+    invocationSignal.throwIfAborted();
+    const expected = (await store.run(run.id)).snapshot;
+    await workspace.verify(project, expected);
+    if (task.evidence)
+        await verifyEvidence(task.evidence);
+    const id = randomUUID();
+    const prompt = fullPrompt + attempt.correction;
+    const readOnly = task.readOnly === true || attempt.number === maxInvocationAttempts;
+    const record = {
+        id,
+        runId: run.id,
+        projectId: project.id,
+        step: name,
+        stepId,
+        attempt: attempt.number,
+        provider: profile.provider,
+        sessionId: null,
+        sessionState: "pending",
+        requested: profile,
+        effective,
+        prompt: redact(prompt),
+        taskPrompt: { ...resolved, content: redact(resolved.content) },
+        outputContract: outputSchema
+            ? sha256(JSON.stringify(outputSchema))
+            : undefined,
+        evidence: task.evidence,
+        outcome: "running",
+        startedAt: new Date().toISOString(),
+        log: join(directory, `${id}.jsonl`),
+    };
+    await store.saveInvocation(record);
+    try {
+        invocationSignal.throwIfAborted();
+        const output = await invokeProvider(execution, prepared, {
+            record,
+            prompt,
+            readOnly,
+        });
+        await appendFile(record.log, "", { mode: 0o600 });
         invocationSignal.throwIfAborted();
-        const expected = (await store.run(run.id)).snapshot;
-        await workspace.verify(project, expected);
+        let contribution = attempt.contribution;
+        if (readOnly)
+            await workspace.verify(project, expected);
+        else
+            contribution = await saveImplementationSnapshot(run.id, expected, profile.provider, dependencies);
         if (task.evidence)
             await verifyEvidence(task.evidence);
-        const id = randomUUID();
-        const prompt = fullPrompt + correction;
-        const readOnly = task.readOnly === true || attempt === maxInvocationAttempts;
-        const record = {
-            id,
-            runId: run.id,
-            projectId: project.id,
-            step: name,
-            stepId,
-            attempt,
-            provider: profile.provider,
-            sessionId: null,
-            sessionState: "pending",
-            requested: profile,
-            effective,
-            prompt: redact(prompt),
-            taskPrompt: { ...resolved, content: redact(resolved.content) },
-            outputContract: outputSchema
-                ? sha256(JSON.stringify(outputSchema))
-                : undefined,
-            evidence: task.evidence,
-            outcome: "running",
-            startedAt: new Date().toISOString(),
-            log: join(directory, `${id}.jsonl`),
+        invocationSignal.throwIfAborted();
+        const response = validateResponse(output, task.outputContract);
+        if (response.kind === "invalid") {
+            const correction = await recordInvalidResponse(record, output, response.error, redact);
+            return { kind: "correction", correction, contribution };
+        }
+        if (contribution)
+            await acceptContribution(run.id, contribution, dependencies);
+        record.outcome = "completed";
+        return {
+            kind: "completed",
+            output: redact(task.outputContract ? JSON.stringify(response.parsed) : output),
         };
+    }
+    catch (error) {
+        if (record.outcome === "running")
+            record.outcome = "failed";
+        throw error;
+    }
+    finally {
+        record.finishedAt = new Date().toISOString();
+        if (!record.sessionId)
+            record.sessionState = "unavailable";
         await store.saveInvocation(record);
-        try {
-            invocationSignal.throwIfAborted();
-            const output = await adapter.invoke({
-                id,
-                runId: run.id,
-                step: name,
-                cwd: project.checkout,
-                prompt,
-                profile,
-                outputSchema,
-                processFile: record.log + ".process.json",
-                readOnly,
-                signal: invocationSignal,
-                timeoutMs: Math.max(1, deadline - Date.now()),
-                session: async (sessionId) => {
-                    record.sessionId = sessionId;
-                    record.sessionState = "available";
-                    await store.saveInvocation(record);
-                },
-                event: async (event) => {
-                    await appendFile(record.log, redact(JSON.stringify(event)) + "\n", {
-                        mode: 0o600,
-                    });
-                },
+    }
+}
+async function invokeProvider(execution, prepared, attempt) {
+    const { run, name, dependencies: { project, store, redact }, } = execution;
+    const { adapter, profile, outputSchema, invocationSignal, deadline } = prepared;
+    const { record, prompt, readOnly } = attempt;
+    return adapter.invoke({
+        id: record.id,
+        runId: run.id,
+        step: name,
+        cwd: project.checkout,
+        prompt,
+        profile,
+        outputSchema,
+        processFile: record.log + ".process.json",
+        readOnly,
+        signal: invocationSignal,
+        timeoutMs: Math.max(1, deadline - Date.now()),
+        session: async (sessionId) => {
+            record.sessionId = sessionId;
+            record.sessionState = "available";
+            await store.saveInvocation(record);
+        },
+        event: async (event) => {
+            await appendFile(record.log, redact(JSON.stringify(event)) + "\n", {
+                mode: 0o600,
             });
-            await appendFile(record.log, "", { mode: 0o600 });
-            invocationSignal.throwIfAborted();
-            if (readOnly)
-                await workspace.verify(project, expected);
-            else
-                pendingContribution = await saveImplementationSnapshot(run.id, expected, profile.provider);
-            if (task.evidence)
-                await verifyEvidence(task.evidence);
-            invocationSignal.throwIfAborted();
-            // Only returned output validation failures qualify for correction.
-            let parsed;
-            try {
-                parsed = task.outputContract
-                    ? task.outputContract.parse(JSON.parse(output))
-                    : undefined;
-            }
-            catch (error) {
-                if (!(error instanceof SyntaxError) && !(error instanceof z.ZodError))
-                    throw error;
-                record.outcome = "invalid-output";
-                record.validationError = redact(String(error));
-                await appendFile(record.log, redact(JSON.stringify({
-                    type: "invalid-output",
-                    output,
-                    error: String(error),
-                })) + "\n");
-                if (attempt === maxInvocationAttempts)
-                    throw new Error(`Invalid output after one correction: ${String(error)}`);
-                correction = `\n\nCorrect the prior response format in this fresh inspection-only session. Do not modify files.\nPrior invalid response:\n${output}\nValidation errors:\n${String(error)}`;
-                continue;
-            }
-            if (pendingContribution)
-                await acceptContribution(run.id, pendingContribution);
-            record.outcome = "completed";
-            return redact(task.outputContract ? JSON.stringify(parsed) : output);
-        }
-        catch (error) {
-            if (record.outcome === "running")
-                record.outcome = "failed";
+        },
+    });
+}
+/** Only returned output validation failures qualify for correction. */
+function validateResponse(output, contract) {
+    let parsed;
+    try {
+        parsed = contract ? contract.parse(JSON.parse(output)) : undefined;
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError) && !(error instanceof z.ZodError))
             throw error;
-        }
-        finally {
-            record.finishedAt = new Date().toISOString();
-            if (!record.sessionId)
-                record.sessionState = "unavailable";
-            await store.saveInvocation(record);
-        }
+        return { kind: "invalid", error };
     }
-    throw new Error("Format correction exhausted");
+    return { kind: "valid", parsed };
+}
+async function recordInvalidResponse(record, output, error, redact) {
+    record.outcome = "invalid-output";
+    record.validationError = redact(String(error));
+    await appendFile(record.log, redact(JSON.stringify({ type: "invalid-output", output, error: String(error) })) + "\n");
+    if (record.attempt === maxInvocationAttempts)
+        throw new Error(`Invalid output after one correction: ${String(error)}`);
+    return `\n\nCorrect the prior response format in this fresh inspection-only session. Do not modify files.\nPrior invalid response:\n${output}\nValidation errors:\n${String(error)}`;
+}
+async function saveImplementationSnapshot(runId, expected, provider, dependencies) {
+    const { workspace, project, store } = dependencies;
+    const snapshot = await workspace.inspect(project);
+    if (snapshot.head !== expected.head || snapshot.branch !== expected.branch)
+        throw new BlockedError("Agent changed branch or committed unexpectedly");
+    await store.patchRun(runId, { snapshot });
+    return snapshot.fingerprint === expected.fingerprint
+        ? undefined
+        : {
+            provider,
+            beforeFiles: expected.files,
+            afterFiles: snapshot.files,
+        };
+}
+async function acceptContribution(runId, candidate, dependencies) {
+    const run = await dependencies.store.run(runId);
+    await dependencies.store.patchRun(runId, {
+        contributionCandidates: [...(run.contributionCandidates ?? []), candidate],
+    });
 }

package/dist/src/operations.d.ts

@@ -25,10 +25,9 @@ export declare class Operations {
     eligible(): Promise<boolean>;
     prepare(): Promise<void>;
     invoke(name: string, stage: Stage, task: InvocationTask): Promise<string>;
-    private saveImplementationSnapshot;
-    private acceptContribution;
     implement(): Promise<void>;
     validate(): Promise<boolean>;
+    private recordValidation;
     private prepareEvidence;
     writePublication(): Promise<void>;
     commit(): Promise<void>;

package/dist/src/operations.js

@@ -9,6 +9,7 @@ import { invokeStage } from "./invocation.js";
 import { defaultStagePrompts } from "./prompts.js";
 import { publicationSteps } from "./recovery.js";
 import { command } from "./runtime/process.js";
+import { selectValidation } from "./validation-selection.js";
 const maxStepAttempts = 3;
 /** Reusable durable coding operations. Call from a registered DBOS workflow. */
 export class Operations {
@@ -76,8 +77,14 @@ export class Operations {
         return this.step("eligibility", async (run) => {
             const { hosting, project } = this.dependencies;
             const issue = await hosting.getIssue(run.issue.number);
-            return (issue.open &&
-                project.labels.every((label) => issue.labels.includes(label)));
+            if (!issue.open ||
+                !project.labels.every((label) => issue.labels.includes(label)))
+                return false;
+            const { profile } = selectValidation(run.issue.body, project);
+            await this.dependencies.store.patchRun(run.id, {
+                validationProfile: profile,
+            });
+            return true;
         });
     }
     async prepare() {
@@ -104,33 +111,8 @@ export class Operations {
             task,
             stepId: DBOS.stepID,
             dependencies: this.dependencies,
-            saveImplementationSnapshot: (runId, expected, provider) => this.saveImplementationSnapshot(runId, expected, provider),
-            acceptContribution: (runId, candidate) => this.acceptContribution(runId, candidate),
         }));
     }
-    async saveImplementationSnapshot(runId, expected, provider) {
-        const { workspace, project, store } = this.dependencies;
-        const snapshot = await workspace.inspect(project);
-        if (snapshot.head !== expected.head || snapshot.branch !== expected.branch)
-            throw new BlockedError("Agent changed branch or committed unexpectedly");
-        await store.patchRun(runId, { snapshot });
-        return snapshot.fingerprint === expected.fingerprint
-            ? undefined
-            : {
-                provider,
-                beforeFiles: expected.files,
-                afterFiles: snapshot.files,
-            };
-    }
-    async acceptContribution(runId, candidate) {
-        const run = await this.dependencies.store.run(runId);
-        await this.dependencies.store.patchRun(runId, {
-            contributionCandidates: [
-                ...(run.contributionCandidates ?? []),
-                candidate,
-            ],
-        });
-    }
     async implement() {
         await this.invoke("implementation", this.dependencies.project.stages.implementation, {
             defaultPrompt: defaultStagePrompts.implementation,
@@ -139,7 +121,7 @@ export class Operations {
     }
     async validate() {
         return this.step("validation", async (run) => {
-            const { project, workspace, store, signal, redact } = this.dependencies;
+            const { project, workspace, signal, redact } = this.dependencies;
             if (!run.snapshot)
                 throw new BlockedError("Missing implementation snapshot");
             await workspace.verify(project, run.snapshot);
@@ -148,7 +130,8 @@ export class Operations {
             const validation = [];
             const directory = join(this.dependencies.artifacts, run.id);
             await mkdir(directory, { recursive: true, mode: 0o700 });
-            for (const [index, check] of project.validation.entries()) {
+            const checks = selectValidation(run.issue.body, project).commands;
+            for (const [index, check] of checks.entries()) {
                 const startedAt = new Date().toISOString();
                 const log = join(directory, `validation-${index}.log`);
                 let captured = "";
@@ -169,25 +152,23 @@ export class Operations {
                     await appendFile(log, redact(captured + "\n" + String(error)), {
                         mode: 0o600,
                     });
-                    validation.push({
+                    await this.recordValidation(run.id, validation, {
                         ...check,
                         exitCode: -1,
                         log,
                         startedAt,
                         finishedAt: new Date().toISOString(),
                     });
-                    await store.patchRun(run.id, { validation });
                     throw error;
                 }
                 await appendFile(log, redact(captured), { mode: 0o600 });
-                validation.push({
+                await this.recordValidation(run.id, validation, {
                     ...check,
                     exitCode: result.exitCode,
                     log,
                     startedAt,
                     finishedAt: new Date().toISOString(),
                 });
-                await store.patchRun(run.id, { validation });
                 if (result.exitCode !== 0)
                     throw new Error(`Validation failed: ${check.command} (exit ${result.exitCode})`);
             }
@@ -195,6 +176,10 @@ export class Operations {
             return true;
         });
     }
+    async recordValidation(runId, validation, result) {
+        validation.push(result);
+        await this.dependencies.store.patchRun(runId, { validation });
+    }
     async prepareEvidence(name, published = false) {
         return this.step(name, async (run) => {
             const { project, workspace, artifacts, signal } = this.dependencies;

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>;
 }