feat(integrations): add a versioned Orca launch manifest

[str0203]

Area

Multiple areas

What are you trying to accomplish?

I want to run Codex and Claude Code inside Orca while keeping OpenCodeX as the single owner of model routing, provider credentials, account pools, and proxy lifecycle. Orca already hosts both agents and supports command overrides, but there is no first-class, machine-readable OpenCodeX integration contract.

What prevents this today?

The current workaround is to hand-edit Orca launch commands and environment variables. That couples Orca to OpenCodeX implementation details, is easy to break across platforms, and is especially ambiguous when Orca sets ORCA_CODEX_HOME/CODEX_HOME for an isolated Codex runtime. OpenCodeX currently recognizes that home mismatch only for diagnostics; it does not export an Orca launch contract.

There is also no safe way for Orca to discover the correct readiness workflow, dashboard action, Codex prelaunch step, and Claude Code wrapper without hard-coding them. Copying OpenCodeX provider keys or OAuth credentials into Orca would be insecure and would create two competing configuration owners.

The existing client-export path normally reads the live proxy model catalog. An Orca launch manifest must not create a bootstrap cycle: it needs to be available while the proxy is stopped so the consumer can discover and run the prelaunch/readiness workflow.

What should OpenCodeX do?

Add Orca to the existing client-export surface, for example:

ocx export --client orca --json

The export should be a versioned, machine-readable, secret-free launch manifest that:

• describes readiness/dashboard operations and Codex/Claude Code launch argv;
• uses argv arrays rather than shell fragments;
• can be generated while the proxy is stopped;
• accepts an intentional Orca-scoped home when all launch stages share it, while returning structured guidance for a genuine cross-home service/config conflict;
• never serializes provider keys, OAuth tokens, account identities, or admin credentials;
• uses environment-variable references when non-loopback admission is required;
• allows consumers to reject unsupported schema versions;
• is covered by cross-platform and secret-leak tests;
• is documented as the stable integration boundary for Orca and similar agent hosts.

Embedding the OpenCodeX dashboard in Orca and implementing Orca UI are explicitly out of scope for this issue.

Example usage or interface

manifest="$(ocx export --client orca --json)"

Illustrative shape:

{
  "schemaVersion": 1,
  "service": {
    "ready": { "argv": ["ocx", "ready", "--wait", "--json"] },
    "dashboard": { "argv": ["ocx", "gui"] }
  },
  "agents": {
    "codex": {
      "prelaunch": { "argv": ["ocx", "ensure"] },
      "launch": { "argv": ["codex"], "passThroughArgs": true }
    },
    "claude": {
      "launch": { "argv": ["ocx", "claude"], "passThroughArgs": true }
    }
  }
}

Field names are illustrative; the important requirements are a versioned contract, argv-safe launch instructions, no secrets, and explicit home/readiness diagnostics.

Alternatives or workarounds

• Manually override Orca's codex and claude commands. This works for basic local launches but has no stable readiness, schema, authentication, or CODEX_HOME contract.
• Ask Orca to reimplement provider and account-pool management. This duplicates OpenCodeX and creates two credential owners.
• Embed the full OpenCodeX dashboard in Orca. This is much larger and can be considered later once the launch contract is stable.

Additional context

• Orca: https://github.com/stablyai/orca
• Orca already supports arbitrary CLI agents and command overrides.
• OpenCodeX already diagnoses the Windows Orca/ChatGPT dual-home mismatch in src/codex/home.ts.
• A companion Orca issue will request the opt-in UI and manifest consumer after this issue is created.

Checks performed:

• I searched existing issues and documentation.
• This request describes a concrete OpenCodeX workflow rather than merely naming a desired technology.
• I removed secrets and personal data.

[str0203]

Companion Orca-side request filed: stablyai/orca#13555

The two issues intentionally split ownership: OpenCodeX provides the versioned, secret-free launch/status contract; Orca consumes it for opt-in Codex and Claude Code session UX.

[Ingwannu]

The integration goal is valid, but it needs to remain a distinct contract from the existing catalog export.

Current ocx export --client ... serializes client configuration from the live management catalog. An Orca launch manifest must also work while the proxy is stopped, so it cannot silently inherit that live-catalog dependency or reuse an existing client schema with different readiness semantics.

A reviewable implementation should therefore:

• define a versioned Orca launch-manifest schema with argv arrays and explicit pass-through semantics;
• build the stopped-proxy manifest only from local executable/config contracts, with no provider keys, OAuth/account data, admin token, or resolved secret values;
• keep environment references symbolic and make non-loopback admission an explicit operator-supplied input;
• report the existing high-confidence Orca/Codex-home mismatch as structured diagnostics rather than rewriting CODEX_HOME;
• keep readiness/prelaunch idempotent and cross-platform, with tests for stopped/running proxy states, unsupported schema versions, path/argv quoting, and secret absence.

This is a worthwhile integration direction. Keeping it open for a focused contract proposal or PR; the companion Orca consumer can then bind to that stable schema.