@mingchuno/agent-workflows 0.1.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mingchuno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# Agent Workflows
+
+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.
+
+## Quickstart
+
+Prerequisites: Node.js 22.12+, Git, PostgreSQL 17+, and an authenticated Codex or Copilot runtime. macOS and Linux are supported; Windows process-group ownership is not supported.
+
+```sh
+npm install -g @mingchuno/agent-workflows
+createdb agent_workflows
+export AGENT_WORKFLOWS_DATABASE_URL="postgresql://$(id -un)@localhost/agent_workflows"
+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.
+
+```sh
+agent-workflows run
+# In a second terminal:
+agent-workflows monitor
+agent-workflows status --json
+```
+
+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
+
+```ts
+import { Runner, createAgents, createHosting } from "@mingchuno/agent-workflows";
+
+const runner = new Runner({
+  config,
+  databaseUrl,
+  agents: createAgents(),
+  hosting: createHosting,
+});
+await runner.start();
+// Later, stop intake and terminate in-flight local work safely:
+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.
+
+## 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 --`.
+
+```sh
+mise trust
+mise install
+pnpm install --frozen-lockfile
+pnpm verify
+pnpm pack:smoke
+```
+
+Use `pnpm start --help` to run the CLI from source. `pnpm build` emits the runtime and declarations into `dist/src` and copies migrations to `dist/drizzle`.
+
+`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)
+- [Public SDK API and composition](docs/api.md)
+- [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)

package/dist/drizzle/0000_initial.sql

@@ -0,0 +1,45 @@
+-- Bootstrap also adopts the identical pre-Drizzle schema without replacing data.
+CREATE SCHEMA IF NOT EXISTS "agent_workflows";
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "agent_workflows"."commands" (
+	"id" text PRIMARY KEY NOT NULL,
+	"scope" text NOT NULL,
+	"kind" text NOT NULL,
+	"target" text NOT NULL,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "agent_workflows"."events" (
+	"sequence" bigserial PRIMARY KEY NOT NULL,
+	"scope" text NOT NULL,
+	"run_id" text,
+	"kind" text NOT NULL,
+	"payload" jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "agent_workflows"."invocations" (
+	"scope" text NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
+	"run_id" text NOT NULL,
+	"record" jsonb NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "agent_workflows"."projects" (
+	"scope" text NOT NULL,
+	"id" text NOT NULL,
+	"paused" boolean DEFAULT false NOT NULL,
+	"blocked" text,
+	CONSTRAINT "projects_pkey" PRIMARY KEY("scope","id")
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "agent_workflows"."runs" (
+	"scope" text NOT NULL,
+	"id" text PRIMARY KEY NOT NULL,
+	"task_key" text NOT NULL,
+	"attempt" integer NOT NULL,
+	"record" jsonb NOT NULL,
+	CONSTRAINT "runs_scope_task_key_attempt_key" UNIQUE("scope","task_key","attempt")
+);

package/dist/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,264 @@
+{
+  "id": "01de7257-12b0-4332-97f8-28f6221d632d",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "agent_workflows.commands": {
+      "name": "commands",
+      "schema": "agent_workflows",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "target": {
+          "name": "target",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "agent_workflows.events": {
+      "name": "events",
+      "schema": "agent_workflows",
+      "columns": {
+        "sequence": {
+          "name": "sequence",
+          "type": "bigserial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "payload": {
+          "name": "payload",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "agent_workflows.invocations": {
+      "name": "invocations",
+      "schema": "agent_workflows",
+      "columns": {
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "record": {
+          "name": "record",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "agent_workflows.projects": {
+      "name": "projects",
+      "schema": "agent_workflows",
+      "columns": {
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "paused": {
+          "name": "paused",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "blocked": {
+          "name": "blocked",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "projects_pkey": {
+          "name": "projects_pkey",
+          "columns": [
+            "scope",
+            "id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "agent_workflows.runs": {
+      "name": "runs",
+      "schema": "agent_workflows",
+      "columns": {
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "task_key": {
+          "name": "task_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "attempt": {
+          "name": "attempt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "record": {
+          "name": "record",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "runs_scope_task_key_attempt_key": {
+          "name": "runs_scope_task_key_attempt_key",
+          "nullsNotDistinct": false,
+          "columns": [
+            "scope",
+            "task_key",
+            "attempt"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {
+    "agent_workflows": "agent_workflows"
+  },
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/dist/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1789854954887,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/dist/src/adapters/agent-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/adapters/agent-worker.js

@@ -0,0 +1,16 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { CopilotClient } from "@github/copilot-sdk";
+import { Codex } from "@openai/codex-sdk";
+import { runCodex, runCopilot } from "./sdk-protocol.js";
+const input = JSON.parse(await readFile(process.argv[2], "utf8"));
+if (input.processFile)
+    await writeFile(input.processFile, JSON.stringify({ pid: process.pid }), {
+        mode: 0o600,
+    });
+const emit = (type, value) => {
+    process.stdout.write(`AW:${JSON.stringify({ type, value })}\n`);
+};
+if (input.provider === "codex")
+    await runCodex(new Codex(), input, emit);
+else
+    await runCopilot(new CopilotClient(), input, emit);

package/dist/src/adapters/agents.d.ts

@@ -0,0 +1,24 @@
+import type { AgentProfile } from "../config.js";
+import type { AgentAdapter, AgentInvocation, EffectiveProfile } from "../domain.js";
+interface ModelCapability {
+    id: string;
+    reasoningEfforts: string[];
+    contextWindowTokens?: number;
+}
+export interface SDKAgentOptions {
+    models?: ModelCapability[];
+}
+/** Runs each SDK invocation in an owned process group; no cross-stage session reuse. */
+export declare class SDKAgent implements AgentAdapter {
+    readonly provider: "codex" | "copilot";
+    readonly options: SDKAgentOptions;
+    constructor(provider: "codex" | "copilot", options?: SDKAgentOptions);
+    validate(profile: AgentProfile, signal?: AbortSignal): Promise<EffectiveProfile>;
+    invoke(invocation: AgentInvocation): Promise<string>;
+    private worker;
+}
+export declare function createAgents(): {
+    codex: SDKAgent;
+    copilot: SDKAgent;
+};
+export {};

package/dist/src/adapters/agents.js

@@ -0,0 +1,142 @@
+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 { command } from "../runtime/process.js";
+/** Runs each SDK invocation in an owned process group; no cross-stage session reuse. */
+export class SDKAgent {
+    provider;
+    options;
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.options = options;
+    }
+    async validate(profile, signal) {
+        if (profile.provider !== this.provider)
+            throw new Error("Profile provider does not match adapter");
+        if (this.provider === "codex" && profile.context)
+            throw new Error("Codex SDK does not expose runtime context controls");
+        const context = profile.context;
+        if (context &&
+            (context.backgroundCompactionThreshold ?? 0.8) >=
+                (context.bufferExhaustionThreshold ?? 0.95))
+            throw new Error("Background compaction threshold must precede buffer exhaustion");
+        let models = this.options.models;
+        if (!models &&
+            this.provider === "codex" &&
+            (profile.model || profile.reasoningEffort)) {
+            try {
+                const cache = JSON.parse(await readFile(join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "models_cache.json"), "utf8"));
+                models = cache.models.map((model) => ({
+                    id: model.slug,
+                    reasoningEfforts: model.supported_reasoning_levels?.map((level) => level.effort) ??
+                        [],
+                    contextWindowTokens: model.context_window,
+                }));
+            }
+            catch {
+                throw new Error("Cannot validate explicit Codex settings: refresh the local Codex model catalog or supply SDKAgent models");
+            }
+        }
+        if (!models &&
+            this.provider === "copilot" &&
+            (profile.model || profile.reasoningEffort)) {
+            const result = await this.worker({ operation: "models" }, undefined, signal);
+            models = JSON.parse(result);
+        }
+        const model = models?.find((candidate) => candidate.id === profile.model);
+        if (profile.model && !model)
+            throw new Error(`Model capability information unavailable: ${profile.model}`);
+        if (profile.reasoningEffort &&
+            !model?.reasoningEfforts.includes(profile.reasoningEffort))
+            throw new Error(`Unsupported reasoning effort ${profile.reasoningEffort} for ${profile.model ?? "unspecified model"}`);
+        return {
+            provider: this.provider,
+            model: profile.model ?? "unknown",
+            reasoningEffort: profile.reasoningEffort ?? "unknown",
+            context: context ?? "unknown",
+            contextWindowTokens: model?.contextWindowTokens ?? "unknown",
+        };
+    }
+    async invoke(invocation) {
+        return this.worker({
+            operation: "invoke",
+            id: invocation.id,
+            cwd: invocation.cwd,
+            prompt: invocation.prompt,
+            profile: invocation.profile,
+            skills: invocation.skills,
+            readOnly: invocation.readOnly,
+            timeoutMs: invocation.timeoutMs ?? 1_800_000,
+        }, invocation);
+    }
+    async worker(input, invocation, signal = invocation?.signal) {
+        const directory = await mkdtemp(join(tmpdir(), "agent-workflows-sdk-"));
+        const path = join(directory, "input.json");
+        await writeFile(path, JSON.stringify({
+            ...input,
+            provider: this.provider,
+            processFile: invocation?.processFile,
+        }), { mode: 0o600 });
+        const ownPath = fileURLToPath(import.meta.url);
+        const source = ownPath.endsWith(".ts");
+        const worker = join(dirname(ownPath), `agent-worker.${source ? "ts" : "js"}`);
+        let buffer = "", output = "", events = Promise.resolve();
+        let eventError;
+        const persistenceFailure = new AbortController();
+        try {
+            await command(process.execPath, [
+                ...(source ? ["--import", import.meta.resolve("tsx")] : []),
+                worker,
+                path,
+            ], {
+                cwd: invocation?.cwd ?? process.cwd(),
+                signal: AbortSignal.any([
+                    persistenceFailure.signal,
+                    ...(signal ? [signal] : []),
+                ]),
+                captureOutput: false,
+                processFile: invocation?.processFile,
+                timeoutMs: invocation ? (invocation.timeoutMs ?? 1_800_000) : 30_000,
+                onOutput: (chunk) => {
+                    buffer += chunk;
+                    for (;;) {
+                        const newline = buffer.indexOf("\n");
+                        if (newline < 0)
+                            break;
+                        const line = buffer.slice(0, newline);
+                        buffer = buffer.slice(newline + 1);
+                        if (!line.startsWith("AW:"))
+                            continue;
+                        const message = JSON.parse(line.slice(3));
+                        if (message.type === "result")
+                            output = message.value;
+                        else
+                            events = events
+                                .then(async () => {
+                                if (message.type === "session")
+                                    await invocation?.session(message.value);
+                                else
+                                    await invocation?.event(message.value);
+                            })
+                                .catch((error) => {
+                                eventError = error;
+                                persistenceFailure.abort();
+                            });
+                    }
+                },
+            });
+            await events;
+            if (eventError)
+                throw eventError;
+            return output;
+        }
+        finally {
+            await events;
+            await rm(directory, { recursive: true, force: true });
+        }
+    }
+}
+export function createAgents() {
+    return { codex: new SDKAgent("codex"), copilot: new SDKAgent("copilot") };
+}

package/dist/src/adapters/hosting.d.ts

@@ -0,0 +1,33 @@
+import type { Project } from "../config.js";
+import { type ChangeRequest, type HostingAdapter, type Issue, type Review } from "../domain.js";
+export declare function inlineFindings(review: Review, diff: string): {
+    body: string;
+    path: string;
+    line: number;
+}[];
+export declare class GitHubHosting implements HostingAdapter {
+    readonly identity: string;
+    private readonly client;
+    private readonly repo;
+    constructor(project: Project);
+    listIssues(labels: string[]): Promise<Issue[]>;
+    getIssue(number: number): Promise<Issue>;
+    findChange(branch: string): Promise<ChangeRequest | undefined>;
+    createChange(input: Parameters<HostingAdapter["createChange"]>[0]): Promise<ChangeRequest>;
+    head(change: ChangeRequest): Promise<string>;
+    publishReview(input: Parameters<HostingAdapter["publishReview"]>[0]): Promise<void>;
+}
+export declare class GitLabHosting implements HostingAdapter {
+    readonly identity: string;
+    private readonly client;
+    private readonly repository;
+    constructor(project: Project);
+    preflight(): Promise<void>;
+    listIssues(labels: string[]): Promise<Issue[]>;
+    getIssue(number: number): Promise<Issue>;
+    findChange(branch: string): Promise<ChangeRequest | undefined>;
+    createChange(input: Parameters<HostingAdapter["createChange"]>[0]): Promise<ChangeRequest>;
+    head(change: ChangeRequest): Promise<string>;
+    publishReview(input: Parameters<HostingAdapter["publishReview"]>[0]): Promise<void>;
+}
+export declare function createHosting(project: Project): HostingAdapter;