@nodeint/migent 0.1.3 → 0.1.5

package/dist/session-row.d.ts

@@ -0,0 +1,20 @@
+export declare const SESSION_COLUMN: {
+    readonly updatedAt: 0;
+    readonly session: 1;
+    readonly workflow: 2;
+    readonly status: 3;
+    readonly execution: 4;
+    readonly decision: 5;
+    readonly outputs: 6;
+    readonly task: 7;
+};
+export interface SessionFields {
+    session: string;
+    workflow: string;
+    status: string;
+    execution: string;
+    decision: string;
+    outputs: string;
+    task: string;
+}
+export declare function sessionFields(row: readonly string[]): SessionFields;

package/dist/session-row.js

@@ -0,0 +1,21 @@
+export const SESSION_COLUMN = {
+    updatedAt: 0,
+    session: 1,
+    workflow: 2,
+    status: 3,
+    execution: 4,
+    decision: 5,
+    outputs: 6,
+    task: 7,
+};
+export function sessionFields(row) {
+    return {
+        session: row[SESSION_COLUMN.session] ?? "",
+        workflow: row[SESSION_COLUMN.workflow] ?? "",
+        status: row[SESSION_COLUMN.status] ?? "",
+        execution: row[SESSION_COLUMN.execution] ?? "",
+        decision: row[SESSION_COLUMN.decision] ?? "",
+        outputs: row[SESSION_COLUMN.outputs] ?? "",
+        task: row[SESSION_COLUMN.task] ?? "",
+    };
+}

package/dist/signals.d.ts

@@ -0,0 +1,3 @@
+export declare function bindCancellationSignals(): () => void;
+export declare function throwIfCliCancelled(): void;
+export declare function delay(ms: number): Promise<void>;

package/dist/signals.js

@@ -0,0 +1,56 @@
+import { CancellationRequested, raiseCancellation, resetCancellation } from "@nodeint/migent-kernel";
+let pending = null;
+const waiters = new Set();
+function note(signalNumber) {
+    pending = new CancellationRequested(signalNumber);
+    for (const waiter of waiters)
+        waiter();
+    try {
+        raiseCancellation(signalNumber);
+    }
+    catch {
+        // The pending flag is what the follow loop and provider runner observe.
+    }
+}
+export function bindCancellationSignals() {
+    const onSigint = () => note(2);
+    const onSigterm = () => note(15);
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    return () => {
+        process.off("SIGINT", onSigint);
+        process.off("SIGTERM", onSigterm);
+        pending = null;
+        resetCancellation();
+    };
+}
+export function throwIfCliCancelled() {
+    const error = pending;
+    if (error === null)
+        return;
+    pending = null;
+    throw error;
+}
+export function delay(ms) {
+    throwIfCliCancelled();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            waiters.delete(wake);
+            try {
+                throwIfCliCancelled();
+                resolve();
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        const timer = setTimeout(finish, ms);
+        const wake = () => finish();
+        waiters.add(wake);
+    });
+}

package/dist/templates/migent/SKILL.md

@@ -1,62 +1,171 @@
 ---
 name: migent
-description: Set up Migent in a project, or configure, run, inspect, and resume its workflows. Use when the user asks about Migent configuration, workflows, sessions, stages, or published outputs.
+description: Set up Migent in a project, or configure, run, inspect, and resume its workflows with the migent CLI. Use when the user asks about Migent, .migent/ configuration, workflows, roles, models, sessions, stages, doctor, or published outputs.
 ---
 
 # Migent
 
-Use Migent as the control plane for the project's multi-stage agent workflows.
+Migent runs a project's multi-stage agent workflows from the `migent` CLI.
+A workflow is a set of stages; each stage runs a role; a role uses a model
+name defined in `.migent/config.yaml`. Each run is a session.
 
 ## Working rules
 
 - For an existing project, work from the root containing
-  `.migent/config.yaml`. To set up a new project, run `migent init` from
-  its root and follow the CLI's provider and model prompts or flags.
+  `.migent/config.yaml`.
 - Read `.migent/config.yaml` and the relevant file under
   `.migent/workflows/` before changing or running a workflow.
-- Run `migent doctor` after editing configuration or workflows.
-  `migent config model` and `migent config role` run it after a write.
-- Treat `.migent/sessions/` as generated, resumable state. Do not edit its
-  files directly.
-- Preserve the user's task wording when passing `--task`.
-- Before continuing a stopped session, inspect the command's `stop_reason` and
-  latest execution. Fix the cause before retrying.
-
-## Choose the command
-
-- Start a workflow: `migent start <workflow> --task "<task>"`. `<workflow>`
-  is the workflow id, or a path to a workflow file. An omitted `id` uses the
-  file name. If its
-  `requires` block names a prerequisite workflow and decision, find a matching
-  completed session and add `--prior <session-id>`.
-- Resume an active session: `migent continue <session-id>`.
-- Advance exactly one eligible stage: `migent stage <session-id>`.
-- List recorded sessions: `migent sessions` or `migent sessions --json`.
-- Inspect a snapshot: `migent watch <session-id> --once --json`.
-- Follow new events: `migent watch <session-id>`.
-- Run a configured role outside a workflow only when the user asks for ad hoc
-  role execution: `migent agent start --role <role> --prompt "<prompt>"`.
-- Read `.migent/config.yaml`: `migent config show`.
-- Change a model entry: `migent config model <name> --provider <provider> --model <model-id>`.
-  This updates every role and stage that uses the name.
-- Point one role at a model without changing a shared entry:
-  `migent config role <role> --provider <provider> --model <model-id>`.
-  `migent config role <role> --model-name <name>` points it at a name that
-  already exists. Add `--json` to read the result.
-
-Workflow commands emit progress on stderr and one result object on stdout.
-Report the session ID, session status, stop reason, decisions, and published
-outputs that matter to the user. A stopped active session is resumable; do not
-describe it as completed.
-
-`retry_exhausted` means the stage has used its total failed-attempt allowance;
-`--attempts` on `continue` sets a new total, not extra retries.
-`revisions_exhausted` leaves the session active. `continue` resets revision
-counts for the existing session, allowing another batch up to `max_revisions`.
-`dispatch_limit` applies to the current command; continue the same session if
-further stages are appropriate. Do not start a replacement session to reset
-these limits.
-
-Published output paths are relative to
-`.migent/sessions/<session-id>/`. Prefer the paths reported by Migent over
-guessing artifact locations.
+- Before writing `.migent/config.yaml` or a file under `.migent/workflows/`,
+  read `.agents/skills/migent/references/schema-config.yaml` and
+  `.agents/skills/migent/references/schema-workflow.yaml`. They list every
+  accepted key. A key absent from those files is ignored.
+- Run `migent doctor --json` after editing configuration or workflows. If it
+  reports an outdated schema, run `migent migrate --yes`. Pass `--json` on
+  `config model` and `config role` writes too. The object includes the doctor
+  result.
+- You have no terminal for prompts. Pass `--no-input` (or set
+  `MIGENT_NO_INPUT=1`) to `init`, `config model`, and `config role`, and give
+  every value as a flag.
+- Treat `.migent/sessions/` as generated, resumable state. Do not edit
+  `manifest.yaml`, `status.json`, `events.jsonl`, or files under
+  `executions/`. In a prepared session, write `task.md` and files next to
+  it before the first stage. Do not change `task.md` after that stage starts.
+- Preserve the user's task wording. Pass a one-line task in `--task`. Write
+  a longer task into `task.md` unchanged.
+- A workflow `session run` or `session continue` prints `session_id`,
+  `session_status`, `stop_reason`, `latest_decision`, and `outputs` on stdout.
+  Stderr carries stage boundaries and errors. A role run prints a table unless
+  `--json`. That JSON is the role result, not this object.
+- This skill is already in the prompt. Do not open its file again.
+- Do not read `task.md` or the documents it names. The stage agent reads
+  them. Still read `.migent/config.yaml` and the workflow file before starting.
+
+## Set up
+
+```
+migent init --no-input --provider <provider> --model <model-id> [--preset implement|plan] [--option KEY=VALUE] [--skill]
+migent doctor --json
+```
+
+`--provider` and `--model` go together. `--preset` picks the workflow to
+create (default `implement`). `--skill` installs this skill at
+`.agents/skills/migent`; `migent skill update` refreshes a managed copy.
+
+## Run
+
+`migent session run` runs a workflow when `--workflow` is set, and one role
+when `--workflow` is omitted.
+
+- Start a one-line task: `migent session run --workflow <workflow> --task "<task>"`.
+  `<workflow>` is a workflow id, or a path to a workflow file (the `id`
+  field defaults to the file name). The sentence is stored in `task.md`.
+  `--task` must be one line. Runs until the session stops.
+- Start a longer task: `migent session prepare <some-id> --workflow <workflow>`.
+  `<some-id>` is a lowercase slug such as `wave-3` (letters, digits, and
+  single hyphens). Write `.migent/sessions/<some-id>/task.md`, then
+  `migent session run --session <some-id> --workflow <workflow>`.
+  `session continue` does not start a prepared session.
+- Start and dispatch one stage only: add `--once`. `--once` requires `--workflow`.
+- If the workflow's `requires` block names a prerequisite workflow and
+  decision, find it with
+  `migent session list --workflow <workflow-id> --status completed --json`
+  and pass `--prior <session-id>`. `session continue` accepts `--prior` too.
+- Resume an active workflow session: `migent session continue <session-id>`.
+  This resets revision counts. `migent session continue <session-id> --once`
+  advances one stage and does not reset them. A blocked session runs that stage
+  again. `migent session continue <session-id> --reply "<reply>"` sends the
+  reply as the new execution's prompt body. Use `--reply-file <path>` for a
+  longer reply. When more than one stage is blocked, pass `--stage`. Without
+  `--reply`, the prompt includes the blocker and the previous response.
+  A cancelled session is resumed the same way, on the same execution: a cut-off
+  provider turn is sent again, and a cut-off verify runs again. Ask the user
+  before resuming a cancellation.
+- Run one role: `migent session run --role <role> --prompt "<prompt>"`.
+  `roles.<role>.instructions` in config, when set, is prepended to that prompt.
+  Use `--file <path>` or `--stdin` for a long prompt. `--task` labels a new
+  role session and cannot be combined with `--session <session-id>`, which
+  continues an earlier role session. `--provider`/`--model` (together) and
+  `--option KEY=VALUE` override the role for this turn. Add `--json` for one
+  result object. Exit 0 means the outcome is complete, 1 not complete.
+- Read the JSON result on stdout for a workflow run. Do not pass `--verbose`
+  or `--progress`. `--verbose` inlines every stage response. `--progress`
+  prints each tool call.
+- Exit 1, 3, and 6 also include `latest_execution_id` and `response_path`,
+  relative to `.migent/sessions/<session-id>/`. Read that file when you must
+  fix the execution.
+- Stderr is not the outcome. Do not read the command log while a run is healthy.
+- When `session run` or `session continue` is in the background, wait for that
+  command's completion notice. Do not add a watcher that only waits for the same exit.
+- To check a run without waiting on the command, use
+  `migent session show <session-id> --json` once.
+- Do not run `session follow` or `--cursor`.
+
+Limits, accepted by workflow `session run` and by `session continue`:
+
+- `--attempts <n>`: failed executions allowed for one stage (default 3). On
+  `session continue` it sets a new total, not extra retries.
+- `--max-dispatches <n>`: stage dispatches allowed in this command (default
+  20). `--unlimited-dispatches` removes the ceiling; use it only if the user
+  agrees.
+
+### Exit codes and stop reasons
+
+A workflow result on stdout includes `stop_reason`. Read the exit code first.
+
+| Exit | Meaning | `stop_reason` | Session | What to do |
+| --- | --- | --- | --- | --- |
+| 0 | Completed (with `--once`: stage complete) | | completed or advancing | Report outputs. |
+| 1 | Blocked (with `--once`: stage not complete) | `blocked`, or `stage` with `--once` | blocked, or active with `--once` | When `stop_reason` is `blocked`, read `response_path`. Pass the user's words with `session continue --reply`, or `session continue` without `--reply` after the blocker is fixed in the workspace. When `stop_reason` is `stage`, `session continue` keeps going. |
+| 2 | Configuration error | | unchanged | Run `migent doctor --json`, fix config. |
+| 3 | `--attempts` spent | `retry_exhausted` | active | Read `response_path`, fix the cause, then `session continue` (add `--attempts` for a higher total). |
+| 4 | A route would exceed `max_revisions` | `revisions_exhausted` | active | Review why the stage keeps being revised; `session continue` (without `--once`) resets counts for another batch. |
+| 5 | `--max-dispatches` spent | `dispatch_limit` | active | `session continue` the same session if more stages are appropriate. |
+| 130 | Cancelled | | see snapshot | Ask the user before resuming. `session continue` resumes that same execution. |
+
+A stopped active session is resumable; do not describe it as completed. A
+blocked session is resumed the same way: `session continue` runs that stage
+again. Do not start a replacement session to reset limits or to get past
+`blocked`. If you change a workflow or
+config while a session is active, that session keeps the workflow, models, and
+role instructions it started with. Run `migent doctor --json` and tell the user.
+`migent session continue <session-id> --refresh-workflow` adopts the current
+workflow, models, and role instructions. `session run --session <id> --workflow <workflow> --refresh-workflow`
+does the same when starting a prepared session.
+
+## Inspect sessions
+
+- Newest match: `migent session list --latest --json`. Add `--workflow <id>` and
+  `--status active|prepared|completed|blocked|cancelled` to narrow it. `--limit <n>`
+  returns the newest n rows. Do not combine `--latest` with `--limit`.
+- `--latest --json` is one object, or `null` when nothing matches. A list is
+  a JSON array. Snapshot: `migent session show <session-id> --json` has the
+  status, latest execution, decision, and outputs. JSON omits the task text.
+- Compare runs with `migent session metrics --json`. One session is one
+  object. Several sessions are one object per line, newest first.
+  `--workflow`, `--status`, and `--limit` match `session list`. Read
+  `usage_missing` and `uncaptured_turns` before comparing totals.
+  `stage_attempt` is not a retry count.
+- `session follow` streams the event trace for a person at a terminal.
+  Do not use it or `--cursor` to coordinate a run.
+
+Report the session ID, status, stop reason, decisions, and published outputs
+that matter to the user. Published output paths are relative to
+`.migent/sessions/<session-id>/`; use the paths Migent reports instead of
+guessing.
+
+## Configure models and roles
+
+- Show: `migent config` or `migent config show`.
+- List models or roles: `migent config model --json`,
+  `migent config role --json`.
+- Change a model name:
+  `migent config model <name> --provider <provider> --model <model-id> --no-input --json`.
+  This updates every role and stage that uses the name. Use
+  `--option KEY=VALUE` and `--clear-option KEY` for provider options.
+- Point roles at an existing model name:
+  `migent config role <role>... --model-name <name> --no-input --json`. The value is
+  a name from `models`, not a provider model id.
+- Override one role without touching the shared name:
+  `migent config role <role> --provider <provider> --model <model-id> --no-input --json`.
+- `roles.<name>.instructions` is an optional list of strings. A stage prompt
+  includes it before that stage's instructions. A role run prepends it to the prompt.

package/dist/templates/migent/references/schema-config.yaml

@@ -0,0 +1,35 @@
+# A missing schema_version is 0. Commands refuse the file while it is older than this Migent.
+schema_version: 2
+
+# models.<name>.model is the provider model id.
+# roles.<name>.default_model and a stage model are this name.
+# Options merge in order: model, then role, then stage.
+# Only keys the adapter marks overridable are stored on the provider session.
+models:
+  planner:
+    provider: grok
+    model: grok-4.7
+    # grok accepts reasoning-effort (overridable), max_turns, tools, disallowed_tools,
+    # permission_mode (default, acceptEdits, auto, dontAsk, bypassPermissions, plan),
+    # rules, allow, deny, and sandbox.
+    # agy accepts effort (low, medium, high, xhigh, max; overridable), mode (accept-edits, auto, plan),
+    # agent, sandbox (true or false), and skip_permissions (true or false).
+    # claude accepts effort (low, medium, high, xhigh, max; overridable), permission_mode
+    # (acceptEdits, auto, bypassPermissions, manual, dontAsk, plan), tools, allowed_tools,
+    # disallowed_tools, max_budget_usd, fallback_model, and append_system_prompt.
+    # codex accepts model_reasoning_effort (overridable). Any other key of letters, digits,
+    # dots, underscores, and hyphens is passed through as codex exec -c.
+    options:
+      reasoning-effort: high
+
+roles:
+  planner:
+    default_model: planner
+    # Included in every prompt for this role, before stage instructions.
+    # A role run prepends the same list to the prompt.
+    instructions:
+      - Break the task into a reviewable plan.
+    options:
+      reasoning-effort: medium
+  reviewer:
+    default_model: planner

package/dist/templates/migent/references/schema-workflow.yaml

@@ -0,0 +1,61 @@
+# A missing schema_version is 0. Commands refuse the file while it is older than this Migent.
+schema_version: 2
+concurrency: 1
+
+# When id is omitted, the id is the file name without .yaml.
+id: reference
+
+constraints:
+  - Stay within the task.
+
+# requires.workflow names another file in .migent/workflows.
+requires:
+  workflow: plan
+
+stages:
+  - id: draft
+    role: planner
+    # model is a name under models in config.yaml, not a provider model id.
+    model: planner
+    # Options merge in order: model, then role, then stage.
+    # Only keys the adapter marks overridable are stored on the provider session.
+    options:
+      reasoning-effort: high
+    depends_on: []
+    # max_revisions is allowed only when a route returns to this stage.
+    max_revisions: 2
+    instructions:
+      - Write the draft.
+    produces:
+      artifact: draft.md
+
+  - id: review
+    role: reviewer
+    depends_on:
+      - draft
+    # resume_from must be one entry in depends_on. It continues that stage's provider session.
+    session:
+      resume_from: draft
+    instructions:
+      - Review the draft.
+    # verify runs after status complete and must sit on every path to complete.
+    # A stage artifact cannot be named verify.md.
+    verify:
+      - pnpm test
+    # max_verify defaults to 3. verify_timeout is seconds for the whole list. Both require verify.
+    max_verify: 3
+    verify_timeout: 900
+    # Route keys must match decision.values. A destination is a stage id, complete, or a non-empty list of stage ids.
+    decision:
+      values:
+        - approved
+        - revise
+      routes:
+        approved: complete
+        revise: draft
+
+# An output artifact must match produces.artifact on from_stage.
+outputs:
+  - name: draft
+    from_stage: draft
+    artifact: draft.md

package/dist/text.d.ts

@@ -0,0 +1,4 @@
+export declare function text(value: string | null | undefined): string | null;
+export declare function optionalText(value: unknown): string | null;
+/** Keep leading and trailing breaks so a one-line task check sees them. */
+export declare function rawText(value: unknown): string | null;

package/dist/text.js

@@ -0,0 +1,13 @@
+export function text(value) {
+    if (typeof value !== "string")
+        return null;
+    const stripped = value.trim();
+    return stripped === "" ? null : stripped;
+}
+export function optionalText(value) {
+    return text(typeof value === "string" ? value : null);
+}
+/** Keep leading and trailing breaks so a one-line task check sees them. */
+export function rawText(value) {
+    return typeof value === "string" ? value : null;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const PACKAGE_VERSION: string;

package/dist/version.js

@@ -0,0 +1,3 @@
+import { createRequire } from "node:module";
+const { version } = createRequire(import.meta.url)("../package.json");
+export const PACKAGE_VERSION = version;

package/dist/workspace.js

@@ -1,6 +1,7 @@
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { ConfigurationError } from "@nodeint/migent-kernel";
+import { isFile } from "./fs-utils.js";
 let invocationCwd = null;
 export function setInvocationCwd(cwd) {
     invocationCwd = cwd === undefined ? null : path.resolve(cwd);
@@ -24,12 +25,12 @@ export function resolvePrompt(args) {
     if (args.promptStdin) {
         const text = readFileSync(0, "utf8");
         if (text === "")
-            throw new Error("Prompt from stdin is empty.");
+            throw new ConfigurationError("Prompt from stdin is empty.");
         return text;
     }
     if (args.promptFile == null) {
         if (args.prompt == null)
-            throw new Error("Pass one of --prompt, --file, or --stdin.");
+            throw new ConfigurationError("Pass one of --prompt, --file, or --stdin.");
         return args.prompt;
     }
     try {
@@ -37,14 +38,6 @@ export function resolvePrompt(args) {
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        throw new Error(`Unable to read prompt file: ${args.promptFile} (${reason})`);
-    }
-}
-function isFile(filePath) {
-    try {
-        return statSync(filePath).isFile();
-    }
-    catch {
-        return false;
+        throw new ConfigurationError(`Unable to read prompt file: ${args.promptFile} (${reason})`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeint/migent",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Compose AI coding agents into repeatable engineering workflows.",
   "keywords": [
     "ai",
@@ -43,9 +43,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@nodeint/migent-adapters": "0.1.3",
-    "@nodeint/migent-kernel": "0.1.3",
-    "@nodeint/migent-registry": "0.1.3",
+    "@nodeint/migent-adapters": "0.1.5",
+    "@nodeint/migent-kernel": "0.1.5",
+    "@nodeint/migent-registry": "0.1.5",
     "commander": "^14.0.2",
     "picocolors": "^1.1.1"
   },