pandora-cli-skills 1.1.33 → 1.1.35

package/README.md

@@ -1,6 +1,6 @@
 # Pandora CLI & Skills
 
-Production CLI for Pandora prediction markets with mirror + hedge tooling.
+Production CLI for Pandora prediction markets with mirror + hedge tooling and agent-native interfaces.
 
 ## Install
 
@@ -15,7 +15,58 @@ Or run without installing:
 npx pandora-cli-skills@latest --help
 ```
 
-## Core commands
+## Agent-Native Features
+
+- `pandora --output json schema`
+  - emits machine-readable envelope schema + command descriptors.
+- `pandora mcp`
+  - runs an MCP server over stdio (`tools/list`, `tools/call`) for direct agent tool execution.
+- JSON errors include optional next-best-action recovery hints:
+  - `error.recovery = { action, command, retryable }`.
+- Attach-only fork runtime for on-chain command families:
+  - `--fork`, `--fork-rpc-url`, `--fork-chain-id`.
+- Event-driven streaming:
+  - `pandora stream prices|events` emits NDJSON lines on stdout.
+
+## Quickstart
+
+```bash
+# schema for typed consumers (Pydantic/Zod/etc.)
+pandora --output json schema
+
+# MCP server mode
+pandora mcp
+
+# Read-only market discovery
+pandora --output json markets list --active --limit 10
+
+# Dry-run trade with fork runtime
+pandora --output json trade --dry-run \
+  --market-address 0x... --side yes --amount-usdc 10 \
+  --fork --fork-rpc-url http://127.0.0.1:8545
+
+# NDJSON stream
+pandora stream prices --indexer-url https://pandoraindexer.up.railway.app/ --interval-ms 1000
+```
+
+## Fork Mode Notes
+
+- Runtime marker is included in payloads: `data.runtime.mode = "fork" | "live"`.
+- Fork RPC precedence:
+  1. `--fork-rpc-url`
+  2. `FORK_RPC_URL` (when `--fork` is set)
+  3. command default live RPC path
+- `polymarket trade --execute` in fork mode is simulation-only unless `--polymarket-mock-url` is provided.
+
+## Streaming Contract
+
+`pandora stream prices|events` outputs NDJSON only (one JSON object per line), for example:
+
+```json
+{"type":"stream.tick","channel":"prices","seq":1,"ts":"2026-03-01T12:00:00.000Z","source":{"transport":"polling"},"data":{"id":"market-1","yesPct":58.12}}
+```
+
+## Command Surface
 
 - `pandora markets list|get`
 - `pandora quote`
@@ -26,17 +77,15 @@ npx pandora-cli-skills@latest --help
 - `pandora autopilot run|once`
 - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close`
 - `pandora polymarket check|approve|preflight|trade`
+- `pandora resolve`
+- `pandora lp add|remove|positions`
+- `pandora stream prices|events`
+- `pandora schema`
+- `pandora mcp`
 
-## Mirror economics commands
-
-- `pandora mirror lp-explain --liquidity-usdc 10000 --source-yes-pct 58`
-- `pandora mirror hedge-calc --reserve-yes-usdc 8 --reserve-no-usdc 12 --excess-no-usdc 2 --polymarket-yes-pct 60`
-- `pandora mirror simulate --liquidity-usdc 10000 --source-yes-pct 58 --target-yes-pct 58 --volume-scenarios 1000,5000,10000`
+## Docs
 
-## Notes
+- Full command contract and workflows: [`SKILL.md`](./SKILL.md)
+- Operator + package documentation: [`README_FOR_SHARING.md`](./README_FOR_SHARING.md)
 
-- Node.js `>=18` required.
-- Full CLI skill contract, error semantics, and workflow references are documented in
-  [`SKILL.md`](./SKILL.md).
-- Full operational and JSON contract documentation is in
-  [`README_FOR_SHARING.md`](./README_FOR_SHARING.md).
+Node.js `>=18` required.

package/README_FOR_SHARING.md

@@ -56,6 +56,20 @@ Prerequisite: Node.js `>=18`.
   - `pandora --output json doctor`
   - `pandora --output table polls list --limit 10`
   - `--output json` is supported for all commands except `launch`/`clone-bet`; those stream script output directly.
+- Agent-native schema + MCP:
+  - `pandora --output json schema`
+  - `pandora mcp`
+  - MCP exposes one tool per command family entrypoint and reuses CLI JSON envelopes.
+- Next Best Action recovery hints:
+  - JSON errors can include `error.recovery = { action, command, retryable }`.
+  - existing `error.code`, `error.message`, and `error.details` fields are preserved.
+- Attach-only fork runtime:
+  - shared flags: `--fork`, `--fork-rpc-url <url>`, `--fork-chain-id <id>`.
+  - payloads include runtime marker (`runtime.mode = "fork" | "live"`).
+  - precedence: `--fork-rpc-url` > `FORK_RPC_URL` (when `--fork`) > normal runtime path.
+- NDJSON streaming:
+  - `pandora stream prices|events [--indexer-url <url>] [--indexer-ws-url <url>] [--interval-ms <ms>] [--limit <n>]`.
+  - always emits NDJSON lines to stdout; WebSocket-first with polling fallback.
 - Guided setup:
   - `pandora setup`
   - `pandora setup --check-usdc-code`
@@ -77,7 +91,9 @@ Prerequisite: Node.js `>=18`.
   - `pandora markets list --with-odds` (include YES/NO percentage odds inline)
   - `pandora markets list --active|--resolved|--expiring-soon` (lifecycle convenience filters)
   - `pandora markets get --id <market-id> --id <market-id>` (batch lookup in one call)
-  - `pandora --output json scan` (single-pass market discovery payload for automation)
+- `pandora --output json scan` (single-pass market discovery payload for automation)
+- `pandora stream prices` (reactive market ticks in NDJSON)
+- `pandora stream events` (reactive event feed in NDJSON)
 - Phase 2 trading helpers:
   - `pandora quote --market-address <0x...> --side yes|no --amount-usdc <amount>`
   - `pandora trade --dry-run --market-address <0x...> --side yes|no --amount-usdc <amount> [--max-amount-usdc <amount>] [--min-probability-pct <0-100>] [--max-probability-pct <0-100>]`
@@ -97,7 +113,45 @@ Prerequisite: Node.js `>=18`.
   - `pandora analyze --market-address <0x...> --provider <name>`
   - `pandora suggest --wallet <0x...> --risk low|medium|high --budget <amount>`
   - `pandora resolve`
-  - `pandora lp add|remove|positions`
+- `pandora lp add|remove|positions`
+
+## Agent-native expansion details
+
+### MCP server (`pandora mcp`)
+- Runs MCP server over stdio with tool discovery + execution.
+- `tools/list` includes JSON-capable command tools (for example `markets.list`, `trade`, `mirror.plan`, `polymarket.check`).
+- `launch` and `clone-bet` are intentionally not exposed over MCP because they stream script output.
+- MCP safety rails:
+  - mutating tools require explicit execute intent (`intent.execute=true`) for live execution.
+  - long-running modes are blocked in v1 (`watch`, `autopilot run`, `mirror sync run/start`).
+
+### Next Best Action recovery hints
+- Structured JSON errors may include:
+  - `error.recovery.action`
+  - `error.recovery.command`
+  - `error.recovery.retryable`
+- This supports automatic recovery flows in agents while keeping backward compatibility for existing JSON parsers.
+
+### Fork runtime support
+- Supported families:
+  - `trade`
+  - `resolve`
+  - `lp`
+  - `polymarket check|approve|preflight|trade`
+- `polymarket trade --execute` in fork mode is simulation-only unless `--polymarket-mock-url` is provided.
+
+### NDJSON stream command
+- `pandora stream prices|events` always emits NDJSON (ignores table rendering path for active stream output).
+- Tick envelope includes:
+  - `type`
+  - `ts`
+  - `seq`
+  - `channel`
+  - `source.transport`
+  - `data`
+- Transport behavior:
+  - primary: WebSocket (`--indexer-ws-url` or derived URL)
+  - fallback: polling (`source.transport = "polling"`)
 
 Mirror advanced flags (for operator tuning):
 - `--sync-interval-ms <ms>` on `mirror go` to control auto-sync tick cadence.

package/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: pandora-cli-skills
 summary: Canonical skill and operator guide for Pandora CLI including mirror, polymarket, resolve, and LP flows.
+version: 1.1.35
 ---
 
 # Pandora CLI & Skills
@@ -37,6 +38,8 @@ npm link
 ## CLI ergonomics
 - Global output mode: `--output table|json` (default `table`)
 - `--output json` is supported for all commands except `launch`/`clone-bet`; those stream script output directly.
+- Agent schema command: `pandora --output json schema`
+- MCP server mode: `pandora mcp`
 - Guided setup command: `pandora setup`
 - Phase 1 discovery command: `pandora scan`
 - Phase 1 lifecycle filters: `pandora markets list --active|--resolved|--expiring-soon`
@@ -57,6 +60,13 @@ npm link
   - `pandora suggest`
   - `pandora resolve`
   - `pandora lp add|remove|positions`
+  - `pandora stream prices|events`
+- Fork runtime flags for transaction families:
+  - `--fork`
+  - `--fork-rpc-url <url>`
+  - `--fork-chain-id <id>`
+- JSON errors can include additive recovery hints:
+  - `error.recovery = { action, command, retryable }`
 - Doctor checks:
   - env presence + format validation
   - RPC reachability and chain id match
@@ -82,7 +92,7 @@ pandora [--output table|json] portfolio --wallet <address> [--chain-id <id>] [--
 pandora [--output table|json] watch [--wallet <address>] [--market-address <address>] [--side yes|no] [--amount-usdc <amount>] [--iterations <n>] [--interval-ms <ms>] [--chain-id <id>] [--include-events|--no-events] [--yes-pct <0-100>] [--alert-yes-below <0-100>] [--alert-yes-above <0-100>] [--alert-net-liquidity-below <amount>] [--alert-net-liquidity-above <amount>] [--fail-on-alert]
 pandora [--output table|json] scan [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--chain-id <id>] [--creator <address>] [--poll-address <address>] [--market-type <type>] [--where-json <json>] [--active|--resolved|--expiring-soon] [--expiring-hours <n>] [--expand]
 pandora [--output table|json] quote [--indexer-url <url>] [--timeout-ms <ms>] --market-address <address> --side yes|no --amount-usdc <amount> [--yes-pct <0-100>] [--slippage-bps <0-10000>]
-pandora [--output table|json] trade [--indexer-url <url>] [--timeout-ms <ms>] [--dotenv-path <path>] [--skip-dotenv] --market-address <address> --side yes|no --amount-usdc <amount> --dry-run|--execute [--yes-pct <0-100>] [--slippage-bps <0-10000>] [--min-shares-out-raw <uint>] [--max-amount-usdc <amount>] [--min-probability-pct <0-100>] [--max-probability-pct <0-100>] [--allow-unquoted-execute] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--usdc <address>]
+pandora [--output table|json] trade [--indexer-url <url>] [--timeout-ms <ms>] [--dotenv-path <path>] [--skip-dotenv] --market-address <address> --side yes|no --amount-usdc <amount> --dry-run|--execute [--yes-pct <0-100>] [--slippage-bps <0-10000>] [--min-shares-out-raw <uint>] [--max-amount-usdc <amount>] [--min-probability-pct <0-100>] [--max-probability-pct <0-100>] [--allow-unquoted-execute] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--usdc <address>]
 pandora [--output table|json] history --wallet <address> [--chain-id <id>] [--market-address <address>] [--side yes|no|both] [--status all|open|won|lost|closed] [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by timestamp|pnl|entry-price|mark-price] [--order-direction asc|desc] [--include-seed]
 pandora [--output table|json] export --wallet <address> --format csv|json [--chain-id <id>] [--year <yyyy>] [--from <unix>] [--to <unix>] [--out <path>]
 pandora [--output table|json] arbitrage [--chain-id <id>] [--venues pandora,polymarket] [--limit <n>] [--min-spread-pct <n>] [--min-liquidity-usdc <n>] [--max-close-diff-hours <n>] [--similarity-threshold <0-1>] [--cross-venue-only|--allow-same-venue] [--with-rules] [--include-similarity] [--question-contains <text>] [--polymarket-host <url>] [--polymarket-mock-url <url>]
@@ -93,8 +103,11 @@ pandora [--output table|json] webhook test [--webhook-url <url>] [--webhook-temp
 pandora [--output table|json] leaderboard [--metric profit|volume|win-rate] [--chain-id <id>] [--limit <n>] [--min-trades <n>]
 pandora [--output table|json] analyze --market-address <address> [--provider <name>] [--model <id>] [--max-cost-usd <n>] [--temperature <n>] [--timeout-ms <ms>]
 pandora [--output table|json] suggest --wallet <address> --risk low|medium|high --budget <amount> [--count <n>] [--include-venues pandora,polymarket]
-pandora [--output table|json] resolve --poll-address <address> --answer yes|no --reason <text> --dry-run|--execute [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>]
-pandora [--output table|json] lp add|remove|positions [--market-address <address>] [--wallet <address>] [--amount-usdc <n>] [--lp-tokens <n>] [--dry-run|--execute] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--usdc <address>] [--deadline-seconds <n>] [--indexer-url <url>] [--timeout-ms <ms>]
+pandora [--output table|json] resolve --poll-address <address> --answer yes|no|invalid --reason <text> --dry-run|--execute [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>]
+pandora [--output table|json] lp add|remove|positions [--market-address <address>] [--wallet <address>] [--amount-usdc <n>] [--lp-tokens <n>] [--dry-run|--execute] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--usdc <address>] [--deadline-seconds <n>] [--indexer-url <url>] [--timeout-ms <ms>]
+pandora stream prices|events [--indexer-url <url>] [--indexer-ws-url <url>] [--timeout-ms <ms>] [--interval-ms <ms>] [--market-address <address>] [--chain-id <id>] [--limit <n>]
+pandora [--output json] schema
+pandora mcp
 pandora launch [--dotenv-path <path>] [--skip-dotenv] [script args...]
 pandora clone-bet [--dotenv-path <path>] [--skip-dotenv] [script args...]
 ```
@@ -125,10 +138,10 @@ sync status --pid-file <path>|--strategy-hash <hash>
 Polymarket subcommand detail:
 
 ```text
-check [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
-approve --dry-run|--execute [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
-preflight [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
-trade --condition-id <id>|--slug <slug>|--token-id <id> --token yes|no --amount-usdc <n> --dry-run|--execute [--side buy|sell] [--polymarket-host <url>] [--timeout-ms <ms>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
+check [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
+approve --dry-run|--execute [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
+preflight [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
+trade --condition-id <id>|--slug <slug>|--token-id <id> --token yes|no --amount-usdc <n> --dry-run|--execute [--side buy|sell] [--polymarket-host <url>] [--polymarket-mock-url <url>] [--timeout-ms <ms>] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
 ```
 
 ## Read-only indexer commands
@@ -187,6 +200,7 @@ pandora --output json webhook test --webhook-url https://example.com/hook
 pandora --output json leaderboard --metric profit --limit 20
 pandora --output json analyze --market-address <0x...> --provider mock
 pandora --output json suggest --wallet <0x...> --risk medium --budget 50 --include-venues pandora
+pandora --output json schema
 ```
 
 ## Phase 1 JSON contracts
@@ -342,7 +356,53 @@ Common structured error codes for automation:
 - `WEBHOOK_DELIVERY_FAILED`: webhook hard-fail when `--fail-on-webhook-error` is set.
 
 Error envelope:
-- `{ ok: false, error: { code, message, details? } }`
+- `{ ok: false, error: { code, message, details?, recovery?: { action, command, retryable } } }`
+
+## MCP server mode
+- Start server:
+  - `pandora mcp`
+- Transport:
+  - MCP stdio JSON-RPC.
+- Tool model:
+  - one tool per command family entrypoint (for example `markets.list`, `trade`, `mirror.plan`, `polymarket.check`).
+- Exclusions in v1:
+  - `launch`, `clone-bet` are intentionally not exposed because they stream interactive script output.
+- Guardrails in v1:
+  - mutating tools require explicit execute intent (`intent.execute=true`) for live execution.
+  - long-running modes are blocked (`watch`, `autopilot run`, `mirror sync run|start`) with actionable structured errors.
+
+## Next Best Action recovery hints
+- JSON errors may include additive recovery guidance:
+  - `error.recovery.action`: short recovery label.
+  - `error.recovery.command`: copy-pasteable remediation command.
+  - `error.recovery.retryable`: whether retry is expected to succeed after recovery.
+- `details.hints` is preserved for human operators.
+
+## Fork runtime (attach-only)
+- Shared flags:
+  - `--fork`
+  - `--fork-rpc-url <url>`
+  - `--fork-chain-id <id>`
+- URL precedence in fork mode:
+  1. `--fork-rpc-url`
+  2. `FORK_RPC_URL` (when `--fork`)
+  3. command live RPC path
+- Commands annotate runtime mode in payload:
+  - `runtime.mode = "fork" | "live"`.
+- `polymarket trade` in fork mode:
+  - default is simulation-only.
+  - `--execute` requires `--polymarket-mock-url`.
+
+## Stream command (NDJSON)
+- Usage:
+  - `pandora stream prices|events [--indexer-url <url>] [--indexer-ws-url <url>] [--timeout-ms <ms>] [--interval-ms <ms>] [--market-address <address>] [--chain-id <id>] [--limit <n>]`
+- Output:
+  - NDJSON only (one JSON object per line to stdout), regardless of table/json global mode.
+- Tick envelope fields:
+  - `type`, `ts`, `seq`, `channel`, `source.transport`, `source.url`, `data`.
+- Transport behavior:
+  - WebSocket-first when `--indexer-ws-url` is provided/derivable.
+  - polling fallback with `source.transport = "polling"`.
 
 ## Additional JSON response shapes
 - `doctor`:

package/cli/lib/cli_output_service.cjs

@@ -9,6 +9,7 @@ function createCliOutputService(options = {}) {
       ? options.defaultSchemaVersion.trim()
       : '1.0.0';
   const CliError = options.CliError;
+  const getRecoveryForError = typeof options.getRecoveryForError === 'function' ? options.getRecoveryForError : null;
 
   if (typeof CliError !== 'function') {
     throw new Error('createCliOutputService requires CliError class.');
@@ -43,16 +44,36 @@ function createCliOutputService(options = {}) {
       if (error.details !== undefined) {
         envelope.error.details = error.details;
       }
+      if (getRecoveryForError) {
+        const recovery = getRecoveryForError({
+          code: error.code,
+          message: error.message,
+          details: error.details,
+        });
+        if (recovery) {
+          envelope.error.recovery = recovery;
+        }
+      }
       return envelope;
     }
 
-    return {
+    const fallback = {
       ok: false,
       error: {
         code: 'UNEXPECTED_ERROR',
         message: formatErrorValue(error && error.message ? error.message : error),
       },
     };
+    if (getRecoveryForError) {
+      const recovery = getRecoveryForError({
+        code: 'UNEXPECTED_ERROR',
+        message: fallback.error.message,
+      });
+      if (recovery) {
+        fallback.error.recovery = recovery;
+      }
+    }
+    return fallback;
   }
 
   function attachJsonMetadata(data) {
@@ -100,6 +121,9 @@ function createCliOutputService(options = {}) {
           console.error(`Details: ${String(envelope.error.details)}`);
         }
       }
+      if (envelope.error.recovery && envelope.error.recovery.command) {
+        console.error(`Next: ${envelope.error.recovery.command}`);
+      }
     }
 
     process.exit(error instanceof CliError ? error.exitCode : 1);

package/cli/lib/command_executor_service.cjs

@@ -0,0 +1,189 @@
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function coerceErrorMessage(value) {
+  if (typeof value === 'string') return value;
+  if (value && typeof value.message === 'string') return value.message;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function parseEnvelopeCandidate(text) {
+  const candidate = String(text || '').trim();
+  if (!candidate) return null;
+  try {
+    const parsed = JSON.parse(candidate);
+    if (parsed && typeof parsed === 'object' && typeof parsed.ok === 'boolean') {
+      return parsed;
+    }
+  } catch {
+    // continue with extraction path
+  }
+  return null;
+}
+
+function extractLastJsonObject(text) {
+  const source = String(text || '');
+  if (!source) return null;
+
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escaped = false;
+  let last = null;
+
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === '\\') {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (ch === '{') {
+      if (depth === 0) start = i;
+      depth += 1;
+      continue;
+    }
+
+    if (ch === '}' && depth > 0) {
+      depth -= 1;
+      if (depth === 0 && start >= 0) {
+        last = source.slice(start, i + 1);
+      }
+    }
+  }
+
+  return parseEnvelopeCandidate(last);
+}
+
+function parseEnvelopeFromOutput(stdout, stderr) {
+  const candidates = [stdout, stderr, `${stdout || ''}\n${stderr || ''}`];
+  for (const candidate of candidates) {
+    const direct = parseEnvelopeCandidate(candidate);
+    if (direct) return direct;
+    const extracted = extractLastJsonObject(candidate);
+    if (extracted) return extracted;
+  }
+  return null;
+}
+
+/**
+ * Build a child-process command executor for JSON-mode CLI invocations.
+ * @param {{cliPath?: string, defaultTimeoutMs?: number, env?: object}} [options]
+ * @returns {{executeJsonCommand: (commandArgs: string[], runtime?: {timeoutMs?: number, env?: object}) => {ok: boolean, envelope: object, exitCode: number, stdout: string, stderr: string}}}
+ */
+function createCommandExecutorService(options = {}) {
+  const cliPath =
+    typeof options.cliPath === 'string' && options.cliPath.trim()
+      ? options.cliPath.trim()
+      : path.resolve(__dirname, '..', 'pandora.cjs');
+  const defaultTimeoutMs = Number.isFinite(options.defaultTimeoutMs) ? Math.max(1_000, Math.trunc(options.defaultTimeoutMs)) : 60_000;
+  const baseEnv = options.env && typeof options.env === 'object' ? options.env : process.env;
+
+  function executeJsonCommand(commandArgs, runtime = {}) {
+    const timeoutMs = Number.isFinite(runtime.timeoutMs)
+      ? Math.max(1_000, Math.trunc(runtime.timeoutMs))
+      : defaultTimeoutMs;
+    const env = runtime.env && typeof runtime.env === 'object' ? runtime.env : baseEnv;
+    const argv = ['--output', 'json', ...commandArgs];
+
+    const result = spawnSync(process.execPath, [cliPath, ...argv], {
+      encoding: 'utf8',
+      env,
+      timeout: timeoutMs,
+      killSignal: 'SIGKILL',
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    if (result.error && result.error.code === 'ETIMEDOUT') {
+      return {
+        ok: false,
+        exitCode: 1,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        envelope: {
+          ok: false,
+          error: {
+            code: 'COMMAND_TIMEOUT',
+            message: `Command timed out after ${timeoutMs}ms.`,
+            details: { commandArgs, timeoutMs },
+          },
+        },
+      };
+    }
+
+    if (result.error) {
+      return {
+        ok: false,
+        exitCode: typeof result.status === 'number' ? result.status : 1,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        envelope: {
+          ok: false,
+          error: {
+            code: 'COMMAND_EXEC_FAILED',
+            message: result.error.message || 'CLI command execution failed.',
+            details: {
+              commandArgs,
+              code: result.error.code || null,
+              signal: result.signal || null,
+            },
+          },
+        },
+      };
+    }
+
+    const envelope = parseEnvelopeFromOutput(result.stdout, result.stderr);
+    if (!envelope) {
+      return {
+        ok: false,
+        exitCode: typeof result.status === 'number' ? result.status : 1,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        envelope: {
+          ok: false,
+          error: {
+            code: 'COMMAND_OUTPUT_PARSE_FAILED',
+            message: 'CLI command returned non-JSON output.',
+            details: {
+              commandArgs,
+              stdout: String(result.stdout || '').slice(0, 10_000),
+              stderr: String(result.stderr || '').slice(0, 10_000),
+            },
+          },
+        },
+      };
+    }
+
+    return {
+      ok: envelope && envelope.ok === true,
+      exitCode: typeof result.status === 'number' ? result.status : 1,
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      envelope,
+    };
+  }
+
+  return {
+    executeJsonCommand,
+    coerceErrorMessage,
+  };
+}
+
+module.exports = {
+  createCommandExecutorService,
+};

package/cli/lib/command_router.cjs

@@ -37,6 +37,8 @@ function createCommandRouter(deps = {}) {
     runSuggestCommand,
     runResolveCommand,
     runLpCommand,
+    runMcpCommand,
+    runStreamCommand,
     runScriptCommand,
   } = deps;
 
@@ -48,6 +50,45 @@ function createCommandRouter(deps = {}) {
     throw new Error('createCommandRouter requires emitSuccess.');
   }
 
+  function requireFn(name, fn) {
+    if (typeof fn !== 'function') {
+      throw new Error(`createCommandRouter requires ${name}.`);
+    }
+  }
+
+  requireFn('helpJsonPayload', helpJsonPayload);
+  requireFn('printHelpTable', printHelpTable);
+  requireFn('includesHelpFlag', includesHelpFlag);
+  requireFn('commandHelpPayload', commandHelpPayload);
+  requireFn('runInitEnv', runInitEnv);
+  requireFn('runDoctor', runDoctor);
+  requireFn('runSetup', runSetup);
+  requireFn('runMarketsCommand', runMarketsCommand);
+  requireFn('runScanCommand', runScanCommand);
+  requireFn('runQuoteCommand', runQuoteCommand);
+  requireFn('runTradeCommand', runTradeCommand);
+  requireFn('runPollsCommand', runPollsCommand);
+  requireFn('runEventsCommand', runEventsCommand);
+  requireFn('runPositionsCommand', runPositionsCommand);
+  requireFn('runPortfolioCommand', runPortfolioCommand);
+  requireFn('runWatchCommand', runWatchCommand);
+  requireFn('runHistoryCommand', runHistoryCommand);
+  requireFn('runExportCommand', runExportCommand);
+  requireFn('runArbitrageCommand', runArbitrageCommand);
+  requireFn('runAutopilotCommand', runAutopilotCommand);
+  requireFn('runMirrorCommand', runMirrorCommand);
+  requireFn('runPolymarketCommand', runPolymarketCommand);
+  requireFn('runWebhookCommand', runWebhookCommand);
+  requireFn('runLeaderboardCommand', runLeaderboardCommand);
+  requireFn('runAnalyzeCommand', runAnalyzeCommand);
+  requireFn('runSuggestCommand', runSuggestCommand);
+  requireFn('runResolveCommand', runResolveCommand);
+  requireFn('runLpCommand', runLpCommand);
+  requireFn('runMcpCommand', runMcpCommand);
+  requireFn('runStreamCommand', runStreamCommand);
+  requireFn('runSchemaCommand', deps.runSchemaCommand);
+  requireFn('runScriptCommand', runScriptCommand);
+
   return async function dispatch(command, args, context) {
     if (!command || command === 'help' || command === '--help' || command === '-h') {
       if (context.outputMode === 'json') {
@@ -131,6 +172,16 @@ function createCommandRouter(deps = {}) {
       suggest: async (handlerArgs, handlerContext) => runSuggestCommand(handlerArgs, handlerContext),
       resolve: async (handlerArgs, handlerContext) => runResolveCommand(handlerArgs, handlerContext),
       lp: async (handlerArgs, handlerContext) => runLpCommand(handlerArgs, handlerContext),
+      mcp: async (handlerArgs, handlerContext) => {
+        if (handlerContext.outputMode === 'json') {
+          throw new CliError(
+            'UNSUPPORTED_OUTPUT_MODE',
+            '--output json is not supported for mcp because MCP uses raw stdio transport.',
+          );
+        }
+        await runMcpCommand(handlerArgs, handlerContext);
+      },
+      stream: async (handlerArgs, handlerContext) => runStreamCommand(handlerArgs, handlerContext),
       schema: async (handlerArgs, handlerContext) => deps.runSchemaCommand(handlerArgs, handlerContext),
       launch: async (handlerArgs, handlerContext) => {
         if (handlerContext.outputMode === 'json') {