@nodeint/migent 0.1.3 → 0.1.5

package/README.md

@@ -17,9 +17,9 @@ where the process is.
   - [Supported CLIs](#supported-clis)
   - [Quickstart](#quickstart)
     - [Install](#install)
-    - [Upgrade](#upgrade)
     - [Create a project](#create-a-project)
     - [Run](#run)
+    - [Next](#next)
   - [Concepts](#concepts)
   - [Current scope](#current-scope)
   - [Documentation](#documentation)
@@ -49,7 +49,7 @@ the process, while each provider CLI remains responsible for authentication,
 agent execution, and its own tools and options.
 
 ```mermaid
-flowchart LR
+flowchart TD
     A[Task] --> B[Planner - Codex]
     B -->|plan.md| C[Reviewer - Grok]
     C -->|revise| B
@@ -61,77 +61,92 @@ flowchart LR
 Migent drives each provider through its headless CLI. Install and sign in to the
 ones your configuration names.
 
-| Provider | CLI      |
-| -------- | -------- |
-| Claude   | `claude` |
-| Codex    | `codex`  |
-| Grok     | `grok`   |
+| Provider           | CLI      |
+| -------------------| -------- |
+| Google Antigravity | `agy`    |
+| Claude             | `claude` |
+| Codex              | `codex`  |
+| Grok               | `grok`   |
 
 ## Quickstart
 
-Node.js 22+ on macOS, Linux, or Windows, and authenticated provider CLIs named by your
-configuration.
+Requires Node.js 22+ (macOS, Linux, or Windows) and the provider CLIs your
+config uses, already signed in.
 
 ### Install
 
 ```bash
 npm install -g @nodeint/migent
+migent --version
 ```
 
-Verify with `migent --version`.
-
-### Upgrade
-
-```bash
-npm install -g @nodeint/migent@latest
-```
+Upgrade with `npm install -g @nodeint/migent@latest`.
 
 ### Create a project
 
-From the project where agents will work:
+From the repository where agents will work:
 
 ```bash
-migent init --preset plan
+migent init
 ```
 
-`init` writes the config, a plan-and-review workflow, and a gitignore for local
-session state:
+In a terminal, `init` walks you through the provider, model, and options, then
+offers to install the Migent skill so agents in the project know how to run it.
+Without a terminal, pass `--provider` and `--model` together. Pass `--skill` to
+install the skill without the prompt.
+
+It creates:
 
 ```text
 .migent/
-├── config.yaml
-├── .gitignore
+├── config.yaml        # models and roles
+├── .gitignore         # keeps sessions/ untracked
 └── workflows/
-    └── plan.yaml
-```
+    └── plan.yaml      # plan-and-review workflow
 
-In a terminal, pick the provider, model, and prompted options from the lists.
-Pass `--provider` and `--model` together when input is not a terminal. Commit
-`config.yaml` and `workflows/`. Leave `.migent/sessions/` untracked.
+.agents/skills/migent/ # only if you install the skill
+```
 
-Model and role shape is in [Providers and model configuration](https://github.com/nodeint/migent/blob/main/docs/providers.md).
-A full plan workflow is in [Writing workflows](https://github.com/nodeint/migent/blob/main/docs/workflows.md#complete-example).
+Commit `config.yaml` and `workflows/`. To add the skill later, run
+`migent skill install`.
 
 ### Run
 
-From that project or any of its subdirectories:
+From the project or any subdirectory:
 
 ```bash
-migent start plan --task "Plan the account settings redesign"
+migent session run --workflow plan --task "Plan the account settings redesign"
 ```
 
-Migent runs the next eligible stage until the workflow completes or stops.
-Progress goes to stderr. Stdout is one JSON result.
+`--task` is one line and is stored in the session as `task.md`. For a longer
+task, create the session first, write the file, then start it:
 
 ```bash
-migent sessions
-migent watch <session-id>
-migent continue <session-id>
+migent session prepare wave-3 --workflow plan
+migent session run --session wave-3 --workflow plan
 ```
 
-Command fields and exit codes are in
-[CLI commands and execution controls](https://github.com/nodeint/migent/blob/main/docs/cli.md). Session files are in
-[Sessions and workflow composition](https://github.com/nodeint/migent/blob/main/docs/sessions.md).
+Migent runs each eligible stage until the workflow completes or stops. Omit
+`--workflow` and pass `--role` to run one role instead. A workflow run prints
+one JSON result with the session id, status, stop reason, decision, and output
+paths. A role run prints a table unless `--json`. Stderr prints one line when
+a stage starts and one when it finishes. Then inspect or resume:
+
+```bash
+migent session list
+migent session list --latest --json
+migent session follow <session-id>
+migent session continue <session-id>
+```
+
+`session list --json` and a JSON snapshot omit the task text.
+
+### Next
+
+- [Providers and model configuration](https://github.com/nodeint/migent/blob/main/docs/providers.md)
+- [Writing workflows](https://github.com/nodeint/migent/blob/main/docs/workflows.md#complete-example)
+- [CLI commands and exit codes](https://github.com/nodeint/migent/blob/main/docs/cli.md)
+- [Sessions and workflow composition](https://github.com/nodeint/migent/blob/main/docs/sessions.md)
 
 ## Concepts
 
@@ -147,8 +162,9 @@ A workflow connects stages through dependencies and explicit decision routes.
 - A **session** records executions, events, decisions, and artifacts so work can
   be inspected or resumed.
 
-Use `depends_on` to give a stage upstream artifacts. Use `session.resume_from`
-when the stage must also continue a provider's prior conversational session.
+Use `depends_on` to give a stage upstream artifacts. Every visit of a stage
+continues that stage's provider agent. Use `session.resume_from` when a stage
+must continue a different stage's provider session.
 
 ## Current scope
 

package/dist/commands/agent.js

@@ -1,7 +1,9 @@
-import { AgentToolRunner, CancellationRequested, ConfigurationError, createAgentSession, log, raiseCancellation, requireAgentSession, resolveRoleTarget, SessionStore, } from "@nodeint/migent-kernel";
+import path from "node:path";
+import { AgentToolRunner, CancellationRequested, ConfigurationError, createAgentSession, loadRoleInstructions, loadYamlMapping, log, prependRoleInstructions, requireAgentSession, isSessionLockLost, repairSessionUnlocked, SessionLock, resolveRoleTarget, SessionStore, } from "@nodeint/migent-kernel";
 import { printAgent, printError, printNotice } from "../display.js";
 import { cliHooks } from "../hooks.js";
 import { requireCurrentSchema } from "../migrate.js";
+import { bindCancellationSignals } from "../signals.js";
 import { adapterMap, parseOptions } from "../provider.js";
 import { resolvePrompt } from "../workspace.js";
 export async function dispatchAgent(workspace, args) {
@@ -13,76 +15,126 @@ export async function dispatchAgent(workspace, args) {
         options: Object.keys(parsed).length > 0 ? parsed : null,
     });
     const [resolvedSessionId, createdSession] = resolveSession(workspace, args.sessionId ?? null, args.role, args.task ?? null);
-    let resumeExecutionId = null;
-    if (!createdSession) {
-        const previous = new SessionStore(workspace).latestExecution(resolvedSessionId);
-        if (previous !== null)
-            resumeExecutionId = previous.executionId;
+    if (createdSession)
+        log(`session_id: ${resolvedSessionId}`);
+    let lock;
+    try {
+        lock = SessionLock.acquire(path.join(workspace, ".migent", "sessions", resolvedSessionId));
     }
-    const optionLabel = Object.entries(target.options)
-        .map(([key, value]) => `${key}: ${value}`)
-        .join(", ") || "default";
-    printNotice(`agent ${args.role} · ${target.provider}/${target.model} (${optionLabel}).`);
-    const onSigint = () => {
-        try {
-            raiseCancellation(2);
-        }
-        catch {
-            // The runner observes the pending cancellation.
-        }
-    };
-    const onSigterm = () => {
-        try {
-            raiseCancellation(15);
-        }
-        catch {
-            // The runner observes the pending cancellation.
+    catch (error) {
+        if (error instanceof Error) {
+            printError(error.message);
+            return 2;
         }
-    };
-    process.on("SIGINT", onSigint);
-    process.on("SIGTERM", onSigterm);
-    let result;
+        throw error;
+    }
     try {
-        const runner = args.runner ?? cliHooks.runner ?? new AgentToolRunner(adapterMap());
-        result = await runner.run({
-            provider: target.provider,
-            model: target.model,
-            options: { ...target.options },
-            prompt: resolvePrompt({
-                prompt: args.prompt ?? null,
-                promptFile: args.promptFile ?? null,
-                promptStdin: args.promptStdin ?? false,
-            }),
-            workspace,
-            sessionId: resolvedSessionId,
-            resumeExecutionId,
-            stageId: args.role,
-        });
+        return await runLocked();
     }
     catch (error) {
-        if (error instanceof CancellationRequested) {
-            log(error.message);
-            return 130;
-        }
-        if (error instanceof ConfigurationError)
-            throw error;
-        if (error instanceof Error) {
+        if (isSessionLockLost(error)) {
             printError(error.message);
             return 2;
         }
         throw error;
     }
     finally {
-        process.off("SIGINT", onSigint);
-        process.off("SIGTERM", onSigterm);
+        lock.release();
+    }
+    async function runLocked() {
+        let resumeExecutionId = null;
+        let resumeCancelled = false;
+        if (!createdSession) {
+            repairSessionUnlocked(workspace, resolvedSessionId);
+            const store = new SessionStore(workspace);
+            if (store.readSessionStatus(resolvedSessionId).status === "cancelled") {
+                resumeCancelled = true;
+            }
+            else {
+                const previous = store.latestExecution(resolvedSessionId);
+                if (previous !== null)
+                    resumeExecutionId = previous.executionId;
+            }
+        }
+        const optionLabel = Object.entries(target.options)
+            .map(([key, value]) => `${key}: ${value}`)
+            .join(", ") || "default";
+        printNotice(`agent ${args.role} · ${target.provider}/${target.model} (${optionLabel}).`);
+        const unbind = bindCancellationSignals();
+        let result;
+        let resumedMany = null;
+        try {
+            const runner = args.runner ?? cliHooks.runner ?? new AgentToolRunner(adapterMap());
+            if (resumeCancelled) {
+                const reopened = new SessionStore(workspace).reopenCancelledExecutions(resolvedSessionId);
+                for (const item of reopened) {
+                    log(`session ${resolvedSessionId} was cancelled during ${item.executionId}. Resuming that execution.`);
+                }
+                const settled = await Promise.allSettled(reopened.map((item) => runner.continueCancelled(workspace, resolvedSessionId, item.executionId)));
+                const rejected = settled.find((item) => item.status === "rejected");
+                if (rejected && rejected.status === "rejected")
+                    throw rejected.reason;
+                const continued = settled.flatMap((item) => (item.status === "fulfilled" ? [item.value] : []));
+                if (continued.length === 0) {
+                    throw new ConfigurationError(`Session ${resolvedSessionId} is cancelled without an execution.`);
+                }
+                if (continued.length === 1)
+                    result = continued[0];
+                else
+                    resumedMany = continued;
+            }
+            else {
+                result = await runner.run({
+                    provider: target.provider,
+                    model: target.model,
+                    options: { ...target.options },
+                    prompt: prependRoleInstructions(loadRoleInstructions(loadYamlMapping(path.join(workspace, ".migent", "config.yaml")), args.role), resolvePrompt({
+                        prompt: args.prompt ?? null,
+                        promptFile: args.promptFile ?? null,
+                        promptStdin: args.promptStdin ?? false,
+                    })),
+                    workspace,
+                    sessionId: resolvedSessionId,
+                    resumeExecutionId,
+                    stageId: args.role,
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof CancellationRequested) {
+                log(error.message);
+                return 130;
+            }
+            if (error instanceof ConfigurationError)
+                throw error;
+            if (error instanceof Error) {
+                printError(error.message);
+                return 2;
+            }
+            throw error;
+        }
+        finally {
+            unbind();
+        }
+        if (resumedMany !== null) {
+            if (args.asJson)
+                process.stdout.write(`${JSON.stringify(resumedMany)}\n`);
+            else {
+                for (const item of resumedMany)
+                    printAgent({ ...item }, args.role, target.provider, target.model);
+            }
+            if (resumedMany.some((item) => item.failure_reason === "verify_exhausted"))
+                return 6;
+            return resumedMany.every((item) => item.outcome_status === "complete") ? 0 : 1;
+        }
+        if (result === undefined)
+            throw new Error("Agent run produced no result.");
+        if (args.asJson)
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+        else
+            printAgent({ ...result }, args.role, target.provider, target.model);
+        return result.outcome_status === "complete" ? 0 : 1;
     }
-    if (createdSession)
-        printNotice(`session_id: ${result.session_id}`);
-    if (args.asJson)
-        process.stdout.write(`${JSON.stringify(result)}\n`);
-    else
-        printAgent({ ...result }, args.role, target.provider, target.model);
-    return result.outcome_status === "complete" ? 0 : 1;
 }
 function resolveSession(workspace, sessionId, role, task) {
     if (sessionId !== null && typeof task === "string" && task.trim() !== "") {

package/dist/commands/config.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { confirm as clackConfirm, isCancel, select as clackSelect, text as clackText } from "@clack/prompts";
 import { ConfigEditError, ConfigurationError, assignRoles, describeChange, diagnose, inspectConfig, loadModelTarget, loadWorkflowCatalog, loadYamlMapping, matchingModelName, patchConfigText, placeRoleModel, resolveStageSpec, setRoleOptions, upsertModel, whichSync, } from "@nodeint/migent-kernel";
 import { printError } from "../display.js";
+import { PromptCancelled } from "../errors.js";
 import { cliHooks } from "../hooks.js";
 import { requireCurrentSchema } from "../migrate.js";
 import { acceptedOptions, adapterMap, asCatalog, detected, knownModel, loadCatalog, loadOptionValues, parseOptions, requireAdapter, runProviderCommand, } from "../provider.js";
@@ -25,6 +26,8 @@ export async function runConfigModel(workspace, options = {}) {
         });
     }
     catch (error) {
+        if (error instanceof PromptCancelled)
+            throw error;
         if (error instanceof ConfigurationError || error instanceof ConfigEditError || error instanceof Error) {
             printError(error.message);
             return 2;
@@ -43,6 +46,8 @@ export async function runConfigRole(workspace, options = {}) {
         });
     }
     catch (error) {
+        if (error instanceof PromptCancelled)
+            throw error;
         if (error instanceof ConfigurationError || error instanceof ConfigEditError || error instanceof Error) {
             printError(error.message);
             return 2;
@@ -382,7 +387,7 @@ function optionUpdatesOf(options, clearOptions) {
 async function selectProvider(prompter, adapters, which, message, defaultValue) {
     const rows = detected(adapters, which);
     if (rows.length === 0)
-        throw new Error("No providers are available.");
+        throw new ConfigurationError("No providers are available.");
     const names = new Set(rows.map(([name]) => name));
     return prompter.select(message, rows.map(([name, found]) => [`${name}  ${found ?? "not found"}`, name]), defaultValue !== null && names.has(defaultValue) ? defaultValue : rows[0]?.[0]);
 }
@@ -486,6 +491,7 @@ function roleJson(role) {
         provider: role.provider,
         model: role.model,
         options: { ...role.options },
+        instructions: [...role.instructions],
         shared_with: [...role.sharedWith],
         stages: role.stages.map((stage) => ({
             workflow: stage.workflow,
@@ -586,7 +592,7 @@ function isRecord(value) {
 class ClackConfigPrompter {
     async select(message, choices, defaultValue) {
         if (choices.length === 0)
-            throw new Error("Choose a value.");
+            throw new ConfigurationError("Choose a value.");
         const values = new Set(choices.map(([, value]) => value));
         const initial = defaultValue != null && values.has(defaultValue) ? defaultValue : choices[0]?.[1];
         const result = await clackSelect({
@@ -594,20 +600,26 @@ class ClackConfigPrompter {
             options: choices.map(([label, value]) => ({ label, value })),
             initialValue: initial,
         });
-        if (isCancel(result) || typeof result !== "string" || !values.has(result))
-            throw new Error("Choose a value.");
+        if (isCancel(result))
+            throw new PromptCancelled();
+        if (typeof result !== "string" || !values.has(result))
+            throw new ConfigurationError("Choose a value.");
         return result;
     }
     async confirm(message) {
         const result = await clackConfirm({ message, initialValue: true });
-        if (isCancel(result) || typeof result !== "boolean")
-            throw new Error("Answer yes or no.");
+        if (isCancel(result))
+            throw new PromptCancelled();
+        if (typeof result !== "boolean")
+            throw new ConfigurationError("Answer yes or no.");
         return result;
     }
     async text(message, defaultValue = "") {
         const result = await clackText({ message, initialValue: defaultValue });
-        if (isCancel(result) || typeof result !== "string")
-            throw new Error("Enter a value.");
+        if (isCancel(result))
+            throw new PromptCancelled();
+        if (typeof result !== "string")
+            throw new ConfigurationError("Enter a value.");
         return result;
     }
 }

package/dist/commands/execute.d.ts

@@ -7,6 +7,12 @@ export interface ExecuteWorkflowOptions {
     priorSessionId?: string | null;
     maxAttempts?: number | null;
     maxDispatches?: number | null;
+    stageId?: string | null;
     runner?: AgentToolRunner | null;
+    verbose?: boolean;
+    itemProgress?: boolean;
+    startPrepared?: boolean;
+    refreshWorkflow?: boolean;
+    reply?: string | null;
 }
 export declare function executeWorkflow(workspace: string, options: ExecuteWorkflowOptions): Promise<number>;

package/dist/commands/execute.js

@@ -2,38 +2,54 @@ import { AgentToolRunner, DEFAULT_MAX_DISPATCHES, executeNamedWorkflow, } from "
 import { cliHooks } from "../hooks.js";
 import { requireCurrentSchema } from "../migrate.js";
 import { adapterMap } from "../provider.js";
+import { text } from "../text.js";
 export async function executeWorkflow(workspace, options) {
     requireCurrentSchema(workspace);
     const once = options.action === "stage";
-    const creating = options.action === "start" || (once && text(options.sessionId) === null);
+    const startPrepared = options.startPrepared === true;
+    const sessionId = text(options.sessionId);
+    const creating = !startPrepared && (options.action === "start" || (once && sessionId === null));
     const maxAttempts = options.maxAttempts === undefined ? 3 : options.maxAttempts;
     const maxDispatches = options.maxDispatches === undefined ? DEFAULT_MAX_DISPATCHES : options.maxDispatches;
     const runner = options.runner ?? cliHooks.runner ?? new AgentToolRunner(adapterMap());
+    runner.itemProgress = options.itemProgress === true;
     const result = await executeNamedWorkflow(workspace, {
-        workflowId: creating ? (options.workflowId ?? null) : null,
+        workflowId: creating || startPrepared ? (options.workflowId ?? null) : null,
         task: creating ? (options.task ?? null) : null,
-        sessionId: creating ? null : (options.sessionId ?? null),
+        sessionId: creating ? null : sessionId,
         priorSessionId: options.priorSessionId ?? null,
+        startPrepared,
         maxAttempts: once ? null : maxAttempts,
         maxDispatches: once ? null : maxDispatches,
+        stageId: options.stageId ?? null,
         once,
         resetRevisions: options.action === "continue",
+        refreshWorkflow: options.refreshWorkflow === true,
+        reply: options.reply ?? null,
     }, runner);
-    printResult(result);
+    printResult(result, options.verbose === true);
+    if (result.stopReason === "retry_exhausted" ||
+        result.stopReason === "revisions_exhausted" ||
+        result.stopReason === "dispatch_limit" ||
+        result.stopReason === "verify_exhausted") {
+        process.stderr.write(`Resume with: migent session continue ${result.sessionId}\n`);
+    }
     return result.code;
 }
-function printResult(result) {
-    process.stdout.write(`${JSON.stringify({
+const INSPECT_EXIT_CODES = new Set([1, 3, 6]);
+function printResult(result, verbose) {
+    const payload = {
         session_id: result.sessionId,
         session_status: result.status,
         stop_reason: result.stopReason,
+        latest_decision: result.latestDecision,
         outputs: result.outputs,
-        stages: result.stages,
-    })}\n`);
-}
-function text(value) {
-    if (typeof value !== "string")
-        return null;
-    const stripped = value.trim();
-    return stripped === "" ? null : stripped;
+    };
+    if (INSPECT_EXIT_CODES.has(result.code) && result.latestExecutionId) {
+        payload.latest_execution_id = result.latestExecutionId;
+        payload.response_path = `executions/${result.latestExecutionId}/response.md`;
+    }
+    if (verbose)
+        payload.stages = result.stages;
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
 }

package/dist/commands/init.d.ts

@@ -18,6 +18,8 @@ export declare function runInit(workspace: string, options?: {
     model?: string | null;
     options?: readonly string[];
     preset?: string;
+    presetExplicit?: boolean;
+    skill?: boolean;
     interactive?: boolean;
     adapters?: Record<string, AgentAdapter> | null;
     which?: Which | null;