@mingchuno/agent-workflows 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,29 @@
 # Agent Workflows
 
+![Print-shop workbench with a job sheet, a worked proof, and an inspected copy awaiting human approval.](docs/assets/hero.png)
+
 A local TypeScript SDK and CLI/TUI that turns labelled GitHub or GitLab issues into draft change requests with independent agent reviews. DBOS persists execution; each project uses its existing checkout, with one task at a time. Separate projects progress concurrently.
 
-Phase 1 includes Codex and Copilot SDK adapters, GitHub and GitLab.com/self-hosted GitLab adapters, durable publication reconciliation, session observability and explicit operator controls. Human review and merging remain separate.
+Supports Codex and Copilot SDKs, GitHub, and GitLab.com/self-hosted GitLab. Human review and merging remain separate.
+
+## Why use this SDK over DBOS directly?
+
+DBOS provides durable execution, checkpoints and queues. This SDK supplies the
+coding-workflow behavior a client would otherwise build around it:
+
+- **Ready-made operations:** issue intake, agent implementation, validation,
+  draft PR/MR publication and independent review, with Codex/Copilot and
+  GitHub/GitLab adapters.
+- **Checkout and recovery rules:** exclusive checkout ownership, process
+  cancellation, preservation of unfinished work, and reconciliation of interrupted
+  commits, pushes and publication.
+- **Application controls and evidence:** explicit run outcomes, safe retry
+  admission, session/log records, and a shared SDK, CLI and terminal monitor.
+
+Clients configure providers and compose operations while DBOS remains responsible
+for durability. [Custom workflows can call DBOS directly](docs/api.md#dbos-sdk-direct-usage).
+Use this SDK when its existing-checkout, one-task-per-project model fits; use DBOS
+directly when you need general-purpose workflows or want to own these policies.
 
 ## Quickstart
 
@@ -17,7 +38,7 @@ agent-workflows init
 
 For SDK use, install locally with `npm install @mingchuno/agent-workflows`. Both interfaces ship in the same package.
 
-Edit `agent-workflows.json`: set the checkout, hosting origin/repository, Git identity, agent stages and validation commands. Set the named hosting-token environment variable through your usual secret manager. Commit or ignore the configuration before running. Keep the state directory outside managed checkouts, or explicitly Git-ignore it.
+Edit `agent-workflows.json`: set the checkout, hosting origin/repository, Git identity, agent stages and validation commands. Set the named hosting-token environment variable through your usual secret manager; for GitHub, follow the [PAT creation and required permissions](docs/providers.md#create-a-fine-grained-personal-access-token) guide before running. Commit or ignore the configuration before running. Keep the state directory outside managed checkouts, or explicitly Git-ignore it.
 
 ```sh
 agent-workflows run
@@ -26,6 +47,10 @@ agent-workflows monitor
 agent-workflows status --json
 ```
 
+Alternatively, load database, hosting and application variables from one explicit
+file: `agent-workflows --env-file ./runner.env run`. Existing shell values win,
+including empty strings. See [environment file examples and boundaries](docs/configuration.md#cli-environment-files).
+
 The runner fetches the configured base, creates a branch, implements an eligible issue, validates it, generates publication text, commits and pushes, creates a draft PR/MR, and publishes an independent review of its exact head. It never merges. Initial use should target a repository and issue you explicitly intend to automate; running the CLI authorizes these effects and agent usage.
 
 ## SDK
@@ -65,10 +90,11 @@ Use `pnpm start --help` to run the CLI from source. `pnpm build` emits the runti
 Schema changes and database upgrades: [database maintenance](docs/database.md). Biome formats and lints supported source/configuration files; Markdown and YAML are maintained manually.
 
 - [Configuration and profiles](docs/configuration.md)
+- [Default stage prompts](docs/configuration.md#default-stage-prompts)
 - [Public SDK API and composition](docs/api.md)
+- [DBOS SDK direct usage](docs/api.md#dbos-sdk-direct-usage)
 - [Authentication and provider capabilities](docs/providers.md)
 - [CLI, TUI, observability and recovery](docs/operations.md)
-- [Architecture and review evidence](docs/architecture.md)
-- [Phase 1 acceptance](docs/acceptance.md)
-- [Release setup, first publication and recovery](docs/releases.md)
-- [Specification](https://github.com/mingchuno/agent-workflows/issues/1)
+- [Observability Landscape](docs/operations.md#observability-landscape)
+- [Architecture](docs/architecture.md)
+- [Releases](docs/releases.md)

package/dist/src/adapters/agents.js

@@ -2,6 +2,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { defaultStageTimeoutMs } from "../defaults.js";
 import { command } from "../runtime/process.js";
 /** Runs each SDK invocation in an owned process group; no cross-stage session reuse. */
 export class SDKAgent {
@@ -65,9 +66,9 @@ export class SDKAgent {
             cwd: invocation.cwd,
             prompt: invocation.prompt,
             profile: invocation.profile,
-            skills: invocation.skills,
+            outputSchema: invocation.outputSchema,
             readOnly: invocation.readOnly,
-            timeoutMs: invocation.timeoutMs ?? 1_800_000,
+            timeoutMs: invocation.timeoutMs ?? defaultStageTimeoutMs,
         }, invocation);
     }
     async worker(input, invocation, signal = invocation?.signal) {
@@ -97,7 +98,9 @@ export class SDKAgent {
                 ]),
                 captureOutput: false,
                 processFile: invocation?.processFile,
-                timeoutMs: invocation ? (invocation.timeoutMs ?? 1_800_000) : 30_000,
+                timeoutMs: invocation
+                    ? (invocation.timeoutMs ?? defaultStageTimeoutMs)
+                    : 30_000,
                 onOutput: (chunk) => {
                     buffer += chunk;
                     for (;;) {

package/dist/src/adapters/hosting.js

@@ -1,6 +1,10 @@
 import { Gitlab } from "@gitbeaker/rest";
 import { Octokit } from "@octokit/rest";
 import { BlockedError, } from "../domain.js";
+const hostingRequestTimeoutMs = 30_000;
+const hostingPageSize = 100;
+const minimumGitLabMajorVersion = 17;
+const maximumGitLabMajorVersion = 19;
 function origin(value) {
     const url = new URL(value);
     if (url.username || url.password || url.search || url.hash)
@@ -70,7 +74,7 @@ export class GitHubHosting {
             baseUrl: host === "https://github.com"
                 ? "https://api.github.com"
                 : `${host}/api/v3`,
-            request: { timeout: 30000, redirect: "error" },
+            request: { timeout: hostingRequestTimeoutMs, redirect: "error" },
         });
     }
     async listIssues(labels) {
@@ -78,7 +82,7 @@ export class GitHubHosting {
             ...this.repo,
             state: "open",
             labels: labels.join(","),
-            per_page: 100,
+            per_page: hostingPageSize,
         });
         return issues
             .filter((issue) => !issue.pull_request)
@@ -112,7 +116,7 @@ export class GitHubHosting {
             ...this.repo,
             head: `${this.repo.owner}:${branch}`,
             state: "all",
-            per_page: 100,
+            per_page: hostingPageSize,
         });
         if (changes.length > 1)
             throw new BlockedError("Multiple change requests match branch");
@@ -139,7 +143,7 @@ export class GitHubHosting {
         const reviews = await this.client.paginate(this.client.pulls.listReviews, {
             ...this.repo,
             pull_number: input.change.id,
-            per_page: 100,
+            per_page: hostingPageSize,
         });
         if (reviews.some((review) => review.body?.includes(marker(input.runId))))
             return;
@@ -172,21 +176,23 @@ export class GitLabHosting {
         this.client = new Gitlab({
             host,
             token: token(project),
-            queryTimeout: 30000,
+            queryTimeout: hostingRequestTimeoutMs,
         });
     }
     async preflight() {
         const metadata = await this.client.Metadata.show();
         const major = Number(metadata.version.split(".")[0]);
-        if (!Number.isInteger(major) || major < 17 || major > 19)
-            throw new Error(`Supported GitLab versions are 17.x–19.x; instance reports ${metadata.version}`);
+        if (!Number.isInteger(major) ||
+            major < minimumGitLabMajorVersion ||
+            major > maximumGitLabMajorVersion)
+            throw new Error(`Supported GitLab versions are ${minimumGitLabMajorVersion}.x–${maximumGitLabMajorVersion}.x; instance reports ${metadata.version}`);
     }
     async listIssues(labels) {
         const issues = await this.client.Issues.all({
             projectId: this.repository,
             state: "opened",
             labels: labels.join(","),
-            perPage: 100,
+            perPage: hostingPageSize,
         });
         return issues.map((issue) => ({
             id: String(issue.id),
@@ -216,7 +222,7 @@ export class GitLabHosting {
         const changes = await this.client.MergeRequests.all({
             projectId: this.repository,
             sourceBranch: branch,
-            perPage: 100,
+            perPage: hostingPageSize,
         });
         if (changes.length > 1)
             throw new BlockedError("Multiple merge requests match branch");
@@ -237,7 +243,7 @@ export class GitLabHosting {
             .sha;
     }
     async publishReview(input) {
-        const notes = await this.client.MergeRequestNotes.all(this.repository, input.change.id, { perPage: 100 });
+        const notes = await this.client.MergeRequestNotes.all(this.repository, input.change.id, { perPage: hostingPageSize });
         if (notes.some((note) => note.body.includes(marker(input.runId))))
             return;
         const change = await this.client.MergeRequests.show(this.repository, input.change.id);

package/dist/src/adapters/sdk-protocol.d.ts

@@ -1,5 +1,5 @@
 import type { ModelInfo, SessionConfig } from "@github/copilot-sdk";
-import type { ThreadEvent, ThreadOptions } from "@openai/codex-sdk";
+import type { ThreadEvent, ThreadOptions, TurnOptions } from "@openai/codex-sdk";
 import type { AgentProfile } from "../config.js";
 export interface WorkerInput {
     provider: "codex" | "copilot";
@@ -8,7 +8,7 @@ export interface WorkerInput {
     cwd: string;
     prompt: string;
     profile: AgentProfile;
-    skills: string[];
+    outputSchema?: unknown;
     readOnly: boolean;
     processFile?: string;
     timeoutMs?: number;
@@ -16,7 +16,7 @@ export interface WorkerInput {
 export type Emit = (type: string, value: unknown) => void;
 export interface CodexClient {
     startThread(options: ThreadOptions): {
-        runStreamed(prompt: string): Promise<{
+        runStreamed(prompt: string, options?: TurnOptions): Promise<{
             events: AsyncIterable<ThreadEvent>;
         }>;
     };

package/dist/src/adapters/sdk-protocol.js

@@ -1,4 +1,4 @@
-import { dirname } from "node:path";
+import { defaultStageTimeoutMs } from "../defaults.js";
 export async function runCodex(client, input, emit) {
     const thread = client.startThread({
         workingDirectory: input.cwd,
@@ -8,7 +8,9 @@ export async function runCodex(client, input, emit) {
         sandboxMode: input.readOnly ? "read-only" : "workspace-write",
         approvalPolicy: "never",
     });
-    const turn = await thread.runStreamed(input.prompt);
+    const turn = await thread.runStreamed(input.prompt, {
+        outputSchema: input.outputSchema,
+    });
     let output = "";
     for await (const event of turn.events) {
         if (event.type === "thread.started")
@@ -39,17 +41,17 @@ export async function runCopilot(client, input, emit) {
             reasoningEffort: input.profile
                 .reasoningEffort,
             workingDirectory: input.cwd,
-            skillDirectories: input.skills.map(dirname),
             infiniteSessions: input.profile.context
                 ? { enabled: true, ...input.profile.context }
                 : undefined,
-            onPermissionRequest: async (request) => input.readOnly && request.kind !== "read"
-                ? { kind: "denied-no-approval-rule-and-could-not-request-from-user" }
-                : { kind: "approved" },
+            onPermissionRequest: async (request) => request.managedApprovalRequired ||
+                (input.readOnly && request.kind !== "read")
+                ? { kind: "reject" }
+                : { kind: "approve-once" },
         });
         emit("session", session.sessionId);
         session.on((event) => emit("event", event));
-        const response = await session.sendAndWait({ prompt: input.prompt }, input.timeoutMs ?? 1_800_000);
+        const response = await session.sendAndWait({ prompt: input.prompt }, input.timeoutMs ?? defaultStageTimeoutMs);
         emit("result", response?.data.content ?? "");
         await session.disconnect();
     }

package/dist/src/cli.d.ts

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --
 export {};

package/dist/src/cli.js

@@ -1,19 +1,40 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --
 import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
+import { parseEnv } from "node:util";
 import { Command } from "commander";
 import { render } from "ink";
 import React from "react";
 import { createAgents } from "./adapters/agents.js";
 import { createHosting } from "./adapters/hosting.js";
 import { configSchema } from "./config.js";
+import { defaultValidationTimeoutMs } from "./defaults.js";
 import { Runner } from "./runner.js";
 import { Store } from "./store.js";
-import { Monitor } from "./tui.js";
+import { Monitor } from "./tui/index.js";
+const launchDirectory = process.cwd();
 const program = new Command()
     .name("agent-workflows")
     .description("Local durable issue-to-review workflows")
-    .option("-c, --config <file>", "configuration path", "agent-workflows.json");
+    .option("-c, --config <file>", "configuration path", "agent-workflows.json")
+    .option("--env-file <path>", "load literal dotenv values; existing environment wins")
+    .hook("preAction", async () => {
+    const path = program.opts().envFile;
+    if (path === undefined)
+        return;
+    const file = resolve(launchDirectory, path);
+    let contents;
+    try {
+        contents = await readFile(file, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Cannot read environment file ${file} (${error.code ?? "read failed"})`);
+    }
+    for (const [name, value] of Object.entries(parseEnv(contents))) {
+        if (process.env[name] === undefined)
+            process.env[name] = value;
+    }
+});
 async function configuration() {
     return configSchema.parse(JSON.parse(await readFile(resolve(program.opts().config), "utf8")));
 }
@@ -41,7 +62,7 @@ program
     const config = {
         id: "local",
         databaseUrlEnv: "AGENT_WORKFLOWS_DATABASE_URL",
-        stateDirectory: resolve(".agent-workflows"),
+        stateDirectory: resolve("..", `${basename(process.cwd())}.agent-workflows`),
         projects: [
             {
                 id: "example",
@@ -57,18 +78,14 @@ program
                 branchTemplate: "agent/{issue}-{attempt}",
                 gitIdentity: { name: "YOUR NAME", email: "you@example.com" },
                 agent: { provider: "codex" },
-                validation: [{ command: "pnpm", args: ["test"], timeoutMs: 300000 }],
-                stages: {
-                    implementation: {
-                        prompt: "Implement the issue and preserve repository conventions.",
-                    },
-                    writing: {
-                        prompt: "Describe the actual changes and validation accurately.",
+                validation: [
+                    {
+                        command: "pnpm",
+                        args: ["test"],
+                        timeoutMs: defaultValidationTimeoutMs,
                     },
-                    review: {
-                        prompt: "Review correctness, safety and the issue acceptance criteria.",
-                    },
-                },
+                ],
+                stages: { implementation: {}, publication: {}, review: {} },
             },
         ],
     };
@@ -88,6 +105,7 @@ program
         config.projects = config.projects.filter((project) => wanted.has(project.id));
     }
     const runner = new Runner({
+        promptBaseDirectory: dirname(resolve(program.opts().config)),
         config,
         databaseUrl: databaseUrl(config),
         hosting: createHosting,
@@ -126,6 +144,7 @@ program
 program.command("inspect <run>").action(async (run) => withStore(async (store) => console.log(JSON.stringify({
     run: await store.run(run),
     invocations: await store.invocations(run),
+    recovery: await store.recoveryPlan(run),
 }, null, 2))));
 program
     .command("logs <run>")
@@ -149,7 +168,7 @@ program
         }
     }
 }));
-for (const kind of ["pause", "resume", "stop", "retry"])
+for (const kind of ["pause", "resume", "stop", "retry", "recover"])
     program
         .command(`${kind} <target>`)
         .description(`${kind} project or run through the active runner`)
@@ -160,10 +179,12 @@ for (const kind of ["pause", "resume", "stop", "retry"])
         }));
     }));
 program.command("monitor").action(async () => {
-    if (!process.stdin.isTTY)
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
         throw new Error("Monitor requires an interactive terminal; use status --json instead");
     await withStore(async (store) => {
-        await render(React.createElement(Monitor, { source: store })).waitUntilExit();
+        await render(React.createElement(Monitor, { source: store }), {
+            alternateScreen: true,
+        }).waitUntilExit();
     });
 });
 try {

package/dist/src/config.d.ts

@@ -25,8 +25,8 @@ export declare const stageSchema: z.ZodObject<{
             bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
-    prompt: z.ZodDefault<z.ZodString>;
-    skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    prompt: z.ZodOptional<z.ZodString>;
+    promptFile: z.ZodOptional<z.ZodString>;
     timeoutMs: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const projectSchema: z.ZodObject<{
@@ -67,8 +67,8 @@ export declare const projectSchema: z.ZodObject<{
             bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
-    stages: z.ZodDefault<z.ZodObject<{
-        implementation: z.ZodDefault<z.ZodObject<{
+    stages: z.ZodPrefault<z.ZodObject<{
+        implementation: z.ZodPrefault<z.ZodObject<{
             profile: z.ZodOptional<z.ZodObject<{
                 provider: z.ZodOptional<z.ZodEnum<{
                     codex: "codex";
@@ -81,11 +81,11 @@ export declare const projectSchema: z.ZodObject<{
                     bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strict>>>;
             }, z.core.$strict>>;
-            prompt: z.ZodDefault<z.ZodString>;
-            skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            prompt: z.ZodOptional<z.ZodString>;
+            promptFile: z.ZodOptional<z.ZodString>;
             timeoutMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
-        writing: z.ZodDefault<z.ZodObject<{
+        publication: z.ZodPrefault<z.ZodObject<{
             profile: z.ZodOptional<z.ZodObject<{
                 provider: z.ZodOptional<z.ZodEnum<{
                     codex: "codex";
@@ -98,11 +98,11 @@ export declare const projectSchema: z.ZodObject<{
                     bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strict>>>;
             }, z.core.$strict>>;
-            prompt: z.ZodDefault<z.ZodString>;
-            skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            prompt: z.ZodOptional<z.ZodString>;
+            promptFile: z.ZodOptional<z.ZodString>;
             timeoutMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
-        review: z.ZodDefault<z.ZodObject<{
+        review: z.ZodPrefault<z.ZodObject<{
             profile: z.ZodOptional<z.ZodObject<{
                 provider: z.ZodOptional<z.ZodEnum<{
                     codex: "codex";
@@ -115,8 +115,8 @@ export declare const projectSchema: z.ZodObject<{
                     bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strict>>>;
             }, z.core.$strict>>;
-            prompt: z.ZodDefault<z.ZodString>;
-            skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            prompt: z.ZodOptional<z.ZodString>;
+            promptFile: z.ZodOptional<z.ZodString>;
             timeoutMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
@@ -163,8 +163,8 @@ export declare const configSchema: z.ZodObject<{
                 bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
-        stages: z.ZodDefault<z.ZodObject<{
-            implementation: z.ZodDefault<z.ZodObject<{
+        stages: z.ZodPrefault<z.ZodObject<{
+            implementation: z.ZodPrefault<z.ZodObject<{
                 profile: z.ZodOptional<z.ZodObject<{
                     provider: z.ZodOptional<z.ZodEnum<{
                         codex: "codex";
@@ -177,11 +177,11 @@ export declare const configSchema: z.ZodObject<{
                         bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strict>>>;
                 }, z.core.$strict>>;
-                prompt: z.ZodDefault<z.ZodString>;
-                skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                prompt: z.ZodOptional<z.ZodString>;
+                promptFile: z.ZodOptional<z.ZodString>;
                 timeoutMs: z.ZodDefault<z.ZodNumber>;
             }, z.core.$strict>>;
-            writing: z.ZodDefault<z.ZodObject<{
+            publication: z.ZodPrefault<z.ZodObject<{
                 profile: z.ZodOptional<z.ZodObject<{
                     provider: z.ZodOptional<z.ZodEnum<{
                         codex: "codex";
@@ -194,11 +194,11 @@ export declare const configSchema: z.ZodObject<{
                         bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strict>>>;
                 }, z.core.$strict>>;
-                prompt: z.ZodDefault<z.ZodString>;
-                skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                prompt: z.ZodOptional<z.ZodString>;
+                promptFile: z.ZodOptional<z.ZodString>;
                 timeoutMs: z.ZodDefault<z.ZodNumber>;
             }, z.core.$strict>>;
-            review: z.ZodDefault<z.ZodObject<{
+            review: z.ZodPrefault<z.ZodObject<{
                 profile: z.ZodOptional<z.ZodObject<{
                     provider: z.ZodOptional<z.ZodEnum<{
                         codex: "codex";
@@ -211,8 +211,8 @@ export declare const configSchema: z.ZodObject<{
                         bufferExhaustionThreshold: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strict>>>;
                 }, z.core.$strict>>;
-                prompt: z.ZodDefault<z.ZodString>;
-                skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                prompt: z.ZodOptional<z.ZodString>;
+                promptFile: z.ZodOptional<z.ZodString>;
                 timeoutMs: z.ZodDefault<z.ZodNumber>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;

package/dist/src/config.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { defaultStageTimeoutMs, defaultValidationTimeoutMs, } from "./defaults.js";
 export const profileSchema = z.strictObject({
     provider: z.enum(["codex", "copilot"]),
     model: z.string().min(1).optional(),
@@ -10,12 +11,24 @@ export const profileSchema = z.strictObject({
     })
         .optional(),
 });
-export const stageSchema = z.strictObject({
+export const stageSchema = z
+    .strictObject({
     profile: profileSchema.partial().optional(),
-    prompt: z.string().default(""),
-    skills: z.array(z.string()).default([]),
-    timeoutMs: z.number().int().positive().default(1_800_000),
-});
+    prompt: z
+        .string()
+        .refine((text) => text.trim().length > 0, "Prompt must be nonblank")
+        .optional(),
+    promptFile: z
+        .string()
+        .refine((text) => text.trim().length > 0, "Prompt file path must be nonblank")
+        .optional(),
+    timeoutMs: z.number().int().positive().default(defaultStageTimeoutMs),
+}, {
+    error: (issue) => issue.code === "unrecognized_keys" && issue.keys.includes("skills")
+        ? "Stage skills was removed; configure skills in your agent runtime and request them in prompt"
+        : undefined,
+})
+    .refine((stage) => stage.prompt === undefined || stage.promptFile === undefined, "Specify either prompt or promptFile, never both");
 export const projectSchema = z.strictObject({
     id: z.string().regex(/^[a-zA-Z0-9_-]+$/),
     checkout: z.string().min(1),
@@ -40,34 +53,26 @@ export const projectSchema = z.strictObject({
         .array(z.strictObject({
         command: z.string().min(1),
         args: z.array(z.string()).default([]),
-        timeoutMs: z.number().int().positive().default(300_000),
+        timeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .default(defaultValidationTimeoutMs),
     }))
         .default([]),
     gitIdentity: z.strictObject({ name: z.string().min(1), email: z.email() }),
     agent: profileSchema,
     stages: z
         .strictObject({
-        implementation: stageSchema.default(() => ({
-            prompt: "",
-            skills: [],
-            timeoutMs: 1_800_000,
-        })),
-        writing: stageSchema.default(() => ({
-            prompt: "",
-            skills: [],
-            timeoutMs: 1_800_000,
-        })),
-        review: stageSchema.default(() => ({
-            prompt: "",
-            skills: [],
-            timeoutMs: 1_800_000,
-        })),
+        implementation: stageSchema.prefault({}),
+        publication: stageSchema.prefault({}),
+        review: stageSchema.prefault({}),
+    }, {
+        error: (issue) => issue.code === "unrecognized_keys" && issue.keys.includes("writing")
+            ? "Stage writing was renamed to publication; update projects.stages.writing"
+            : undefined,
     })
-        .default(() => ({
-        implementation: { prompt: "", skills: [], timeoutMs: 1_800_000 },
-        writing: { prompt: "", skills: [], timeoutMs: 1_800_000 },
-        review: { prompt: "", skills: [], timeoutMs: 1_800_000 },
-    })),
+        .prefault({}),
 });
 export const configSchema = z.strictObject({
     id: z.string().regex(/^[a-zA-Z0-9_-]+$/),

package/dist/src/defaults.d.ts

@@ -0,0 +1,2 @@
+export declare const defaultStageTimeoutMs = 1800000;
+export declare const defaultValidationTimeoutMs = 300000;

package/dist/src/defaults.js

@@ -0,0 +1,2 @@
+export const defaultStageTimeoutMs = 1_800_000;
+export const defaultValidationTimeoutMs = 300_000;

package/dist/src/domain.d.ts

@@ -21,14 +21,16 @@ export declare const publicationSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type Publication = z.infer<typeof publicationSchema>;
 export declare const reviewSchema: z.ZodObject<{
+    complete: z.ZodBoolean;
+    limitations: z.ZodArray<z.ZodString>;
     summary: z.ZodString;
     findings: z.ZodArray<z.ZodObject<{
         body: z.ZodString;
-        path: z.ZodOptional<z.ZodString>;
-        line: z.ZodOptional<z.ZodNumber>;
+        path: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        line: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export type Review = z.infer<typeof reviewSchema>;
+export type Review = z.input<typeof reviewSchema>;
 export interface ValidationResult {
     command: string;
     args: string[];
@@ -84,7 +86,7 @@ export interface AgentInvocation {
     cwd: string;
     prompt: string;
     profile: AgentProfile;
-    skills: string[];
+    outputSchema?: unknown;
     processFile?: string;
     readOnly: boolean;
     signal: AbortSignal;
@@ -104,6 +106,22 @@ export interface AgentAdapter {
     invoke(invocation: AgentInvocation): Promise<string>;
 }
 export type Outcome = "queued" | "running" | "completed" | "failed" | "blocked" | "cancelled" | "no-change" | "ineligible";
+export interface ExecutionRecord {
+    /** DBOS workflow identity; publication markers continue to use the run ID. */
+    id: string;
+    recoveryOf?: string;
+    startStep?: number;
+    reusedSteps?: string[];
+    fingerprint: string;
+    recoverySupported: boolean;
+    createdAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    outcome: Outcome;
+    phase: string;
+    failedStep?: number;
+    error?: string;
+}
 export interface RunRecord {
     id: string;
     projectId: string;
@@ -126,6 +144,8 @@ export interface RunRecord {
     review?: Review;
     reviewHead?: string;
     error?: string;
+    failedStep?: number;
+    executions?: ExecutionRecord[];
 }
 export declare class BlockedError extends Error {
     constructor(message: string);