@mingchuno/agent-workflows 0.2.0 → 0.3.0

package/docs/operations.md

@@ -15,7 +15,7 @@ All commands accept `--config PATH` before the subcommand.
 | `stop RUN`                         | Queue cancellation; success means active local work has stopped |
 | `recover RUN`                      | Continue a failed publication step using completed checkpoints |
 | `retry RUN`                        | Queue an explicit new attempt after checkout validation         |
-| `monitor`                          | Attach an interactive terminal view                             |
+| `monitor [--notify]`               | Attach an interactive terminal view; optionally alert on outcomes |
 
 Control commands return a command ID and `pending`; inspect `status --json` or the monitor for success/failure. With no runner, commands stay pending. Run and monitor are separate processes. Closing the monitor never cancels work. Ctrl-C on the runner stops intake, cancels active work, waits for process termination and releases ownership. Queued issues remain durable for the next start.
 
@@ -27,10 +27,37 @@ prove that a runner is alive. Requires an interactive terminal of at least
 compact terminals show the focused pane. Titles and identifiers are available
 in full in scrollable details. `NO_COLOR=1` disables semantic colors.
 
+`monitor --notify` emits one desktop notification when an Execution first
+reaches `completed`, `failed`, `blocked`, `cancelled`, `no-change` or
+`ineligible` during that monitor session. The initial snapshot is silent;
+later terminal Executions are detected across every visible project, including
+Executions first seen after a database reconnection. Delivery uses OSC 9 and is
+best-effort: notifications are not persisted, retried or acknowledged, and a
+terminal write failure does not affect monitoring or workflow state. Current
+iTerm2, Kitty, WezTerm and Ghostty releases are supported; other OSC 9
+implementations may work, while Windows Terminal is not supported in this
+version. Terminal permissions and settings determine whether an alert appears,
+including whether foreground alerts are suppressed.
+
+The notification payload is display-only and contains only
+`agent-workflows: <project> · <issue reference> · <outcome>`. It excludes issue
+titles, diagnostics, paths and internal Run, Execution and session identifiers.
+Under tmux, the monitor emits one layer of DCS passthrough wrapping. tmux 3.3
+and later requires `set -g allow-passthrough on`; the CLI does not change tmux
+configuration.
+
+Run details is one responsive, vertically scrollable document. It leads with
+the issue, outcome, phase, attempt, total elapsed time and branch, and adds an
+attention summary only when operator action may be required. At 140 columns
+and above, execution history appears beside validation and agent-session
+evidence; narrower terminals stack those sections in the same reading order.
+The primary design target is 160×48, with 80×24 retained as the functional
+fallback. An overflowing document shows its visible line range in the heading.
+
 | Context | Keys |
 | --- | --- |
 | Dashboard | Left/Right project; Tab/Shift+Tab pane; Up/Down selection or scroll |
-| Details | Enter opens; Up/Down or PgUp/PgDn scroll; Esc returns |
+| Details | Enter opens; Up/Down or PgUp/PgDn scroll; Esc returns; `l` opens the latest current-execution session, preferring a running session |
 | Progress | `[`/`]` inspect step history; End follows latest event |
 | Sessions | `a` focuses session list; Up/Down selects invocation; `l` opens log |
 | Validation | `v` opens validation logs |
@@ -61,8 +88,10 @@ Execution duration includes eligibility, preparation and waits within one
 execution. It excludes queue waiting and gaps before publication recovery.
 Details show each execution, its queue wait and the run's total elapsed time.
 Completed execution durations freeze at their first terminal outcome. Records
-without timing evidence show an em dash. Noninteractive tools use `status --json`
-and `inspect`. See [TUI design](tui-redesign.md) for implementation boundaries.
+without timing evidence use factual labels such as `not started`, `not recorded`
+or `unavailable`. Noninteractive tools use `status --json` and `inspect`. Run
+details keeps complete errors under Diagnostics and exact identifiers, paths,
+profiles and ISO timestamps under Technical details.
 
 ## Observability Landscape
 
@@ -116,7 +145,14 @@ Git process journals live in `<git-directory>/agent-workflows-processes/`, indep
 
 Startup and phase boundaries check ownership assumptions, branch/head and actual changes. Unfinished files are never reset, cleaned, stashed or discarded automatically. Dirty files, unresolved Git operations, branch collisions, unexpected mutations and ambiguous agent recovery become inspectable blocked states. Other eligible projects continue.
 
-Publication effects have independent DBOS checkpoints. A task commit carries `Agent-Workflows-Run`; commit recovery checks parent and marker, push recovery checks the remote ref, request creation checks the source branch, and review publication checks stable markers. Transient publication failures use bounded retries and reconciliation. Interrupted agent stages block rather than starting another writer.
+Publication effects have independent DBOS checkpoints. A task commit preserves
+publication trailers, carries exactly one `Agent-Workflows-Run`, and by default
+adds co-author trailers for providers with retained writable contributions.
+Commit reconciliation checks the expected parent, change set, finalized message,
+and clean checkout. Push recovery checks the remote ref, request creation checks
+the source branch, and review publication checks stable markers. Transient
+publication failures use bounded retries and reconciliation. Interrupted agent
+stages block rather than starting another writer.
 
 ## Publication recovery
 
@@ -156,6 +192,10 @@ A failed review after publication remains a failed automation attempt, even if i
 
 Git hooks are disabled for application-authored task commits; configure required checks as validation commands. Changed symlinks and submodules require manual handling. Checkout checks detect boundary changes but do not sandbox custom adapters or prevent unrelated local tools from writing.
 
+Git chooses author and committer through its normal configuration and environment
+rules. Runner startup performs no identity preflight; missing identity fails at
+the commit step before push or hosting publication.
+
 Validation records say exactly which command ran, when, its exit code and artifact path. No-change work skips publication. Generated commit/request text is validated and saved before Git/API writes. Logs, prompts and errors redact configured credentials and recognized secret environment values; this does not sanitize arbitrary repository content or secrets unknown to the runner.
 
 Back up both PostgreSQL and the state directory if history/artifacts matter. The checkout and runtime session stores are separate local state. Losing them cannot be repaired from DBOS checkpoints alone. Do not change a custom workflow's step order or rename projects while its runs are pending; use a new workflow version and finish or explicitly resolve existing runs first.

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,7 +17,7 @@ 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: {

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.2.0",
+  "version": "0.3.0",
   "description": "Local durable coding workflows on DBOS",
   "type": "module",
   "license": "MIT",