@nodeint/migent 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Migent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
+# Migent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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)
+    - [Upgrade](#upgrade)
+    - [Create a project](#create-a-project)
+    - [Run](#run)
+  - [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.
+
+```mermaid
+flowchart LR
+    A[Task] --> B[Planner - Codex]
+    B -->|plan.md| C[Reviewer - Grok]
+    C -->|revise| B
+    C -->|approved| D[Complete]
+```
+
+## Supported CLIs
+
+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`   |
+
+## Quickstart
+
+Node.js 22+ on macOS or Linux, and authenticated provider CLIs named by your
+configuration.
+
+### Install
+
+```bash
+npm install -g @nodeint/migent
+```
+
+Verify with `migent --version`.
+
+### Upgrade
+
+```bash
+npm install -g @nodeint/migent@latest
+```
+
+### Create a project
+
+From the project where agents will work:
+
+```bash
+migent init --preset plan
+```
+
+`init` writes the config, a plan-and-review workflow, and a gitignore for local
+session state:
+
+```text
+.migent/
+├── config.yaml
+├── .gitignore
+└── workflows/
+    └── plan.yaml
+```
+
+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.
+
+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).
+
+### Run
+
+From that project or any of its subdirectories:
+
+```bash
+migent start 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.
+
+```bash
+migent sessions
+migent watch <session-id>
+migent continue <session-id>
+```
+
+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).
+
+## Concepts
+
+A workflow connects stages through dependencies and explicit decision routes.
+
+- 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.
+
+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.
+
+## Current scope
+
+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.
+
+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.
+
+## Documentation
+
+- [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)
+
+Run `migent <command> --help` for the exact command contract, output fields,
+and exit codes.
+
+## Development
+
+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`.
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm migent --help   # run the local build
+```
+
+### Releasing
+
+All four packages share one version. Bump it, commit, and push a matching tag:
+
+```bash
+pnpm -r exec npm pkg set version=0.2.0
+pnpm install
+git commit -am "Release 0.2.0"
+git tag v0.2.0
+git push origin main v0.2.0
+```
+
+The tag runs `.github/workflows/release.yml`, which builds, tests, packs, and
+stages each package through npm trusted publishing. Nothing goes live until a
+maintainer approves the staged versions on npmjs.com (Staged Packages tab) or
+with `npm stage approve`, kernel first and `@nodeint/migent` last.
+
+## License
+
+Migent is licensed under the [MIT License](https://github.com/nodeint/migent/blob/main/LICENSE).

package/dist/commands/agent.d.ts

@@ -0,0 +1,14 @@
+import { AgentToolRunner } from "@nodeint/migent-kernel";
+export declare function dispatchAgent(workspace: string, args: {
+    role: string;
+    task?: string | null;
+    sessionId?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    options?: readonly string[];
+    prompt?: string | null;
+    promptFile?: string | null;
+    promptStdin?: boolean;
+    asJson?: boolean;
+    runner?: AgentToolRunner | null;
+}): Promise<number>;

package/dist/commands/agent.js

@@ -0,0 +1,97 @@
+import { AgentToolRunner, CancellationRequested, ConfigurationError, createAgentSession, log, raiseCancellation, requireAgentSession, resolveRoleTarget, SessionStore, } from "@nodeint/migent-kernel";
+import { printAgent, printError, printNotice } from "../display.js";
+import { cliHooks } from "../hooks.js";
+import { requireCurrentSchema } from "../migrate.js";
+import { adapterMap, parseOptions } from "../provider.js";
+import { resolvePrompt } from "../workspace.js";
+export async function dispatchAgent(workspace, args) {
+    requireCurrentSchema(workspace);
+    const parsed = parseOptions(args.options ?? []);
+    const target = resolveRoleTarget(workspace, args.role, {
+        provider: args.provider ?? null,
+        model: args.model ?? null,
+        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;
+    }
+    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.
+        }
+    };
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    let result;
+    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,
+        });
+    }
+    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 {
+        process.off("SIGINT", onSigint);
+        process.off("SIGTERM", onSigterm);
+    }
+    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() !== "") {
+        throw new ConfigurationError("--task cannot be combined with a session.");
+    }
+    if (sessionId !== null) {
+        requireAgentSession(workspace, sessionId);
+        return [sessionId, false];
+    }
+    const taskSummary = (task ?? role).trim();
+    return [createAgentSession(workspace, role, taskSummary), true];
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,35 @@
+import { type AgentAdapter } from "@nodeint/migent-kernel";
+import { type RunCommand, type Which } from "../provider.js";
+export interface ConfigPrompter {
+    select(message: string, choices: ReadonlyArray<readonly [string, string]>, defaultValue?: string | null): string | Promise<string>;
+    confirm(message: string): boolean | Promise<boolean>;
+    text(message: string, defaultValue?: string): string | Promise<string>;
+}
+export declare function runConfigShow(workspace: string): number;
+export declare function runConfigModel(workspace: string, options?: {
+    key?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    options?: readonly string[];
+    clearOptions?: readonly string[];
+    asJson?: boolean;
+    interactive?: boolean;
+    adapters?: Record<string, AgentAdapter> | null;
+    which?: Which | null;
+    prompter?: ConfigPrompter | null;
+    runCommand?: RunCommand | null;
+}): Promise<number>;
+export declare function runConfigRole(workspace: string, options?: {
+    roles?: readonly string[];
+    modelName?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    options?: readonly string[];
+    clearOptions?: readonly string[];
+    asJson?: boolean;
+    interactive?: boolean;
+    adapters?: Record<string, AgentAdapter> | null;
+    which?: Which | null;
+    prompter?: ConfigPrompter | null;
+    runCommand?: RunCommand | null;
+}): Promise<number>;