@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
564 lines • 52.9 kB
text/typescript
import type { Capability } from "./capability-types";
export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
{
command: ["message", "sessions"],
summary: "Discover already-loaded Codex sessions locally or on an explicitly enrolled peer.",
routes: [], flags: [{ name: "--json", value: "boolean", summary: "Emit a versioned session directory." }, { name: "--host", value: "string", summary: "Exact enrolled peer alias or machine UUID; requires a live foreground owner." }],
mutates: false, json: "envelope",
bannerLines: ["ocx message <sub> Codex queued messages, explicit SSH peers and foreground ownership"],
details: ["Linux/macOS only. Local discovery uses the effective CODEX_HOME Unix socket; --host uses the live foreground owner's authenticated loopback route. Starts no daemon and returns no partial directory."],
},
{
command: ["message", "send"],
summary: "Submit one correlated peer message to an exact loaded Codex destination.",
routes: [], mutates: true, json: "envelope",
flags: [
{ name: "--thread", value: "string", summary: "Exact loaded UUID; choose this or --name." },
{ name: "--name", value: "string", summary: "Unique exact loaded name; choose this or --thread." },
{ name: "--stdin", value: "boolean", required: true, summary: "Read at most 16 KiB of UTF-8 message text." },
{ name: "--kind", value: "string", summary: "request (default), response or notification." },
{ name: "--in-reply-to", value: "string", summary: "Request message UUID; required only for a response." },
{ name: "--json", value: "boolean", summary: "Emit a receipt with not_sent, queued or unknown status." },
{ name: "--host", value: "string", summary: "Exact enrolled peer alias or machine UUID; omit for the unchanged local path." },
],
details: ["Requires daemon support for experimental thread/queue/add. Sender context comes from CODEX_THREAD_ID, not an authentication claim.",
"queued means submitted, not processed. unknown must not be replayed; no automatic retry, daemon start or thread resume.",
"Exit 0: queued; 1: not sent; 3: unknown; 64: invalid usage. No Claude transport, native lifecycle mutation or skill installation."],
},
{
command: ["message", "mcp"], usage: "ocx message mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read] [--allow-resume --resume-socket <absolute-existing-unix-socket> --resume-permissions <profile-id>]",
summary: "Serve MCP tools for stored Codex metadata, queued text, opt-in stored-turn reply reads, bounded waits and guarded existing-server resume preflight.",
routes: [], mutates: true, json: "none",
flags: [{ name: "--codex", value: "string", required: true, summary: "Explicit local Codex CLI executable." },
{ name: "--codex-home", value: "string", required: true, summary: "Explicit existing Codex home; no creation or login." },
{ name: "--allow-reply-read", value: "boolean", summary: "Explicitly expose stored final-turn text through codex_read_reply and codex_wait_reply; disabled by default." },
{ name: "--allow-resume", value: "boolean", summary: "Expose existing-thread resume preflight; requires --resume-socket and --resume-permissions. Execution is blocked pending native atomic resume support." },
{ name: "--resume-socket", value: "string", summary: "Existing trusted local Unix App Server socket; requires --allow-resume, --resume-permissions and matching Codex home." },
{ name: "--resume-permissions", value: "string", summary: "Host-selected native profile for resume preflight; does not bypass the atomicity refusal or preserve saved permissions automatically." }],
details: ["macOS/Linux only. Default queue/read tools need no proxy/control socket; resume uses the explicitly configured existing Unix socket. Starts bounded stdio helpers only when a tool is called; existing sessions/send behavior stays unchanged.",
"Stored threads are not verified live sessions. queued is not processing; unknown is never replayed. --allow-reply-read exposes bounded same-turn final text, not exclusive reply ownership or goal completion. No daemon start, steer, automatic replies or registration. Resume preflight is separate opt-in through a same-home existing Unix server; managed requirements and unavailable profiles refuse. The checked native API cannot enforce unloaded-only resume atomically, so execution is blocked with resume_atomicity_unsupported; no thread/resume is sent."],
},
{
command: ["advisor"],
summary: "Inspect and configure the advisor sidecar (expert consultation for routed workers).",
routes: [
{ method: "GET", path: "/api/advisor/settings" },
{ method: "GET", path: "/api/advisor/activity" },
{ method: "PUT", path: "/api/advisor/settings" },
],
flags: [
{ name: "--json", value: "boolean", summary: "Emit advisor settings as JSON." },
{ name: "--context-mode", value: "string", summary: "With set: context (default) or question-only; question-only pauses automatic consultations." },
],
mutates: true,
json: "payload",
details: [
"`status` (the default) reads the resolved settings; `on`/`off` toggle the sidecar; `consent` records or revokes context-sharing consent; `set` updates model, effort, policy, context mode, task limit, or timeout.",
"`on` does not grant consent. Without current consent it refuses and prints the disclosure. `on --ack-context-sharing` records consent v1 and enables. `consent --revoke` removes consent: consultations not yet dispatched are blocked, but it cannot cancel a dispatched consultation or retract task context already sent.",
"The advisor model may be any routable model string: a bare native model, an explicit `provider/model`, or an account-qualified native model.",
"`policy: preflight` makes OpenCodex attempt one automatic consultation per task with a stable conversation identity once the task shows orientation evidence (an assistant tool call or a tool result after the latest user message). Without a stable identity, each eligible request may trigger another consultation. `policy: manual` consults only when the worker calls the synthetic `advisor` tool. Neither path sends task context without current context-sharing consent.",
"`policy: adaptive` adds evidence-based failed-repair consultation after the same validation fails, a file edit completes, and validation fails again. Automatic calls require a stable conversation identity. `set --max-consultations <1-3>` caps adaptive task attempts, including manual calls, in a durable 24-hour budget. No semantic stuck detection is claimed.",
"`set --context-mode question-only` sends only a fixed instruction and a required, self-contained worker question (up to 2,000 retained characters plus a truncation notice). No task history, tools, worker identity or repair evidence is attached. Automatic preflight and adaptive repair calls are paused; manual calls, consent and existing limits still apply. `set --context-mode context` restores the default context-sharing behavior and selected policy.",
"`activity` reads up to 100 recent consultation metadata records (trigger, status, models, requested and mapped effort, duration, reported tokens); no task or advice content is retained. Records are process-local and expire after 24 hours. Missing mapped effort means unreported, not successful application.",
],
},
{
command: ["message", "enable"], summary: "Explicitly enable private remote messaging state, without starting a listener.", routes: [],
flags: [{ name: "--port", value: "number", summary: "Unprivileged IPv4-loopback port; defaults to 39176 on first enable." },
{ name: "--json", value: "boolean", summary: "Emit configuration without credentials." }], mutates: true, json: "envelope",
},
{ command: ["message", "disable"], summary: "Disable remote admission and retire the foreground owner generation.", routes: [],
flags: [{ name: "--json", value: "boolean", summary: "Emit safe configuration." }], mutates: true, json: "envelope" },
{ command: ["message", "status"], summary: "Read enabled, running and leased/initiated route states without activation.", routes: [],
flags: [{ name: "--json", value: "boolean", summary: "Emit safe configuration and owner observations." }], mutates: false, json: "envelope" },
{ command: ["message", "serve"], summary: "Own a foreground listener and optional duplex SSH peer routes; no automatic reconnect.", routes: [],
flags: [{ name: "--host", value: "string", summary: "Exact initiating peer; repeat for at most four distinct peers." },
{ name: "--json", value: "boolean", summary: "Emit the startup observation without credentials." }], mutates: true, json: "envelope" },
{ command: ["message", "hosts", "probe"], summary: "Offer an SSH host fingerprint without enrollment or persistent changes.", routes: [],
flags: [{ name: "--ssh", value: "string", required: true, summary: "OpenSSH destination/alias." },
{ name: "--json", value: "boolean", summary: "Emit the offered fingerprint." }], mutates: false, json: "envelope" },
{ command: ["message", "hosts", "add"], usage: "ocx message hosts add <alias> --ssh <destination> --fingerprint <SHA256> [--json]",
summary: "Enroll outbound delivery and correlated return replies after SSH fingerprint confirmation.", routes: [],
flags: [{ name: "--ssh", value: "string", required: true, summary: "OpenSSH destination/alias." },
{ name: "--fingerprint", value: "string", required: true, summary: "Explicitly confirmed offered SSH host-key fingerprint." },
{ name: "--json", value: "boolean", summary: "Emit enrollment metadata, never credentials." }], mutates: true, json: "envelope" },
{ command: ["message", "hosts", "allow-inbound"], usage: "ocx message hosts allow-inbound <alias-or-machine-uuid> [--json]",
summary: "Explicitly allow this enrolled peer to send any message kind to local loaded sessions.", routes: [],
flags: [{ name: "--json", value: "boolean", summary: "Emit the local inbound grant, without credentials." }], mutates: true, json: "envelope" },
{ command: ["message", "hosts", "deny-inbound"], usage: "ocx message hosts deny-inbound <alias-or-machine-uuid> [--json]",
summary: "Restrict this peer to correlated replies on locally opened reply routes.", routes: [],
flags: [{ name: "--json", value: "boolean", summary: "Emit the narrowed local inbound grant." }], mutates: true, json: "envelope" },
{ command: ["message", "hosts", "list"], summary: "List exact peer identities without credentials or listener activation.", routes: [],
flags: [{ name: "--json", value: "boolean", summary: "Emit safe peer metadata." }], mutates: false, json: "envelope" },
{ command: ["message", "hosts", "remove"], usage: "ocx message hosts remove <alias-or-machine-uuid> [--transaction <uuid>] [--json]",
summary: "Revoke local admission first and report any unconfirmed remote cleanup explicitly.", routes: [],
flags: [{ name: "--transaction", value: "string", summary: "Remove only this exact enrollment; refuse a replacement transaction." },
{ name: "--json", value: "boolean", summary: "Emit local and remote revocation outcomes." }], mutates: true, json: "envelope" },
{ command: ["message", "hosts", "abandon"], usage: "ocx message hosts abandon --transaction <uuid> [--json]",
summary: "Abandon an exact pending local enrollment; remote cleanup remains unconfirmed (exit 3).", routes: [],
flags: [{ name: "--transaction", value: "string", required: true, summary: "Exact pending UUID from hosts list or status; never an alias." },
{ name: "--json", value: "boolean", summary: "Emit local abandonment and explicit remote-cleanup guidance." }], mutates: true, json: "envelope" },
{
command: ["agent", "status"],
usage: "ocx agent status [--json]",
summary: "Read agent mode, delegation, effort caps, roster, fallback and sidecars.",
routes: [{"method": "GET", "path": "/api/v2"}, {"method": "GET", "path": "/api/injection-model"}, {"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/subagent-models"}, {"method": "GET", "path": "/api/subagent-model-fallback"}, {"method": "GET", "path": "/api/sidecar-settings"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "envelope",
details: [],
},
{
command: ["agent", "effort"],
usage: "ocx agent effort status [--json]",
summary: "Read or set main and subagent effort caps.",
routes: [{"method": "GET", "path": "/api/effort-caps"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: ["set requires at least one cap; a null clears it."],
},
{
command: ["agent", "effort", "set"],
usage: "ocx agent effort set [--main <level|->] [--subagent <level|->] [--json]",
summary: "Read or set main and subagent effort caps.",
routes: [{"method": "PUT", "path": "/api/effort-caps"}],
flags: [{"name": "--main", "value": "string", "summary": "Main effort cap; - clears."}, {"name": "--subagent", "value": "string", "summary": "Subagent effort cap; - clears."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["set requires at least one cap; a null clears it."],
},
{
command: ["agent", "subagents"],
usage: "ocx agent subagents status [--json]",
summary: "Read, replace or clear the ordered featured subagent roster.",
routes: [{"method": "GET", "path": "/api/subagent-models"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: ["At most five models; clear sends an empty roster. agent roster is an alias."],
},
{
command: ["agent", "subagents", "set"],
usage: "ocx agent subagents set <model,model...> [--json]",
summary: "Read, replace or clear the ordered featured subagent roster.",
routes: [{"method": "PUT", "path": "/api/subagent-models"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["At most five models; clear sends an empty roster. agent roster is an alias."],
},
{
command: ["agent", "subagents", "clear"],
usage: "ocx agent subagents clear [--json]",
summary: "Clear the saved subagents models.",
routes: [{"method": "PUT", "path": "/api/subagent-models"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["At most five models; clear sends an empty roster. agent roster is an alias."],
},
{
command: ["agent", "fallback"],
usage: "ocx agent fallback status [--json]",
summary: "Read, replace or clear fallback models and polling interval.",
routes: [{"method": "GET", "path": "/api/subagent-model-fallback"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: ["set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms."],
},
{
command: ["agent", "fallback", "set"],
usage: "ocx agent fallback set [model,model...] [--poll-ms <5000-600000>] [--json]",
summary: "Read, replace or clear fallback models and polling interval.",
routes: [{"method": "PUT", "path": "/api/subagent-model-fallback"}],
flags: [{"name": "--poll-ms", "value": "number", "summary": "Polling interval, 5000-600000 milliseconds."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms."],
},
{
command: ["agent", "fallback", "clear"],
usage: "ocx agent fallback clear [--poll-ms <5000-600000>] [--json]",
summary: "Clear the saved fallback models.",
routes: [{"method": "PUT", "path": "/api/subagent-model-fallback"}],
flags: [{"name": "--poll-ms", "value": "number", "summary": "Polling interval, 5000-600000 milliseconds."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms."],
},
{
command: ["agent", "sidecar"],
usage: "ocx agent sidecar status [--json]",
summary: "Read configured sidecars and candidate models.",
routes: [{"method": "GET", "path": "/api/sidecar-settings"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: [],
},
{
command: ["agent","sidecar","web"],
usage: "ocx agent sidecar web (--list | [--model <id|->] [--backend <openai|anthropic|xai|gemini|exa|->] [--reasoning <level>] [--enabled <on|off>] [--stream-routed-output <on|off>]) [--json]",
summary: "List web candidates or change the web sidecar.",
routes: [{"method":"GET","path":"/api/sidecar-settings"},{"method":"PUT","path":"/api/sidecar-settings"}],
flags: [{"name":"--list","value":"boolean","summary":"Read candidates only; cannot combine with setting flags."},{"name":"--model","value":"string","summary":"Model selector; - clears."},{"name":"--backend","value":"string","summary":"Backend selector; - clears."},{"name":"--reasoning","value":"string","summary":"Reasoning level."},{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--stream-routed-output","value":"string","summary":"Stream routed web-search model output; web only."}],
mutates: true,
json: "payload",
details: ["Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct.","Web reasoning remains supported even though the mutation reply does not echo it. max-descriptions and timeout belong only to vision. New-option replies project the saved web settings and actual native apply report."],
},
{
command: ["agent","sidecar","vision"],
usage: "ocx agent sidecar vision (--list | [--model <id|->] [--backend <openai|anthropic|routed|->] [--reasoning <level>] [--max-descriptions <n>] [--enabled <on|off>] [--timeout-ms <1-2147483647>]) [--json]",
summary: "List vision candidates or change the vision sidecar.",
routes: [{"method":"GET","path":"/api/sidecar-settings"},{"method":"PUT","path":"/api/sidecar-settings"}],
flags: [{"name":"--list","value":"boolean","summary":"Read candidates only; cannot combine with setting flags."},{"name":"--model","value":"string","summary":"Model selector; - clears."},{"name":"--backend","value":"string","summary":"Backend selector; - clears."},{"name":"--reasoning","value":"string","summary":"Reasoning level."},{"name":"--max-descriptions","value":"number","summary":"Positive description limit."},{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--timeout-ms","value":"number","summary":"Vision request timeout, integer1–2147483647 milliseconds."}],
mutates: true,
json: "payload",
details: ["Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct.","Stream-routed-output belongs only to web. Timeout changes preserve siblings; native apply and saved state are distinct."],
},
{
command: ["fallback"],
usage: "ocx fallback [status] [--json]",
summary: "Show which model and provider fallbacks are allowed, per-device local fallback, and the last fallback taken or refused.",
routes: [{"method": "GET", "path": "/api/fallback"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit the ocx.fallback/1 state."}],
mutates: false,
json: "payload",
details: ["Reads the live proxy. On a Remote Link Child it reads the Home's state over the link (aliases omitted). The last event is in memory and resets on restart."],
},
{
command: ["fallback", "off"],
usage: "ocx fallback off [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
summary: "Refuse model or provider fallback globally or for one provider, route or device.",
routes: [{"method": "PUT", "path": "/api/fallback"}],
flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to the provider a request started on."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector such as combo/<id> or policy/<id>."}, {"name": "--device", "value": "string", "summary": "Scope to a Remote Link id or alias, or a Hub data key id; device off always refuses."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
mutates: true,
json: "payload",
details: ["A refused hop answers fallback_refused with the triggering failure's status. Rotation among accounts or keys of one provider pool is not a fallback and stays on."],
},
{
command: ["fallback", "on"],
usage: "ocx fallback on [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
summary: "Allow model or provider fallback at one scope, overriding a broader off.",
routes: [{"method": "PUT", "path": "/api/fallback"}],
flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to a provider."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector."}, {"name": "--device", "value": "string", "summary": "Scope to a device."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
mutates: true,
json: "payload",
details: ["Route beats provider beats global. A device setting can only refuse: on for a device records the value but never reopens a hop another scope refuses."],
},
{
command: ["fallback", "clear"],
usage: "ocx fallback clear [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
summary: "Remove a fallback override so the scope inherits again.",
routes: [{"method": "PUT", "path": "/api/fallback"}],
flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to a provider."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector."}, {"name": "--device", "value": "string", "summary": "Scope to a device."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
mutates: true,
json: "payload",
details: ["Clearing every override restores today's behavior: every fallback allowed."],
},
{
command: ["fallback", "local"],
usage: "ocx fallback local <on|off> --device <id|alias> [--json]",
summary: "Record whether a device may use its own providers while the Home is unreachable.",
routes: [{"method": "PUT", "path": "/api/fallback"}],
flags: [{"name": "--device", "value": "string", "summary": "Remote Link id or alias, or Hub data key id."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
mutates: true,
json: "payload",
details: ["Run on the Home. A permission GOAT reads; OpenCodex itself keeps answering home_unreachable on the device and never serves it from local providers."],
},
{
command: ["effort"],
usage: "ocx effort [status|low|medium|high|xhigh|max|ultra|->] [--json]",
summary: "Read effort settings or set the main cap with a shorthand level.",
routes: [{"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/injection-model"}, {"method": "PUT", "path": "/api/effort-caps"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "envelope",
details: ["Uses the live proxy when available, otherwise local config. Once live is selected, errors never fall back to local writes; set reads back live status and can report partial application.", "The shorthand ocx effort <low|medium|high|xhigh|max|ultra|-> changes only the main cap; unset aliases clear."],
},
{
command: ["effort", "set"],
usage: "ocx effort set [--main <level|->] [--subagent <level|->] [--injection <level|->] [--json]",
summary: "Set one or more effort fields.",
routes: [{"method": "PUT", "path": "/api/effort-caps"}, {"method": "PUT", "path": "/api/injection-model"}, {"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/injection-model"}],
flags: [{"name": "--main", "value": "string", "summary": "Main cap; - clears."}, {"name": "--subagent", "value": "string", "summary": "Subagent cap; - clears."}, {"name": "--injection", "value": "string", "summary": "Delegation effort; - clears; also accepts none/minimal."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "envelope",
details: ["Local configuration is used when no live proxy is found; runtime failures are not silent offline success."],
},
{
command: ["effort", "clear"],
usage: "ocx effort clear [--json]",
summary: "Clear both caps while retaining delegation effort.",
routes: [{"method": "PUT", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/injection-model"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "envelope",
details: ["Local configuration is used when no live proxy is found; runtime failures are not silent offline success."],
},
{
command: ["effort", "model"],
usage: "ocx effort model <provider/model|model> [--json]",
summary: "Inspect a model effort ladder and wire mappings from local configuration.",
routes: [],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "envelope",
details: ["Local configuration/catalog derivation; routes is empty because no management API is called."],
},
{
command: ["v2","status"],
usage: "ocx v2 [status] [--live] [--json]",
summary: "Report local multi-agent mode and Codex feature settings.",
routes: [{"method":"GET","path":"/api/v2"}],
flags: [{"name":"--live","value":"boolean","summary":"Use the selected runtime; otherwise preserve the local native/config operation."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: false,
json: "envelope",
details: ["Local and live targets never fall back into each other. Parse failures occur before native effects; JSON is one safe state/change/sync result, not collected log text.","Local mode/keep-native and changed on/off preserve their existing sync calls even without a discovered port; threads/hints and unchanged toggles do not gain sync. Unknown or failed sync evidence is nonzero with landed state visible.","Live writes use actual post-write state and full catalog outcomes; a502 can mean partial native changes. Read back before retrying; no rollback is implied."],
},
{
command: ["v2","on"],
usage: "ocx v2 on [--live] [--json]",
summary: "Enable the local Codex multi_agent_v2 feature.",
routes: [{"method":"PUT","path":"/api/v2"}],
flags: [{"name":"--live","value":"boolean","summary":"Use the selected runtime; otherwise preserve the local native/config operation."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["Local and live targets never fall back into each other. Parse failures occur before native effects; JSON is one safe state/change/sync result, not collected log text.","Local mode/keep-native and changed on/off preserve their existing sync calls even without a discovered port; threads/hints and unchanged toggles do not gain sync. Unknown or failed sync evidence is nonzero with landed state visible.","Live writes use actual post-write state and full catalog outcomes; a502 can mean partial native changes. Read back before retrying; no rollback is implied."],
},
{
command: ["v2","off"],
usage: "ocx v2 off [--live] [--json]",
summary: "Disable the local Codex multi_agent_v2 feature.",
routes: [{"method":"PUT","path":"/api/v2"}],
flags: [{"name":"--live","value":"boolean","summary":"Use the selected runtime; otherwise preserve the local native/config operation."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["Local and live targets never fall back into each other. Parse failures occur before native effects; JSON is one safe state/change/sync result, not collected log text.","Local mode/keep-native and changed on/off preserve their existing sync calls even without a discovered port; threads/hints and unchanged toggles do not gain sync. Unknown or failed sync evidence is nonzero with landed state visible.","Live writes use actual post-write state and full catalog outcomes; a502 can mean partial native changes. Read back before retrying; no rollback is implied."],
},
{
command: ["v2","mode"],
usage: "ocx v2 mode <v1|default|v2|v2-plaintext> [--live] [--json] [--acknowledge-surface-advisory] [--acknowledge-plaintext-agent-messages]",
summary: "Set local model-catalog multi-agent mode.",
routes: [{"method":"PUT","path":"/api/v2"}],
flags: [{"name":"--live","value":"boolean","summary":"Use the selected runtime; otherwise preserve the local native/config operation."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."},{"name":"--acknowledge-surface-advisory","value":"boolean","summary":"Explicit live mode only; never implicitly acknowledged."},{"name":"--acknowledge-plaintext-agent-messages","value":"boolean","summary":"Required when entering v2-plaintext; task text may remain in history, provider requests and debug state."}],
mutates: true,
json: "envelope",
details: ["Local and live targets never fall back into each other. Parse failures occur before native effects; JSON is one safe state/change/sync result, not collected log text.","Local mode/keep-native and changed on/off preserve their existing sync calls even without a discovered port; threads/hints and unchanged toggles do not gain sync. Unknown or failed sync evidence is nonzero with landed state visible.","Live writes use actual post-write state and full catalog outcomes; a502 can mean partial native changes. Read back before retrying; no rollback is implied."],
},
{
command: ["v2","keep-native-v1"],
usage: "ocx v2 keep-native-v1 <on|off> [--live] [--json]",
summary: "Keep native ChatGPT on v1 while routed models use v2.",
routes: [{"method":"PUT","path":"/api/v2"}],
flags: [{"name":"--live","value":"boolean","summary":"Use the selected runtime; otherwise preserve the local native/config operation."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["Local and live targets never fall back into each other. Parse failures occur before native effects; JSON is one safe state/change/sync result, not collected log text.","Local mode/keep-native and changed on/off preserve their existing sync calls even without a discovered port; threads/hints and unchanged toggles do not gain sync. Unknown or failed sync evidence is nonzero with landed state visible.","Live writes use actual post-write state and full catalog outcomes; a502 can mean partial native changes. Read back before retrying; no rollback is implied."],
},
{
command: ["v2","threads"],
usage: "ocx v2 threads <n> [--live] [--json]",
summary: "Set the local active-mode thread limit (integer at least 1).",
routes: [{"method":"PUT","path":"/api/v2"}],
flags: [{"name":"--live","value":"boolean","summary":"Use the selected runtime; otherwise preserve the local native/config operation."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["Local and live targets never fall back into each other. Parse failures occur before native effects; JSON is one safe state/change/sync result, not collected log text.","Local mode/keep-native and changed on/off preserve their existing sync calls even without a discovered port; threads/hints and unchanged toggles do not gain sync. Unknown or failed sync evidence is nonzero with landed state visible.","Live writes use actual post-write state and full catalog outcomes; a502 can mean partial native changes. Read back before retrying; no rollback is implied."],
},
{
command: ["v2","mode-hint"],
usage: "ocx v2 mode-hint <text|--clear> [--live] [--json]; ocx v2 mode-hint [--live] [--json] -- <literal-text>",
summary: "Set nonblank local delegation hint text or restore effort-derived policy.",
routes: [{"method":"PUT","path":"/api/v2"}],
flags: [{"name":"--clear","value":"boolean","summary":"Unset the hint."},{"name":"--live","value":"boolean","summary":"Use the selected runtime; otherwise preserve the local native/config operation."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["Local and live targets never fall back into each other. Parse failures occur before native effects; JSON is one safe state/change/sync result, not collected log text.","Local mode/keep-native and changed on/off preserve their existing sync calls even without a discovered port; threads/hints and unchanged toggles do not gain sync. Unknown or failed sync evidence is nonzero with landed state visible.","Live writes use actual post-write state and full catalog outcomes; a502 can mean partial native changes. Read back before retrying; no rollback is implied.","Use -- before one literal hint that equals a reserved control such as --live, --json or --clear. Text after the terminator is never interpreted as a target/output flag."],
},
{
command: ["combo", "list"],
usage: "ocx combo list [--json]",
summary: "List saved combos.",
routes: [{"method": "GET", "path": "/api/combos"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: [],
},
{
command: ["combo", "show"],
usage: "ocx combo show <id> [--json]",
summary: "Read one saved combo from the collection.",
routes: [{"method": "GET", "path": "/api/combos"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: [],
},
{
command: ["combo","set"],
usage: "ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--cooldown-reprobe <on|off>] [--cooldown-reprobe-interval <ms>] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->] [--description <text|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--decision-quota-signals <on|off|->] [--decision-quota-tiers <JSON|->] [--session-pin <duration|->] [--session-pin-effort <pinned|per-turn>] [--rename-from <id>] [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>] [--jev-effort-mode <decide|client>] [--json]",
summary: "Create, update or rename a combo.",
routes: [{"method":"GET","path":"/api/combos"},{"method":"PUT","path":"/api/combos"}],
flags: [{"name":"--allow-metered-targets","value":"string","summary":"on grants operator consent to metered targets only on a loopback-only proxy; off clears it."},{"name":"--targets","value":"string","summary":"Ordered provider/model[:weight] list; required for creation."},{"name":"--strategy","value":"string","summary":"Routing strategy."},{"name":"--sticky","value":"string","summary":"Round-robin limit 1-100; - resets."},{"name":"--cooldown-reprobe","value":"string","summary":"Opt into one recovery pass when all eligible targets cool; off by default."},{"name":"--cooldown-reprobe-interval","value":"string","summary":"Minimum interval between recovery passes in ms (1000..86400000); default 300000."},{"name":"--effort","value":"string","summary":"Default effort; - clears."},{"name":"--effort-mode","value":"string","summary":"fallback or force; - resets to fallback."},{"name":"--alias","value":"string","summary":"Alias; - clears."},{"name":"--display-name","value":"string","summary":"Label; - clears."},{"name":"--description","value":"string","summary":"Catalog row description; - clears."},{"name":"--decision-provider","value":"string","summary":"JEV provider; - clears."},{"name":"--decision-model","value":"string","summary":"JEV route; - clears; exclusive with provider."},{"name":"--decision-timeout","value":"string","summary":"JEV deadline 1000-120000 ms; - clears."},{"name":"--decision-quota-signals","value":"string","summary":"JEV advisory quota on/off; - clears."},{"name":"--decision-quota-tiers","value":"string","summary":"Partial JSON thresholds; - clears."},{"name":"--session-pin","value":"string","summary":"JEV session pin idle window 1m-24h (90s, 20m, 1h); - clears."},{"name":"--session-pin-effort","value":"string","summary":"pinned reuses the pinned effort; per-turn asks JEV for the pinned target's effort each turn."},{"name":"--rename-from","value":"string","summary":"Existing combo ID to rename."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--native-alias","value":"string","summary":"Bare legacy flag means on; explicit on/off preserves presence, including false."},{"name":"--targets-file","value":"string","summary":"Bounded ordered target JSON array, exclusive with --targets; preserves effort/profile/last-resort metadata."},{"name":"--image-input","value":"string","summary":"auto or disabled; explicit auto clears the previous disabled choice."},{"name":"--reasoning-effort-mode","value":"string","summary":"strict or adaptive, distinct from --effort-mode fallback/force."},{"name":"--jev-effort-mode","value":"string","summary":"JEV wire-effort owner: decide (default) applies the decision effort; client keeps its target and leaves effort to combo policy."}],
mutates: true,
json: "payload",
details: ["create and update are aliases of set. Existing fields are read before writing; --targets replaces targets. Without --strategy an existing combo keeps its stored strategy and JEV policy; a new combo defaults to failover.","force overrides valid client effort and may increase cost and latency.","Only the implemented target grammar is supported; full GUI target metadata and routing-profile writes are separate tasks.","New file/flag conflicts refuse before transport. Partial edits preserve target metadata; explicit false/default values override server carry. Turning a native alias off may also require clearing its incompatible alias.","Read/merge/write uses one target and remains an upsert without revision CAS. Saved-but-incomplete catalog outcomes return nonzero with their receipt."],
},
{
command: ["combo", "remove"],
usage: "ocx combo remove <id> --yes [--json]",
summary: "Remove a saved combo after explicit confirmation.",
routes: [{"method": "DELETE", "path": "/api/combos"}],
flags: [{"name": "--yes", "value": "boolean", "summary": "Confirm deletion.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["delete is an alias; the ID is encoded in the id query parameter."],
},
{
command: ["route", "policy", "list"],
usage: "ocx route policy list [--json]",
summary: "List saved routing profiles and revisions.",
routes: [{"method": "GET", "path": "/api/routing-profiles"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: [],
},
{
command: ["route", "policy", "show"],
usage: "ocx route policy show <id> [--json]",
summary: "Read one saved routing profile.",
routes: [{"method": "GET", "path": "/api/routing-profiles"}],
flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: false,
json: "payload",
details: [],
},
{
command: ["route", "policy", "dry-run"],
usage: "ocx route policy dry-run <id> [--model-context <tokens>] [--tools] [--image] [--structured-output] [--json]",
summary: "Evaluate a saved profile against explicit requirements without changing it.",
routes: [{"method": "POST", "path": "/api/routing-profiles/dry-run"}],
flags: [{"name": "--model-context", "value": "number", "summary": "Positive context window requirement."}, {"name": "--tools", "value": "boolean", "summary": "Require tools."}, {"name": "--image", "value": "boolean", "summary": "Require image input."}, {"name": "--structured-output", "value": "boolean", "summary": "Require structured output."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["evaluate and dry-run do not save the profile, but their POST can activate Lab and start automation already enabled by local policy. No profile create, update or delete is exposed."],
},
{
command: ["route", "policy", "evaluate"],
usage: "ocx route policy evaluate <id> [--model-context <tokens>] [--tools] [--image] [--structured-output] [--json]",
summary: "Evaluate a saved profile against explicit requirements without changing it.",
routes: [{"method": "POST", "path": "/api/routing-profiles/dry-run"}],
flags: [{"name": "--model-context", "value": "number", "summary": "Positive context window requirement."}, {"name": "--tools", "value": "boolean", "summary": "Require tools."}, {"name": "--image", "value": "boolean", "summary": "Require image input."}, {"name": "--structured-output", "value": "boolean", "summary": "Require structured output."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
mutates: true,
json: "payload",
details: ["evaluate and dry-run do not save the profile, but their POST can activate Lab and start automation already enabled by local policy. No profile create, update or delete is exposed."],
},
{
command: ["route","policy","create"],
usage: "ocx route policy create <id> --file <FILE|-> [--json]",
summary: "Create a routing profile from an editable-only document.",
routes: [{"method":"PUT","path":"/api/routing-profiles"}],
flags: [{"name":"--file","value":"string","summary":"Bounded editable profile JSON; omit show DTO id/model/revision fields.","required":true},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: true,
json: "envelope",
details: ["The server validates provider/alias/routing relationships and may activate Lab plus automation already enabled on the target. No implicit decision/inference probe follows the save.","An existing ID refuses rather than becoming an update.","Unknown/readonly/nested unsupported file fields refuse; no raw validator issues or file contents are echoed."],
},
{
command: ["route","policy","update"],
usage: "ocx route policy update <id> --file <FILE|-> --expected-revision <revision> [--json]",
summary: "Update a routing profile from an editable-only document.",
routes: [{"method":"PUT","path":"/api/routing-profiles"}],
flags: [{"name":"--file","value":"string","summary":"Bounded editable profile JSON; omit show DTO id/model/revision fields.","required":true},{"name":"--expected-revision","value":"string","summary":"Exact nonblank revision observed by the caller; never automatically refreshed.","required":true},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: true,
json: "envelope",
details: ["The server validates provider/alias/routing relationships and may activate Lab plus automation already enabled on the target. No implicit decision/inference probe follows the save.","Stale revision is exit5 with no overwrite/retry; missing profile is exit4.","Unknown/readonly/nested unsupported file fields refuse; no raw validator issues or file contents are echoed."],
},
{
command: ["route","policy","remove"],
usage: "ocx route policy remove <id> --yes [--json]",
summary: "Remove one exact routing profile ID.",
routes: [{"method":"DELETE","path":"/api/routing-profiles"}],
flags: [{"name":"--yes","value":"boolean","summary":"Explicitly confirm removal.","required":true},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: true,
json: "envelope",
details: ["Uses the internal stored ID, not a public model alias. DELETE has no revision guard. Saved/catalog outcomes remain distinct; no alternate-target retry."],
},
{
command: ["combo","stats"],
usage: "ocx combo stats <id> [--range <7d|30d|all>] [--json]",
summary: "Read JEV decision and token coverage for an exact combo ID.",
routes: [{"method":"GET","path":"/api/usage"}],
flags: [{"name":"--range","value":"string","summary":"7d,30d or all; default30d."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: false,
json: "envelope",
details: ["Uses jev=1,comboId and range. Preserves actual counts, nullable averages, measurement coverage and incomplete/truncated history.","No monetary cost or comparative savings baseline exists in this DTO. This is not a decision probe and makes no model inference request."],
},
{
command: ["agent","memory-models","show"],
usage: "ocx agent memory-models show [--json]",
summary: "Read the memory model override block.",
routes: [{"method":"GET","path":"/api/settings"}],
flags: [{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: false,
json: "envelope",
details: ["An omitted phase keeps its existing/default route; this does not disable extraction, consolidation or the memory pipeline. File{} means no configured overrides, while clear sends null.","Set replaces the full block, preserving canonical schema normalization only. No synthetic inference verifies the save. Writes report the actual normalized block and catalogRefreshPending, which is not a full catalog receipt."],
},
{
command: ["agent","memory-models","set"],
usage: "ocx agent memory-models set (--file <FILE|-> | [--extract-model <model> [--extract-effort <effort>]] [--consolidation-model <model> [--consolidation-effort <effort>]]) [--json]",
summary: "Replace the memory model override block.",
routes: [{"method":"PUT","path":"/api/settings"}],
flags: [{"name":"--file","value":"string","summary":"Bounded strict block JSON or explicit stdin; exclusive with all scalar fields."},{"name":"--extract-model","value":"string","summary":"Extraction override model."},{"name":"--extract-effort","value":"string","summary":"Requires an extraction model."},{"name":"--consolidation-model","value":"string","summary":"Consolidation override model."},{"name":"--consolidation-effort","value":"string","summary":"Requires a consolidation model."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["An omitted phase keeps its existing/default route; this does not disable extraction, consolidation or the memory pipeline. File{} means no configured overrides, while clear sends null.","Set replaces the full block, preserving canonical schema normalization only. No synthetic inference verifies the save. Writes report the actual normalized block and catalogRefreshPending, which is not a full catalog receipt."],
},
{
command: ["agent","memory-models","clear"],
usage: "ocx agent memory-models clear [--json]",
summary: "Clear the memory model override block.",
routes: [{"method":"PUT","path":"/api/settings"}],
flags: [{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["An omitted phase keeps its existing/default route; this does not disable extraction, consolidation or the memory pipeline. File{} means no configured overrides, while clear sends null.","Set replaces the full block, preserving canonical schema normalization only. No synthetic inference verifies the save. Writes report the actual normalized block and catalogRefreshPending, which is not a full catalog receipt."],
},
{
command: ["agent","compaction-routing","show"],
usage: "ocx agent compaction-routing show [--json]",
summary: "Read the compaction routing override block.",
routes: [{"method":"GET","path":"/api/settings"}],
flags: [{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: false,
json: "envelope",
details: ["Clear restores ordinary compaction routing; it does not disable compaction. Omitted triggers/sources retain server defaults.","Set replaces the full block, preserving canonical schema normalization only. No synthetic inference verifies the save. Writes report the actual normalized block and catalogRefreshPending, which is not a full catalog receipt."],
},
{
command: ["agent","compaction-routing","set"],
usage: "ocx agent compaction-routing set (--file <FILE|-> | --model <model> [--effort <effort>] [--triggers <manual,auto>] [--sources <selector,...>]) [--json]",
summary: "Replace the compaction routing override block.",
routes: [{"method":"PUT","path":"/api/settings"}],
flags: [{"name":"--file","value":"string","summary":"Bounded strict block JSON or explicit stdin; exclusive with all scalar fields."},{"name":"--model","value":"string","summary":"Required routing override model in scalar mode."},{"name":"--effort","value":"string","summary":"Optional canonical pinned effort."},{"name":"--triggers","value":"string","summary":"Unique nonempty manual/auto values; no lossy filtering."},{"name":"--sources","value":"string","summary":"Unique exact selectors or provider/* patterns; omitted means all/default scope."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["Clear restores ordinary compaction routing; it does not disable compaction. Omitted triggers/sources retain server defaults.","Set replaces the full block, preserving canonical schema normalization only. No synthetic inference verifies the save. Writes report the actual normalized block and catalogRefreshPending, which is not a full catalog receipt."],
},
{
command: ["agent","compaction-routing","clear"],
usage: "ocx agent compaction-routing clear [--json]",
summary: "Clear the compaction routing override block.",
routes: [{"method":"PUT","path":"/api/settings"}],
flags: [{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
mutates: true,
json: "envelope",
details: ["Clear restores ordinary compaction routing; it does not disable compaction. Omitted triggers/sources retain server defaults.","Set replaces the full block, preserving canonical schema normalization only. No synthetic inference verifies the save. Writes report the actual normalized block and catalogRefreshPending, which is not a full catalog receipt."],
},
];