@mingchuno/agent-workflows 0.1.0 → 0.2.0

package/dist/src/operations.js

@@ -1,10 +1,14 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFile, mkdir, readFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
 import { DBOS } from "@dbos-inc/dbos-sdk";
-import { resolveProfile } from "./config.js";
 import { BlockedError, isBlockedError, publicationSchema, reviewSchema, } from "./domain.js";
+import { captureEvidence, evidenceContext, } from "./evidence.js";
+import { invokeStage } from "./invocation.js";
+import { defaultStagePrompts } from "./prompts.js";
+import { publicationSteps } from "./recovery.js";
 import { command } from "./runtime/process.js";
+const maxStepAttempts = 3;
 /** Reusable durable coding operations. Call from a registered DBOS workflow. */
 export class Operations {
     runId;
@@ -17,10 +21,12 @@ export class Operations {
         return DBOS.runStep(async () => {
             const { store, signal } = this.dependencies;
             signal.throwIfAborted();
+            await this.dependencies.beforeStep?.();
             const run = await store.run(this.runId);
             await store.patchRun(this.runId, { phase: name });
             await store.emit(this.runId, "step", {
                 name,
+                executionId: DBOS.workflowID,
                 stepId: DBOS.stepID,
                 attempt: DBOS.stepStatus?.currentAttempt ?? 1,
                 status: "running",
@@ -31,6 +37,7 @@ export class Operations {
                 const result = await operation(run);
                 await store.emit(this.runId, "step", {
                     name,
+                    executionId: DBOS.workflowID,
                     stepId: DBOS.stepID,
                     attempt: DBOS.stepStatus?.currentAttempt ?? 1,
                     status: "completed",
@@ -38,8 +45,13 @@ export class Operations {
                 return result;
             }
             catch (error) {
+                if (!publicationSteps.includes(name) ||
+                    isBlockedError(error) ||
+                    DBOS.stepStatus?.currentAttempt === maxStepAttempts)
+                    await store.patchRun(this.runId, { failedStep: DBOS.stepID });
                 await store.emit(this.runId, "step", {
                     name,
+                    executionId: DBOS.workflowID,
                     stepId: DBOS.stepID,
                     attempt: DBOS.stepStatus?.currentAttempt ?? 1,
                     status: "failed",
@@ -52,12 +64,8 @@ export class Operations {
             }
         }, {
             name,
-            retriesAllowed: [
-                "push",
-                "change-request",
-                "review-publication",
-            ].includes(name),
-            maxAttempts: 3,
+            retriesAllowed: publicationSteps.includes(name),
+            maxAttempts: maxStepAttempts,
             intervalSeconds: 0.2,
             backoffRate: 2,
             shouldRetry: (error) => !isBlockedError(error),
@@ -75,128 +83,28 @@ export class Operations {
         await this.step("prepare", async (run) => {
             const { workspace, project, store } = this.dependencies;
             const snapshot = await workspace.prepare(project, run.branch, this.dependencies.signal);
+            const execution = run.executions?.at(-1);
+            if (execution?.recoverySupported &&
+                this.dependencies.executionFingerprint)
+                execution.fingerprint = await this.dependencies.executionFingerprint();
             await store.patchRun(run.id, {
                 base: snapshot.head,
                 snapshot,
                 outcome: "running",
+                executions: run.executions,
             });
         });
     }
-    async invoke(name, stage, prompt, readOnly = false) {
-        return this.step(name, async (run) => {
-            const { store, project, agents, signal, workspace, redact } = this.dependencies;
-            const previous = (await store.invocations(run.id)).filter((invocation) => invocation.stepId === DBOS.stepID);
-            if (previous.length) {
-                for (const invocation of previous) {
-                    if (invocation.outcome === "running") {
-                        invocation.outcome = "interrupted";
-                        invocation.finishedAt = new Date().toISOString();
-                        if (!invocation.sessionId)
-                            invocation.sessionState = "unavailable";
-                        await store.saveInvocation(invocation);
-                    }
-                }
-                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);
-            const profile = resolveProfile(project.agent, stage.profile);
-            const adapter = agents[profile.provider];
-            if (!adapter)
-                throw new Error(`Missing agent adapter ${profile.provider}`);
-            const invocationSignal = AbortSignal.any([
-                signal,
-                AbortSignal.timeout(stage.timeoutMs),
-            ]);
-            const effective = await adapter.validate(profile, invocationSignal);
-            const { skills, fullPrompt } = await this.prepareInvocationPrompt(stage, () => prompt(run));
-            const id = randomUUID();
-            const directory = join(this.dependencies.artifacts, run.id);
-            await mkdir(directory, { recursive: true, mode: 0o700 });
-            const record = {
-                id,
-                runId: run.id,
-                projectId: project.id,
-                step: name,
-                stepId: DBOS.stepID,
-                attempt: previous.length + 1,
-                provider: profile.provider,
-                sessionId: null,
-                sessionState: "pending",
-                requested: profile,
-                effective,
-                prompt: redact(fullPrompt),
-                skills: skills.map((skill) => ({
-                    ...skill,
-                    content: redact(skill.content),
-                })),
-                outcome: "running",
-                startedAt: new Date().toISOString(),
-                log: join(directory, `${id}.jsonl`),
-            };
-            await store.saveInvocation(record);
-            try {
-                const output = await adapter.invoke({
-                    id,
-                    runId: run.id,
-                    step: name,
-                    cwd: project.checkout,
-                    prompt: fullPrompt,
-                    profile,
-                    skills: skills.map((skill) => skill.path),
-                    processFile: record.log + ".process.json",
-                    readOnly,
-                    signal: invocationSignal,
-                    timeoutMs: stage.timeoutMs,
-                    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,
-                        });
-                    },
-                });
-                invocationSignal.throwIfAborted();
-                if (readOnly)
-                    await workspace.verify(project, run.snapshot);
-                else
-                    await this.saveImplementationSnapshot(run.id, run.snapshot);
-                record.outcome = "completed";
-                return redact(output);
-            }
-            catch (error) {
-                record.outcome = "failed";
-                throw error;
-            }
-            finally {
-                record.finishedAt = new Date().toISOString();
-                if (!record.sessionId)
-                    record.sessionState = "unavailable";
-                await store.saveInvocation(record);
-            }
-        });
-    }
-    async prepareInvocationPrompt(stage, prompt) {
-        const { project } = this.dependencies;
-        const skills = await Promise.all(stage.skills.map(async (path) => {
-            const absolute = resolve(project.checkout, path);
-            const content = await readFile(absolute, "utf8");
-            return {
-                path: absolute,
-                sha256: createHash("sha256").update(content).digest("hex"),
-                content,
-            };
+    async invoke(name, stage, task) {
+        return this.step(name, (run) => invokeStage({
+            run,
+            name,
+            stage,
+            task,
+            stepId: DBOS.stepID,
+            dependencies: this.dependencies,
+            saveImplementationSnapshot: (runId, expected) => this.saveImplementationSnapshot(runId, expected),
         }));
-        const fullPrompt = [
-            stage.prompt,
-            prompt(),
-            ...skills.map((skill) => `Apply this selected skill (${skill.path}):\n${skill.content}`),
-        ].join("\n\n");
-        return { skills, fullPrompt };
     }
     async saveImplementationSnapshot(runId, expected) {
         const { workspace, project, store } = this.dependencies;
@@ -206,7 +114,10 @@ export class Operations {
         await store.patchRun(runId, { snapshot });
     }
     async implement() {
-        await this.invoke("implementation", this.dependencies.project.stages.implementation, (run) => `Implement the following issue in the current checkout. Do not commit, push, or publish.\n${run.issue.title}\n${run.issue.body}`);
+        await this.invoke("implementation", this.dependencies.project.stages.implementation, {
+            defaultPrompt: defaultStagePrompts.implementation,
+            context: (run) => `Issue: ${JSON.stringify(run.issue)}`,
+        });
     }
     async validate() {
         return this.step("validation", async (run) => {
@@ -266,8 +177,34 @@ export class Operations {
             return true;
         });
     }
+    async prepareEvidence(name, published = false) {
+        return this.step(name, async (run) => {
+            const { project, workspace, artifacts, signal } = this.dependencies;
+            if (!run.snapshot)
+                throw new BlockedError("Missing workspace snapshot");
+            if (published && (!run.base || !run.head))
+                throw new BlockedError("Missing published revisions");
+            await workspace.verify(project, run.snapshot);
+            const evidence = await captureEvidence({
+                project,
+                snapshot: run.snapshot,
+                directory: join(artifacts, run.id, `${name}-${randomUUID()}`),
+                signal,
+                revisions: published ? { base: run.base, head: run.head } : undefined,
+            });
+            await workspace.verify(project, run.snapshot);
+            return evidence;
+        });
+    }
     async writePublication() {
-        const output = await this.invoke("writing", this.dependencies.project.stages.writing, (run) => `Return ONLY JSON with commitMessage, title, description (all nonempty strings). Describe actual changes and exact validation; do not claim unrun checks. Do not modify files.\nIssue: ${JSON.stringify(run.issue)}\nDiff: ${run.snapshot?.diff}\nValidation: ${JSON.stringify(run.validation ?? [])}`, true);
+        const evidence = await this.prepareEvidence("publication-input");
+        const output = await this.invoke("publication", this.dependencies.project.stages.publication, {
+            defaultPrompt: defaultStagePrompts.publication,
+            readOnly: true,
+            outputContract: publicationSchema,
+            evidence,
+            context: (run) => `${evidenceContext(evidence)}\nIssue: ${JSON.stringify(run.issue)}\nValidation: ${JSON.stringify(run.validation ?? [])}`,
+        });
         await this.step("publication-content", async (run) => {
             await this.dependencies.store.patchRun(run.id, {
                 publication: publicationSchema.parse(JSON.parse(output)),
@@ -314,19 +251,22 @@ export class Operations {
         });
     }
     async review() {
-        const diff = await this.step("review-input", async (run) => {
-            if (!run.base || !run.head)
-                throw new Error("Missing published revision");
-            return (await command("git", ["diff", "--no-ext-diff", run.base, run.head], {
-                cwd: this.dependencies.project.checkout,
-            })).stdout;
+        const evidence = await this.prepareEvidence("review-input", true);
+        const output = await this.invoke("review", this.dependencies.project.stages.review, {
+            defaultPrompt: defaultStagePrompts.review,
+            readOnly: true,
+            outputContract: reviewSchema,
+            evidence,
+            context: (run) => `${evidenceContext(evidence)}\nIssue: ${JSON.stringify(run.issue)}\nValidation: ${JSON.stringify(run.validation ?? [])}\nSet complete=false with limitations if any required evidence cannot be inspected. Never report an incomplete review as clean. Use null for finding path/line where no valid added-line location exists.`,
         });
-        const output = await this.invoke("review", this.dependencies.project.stages.review, (run) => `Independently review this published revision without editing files. Return ONLY JSON {"summary":"...","findings":[{"body":"...","path":"optional relative path","line":1}]}. Omit path/line where no valid added-line location exists.\nIssue: ${JSON.stringify(run.issue)}\nExact head: ${run.head}\nValidation: ${JSON.stringify(run.validation ?? [])}\nPublished diff:\n${diff}`, true);
         await this.step("review-content", async (run) => {
+            const review = reviewSchema.parse(JSON.parse(output));
             await this.dependencies.store.patchRun(run.id, {
-                review: reviewSchema.parse(JSON.parse(output)),
+                review,
                 reviewHead: run.head,
             });
+            if (!review.complete)
+                throw new BlockedError("Incomplete review; partial findings and limitations retained locally");
         });
     }
     async publishReview() {
@@ -334,6 +274,8 @@ export class Operations {
             const { hosting, project } = this.dependencies;
             if (!run.change || !run.review || !run.reviewHead || !run.base)
                 throw new Error("Missing review");
+            if (run.review.complete !== true)
+                throw new BlockedError("Incomplete or historical review; use retry for a fresh inspection");
             if ((await hosting.head(run.change)) !== run.reviewHead)
                 throw new BlockedError("Review stale: remote head changed");
             const diff = (await command("git", ["diff", "--unified=0", run.base, run.reviewHead], { cwd: project.checkout })).stdout;

package/dist/src/prompts.d.ts

@@ -0,0 +1,28 @@
+import type { Project, Stage } from "./config.js";
+export declare const defaultStagePrompts: {
+    readonly implementation: `Implement the supplied issue in the current checkout. Follow repository
+instructions and existing conventions. Keep changes focused on the issue's
+requirements, and add or update tests where needed to verify the behavior.`;
+    readonly publication: `Prepare a Git commit message and a pull request or merge request title and
+description for the supplied changes. Follow repository conventions. Describe
+what changed and why, summarize the recorded validation accurately, and state
+material limitations. Do not claim checks passed unless the supplied evidence
+shows they ran and passed.`;
+    readonly review: `Independently review the supplied published changes against the issue's
+requirements and repository conventions. Inspect the change artifacts and
+relevant source for correctness, regressions, and missing validation. Report
+actionable findings with supporting locations where possible. State any gaps
+in inspection explicitly; do not present an incomplete review as a clean review.`;
+};
+export interface ResolvedPrompt {
+    source: "default" | "inline" | "file";
+    path?: string;
+    content: string;
+    sha256: string;
+}
+export declare function sha256(content: string | Buffer): string;
+/** Resolve overrides once. Defaults belong to the caller, not the stage name. */
+export declare function resolveStagePrompt(stage: Stage, defaultTask: string, baseDirectory?: string): ResolvedPrompt;
+export declare function projectPrompts(project: Project, baseDirectory?: string): {
+    [k: string]: ResolvedPrompt;
+};

package/dist/src/prompts.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+export const defaultStagePrompts = {
+    implementation: `Implement the supplied issue in the current checkout. Follow repository
+instructions and existing conventions. Keep changes focused on the issue's
+requirements, and add or update tests where needed to verify the behavior.`,
+    publication: `Prepare a Git commit message and a pull request or merge request title and
+description for the supplied changes. Follow repository conventions. Describe
+what changed and why, summarize the recorded validation accurately, and state
+material limitations. Do not claim checks passed unless the supplied evidence
+shows they ran and passed.`,
+    review: `Independently review the supplied published changes against the issue's
+requirements and repository conventions. Inspect the change artifacts and
+relevant source for correctness, regressions, and missing validation. Report
+actionable findings with supporting locations where possible. State any gaps
+in inspection explicitly; do not present an incomplete review as a clean review.`,
+};
+export function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+const overrides = new WeakMap();
+/** Resolve overrides once. Defaults belong to the caller, not the stage name. */
+export function resolveStagePrompt(stage, defaultTask, baseDirectory) {
+    const cached = overrides.get(stage);
+    if (cached)
+        return cached;
+    if (stage.prompt !== undefined && stage.promptFile !== undefined)
+        throw new Error("Specify either prompt or promptFile, never both");
+    let content = stage.prompt ?? defaultTask;
+    let path;
+    if (stage.promptFile !== undefined) {
+        if (!isAbsolute(stage.promptFile) && !baseDirectory)
+            throw new Error("Relative promptFile requires an explicit base directory");
+        path = resolve(baseDirectory ?? "/", stage.promptFile);
+        try {
+            content = new TextDecoder("utf-8", {
+                fatal: true,
+                ignoreBOM: true,
+            }).decode(readFileSync(path));
+        }
+        catch (cause) {
+            throw new Error(`Cannot read UTF-8 promptFile ${path}`, { cause });
+        }
+    }
+    if (!content.trim())
+        throw new Error(`Stage prompt must be nonblank${path ? `: ${path}` : ""}`);
+    const result = {
+        source: path ? "file" : stage.prompt !== undefined ? "inline" : "default",
+        ...(path ? { path } : {}),
+        content,
+        sha256: sha256(content),
+    };
+    if (result.source === "file")
+        overrides.set(stage, result);
+    return result;
+}
+export function projectPrompts(project, baseDirectory) {
+    return Object.fromEntries(Object.entries(defaultStagePrompts).map(([name, task]) => [
+        name,
+        resolveStagePrompt(project.stages[name], task, baseDirectory),
+    ]));
+}

package/dist/src/recovery.d.ts

@@ -0,0 +1,19 @@
+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[];
+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>;
+interface RecoveryDependencies {
+    project: Project;
+    workspace: Workspace;
+    hosting: HostingAdapter;
+    store: Pick<Store, "invocations">;
+    stateDirectory: string;
+    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>;
+export {};

package/dist/src/recovery.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { BlockedError, } from "./domain.js";
+import { verifyEvidence } from "./evidence.js";
+import { projectPrompts } from "./prompts.js";
+import { assertProcessesStopped } from "./runtime/ownership.js";
+import { command } from "./runtime/process.js";
+export const publicationSteps = [
+    "push",
+    "change-request",
+    "review-publication",
+];
+export function recoveryUnavailable(run) {
+    if (run.outcome !== "failed")
+        return "Only failed publication runs can be recovered";
+    if (!publicationSteps.includes(run.phase))
+        return `Recovery does not support ${run.phase}`;
+    const execution = run.executions?.at(-1);
+    if (!execution?.fingerprint || execution.failedStep === undefined)
+        return "Run has no recovery metadata; use retry for a fresh attempt";
+    if (!execution.recoverySupported)
+        return "Publication recovery supports the default workflow only";
+    if (!run.head || !run.base || !run.snapshot || !run.publication)
+        return "Missing committed publication evidence";
+    if (run.phase === "review-publication" &&
+        (!run.change || !run.review || run.reviewHead !== run.head))
+        return "Missing review for the published revision";
+    return undefined;
+}
+/** Hash execution inputs without reading credential environment values. */
+export async function executionFingerprint(project, workflowVersion, signal) {
+    const { pollIntervalMs: _poll, labels: _labels, branchTemplate: _branch, hosting, ...execution } = project;
+    const { tokenEnv: _token, ...destination } = hosting;
+    const prompts = projectPrompts(project);
+    const remote = await command("git", ["remote", "get-url", "--push", "--all", project.remote], { cwd: project.checkout, signal });
+    const fetchRemote = await command("git", ["remote", "get-url", "--all", project.remote], { cwd: project.checkout, signal });
+    return createHash("sha256")
+        .update(JSON.stringify({
+        version: 2,
+        workflowVersion,
+        execution,
+        destination,
+        prompts,
+        remote: remote.stdout,
+        fetchRemote: fetchRemote.stdout,
+    }))
+        .digest("hex");
+}
+/** Read-only checks shared by admission and the first non-replayed operation. */
+export 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");
+    const fingerprint = await executionFingerprint(project, workflowVersion, signal);
+    if (fingerprint !== run.executions?.at(-1)?.fingerprint)
+        throw new BlockedError("Execution configuration or prompts changed; use retry");
+    await assertProcessesStopped(resolve(stateDirectory, run.id));
+    const gitDirectory = (await command("git", ["rev-parse", "--absolute-git-dir"], {
+        cwd: project.checkout,
+        signal,
+    })).stdout.trim();
+    await assertProcessesStopped(resolve(gitDirectory, "agent-workflows-processes"));
+    await workspace.check(project);
+    const snapshot = await workspace.inspect(project);
+    if (snapshot.branch !== run.branch || snapshot.head !== run.head)
+        throw new BlockedError("Recovery requires the original branch and commit");
+    await workspace.verify(project, run.snapshot);
+    await command("git", ["cat-file", "-e", `${run.base}^{commit}`], {
+        cwd: project.checkout,
+        signal,
+    });
+    const invocations = await store.invocations(run.id);
+    for (const invocation of invocations) {
+        if (invocation.evidence)
+            await verifyEvidence(invocation.evidence);
+    }
+    for (const path of [
+        ...invocations.map((item) => item.log),
+        ...(run.validation ?? []).map((item) => item.log),
+    ]) {
+        try {
+            await access(path);
+        }
+        catch {
+            throw new BlockedError(`Recovery artifact unavailable: ${path}`);
+        }
+    }
+    const remote = (await command("git", ["ls-remote", "--heads", project.remote, `refs/heads/${run.branch}`], { cwd: project.checkout, signal })).stdout.trim();
+    if ((remote && remote.split(/\s/)[0] !== run.head) ||
+        (!remote && run.phase !== "push"))
+        throw new BlockedError("Published remote revision changed; recovery refused");
+    const change = await hosting.findChange(run.branch);
+    if (change && change.head !== run.head)
+        throw new BlockedError("Existing change request has a different head");
+    if (run.phase === "review-publication" &&
+        (!run.change || (await hosting.head(run.change)) !== run.reviewHead))
+        throw new BlockedError("Review stale: remote head changed");
+}

package/dist/src/runner.d.ts

@@ -3,6 +3,7 @@ import { type AgentAdapter, type HostingAdapter, type Workspace } from "./domain
 import { Operations } from "./operations.js";
 import { Store } from "./store.js";
 export interface RunnerOptions {
+    promptBaseDirectory?: string;
     config: Configuration;
     databaseUrl: string;
     hosting: (project: Project) => HostingAdapter;
@@ -36,12 +37,16 @@ export declare class Runner {
     private processCommands;
     private pollDueProjects;
     private dispatchRuns;
+    private dispatch;
     private recordWorkflowFailure;
     private execute;
     private executeOwned;
     pause(projectId: string): Promise<void>;
+    private initializeExecution;
     resume(projectId: string): Promise<void>;
     stop(runId: string): Promise<void>;
     retry(runId: string, commandId?: string): Promise<string>;
+    recover(runId: string, commandId?: string): Promise<string>;
+    private checkRecoveryState;
     shutdown(): Promise<void>;
 }