Multi-Model Execution

Status: shipped (November 21, 2025) Owner: Oracle CLI

This document describes the architecture for Oracle’s multi-model mode. A single CLI invocation can fan out the same prompt/files to multiple models (GPT-5 variants, Gemini, Claude, etc.), run them in parallel, and capture outputs side-by-side.

#Goals

1. Consistent UX – users type the prompt once and get a compact summary showing how each model responded (status, cost, elapsed time, answer snippet).
2. Safe concurrency – API requests run in parallel but everything else (file attachment, prompt rendering, logging, session writes) stays deterministic.
3. Disk clarity – session artifacts stay human-readable and forward-compatible.
4. Filterable history – oracle session --status and oracle session <id> can filter by model, show partial completion, and recover from interrupted runs.
5. Extensible – adding another model alias requires no schema migrations.

#CLI Surface

Execution flow: CLI normalizes the --models list, builds the prompt/files once, then dispatches per-model runs with isolated logs. Standard output prints each model section sequentially ([gpt-5.1-pro] …, then [gemini-3-pro] …).

When some models fail, Oracle prints a structured multi-model result. If --write-output is set, saved outputs are listed before failures so agents and humans can recover the usable answers first.

For advisory panels, preflight keys/routes first and allow partial success when one strong answer is useful:

oracle --preflight --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
oracle \
  --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro \
  --allow-partial \
  --write-output /tmp/panel.md \
  -p "Compare these options and recommend one."

Default mode remains strict: without --allow-partial / --partial ok, any failed model exits 1 after printing the partial summary.

#Session Storage

Sessions live under ~/.oracle/sessions/<sessionId>:

sessionId/
├── meta.json             # shared session metadata + request
├── output.log            # combined view (headers + concatenated model logs)
└── models/
    ├── gpt-5.1-pro.json    # per-model metadata
    ├── gpt-5.1-pro.log     # per-model log
    ├── gemini-3-pro.json
    ├── gemini-3-pro.log
    └── …

The CLI renders per-model logs without interleaving tokens. Aggregate cost/tokens are derived from the per-model usage files.

With --write-output /tmp/name.md, Oracle writes successful answers to per-model files such as /tmp/name.gpt-5.1.md and records /tmp/name.oracle.json. The manifest includes each model's status, output path, run log path, usage, elapsed time when available, and error category/message for failed models. Terminal summaries print saved outputs first, then run logs, then failures so agents can recover partial results without scraping noisy error blocks.

Common provider failures are normalized before display. Auth, expired-key, quota, rate-limit, and unavailable-model errors include the provider env var name, the provider message, and a short recovery hint; secret values are never printed.

#Implementation Notes

• Storage helpers live in src/sessionManager.ts and src/sessionStore.ts; callers never touch paths directly.
• Multi-model orchestration runs through src/cli/sessionRunner.ts and src/oracle/multiModelRunner.ts, which schedule per-model runs and emit model-specific logs.
• Background mode still applies per model (e.g., GPT-5 Pro defaults to background; Claude is forced foreground).
• MCP server and TUI honor the multi-model layout: oracle session --status shows compact per-model icons; oracle session <id> --model foo renders a single model log.

#Testing

• Unit tests cover session storage + log rendering.
• Manual checklist: see docs/manual-tests.md (multi-model section) for cross-model smoke steps.