@nodeint/migent 0.1.5 → 0.1.6

package/README.md

@@ -1,209 +1,249 @@
 # Migent
 
-**Compose AI coding agents into repeatable engineering workflows.**
-
-Use the right model for each stage of the job.
-
-Migent connects coding-agent CLIs from different providers through explicit,
-repository-defined workflows. One model can plan, another can review, and the
-first can revise—while Migent carries artifacts between them and remembers
-where the process is.
-
-## Contents
-
-- [Migent](#migent)
-  - [Contents](#contents)
-  - [Why Migent?](#why-migent)
-  - [Supported CLIs](#supported-clis)
-  - [Quickstart](#quickstart)
-    - [Install](#install)
-    - [Create a project](#create-a-project)
-    - [Run](#run)
-    - [Next](#next)
-  - [Concepts](#concepts)
-  - [Current scope](#current-scope)
-  - [Documentation](#documentation)
-  - [Development](#development)
-  - [License](#license)
-
-## Why Migent?
-
-Calling two agent CLIs from a shell script is easy. Reliably coordinating them
-across reviews, revisions, failures, and resumed sessions is not.
-
-Migent is built around three ideas:
-
-- **Use models for what they do best.** Assign each role to a provider and model
-  suited to the work, rather than asking one agent to do everything.
-- **Treat AI engineering process as code.** Keep stages, handoffs, review gates,
-  and revision policies in version control beside the project they govern.
-- **Keep orchestration explicit.** The team defines the process; models execute
-  roles inside it. A supervisor model does not invent or dynamically control
-  the workflow.
-
-**Models describe execution. Roles describe intent.** Changing the model behind
-a role does not require rewriting the workflow.
-
-**Common workflow model, native provider capabilities.** Migent coordinates
-the process, while each provider CLI remains responsible for authentication,
-agent execution, and its own tools and options.
+<p align="center">
+  <strong>Autonomous, multi-stage engineering pipelines for your coding agents.</strong><br>
+  Repeatable workflows. Multi-agent orchestration. Native CLI execution. Full observability.
+</p>
 
-```mermaid
-flowchart TD
-    A[Task] --> B[Planner - Codex]
-    B -->|plan.md| C[Reviewer - Grok]
-    C -->|revise| B
-    C -->|approved| D[Complete]
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nodeint/migent"><img src="https://img.shields.io/npm/v/@nodeint/migent.svg?style=flat-square" alt="npm version" /></a>
+  <a href="https://github.com/nodeint/migent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License: MIT" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg?style=flat-square" alt="Node.js 22+" /></a>
+  <img src="https://img.shields.io/badge/agents-Multi--Agent_Ready-orange.svg?style=flat-square" alt="Multi-Agent Ready" />
+</p>
+
+---
+
+Migent coordinates the coding-agent CLIs you already have into **reusable, verified engineering pipelines**. Instead of juggling tabs, manually copying plans, and pasting test errors back and forth, you define the pipeline as code. Migent orchestrates the handoffs, runs strict local verification gates, handles review loops, and captures deep execution metrics.
 
-## Supported CLIs
+### 🌟 Why Migent?
 
-Migent drives each provider through its headless CLI. Install and sign in to the
-ones your configuration names.
+- 🔁 **Automate Recurring Tasks (Workflows & Stages):** Package routine engineering work—bug fixes, refactors, migrations, test authoring—into structured, multi-stage pipelines with deterministic verification gates.
+- 🤖 **Multi-Agent Orchestration & Flexibility:** Assign the best model to each role (`claude` for planning, `codex` for implementation, `grok` for independent review). Run directly through your installed agent CLIs without custom wrappers or API lock-in.
+- 📊 **Observability & Continuous Improvement:** Live-stream running pipelines with `session follow`, and collect token spend, wall-time, and revision counts with `session metrics` to measure and refine your team's workflows.
 
-| Provider           | CLI      |
-| -------------------| -------- |
-| Google Antigravity | `agy`    |
-| Claude             | `claude` |
-| Codex              | `codex`  |
-| Grok               | `grok`   |
+---
 
 ## Quickstart
 
-Requires Node.js 22+ (macOS, Linux, or Windows) and the provider CLIs your
-config uses, already signed in.
+### Option A: Agent-Assisted via `/migent` (Recommended)
 
-### Install
+Let your coding agent handle the initial configuration using Migent's official Skill.
 
 ```bash
+# 1. Install Migent globally
 npm install -g @nodeint/migent
-migent --version
+
+# 2. Install the Migent Skill in your repo
+migent skill install
+```
+
+Now open your favorite coding agent CLI (such as Google Antigravity `agy`, Anthropic `claude`, Cursor, or Windsurf) in this repository and type:
+
+```text
+/migent Set up a workflow for this repo: Claude for planning, Codex for coding, Grok for review. Then run a pipeline to resolve issue #42.
 ```
 
-Upgrade with `npm install -g @nodeint/migent@latest`.
+> **How it works:** `migent skill install` creates `.agents/skills/migent/` containing Migent's schema rules and CLI definitions. Using the `/migent` slash command instructs your agent to inspect your repo, generate valid configuration files under `.migent/`, validate them with `migent doctor`, and launch the workflow.
 
-### Create a project
+---
 
-From the repository where agents will work:
+### Option B: Terminal CLI (Direct Control)
+
+Prefer setting it up yourself? Get started in three commands:
 
 ```bash
-migent init
+# 1. Initialize a workflow preset and validate environment
+migent init --preset plan
+migent doctor
+
+# 2. Run your engineering task
+migent session run --workflow plan --task "Implement JWT authentication with refresh tokens"
+
+# 3. Stream real-time events or inspect performance metrics
+migent session follow <session-id>
+migent session metrics <session-id> --json
 ```
 
-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:
+## What Migent Solves
 
-```text
-.migent/
-├── config.yaml        # models and roles
-├── .gitignore         # keeps sessions/ untracked
-└── workflows/
-    └── plan.yaml      # plan-and-review workflow
+| Without Migent | With Migent |
+| :--- | :--- |
+| **Manual handoffs:** Copying plans and pasting stack traces across conversations. | **Automated handoffs:** Upstream artifacts and diffs pass automatically into downstream stages. |
+| **Single-agent bottleneck:** One model handles planning, coding, and review, accumulating context bloat. | **Specialized roles:** Multi-agent pipeline with dedicated models per role (e.g., Planner $\rightarrow$ Coder $\rightarrow$ Reviewer). |
+| **Vendor lock-in & wrappers:** Restricted to one provider or requiring custom API adapters. | **Native CLI execution:** Drives your installed agent CLIs (`agy`, `claude`, `codex`, `grok`) directly in your workspace. |
+| **Blind trust:** Agents claim "all tests pass" without actually running project commands. | **Verification gates:** Real local checks (`pnpm test`, `pytest`, `cargo test`) must succeed before advancing. |
+| **Fragile one-off prompts:** Team members execute tasks with inconsistent, ad-hoc instructions. | **Process as code:** Workflows live in Git (`.migent/workflows/`), making best practices versioned and repeatable. |
+| **No execution visibility:** No record of how long tasks took, why checks failed, or how many retries occurred. | **Telemetry & Metrics:** Append-only event logs, live streaming, and full JSON metrics for duration, retries, and token cost. |
 
-.agents/skills/migent/ # only if you install the skill
+---
+
+## How It Works
+
+A typical software engineering workflow breaks down into structured, verifiable stages:
+
+```mermaid
+flowchart TD
+    Task["Task: Fix OAuth Callback"] --> Plan["1. Plan\n(Claude)"]
+    Plan -->|"artifact: plan.md"| Implement["2. Implement\n(Codex)"]
+    Implement --> Verify{"3. Verification Gate\n(pnpm test)"}
+    Verify -->|"Fails (retry <= max)"| Implement
+    Verify -->|"Retry limit reached"| Blocked["Stop for inspection"]
+    Verify -->|"Passes"| Review["4. Review\n(Grok)"]
+    Review -->|"Revise + feedback"| Implement
+    Review -->|"Approved"| Done["Workflow Complete"]
 ```
 
-Commit `config.yaml` and `workflows/`. To add the skill later, run
-`migent skill install`.
+1. **Plan:** A high-reasoning model analyzes the codebase and generates an actionable `plan.md`.
+2. **Implement:** A coding model applies changes to the working tree according to the plan.
+3. **Verify Gate:** Migent runs your repository's native verification commands (tests, typecheck, lint).
+4. **Review & Revision Loop:** An independent reviewer evaluates the git diff against the plan. If changes are requested, feedback routes back to the implementation stage.
 
-### Run
+---
 
-From the project or any subdirectory:
+## Core Capabilities
 
-```bash
-migent session run --workflow plan --task "Plan the account settings redesign"
-```
+### 1. Repeatable Workflows as Code
+Define stages, dependencies, artifacts, and routing decisions in declarative YAML stored under `.migent/workflows/`. Version control your engineering processes alongside your application code.
 
-`--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:
+### 2. Multi-Agent Orchestration & BYO CLIs
+Decouple **what** a stage does from **which model** executes it. Migent drives the agent CLIs already installed and authenticated on your machine:
 
-```bash
-migent session prepare wave-3 --workflow plan
-migent session run --session wave-3 --workflow plan
-```
+| Provider | CLI | Typical Role in Pipeline |
+| :--- | :--- | :--- |
+| **Anthropic Claude** | `claude` | High-reasoning architecture planning & refactoring |
+| **Google Antigravity** | `agy` | Deep repository analysis, plan generation & review |
+| **OpenAI Codex** | `codex` | Fast, focused implementation & unit test authoring |
+| **xAI Grok** | `grok` | Independent logic review & edge case discovery |
 
-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:
+Switch models anytime in `.migent/config.yaml` without touching your workflow logic.
 
-```bash
-migent session list
-migent session list --latest --json
-migent session follow <session-id>
-migent session continue <session-id>
-```
+### 3. Observability, Telemetry & Continuous Improvement
+Migent treats engineering runs as first-class observable processes:
+- **Live Monitoring:** `migent session follow <session-id>` streams execution events, stage heartbeats, and runner turns in real time.
+- **Detailed Metrics:** `migent session metrics <session-id> --json` outputs execution wall-time, active runner seconds, verify durations, revision counts, and token usage.
+- **Continuous Refinement:** Use hard metrics from past sessions to optimize prompts, tune retry limits, and pick the most cost-effective models.
+- **Session Recovery:** When rate limits or network issues strike, `migent session continue <session-id>` resumes right where the pipeline stopped.
 
-`session list --json` and a JSON snapshot omit the task text.
+---
 
-### Next
+## Configuration Example
 
-- [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)
+Migent separates model/role assignments from pipeline control flow.
 
-## Concepts
+### 1. Configure Models and Roles (`.migent/config.yaml`)
 
-A workflow connects stages through dependencies and explicit decision routes.
+```yaml
+schema_version: 2
 
-- A **model** identifies a provider model and its execution options.
-- A **role** names a kind of work and selects its default model.
-- A **stage** assigns work to a role and may declare dependencies, an artifact,
-  a decision, or both.
-- An **artifact** is a named file produced by a successful stage and stored with
-  the workflow session.
-- A **decision** selects the next route, including a route back for revision.
-- A **session** records executions, events, decisions, and artifacts so work can
-  be inspected or resumed.
+models:
+  planning-model:
+    provider: claude
+    model: opus
 
-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.
+  coding-model:
+    provider: codex
+    model: default
 
-## Current scope
+  review-model:
+    provider: grok
+    model: grok-4.7
 
-Migent is a local, file-backed orchestration layer for provider CLIs. It does
-not replace their agent runtimes, and it does not hide their distinctive
-capabilities behind a lowest-common-denominator API.
+roles:
+  planner:
+    default_model: planning-model
+    instructions:
+      - Analyze the repository and create an actionable plan with file paths.
 
-Today, Migent supports explicit stage routing, review loops, local session
-history, provider-session resume, prerequisite workflows, and standalone role
-execution. A machine-local registry service records workspaces
-so another tool can ask which projects exist.
+  coder:
+    default_model: coding-model
+    instructions:
+      - Implement changes according to the plan and write regression tests.
 
-## Documentation
+  reviewer:
+    default_model: review-model
+    instructions:
+      - Review the git diff against the plan for correctness, security, and edge cases.
+```
 
-- [Writing workflows](https://github.com/nodeint/migent/blob/main/docs/workflows.md)
-- [Providers and model configuration](https://github.com/nodeint/migent/blob/main/docs/providers.md)
-- [Sessions and workflow composition](https://github.com/nodeint/migent/blob/main/docs/sessions.md)
-- [CLI commands and execution controls](https://github.com/nodeint/migent/blob/main/docs/cli.md)
+### 2. Define the Pipeline (`.migent/workflows/feature.yaml`)
+
+```yaml
+schema_version: 2
+id: feature
+
+stages:
+  - id: plan
+    role: planner
+    produces:
+      artifact: plan.md
+
+  - id: implement
+    role: coder
+    depends_on: [plan]
+    verify:
+      - pnpm test
+    max_verify: 3
+
+  - id: review
+    role: reviewer
+    depends_on: [implement]
+    decision:
+      values: [approved, revise]
+      routes:
+        approved: complete
+        revise: implement
+
+outputs:
+  - name: plan
+    from_stage: plan
+    artifact: plan.md
+```
+
+---
+
+## CLI Cheatsheet
+
+```bash
+# Setup & Health
+migent init --preset plan           # Initialize starter configuration
+migent doctor                      # Validate configuration, schemas, and CLI availability
+migent skill install               # Install the Migent Skill for coding agents (.agents/skills/migent/)
+
+# Execution
+migent session run --workflow <id> --task "<task>"   # Run a workflow
+migent session continue <session-id>                 # Resume an interrupted or blocked session
+
+# Monitoring & Telemetry
+migent session list                                  # List recorded sessions and statuses
+migent session follow <session-id>                   # Live-stream session events and progress
+migent session metrics <session-id> --json           # View token spend, duration, and retry metrics
+migent session show <session-id>                     # Inspect session state and artifact status
+```
+
+---
+
+## Documentation
 
-Run `migent <command> --help` for the exact command contract, output fields,
-and exit codes.
+- [Writing Workflows](https://github.com/nodeint/migent/blob/main/docs/workflows.md) — Stages, dependencies, artifacts, and routing decisions.
+- [Providers and Model Configuration](https://github.com/nodeint/migent/blob/main/docs/providers.md) — Configuring CLIs, models, options, and fallback models.
+- [Sessions and State](https://github.com/nodeint/migent/blob/main/docs/sessions.md) — Manifests, append-only event logs, and recovery.
+- [CLI Reference](https://github.com/nodeint/migent/blob/main/docs/cli.md) — Full command catalog, flags, and JSON modes.
 
-## Development
+## Contributing
 
-The pnpm workspace contains four packages: the `@nodeint/migent` CLI and its
-internal libraries `@nodeint/migent-kernel`, `@nodeint/migent-adapters`, and
-`@nodeint/migent-registry`. The libraries have no stable API; depend on
-`@nodeint/migent`.
+Migent is built with TypeScript in a pnpm workspace:
 
 ```bash
 pnpm install
 pnpm build
 pnpm test
-pnpm migent --help   # run the local build
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for testing rules, platform notes, and
-the release process.
+See [CONTRIBUTING.md](https://github.com/nodeint/migent/blob/main/CONTRIBUTING.md) for details.
 
 ## License
 
-Migent is licensed under the [MIT License](https://github.com/nodeint/migent/blob/main/LICENSE).
+Migent is open source under the [MIT License](https://github.com/nodeint/migent/blob/main/LICENSE).

package/dist/commands/agent.d.ts

@@ -1,4 +1,4 @@
-import { AgentToolRunner } from "@nodeint/migent-kernel";
+import { AgentToolRunner, type WaitHooks } from "@nodeint/migent-kernel";
 export declare function dispatchAgent(workspace: string, args: {
     role: string;
     task?: string | null;
@@ -11,4 +11,11 @@ export declare function dispatchAgent(workspace: string, args: {
     promptStdin?: boolean;
     asJson?: boolean;
     runner?: AgentToolRunner | null;
+    waitHooks?: WaitHooks;
+}): Promise<number>;
+export declare function continueAgent(workspace: string, args: {
+    sessionId: string;
+    reply: string | null;
+    runner?: AgentToolRunner | null;
+    waitHooks?: WaitHooks;
 }): Promise<number>;