@mingchuno/agent-workflows 0.1.0 → 0.2.0

package/dist/src/domain.js

@@ -4,13 +4,20 @@ export const publicationSchema = z.strictObject({
     title: z.string().trim().min(1).max(240),
     description: z.string().trim().min(1).max(60000),
 });
-export const reviewSchema = z.strictObject({
+export const reviewSchema = z
+    .strictObject({
+    complete: z.boolean(),
+    limitations: z.array(z.string().trim().min(1)),
     summary: z.string().min(1),
     findings: z.array(z.strictObject({
         body: z.string().min(1),
-        path: z.string().optional(),
-        line: z.number().int().positive().optional(),
+        path: z.string().nullable().default(null),
+        line: z.number().int().positive().nullable().default(null),
     })),
+})
+    .refine((review) => review.complete || review.limitations.length > 0, {
+    message: "Incomplete review requires at least one inspection limitation",
+    path: ["limitations"],
 });
 export class BlockedError extends Error {
     constructor(message) {

package/dist/src/evidence.d.ts

@@ -0,0 +1,54 @@
+import type { Project } from "./config.js";
+import { type Snapshot } from "./domain.js";
+export declare const evidenceLimits: {
+    readonly chunkBytes: number;
+    readonly totalBytes: number;
+};
+interface Artifact {
+    path: string;
+    sha256: string;
+    bytes: number;
+}
+export interface ChangeEvidence {
+    index: string;
+    identity: string;
+    files: Artifact[];
+    changedPaths: number;
+    base: string;
+    head?: string;
+    snapshot?: string;
+}
+/** Split even single long lines, preserving UTF-8 and exact reconstruction. */
+export declare function chunkText(text: string): string[];
+export declare class EvidenceWriter {
+    readonly directory: string;
+    readonly files: Artifact[];
+    private bytes;
+    constructor(directory: string);
+    write(name: string, content: string): Promise<Artifact>;
+    index(contents: string, metadata: Record<string, unknown>): Promise<Artifact>;
+    chunks(prefix: string, content: string): Promise<{
+        path: string;
+        sha256: string;
+        bytes: number;
+        ordinal: number;
+        byteOffset: number;
+        startLine: number;
+    }[]>;
+}
+interface CaptureOptions {
+    project: Project;
+    directory: string;
+    snapshot: Snapshot;
+    revisions?: {
+        base: string;
+        head: string;
+    };
+    signal?: AbortSignal;
+}
+export declare function captureEvidence(options: CaptureOptions): Promise<ChangeEvidence>;
+export declare function verifyEvidence(evidence: ChangeEvidence): Promise<void>;
+export declare function evidenceContext(evidence: ChangeEvidence): string;
+/** Resolve through existing ancestors, rejecting source-tree writes before mkdir. */
+export declare function assertEvidenceDirectory(checkout: string, requested: string): Promise<string>;
+export {};

package/dist/src/evidence.js

@@ -0,0 +1,214 @@
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { BlockedError } from "./domain.js";
+import { sha256 } from "./prompts.js";
+import { command, maxCapturedOutputBytes } from "./runtime/process.js";
+export const evidenceLimits = {
+    chunkBytes: 64 * 1024,
+    totalBytes: maxCapturedOutputBytes,
+};
+/** Split even single long lines, preserving UTF-8 and exact reconstruction. */
+export function chunkText(text) {
+    const buffer = Buffer.from(text);
+    const chunks = [];
+    for (let start = 0; start < buffer.length;) {
+        let end = Math.min(start + evidenceLimits.chunkBytes, buffer.length);
+        while (end < buffer.length && (buffer[end] & 0xc0) === 0x80)
+            end--;
+        chunks.push(buffer.subarray(start, end).toString("utf8"));
+        start = end;
+    }
+    return chunks;
+}
+export class EvidenceWriter {
+    directory;
+    files = [];
+    bytes = 0;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async write(name, content) {
+        const bytes = Buffer.byteLength(content);
+        const total = this.bytes + bytes;
+        if (total > evidenceLimits.totalBytes)
+            throw new BlockedError(`Change evidence size ${total} bytes exceeds limit ${evidenceLimits.totalBytes} bytes`);
+        if (bytes > evidenceLimits.chunkBytes)
+            throw new BlockedError(`Evidence chunk size ${bytes} exceeds limit ${evidenceLimits.chunkBytes}`);
+        const artifact = {
+            path: resolve(this.directory, name),
+            sha256: sha256(content),
+            bytes,
+        };
+        await writeFile(artifact.path, content, { mode: 0o600, flag: "wx" });
+        this.bytes = total;
+        this.files.push(artifact);
+        return artifact;
+    }
+    async index(contents, metadata) {
+        let pages = await this.chunks("index", contents);
+        let depth = 0;
+        const serialize = () => JSON.stringify({
+            version: 1,
+            ...metadata,
+            indexDepth: depth,
+            instructions: "At depth 0, concatenate pages as JSONL change entries. At greater depth, concatenate pages as a JSON array of page references and descend one level. Read ordered patch chunks; hunk headers carry original line numbers. Untracked content starts at line 1. Report incomplete inspection explicitly.",
+            pages,
+        });
+        while (Buffer.byteLength(serialize()) > evidenceLimits.chunkBytes) {
+            depth++;
+            pages = await this.chunks(`catalog-${depth}`, JSON.stringify(pages));
+        }
+        return this.write("index.json", serialize());
+    }
+    async chunks(prefix, content) {
+        const result = [];
+        let byteOffset = 0, line = 1;
+        for (const [ordinal, part] of chunkText(content).entries()) {
+            result.push({
+                ...(await this.write(`${prefix}-${ordinal}.txt`, part)),
+                ordinal,
+                byteOffset,
+                startLine: line,
+            });
+            byteOffset += Buffer.byteLength(part);
+            line += part.split("\n").length - 1;
+        }
+        return result;
+    }
+}
+export async function captureEvidence(options) {
+    const { project, snapshot, revisions, signal } = options;
+    const checkout = await realpath(project.checkout);
+    const directory = await assertEvidenceDirectory(checkout, options.directory);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const writer = new EvidenceWriter(directory);
+    const git = async (...args) => (await command("git", args, { cwd: checkout, signal, strictUtf8: true }))
+        .stdout;
+    const diff = (...args) => git("--literal-pathspecs", "diff", "--no-ext-diff", "--no-textconv", "--no-renames", "--full-index", ...args);
+    const split = (text) => text.split("\0").filter(Boolean);
+    const untracked = revisions
+        ? []
+        : split(await git("ls-files", "--others", "--exclude-standard", "-z"));
+    const paths = revisions
+        ? split(await diff("--name-only", "-z", revisions.base, revisions.head))
+        : [
+            ...new Set([
+                ...snapshot.paths,
+                ...split(await diff("--cached", "--name-only", "-z")),
+                ...split(await diff("--name-only", "-z")),
+                ...untracked,
+            ]),
+        ].sort();
+    const entries = [];
+    for (const [number, path] of paths.entries()) {
+        signal?.throwIfAborted();
+        if (untracked.includes(path)) {
+            const content = await readFile(resolve(checkout, path));
+            let text;
+            try {
+                if (!content.includes(0))
+                    text = new TextDecoder("utf-8", {
+                        fatal: true,
+                        ignoreBOM: true,
+                    }).decode(content);
+            }
+            catch {
+                /* Binary metadata is intentional. */
+            }
+            entries.push({
+                path,
+                kind: "untracked",
+                change: "added",
+                sha256: sha256(content),
+                bytes: content.length,
+                binary: text === undefined,
+                reason: text === undefined
+                    ? "Binary or non-UTF-8 content; metadata only"
+                    : undefined,
+                chunks: text === undefined ? [] : await writer.chunks(`file-${number}`, text),
+            });
+        }
+        const ranges = revisions
+            ? [{ kind: "published", args: [revisions.base, revisions.head] }]
+            : [
+                { kind: "staged", args: ["--cached", snapshot.head] },
+                { kind: "unstaged", args: [] },
+            ];
+        for (const range of ranges) {
+            const patch = await diff(...range.args, "--", path);
+            if (!patch)
+                continue;
+            const blobs = /^index ([0-9a-f]+)\.\.([0-9a-f]+)/m.exec(patch);
+            entries.push({
+                path,
+                kind: range.kind,
+                change: /^new file mode /m.test(patch)
+                    ? "added"
+                    : /^deleted file mode /m.test(patch)
+                        ? "deleted"
+                        : "modified",
+                blobs: blobs ? { before: blobs[1], after: blobs[2] } : undefined,
+                sha256: sha256(patch),
+                binary: /^Binary files /m.test(patch),
+                reason: /^Binary files /m.test(patch)
+                    ? "Git binary change; metadata only"
+                    : undefined,
+                // Patch headers/hunks preserve original old/new line numbers. Offsets support split long lines.
+                chunks: await writer.chunks(`patch-${number}-${range.kind}`, patch),
+            });
+        }
+    }
+    const identity = {
+        base: revisions?.base ?? snapshot.head,
+        ...(revisions
+            ? { head: revisions.head }
+            : { snapshot: snapshot.fingerprint }),
+    };
+    const index = await writer.index(entries.map((entry) => JSON.stringify(entry)).join("\n") + "\n", { ...identity, changedPaths: paths.length });
+    const evidence = {
+        ...identity,
+        index: index.path,
+        identity: index.sha256,
+        files: writer.files,
+        changedPaths: paths.length,
+    };
+    await verifyEvidence(evidence);
+    return evidence;
+}
+export async function verifyEvidence(evidence) {
+    for (const file of evidence.files) {
+        const content = await readFile(file.path).catch((cause) => {
+            throw new BlockedError(`Required change evidence unavailable: ${file.path}: ${String(cause)}`);
+        });
+        if (content.length !== file.bytes || sha256(content) !== file.sha256)
+            throw new BlockedError(`Change evidence changed: ${file.path}`);
+    }
+}
+export function evidenceContext(evidence) {
+    return `Change evidence index: ${evidence.index}\nIdentity: ${evidence.identity}\nBase: ${evidence.base}\nHead: ${evidence.head ?? "verified dirty snapshot"}\nChanged paths: ${evidence.changedPaths}\nRead the index and its ordered artifacts incrementally. Use read-only tools and do not edit files. Required evidence must be readable; never infer missing content. Binary content is metadata-only.`;
+}
+/** Resolve through existing ancestors, rejecting source-tree writes before mkdir. */
+export async function assertEvidenceDirectory(checkout, requested) {
+    const canonicalCheckout = await realpath(checkout);
+    let ancestor = resolve(requested);
+    const suffix = [];
+    while (true) {
+        try {
+            const canonical = await realpath(ancestor);
+            const destination = resolve(canonical, ...suffix);
+            const location = relative(canonicalCheckout, destination);
+            if (!location ||
+                (!isAbsolute(location) &&
+                    location !== ".." &&
+                    !location.startsWith(`..${sep}`)))
+                throw new BlockedError("State directory for change evidence must be outside the managed checkout");
+            return destination;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            suffix.unshift(relative(dirname(ancestor), ancestor));
+            ancestor = dirname(ancestor);
+        }
+    }
+}

package/dist/src/index.d.ts

@@ -3,6 +3,7 @@ export * from "./adapters/hosting.js";
 export * from "./config.js";
 export * from "./domain.js";
 export * from "./operations.js";
+export * from "./prompts.js";
 export * from "./runner.js";
 export * from "./store.js";
 export * from "./workspace.js";

package/dist/src/index.js

@@ -3,6 +3,7 @@ export * from "./adapters/hosting.js";
 export * from "./config.js";
 export * from "./domain.js";
 export * from "./operations.js";
+export * from "./prompts.js";
 export * from "./runner.js";
 export * from "./store.js";
 export * from "./workspace.js";

package/dist/src/invocation.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { type Stage } from "./config.js";
+import { type RunRecord, type Snapshot } from "./domain.js";
+import { type ChangeEvidence } from "./evidence.js";
+import type { OperationDependencies } from "./operations.js";
+export interface InvocationTask {
+    defaultPrompt: string;
+    context?: (run: RunRecord) => string;
+    readOnly?: boolean;
+    outputContract?: z.ZodType;
+    evidence?: ChangeEvidence;
+}
+interface StageExecution {
+    run: RunRecord;
+    name: string;
+    stage: Stage;
+    task: InvocationTask;
+    stepId: number;
+    dependencies: OperationDependencies;
+    saveImplementationSnapshot: (runId: string, snapshot: Snapshot) => Promise<void>;
+}
+/** One logical stage; only returned format errors admit a second response attempt. */
+export declare function invokeStage({ run, name, stage, task, stepId, dependencies, saveImplementationSnapshot, }: StageExecution): Promise<string>;
+export {};

package/dist/src/invocation.js

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { resolveProfile } from "./config.js";
+import { BlockedError } from "./domain.js";
+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, }) {
+    const { store, project, agents, signal, workspace, redact } = dependencies;
+    const previous = (await store.invocations(run.id)).filter((item) => item.stepId === stepId);
+    if (previous.length) {
+        for (const record of previous) {
+            if (record.outcome !== "running")
+                continue;
+            record.outcome = "interrupted";
+            record.finishedAt = new Date().toISOString();
+            if (!record.sessionId)
+                record.sessionState = "unavailable";
+            await store.saveInvocation(record);
+        }
+        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);
+    const resolved = resolveStagePrompt(stage, task.defaultPrompt, dependencies.promptBaseDirectory);
+    const outputSchema = task.outputContract
+        ? z.toJSONSchema(task.outputContract)
+        : undefined;
+    const contract = outputSchema
+        ? `Return ONLY JSON satisfying this application-owned schema:\n${JSON.stringify(outputSchema)}`
+        : "";
+    const fullPrompt = [
+        resolved.content,
+        `Run context:\n${task.context?.(run) ?? ""}`,
+        task.readOnly
+            ? "Inspection only. Do not modify files, commit, push, or publish."
+            : "Do not commit, push, or publish.",
+        contract,
+    ].join("\n\n");
+    const profile = resolveProfile(project.agent, stage.profile);
+    const adapter = agents[profile.provider];
+    if (!adapter)
+        throw new Error(`Missing agent adapter ${profile.provider}`);
+    const deadline = Date.now() + stage.timeoutMs;
+    const invocationSignal = AbortSignal.any([
+        signal,
+        AbortSignal.timeout(stage.timeoutMs),
+    ]);
+    const effective = await adapter.validate(profile, invocationSignal);
+    const directory = join(dependencies.artifacts, run.id);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    let correction = "";
+    for (let attempt = 1; attempt <= maxInvocationAttempts; attempt++) {
+        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 + 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`),
+        };
+        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,
+                    });
+                },
+            });
+            await appendFile(record.log, "", { mode: 0o600 });
+            invocationSignal.throwIfAborted();
+            if (readOnly)
+                await workspace.verify(project, expected);
+            else
+                await saveImplementationSnapshot(run.id, expected);
+            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;
+            }
+            record.outcome = "completed";
+            return redact(task.outputContract ? JSON.stringify(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);
+        }
+    }
+    throw new Error("Format correction exhausted");
+}

package/dist/src/operations.d.ts

@@ -1,7 +1,10 @@
 import type { Project, Stage } from "./config.js";
 import { type AgentAdapter, type HostingAdapter, type RunRecord, type Workspace } from "./domain.js";
+import { type InvocationTask } from "./invocation.js";
 import type { Store } from "./store.js";
+export type { InvocationTask } from "./invocation.js";
 export interface OperationDependencies {
+    promptBaseDirectory?: string;
     store: Store;
     project: Project;
     workspace: Workspace;
@@ -10,6 +13,8 @@ export interface OperationDependencies {
     artifacts: string;
     signal: AbortSignal;
     redact: (text: string) => string;
+    beforeStep?: () => Promise<void>;
+    executionFingerprint?: () => Promise<string>;
 }
 /** Reusable durable coding operations. Call from a registered DBOS workflow. */
 export declare class Operations {
@@ -19,11 +24,11 @@ export declare class Operations {
     step<T>(name: string, operation: (run: RunRecord) => Promise<T>): Promise<T>;
     eligible(): Promise<boolean>;
     prepare(): Promise<void>;
-    invoke(name: string, stage: Stage, prompt: (run: RunRecord) => string, readOnly?: boolean): Promise<string>;
-    private prepareInvocationPrompt;
+    invoke(name: string, stage: Stage, task: InvocationTask): Promise<string>;
     private saveImplementationSnapshot;
     implement(): Promise<void>;
     validate(): Promise<boolean>;
+    private prepareEvidence;
     writePublication(): Promise<void>;
     commit(): Promise<void>;
     push(): Promise<void>;