@mingchuno/agent-workflows 0.1.0 → 0.3.0

package/examples/config.ts

@@ -1,13 +1,13 @@
 import { configSchema } from "@mingchuno/agent-workflows";
 
-/** Replace paths, repository, identity and model IDs with locally available values. */
+/** Replace paths, repository and model IDs with locally available values. */
 export const configuration = configSchema.parse({
   id: "local",
-  stateDirectory: "/absolute/path/outside-the-checkout/agent-workflows-state",
+  stateDirectory: "../application.agent-workflows",
   projects: [
     {
       id: "application",
-      checkout: "/absolute/path/to/existing-checkout",
+      checkout: ".",
       hosting: {
         provider: "gitlab",
         origin: "https://git.example.com/gitlab",
@@ -17,13 +17,13 @@ export const configuration = configSchema.parse({
       labels: ["ready-for-agent"],
       baseBranch: "main",
       branchTemplate: "agent/{issue}-{attempt}",
-      gitIdentity: { name: "Workflow Agent", email: "agent@example.com" },
+      includeAgentCoAuthors: true,
       agent: { provider: "codex" },
       stages: {
         implementation: {
           prompt: "Implement the issue and follow repository guidance.",
         },
-        writing: {
+        publication: {
           profile: { provider: "copilot" },
           prompt:
             "Write concise publication text from the diff and validation evidence.",
@@ -45,7 +45,7 @@ export const modelOverrides = {
     model: "YOUR_CODEX_MODEL",
     reasoningEffort: "high",
   },
-  writing: {
+  publication: {
     provider: "copilot" as const,
     model: "YOUR_COPILOT_MODEL",
     reasoningEffort: "low",

package/examples/run.ts

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import {
   configSchema,
   createAgents,
@@ -7,13 +8,15 @@ import {
 } from "@mingchuno/agent-workflows";
 import { reportingWorkflow } from "./custom-workflow.js";
 
+const configPath = resolve(process.argv[2] ?? "agent-workflows.json");
 const config = configSchema.parse(
-  JSON.parse(await readFile(process.argv[2] ?? "agent-workflows.json", "utf8")),
+  JSON.parse(await readFile(configPath, "utf8")),
 );
 const databaseUrl = process.env[config.databaseUrlEnv];
 if (!databaseUrl) throw new Error(`Set ${config.databaseUrlEnv}`);
 const runner = new Runner({
   config,
+  pathBaseDirectory: dirname(configPath),
   databaseUrl,
   hosting: createHosting,
   agents: createAgents(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingchuno/agent-workflows",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Local durable coding workflows on DBOS",
   "type": "module",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "pack:smoke": "pnpm build && node scripts/test.mjs --pack-smoke",
     "release:publish": "node scripts/publish.mjs",
     "lint:pr": "node scripts/lint-pr-title.mjs",
-    "start": "tsx src/cli.ts",
+    "start": "node --import tsx -- src/cli.ts",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "biome check .",
@@ -60,6 +60,8 @@
     "pg": "^8.23.0",
     "pino": "^10.3.1",
     "react": "^19.3.0",
+    "string-width": "^8.2.2",
+    "wrap-ansi": "^9.0.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/dist/src/tui-data.js

@@ -1,89 +0,0 @@
-import { useEffect, useState } from "react";
-export function useMonitorData(source, selection) {
-    const { projectIndex, runIndex } = selection;
-    const [projects, setProjects] = useState([]);
-    const [runs, setRuns] = useState([]);
-    const [sessions, setSessions] = useState([]), [events, setEvents] = useState([]);
-    const [message, setMessage] = useState("Connecting…"), [pending, setPending] = useState();
-    const project = projects[projectIndex];
-    const projectRuns = runs.filter((run) => run.projectId === project?.id);
-    const run = projectRuns[runIndex];
-    const selectedRunId = run?.id;
-    useEffect(() => {
-        let closed = false, busy = false;
-        const update = async () => {
-            if (busy)
-                return;
-            busy = true;
-            try {
-                const [nextProjects, nextRuns] = await Promise.all([
-                    source.projects(),
-                    source.runs(),
-                ]);
-                if (closed)
-                    return;
-                setProjects(nextProjects);
-                setRuns(nextRuns);
-                if (selectedRunId) {
-                    const [nextSessions, nextEvents] = await Promise.all([
-                        source.invocations(selectedRunId),
-                        source.events(0, selectedRunId),
-                    ]);
-                    if (closed)
-                        return;
-                    setSessions(nextSessions);
-                    setEvents(nextEvents.filter((event) => event.runId === selectedRunId));
-                }
-                else {
-                    setSessions([]);
-                    setEvents([]);
-                }
-                if (pending) {
-                    const command = (await source.commands()).find((command) => command.id === pending);
-                    if (command && command.status !== "pending") {
-                        setMessage(`${command.kind}: ${command.status}${command.error ? ` — ${command.error}` : ""}`);
-                        setPending(undefined);
-                    }
-                }
-                else
-                    setMessage((current) => current === "Connecting…" ? "Connected" : current);
-            }
-            catch (error) {
-                if (!closed)
-                    setMessage(`Connection error: ${String(error)}`);
-            }
-            finally {
-                busy = false;
-            }
-        };
-        void update();
-        const timer = setInterval(() => void update(), 400);
-        return () => {
-            closed = true;
-            clearInterval(timer);
-        };
-    }, [source, selectedRunId, pending]);
-    const action = async (kind, target) => {
-        setMessage(`${kind}: pending`);
-        setPending("submitting");
-        try {
-            setPending(await source.request(kind, target));
-        }
-        catch (error) {
-            setPending(undefined);
-            setMessage(`${kind}: failed — ${String(error)}`);
-        }
-    };
-    return {
-        projects,
-        project,
-        projectRuns,
-        run,
-        sessions,
-        events,
-        message,
-        setMessage,
-        pending,
-        action,
-    };
-}

package/dist/src/tui.d.ts

@@ -1,5 +0,0 @@
-import { type MonitorSource } from "./tui-data.js";
-export type { MonitorSource } from "./tui-data.js";
-export declare function Monitor({ source }: {
-    source: MonitorSource;
-}): import("react").JSX.Element;

package/dist/src/tui.js

@@ -1,69 +0,0 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { readFile } from "node:fs/promises";
-import { Box, Text, useApp, useInput } from "ink";
-import { useState } from "react";
-import { useMonitorData } from "./tui-data.js";
-export function Monitor({ source }) {
-    const { exit } = useApp();
-    const [projectIndex, setProjectIndex] = useState(0), [runIndex, setRunIndex] = useState(0), [sessionIndex, setSessionIndex] = useState(0), [stepIndex, setStepIndex] = useState(0), [validationIndex, setValidationIndex] = useState(0);
-    const { projects, project, projectRuns, run, sessions, events, message, setMessage, pending, action, } = useMonitorData(source, { projectIndex, runIndex });
-    const [log, setLog] = useState("");
-    const session = sessions[sessionIndex];
-    const steps = events.filter((event) => event.kind === "step");
-    const selectedStep = steps[stepIndex];
-    const showLog = (path) => {
-        void readFile(path, "utf8").then((text) => setLog(text.split("\n").slice(-8).join("\n")), (error) => setMessage(`Log unavailable: ${String(error)}`));
-    };
-    useInput((input, key) => {
-        if (input === "q") {
-            exit();
-            return;
-        }
-        if (key.leftArrow || key.rightArrow) {
-            setProjectIndex((index) => Math.max(0, Math.min(projects.length - 1, index + (key.rightArrow ? 1 : -1))));
-            setRunIndex(0);
-            setSessionIndex(0);
-            setStepIndex(0);
-            setValidationIndex(0);
-            setLog("");
-        }
-        if (key.upArrow || key.downArrow) {
-            setRunIndex((index) => Math.max(0, Math.min(projectRuns.length - 1, index + (key.downArrow ? 1 : -1))));
-            setSessionIndex(0);
-            setStepIndex(0);
-            setValidationIndex(0);
-            setLog("");
-        }
-        if (key.tab) {
-            setSessionIndex((index) => (index + 1) % Math.max(sessions.length, 1));
-            setLog("");
-        }
-        if (input === "l" && session)
-            showLog(session.log);
-        if (input === "[" || input === "]")
-            setStepIndex((index) => Math.max(0, Math.min(steps.length - 1, index + (input === "]" ? 1 : -1))));
-        if (input === "v" && run?.validation?.length) {
-            const check = run.validation[validationIndex % run.validation.length];
-            setMessage(`Validation: ${check.command} · exit ${check.exitCode}`);
-            showLog(check.log);
-            setValidationIndex((index) => index + 1);
-        }
-        if (pending)
-            return;
-        if (input === "p" && project)
-            void action(project.paused ? "resume" : "pause", project.id);
-        if (input === "s" && run)
-            void action("stop", run.id);
-        if (input === "r" && run)
-            void action("retry", run.id);
-    });
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, children: "Agent Workflows \u00B7 Monitor" }), _jsx(Text, { children: "\u2190 \u2192 project \u00B7 \u2191 \u2193 run \u00B7 [ ] step/attempt \u00B7 Tab session \u00B7 l agent log \u00B7 v validation log \u00B7 p pause/resume \u00B7 s stop \u00B7 r retry \u00B7 q close" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: project
-                            ? `${project.id} · ${project.paused ? "intake paused" : "intake enabled"} · ${projectRuns.filter((run) => run.outcome === "queued").length} queued`
-                            : "No projects registered. Start the runner to populate this view." }), project?.blocked && (_jsxs(Text, { color: "yellow", children: ["Blocked: ", project.blocked] })), projectRuns
-                        .slice(Math.max(0, runIndex - 1), runIndex + 2)
-                        .map((item) => (_jsxs(Text, { inverse: item.id === run?.id, children: [item.id === run?.id ? ">" : " ", " #", item.issue.number, " \u00B7 attempt", " ", item.attempt, " \u00B7 ", item.outcome, " \u00B7 ", item.phase] }, item.id))), project && projectRuns.length === 0 && (_jsx(Text, { children: "No runs yet. Eligible issues appear after polling." }))] }), run && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, children: ["Run ", run.id] }), _jsx(Text, { children: run.issue.title }), run.error && _jsx(Text, { color: "red", children: run.error }), _jsxs(Text, { children: ["Validation:", " ", run.validation
-                                ?.map((check) => `${check.command}: exit ${check.exitCode}`)
-                                .join(" · ") || "No checks recorded"] }), _jsxs(Text, { children: ["Step/attempt event ", steps.length ? stepIndex + 1 : 0, "/", steps.length, ":", " ", selectedStep
-                                ? JSON.stringify(selectedStep.payload)
-                                : "No steps recorded"] }), _jsxs(Text, { bold: true, children: ["Agent sessions \u00B7 ", sessions.length] }), session ? (_jsxs(_Fragment, { children: [_jsxs(Text, { children: [session.step, " \u00B7 invocation ", session.attempt, " \u00B7", " ", session.outcome] }), _jsxs(Text, { children: ["Session: ", session.sessionId ?? session.sessionState] }), _jsxs(Text, { children: ["Requested: ", JSON.stringify(session.requested)] }), _jsxs(Text, { children: ["Effective: ", JSON.stringify(session.effective)] }), _jsxs(Text, { children: ["Log: ", session.log] })] })) : (_jsx(Text, { children: "No agent sessions recorded" })), log && _jsx(Text, { children: log })] })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: message }) }), _jsx(Text, { dimColor: true, children: "Closing this monitor leaves the runner and its tasks running." })] }));
-}

package/docs/acceptance.md

@@ -1,35 +0,0 @@
-# Phase 1 review guide
-
-Implementation scope is the unchanged [specification in issue #1](https://github.com/mingchuno/agent-workflows/issues/1). Review the public contracts first, then the workspace/recovery boundaries. No task-specific worktrees, clones, merges or automatic review/fix loops are implemented.
-
-| Acceptance area                                                     | Implementation / behavioral evidence                                                                                                                                  |
-| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Existing checkout, clean startup, branch policy and base transition | `ExistingCheckout`; real Git tests cover dirty files, collisions, unresolved Git operations, mutation detection and next-task base                                    |
-| Durable default workflow and extension                              | `Operations`, `defaultWorkflow`; PostgreSQL runner tests and the executable reporting-workflow example                                                                |
-| Deduplication, one task/project, independent progress               | Instance-qualified task keys, DBOS concurrency-one queues; all four agent/host combinations and multi-project tests                                                   |
-| GitHub/GitLab intake and publication                                | Octokit/Gitbeaker contracts; pagination, PR exclusion, label queries, custom GitLab root/credentials, draft MR and inline review fixtures                             |
-| Agent profiles, SDKs, prompts and sessions                          | Isolated SDK workers; profile/default isolation, supported-setting rejection, SDK argument/event contracts and invocation records                                     |
-| Validation and generated publication                                | Actual Git diff/fingerprints, schema-checked text; failed validation, malformed text, no-change and timeout tests                                                     |
-| Recovery and external effects                                       | Process-level interruptions after edits, commit, push, request creation and review publication; blocked ambiguous agent recovery and no duplicate publication effects |
-| Cancellation and ownership                                          | Real stubborn child process, journals, local leases, advisory locks; cancellation/reuse and duplicate-owner tests                                                     |
-| Independent exact-revision review                                   | Fresh sessions, published diff/head context, added-line mapping and stale-head rejection                                                                              |
-| Public observability and controls                                   | Store query/subscription, retained sessions, timestamps, artifacts, credential redaction, CLI JSON and explicit retries                                               |
-| CLI/TUI                                                             | Init/error/help tests; keyboard step/session navigation, live state and action feedback; controls share application commands                                          |
-| SDK documentation                                                   | Quickstart, configuration, API, providers, operations/recovery and type-checked examples; reporting example runs with controlled adapters                             |
-
-## Local verification
-
-Run `pnpm check`, `pnpm test`, `pnpm build`, and `pnpm lint`. Tests create a disposable PostgreSQL database unless `TEST_DATABASE_URL` is set, use real temporary Git repositories, and use controlled agents/hosting endpoints. `pnpm audit --prod` checks runtime dependency advisories. The GitHub Actions job supplies the same fixture boundary on Linux.
-
-The implementation was verified locally on macOS with Node 24 and PostgreSQL 17. Remote CI has not run for this uncommitted working tree. No authenticated live Codex/Copilot model invocation, real GitHub publication or real GitLab instance smoke test was performed. Those require a deliberately chosen test repository and provider access and are separate from deterministic acceptance.
-
-## Deliberate operational boundaries
-
-- Interrupted agent work blocks if ownership/state is ambiguous; it never starts another writer merely because DBOS recovered.
-- Explicit retry creates a new attempt from the base after the developer restores a clean checkout. It preserves the previous run and branch and does not silently amend an existing PR/MR.
-- Runtime context controls are supported only where exposed by the provider; unknown defaults remain unknown. Codex explicit-model validation depends on its local model catalog or an injected catalog.
-- Git hooks are disabled for the application-authored task commit; configure required checks as validation commands. Changed symlinks and submodules require manual handling.
-- The runner assumes exclusive checkout use. It detects boundary changes but does not sandbox arbitrary custom adapters or prevent every unrelated local tool write.
-- macOS/Linux process groups are required. Windows startup fails explicitly.
-
-Human review should concentrate on cancellation/ownership, recovery reconciliation and adapter permissions before enabling unattended work on a real repository. Completion means the automation has published its draft and review, not that the code is approved.