@maiaos/cli 0.1.0-canary.44938d4.manual.1

package/dist/turn/commands.js

@@ -0,0 +1,126 @@
+import { MAX_TURN_INPUT_BYTES, } from "@maiaos/sdk";
+import { CliArgumentError, parseOptions, readExpectedRevision, requirePositionals, } from "../command-line/arguments.js";
+import { writeNodeResult } from "../command-line/output.js";
+const utf8 = new TextEncoder();
+const summarizeTurnMutation = (result) => ({
+    delivery: result.delivery,
+    receipt: result.receipt,
+    revision: result.turn.revision,
+    sessionId: result.turn.sessionId,
+    state: result.turn.state,
+    turnId: result.turn.id,
+});
+const parseTurnSendArguments = (tokens) => {
+    const parsed = parseOptions(tokens, new Set(["--command-id", "--expected-revision"]), new Set(["--prompt-stdin"]));
+    requirePositionals(parsed.positionals, 1, "maia turn send <session-id> --prompt-stdin --expected-revision <revision>");
+    const sessionId = parsed.positionals[0];
+    if (sessionId === undefined) {
+        throw new CliArgumentError("The session identifier is missing.");
+    }
+    if (!parsed.flags.has("--prompt-stdin")) {
+        throw new CliArgumentError("Option '--prompt-stdin' is required.");
+    }
+    const commandId = parsed.options.get("--command-id");
+    return {
+        expectedRevision: readExpectedRevision(parsed.options.get("--expected-revision")),
+        sessionId,
+        ...(commandId === undefined ? {} : { commandId }),
+    };
+};
+const runTurnSend = async (tokens, context) => {
+    const input = parseTurnSendArguments(tokens);
+    if (context.io.stdin === undefined) {
+        throw new CliArgumentError("Standard input is unavailable.");
+    }
+    const prompt = await context.io.stdin({
+        label: "turn prompt",
+        maxBytes: MAX_TURN_INPUT_BYTES,
+        maxChunks: 1024,
+    });
+    const result = await context.dependencies.sendTurn({ ...input, prompt });
+    return writeNodeResult(result, context, (value) => ({
+        command: "turn.send",
+        result: summarizeTurnMutation(value),
+    }));
+};
+const parseTurnInterruptArguments = (tokens) => {
+    const parsed = parseOptions(tokens, new Set(["--command-id", "--expected-revision"]));
+    requirePositionals(parsed.positionals, 1, "maia turn interrupt <turn-id> --expected-revision <revision>");
+    const turnId = parsed.positionals[0];
+    if (turnId === undefined) {
+        throw new CliArgumentError("The turn identifier is missing.");
+    }
+    const commandId = parsed.options.get("--command-id");
+    return {
+        expectedRevision: readExpectedRevision(parsed.options.get("--expected-revision")),
+        turnId,
+        ...(commandId === undefined ? {} : { commandId }),
+    };
+};
+const runTurnInterrupt = async (tokens, context) => {
+    const input = parseTurnInterruptArguments(tokens);
+    const result = await context.dependencies.interruptTurn(input);
+    return writeNodeResult(result, context, (value) => ({
+        command: "turn.interrupt",
+        result: summarizeTurnMutation(value),
+    }));
+};
+const parseTurnShowArguments = (tokens, json) => {
+    const parsed = parseOptions(tokens, new Set(), new Set(["--include-content"]));
+    requirePositionals(parsed.positionals, 1, "maia turn show <turn-id>");
+    const includeContent = parsed.flags.has("--include-content");
+    if (includeContent && !json) {
+        throw new CliArgumentError("Option '--include-content' requires machine-readable '--json' output.");
+    }
+    const turnId = parsed.positionals[0];
+    if (turnId === undefined) {
+        throw new CliArgumentError("The turn identifier is missing.");
+    }
+    return { includeContent, turnId };
+};
+const turnTerminalProjection = (turn) => {
+    if (turn.state === "completed") {
+        return {
+            responseBytes: utf8.encode(turn.responseText).byteLength,
+            ...(turn.tokenUsage === undefined ? {} : { tokenUsage: turn.tokenUsage }),
+        };
+    }
+    return turn.state === "failed" || turn.state === "outcome-unknown"
+        ? { failureReason: turn.failureReason }
+        : {};
+};
+const projectTurnWithoutContent = (value) => ({
+    contentIncluded: false,
+    method: value.method,
+    turn: {
+        id: value.turn.id,
+        inputBytes: utf8.encode(value.turn.input.text).byteLength,
+        revision: value.turn.revision,
+        sessionId: value.turn.sessionId,
+        sessionRevision: value.turn.sessionRevision,
+        state: value.turn.state,
+        ...turnTerminalProjection(value.turn),
+    },
+});
+const summarizeTurnShow = (value, includeContent) => includeContent
+    ? { ...value, contentIncluded: true }
+    : projectTurnWithoutContent(value);
+const runTurnShow = async (tokens, context) => {
+    const input = parseTurnShowArguments(tokens, context.json);
+    const result = await context.dependencies.showTurn(input.turnId);
+    return writeNodeResult(result, context, (value) => ({
+        command: "turn.show",
+        result: summarizeTurnShow(value, input.includeContent),
+    }));
+};
+export const runTurnCommand = (tokens, context) => {
+    const [subcommand, ...rest] = tokens;
+    if (subcommand === "interrupt")
+        return runTurnInterrupt(rest, context);
+    if (subcommand === "send")
+        return runTurnSend(rest, context);
+    if (subcommand === "show")
+        return runTurnShow(rest, context);
+    throw new CliArgumentError("Usage: maia turn <interrupt|send|show>");
+};
+//# sourceMappingURL=commands.js.map

package/dist/turn/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const readTurnPrompt: (input: AsyncIterable<string | Uint8Array>) => Promise<string>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/turn/prompt.js

@@ -0,0 +1,9 @@
+import { MAX_TURN_INPUT_BYTES } from "@maiaos/sdk";
+import { readBoundedStdin } from "../command-line/stdin.js";
+const MAX_TURN_INPUT_CHUNKS = 1024;
+export const readTurnPrompt = async (input) => readBoundedStdin(input, {
+    label: "turn prompt",
+    maxBytes: MAX_TURN_INPUT_BYTES,
+    maxChunks: MAX_TURN_INPUT_CHUNKS,
+});
+//# sourceMappingURL=prompt.js.map

package/guidance/maia-cli/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: maia-cli
+description: >
+  Operate the public Maia CLI through JSON-first commands. Discover the
+  classified index with maia help --json, then maia help <family> --json for
+  usage rows. Inspect node status, register projects and workspaces, recover
+  receipts, probe Codex compatibility, and create or inspect sessions. Use
+  when an external agent must call maia rather than inventing a node API,
+  Skill install, or harness adapter.
+---
+
+# Maia CLI
+
+Call the installed `maia` binary. Treat the classified index from
+`maia help --json` plus the matching `maia help <family> --json` page as the
+only command list. Do not invent verbs. Do not write `~/.codex`, `~/.claude`,
+`~/.cursor`, `~/.grok`, or another native Skill root.
+
+## Discover, then invoke
+
+1. Run `maia help --json`. Use only `commands[].name` as the family allowlist.
+   The default index has no usage array.
+2. Run `maia help <family> --json` for that family's usage rows and
+   `availability` (`implemented` or `source_implemented_candidate`).
+3. Prefer `--json` on every node-facing command.
+4. Put secrets, graph JSON, and prompt bodies on stdin. Do not pass them as
+   argv.
+5. On failure, read stderr JSON. Recover a mutation with
+   `maia receipt show <command-id>` when a command id exists. If the
+   command id was lost, use `maia --json receipt list` as bounded
+   no-payload discovery, then show the known id.
+
+## Implemented foundation
+
+These are classified-help `implemented` commands. That help availability is
+not the AGENTS release-gated Implemented label and is not product
+enablement. Use them as source-callable current evidence.
+
+- `maia --json status`
+- `maia --json project add <repository>`
+- `maia --json project list`
+- `maia --json project show <project-id>`
+- `maia --json workspace list --project <project-id>`
+- `maia --json workspace show <workspace-id>`
+- `maia --json workspace repo add <workspace-id> <repository> --expected-revision <revision>`
+- `maia --json receipt list`
+- `maia --json receipt show <command-id>`
+- `maia --json runtime probe codex`
+- `maia --json session create <workspace-id> --runtime codex`
+- `maia --json session list --project <project-id>`
+- `maia --json session show <session-id>`
+- `maia --json session events <session-id>`
+
+`runtime probe codex` is a compatibility handshake. It does not log in, start a
+model turn, or authorize a harness.
+
+## Source candidates (do not treat as product)
+
+Mention these only when the caller already accepted a release-disabled
+candidate. They are not implemented product behavior.
+
+- `maia --json context show` — Client principal only; no mailbox.
+- `maia --json runtime list` — detection catalog; nothing is selected or
+  authorized.
+- `maia --json session start <session-id> --expected-revision <revision>` —
+  blocked activation candidate. Do not start Codex from this Skill.
+
+## Do not run
+
+Do not run Skill install/sync, Agent, Room, Routine, extension, integration, or
+any `runtime probe` other than `codex`. Those verbs are planned. Absence from
+the index `commands[]` and from the matching family `usage[]` is a deny.
+
+Do not infer Run, Session, or node identity from cwd, Git, or environment.
+Do not launch a harness process.

package/guidance/maia-orchestration/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: maia-orchestration
+description: >
+  Coordinate source-candidate, release-disabled local-v1 Maia Runs through the
+  public CLI: create, list, show, task list and show, inbox check and ack,
+  questions, and dispatch show or settle-terminal. Use when an external agent
+  is the explicit Run coordinator. Do not treat these commands as
+  release-enabled, worker assignment, or Orca equivalence.
+---
+
+# Maia orchestration
+
+Every command in this Skill is a **source-implemented candidate,
+release-disabled**. Confirm the usage exists on `maia help run --json` and is
+tagged `source_implemented_candidate` before running it. Do not start a
+worker, waiter, harness, or model turn.
+
+## Identity
+
+Supply explicit ids. Do not infer a Run from the terminal, cwd, Git, or
+environment. Do not use `--scope current`, `--run`, `--from`, or `--preamble`.
+
+After `run create`, keep `run.id`, `run.revision`, `dispatch.id`,
+`dispatch.revision`, both mailbox ids and revisions, and `receipt.commandId`
+from the compact CLI projection. Recover a Task objective with
+`run task show`. Recover Dispatch identity with `run dispatch show`.
+
+## Candidate commands
+
+Label every invocation as release-disabled when you describe it.
+
+- `maia --json run create <workspace-id> <terminal-id> --graph-stdin`
+- `maia --json run list --workspace <workspace-id>`
+- `maia --json run show <run-id>`
+- `maia --json run task list <run-id>`
+- `maia --json run task show <run-id> <task-id>`
+- `maia --json run inbox check <run-id> --owner <run|dispatch> --owner-id <id> --coordinator-epoch 1`
+- `maia --json run inbox ack <run-id> --owner <run|dispatch> --owner-id <id> --delivery-id <id> --expected-mailbox-revision <revision> --coordinator-epoch 1`
+- `maia --json run question open <run-id> <dispatch-id> --subject <text> --body-stdin --expected-run-revision <revision> --expected-dispatch-revision <revision> --coordinator-epoch 1`
+- `maia --json run question reply <run-id> <dispatch-id> <question-id> --answer-stdin --expected-run-revision <revision> --expected-dispatch-revision <revision> --expected-question-revision <revision> --coordinator-epoch 1`
+- `maia --json run question cancel <run-id> <dispatch-id> <question-id> --expected-run-revision <revision> --expected-dispatch-revision <revision> --expected-question-revision <revision> --coordinator-epoch 1`
+- `maia --json run dispatch show <run-id>`
+- `maia --json run dispatch settle-terminal <run-id> <dispatch-id> --expected-run-revision <revision> --expected-dispatch-revision <revision> --coordinator-epoch 1`
+
+Put the Task graph, Question body, and reply answer on stdin.
+
+## Do not run
+
+Do not wait, watch, or poll an inbox. Do not assign a worker. Do not settle a
+caller-selected outcome. `settle-terminal` only records the Terminal's exact
+unavailable failure. Do not teach Skill install/sync or extra runtime probes.
+
+A compact CLI projection is not a protocol change. The SDK remains lossless.
+No Orca command is equivalent.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@maiaos/cli",
+  "version": "0.1.0-canary.44938d4.manual.1",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "maia": "./dist/bin/maia.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/bin/*.meta.json",
+    "!dist/**/*.d.ts.map",
+    "!dist/**/*.js.map",
+    "!dist/**/*.mjs.map",
+    "!dist/bin/maia.d.ts",
+    "!dist/bin/maia.d.ts.map",
+    "guidance",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "24.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@vllnt/typescript": "1.0.0",
+    "eslint": "9.39.5",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@maiaos/sdk": "0.1.0-canary.44938d4.manual.1",
+    "effect": "4.0.0-beta.106"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{force:true,recursive:true})\" && tsc --project tsconfig.build.json && node scripts/build-executable.mjs",
+    "lint": "eslint src scripts --max-warnings 0",
+    "test": "node -e \"require('node:fs').rmSync('.test-dist',{force:true,recursive:true})\" && tsc --project tsconfig.test.json && node --test --test-concurrency=2 --enable-source-maps .test-dist/command-line/cli.test.js .test-dist/command-line/help.test.js .test-dist/command-line/stdin.test.js .test-dist/command-receipt/command.test.js .test-dist/command-receipt/compact-list.test.js .test-dist/context/commands.test.js .test-dist/execution/client.test.js .test-dist/execution/commands.test.js .test-dist/guidance/pack-contents.test.js .test-dist/integration-authorization/client.test.js .test-dist/integration-authorization/commands.test.js .test-dist/orchestration/compact-aggregate.test.js .test-dist/orchestration/compact-run-list.test.js .test-dist/orchestration/commands.test.js .test-dist/project-workspace/client.test.js .test-dist/project-workspace/commands.test.js .test-dist/runtime/command.test.js .test-dist/session/client.test.js .test-dist/session/commands.test.js .test-dist/status/command.test.js .test-dist/terminal/client.test.js .test-dist/terminal/compact-list.test.js .test-dist/terminal/commands.test.js .test-dist/turn/client.test.js .test-dist/turn/commands.test.js .test-dist/turn/prompt.test.js",
+    "typecheck": "tsc --project tsconfig.json --noEmit && tsc --project scripts/tsconfig.json --noEmit"
+  }
+}