@mingchuno/agent-workflows 0.1.0

package/dist/src/adapters/hosting.js

@@ -0,0 +1,275 @@
+import { Gitlab } from "@gitbeaker/rest";
+import { Octokit } from "@octokit/rest";
+import { BlockedError, } from "../domain.js";
+function origin(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash)
+        throw new Error("Hosting origin must not contain credentials, query or fragment");
+    if (url.protocol !== "https:" &&
+        !(url.protocol === "http:" &&
+            ["127.0.0.1", "localhost"].includes(url.hostname)))
+        throw new Error("Hosting origin requires HTTPS");
+    return url.href.replace(/\/$/, "");
+}
+function token(project) {
+    const value = process.env[project.hosting.tokenEnv];
+    if (!value)
+        throw new Error(`Missing credential environment variable: ${project.hosting.tokenEnv}`);
+    return value;
+}
+function marker(runId, suffix = "") {
+    return `<!-- agent-workflows:${runId}${suffix} -->`;
+}
+export function inlineFindings(review, diff) {
+    const lines = new Map();
+    let path = "", line = 0;
+    for (const text of diff.split("\n")) {
+        if (text.startsWith("+++ b/")) {
+            path = text.slice(6);
+            lines.set(path, new Set());
+        }
+        else if (text.startsWith("@@")) {
+            line = Number(/\+(\d+)/.exec(text)?.[1] ?? 0);
+        }
+        else if (text.startsWith("+")) {
+            lines.get(path)?.add(line);
+            line++;
+        }
+        else if (!text.startsWith("-") && !text.startsWith("\\"))
+            line++;
+    }
+    return review.findings.filter((finding) => !!finding.path &&
+        !!finding.line &&
+        !!lines.get(finding.path)?.has(finding.line));
+}
+function reviewPresentation(input) {
+    const inline = inlineFindings(input.review, input.diff);
+    const body = [
+        `Review of ${input.head}`,
+        input.review.summary,
+        ...input.review.findings
+            .filter((finding) => !inline.includes(finding))
+            .map((finding) => finding.body),
+        marker(input.runId),
+    ].join("\n\n");
+    return { inline, body };
+}
+export class GitHubHosting {
+    identity;
+    client;
+    repo;
+    constructor(project) {
+        const host = origin(project.hosting.origin);
+        const [owner, repo, ...extra] = project.hosting.repository.split("/");
+        if (!owner || !repo || extra.length)
+            throw new Error("GitHub repository must be owner/repo");
+        this.repo = { owner, repo };
+        this.identity = `${host}/${owner}/${repo}`;
+        this.client = new Octokit({
+            auth: token(project),
+            baseUrl: host === "https://github.com"
+                ? "https://api.github.com"
+                : `${host}/api/v3`,
+            request: { timeout: 30000, redirect: "error" },
+        });
+    }
+    async listIssues(labels) {
+        const issues = await this.client.paginate(this.client.issues.listForRepo, {
+            ...this.repo,
+            state: "open",
+            labels: labels.join(","),
+            per_page: 100,
+        });
+        return issues
+            .filter((issue) => !issue.pull_request)
+            .map((issue) => ({
+            id: String(issue.id),
+            number: issue.number,
+            title: issue.title,
+            body: issue.body ?? "",
+            url: issue.html_url,
+            labels: issue.labels.map((label) => typeof label === "string" ? label : (label.name ?? "")),
+            open: issue.state === "open",
+        }));
+    }
+    async getIssue(number) {
+        const { data } = await this.client.issues.get({
+            ...this.repo,
+            issue_number: number,
+        });
+        return {
+            id: String(data.id),
+            number: data.number,
+            title: data.title,
+            body: data.body ?? "",
+            url: data.html_url,
+            labels: data.labels.map((label) => typeof label === "string" ? label : (label.name ?? "")),
+            open: data.state === "open" && !data.pull_request,
+        };
+    }
+    async findChange(branch) {
+        const changes = await this.client.paginate(this.client.pulls.list, {
+            ...this.repo,
+            head: `${this.repo.owner}:${branch}`,
+            state: "all",
+            per_page: 100,
+        });
+        if (changes.length > 1)
+            throw new BlockedError("Multiple change requests match branch");
+        const change = changes[0];
+        return change
+            ? { id: change.number, url: change.html_url, head: change.head.sha }
+            : undefined;
+    }
+    async createChange(input) {
+        const { data } = await this.client.pulls.create({
+            ...this.repo,
+            head: input.branch,
+            base: input.base,
+            title: input.publication.title,
+            body: `${input.publication.description}\n\nRefs ${input.issue.url}\n${marker(input.runId)}`,
+            draft: true,
+        });
+        return { id: data.number, url: data.html_url, head: data.head.sha };
+    }
+    async head(change) {
+        return (await this.client.pulls.get({ ...this.repo, pull_number: change.id })).data.head.sha;
+    }
+    async publishReview(input) {
+        const reviews = await this.client.paginate(this.client.pulls.listReviews, {
+            ...this.repo,
+            pull_number: input.change.id,
+            per_page: 100,
+        });
+        if (reviews.some((review) => review.body?.includes(marker(input.runId))))
+            return;
+        if ((await this.head(input.change)) !== input.head)
+            throw new BlockedError("Review stale: head changed");
+        const { inline, body } = reviewPresentation(input);
+        await this.client.pulls.createReview({
+            ...this.repo,
+            pull_number: input.change.id,
+            commit_id: input.head,
+            event: "COMMENT",
+            body,
+            comments: inline.map((finding) => ({
+                path: finding.path,
+                line: finding.line,
+                side: "RIGHT",
+                body: finding.body,
+            })),
+        });
+    }
+}
+export class GitLabHosting {
+    identity;
+    client;
+    repository;
+    constructor(project) {
+        const host = origin(project.hosting.origin);
+        this.repository = project.hosting.repository;
+        this.identity = `${host}/${this.repository}`;
+        this.client = new Gitlab({
+            host,
+            token: token(project),
+            queryTimeout: 30000,
+        });
+    }
+    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}`);
+    }
+    async listIssues(labels) {
+        const issues = await this.client.Issues.all({
+            projectId: this.repository,
+            state: "opened",
+            labels: labels.join(","),
+            perPage: 100,
+        });
+        return issues.map((issue) => ({
+            id: String(issue.id),
+            number: issue.iid,
+            title: issue.title,
+            body: issue.description ?? "",
+            url: issue.web_url,
+            labels: issue.labels,
+            open: issue.state === "opened",
+        }));
+    }
+    async getIssue(number) {
+        const issue = await this.client.Issues.show(number, {
+            projectId: this.repository,
+        });
+        return {
+            id: String(issue.id),
+            number: issue.iid,
+            title: issue.title,
+            body: issue.description ?? "",
+            url: issue.web_url,
+            labels: issue.labels.map((label) => typeof label === "string" ? label : label.name),
+            open: issue.state === "opened",
+        };
+    }
+    async findChange(branch) {
+        const changes = await this.client.MergeRequests.all({
+            projectId: this.repository,
+            sourceBranch: branch,
+            perPage: 100,
+        });
+        if (changes.length > 1)
+            throw new BlockedError("Multiple merge requests match branch");
+        const change = changes[0];
+        return change
+            ? { id: change.iid, url: change.web_url, head: change.sha }
+            : undefined;
+    }
+    async createChange(input) {
+        const change = await this.client.MergeRequests.create(this.repository, input.branch, input.base, `Draft: ${input.publication.title}`, {
+            description: `${input.publication.description}\n\nRefs ${input.issue.url}\n${marker(input.runId)}`,
+            removeSourceBranch: false,
+        });
+        return { id: change.iid, url: change.web_url, head: change.sha };
+    }
+    async head(change) {
+        return (await this.client.MergeRequests.show(this.repository, change.id))
+            .sha;
+    }
+    async publishReview(input) {
+        const notes = await this.client.MergeRequestNotes.all(this.repository, input.change.id, { perPage: 100 });
+        if (notes.some((note) => note.body.includes(marker(input.runId))))
+            return;
+        const change = await this.client.MergeRequests.show(this.repository, input.change.id);
+        if (change.sha !== input.head)
+            throw new BlockedError("Review stale: head changed");
+        const { inline, body } = reviewPresentation(input);
+        for (const [index, finding] of inline.entries()) {
+            const tag = marker(input.runId, `:inline:${index}`);
+            if (notes.some((note) => note.body.includes(tag)))
+                continue;
+            const refs = change.diff_refs;
+            if (!refs)
+                throw new BlockedError("GitLab diff refs unavailable");
+            await this.client.MergeRequestDiscussions.create(this.repository, input.change.id, `${finding.body}\n\n${tag}`, {
+                position: {
+                    positionType: "text",
+                    baseSha: refs.base_sha,
+                    startSha: refs.start_sha,
+                    headSha: input.head,
+                    newPath: finding.path,
+                    oldPath: finding.path,
+                    newLine: String(finding.line),
+                },
+            });
+        }
+        if ((await this.head(input.change)) !== input.head)
+            throw new BlockedError("Review stale: head changed");
+        await this.client.MergeRequestNotes.create(this.repository, input.change.id, body);
+    }
+}
+export function createHosting(project) {
+    return project.hosting.provider === "github"
+        ? new GitHubHosting(project)
+        : new GitLabHosting(project);
+}

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

@@ -0,0 +1,43 @@
+import type { ModelInfo, SessionConfig } from "@github/copilot-sdk";
+import type { ThreadEvent, ThreadOptions } from "@openai/codex-sdk";
+import type { AgentProfile } from "../config.js";
+export interface WorkerInput {
+    provider: "codex" | "copilot";
+    operation: string;
+    id: string;
+    cwd: string;
+    prompt: string;
+    profile: AgentProfile;
+    skills: string[];
+    readOnly: boolean;
+    processFile?: string;
+    timeoutMs?: number;
+}
+export type Emit = (type: string, value: unknown) => void;
+export interface CodexClient {
+    startThread(options: ThreadOptions): {
+        runStreamed(prompt: string): Promise<{
+            events: AsyncIterable<ThreadEvent>;
+        }>;
+    };
+}
+export declare function runCodex(client: CodexClient, input: WorkerInput, emit: Emit): Promise<void>;
+export interface CopilotSessionClient {
+    sessionId: string;
+    on(handler: (event: unknown) => void): unknown;
+    sendAndWait(message: {
+        prompt: string;
+    }, timeout: number): Promise<{
+        data: {
+            content: string;
+        };
+    } | undefined>;
+    disconnect(): Promise<void>;
+}
+export interface CopilotClientContract {
+    listModels(): Promise<ModelInfo[]>;
+    createSession(options: SessionConfig): Promise<CopilotSessionClient>;
+    stop(): Promise<Error[]>;
+    forceStop(): Promise<void>;
+}
+export declare function runCopilot(client: CopilotClientContract, input: WorkerInput, emit: Emit): Promise<void>;

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

@@ -0,0 +1,64 @@
+import { dirname } from "node:path";
+export async function runCodex(client, input, emit) {
+    const thread = client.startThread({
+        workingDirectory: input.cwd,
+        model: input.profile.model,
+        modelReasoningEffort: input.profile
+            .reasoningEffort,
+        sandboxMode: input.readOnly ? "read-only" : "workspace-write",
+        approvalPolicy: "never",
+    });
+    const turn = await thread.runStreamed(input.prompt);
+    let output = "";
+    for await (const event of turn.events) {
+        if (event.type === "thread.started")
+            emit("session", event.thread_id);
+        emit("event", event);
+        if (event.type === "item.completed" && event.item.type === "agent_message")
+            output = event.item.text;
+        if (event.type === "turn.failed")
+            throw new Error(event.error.message);
+        if (event.type === "error")
+            throw new Error(event.message);
+    }
+    emit("result", output);
+}
+export async function runCopilot(client, input, emit) {
+    try {
+        if (input.operation === "models") {
+            emit("result", JSON.stringify((await client.listModels()).map((model) => ({
+                id: model.id,
+                reasoningEfforts: model.supportedReasoningEfforts ?? [],
+                contextWindowTokens: model.capabilities.limits.max_context_window_tokens,
+            }))));
+            return;
+        }
+        const session = await client.createSession({
+            sessionId: input.id,
+            model: input.profile.model,
+            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" },
+        });
+        emit("session", session.sessionId);
+        session.on((event) => emit("event", event));
+        const response = await session.sendAndWait({ prompt: input.prompt }, input.timeoutMs ?? 1_800_000);
+        emit("result", response?.data.content ?? "");
+        await session.disconnect();
+    }
+    finally {
+        const errors = await client.stop();
+        if (errors.length) {
+            await client.forceStop();
+            // biome-ignore lint/correctness/noUnsafeFinally: Preserve the existing shutdown-failure contract.
+            throw new AggregateError(errors, "Copilot shutdown failed");
+        }
+    }
+}

package/dist/src/cli.d.ts

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

package/dist/src/cli.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+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 { Runner } from "./runner.js";
+import { Store } from "./store.js";
+import { Monitor } from "./tui.js";
+const program = new Command()
+    .name("agent-workflows")
+    .description("Local durable issue-to-review workflows")
+    .option("-c, --config <file>", "configuration path", "agent-workflows.json");
+async function configuration() {
+    return configSchema.parse(JSON.parse(await readFile(resolve(program.opts().config), "utf8")));
+}
+function databaseUrl(config) {
+    const value = process.env[config.databaseUrlEnv];
+    if (!value)
+        throw new Error(`Set ${config.databaseUrlEnv} to a PostgreSQL URL`);
+    return value;
+}
+async function withStore(action) {
+    const config = await configuration();
+    const store = new Store(databaseUrl(config), config.id);
+    try {
+        await store.initialize();
+        await action(store);
+    }
+    finally {
+        await store.close();
+    }
+}
+program
+    .command("init")
+    .description("Write a configuration scaffold without overwriting files")
+    .action(async () => {
+    const config = {
+        id: "local",
+        databaseUrlEnv: "AGENT_WORKFLOWS_DATABASE_URL",
+        stateDirectory: resolve(".agent-workflows"),
+        projects: [
+            {
+                id: "example",
+                checkout: process.cwd(),
+                hosting: {
+                    provider: "github",
+                    origin: "https://github.com",
+                    repository: "OWNER/REPOSITORY",
+                    tokenEnv: "GITHUB_TOKEN",
+                },
+                labels: ["ready-for-agent"],
+                baseBranch: "main",
+                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.",
+                    },
+                    review: {
+                        prompt: "Review correctness, safety and the issue acceptance criteria.",
+                    },
+                },
+            },
+        ],
+    };
+    await writeFile(resolve(program.opts().config), JSON.stringify(config, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+    console.log("Created configuration. Set repository, checkout, identity and credentials before running.");
+});
+program
+    .command("run")
+    .option("-p, --project <ids...>", "run selected project IDs")
+    .action(async (options) => {
+    const config = await configuration();
+    if (options.project) {
+        const wanted = new Set(options.project);
+        for (const id of wanted)
+            if (!config.projects.some((project) => project.id === id))
+                throw new Error(`Unknown project ${id}`);
+        config.projects = config.projects.filter((project) => wanted.has(project.id));
+    }
+    const runner = new Runner({
+        config,
+        databaseUrl: databaseUrl(config),
+        hosting: createHosting,
+        agents: createAgents(),
+    });
+    try {
+        await runner.start();
+        console.log(`Runner ${config.id} started. Use status or monitor in another terminal.`);
+        await new Promise((resolve) => {
+            process.once("SIGINT", resolve);
+            process.once("SIGTERM", resolve);
+        });
+    }
+    finally {
+        await runner.shutdown();
+    }
+});
+program
+    .command("status")
+    .option("--json", "machine-readable output")
+    .action(async (options) => withStore(async (store) => {
+    const status = {
+        projects: await store.projects(),
+        runs: await store.runs(),
+        commands: await store.commands(),
+    };
+    if (options.json)
+        console.log(JSON.stringify(status));
+    else
+        for (const project of status.projects) {
+            console.log(`${project.id}: ${project.blocked ? "blocked" : project.paused ? "paused" : "enabled"}`);
+            for (const run of status.runs.filter((run) => run.projectId === project.id))
+                console.log(`  ${run.id} #${run.issue.number} attempt ${run.attempt}: ${run.outcome} / ${run.phase}`);
+        }
+}));
+program.command("inspect <run>").action(async (run) => withStore(async (store) => console.log(JSON.stringify({
+    run: await store.run(run),
+    invocations: await store.invocations(run),
+}, null, 2))));
+program
+    .command("logs <run>")
+    .option("--invocation <id>", "specific invocation")
+    .action(async (run, options) => withStore(async (store) => {
+    const record = await store.run(run);
+    const invocations = (await store.invocations(run)).filter((item) => !options.invocation || item.id === options.invocation);
+    const paths = [
+        ...invocations.map((item) => item.log),
+        ...(!options.invocation
+            ? (record.validation?.map((check) => check.log) ?? [])
+            : []),
+    ];
+    for (const path of paths) {
+        console.log(`--- ${path}`);
+        try {
+            console.log(await readFile(path, "utf8"));
+        }
+        catch {
+            console.log("Artifact unavailable");
+        }
+    }
+}));
+for (const kind of ["pause", "resume", "stop", "retry"])
+    program
+        .command(`${kind} <target>`)
+        .description(`${kind} project or run through the active runner`)
+        .action(async (target) => withStore(async (store) => {
+        console.log(JSON.stringify({
+            commandId: await store.request(kind, target),
+            status: "pending",
+        }));
+    }));
+program.command("monitor").action(async () => {
+    if (!process.stdin.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();
+    });
+});
+try {
+    await program.parseAsync();
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}