@mingchuno/agent-workflows 0.2.0 → 0.4.0

package/README.md

@@ -38,7 +38,12 @@ 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; for GitHub, follow the [PAT creation and required permissions](docs/providers.md#create-a-fine-grained-personal-access-token) guide before running. Commit or ignore the configuration before running. Keep the state directory outside managed checkouts, or explicitly Git-ignore it.
+Edit `agent-workflows.json`: set the checkout, hosting origin/repository, agent
+stages and validation commands. Relative checkout, state and prompt-file paths
+resolve from the configuration file's directory. Commits use native Git identity
+and disclose retained writable agent contributions with default-enabled co-author
+trailers. Set the named hosting-token environment variable through your usual
+secret manager; for GitHub, follow the [PAT creation and required permissions](docs/providers.md#create-a-fine-grained-personal-access-token) guide before running. Commit or ignore the configuration before running. Keep the state directory outside managed checkouts, or explicitly Git-ignore it.
 
 ```sh
 agent-workflows run
@@ -47,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.
 
@@ -71,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 --`.
@@ -87,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/attribution.d.ts

@@ -0,0 +1,9 @@
+import type { Project } from "./config.js";
+import type { ContributionCandidate, Publication, Snapshot } from "./domain.js";
+export declare const agentCoAuthors: {
+    readonly codex: "Codex <noreply@openai.com>";
+    readonly copilot: "Copilot <223556219+Copilot@users.noreply.github.com>";
+};
+export type AttributedProvider = keyof typeof agentCoAuthors;
+export declare function contributingProviders(candidates: ContributionCandidate[], final: Snapshot): AttributedProvider[];
+export declare function finalizeCommitMessage(publication: Publication, project: Project, providers: AttributedProvider[], runId: string): Publication;

package/dist/src/attribution.js

@@ -0,0 +1,57 @@
+export const agentCoAuthors = {
+    codex: "Codex <noreply@openai.com>",
+    copilot: "Copilot <223556219+Copilot@users.noreply.github.com>",
+};
+const trailerLine = /^([A-Za-z0-9][A-Za-z0-9-]*):[ \t]*(\S.*)$/;
+function normalizedTrailer(line) {
+    const match = trailerLine.exec(line);
+    return match ? `${match[1]}:${match[2]}`.toLowerCase() : undefined;
+}
+function retained(candidate, final) {
+    const paths = new Set([
+        ...Object.keys(candidate.beforeFiles),
+        ...Object.keys(candidate.afterFiles),
+    ]);
+    return [...paths].some((path) => candidate.beforeFiles[path] !== candidate.afterFiles[path] &&
+        candidate.beforeFiles[path] !== final.files[path]);
+}
+export function contributingProviders(candidates, final) {
+    const providers = new Set();
+    for (const candidate of candidates) {
+        if (!(candidate.provider in agentCoAuthors) || !retained(candidate, final))
+            continue;
+        providers.add(candidate.provider);
+    }
+    return [...providers];
+}
+export function finalizeCommitMessage(publication, project, providers, runId) {
+    const identities = project.includeAgentCoAuthors
+        ? providers.map((provider) => agentCoAuthors[provider])
+        : [];
+    const matching = new Set(identities.map((identity) => `co-authored-by:${identity}`.toLowerCase()));
+    const lines = publication.commitMessage
+        .split(/\r?\n/)
+        .filter((line) => !line.trim().toLowerCase().startsWith("agent-workflows-run:"));
+    while (lines.at(-1)?.trim() === "")
+        lines.pop();
+    const separator = lines.findLastIndex((line) => line.trim() === "");
+    const possibleTrailers = lines.slice(separator + 1);
+    const hasTrailerBlock = separator >= 0 &&
+        possibleTrailers.length > 0 &&
+        possibleTrailers.every((line) => trailerLine.test(line) || /^\s+\S/.test(line));
+    const body = hasTrailerBlock ? lines.slice(0, separator) : lines;
+    while (body.at(-1)?.trim() === "")
+        body.pop();
+    const existingTrailers = hasTrailerBlock
+        ? possibleTrailers.filter((line) => !matching.has(normalizedTrailer(line.trim()) ?? ""))
+        : [];
+    const finalizedTrailers = [
+        ...existingTrailers,
+        ...identities.map((identity) => `Co-authored-by: ${identity}`),
+        `Agent-Workflows-Run: ${runId}`,
+    ];
+    return {
+        ...publication,
+        commitMessage: `${body.join("\n")}\n\n${finalizedTrailers.join("\n")}`,
+    };
+}

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

@@ -1,42 +1,44 @@
 #!/usr/bin/env -S node --
+import { realpathSync, statSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
-import { basename, dirname, resolve } from "node:path";
-import { parseEnv } from "node:util";
+import { basename, dirname, relative, 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 { readCliConfiguration } from "./cli-config.js";
 import { defaultValidationTimeoutMs } from "./defaults.js";
 import { Runner } from "./runner.js";
 import { Store } from "./store.js";
-import { Monitor } from "./tui/index.js";
+import { createTerminalNotificationWriter, Monitor } from "./tui/index.js";
 const launchDirectory = process.cwd();
 const program = new Command()
     .name("agent-workflows")
     .description("Local durable issue-to-review workflows")
     .option("-c, --config <file>", "configuration path", "agent-workflows.json")
-    .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;
+    .option("--config-base-directory <directory>", "base directory for paths contained in configuration");
+async function configuration() {
+    return readCliConfiguration(configPath(), (path) => resolve(configBaseDirectory(), path));
+}
+function configPath() {
+    return resolve(launchDirectory, program.opts().config);
+}
+function configBaseDirectory() {
+    const selected = program.opts().configBaseDirectory;
+    const path = selected
+        ? resolve(launchDirectory, selected)
+        : dirname(configPath());
+    let canonical;
     try {
-        contents = await readFile(file, "utf8");
+        canonical = realpathSync(path);
     }
     catch (error) {
-        throw new Error(`Cannot read environment file ${file} (${error.code ?? "read failed"})`);
+        throw new Error(`Configuration path base is not an existing directory: ${path}`, { cause: error });
     }
-    for (const [name, value] of Object.entries(parseEnv(contents))) {
-        if (process.env[name] === undefined)
-            process.env[name] = value;
-    }
-});
-async function configuration() {
-    return configSchema.parse(JSON.parse(await readFile(resolve(program.opts().config), "utf8")));
+    if (!statSync(canonical).isDirectory())
+        throw new Error(`Configuration path base is not an existing directory: ${path}`);
+    return canonical;
 }
 function databaseUrl(config) {
     const value = process.env[config.databaseUrlEnv];
@@ -46,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();
@@ -59,14 +64,18 @@ program
     .command("init")
     .description("Write a configuration scaffold without overwriting files")
     .action(async () => {
+    const base = configBaseDirectory();
+    const checkout = process.cwd();
+    const externalState = resolve(checkout, "..", `${basename(checkout)}.agent-workflows`);
+    const portable = (path) => relative(base, path) || ".";
     const config = {
         id: "local",
         databaseUrlEnv: "AGENT_WORKFLOWS_DATABASE_URL",
-        stateDirectory: resolve("..", `${basename(process.cwd())}.agent-workflows`),
+        stateDirectory: portable(externalState),
         projects: [
             {
                 id: "example",
-                checkout: process.cwd(),
+                checkout: portable(checkout),
                 hosting: {
                     provider: "github",
                     origin: "https://github.com",
@@ -76,7 +85,7 @@ program
                 labels: ["ready-for-agent"],
                 baseBranch: "main",
                 branchTemplate: "agent/{issue}-{attempt}",
-                gitIdentity: { name: "YOUR NAME", email: "you@example.com" },
+                includeAgentCoAuthors: true,
                 agent: { provider: "codex" },
                 validation: [
                     {
@@ -89,8 +98,11 @@ program
             },
         ],
     };
-    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.");
+    await writeFile(configPath(), JSON.stringify(config, null, 2) + "\n", {
+        flag: "wx",
+        mode: 0o600,
+    });
+    console.log("Created configuration. Set repository and credentials before running.");
 });
 program
     .command("run")
@@ -105,7 +117,7 @@ program
         config.projects = config.projects.filter((project) => wanted.has(project.id));
     }
     const runner = new Runner({
-        promptBaseDirectory: dirname(resolve(program.opts().config)),
+        pathBaseDirectory: configBaseDirectory(),
         config,
         databaseUrl: databaseUrl(config),
         hosting: createHosting,
@@ -178,13 +190,20 @@ for (const kind of ["pause", "resume", "stop", "retry", "recover"])
             status: "pending",
         }));
     }));
-program.command("monitor").action(async () => {
+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 render(React.createElement(Monitor, { source: store }), {
-            alternateScreen: true,
-        }).waitUntilExit();
+    await withConfiguredStore(config, async (store) => {
+        await render(React.createElement(Monitor, {
+            source: store,
+            notificationWriter: options.notify
+                ? createTerminalNotificationWriter()
+                : undefined,
+        }), { alternateScreen: true }).waitUntilExit();
     });
 });
 try {

package/dist/src/config.d.ts

@@ -51,10 +51,7 @@ export declare const projectSchema: z.ZodObject<{
         args: z.ZodDefault<z.ZodArray<z.ZodString>>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>>;
-    gitIdentity: z.ZodObject<{
-        name: z.ZodString;
-        email: z.ZodEmail;
-    }, z.core.$strict>;
+    includeAgentCoAuthors: z.ZodDefault<z.ZodBoolean>;
     agent: z.ZodObject<{
         provider: z.ZodEnum<{
             codex: "codex";
@@ -147,10 +144,7 @@ export declare const configSchema: z.ZodObject<{
             args: z.ZodDefault<z.ZodArray<z.ZodString>>;
             timeoutMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>>;
-        gitIdentity: z.ZodObject<{
-            name: z.ZodString;
-            email: z.ZodEmail;
-        }, z.core.$strict>;
+        includeAgentCoAuthors: z.ZodDefault<z.ZodBoolean>;
         agent: z.ZodObject<{
             provider: z.ZodEnum<{
                 codex: "codex";

package/dist/src/config.js

@@ -60,7 +60,7 @@ export const projectSchema = z.strictObject({
             .default(defaultValidationTimeoutMs),
     }))
         .default([]),
-    gitIdentity: z.strictObject({ name: z.string().min(1), email: z.email() }),
+    includeAgentCoAuthors: z.boolean().default(true),
     agent: profileSchema,
     stages: z
         .strictObject({

package/dist/src/domain.d.ts

@@ -47,6 +47,11 @@ export interface Snapshot {
     paths: string[];
     files: Record<string, string | null>;
 }
+export interface ContributionCandidate {
+    provider: string;
+    beforeFiles: Record<string, string | null>;
+    afterFiles: Record<string, string | null>;
+}
 export interface Workspace {
     check(project: Project): Promise<void>;
     prepare(project: Project, branch: string, signal?: AbortSignal): Promise<Snapshot>;
@@ -140,6 +145,8 @@ export interface RunRecord {
     snapshot?: Snapshot;
     validation?: ValidationResult[];
     publication?: Publication;
+    contributionCandidates?: ContributionCandidate[];
+    contributingProviders?: string[];
     change?: ChangeRequest;
     review?: Review;
     reviewHead?: string;

package/dist/src/invocation.d.ts

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

package/dist/src/invocation.js

@@ -3,12 +3,12 @@ import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { z } from "zod";
 import { resolveProfile } from "./config.js";
-import { BlockedError } from "./domain.js";
+import { BlockedError, } from "./domain.js";
 import { verifyEvidence } from "./evidence.js";
 import { resolveStagePrompt, sha256 } from "./prompts.js";
 const maxInvocationAttempts = 2;
 /** One logical stage; only returned format errors admit a second response attempt. */
-export async function invokeStage({ run, name, stage, task, stepId, dependencies, saveImplementationSnapshot, }) {
+export async function invokeStage({ run, name, stage, task, stepId, dependencies, saveImplementationSnapshot, acceptContribution, }) {
     const { store, project, agents, signal, workspace, redact } = dependencies;
     const previous = (await store.invocations(run.id)).filter((item) => item.stepId === stepId);
     if (previous.length) {
@@ -56,6 +56,7 @@ export async function invokeStage({ run, name, stage, task, stepId, dependencies
     const directory = join(dependencies.artifacts, run.id);
     await mkdir(directory, { recursive: true, mode: 0o700 });
     let correction = "";
+    let pendingContribution;
     for (let attempt = 1; attempt <= maxInvocationAttempts; attempt++) {
         invocationSignal.throwIfAborted();
         const expected = (await store.run(run.id)).snapshot;
@@ -118,7 +119,7 @@ export async function invokeStage({ run, name, stage, task, stepId, dependencies
             if (readOnly)
                 await workspace.verify(project, expected);
             else
-                await saveImplementationSnapshot(run.id, expected);
+                pendingContribution = await saveImplementationSnapshot(run.id, expected, profile.provider);
             if (task.evidence)
                 await verifyEvidence(task.evidence);
             invocationSignal.throwIfAborted();
@@ -144,6 +145,8 @@ export async function invokeStage({ run, name, stage, task, stepId, dependencies
                 correction = `\n\nCorrect the prior response format in this fresh inspection-only session. Do not modify files.\nPrior invalid response:\n${output}\nValidation errors:\n${String(error)}`;
                 continue;
             }
+            if (pendingContribution)
+                await acceptContribution(run.id, pendingContribution);
             record.outcome = "completed";
             return redact(task.outputContract ? JSON.stringify(parsed) : output);
         }

package/dist/src/operations.d.ts

@@ -26,6 +26,7 @@ export declare class Operations {
     prepare(): Promise<void>;
     invoke(name: string, stage: Stage, task: InvocationTask): Promise<string>;
     private saveImplementationSnapshot;
+    private acceptContribution;
     implement(): Promise<void>;
     validate(): Promise<boolean>;
     private prepareEvidence;

package/dist/src/operations.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { contributingProviders, finalizeCommitMessage } from "./attribution.js";
 import { BlockedError, isBlockedError, publicationSchema, reviewSchema, } from "./domain.js";
 import { captureEvidence, evidenceContext, } from "./evidence.js";
 import { invokeStage } from "./invocation.js";
@@ -103,15 +104,32 @@ export class Operations {
             task,
             stepId: DBOS.stepID,
             dependencies: this.dependencies,
-            saveImplementationSnapshot: (runId, expected) => this.saveImplementationSnapshot(runId, expected),
+            saveImplementationSnapshot: (runId, expected, provider) => this.saveImplementationSnapshot(runId, expected, provider),
+            acceptContribution: (runId, candidate) => this.acceptContribution(runId, candidate),
         }));
     }
-    async saveImplementationSnapshot(runId, expected) {
+    async saveImplementationSnapshot(runId, expected, provider) {
         const { workspace, project, store } = this.dependencies;
         const snapshot = await workspace.inspect(project);
         if (snapshot.head !== expected.head || snapshot.branch !== expected.branch)
             throw new BlockedError("Agent changed branch or committed unexpectedly");
         await store.patchRun(runId, { snapshot });
+        return snapshot.fingerprint === expected.fingerprint
+            ? undefined
+            : {
+                provider,
+                beforeFiles: expected.files,
+                afterFiles: snapshot.files,
+            };
+    }
+    async acceptContribution(runId, candidate) {
+        const run = await this.dependencies.store.run(runId);
+        await this.dependencies.store.patchRun(runId, {
+            contributionCandidates: [
+                ...(run.contributionCandidates ?? []),
+                candidate,
+            ],
+        });
     }
     async implement() {
         await this.invoke("implementation", this.dependencies.project.stages.implementation, {
@@ -206,8 +224,12 @@ export class Operations {
             context: (run) => `${evidenceContext(evidence)}\nIssue: ${JSON.stringify(run.issue)}\nValidation: ${JSON.stringify(run.validation ?? [])}`,
         });
         await this.step("publication-content", async (run) => {
+            if (!run.snapshot)
+                throw new Error("Missing publication snapshot");
+            const providers = contributingProviders(run.contributionCandidates ?? [], run.snapshot);
             await this.dependencies.store.patchRun(run.id, {
-                publication: publicationSchema.parse(JSON.parse(output)),
+                publication: finalizeCommitMessage(publicationSchema.parse(JSON.parse(output)), this.dependencies.project, providers, run.id),
+                contributingProviders: providers,
             });
         });
     }

package/dist/src/runner.d.ts

@@ -3,6 +3,7 @@ import { type AgentAdapter, type HostingAdapter, type Workspace } from "./domain
 import { Operations } from "./operations.js";
 import { Store } from "./store.js";
 export interface RunnerOptions {
+    pathBaseDirectory?: string;
     promptBaseDirectory?: string;
     config: Configuration;
     databaseUrl: string;
@@ -19,6 +20,7 @@ export declare class Runner {
     private readonly controllers;
     private readonly active;
     private readonly hosting;
+    private readonly promptBaseDirectory;
     private workflow;
     private readonly ownership;
     private stopping;

package/dist/src/runner.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { realpathSync, statSync } from "node:fs";
 import { mkdir, realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { DBOS } from "@dbos-inc/dbos-sdk";
@@ -22,6 +23,7 @@ export class Runner {
     controllers = new Map();
     active = new Map();
     hosting = new Map();
+    promptBaseDirectory;
     workflow;
     ownership = new CheckoutOwnership();
     stopping = false;
@@ -33,8 +35,16 @@ export class Runner {
     constructor(options) {
         this.options = options;
         this.config = configSchema.parse(options.config);
+        const pathBaseDirectory = canonicalDirectory(options.pathBaseDirectory ?? process.cwd(), "Configuration path base");
+        this.config.stateDirectory = resolve(pathBaseDirectory, this.config.stateDirectory);
         for (const project of this.config.projects)
-            projectPrompts(project, options.promptBaseDirectory);
+            project.checkout = resolve(pathBaseDirectory, project.checkout);
+        const promptBaseDirectory = options.promptBaseDirectory
+            ? resolve(options.promptBaseDirectory)
+            : pathBaseDirectory;
+        this.promptBaseDirectory = promptBaseDirectory;
+        for (const project of this.config.projects)
+            projectPrompts(project, promptBaseDirectory);
         this.store = new Store(options.databaseUrl, this.config.id, this.redact);
     }
     queue(id) {
@@ -49,7 +59,7 @@ export class Runner {
         const ids = new Set();
         for (const project of this.config.projects) {
             project.checkout = await realpath(project.checkout);
-            await assertEvidenceDirectory(project.checkout, this.config.stateDirectory);
+            this.config.stateDirectory = await assertEvidenceDirectory(project.checkout, this.config.stateDirectory);
             if (canonical.has(project.checkout) || ids.has(project.id))
                 throw new Error("Duplicate project identity or canonical checkout");
             canonical.add(project.checkout);
@@ -277,7 +287,7 @@ export class Runner {
         const workspace = this.options.workspace ?? new ExistingCheckout();
         let recoveryChecked = false;
         const operations = new Operations(runId, {
-            promptBaseDirectory: this.options.promptBaseDirectory,
+            promptBaseDirectory: this.promptBaseDirectory,
             store: this.store,
             project,
             workspace,
@@ -495,3 +505,18 @@ export class Runner {
         await this.store.close();
     }
 }
+function canonicalDirectory(path, label) {
+    const resolved = resolve(path);
+    let canonical;
+    try {
+        canonical = realpathSync(resolved);
+    }
+    catch (error) {
+        throw new Error(`${label} is not an existing directory: ${resolved}`, {
+            cause: error,
+        });
+    }
+    if (!statSync(canonical).isDirectory())
+        throw new Error(`${label} is not an existing directory: ${resolved}`);
+    return canonical;
+}

package/dist/src/tui/data.d.ts

@@ -1,5 +1,6 @@
 import type { RunRecord } from "../domain.js";
 import type { EventRecord, InvocationRecord, ProjectState, Store } from "../store.js";
+import { type ExecutionNotificationWriter } from "./notifications.js";
 export interface MonitorSource {
     projects: Store["projects"];
     runs: Store["runs"];
@@ -12,7 +13,7 @@ export type MonitorAction = "pause" | "resume" | "stop" | "retry" | "recover";
 export declare function useMonitorData(source: MonitorSource, selection: {
     projectId?: string;
     runId?: string;
-}): {
+}, notificationWriter?: ExecutionNotificationWriter): {
     projects: ProjectState[];
     project: ProjectState | undefined;
     projectRuns: RunRecord[];

package/dist/src/tui/data.js

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 import { tuiRefreshIntervalMs } from "./constants.js";
-export function useMonitorData(source, selection) {
+import { ExecutionNotificationObserver, } from "./notifications.js";
+export function useMonitorData(source, selection, notificationWriter) {
     const [projects, setProjects] = useState([]);
     const [runs, setRuns] = useState([]);
     const [detail, setDetail] = useState({ sessions: [], events: [] });
@@ -10,6 +11,9 @@ export function useMonitorData(source, selection) {
     const [pending, setPending] = useState();
     const pendingRef = useRef(undefined);
     const mounted = useRef(true);
+    const notificationObserver = useRef(notificationWriter
+        ? new ExecutionNotificationObserver(notificationWriter)
+        : undefined).current;
     const project = projects.find((item) => item.id === selection.projectId) ?? projects[0];
     const projectRuns = runs.filter((item) => item.projectId === project?.id);
     const run = projectRuns.find((item) => item.id === selection.runId) ?? projectRuns[0];
@@ -38,6 +42,7 @@ export function useMonitorData(source, selection) {
                     return;
                 setProjects(nextProjects);
                 setRuns(nextRuns);
+                notificationObserver?.observe(nextRuns);
                 if (selectedRunId) {
                     const [sessions, nextEvents] = await Promise.all([
                         source.invocations(selectedRunId),
@@ -71,7 +76,7 @@ export function useMonitorData(source, selection) {
             closed = true;
             clearInterval(timer);
         };
-    }, [source, selectedRunId]);
+    }, [source, selectedRunId, notificationObserver]);
     useEffect(() => {
         if (!pending || pending === "submitting")
             return;