pandora-cli-skills 1.1.61 → 1.1.63

package/SKILL.md

@@ -1,7 +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.61
+version: 1.1.63
 ---
 
 # Pandora CLI & Skills
@@ -40,6 +40,9 @@ npm link
 - `--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`
+- Agent market prompt tools:
+  - `pandora --output json agent market autocomplete --question "<text>" [--market-type amm|parimutuel]`
+  - `pandora --output json agent market validate --question "<text>" --rules "<text>" --target-timestamp <unix-seconds> [--sources <url...>]`
 - Guided setup command: `pandora setup`
 - Phase 1 discovery command: `pandora scan`
 - Phase 1 lifecycle filters: `pandora markets list --active|--resolved|--expiring-soon`
@@ -73,6 +76,10 @@ npm link
   - `--fork-chain-id <id>`
 - JSON errors can include additive recovery hints:
   - `error.recovery = { action, command, retryable }`
+- Agent/MCP market creation policy:
+  - Agent-drafted manual markets should start with `agent market autocomplete` when rules, sources, or timing still need to be generated/refined.
+  - Execute/live MCP calls for `sports create run`, `mirror deploy`, and `mirror go` require a PASS attestation from `agent market validate`.
+  - Dry-run outputs for those flows include the exact validation ticket that must be echoed back via `agentPreflight` on the execute call.
 - Doctor checks:
   - env presence + format validation
   - RPC reachability and chain id match

package/cli/lib/agent_command_service.cjs

@@ -0,0 +1,222 @@
+const {
+  buildAgentMarketAutocompletePayload,
+  buildAgentMarketValidationPayload,
+} = require('./agent_market_prompt_service.cjs');
+
+function requireDep(deps, name) {
+  if (!deps || typeof deps[name] !== 'function') {
+    throw new Error(`createRunAgentCommand requires deps.${name}()`);
+  }
+  return deps[name];
+}
+
+function readFlagValue(args, index, flagName) {
+  const value = args[index + 1];
+  if (typeof value !== 'string' || value.startsWith('--')) {
+    const error = new Error(`${flagName} requires a value.`);
+    error.code = 'MISSING_FLAG_VALUE';
+    throw error;
+  }
+  return value;
+}
+
+function parseAgentMarketAutocompleteFlags(args) {
+  const options = {
+    question: '',
+    marketType: 'amm',
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--question') {
+      options.question = readFlagValue(args, i, '--question');
+      i += 1;
+      continue;
+    }
+    if (token === '--market-type') {
+      options.marketType = readFlagValue(args, i, '--market-type');
+      i += 1;
+      continue;
+    }
+    const error = new Error(`Unknown flag for agent market autocomplete: ${token}`);
+    error.code = 'UNKNOWN_FLAG';
+    throw error;
+  }
+
+  if (!String(options.question || '').trim()) {
+    const error = new Error('agent market autocomplete requires --question <text>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+
+  return options;
+}
+
+function parseAgentMarketValidateFlags(args) {
+  const options = {
+    question: '',
+    rules: '',
+    sources: [],
+    targetTimestamp: 0,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--question') {
+      options.question = readFlagValue(args, i, '--question');
+      i += 1;
+      continue;
+    }
+    if (token === '--rules') {
+      options.rules = readFlagValue(args, i, '--rules');
+      i += 1;
+      continue;
+    }
+    if (token === '--target-timestamp') {
+      const raw = readFlagValue(args, i, '--target-timestamp');
+      const numeric = Number(raw);
+      if (!Number.isFinite(numeric) || numeric <= 0) {
+        const error = new Error('--target-timestamp must be a unix timestamp in seconds.');
+        error.code = 'INVALID_FLAG_VALUE';
+        throw error;
+      }
+      options.targetTimestamp = Math.trunc(numeric);
+      i += 1;
+      continue;
+    }
+    if (token === '--sources') {
+      let consumed = 0;
+      for (let j = i + 1; j < args.length; j += 1) {
+        const value = args[j];
+        if (typeof value !== 'string' || value.startsWith('--')) break;
+        options.sources.push(value);
+        consumed += 1;
+      }
+      if (!consumed) {
+        const error = new Error('--sources requires at least one URL value.');
+        error.code = 'MISSING_FLAG_VALUE';
+        throw error;
+      }
+      i += consumed;
+      continue;
+    }
+    if (token === '--source') {
+      options.sources.push(readFlagValue(args, i, '--source'));
+      i += 1;
+      continue;
+    }
+    const error = new Error(`Unknown flag for agent market validate: ${token}`);
+    error.code = 'UNKNOWN_FLAG';
+    throw error;
+  }
+
+  if (!String(options.question || '').trim()) {
+    const error = new Error('agent market validate requires --question <text>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+  if (!String(options.rules || '').trim()) {
+    const error = new Error('agent market validate requires --rules <text>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+  if (!options.targetTimestamp) {
+    const error = new Error('agent market validate requires --target-timestamp <unix-seconds>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+
+  return options;
+}
+
+function renderAgentPromptTable(payload) {
+  const lines = [
+    `${payload.promptKind} (${payload.promptVersion})`,
+  ];
+  if (payload.ticket) {
+    lines.push(`ticket: ${payload.ticket}`);
+  }
+  lines.push('');
+  lines.push('Prompt:');
+  lines.push(payload.prompt);
+  lines.push('');
+  lines.push('Workflow:');
+  for (const note of payload.workflow && Array.isArray(payload.workflow.notes) ? payload.workflow.notes : []) {
+    lines.push(`- ${note}`);
+  }
+  if (payload.requiredAttestation) {
+    lines.push('');
+    lines.push('Required attestation:');
+    lines.push(JSON.stringify(payload.requiredAttestation, null, 2));
+  }
+  // eslint-disable-next-line no-console
+  console.log(lines.join('\n'));
+}
+
+function createRunAgentCommand(deps) {
+  const CliError = deps.CliError;
+  const includesHelpFlag = requireDep(deps, 'includesHelpFlag');
+  const emitSuccess = requireDep(deps, 'emitSuccess');
+  const commandHelpPayload = requireDep(deps, 'commandHelpPayload');
+
+  if (typeof CliError !== 'function') {
+    throw new Error('createRunAgentCommand requires deps.CliError.');
+  }
+
+  async function runAgentCommand(args, context) {
+    const rest = Array.isArray(args) ? args : [];
+    if (!rest.length || includesHelpFlag(rest)) {
+      const usage = [
+        'pandora [--output table|json] agent market autocomplete --question <text> [--market-type amm|parimutuel]',
+        'pandora [--output table|json] agent market validate --question <text> --rules <text> --target-timestamp <unix-seconds> [--sources <url...>]',
+      ];
+      if (context.outputMode === 'json') {
+        emitSuccess(context.outputMode, 'agent.help', commandHelpPayload(usage));
+      } else {
+        renderAgentPromptTable({
+          promptKind: 'agent.help',
+          promptVersion: 'n/a',
+          ticket: null,
+          prompt: usage.join('\n'),
+          workflow: {
+            notes: [
+              'Use agent market autocomplete when the agent must draft market rules or timing.',
+              'Use agent market validate before any agent-exposed market execute path.',
+            ],
+          },
+        });
+      }
+      return;
+    }
+
+    const namespace = rest[0];
+    const action = rest[1];
+    const actionArgs = rest.slice(2);
+
+    if (namespace !== 'market') {
+      throw new CliError('INVALID_ARGS', 'agent requires subcommand: market autocomplete|validate');
+    }
+
+    if (action === 'autocomplete') {
+      const payload = buildAgentMarketAutocompletePayload(parseAgentMarketAutocompleteFlags(actionArgs));
+      emitSuccess(context.outputMode, 'agent.market.autocomplete', payload, renderAgentPromptTable);
+      return;
+    }
+
+    if (action === 'validate') {
+      const payload = buildAgentMarketValidationPayload(parseAgentMarketValidateFlags(actionArgs));
+      emitSuccess(context.outputMode, 'agent.market.validate', payload, renderAgentPromptTable);
+      return;
+    }
+
+    throw new CliError('INVALID_ARGS', 'agent market requires subcommand: autocomplete|validate');
+  }
+
+  return {
+    runAgentCommand,
+  };
+}
+
+module.exports = {
+  createRunAgentCommand,
+};

package/cli/lib/agent_contract_registry.cjs

@@ -43,6 +43,21 @@ function flexibleArraySchema(itemSchema, description, extras = {}) {
   };
 }
 
+function buildAgentPreflightSchema(description) {
+  return {
+    type: 'object',
+    properties: {
+      validationTicket: stringSchema('Ticket returned by agent.market.validate for the exact market payload.'),
+      validationDecision: enumSchema(['PASS', 'FAIL'], 'Validation verdict from the agent AI run.'),
+      validationSummary: stringSchema('Short summary of the validation result.'),
+      autocompleteTicket: stringSchema('Optional ticket from agent.market.autocomplete when the agent drafted the market.'),
+    },
+    required: ['validationTicket', 'validationDecision', 'validationSummary'],
+    additionalProperties: false,
+    ...(description ? { description } : {}),
+  };
+}
+
 function buildIntentSchema() {
   return {
     type: 'object',
@@ -191,6 +206,58 @@ const commandContracts = [
     dataSchema: MCP_HELP_SCHEMA_REF,
     helpDataSchema: null,
   }),
+  commandContract({
+    name: 'agent',
+    summary: 'Agent prompt workflow namespace for market drafting and validation.',
+    usage: 'pandora [--output table|json] agent market autocomplete|validate ...',
+    emits: ['agent.help'],
+    dataSchema: COMMAND_HELP_SCHEMA_REF,
+    helpDataSchema: null,
+  }),
+  commandContract({
+    name: 'agent.market.autocomplete',
+    summary: 'Emit AI prompt text for drafting market rules, sources, and timing.',
+    usage:
+      'pandora [--output table|json] agent market autocomplete --question <text> [--market-type amm|parimutuel]',
+    emits: ['agent.market.autocomplete', 'agent.help'],
+    dataSchema: '#/definitions/AgentMarketPromptPayload',
+    mcpExposed: true,
+    mcp: {
+      command: ['agent', 'market', 'autocomplete'],
+      description: 'Emit AI autocomplete prompt for market drafting.',
+      inputSchema: buildInputSchema({
+        flagProperties: {
+          question: stringSchema('Seed market question to refine into rules, sources, and timing.'),
+          'market-type': enumSchema(['amm', 'parimutuel'], 'Target market type.'),
+        },
+        requiredFlags: ['question'],
+      }),
+      preferred: true,
+    },
+  }),
+  commandContract({
+    name: 'agent.market.validate',
+    summary: 'Emit AI validation prompt text plus the exact attestation ticket required for execute mode.',
+    usage:
+      'pandora [--output table|json] agent market validate --question <text> --rules <text> --target-timestamp <unix-seconds> [--sources <url...>]',
+    emits: ['agent.market.validate', 'agent.help'],
+    dataSchema: '#/definitions/AgentMarketPromptPayload',
+    mcpExposed: true,
+    mcp: {
+      command: ['agent', 'market', 'validate'],
+      description: 'Emit AI validation prompt and required attestation ticket for market execution.',
+      inputSchema: buildInputSchema({
+        flagProperties: {
+          question: stringSchema('Exact market question to validate.'),
+          rules: stringSchema('Exact market rules to validate.'),
+          'target-timestamp': integerSchema('Resolution timestamp in unix seconds.', { minimum: 1 }),
+          sources: flexibleArraySchema(stringSchema(), 'Source URL list.'),
+        },
+        requiredFlags: ['question', 'rules', 'target-timestamp'],
+      }),
+      preferred: true,
+    },
+  }),
   commandContract({
     name: 'launch',
     summary: 'Launch a one-off market via the interactive/non-JSON deployment flow.',
@@ -198,6 +265,15 @@ const commandContracts = [
       'pandora launch --dry-run|--execute [options] --question "<text>" --rules "<resolution rules>" --sources "<url1>" "<url2>" [more] --target-timestamp <unix-seconds>',
     emits: ['launch.help'],
     outputModes: ['table'],
+    agentWorkflow: {
+      requiredTools: ['agent.market.validate'],
+      recommendedTools: ['agent.market.autocomplete'],
+      executeRequiresValidation: true,
+      notes: [
+        'When an agent drafts or executes a manual launch market, run autocomplete first if rules or timing still need refinement.',
+        'Run agent.market.validate on the final payload before any execute path.',
+      ],
+    },
   }),
   commandContract({
     name: 'clone-bet',
@@ -206,6 +282,14 @@ const commandContracts = [
       'pandora clone-bet --dry-run|--execute [options] --question "<text>" --rules "<resolution rules>" --sources "<url1>" "<url2>" [more] --target-timestamp <unix-seconds>',
     emits: ['clone-bet.help'],
     outputModes: ['table'],
+    agentWorkflow: {
+      requiredTools: ['agent.market.validate'],
+      recommendedTools: ['agent.market.autocomplete'],
+      executeRequiresValidation: true,
+      notes: [
+        'When an agent drafts or executes a clone-bet market, validate the final payload before execute mode.',
+      ],
+    },
   }),
   commandContract({
     name: 'markets',
@@ -1202,6 +1286,15 @@ const commandContracts = [
     emits: ['sports.create.run', 'sports.help'],
     dataSchema: '#/definitions/SportsCreatePayload',
     mcpExposed: true,
+    agentWorkflow: {
+      requiredTools: ['agent.market.validate'],
+      recommendedTools: ['agent.market.autocomplete'],
+      executeRequiresValidation: true,
+      notes: [
+        'Use agent.market.autocomplete when the agent must rewrite the question, rules, or timing before market creation.',
+        'Run agent.market.validate on the exact final sports market payload before any execute path.',
+      ],
+    },
     mcp: {
       command: ['sports', 'create', 'run'],
       description: 'Execute or dry-run sports market creation.',
@@ -1217,6 +1310,7 @@ const commandContracts = [
           'chain-id': commonFlags.chainId,
           'rpc-url': commonFlags.rpcUrl,
           'private-key': commonFlags.privateKey,
+          agentPreflight: buildAgentPreflightSchema('Agent validation attestation for execute mode.'),
         },
         requiredFlags: ['event-id'],
       }),
@@ -1224,6 +1318,7 @@ const commandContracts = [
       mutating: true,
       safeFlags: ['--dry-run', '--paper'],
       executeFlags: ['--execute'],
+      controlInputNames: ['agentPreflight'],
     },
   }),
   commandContract({
@@ -1828,10 +1923,20 @@ const commandContracts = [
     name: 'mirror.deploy',
     summary: 'Deploy a mirror market from selector or plan in dry-run or execute mode.',
     usage:
-      'pandora [--output table|json] mirror deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--sources <url...>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--min-close-lead-seconds <n>]',
+      'pandora [--output table|json] mirror deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--sources <url...>] [--validation-ticket <ticket>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--min-close-lead-seconds <n>]',
     emits: ['mirror.deploy', 'mirror.deploy.help'],
     dataSchema: '#/definitions/MirrorDeployPayload',
     mcpExposed: true,
+    agentWorkflow: {
+      requiredTools: ['agent.market.validate'],
+      recommendedTools: ['agent.market.autocomplete'],
+      executeRequiresValidation: true,
+      notes: [
+        'Mirror deploy dry-run returns the exact Pandora deployment payload and required validation ticket.',
+        'Mirror deploy never auto-copies Polymarket URLs into sources; pass independent public resolution URLs with --sources.',
+        'Run agent.market.validate on that final payload before rerunning mirror.deploy with execute mode, then pass --validation-ticket locally or agentPreflight in MCP.',
+      ],
+    },
     mcp: {
       command: ['mirror', 'deploy'],
       description: 'Dry-run or execute mirror deployment.',
@@ -1857,18 +1962,21 @@ const commandContracts = [
           'distribution-yes': numberSchema('Initial YES distribution parts.', { minimum: 0 }),
           'distribution-no': numberSchema('Initial NO distribution parts.', { minimum: 0 }),
           sources: flexibleArraySchema(stringSchema(), 'Source URL list.'),
+          'validation-ticket': stringSchema('Ticket returned by agent.market.validate for the exact final payload (CLI execute mode).'),
           'manifest-file': stringSchema('Mirror manifest path.'),
           'polymarket-host': stringSchema('Polymarket host override.'),
           'polymarket-gamma-url': stringSchema('Polymarket Gamma API base URL.'),
           'polymarket-gamma-mock-url': stringSchema('Polymarket Gamma mock URL.'),
           'polymarket-mock-url': stringSchema('Polymarket mock CLOB URL.'),
           'min-close-lead-seconds': integerSchema('Minimum close lead time in seconds.', { minimum: 0 }),
+          agentPreflight: buildAgentPreflightSchema('Agent validation attestation for execute mode.'),
         },
       }),
       preferred: true,
       mutating: true,
       safeFlags: ['--dry-run'],
       executeFlags: ['--execute'],
+      controlInputNames: ['agentPreflight'],
     },
   }),
   commandContract({
@@ -1983,10 +2091,20 @@ const commandContracts = [
     name: 'mirror.go',
     summary: 'Run mirror deploy, verify, and optional sync workflow.',
     usage:
-      'pandora [--output table|json] mirror go --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--max-open-exposure-usdc <amount>] [--max-trades-per-day <n>] [--polymarket-rpc-url <url>] [--manifest-file <path>] [--dotenv-path <path>] [--rpc-url <url>] [--private-key <hex>]',
+      'pandora [--output table|json] mirror go --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--max-open-exposure-usdc <amount>] [--max-trades-per-day <n>] [--polymarket-rpc-url <url>] [--sources <url...>] [--validation-ticket <ticket>] [--manifest-file <path>] [--dotenv-path <path>] [--rpc-url <url>] [--private-key <hex>]',
     emits: ['mirror.go', 'mirror.go.help'],
     dataSchema: '#/definitions/MirrorDeployPayload',
     mcpExposed: true,
+    agentWorkflow: {
+      requiredTools: ['agent.market.validate'],
+      recommendedTools: ['agent.market.autocomplete'],
+      executeRequiresValidation: true,
+      notes: [
+        'Mirror go inherits the exact market payload from its deploy stage; use the returned validation ticket from paper/dry-run output.',
+        'When mirror go will execute a fresh deploy, provide independent public --sources and a matching validation ticket.',
+        'Run agent.market.validate on that exact payload before rerunning mirror.go with execute or execute-live.',
+      ],
+    },
     mcp: {
       command: ['mirror', 'go'],
       description: 'Plan/deploy/verify/go orchestration.',
@@ -2010,16 +2128,20 @@ const commandContracts = [
           'max-open-exposure-usdc': numberSchema('Maximum open exposure in USDC.', { minimum: 0 }),
           'max-trades-per-day': integerSchema('Maximum daily trade count.', { minimum: 0 }),
           'polymarket-rpc-url': stringSchema('Polygon RPC URL for Polymarket preflight.'),
+          sources: flexibleArraySchema(stringSchema(), 'Independent public source URL list.'),
+          'validation-ticket': stringSchema('Ticket returned by agent.market.validate for the exact final payload (CLI execute mode).'),
           'manifest-file': stringSchema('Mirror manifest path.'),
           'dotenv-path': stringSchema('Env file path.'),
           'rpc-url': commonFlags.rpcUrl,
           'private-key': commonFlags.privateKey,
+          agentPreflight: buildAgentPreflightSchema('Agent validation attestation for execute or execute-live mode.'),
         },
       }),
       preferred: true,
       mutating: true,
-      safeFlags: ['--paper'],
-      executeFlags: ['--execute-live'],
+      safeFlags: ['--paper', '--dry-run'],
+      executeFlags: ['--execute-live', '--execute'],
+      controlInputNames: ['agentPreflight'],
     },
   }),
   commandContract({
@@ -2518,6 +2640,11 @@ function buildCommandDescriptors() {
       preferred: contract.mcp && contract.mcp.preferred === false ? false : Boolean(canonicalTool ? contract.name === canonicalTool : contract.aliasOf ? false : contract.mcpExposed),
       mcpMutating: Boolean(contract.mcp && contract.mcp.mutating),
       mcpLongRunningBlocked: Boolean(contract.mcp && contract.mcp.longRunningBlocked),
+      controlInputNames:
+        contract.mcp && Array.isArray(contract.mcp.controlInputNames)
+          ? [...contract.mcp.controlInputNames]
+          : [],
+      agentWorkflow: contract.agentWorkflow || null,
     };
   }
   return descriptors;
@@ -2539,6 +2666,8 @@ function buildMcpToolDefinitions() {
       aliasOf: contract.aliasOf || null,
       canonicalTool: contract.canonicalTool || contract.aliasOf || contract.name,
       preferred: contract.mcp.preferred !== false,
+      controlInputNames: Array.isArray(contract.mcp.controlInputNames) ? [...contract.mcp.controlInputNames] : undefined,
+      agentWorkflow: contract.agentWorkflow || null,
     }));
 }