[Feature]: add Muse Code subscription routing through a process-backed MSP adapter #3191

Area

Multiple areas

What are you trying to accomplish?

Use an active Muse Code subscription as an explicit, subscription-backed model route for Codex CLI, Codex Desktop, and other OpenCodex-connected clients without silently sending those requests through Meta Model API pay-as-you-go billing.

The desired user workflow is:

1. Install the official muse CLI.
2. Sign in through muse login with the Meta account that owns a Muse Code subscription.
3. Let OpenCodex expose a clearly labeled Muse Code route to compatible clients.
4. Select a model such as muse-code/muse-spark-1.2 in Codex.
5. Have the request consume Muse Code plan allowance, preserving the subscription's current and weekly usage windows.
6. Keep any separately configured Meta Model API key route visibly distinct and pay-as-you-go.

This is primarily a provider-adapter and authentication-provenance request, with related proxy, streaming, tool, lifecycle, catalog, usage, and dashboard implications.

What prevents this today?

OpenCodex currently treats Meta Muse models as a normal HTTP API-key provider. On OpenCodex 2.39.0, the configured route is equivalent to:

provider: meta-model-api
adapter: openai-chat
base URL: https://api.meta.ai/v1
authentication: API key
models:
  - muse-spark-1.1
  - muse-spark-1.2
  - muse-spark-1.2-contributor

That route works technically, but Meta records it under Model API pay-as-you-go usage. It does not consume the Muse Code subscription merely because the same Meta account owns both.

Meta's subscription documentation states that:

• Muse Code subscriptions are flat-rate usage for Muse Code rather than per-token API billing.
• The subscription applies through the Muse Code CLI while signed in with the Meta Model API account.
• The subscription credential is for Muse Code only.
• Additional API keys under the Model API account are billed pay-as-you-go.

Source: https://dev.meta.ai/docs/muse-code/subscriptions

The official CLI exposes a process boundary that appears intended for host integrations:

muse serve — serve an MSP session host over stdio

The embedded schema advertises a session-oriented command plane including session/*, turn/*, model/list, view/*, approval/*, and userInput/*. However, OpenCodex's current adapter registry has HTTP/provider wire adapters such as openai-chat, openai-responses, anthropic, google, kiro, and cursor; it has no MSP, stdio, or general process-backed provider adapter. Its current OAuth controllers also do not include Muse/Meta account login.

As a result, none of these current approaches satisfies the workflow:

• Pointing OpenCodex at https://api.meta.ai/v1 uses API-key billing.
• Importing or extracting Muse account tokens would cross an unsupported credential boundary and should not be done.
• Running muse separately uses the subscription but does not make it an OpenCodex/Codex model route.
• Wrapping one-shot muse exec calls as plain text loses session continuity, tool calls, approvals, cancellation, model configuration, and authoritative streaming semantics.
• Exposing Muse only as an MCP tool would make it a tool used by another primary model, not a selectable Muse-backed coding agent.

The important failure mode is billing ambiguity. A catalog row named only muse-spark-1.2 can look subscription-backed even when it is actually the separately metered Model API route.

What should OpenCodex do?

Provide a first-class, explicitly labeled Muse Code subscription integration that launches and communicates with the official authenticated Muse CLI instead of reusing a Meta Model API key.

Observable behavior should include the following.

1. Explicit credential and billing provenance

• Present the subscription route as something like Muse Code subscription via Muse CLI.
• Keep it separate from Meta Model API · pay-as-you-go even when both offer the same model ID.
• Never imply that an API-key route consumes subscription allowance.
• Never silently fall back from the subscription route to a Meta API key.
• If an optional fallback is ever supported, require explicit configuration and surface the billing boundary before it is enabled and in per-request logs afterward.

This should follow the same provenance principle described in #1213: a unified catalog must not hide a meaningful change in credential or billing source behind identical model names.

2. Official Muse CLI account boundary

• Use the installed muse executable and its own Meta account session.
• Do not read, export, copy, persist, or forward Muse OAuth/access/refresh credentials into OpenCodex storage.
• Provide an authentication-status check that can distinguish at least:
  • Muse CLI not installed;
  • installed but not logged in;
  • logged in without an eligible subscription;
  • eligible subscription available;
  • subscription usage limit reached;
  • account session requires reauthentication.
• When login is required, direct the user to the official muse login flow rather than collecting Meta credentials in OpenCodex.

3. Process-backed MSP session integration

• Launch muse serve as a supervised local child process or equivalent official Muse host boundary.
• Translate OpenCodex's downstream Responses API contract into MSP sessions and turns without flattening the interaction into one-shot text completion calls.
• Preserve:
  • conversation/session affinity;
  • streaming text and status events;
  • model selection and supported reasoning-effort configuration;
  • tool declarations and tool results where the protocols permit them;
  • approval and user-input requests;
  • cancellation and interruption;
  • session rotation and recovery;
  • image or other supported multimodal inputs;
  • authoritative terminal completion and error states.
• Bound process startup, idle, turn, cancellation, and shutdown behavior so a dead or wedged Muse host cannot leave Codex requests hanging indefinitely.

If MSP cannot faithfully represent a required Codex Responses behavior, fail with a named compatibility error instead of silently degrading the request.

4. Catalog and client behavior

• Expose plan-backed models under a distinct namespace, for example:

muse-code/muse-spark-1.2

• Preserve the existing API-backed namespace separately, for example:

meta-model-api/muse-spark-1.2

• Make GET /v1/models, the generated Codex catalog, CLI output, dashboard rows, and request logs agree on the selected provenance.
• Allow the subscription route to be selected from both Codex CLI and Codex Desktop through the normal OpenCodex catalog path.
• Do not require the user to expose a Meta API key just to use the subscription route.

5. Usage and observability

• Report Muse plan usage as subscription allowance, not estimated token cost.
• If the Muse host exposes current-window and weekly-window usage, show those windows distinctly from pay-as-you-go spend.
• Tag request logs with safe route metadata such as:

provider=muse-code
auth=meta-account-session
billing=subscription
transport=msp-stdio

• Never log account tokens, browser authorization codes, raw credential stores, or unsafe account identifiers.
• Make it possible to prove that a request used the subscription route without inspecting secrets.

6. Security and policy boundaries

• Keep the Muse child process local by default.
• Preserve OpenCodex's existing loopback and client-admission protections.
• Treat workspace trust, shell access, filesystem access, sandbox posture, and network posture as explicit host configuration rather than protocol assumptions.
• Do not enable muse serve --trust-workspace, disable its sandbox, or broaden network/filesystem access implicitly.
• Document which process owns tool execution and approval decisions so the same tool is not executed once by Muse and again by Codex/OpenCodex.
• Verify the proposed integration against Meta's current Muse Code subscription terms before declaring it supported.

7. Failure and recovery behavior

Return clear, non-secret-bearing errors for at least:

• executable missing or unsupported Muse version;
• invalid or expired Meta account session;
• no eligible Muse Code subscription;
• plan window exhausted;
• incompatible MSP schema or protocol version;
• child-process startup failure;
• child-process crash during a turn;
• stalled stream or cancellation timeout;
• unsupported tool, modality, or Responses feature;
• user-selected subscription route with only an API key available.

Restart or retry behavior must be bounded and must not change billing provenance.

Example usage or interface

One possible CLI shape is shown below. The exact option names can follow existing OpenCodex conventions, but the user-visible separation between subscription and API billing is required.

# Authenticate through the official client. OpenCodex does not receive the token.
muse login

# Register or enable the process-backed subscription provider.
ocx provider add muse-code \
  --adapter muse-msp \
  --command muse \
  --command-arg serve

# Confirm executable, login, subscription eligibility, model discovery,
# protocol compatibility, and billing provenance without consuming API-key credit.
ocx provider test muse-code

# Show a redacted status projection.
ocx provider show muse-code --json

# Use the subscription-backed route from Codex CLI.
codex --model muse-code/muse-spark-1.2

Expected status projection:

{
  "name": "muse-code",
  "adapter": "muse-msp",
  "transport": "stdio",
  "authentication": "Meta account session owned by Muse CLI",
  "billing": "Muse Code subscription",
  "loggedIn": true,
  "subscriptionEligible": true,
  "models": ["muse-spark-1.2"]
}

The existing API route remains separately visible:

{
  "name": "meta-model-api",
  "adapter": "openai-chat",
  "baseUrl": "https://api.meta.ai/v1",
  "authentication": "API key",
  "billing": "pay-as-you-go",
  "models": [
    "muse-spark-1.1",
    "muse-spark-1.2",
    "muse-spark-1.2-contributor"
  ]
}

The dashboard and picker should use provenance-aware labels, for example:

Muse Spark 1.2 · Muse Code subscription
Muse Spark 1.2 · Meta Model API pay-as-you-go

Alternatives or workarounds

Continue using the Meta Model API key

This already works in OpenCodex, but it incurs per-token API charges and does not satisfy the subscription workflow.

Run Muse Code separately

This is the only currently verified subscription-backed route. It does not make Muse a selectable model inside Codex CLI/Desktop or other OpenCodex clients.

Invoke muse exec from a shell script or MCP tool

This can use the official CLI account session for bounded calls, but Muse becomes a secondary tool rather than the primary coding agent. A naive one-shot wrapper also loses session, tool, approval, interruption, and streaming semantics.

Extract the Muse account token and use it as an OpenCodex bearer token

This should not be implemented. It would bypass the documented credential boundary, create token-refresh and storage risks, and may violate Meta's intended subscription usage contract.

Build a standalone Responses-to-MSP proxy outside OpenCodex

This could prove the translation experimentally, but it would duplicate OpenCodex routing, lifecycle, catalog, logging, and security responsibilities. If the integration is supportable, OpenCodex is the more coherent long-term owner.

Additional context

Verified environment

The following was verified on September 1, 2026:

OpenCodex installed: 2.39.0
OpenCodex latest npm: 2.39.0
Muse Code CLI: 1.0.1 (1.0.1-R2006.1)
Operating system: Linux x86_64

Direct evidence:

• ocx provider show meta-model-api --json reports adapter: openai-chat, baseUrl: https://api.meta.ai/v1, and API-key presence.
• A minimal request through the raw OpenCodex/Meta route appeared under Meta Model API pay-as-you-go usage.
• After muse login, a minimal muse exec --model muse-spark-1.2 request completed successfully.
• The Meta usage dashboard then exposed Muse Code subscription-window consumption separately from pay-as-you-go spend.
• The pay-as-you-go balance did not change across the direct Muse CLI subscription smoke request.
• muse serve --help confirms an MSP session host over stdio.
• muse schema documents a session/turn/model/view/approval/user-input command plane embedded in the installed binary.
• OpenCodex 2.39.0's adapter registry does not contain an MSP, ACP, stdio, Muse CLI, or generic process-backed provider.
• OpenCodex's current sidecar surface is limited to web and vision model sidecars and does not host an external full coding agent.

No credentials, account identifiers, project IDs, payment details, prompts from private work, or personal paths are included in this report.

Related issue and provenance precedent

• [Feature/UX]: add additive Claude Desktop catalog mode with honest native/OpenCodex switching #1213 documents the requirement not to simulate subscription-backed access with a separately billed API credential and asks that unified catalogs expose meaningful provider/credential provenance.

No open issue was found for Muse Code subscriptions, Meta subscription routing, MSP adapters, stdio/process-backed providers, or muse serve integration before filing this proposal.

Suggested delivery slices

This likely benefits from staged delivery rather than one large change:

1. Read-only Muse executable, version, login, eligibility, and model discovery probe.
2. MSP schema/version negotiation and supervised process lifecycle.
3. Single-session text streaming through an explicit experimental provider.
4. Cancellation, interruption, terminal errors, and restart recovery.
5. Tool, approval, user-input, and multimodal compatibility.
6. Multi-session affinity, bounded concurrency, and lifecycle tests.
7. Catalog, picker, dashboard, usage, and billing-provenance UI.
8. Documentation, migration guidance, and a no-API-fallback security review.

Non-goals

• Do not scrape or copy credentials from Muse storage.
• Do not claim that Meta Model API keys are subscription-backed.
• Do not silently convert subscription exhaustion into API charges.
• Do not make Muse Code the OpenCodex default automatically.
• Do not weaken Muse or OpenCodex sandbox, approval, workspace-trust, or network defaults.
• Do not expose a local account-backed Muse host remotely without a separate authenticated multi-user security design.

Acceptance criteria

• A supported process-backed Muse integration uses the official muse account session without OpenCodex owning the Meta credential.
• Codex CLI and Codex Desktop can select a distinctly namespaced Muse subscription route from the OpenCodex catalog.
• A subscription-backed request is observable as plan usage and does not increment Meta Model API pay-as-you-go spend.
• The existing Meta API-key provider remains available only under explicit pay-as-you-go provenance.
• No automatic fallback crosses from subscription to API billing.
• Missing login, missing subscription, exhausted plan, protocol mismatch, process failure, and unsupported capabilities produce clear bounded errors.
• Streaming, cancellation, session affinity, terminal completion, and restart behavior have focused regression coverage.
• Tool and approval ownership is explicit and double execution is prevented.
• Logs, config projections, and error output never expose Muse or Meta credential material.
• Catalog, /v1/models, generated Codex metadata, dashboard, and request logs agree on billing provenance.
• Documentation states the supported Meta/Muse boundary and links to current upstream subscription documentation.
• The integration is verified against current Muse Code subscription terms before being advertised as supported.

Checks

• 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.