@maiaos/cli 0.1.0-canary.2

package/README.md

@@ -0,0 +1,287 @@
+# `maia` CLI (`@maiaos/cli`)
+
+[![npm canary](https://img.shields.io/npm/v/@maiaos/cli/canary?label=npm%20canary)](https://www.npmjs.com/package/@maiaos/cli)
+
+The `maia` command-line tool and MCP server for Maia OS: start, drive, observe
+and stop swarms of AI coding agents (Claude Code and Codex workers) from a
+terminal, a script, or another agent such as Claude Code.
+
+The CLI is the reference Maia client and the first complete one. Every
+Node-facing command goes through [`@maiaos/sdk`](../../packages/sdk/README.md)
+to Maia Node; `--json` prints one bounded JSON result built for LLMs and
+scripts. `maia mcp` serves the same operations as MCP tools, and `maia agent`
+runs Maia's own coding agent.
+
+## Install
+
+From a source checkout (see the [quick start](../../README.md#quick-start)):
+
+```sh
+pnpm dev:cli          # installs ~/.local/bin/maia for this checkout
+pnpm maia help        # or run this checkout's CLI without installing
+```
+
+Each call runs the checkout around your working directory, so a dev worktree
+runs its own build against its own Node. Pre-release builds:
+`@maiaos/cli@nightly` and `@maiaos/cli@canary`; no stable release exists.
+
+## Example
+
+```sh
+maia status
+maia --json project list
+maia --json session create --workspace <workspace-id> --executor codex-cli --command-id create-1
+maia --json session start <session-id> --expected-revision 1 --command-id start-1 --wait
+printf '%s' "Explain the build" |
+  maia --json session turn send --session <session-id> --prompt-stdin --expected-revision <revision> --command-id send-1
+maia --json session turn wait <turn-id> --timeout 10m
+maia --json session turn show <turn-id> --include-content
+```
+
+`session create --message <text>` creates, starts and sends the first turn in
+one command, and `maia doctor` checks the installation, the Node and the
+accounts, naming the next command for each failure.
+
+A coding Session writes in a worktree of its own from a base ref; review and
+retire it with `diff` and `archive`
+([coding Sessions](../../docs/maia-swarm/external-executors.md#coding-sessions)):
+
+```sh
+maia --json session create --workspace <workspace-id> --executor claude-code --base main --command-id code-1
+maia session diff <session-id> --stat
+maia --json session archive <session-id> --expected-revision <revision> --command-id archive-1
+```
+
+## Commands
+
+`maia help` lists the root commands by section, and `-h` or `--help` works on
+every command (`maia session start --help`). `maia help --json` describes
+every command, with its availability (implemented or source candidate),
+example and operation, plus the [agent contract](../../docs/reference/cli.md#agent-contract);
+`maia <command> --help --json` adds typed arguments. Each command is authored
+once, as a leaf of a command-tree fragment in its feature's `tree/` scope;
+`src/command-tree/` holds the grammar, help and suggestions.
+
+Paths are scope-first: a noun, then a verb (`session turn send`,
+`connection capacity set`). The ID a command is about is positional; the ID of
+a parent or related resource is a flag (`--session`, `--workspace`, `--run`).
+An unknown or retired path prints `Did you mean 'maia ...'?` and runs nothing.
+Any resource argument takes an ID, an ID prefix or a unique name or Session
+title; the CLI asks the Node to resolve it and sends the exact ID. A missing
+required `--project` or `--workspace` comes from the current folder, then the
+selected Workspace ([references and defaults](../../docs/reference/cli.md#references-and-defaults)).
+List commands print plain header tables.
+
+| Family                                     | What it does                                                                                      |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `status`, `node status`, `node monitor`    | Node readiness and health (`status` is a shortcut); a one-time loopback URL for the admin monitor |
+| `setup`, `login`, `connection`             | Use installed vendor CLIs, sign in worker accounts and model providers, usage, capacity           |
+| `integration`, `provider`                  | Approve vendor executables; model-provider pools                                                  |
+| `project`, `workspace`, `container`        | Register repositories, Project guards, Workspaces and containers                                  |
+| `session`                                  | Create, rename, start, observe, stop, resume, diff and archive workers; adopt, message, approve   |
+| `session turn`                             | Send, show, wait for and interrupt turns                                                          |
+| `session approval`, `session interaction`  | What workers wait on a person for; record-only questions to a person                              |
+| `receipt`                                  | Look up the outcome of any mutation by command ID                                                 |
+| `port`                                     | Advisory loopback port leases for Sessions sharing one machine                                    |
+| `hold`                                     | Emergency holds on exact Projects and accounts; release them                                      |
+| `run`, `terminal`, `context`               | Runs and the Run ledger, terminals, context                                                       |
+| `execution`                                | Execution environments, worktrees, placements and relocation                                      |
+| `import`                                   | Find Claude Code and Codex sessions to adopt                                                      |
+| `presentation`                             | Read-only view specifications                                                                     |
+| `reference`                                | The exact ID of a name, ID prefix or title, or the current folder's Project or Workspace          |
+| `agent`                                    | Maia's interactive coding agent on the official Pi SDK                                            |
+| `mcp`                                      | Coordinator or worker MCP server over stdio                                                       |
+| `node install`, `node list`, `node remove` | Remote Nodes over SSH; `--node <name>` routes any command to one                                  |
+| `doctor`, `version`, `completion`          | Installation, Node and account check; version; shell completion (`bash`, `zsh`, `fish`)           |
+
+Global options may go anywhere before `--`:
+`maia [--json] [--profile <name>] [--node <name>] [--no-input] <command>`;
+everything after `--` belongs to the command, `--json` included. `--profile`
+selects a local Node runtime profile, not a configuration profile.
+`MAIA_PROFILE`, `MAIA_NODE` and `MAIA_NO_INPUT` stand in for `--profile`,
+`--node` and `--no-input` on the commands that take them; a flag wins.
+`--timeout` and `--stall-after` take durations such as `30s`, `10m` or `1h`;
+lists show 20 items per page unless their usage shows another range. `maia version --json` reports the
+version, the protocol and, in a build made with `MAIA_CLI_BUILD_COMMIT`, the
+commit. `-v` is not an option; use `--version` or `maia version`.
+`maia completion <bash|zsh|fish>` prints a completion script generated from
+the command tree.
+
+## Output and exit codes
+
+A JSON result is `{ "ok": true, "result": { "command", "result" } }` on stdout
+or `{ "ok": false, "error": { "code", "message", "retryable" } }` on stderr;
+a usage error adds the command's `usage` lines and a `hint`.
+
+| Exit | Meaning                                                              |
+| ---- | -------------------------------------------------------------------- |
+| 0    | Done                                                                 |
+| 64   | Invalid usage                                                        |
+| 66   | Unknown ID                                                           |
+| 69   | Node unavailable                                                     |
+| 70   | Other failure, a waited turn that failed, or a failed `doctor` check |
+| 74   | Deadline reached (for example `session turn wait`)                   |
+| 75   | Retry later: revision changed, full, limited, held                   |
+| 76   | Outcome unknown: check `maia receipt show`                           |
+| 77   | Not permitted                                                        |
+
+Mutations take the current revision and a command ID you choose. Retry with
+the same command ID; the Node replays the first result instead of acting twice.
+A person-facing prompt appears only at a terminal, without `--json` and
+`--no-input`; otherwise the command exits 64 and names its flags.
+
+A consequential mutation that needs a preview is two-phase. `--dry-run`
+previews and `--confirm-stdin` confirms a preview piped back. At a terminal a
+command that takes its request as flags (`session adopt`, `project guard set`,
+`setup`, `node install`, `node remove`) previews and asks y/N; one that reads
+its request from `--input-stdin` never prompts, so it needs `--dry-run` or
+`--confirm-stdin`:
+
+```sh
+maia --json hold place --input-stdin --dry-run < in.json | maia hold place --confirm-stdin
+```
+
+## Sign-in
+
+```sh
+maia connection detect         # the installed claude and codex as the Node sees them
+maia setup [--max-sessions 4]  # use them as they are: system-default accounts
+maia login                     # list worker accounts and model providers
+maia login claude              # add or re-sign a Claude Code account
+maia login codex [--name codex-2] [--device-code]
+maia login vercel-ai-gateway   # a model provider from Pi's catalog
+maia connection usage show codex-1 [--refresh]
+printf %s "$AI_GATEWAY_API_KEY" | maia login gateway --name vercel \
+  --base-url https://ai-gateway.vercel.sh --api-key-stdin
+maia connection models list --connection vercel
+maia session create --workspace <workspace-id> --connection vercel \
+  --executor claude-code --model anthropic/claude-sonnet-4.5
+```
+
+`maia login claude` and `maia login codex` run the vendor's own sign-in for a
+Maia-managed account root; Maia never reads or stores that credential. Model
+providers store one credential per provider in Maia's `auth.json`. On a server,
+Codex signs in with a device code and Claude Code with a link and a pasted
+code. A person approves vendor executables with `maia integration plan
+<codex|claude-code>` and `maia integration apply <codex|claude-code> --plan
+<plan-id>`. `maia connection capacity set` changes an account's session cap. A gateway Connection lets
+Claude Code and Codex Sessions use an AI gateway's models with its API key,
+which the CLI reads from stdin and never prints; a subscription proxy can
+breach provider terms, so prefer an API-key gateway.
+
+## Coordinator MCP server
+
+`maia mcp` serves 43 coordinator tools over stdio (MCP protocol 2025-06-18),
+such as `session_create`, `turn_send`, `turn_wait`, `port_lease_acquire`,
+`reference_resolve` and `receipt_get`. Their input schemas are generated from `@maiaos/protocol`, so
+they never drift from the JSON commands. Accounts, integrations, confirmations
+and answers are not exposed; the only human-only operation exposed is
+`turn.send`, which the coordinator sends as the operator's client. The
+[`maia` plugin](../../plugins/maia) registers this server and ships the
+`maia-orchestration` Skill for Claude Code and Codex
+([setup](../../README.md#4-drive-maia-from-claude-code-or-codex)). An invalid
+argument names the failing field in the error message.
+
+## Worker Sessions, roles and guards (source candidate)
+
+A Codex or Claude Code Session that Maia launches gets its own credential in
+`MAIA_SESSION_CREDENTIAL` and the Node's loopback origin in `MAIA_NODE_ORIGIN`,
+never the operator's bearer. With that credential, `maia` and `maia mcp` act
+as the Session within its role: a `worker` reads its context, Node status and
+its Project's Session list and manages its own port leases; an `orchestrator` may also read its Project's
+guards and create child Sessions. Anything else fails with `role_denied`
+(exit 77). Without a valid `MAIA_NODE_ORIGIN` the command fails closed; it
+never falls back to the operator's profile. With a Session credential,
+`maia session list --all` still lists only that Session's Project; naming a
+different Project fails with `role_denied`. Human and external-coordinator
+lists remain unchanged.
+
+Coding workers receive a launch-configured `maia_worker` MCP server running
+`maia mcp --worker`. The vendor starts it outside its tool sandbox; the
+sandbox keeps its existing filesystem and network limits. `--worker` requires
+the Session environment even when both variables are missing. Plain `maia mcp`
+also selects worker tools when either variable is present. Only Project-scoped `session_list`, `context_show`,
+`node_status` and the four `port_lease_*` tools are exposed. Node authentication
+checks expiry and revocation on every call.
+
+```sh
+maia session create --workspace <workspace-id> --role orchestrator
+maia project guard show <project-id>
+maia --json project guard set <project-id> --expected-revision 0 \
+  --max-depth 2 --max-live-children 4 --max-messages-per-minute 60 \
+  --max-leases-per-session 8 --dry-run |
+  maia project guard set --confirm-stdin
+```
+
+A person previews a Project's guards and confirms the preview within 30
+seconds (at a terminal, `project guard set` previews and asks y/N); human
+preview text never shows the proof. The Node enforces the
+guards when a Session creates a child, sends a message or leases a port. A
+full guard exits 75; the depth guard exits 70 until a person raises it.
+
+## Emergency holds (source candidate)
+
+```sh
+# place.json: {commandId, reason, running, targets}
+maia --json hold place --input-stdin --dry-run < place.json | maia hold place --confirm-stdin
+maia hold list --state active
+# release.json: {commandId, holdId, expectedRevision}
+maia --json hold release --input-stdin --dry-run < release.json | maia hold release --confirm-stdin
+```
+
+A hold names exact Projects or accounts, for example
+`"targets": [{ "kind": "project", "id": "project_..." }]`; there is no `all`.
+`"running": "keep"` rejects new work; `"running": "stop"` also stops the
+Sessions the preview lists. Work refused by a hold exits 75 and names the
+hold. There is no automatic confirmation, and no coordinator tool can place
+or release a hold.
+
+## External questions and recorded answers (source candidate)
+
+```sh
+maia --json session interaction create --input-stdin
+maia --json session interaction list --session <session-id> --project <project-id> --status pending --limit 8
+maia --json session interaction respond --input-stdin
+```
+
+A question or selection is attached to an idle Session and answered by a
+person. Answers are recorded data, never approval to act. Inputs are strict
+JSON on stdin; reuse the same command ID after an uncertain result and
+reconcile with `maia receipt show`. See the
+[interaction contract](../../packages/protocol/src/interaction/README.md).
+
+## Status
+
+Source-implemented candidate; many families are release-disabled, as
+`maia help --json` reports. Planned: `maia session attach` with live streaming
+(S12), `maia lock` (S16), `maia node install` for fleets (S14) and
+`maia update` (RL4). A team Workspace first-owner bootstrap is
+designed, not implemented; see
+[team Workspaces and Control Nodes](../../docs/team-workspaces-and-control-nodes.md).
+
+## Development
+
+```sh
+pnpm --filter @maiaos/cli build
+pnpm --filter @maiaos/cli lint
+pnpm --filter @maiaos/cli typecheck
+pnpm --filter @maiaos/cli test
+```
+
+The release entry is a standalone, tree-shaken executable with a 355 KiB hard
+ceiling; `src/bin/maia.test.ts` locks the packed contents and size. The
+package's library entry exports `makeCli` and `runCli`, which return an Effect
+of the exit code ([D-068](../../docs/decisions.md#d-068)); the `maia` binary
+runs that Effect on one runtime per process.
+
+## Documentation
+
+- [CLI reference](../../docs/reference/cli.md): the complete target grammar and
+  JSON contracts
+- [Normative contracts](../../docs/reference/contracts.md)
+- [`maia agent`](../../packages/agent/README.md) and
+  [Maia Node](../../services/node/README.md)
+
+## License
+
+No license has been published yet. All rights reserved.

package/dist/bin/maia.NOTICES.txt

@@ -0,0 +1,59 @@
+Maia CLI third-party notices
+
+Generated from the exact esbuild input graph. Do not edit by hand.
+
+================================================================================
+@effect/platform-node-shared 4.0.0
+Declared license: MIT
+Bundled source: node_modules/.pnpm/@effect+platform-node-shared@4.0.0_effect@4.0.0/node_modules/@effect/platform-node-shared
+
+--- node_modules/.pnpm/@effect+platform-node-shared@4.0.0_effect@4.0.0/node_modules/@effect/platform-node-shared/LICENSE ---
+MIT License
+
+Copyright (c) 2023 Effectful Technologies Inc
+
+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.
+
+================================================================================
+effect 4.0.0
+Declared license: MIT
+Bundled source: node_modules/.pnpm/effect@4.0.0/node_modules/effect
+
+--- node_modules/.pnpm/effect@4.0.0/node_modules/effect/LICENSE ---
+MIT License
+
+Copyright (c) 2023 Effectful Technologies Inc
+
+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/dist/bin/maia.cdx.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://cyclonedx.org/schema/bom-1.6.schema.json",
+  "bomFormat": "CycloneDX",
+  "components": [
+    {
+      "bom-ref": "@effect/platform-node-shared@4.0.0",
+      "licenses": [
+        {
+          "license": {
+            "name": "MIT"
+          }
+        }
+      ],
+      "name": "@effect/platform-node-shared",
+      "properties": [
+        {
+          "name": "maia:source-kind",
+          "value": "third-party"
+        },
+        {
+          "name": "maia:source-path",
+          "value": "node_modules/.pnpm/@effect+platform-node-shared@4.0.0_effect@4.0.0/node_modules/@effect/platform-node-shared"
+        }
+      ],
+      "purl": "pkg:npm/%40effect/platform-node-shared@4.0.0",
+      "scope": "required",
+      "type": "library",
+      "version": "4.0.0"
+    },
+    {
+      "bom-ref": "@maiaos/protocol@0.1.0-canary.2",
+      "name": "@maiaos/protocol",
+      "properties": [
+        {
+          "name": "maia:source-kind",
+          "value": "workspace"
+        },
+        {
+          "name": "maia:source-path",
+          "value": "packages/protocol"
+        }
+      ],
+      "purl": "pkg:npm/%40maiaos/protocol@0.1.0-canary.2",
+      "scope": "required",
+      "type": "library",
+      "version": "0.1.0-canary.2"
+    },
+    {
+      "bom-ref": "@maiaos/sdk@0.1.0-canary.2",
+      "name": "@maiaos/sdk",
+      "properties": [
+        {
+          "name": "maia:source-kind",
+          "value": "workspace"
+        },
+        {
+          "name": "maia:source-path",
+          "value": "packages/sdk"
+        }
+      ],
+      "purl": "pkg:npm/%40maiaos/sdk@0.1.0-canary.2",
+      "scope": "required",
+      "type": "library",
+      "version": "0.1.0-canary.2"
+    },
+    {
+      "bom-ref": "effect@4.0.0",
+      "licenses": [
+        {
+          "license": {
+            "name": "MIT"
+          }
+        }
+      ],
+      "name": "effect",
+      "properties": [
+        {
+          "name": "maia:source-kind",
+          "value": "third-party"
+        },
+        {
+          "name": "maia:source-path",
+          "value": "node_modules/.pnpm/effect@4.0.0/node_modules/effect"
+        }
+      ],
+      "purl": "pkg:npm/effect@4.0.0",
+      "scope": "required",
+      "type": "library",
+      "version": "4.0.0"
+    }
+  ],
+  "dependencies": [
+    {
+      "dependsOn": [
+        "@effect/platform-node-shared@4.0.0",
+        "@maiaos/protocol@0.1.0-canary.2",
+        "@maiaos/sdk@0.1.0-canary.2",
+        "effect@4.0.0"
+      ],
+      "ref": "@maiaos/cli@0.1.0-canary.2"
+    },
+    {
+      "dependsOn": [],
+      "ref": "@effect/platform-node-shared@4.0.0"
+    },
+    {
+      "dependsOn": [],
+      "ref": "@maiaos/protocol@0.1.0-canary.2"
+    },
+    {
+      "dependsOn": [],
+      "ref": "@maiaos/sdk@0.1.0-canary.2"
+    },
+    {
+      "dependsOn": [],
+      "ref": "effect@4.0.0"
+    }
+  ],
+  "metadata": {
+    "component": {
+      "bom-ref": "@maiaos/cli@0.1.0-canary.2",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "8e39714f458fb216a194c19e86a491c4ea7cda05a1c257b6d973bced5c93e818"
+        }
+      ],
+      "name": "@maiaos/cli",
+      "type": "application",
+      "version": "0.1.0-canary.2"
+    },
+    "properties": [
+      {
+        "name": "maia:artifact",
+        "value": "dist/bin/maia.mjs"
+      },
+      {
+        "name": "maia:generator",
+        "value": "apps/cli/scripts/build-executable.mjs"
+      }
+    ]
+  },
+  "specVersion": "1.6",
+  "version": 1
+}