pandora-cli-skills 1.1.33 → 1.1.34

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.34
 ---
 
 # Pandora CLI & Skills

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,123 @@
+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 parseEnvelopeFromOutput(stdout, stderr) {
+  const candidates = [stdout, stderr, `${stdout || ''}\n${stderr || ''}`]
+    .map((value) => String(value || '').trim())
+    .filter(Boolean);
+
+  for (const candidate of candidates) {
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      const start = candidate.indexOf('{');
+      const end = candidate.lastIndexOf('}');
+      if (start >= 0 && end > start) {
+        const slice = candidate.slice(start, end + 1);
+        try {
+          return JSON.parse(slice);
+        } catch {
+          // continue
+        }
+      }
+    }
+  }
+
+  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 },
+          },
+        },
+      };
+    }
+
+    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;
 
@@ -131,6 +133,8 @@ 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) => 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') {

package/cli/lib/error_recovery_service.cjs

@@ -0,0 +1,108 @@
+function cleanToken(value, fallback) {
+  const normalized = String(value === undefined || value === null ? '' : value).trim();
+  return normalized || fallback;
+}
+
+function toAddressOrPlaceholder(value, placeholder = '<address>') {
+  const normalized = cleanToken(value, '');
+  if (/^0x[a-fA-F0-9]{40}$/.test(normalized)) {
+    return normalized;
+  }
+  return placeholder;
+}
+
+function toSideOrPlaceholder(value) {
+  const normalized = cleanToken(value, '').toLowerCase();
+  return normalized === 'yes' || normalized === 'no' ? normalized : 'yes';
+}
+
+function toPositiveNumberOrPlaceholder(value, placeholder = '<amount>') {
+  const numeric = Number(value);
+  if (Number.isFinite(numeric) && numeric > 0) {
+    return String(numeric);
+  }
+  return placeholder;
+}
+
+function buildTradeRetryCommand(cliName, details) {
+  const marketAddress = toAddressOrPlaceholder(details && details.marketAddress);
+  const side = toSideOrPlaceholder(details && details.side);
+  const amountUsdc = toPositiveNumberOrPlaceholder(details && details.amountUsdc);
+  return `${cliName} trade --dry-run --market-address ${marketAddress} --side ${side} --amount-usdc ${amountUsdc}`;
+}
+
+function buildPolymarketApproveCommand(cliName) {
+  return `${cliName} polymarket approve --dry-run`;
+}
+
+function buildPolymarketPreflightCommand(cliName) {
+  return `${cliName} polymarket preflight`;
+}
+
+/**
+ * Build deterministic Next-Best-Action recovery hints for JSON errors.
+ * @param {{cliName?: string}} [options]
+ * @returns {{getRecoveryForError: (errorLike: any) => (null|{action: string, command: string, retryable: boolean})}}
+ */
+function createErrorRecoveryService(options = {}) {
+  const cliName = cleanToken(options.cliName, 'pandora');
+
+  function getRecoveryForError(errorLike) {
+    const code = cleanToken(errorLike && errorLike.code, '');
+    const details = errorLike && typeof errorLike.details === 'object' && errorLike.details ? errorLike.details : {};
+
+    switch (code) {
+      case 'TRADE_RISK_GUARD':
+        return {
+          action: 'Adjust risk guard inputs',
+          command: buildTradeRetryCommand(cliName, details),
+          retryable: true,
+        };
+      case 'ALLOWANCE_READ_FAILED':
+      case 'APPROVE_SIMULATION_FAILED':
+      case 'APPROVE_EXECUTION_FAILED':
+      case 'TRADE_EXECUTION_FAILED':
+        return {
+          action: 'Re-run trade planning before execute',
+          command: buildTradeRetryCommand(cliName, details),
+          retryable: true,
+        };
+      case 'POLYMARKET_APPROVE_FAILED':
+      case 'POLYMARKET_PROXY_APPROVAL_REQUIRES_MANUAL_EXECUTION':
+        return {
+          action: 'Run Polymarket approve flow first',
+          command: buildPolymarketApproveCommand(cliName),
+          retryable: true,
+        };
+      case 'POLYMARKET_TRADE_FAILED':
+      case 'POLYMARKET_PREFLIGHT_FAILED':
+      case 'POLYMARKET_CHECK_FAILED':
+      case 'POLYMARKET_MARKET_RESOLUTION_FAILED':
+        return {
+          action: 'Run Polymarket preflight diagnostics',
+          command: buildPolymarketPreflightCommand(cliName),
+          retryable: true,
+        };
+      case 'MISSING_REQUIRED_FLAG':
+      case 'MISSING_FLAG_VALUE':
+      case 'INVALID_FLAG_VALUE':
+      case 'UNKNOWN_FLAG':
+      case 'INVALID_ARGS':
+        return {
+          action: 'Inspect command help and retry',
+          command: `${cliName} help`,
+          retryable: true,
+        };
+      default:
+        return null;
+    }
+  }
+
+  return {
+    getRecoveryForError,
+  };
+}
+
+module.exports = {
+  createErrorRecoveryService,
+};

package/cli/lib/fork_runtime_service.cjs

@@ -0,0 +1,79 @@
+function toServiceError(code, message, details = undefined) {
+  const error = new Error(message);
+  error.code = code;
+  if (details !== undefined) {
+    error.details = details;
+  }
+  return error;
+}
+
+function toIntegerOrNull(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) return null;
+  return parsed;
+}
+
+/**
+ * Resolve attach-only fork runtime settings.
+ * Precedence in fork mode: --fork-rpc-url > FORK_RPC_URL (when --fork).
+ * @param {object} [options]
+ * @param {{env?: object, isSecureHttpUrlOrLocal?: (url: string) => boolean, defaultChainId?: number}} [runtime]
+ * @returns {{mode: 'live'|'fork', rpcUrl: (string|null), chainId: (number|null)}}
+ */
+function resolveForkRuntime(options = {}, runtime = {}) {
+  const env = runtime.env && typeof runtime.env === 'object' ? runtime.env : process.env;
+  const isSecureHttpUrlOrLocal =
+    typeof runtime.isSecureHttpUrlOrLocal === 'function' ? runtime.isSecureHttpUrlOrLocal : () => true;
+  const defaultChainId = Number.isInteger(runtime.defaultChainId) ? runtime.defaultChainId : 1;
+
+  const forkExplicit = options.fork === true;
+  const forkRpcUrlFromFlag = String(options.forkRpcUrl || '').trim();
+  const forkRequested = forkExplicit || Boolean(forkRpcUrlFromFlag);
+
+  if (!forkRequested) {
+    const chainId = toIntegerOrNull(options.chainId) ?? toIntegerOrNull(env.CHAIN_ID) ?? defaultChainId;
+    return {
+      mode: 'live',
+      rpcUrl: null,
+      chainId,
+    };
+  }
+
+  const envForkRpcUrl = String(env.FORK_RPC_URL || '').trim();
+  let rpcUrl = forkRpcUrlFromFlag || (forkExplicit ? envForkRpcUrl : '');
+
+  if (!rpcUrl) {
+    throw toServiceError(
+      'MISSING_REQUIRED_FLAG',
+      '--fork requires FORK_RPC_URL env var or explicit --fork-rpc-url <url>.',
+      {
+        hints: ['Set FORK_RPC_URL=http://127.0.0.1:8545 and rerun with --fork.'],
+      },
+    );
+  }
+
+  if (!isSecureHttpUrlOrLocal(rpcUrl)) {
+    throw toServiceError(
+      'INVALID_FLAG_VALUE',
+      '--fork-rpc-url must use https:// (or http://localhost/127.0.0.1 for local testing).',
+      { rpcUrl },
+    );
+  }
+
+  const chainId =
+    toIntegerOrNull(options.forkChainId)
+    ?? toIntegerOrNull(options.chainId)
+    ?? toIntegerOrNull(env.CHAIN_ID)
+    ?? defaultChainId;
+
+  return {
+    mode: 'fork',
+    rpcUrl,
+    chainId,
+  };
+}
+
+module.exports = {
+  resolveForkRuntime,
+};

package/cli/lib/mcp_server_service.cjs

@@ -0,0 +1,147 @@
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  McpError,
+  ErrorCode,
+} = require('@modelcontextprotocol/sdk/types.js');
+
+const { createMcpToolRegistry } = require('./mcp_tool_registry.cjs');
+const { createCommandExecutorService } = require('./command_executor_service.cjs');
+
+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 asCliErrorEnvelope(error) {
+  const code = error && error.code ? String(error.code) : 'MCP_TOOL_FAILED';
+  const envelope = {
+    ok: false,
+    error: {
+      code,
+      message: coerceErrorMessage(error),
+    },
+  };
+  if (error && error.details !== undefined) {
+    envelope.error.details = error.details;
+  }
+  return envelope;
+}
+
+function asToolResult(envelope) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(envelope, null, 2),
+      },
+    ],
+    structuredContent: envelope,
+    isError: envelope && envelope.ok === false,
+  };
+}
+
+/**
+ * Create the MCP stdio server runner for `pandora mcp`.
+ * @param {{packageVersion?: string, cliPath?: string}} [options]
+ * @returns {{runMcpServer: (args: string[], context: {outputMode: 'table'|'json'}) => Promise<void>}}
+ */
+function createRunMcpServer(options = {}) {
+  const packageVersion =
+    typeof options.packageVersion === 'string' && options.packageVersion.trim()
+      ? options.packageVersion.trim()
+      : '0.0.0';
+  const registry = createMcpToolRegistry();
+  const executor = createCommandExecutorService({
+    cliPath: options.cliPath,
+    defaultTimeoutMs: 60_000,
+  });
+
+  async function runMcpServer(args, context) {
+    const mcpArgs = Array.isArray(args) ? args : [];
+    if (mcpArgs.includes('--help') || mcpArgs.includes('-h')) {
+      if (context && context.outputMode === 'json') {
+        const usageEnvelope = {
+          ok: true,
+          command: 'mcp.help',
+          data: {
+            usage: 'pandora mcp',
+            notes: [
+              'Runs an MCP stdio server.',
+              'Do not pass --output json to this command in normal MCP operation.',
+            ],
+          },
+        };
+        process.stdout.write(`${JSON.stringify(usageEnvelope, null, 2)}\n`);
+      } else {
+        // eslint-disable-next-line no-console
+        console.log('Usage: pandora mcp');
+        // eslint-disable-next-line no-console
+        console.log('Runs Pandora as an MCP stdio server.');
+      }
+      return;
+    }
+
+    if (context && context.outputMode === 'json') {
+      throw new Error('pandora mcp must be run without --output json because MCP uses raw stdio transport.');
+    }
+
+    const server = new Server(
+      {
+        name: 'pandora-cli-skills',
+        version: packageVersion,
+      },
+      {
+        capabilities: {
+          tools: { listChanged: false },
+        },
+      },
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: registry.listTools(),
+    }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const params = request && request.params ? request.params : {};
+        const toolName = String(params.name || '').trim();
+        if (!toolName) {
+          throw new McpError(ErrorCode.InvalidParams, 'tools/call requires params.name.');
+        }
+
+        const toolArgs = params.arguments && typeof params.arguments === 'object' ? params.arguments : {};
+        const invocation = registry.prepareInvocation(toolName, toolArgs);
+        const execution = executor.executeJsonCommand(invocation.argv);
+        return asToolResult(execution.envelope);
+      } catch (err) {
+        if (err instanceof McpError) throw err;
+        return asToolResult(asCliErrorEnvelope(err));
+      }
+    });
+
+    const transport = new StdioServerTransport(process.stdin, process.stdout);
+    await server.connect(transport);
+
+    await new Promise((resolve, reject) => {
+      transport.onclose = () => resolve();
+      transport.onerror = (error) => reject(error);
+      server.onclose = () => resolve();
+    });
+  }
+
+  return {
+    runMcpServer,
+  };
+}
+
+module.exports = {
+  createRunMcpServer,
+};