pandora-cli-skills 1.1.38 → 1.1.39

package/README.md

@@ -49,6 +49,20 @@ pandora --output json trade --dry-run \
 pandora stream prices --indexer-url https://pandoraindexer.up.railway.app/ --interval-ms 1000
 ```
 
+### Sports Quickstart
+
+```bash
+# list upcoming soccer events
+pandora --output json sports events list --competition <id-or-slug> --limit 5
+
+# compute trimmed-median consensus for one event
+pandora --output json sports consensus --event-id <event-id> --trim-percent 20
+
+# build conservative create + resolve plans
+pandora --output json sports create plan --event-id <event-id> --selection home
+pandora --output json sports resolve plan --event-id <event-id> --poll-address <0x...>
+```
+
 ## Fork Mode Notes
 
 - Runtime marker is included in payloads: `data.runtime.mode = "fork" | "live"`.

package/README_FOR_SHARING.md

@@ -51,6 +51,16 @@ Prerequisite: Node.js `>=18`.
    - `npm run dry-run:clone`
    - `node cli/pandora.cjs help`
 
+## Quickstart (Sports)
+- List soccer events:
+  - `pandora --output json sports events list --competition <id-or-slug> --limit 5`
+- Compute sportsbook consensus:
+  - `pandora --output json sports consensus --event-id <event-id> --trim-percent 20`
+- Build creation plan:
+  - `pandora --output json sports create plan --event-id <event-id> --selection home`
+- Build manual resolve recommendation:
+  - `pandora --output json sports resolve plan --event-id <event-id> --poll-address <0x...>`
+
 ## New CLI capabilities
 - Global machine-readable output:
   - `pandora --output json doctor`

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.37
+version: 1.1.39
 ---
 
 # Pandora CLI & Skills
@@ -83,6 +83,7 @@ pandora [--output table|json] doctor [--dotenv-path <path>] [--skip-dotenv] [--c
 pandora [--output table|json] setup [--force] [--dotenv-path <path>] [--example <path>] [--check-usdc-code] [--check-polymarket] [--rpc-timeout-ms <ms>]
 pandora [--output table|json] markets list [--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] [--with-odds]
 pandora [--output table|json] markets get [--id <id> ...] [--stdin]
+pandora [--output table|json] sports books list|events list|events live|odds snapshot|consensus|create plan|create run|sync once|sync run|sync start|sync stop|sync status|resolve plan [flags]
 pandora [--output table|json] polls list [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--chain-id <id>] [--creator <address>] [--status <int>] [--category <int>] [--question-contains <text>] [--where-json <json>]
 pandora [--output table|json] polls get --id <id>
 pandora [--output table|json] events list [--type all|liquidity|oracle-fee|claim] [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-direction asc|desc] [--chain-id <id>] [--wallet <address>] [--market-address <address>] [--poll-address <address>] [--tx-hash <hash>]
@@ -144,6 +145,81 @@ preflight [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url
 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>]
 ```
 
+## Sports command matrix
+| Command | Purpose | Primary flags |
+| --- | --- | --- |
+| `sports books list` | Show sportsbook provider health and active book preference list. | `--provider`, `--book-priority`, `--timeout-ms` |
+| `sports events list` | List normalized soccer events. | `--competition`, `--kickoff-after`, `--kickoff-before`, `--limit` |
+| `sports events live` | List only live/in-play events. | `--competition`, `--limit`, `--provider` |
+| `sports odds snapshot` | Fetch event odds snapshot plus consensus context. | `--event-id`, `--trim-percent`, `--min-tier1-books`, `--min-total-books` |
+| `sports consensus` | Compute trimmed-median consensus from live or offline checks. | `--event-id` or `--checks-json`, `--trim-percent`, `--book-priority` |
+| `sports create plan` | Build conservative creation plan and safety gates. | `--event-id`, `--selection`, `--market-type`, `--creation-window-open-min`, `--creation-window-close-min` |
+| `sports create run` | Dry-run or execute creation path. | `--event-id`, `--dry-run/--execute`, `--liquidity-usdc`, `--chain-id`, `--rpc-url` |
+| `sports sync once|run|start|stop|status` | Evaluate and operate sports sync runtime state. | `--event-id` (required for `once|run|start`), `--risk-profile`, `--state-file`, `--paper/--execute-live` |
+| `sports resolve plan` | Build manual-final resolution recommendation. | `--event-id` or `--checks-json/--checks-file`, `--poll-address`, `--settle-delay-ms`, `--consecutive-checks-required` |
+
+## Sports consensus policy
+- Odds are normalized to implied probability from decimal/American/fractional inputs.
+- Consensus method is `trimmed-median` (v1), with default `--trim-percent 20`.
+- Conservative coverage inputs default to `--min-tier1-books 3` and `--min-total-books 6`.
+- Confidence can degrade when coverage policy is not satisfied.
+- Consensus payload includes:
+  - `method`
+  - `tier1Coverage`
+  - `totalBooks`
+  - `includedBooks`
+  - `excludedBooks`
+  - `outliers`
+  - `consensusYesPct`
+  - `consensusNoPct`
+
+## Sports timing policy
+- Creation planning defaults:
+  - `--creation-window-open-min 1440` (24h before kickoff)
+  - `--creation-window-close-min 90` (90m before kickoff)
+- Core timing module defaults (spec-level fallbacks):
+  - creation open lead `7d`, creation close lead `15m`
+  - assumed event duration `3h`
+  - resolve open delay `30m`, resolve target delay `2h`, resolve close delay `48h`
+- Resolve plan safety defaults:
+  - `--settle-delay-ms 600000` (10m)
+  - `--consecutive-checks-required 2`
+
+## Manual resolve workflow (sports)
+1. Build resolve plan:
+   - `pandora --output json sports resolve plan --event-id <id> --poll-address <0x...>`
+2. Confirm plan safety:
+   - require `safeToResolve=true`
+   - read `recommendedAnswer`, `stableWindowStartAt`, and diagnostics
+3. Execute resolution:
+   - run `recommendedCommand` when present
+   - or run manual command: `pandora resolve --poll-address <0x...> --answer yes|no|invalid --reason "<text>" --execute`
+4. If unsafe:
+   - continue collecting checks (`--checks-json`/`--checks-file`) and rerun until safety gates pass.
+
+## Sports sync risk defaults
+- Conservative (`--risk-profile conservative`):
+  - `maxDataAgeMs=120000`
+  - `minCoverageRatio=0.70`
+  - `maxCoverageDropRatio=0.25`
+  - `maxSpreadJumpBps=150`
+  - `maxConsecutiveFailures=3`
+  - `maxConsecutiveGateFailures=2`
+- Balanced:
+  - `maxDataAgeMs=150000`
+  - `minCoverageRatio=0.60`
+  - `maxCoverageDropRatio=0.30`
+  - `maxSpreadJumpBps=200`
+  - `maxConsecutiveFailures=4`
+  - `maxConsecutiveGateFailures=3`
+- Aggressive:
+  - `maxDataAgeMs=180000`
+  - `minCoverageRatio=0.50`
+  - `maxCoverageDropRatio=0.40`
+  - `maxSpreadJumpBps=250`
+  - `maxConsecutiveFailures=5`
+  - `maxConsecutiveGateFailures=4`
+
 ## Read-only indexer commands
 Indexer URL resolution order:
 1. `--indexer-url`

package/cli/lib/command_router.cjs

@@ -18,6 +18,7 @@ function createCommandRouter(deps = {}) {
     runSetup,
     runMarketsCommand,
     runScanCommand,
+    runSportsCommand,
     runQuoteCommand,
     runTradeCommand,
     runPollsCommand,
@@ -65,6 +66,7 @@ function createCommandRouter(deps = {}) {
   requireFn('runSetup', runSetup);
   requireFn('runMarketsCommand', runMarketsCommand);
   requireFn('runScanCommand', runScanCommand);
+  requireFn('runSportsCommand', runSportsCommand);
   requireFn('runQuoteCommand', runQuoteCommand);
   requireFn('runTradeCommand', runTradeCommand);
   requireFn('runPollsCommand', runPollsCommand);
@@ -153,6 +155,7 @@ function createCommandRouter(deps = {}) {
       },
       markets: async (handlerArgs, handlerContext) => runMarketsCommand(handlerArgs, handlerContext),
       scan: async (handlerArgs, handlerContext) => runScanCommand(handlerArgs, handlerContext),
+      sports: async (handlerArgs, handlerContext) => runSportsCommand(handlerArgs, handlerContext),
       quote: async (handlerArgs, handlerContext) => runQuoteCommand(handlerArgs, handlerContext),
       trade: async (handlerArgs, handlerContext) => runTradeCommand(handlerArgs, handlerContext),
       polls: async (handlerArgs, handlerContext) => runPollsCommand(handlerArgs, handlerContext),

package/cli/lib/error_recovery_service.cjs

@@ -51,6 +51,38 @@ function buildMcpRestartCommand(cliName) {
   return `${cliName} mcp`;
 }
 
+function buildMcpBoundedCommand(cliName, details) {
+  const toolName = cleanToken(details && details.toolName, '');
+  if (toolName.startsWith('sports.sync.')) {
+    return `${cliName} sports sync once --help`;
+  }
+  if (toolName.startsWith('mirror.sync.')) {
+    return `${cliName} mirror sync once --help`;
+  }
+  if (toolName.startsWith('autopilot.')) {
+    return `${cliName} autopilot once --help`;
+  }
+  if (toolName.startsWith('watch')) {
+    return `${cliName} watch --help`;
+  }
+  return `${cliName} help`;
+}
+
+function buildSportsConsensusRetryCommand(cliName, details) {
+  const eventId = cleanToken(details && details.eventId, '<event-id>');
+  return `${cliName} sports consensus --event-id ${eventId}`;
+}
+
+function buildSportsCreatePlanCommand(cliName, details) {
+  const eventId = cleanToken(details && details.eventId, '<event-id>');
+  return `${cliName} sports create plan --event-id ${eventId}`;
+}
+
+function buildSportsResolvePlanRetryCommand(cliName, details) {
+  const eventId = cleanToken(details && details.eventId, '<event-id>');
+  return `${cliName} sports resolve plan --event-id ${eventId}`;
+}
+
 /**
  * Build deterministic Next-Best-Action recovery hints for JSON errors.
  * @param {{cliName?: string}} [options]
@@ -124,7 +156,7 @@ function createErrorRecoveryService(options = {}) {
       case 'MCP_LONG_RUNNING_MODE_BLOCKED':
         return {
           action: 'Switch to a bounded command variant for MCP',
-          command: `${cliName} mirror sync once --help`,
+          command: buildMcpBoundedCommand(cliName, details),
           retryable: true,
         };
       case 'MCP_TOOL_FAILED':
@@ -134,6 +166,46 @@ function createErrorRecoveryService(options = {}) {
           command: `${cliName} --output json schema`,
           retryable: true,
         };
+      case 'SPORTS_PROVIDER_NOT_CONFIGURED':
+      case 'SPORTS_PROVIDER_FETCH_MISSING':
+      case 'SPORTS_LIST_COMPETITIONS_FAILED':
+      case 'SPORTS_LIST_EVENTS_FAILED':
+      case 'SPORTS_GET_EVENT_ODDS_FAILED':
+      case 'SPORTS_GET_EVENT_STATUS_FAILED':
+        return {
+          action: 'Retry sportsbook query with explicit provider settings',
+          command: `${cliName} sports books list --provider auto`,
+          retryable: true,
+        };
+      case 'SPORTS_PROVIDER_TIMEOUT':
+      case 'SPORTS_PROVIDER_REQUEST_FAILED':
+      case 'SPORTS_PROVIDER_HTTP_ERROR':
+      case 'SPORTS_PROVIDER_INVALID_JSON':
+        return {
+          action: 'Retry sportsbook read path with backup provider',
+          command: `${cliName} sports events list --provider backup --limit 10`,
+          retryable: true,
+        };
+      case 'SPORTS_CONSENSUS_FAILED':
+      case 'SPORTS_CONSENSUS_UNAVAILABLE':
+        return {
+          action: 'Re-run consensus for the target event',
+          command: buildSportsConsensusRetryCommand(cliName, details),
+          retryable: true,
+        };
+      case 'SPORTS_CREATE_BLOCKED':
+      case 'SPORTS_CREATE_FAILED':
+        return {
+          action: 'Rebuild creation plan and adjust timing/coverage inputs',
+          command: buildSportsCreatePlanCommand(cliName, details),
+          retryable: true,
+        };
+      case 'SPORTS_RESOLVE_PLAN_UNSAFE':
+        return {
+          action: 'Wait for stable final status and retry resolve plan',
+          command: buildSportsResolvePlanRetryCommand(cliName, details),
+          retryable: true,
+        };
       case 'MISSING_REQUIRED_FLAG':
       case 'MISSING_FLAG_VALUE':
       case 'INVALID_FLAG_VALUE':

package/cli/lib/mcp_tool_registry.cjs

@@ -175,6 +175,54 @@ const TOOL_DEFINITIONS = [
   { name: 'markets.list', command: ['markets', 'list'], description: 'List Pandora markets with filters.' },
   { name: 'markets.get', command: ['markets', 'get'], description: 'Get one or more markets by id.' },
   { name: 'scan', command: ['scan'], description: 'Scan markets with lifecycle filters.' },
+  { name: 'sports.books.list', command: ['sports', 'books', 'list'], description: 'List sportsbook provider health and configured book priorities.' },
+  { name: 'sports.events.list', command: ['sports', 'events', 'list'], description: 'List normalized soccer events from sportsbook providers.' },
+  { name: 'sports.events.live', command: ['sports', 'events', 'live'], description: 'List currently-live soccer events from sportsbook providers.' },
+  { name: 'sports.odds.snapshot', command: ['sports', 'odds', 'snapshot'], description: 'Get normalized event odds snapshot and consensus.' },
+  { name: 'sports.consensus', command: ['sports', 'consensus'], description: 'Compute majority-book trimmed-median consensus for one event.' },
+  { name: 'sports.create.plan', command: ['sports', 'create', 'plan'], description: 'Build conservative market creation plan from sportsbook consensus.' },
+  {
+    name: 'sports.create.run',
+    command: ['sports', 'create', 'run'],
+    description: 'Execute or dry-run sports market creation.',
+    mutating: true,
+    safeFlags: ['--dry-run', '--paper'],
+    executeFlags: ['--execute'],
+  },
+  {
+    name: 'sports.sync.once',
+    command: ['sports', 'sync', 'once'],
+    description: 'Run one sports sync evaluation tick.',
+    mutating: true,
+    safeFlags: ['--paper', '--dry-run'],
+    executeFlags: ['--execute-live', '--execute'],
+  },
+  {
+    name: 'sports.sync.run',
+    command: ['sports', 'sync', 'run'],
+    description: 'Continuous sports sync loop (blocked in MCP v1).',
+    longRunningBlocked: true,
+    mutating: true,
+    safeFlags: ['--paper', '--dry-run'],
+    executeFlags: ['--execute-live', '--execute'],
+  },
+  {
+    name: 'sports.sync.start',
+    command: ['sports', 'sync', 'start'],
+    description: 'Start detached sports sync runtime (blocked in MCP v1).',
+    longRunningBlocked: true,
+    mutating: true,
+    safeFlags: ['--paper', '--dry-run'],
+    executeFlags: ['--execute-live', '--execute'],
+  },
+  {
+    name: 'sports.sync.stop',
+    command: ['sports', 'sync', 'stop'],
+    description: 'Stop sports sync runtime.',
+    mutating: true,
+  },
+  { name: 'sports.sync.status', command: ['sports', 'sync', 'status'], description: 'Inspect sports sync runtime status.' },
+  { name: 'sports.resolve.plan', command: ['sports', 'resolve', 'plan'], description: 'Build manual-final resolution recommendation.' },
   { name: 'quote', command: ['quote'], description: 'Build YES/NO quote estimates.' },
   {
     name: 'trade',
@@ -391,6 +439,7 @@ function createMcpToolRegistry() {
       );
       blocked.code = 'MCP_LONG_RUNNING_MODE_BLOCKED';
       blocked.details = {
+        toolName: definition.name,
         hints: ['Use the non-long-running variant (for example, *.once) or call the CLI directly outside MCP.'],
       };
       throw blocked;