@mingchuno/agent-workflows 0.3.0 → 0.5.0

package/README.md

@@ -52,9 +52,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).
+Alternatively, set `"envFile": "./runner.env"` at the top level of
+`agent-workflows.json` to load database, hosting and application variables from
+one explicit file. Existing process 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.
 
@@ -76,6 +77,24 @@ await runner.shutdown();
 
 [Custom workflow](examples/custom-workflow.ts), [complete runner](examples/run.ts), [configuration](examples/config.ts), and [inspection](examples/observe.ts) examples are type-checked with the library. The custom workflow is also exercised using controlled providers.
 
+## Documentation
+
+### Using the package
+
+- [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)
+- [Observability landscape](docs/operations.md#observability-landscape)
+
+### Maintaining the project
+
+- [Architecture decisions](docs/adr/README.md)
+- [Database maintenance](docs/database.md)
+- [Release process](docs/releases.md)
+
 ## Development and review
 
 [mise](https://mise.jdx.dev/getting-started.html) pins the development Node and pnpm versions. Activate it in your shell or prefix commands with `mise exec --`.
@@ -92,14 +111,6 @@ Use `pnpm start --help` to run the CLI from source. `pnpm build` emits the runti
 
 `pnpm test` builds the application, then starts and removes a disposable real PostgreSQL database using `initdb`, `pg_ctl`, and `createdb` on PATH. Alternatively, set `TEST_DATABASE_URL` to a disposable database whose role can create test databases. Tests use real temporary Git repositories and controlled adapters/HTTP servers; they make no paid agent calls or writes to real hosting providers.
 
-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)
-- [Observability Landscape](docs/operations.md#observability-landscape)
-- [Architecture](docs/architecture.md)
-- [Releases](docs/releases.md)
+Schema changes and database upgrades: [database maintenance](docs/database.md).
+Biome formats and lints supported source/configuration files; Markdown and YAML
+are maintained manually.

package/dist/src/adapters/agents.js

@@ -84,6 +84,7 @@ export class SDKAgent {
         const worker = join(dirname(ownPath), `agent-worker.${source ? "ts" : "js"}`);
         let buffer = "", output = "", events = Promise.resolve();
         let eventError;
+        let stderr = "";
         const persistenceFailure = new AbortController();
         try {
             await command(process.execPath, [
@@ -97,6 +98,9 @@ export class SDKAgent {
                     ...(signal ? [signal] : []),
                 ]),
                 captureOutput: false,
+                onStderr: (chunk) => {
+                    stderr = (stderr + chunk).slice(-16_384);
+                },
                 processFile: invocation?.processFile,
                 timeoutMs: invocation
                     ? (invocation.timeoutMs ?? defaultStageTimeoutMs)
@@ -128,6 +132,11 @@ export class SDKAgent {
                             });
                     }
                 },
+            }).catch((error) => {
+                const detail = stderr.trim();
+                throw detail
+                    ? new Error(`${String(error)}\nWorker stderr (last 16 KiB):\n${detail}`)
+                    : error;
             });
             await events;
             if (eventError)

package/dist/src/cli-config.d.ts

@@ -0,0 +1,2 @@
+import { type Configuration } from "./config.js";
+export declare function readCliConfiguration(path: string, resolveEnvironmentFile: (path: string) => string): Promise<Configuration>;

package/dist/src/cli-config.js

@@ -0,0 +1,35 @@
+import { readFile } from "node:fs/promises";
+import { parseEnv } from "node:util";
+import { z } from "zod";
+import { configSchema } from "./config.js";
+const cliConfigurationSchema = configSchema.extend({
+    envFile: z
+        .string()
+        .refine((path) => path.trim().length > 0, "Environment file path must be nonblank")
+        .optional(),
+});
+export async function readCliConfiguration(path, resolveEnvironmentFile) {
+    const { envFile, ...configuration } = cliConfigurationSchema.parse(JSON.parse(await readFile(path, "utf8")));
+    if (envFile !== undefined)
+        await loadEnvironmentFile(resolveEnvironmentFile(envFile));
+    return configuration;
+}
+async function loadEnvironmentFile(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Cannot read environment file ${path} (${error.code ?? "read failed"})`);
+    }
+    let values;
+    try {
+        values = parseEnv(contents);
+    }
+    catch (error) {
+        throw new Error(`Cannot parse environment file ${path}`, { cause: error });
+    }
+    for (const [name, value] of Object.entries(values))
+        if (value !== undefined && process.env[name] === undefined)
+            process.env[name] = value;
+}

package/dist/src/cli.js

@@ -2,13 +2,12 @@
 import { realpathSync, statSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, relative, 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 { readCliConfiguration } from "./cli-config.js";
 import { defaultValidationTimeoutMs } from "./defaults.js";
 import { Runner } from "./runner.js";
 import { Store } from "./store.js";
@@ -18,27 +17,9 @@ const program = new Command()
     .name("agent-workflows")
     .description("Local durable issue-to-review workflows")
     .option("-c, --config <file>", "configuration path", "agent-workflows.json")
-    .option("--config-base-directory <directory>", "base directory for paths contained in configuration")
-    .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;
-    }
-});
+    .option("--config-base-directory <directory>", "base directory for paths contained in configuration");
 async function configuration() {
-    return configSchema.parse(JSON.parse(await readFile(configPath(), "utf8")));
+    return readCliConfiguration(configPath(), (path) => resolve(configBaseDirectory(), path));
 }
 function configPath() {
     return resolve(launchDirectory, program.opts().config);
@@ -67,6 +48,9 @@ function databaseUrl(config) {
 }
 async function withStore(action) {
     const config = await configuration();
+    await withConfiguredStore(config, action);
+}
+async function withConfiguredStore(config, action) {
     const store = new Store(databaseUrl(config), config.id);
     try {
         await store.initialize();
@@ -181,6 +165,9 @@ program
     const record = await store.run(run);
     const invocations = (await store.invocations(run)).filter((item) => !options.invocation || item.id === options.invocation);
     const paths = [
+        ...(!options.invocation
+            ? (record.stageLogs?.map((item) => item.path) ?? [])
+            : []),
         ...invocations.map((item) => item.log),
         ...(!options.invocation
             ? (record.validation?.map((check) => check.log) ?? [])
@@ -196,7 +183,7 @@ program
         }
     }
 }));
-for (const kind of ["pause", "resume", "stop", "retry", "recover"])
+for (const kind of ["pause", "resume", "stop", "recover"])
     program
         .command(`${kind} <target>`)
         .description(`${kind} project or run through the active runner`)
@@ -206,13 +193,24 @@ for (const kind of ["pause", "resume", "stop", "retry", "recover"])
             status: "pending",
         }));
     }));
+program
+    .command("retry <target>")
+    .description("retry a run through the active runner")
+    .option("--refresh-issue", "use the current hosted issue for the new run")
+    .action(async (target, options) => withStore(async (store) => {
+    console.log(JSON.stringify({
+        commandId: await store.request(options.refreshIssue ? "retry-refresh" : "retry", target),
+        status: "pending",
+    }));
+}));
 program
     .command("monitor")
     .option("--notify", "notify when an observed execution reaches an outcome")
     .action(async (options) => {
+    const config = await configuration();
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         throw new Error("Monitor requires an interactive terminal; use status --json instead");
-    await withStore(async (store) => {
+    await withConfiguredStore(config, async (store) => {
         await render(React.createElement(Monitor, {
             source: store,
             notificationWriter: options.notify

package/dist/src/config.d.ts

@@ -51,6 +51,11 @@ export declare const projectSchema: z.ZodObject<{
         args: z.ZodDefault<z.ZodArray<z.ZodString>>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>>;
+    validationProfiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>>>;
     includeAgentCoAuthors: z.ZodDefault<z.ZodBoolean>;
     agent: z.ZodObject<{
         provider: z.ZodEnum<{
@@ -144,6 +149,11 @@ export declare const configSchema: z.ZodObject<{
             args: z.ZodDefault<z.ZodArray<z.ZodString>>;
             timeoutMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>>;
+        validationProfiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>>>;
         includeAgentCoAuthors: z.ZodDefault<z.ZodBoolean>;
         agent: z.ZodObject<{
             provider: z.ZodEnum<{

package/dist/src/config.js

@@ -29,6 +29,11 @@ export const stageSchema = z
         : undefined,
 })
     .refine((stage) => stage.prompt === undefined || stage.promptFile === undefined, "Specify either prompt or promptFile, never both");
+const validationCommandSchema = z.strictObject({
+    command: z.string().min(1),
+    args: z.array(z.string()).default([]),
+    timeoutMs: z.number().int().positive().default(defaultValidationTimeoutMs),
+});
 export const projectSchema = z.strictObject({
     id: z.string().regex(/^[a-zA-Z0-9_-]+$/),
     checkout: z.string().min(1),
@@ -49,17 +54,10 @@ export const projectSchema = z.strictObject({
         .includes("{issue}")
         .default("agent/{issue}-{attempt}"),
     pollIntervalMs: z.number().int().min(100).default(30_000),
-    validation: z
-        .array(z.strictObject({
-        command: z.string().min(1),
-        args: z.array(z.string()).default([]),
-        timeoutMs: z
-            .number()
-            .int()
-            .positive()
-            .default(defaultValidationTimeoutMs),
-    }))
-        .default([]),
+    validation: z.array(validationCommandSchema).default([]),
+    validationProfiles: z
+        .record(z.string().regex(/^[a-zA-Z0-9_-]+$/), z.array(validationCommandSchema).min(1))
+        .default({}),
     includeAgentCoAuthors: z.boolean().default(true),
     agent: profileSchema,
     stages: z

package/dist/src/domain.d.ts

@@ -135,6 +135,7 @@ export interface RunRecord {
     attempt: number;
     retryOf?: string;
     issue: Issue;
+    validationProfile?: string;
     outcome: Outcome;
     phase: string;
     createdAt: string;
@@ -152,6 +153,11 @@ export interface RunRecord {
     reviewHead?: string;
     error?: string;
     failedStep?: number;
+    stageLogs?: Array<{
+        executionId: string;
+        step: string;
+        path: string;
+    }>;
     executions?: ExecutionRecord[];
 }
 export declare class BlockedError extends Error {

package/dist/src/invocation.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { type Stage } from "./config.js";
-import { type ContributionCandidate, type RunRecord, type Snapshot } from "./domain.js";
+import { type RunRecord } from "./domain.js";
 import { type ChangeEvidence } from "./evidence.js";
 import type { OperationDependencies } from "./operations.js";
 export interface InvocationTask {
@@ -17,9 +17,7 @@ interface StageExecution {
     task: InvocationTask;
     stepId: number;
     dependencies: OperationDependencies;
-    saveImplementationSnapshot: (runId: string, snapshot: Snapshot, provider: string) => Promise<ContributionCandidate | undefined>;
-    acceptContribution: (runId: string, candidate: ContributionCandidate) => 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, acceptContribution, }: StageExecution): Promise<string>;
+export declare function invokeStage(execution: StageExecution): Promise<string>;
 export {};