opencode-muse-auth 0.4.1 → 0.5.0

package/ADAPTER_CONTRACT.md

@@ -0,0 +1,132 @@
+# Muse wire adapter contract (v3)
+
+Every Muse Code plugin in this family sends subscription inference through the same local
+adapter. This file pins the wire rules; `ADAPTER_VERSION` in the code is the matching constant.
+Change both together in all four repositories:
+
+- `opencode-muse-auth`
+- `hermes-muse-code`
+- `openclaw-muse-code`
+- `dsh-muse-code`
+
+## Why the adapter exists
+
+Since 2026-10-29/30, `https://api.meta.ai/v1` refuses a Muse Code subscription credential when
+the request declares a flat function tool whose name is exactly one of Muse Code's builtin tool
+names. The refusal is HTTP 403 with `code: client_attestation_denied`:
+
+> This API key is billed to a Muse Code subscription. Muse Code subscriptions cover requests from
+> the Muse Code client only. Use it in Muse Code, or use a pay-as-you-go API key for other clients.
+
+The gate inspects the declared tool names, not the client identity: headers, user agent, system
+prompt and the rest of the payload do not change the outcome. The adapter aliases only the
+colliding names on the way out and restores them on the way back, so the host keeps its own tool
+names and no credential or signature is forged.
+
+## Measured trigger (live subscription key, 2026-10-30)
+
+| Request tool declarations | Result |
+|---|---|
+| no `tools` | 200 |
+| flat `get_weather` | 200 |
+| flat `client_read_file` | 200 |
+| flat `read_file` | 403 |
+| flat `bash` | 403 |
+| flat `web_search` | 403 |
+| flat names outside the first six, e.g. `web_fetch`, `workflow`, `powershell`, `add_memory` | 403 (each, separate probe) |
+| flat `read_file` + `get_weather` | 403 |
+| namespace `client` containing `read_file` | 200 |
+| namespace `muse` with the genuine builtin declaration | 200 |
+| namespace `muse` with a re-schematized `read_file` | 403 |
+
+Two consequences drive the rules below:
+
+1. A single colliding flat name is enough to fail the whole request.
+2. Wrapping client tools in a namespace also passes today, but Meta validates the contents of a
+   namespace named `muse`, and a wrapper changes the tool surface the model sees. The adapter
+   therefore keeps the flat shape and only renames the colliding declarations.
+
+## Builtin collision set (v3)
+
+`workflow`, `read_file`, `write_file`, `edit_file`, `bash`, `bash_input`, `search`,
+`web_search`, `web_fetch`, `powershell`, `powershell_input`, `read_memory`,
+`add_memory`, `edit_memory`, `read_skill`, `write_todos`, `monitor`, `work_status`,
+`work_list`, `work_stop`, `snooze_reminder`, `apply_patch`, `shell`, `create_goal`,
+`get_goal`, `update_goal`, `report_progress`, `request_user_input`, `cron_create`,
+`cron_delete`, `cron_list`, `send_session_message`, `list_peer_sessions`,
+`subagent_send_message`, `subagent_cancel`, `subagent_spawn`, `subagent_status`,
+`subagent_wait`, `subagent_read_result`, `tool_search`.
+
+The set comes from the 1.4.14 binary's tool catalog plus `muse exec` captures;
+every name was probed individually against api.meta.ai on 2026-10-30: all but
+`tool_search` returned 403, and `tool_search` stays in the set defensively. The
+catalog includes the goal, cron, session and patch tools as well as the file,
+shell and web families.
+
+The set is pinned in code (`COLLIDING_TOOL_NAMES`). Add a name only with evidence that Meta
+rejects it, and bump `ADAPTER_VERSION`.
+
+## Request rules
+
+1. **Aliasing.** Every flat tool of `type: "function"` whose `name` is in the collision set is
+   renamed to `client_<name>`. If that alias is already taken by another declared tool, append
+   `_2`, `_3`, and so on. The same mapping is applied to `input[].function_call.name` for
+   `type: "function_call"` history items. Non-function tools, namespace containers and
+   non-colliding names are left untouched.
+2. **`tool_choice`.** Meta accepts only `"auto"`. Any other value (named function, `"none"`,
+   `"required"`) is replaced with `"auto"`.
+3. **Reasoning effort.** A top-level `reasoning_effort` string moves to `reasoning.effort`; an
+   explicit `reasoning.effort` already present wins.
+4. **Output floor.** `max_output_tokens` below 16 is raised to 16.
+5. **Reasoning replay.** `reasoning.encrypted_content` is appended to `include` when missing, so a
+   host that replays provider items can keep the encrypted reasoning item.
+6. **Version header.** `x-api-version: 1.0.0` is added when the host did not set it.
+7. Unknown fields are preserved untouched, and the caller's body object is never mutated.
+
+## Automatic fallback
+
+If Meta refuses a request with `client_attestation_denied` even after these
+rules, the adapter retries the same request once with every flat function tool
+aliased (`client_<name>`), and restores the names in the answer. That keeps a
+Muse builtin name this release does not know from taking the lane down; the
+retry is logged as `gate refused; retried with all N tools aliased`.
+
+## Response rules
+
+1. Aliased `function_call` names are restored to the original name in:
+   `response.output_item.added` / `.done` items, the `output` array of every `response.*` event,
+   the `tools` echo of the response object, the top-level `name` of
+   `response.function_call_arguments.done`, and the `output` array of a non-streaming JSON body.
+2. If an authoritative `output_item.done` or completed item carries an empty `arguments`, the
+   value accumulated from `response.function_call_arguments.delta` events is written back.
+3. SSE is relayed line by line and flushed per line; responses are never buffered.
+
+## Transport rules
+
+- The adapter listens on `127.0.0.1` only, on the first free port of `43219`, `43220`, `43221`,
+  `43222`, then an ephemeral port.
+- The provider base URL becomes `http://127.0.0.1:<port>/v1`.
+- `Authorization` is forwarded unchanged; the adapter never reads, stores or logs credentials,
+  request bodies or response bodies.
+- Every path other than the Responses and Chat completion paths is relayed untouched, so
+  `GET /v1/models` discovery keeps working through the same base URL.
+- `MUSE_CODE_ADAPTER=off` turns the wire rules off while keeping the proxy in place, so a
+  persisted base URL stays valid. Diagnostic logging is one line per adapted request, through the
+  host's debug logger.
+- If the adapter cannot bind, the plugin logs the failure and leaves the provider on the direct
+  endpoint, which is the pre-0.3 behavior.
+
+## Failure modes
+
+- Meta changes the gate to a real per-client signature: aliasing stops helping and requests fail
+  again with `client_attestation_denied`. Nothing in this design can fake a signature.
+- Meta renames or removes a builtin: the collision set needs an update.
+- A host does not preserve provider reasoning items across turns: tool arguments may degrade to
+  `{}`. The adapter repairs the empty-arguments field, but not a host that never replays the
+  reasoning item.
+
+## Verification
+
+- Offline: the adapter unit and proxy tests in each repository, against a fake upstream.
+- Live: start the adapter against `https://api.meta.ai`, send a request with a colliding tool
+  name, and require HTTP 200 with the original name restored in the response.

package/AUTH_CONTRACT.md

@@ -1,11 +1,12 @@
 # Muse auth contract (v1)
 
-The three Muse Code plugins implement the same Meta device-code flow. Change
-this file and the pinned constants/tests together in all three repositories:
+The four Muse Code plugins implement the same Meta device-code flow. Change
+this file and the pinned constants/tests together in all four repositories:
 
 - `opencode-muse-auth`
 - `hermes-muse-code`
 - `openclaw-muse-code`
+- `dsh-muse-code`
 
 ## Wire contract
 
@@ -18,6 +19,7 @@ this file and the pinned constants/tests together in all three repositories:
 | API version header | `x-api-version: 1.0.0` |
 | Cache fields | `apiKey`, `accountId`, `email` (never the OAuth access token) |
 | Inference base URL | `https://api.meta.ai/v1` |
+| Inference wire adapter | see `ADAPTER_CONTRACT.md` (v3) |
 
 ## Behaviour
 
@@ -28,5 +30,11 @@ this file and the pinned constants/tests together in all three repositories:
   key; reject an inactive subscription or a pending payment.
 - Persistence: only the inference key and account identity are stored; the
   OAuth access token stays in memory.
+- Inference traffic on the V2 plugin API goes through the loopback adapter
+  described in `ADAPTER_CONTRACT.md` (tool-name aliasing, parameter
+  normalization, response name restoration). The adapter is part of the wire
+  contract: a change to those rules bumps `ADAPTER_VERSION` and the pinned
+  tests in every repository that vendors the adapter. The V1 code path keeps
+  sending directly to `https://api.meta.ai/v1`.
 - Any change to this contract bumps `AUTH_CONTRACT_VERSION` in the code and
-  requires updating the pinned tests in all three repositories.
+  requires updating the pinned tests in all four repositories.

package/DISCLAIMER.md

@@ -25,6 +25,19 @@ Meta may change, restrict or enforce its terms at any time, and may suspend,
 restrict or terminate accounts, subscriptions or credentials involved. The
 authors cannot prevent, predict or reverse that outcome.
 
+## Request shaping
+
+Since 2026-10-29 Meta refuses subscription requests from other clients when the
+declared client tool names collide with Muse Code's builtin tool names. On the
+V2 plugin API this plugin therefore runs a local adapter that renames exactly
+those declarations on the way to `api.meta.ai` and restores them in the
+response, so the request matches Muse Code's wire format. This is a deliberate
+workaround of Meta's client restriction: it does not forge a credential, token
+or signature, and the subscription key remains your own, but Meta may treat the
+reshaping itself as a violation of its terms. The suspension, revocation and
+no-refund risks described above apply with full force, and revocation can
+happen immediately.
+
 ## No warranty, no guarantee
 
 - The integration is provided "as is"; there is no guarantee that it is

package/README.md

@@ -7,8 +7,10 @@ Muse Code subscription sign-in for opencode
 [![npm](https://img.shields.io/npm/v/opencode-muse-auth)](https://www.npmjs.com/package/opencode-muse-auth)
 
 opencode plugin that registers the **Muse Code subscription** login method for the built-in `meta`
-provider. No API key to copy and no third-party CLI to install. A successful login does not guarantee
-model access: Meta may reject subscription requests from clients other than Muse Code.
+provider. No API key to copy and no third-party CLI to install. On the V2 plugin API the plugin also
+routes subscription inference through a local wire adapter that keeps requests compatible with Muse
+Code's tool declarations; see [ADAPTER_CONTRACT.md](ADAPTER_CONTRACT.md). A successful login still
+does not guarantee model access: Meta may reject or restrict this use.
 
 > **Unofficial and experimental.** This plugin uses a Muse Code subscription credential from
 > opencode. Meta's terms limit that credential to Muse Code, so this use may not be supported and
@@ -34,7 +36,9 @@ Add the plugin to `opencode.json`; opencode installs it from npm:
 3. Open the printed Meta device page, enter the printed code, and approve the login in your own
    browser. The login completes by itself.
 4. Select a `muse-*` model exposed by the `meta` provider, for example `meta/muse-spark-1.3`.
-   Meta's subscription restrictions still apply to requests from opencode.
+   On opencode 2.x the plugin routes inference through the local adapter, so client tool names that
+   collide with Muse Code's builtins no longer trip Meta's client gate. The V1 plugin API still
+   sends requests straight to `api.meta.ai` and keeps receiving the 403.
 
 The plugin mints a stable, account-bound inference key and hands it to opencode. The OAuth access
 token from the login flow is kept in memory only and is never written to disk.
@@ -47,6 +51,12 @@ token from the login flow is kept in memory only and is never written to disk.
   inference key through the Model API.
 - Routes through the Responses API; the `meta.txt` system prompt applies automatically to `muse-*`
   model ids.
+- Runs a loopback wire adapter for the V2 plugin API: it aliases the client tool names that collide
+  with Muse Code's builtins on the way to `api.meta.ai`, restores them in the response, and
+  normalizes parameters Meta rejects (`tool_choice`, reasoning effort, output-token floor,
+  encrypted-reasoning include). The adapter's `/v1` origin becomes the per-request base URL; on
+  routes that ignore that override the plugin rewrites the assembled request onto the same origin. If Meta still refuses the request, the
+  adapter retries once with every tool aliased. See [ADAPTER_CONTRACT.md](ADAPTER_CONTRACT.md).
 - V1 storage: the OpenCode auth store is the primary source, and the loader falls back to the
   legacy cache only when the store has no key.
 - V2 storage: the credential lives in the OpenCode integration store, and no local cache is
@@ -60,6 +70,8 @@ token from the login flow is kept in memory only and is never written to disk.
 
 - opencode with plugin support, including the v2 plugin module shape accepted by opencode 1.18.29+
   and 2.x.
+- The loopback adapter requires the V2 plugin API (opencode 2.x). V1 installs keep authenticating
+  but still receive Meta's `client_attestation_denied` 403.
 - Node.js 22.6 or newer for development; CI runs Node.js 22 and 24.
 - An active Muse Code subscription on the Meta account used at login.
 
@@ -71,14 +83,17 @@ token from the login flow is kept in memory only and is never written to disk.
 | Auth store | Primary credential storage used by the V1 loader. | `~/.local/share/opencode/auth.json` |
 | Legacy cache | Read-only fallback for credentials written by earlier versions. | `~/.config/opencode/muse-code-sub.json` |
 | `/connect` method | Selects Muse Code subscription login for the `meta` provider. | `meta` provider |
+| `MUSE_CODE_ADAPTER` | `off` keeps the local proxy but disables the tool-name reshaping and parameter normalization. | unset |
 
 ## Privacy and security
 
 The inference key is held by opencode: in the V1 auth store or the V2 integration store. The
 legacy cache, when present, stores only `apiKey`, `accountId`, and `email`; the OAuth access token
 is never written to disk. The plugin talks only to `auth.meta.com` for the device login and
-`api.meta.ai` for key minting and inference. See [SECURITY.md](SECURITY.md) for vulnerability
-reporting.
+`api.meta.ai` for key minting and inference. The V2 wire adapter listens on `127.0.0.1` only,
+forwards the `Authorization` header unchanged, and never reads, stores or logs credentials,
+request bodies or response bodies. See [SECURITY.md](SECURITY.md) for vulnerability reporting and
+[ADAPTER_CONTRACT.md](ADAPTER_CONTRACT.md) for the inference wire rules.
 
 To remove access:
 
@@ -103,9 +118,19 @@ its own.
 ### Meta rejects subscription requests from this client
 
 Meta may return a 403 mentioning `client_attestation_denied` or that Muse Code subscriptions cover
-the Muse Code client only. This is a client restriction, not evidence of an expired key. Signing in
-again does not remove the restriction. Use Muse Code for the subscription, or a separate
-pay-as-you-go Meta Model API key for other clients, subject to Meta's terms.
+the Muse Code client only. With the V2 adapter running this should not happen for tool names that
+collide with Muse Code's builtins. If it appears anyway, one of these is true:
+
+- the adapter could not bind its loopback port; opencode's log records
+  `the local request adapter could not start`, and the provider stays on the direct endpoint;
+- `MUSE_CODE_ADAPTER=off` is set, which keeps the proxy but disables the reshaping;
+- you are on the V1 plugin API, which has no adapter;
+- Meta changed the gate, for example to a real per-client signature. Nothing in this plugin can
+  forge one.
+
+This is a client restriction, not evidence of an expired key. Signing in again does not remove it.
+Use Muse Code for the subscription, or a separate pay-as-you-go Meta Model API key for other
+clients, subject to Meta's terms.
 
 ### The login times out or is denied
 

package/dist/adapter.d.ts

@@ -0,0 +1,97 @@
+/** Version of the wire rules below; bump with ADAPTER_CONTRACT.md. */
+export declare const ADAPTER_VERSION = 3;
+/** Default upstream; tests override it with a local fake. */
+export declare const DEFAULT_UPSTREAM = "https://api.meta.ai";
+/**
+ * Muse Code builtin tool names.
+ *
+ * Reconstructed from the 1.4.14 binary's tool catalog and from `muse exec`
+ * captures, then probed one by one against api.meta.ai on 2026-10-30: a flat
+ * client tool with one of these exact names is refused with 403
+ * `client_attestation_denied`. The catalog includes goal, cron, session and
+ * patch tools as well as the file, shell and web families. `tool_search` is
+ * included defensively: one probe returned 200, but field reports see a 403.
+ */
+export declare const COLLIDING_TOOL_NAMES: ReadonlySet<string>;
+type JsonRecord = Record<string, unknown>;
+/** One alias plan: original name to wire name, plus the reverse map. */
+export interface AliasPlan {
+    readonly aliases: ReadonlyMap<string, string>;
+    readonly reverse: ReadonlyMap<string, string>;
+}
+/**
+ * Decide which declared tool names must be aliased.
+ *
+ * Only flat `function` tools are considered: those are the declarations Meta
+ * compares against its builtin set. A namespace container is left untouched.
+ * With `all`, every flat function tool is aliased; the proxy uses that as a
+ * one-shot retry when the gate refuses names this release does not know.
+ */
+export declare function planToolAliases(tools: unknown, options?: {
+    all?: boolean;
+}): AliasPlan;
+/** Result of adapting a request body: the body to send, its plan and a log line. */
+export interface AdaptedRequest {
+    readonly body: JsonRecord;
+    readonly plan: AliasPlan;
+    readonly notes: string[];
+}
+/**
+ * Apply the wire rules to one Responses/Chat request body.
+ *
+ * The input object is not mutated: a shallow copy is returned. Unknown fields
+ * are preserved untouched. Pass a plan from {@link planToolAliases} to reuse a
+ * mapping, for example the full-aliasing retry.
+ */
+export declare function transformRequestBody(body: JsonRecord, plan?: AliasPlan): AdaptedRequest;
+/**
+ * Streaming name restorer.
+ *
+ * Feeds complete SSE lines and returns the line to relay. It restores aliased
+ * function-call names and repairs empty `arguments` from the streamed deltas:
+ * Meta's authoritative `response.output_item.done` sometimes ships "" even
+ * though the deltas carried the JSON.
+ */
+export declare class SseRestorer {
+    private readonly reverse;
+    private readonly arguments;
+    constructor(reverse: ReadonlyMap<string, string>);
+    /** Adapt one complete SSE line (without the trailing newline). */
+    feed(line: string): string;
+    private adapt;
+    /** Restore names in an emitted response object (tools echo and output items). */
+    private adaptResponse;
+    private collectArguments;
+    private repairArguments;
+}
+/** Restore aliased names and empty arguments in a complete JSON response. */
+export declare function transformResponseBody(body: JsonRecord, reverse: ReadonlyMap<string, string>): JsonRecord;
+/** Options for {@link startMuseCodeAdapter}. */
+export interface AdapterOptions {
+    /** Upstream origin; override for tests only. */
+    readonly upstream?: string;
+    /** Candidate loopback ports; the first free one wins, then an ephemeral port. */
+    readonly ports?: readonly number[];
+    /** Diagnostic sink; one short line per adapted request. */
+    readonly log?: (message: string) => void;
+    /** Disable the wire rules but keep proxying (MUSE_CODE_ADAPTER=off). */
+    readonly passthrough?: boolean;
+}
+/** A running adapter. */
+export interface RunningAdapter {
+    /** Loopback origin to use as the provider baseURL, e.g. http://127.0.0.1:43219/v1. */
+    readonly baseUrl: string;
+    /** Actual loopback port. */
+    readonly port: number;
+    /** Stop accepting and close the server. */
+    close(): Promise<void>;
+}
+/**
+ * Start the loopback adapter.
+ *
+ * The server binds 127.0.0.1 only. Requests to the Responses and Chat
+ * completion paths are adapted; every other path is relayed untouched, so
+ * the provider's model discovery keeps working through the same baseURL.
+ */
+export declare function startMuseCodeAdapter(options?: AdapterOptions): Promise<RunningAdapter>;
+export {};

package/dist/adapter.js

@@ -0,0 +1,554 @@
+// Muse Code request adapter: make subscription traffic look like Muse Code's
+// own tool declarations.
+//
+// Meta's api.meta.ai refuses a Muse Code subscription key when the request
+// declares a client function tool whose name collides with one of Muse Code's
+// builtin tool names (`read_file`, `bash`, `web_search`, ...). The refusal is
+// HTTP 403 with code `client_attestation_denied`. Names that do not collide are
+// accepted, and so is the same tool under a non-colliding name (see
+// ADAPTER_CONTRACT.md for the measured matrix).
+//
+// This module runs as a loopback reverse proxy in front of api.meta.ai. It
+// aliases only the colliding tool names on the way out and restores them on the
+// way back, so the host sees its own tool names and MCP servers keep working.
+// Nothing else about the request is rewritten.
+//
+// The file is dependency-free and deliberately host-agnostic: the same module
+// is vendored by the sibling Muse plugins. Keep it in sync (ADAPTER_VERSION).
+import http from "node:http";
+/** Version of the wire rules below; bump with ADAPTER_CONTRACT.md. */
+export const ADAPTER_VERSION = 3;
+/** Default upstream; tests override it with a local fake. */
+export const DEFAULT_UPSTREAM = "https://api.meta.ai";
+/**
+ * Muse Code builtin tool names.
+ *
+ * Reconstructed from the 1.4.14 binary's tool catalog and from `muse exec`
+ * captures, then probed one by one against api.meta.ai on 2026-10-30: a flat
+ * client tool with one of these exact names is refused with 403
+ * `client_attestation_denied`. The catalog includes goal, cron, session and
+ * patch tools as well as the file, shell and web families. `tool_search` is
+ * included defensively: one probe returned 200, but field reports see a 403.
+ */
+export const COLLIDING_TOOL_NAMES = new Set([
+    "workflow",
+    "read_file",
+    "write_file",
+    "edit_file",
+    "bash",
+    "bash_input",
+    "search",
+    "web_search",
+    "web_fetch",
+    "powershell",
+    "powershell_input",
+    "read_memory",
+    "add_memory",
+    "edit_memory",
+    "read_skill",
+    "write_todos",
+    "monitor",
+    "work_status",
+    "work_list",
+    "work_stop",
+    "snooze_reminder",
+    "apply_patch",
+    "shell",
+    "create_goal",
+    "get_goal",
+    "update_goal",
+    "report_progress",
+    "request_user_input",
+    "cron_create",
+    "cron_delete",
+    "cron_list",
+    "send_session_message",
+    "list_peer_sessions",
+    "subagent_send_message",
+    "subagent_cancel",
+    "subagent_spawn",
+    "subagent_status",
+    "subagent_wait",
+    "subagent_read_result",
+    "tool_search",
+]);
+/** Prefix used for aliases; kept outside the builtin set. */
+const ALIAS_PREFIX = "client_";
+/** Requests larger than this are forwarded untransformed (images, huge prompts). */
+const MAX_BODY_BYTES = 32 * 1024 * 1024;
+/** Ports tried in order, so a route's persisted baseURL stays stable. */
+const DEFAULT_PORTS = [43219, 43220, 43221, 43222];
+/** Paths whose JSON body and response are adapted. Everything else is relayed. */
+function isAdaptedPath(pathname) {
+    return pathname.endsWith("/responses") || pathname.endsWith("/chat/completions");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Decide which declared tool names must be aliased.
+ *
+ * Only flat `function` tools are considered: those are the declarations Meta
+ * compares against its builtin set. A namespace container is left untouched.
+ * With `all`, every flat function tool is aliased; the proxy uses that as a
+ * one-shot retry when the gate refuses names this release does not know.
+ */
+export function planToolAliases(tools, options = {}) {
+    const aliases = new Map();
+    if (!Array.isArray(tools))
+        return { aliases, reverse: new Map() };
+    const taken = new Set();
+    for (const tool of tools) {
+        if (isRecord(tool) && typeof tool["name"] === "string")
+            taken.add(tool["name"]);
+    }
+    for (const tool of tools) {
+        if (!isRecord(tool) || tool["type"] !== "function")
+            continue;
+        const name = tool["name"];
+        if (typeof name !== "string")
+            continue;
+        if (options.all !== true && !COLLIDING_TOOL_NAMES.has(name))
+            continue;
+        let alias = `${ALIAS_PREFIX}${name}`;
+        let suffix = 2;
+        while (taken.has(alias)) {
+            alias = `${ALIAS_PREFIX}${name}_${String(suffix)}`;
+            suffix += 1;
+        }
+        taken.add(alias);
+        aliases.set(name, alias);
+    }
+    const reverse = new Map();
+    for (const [original, alias] of aliases)
+        reverse.set(alias, original);
+    return { aliases, reverse };
+}
+/** Rewrite the names of the tools, history calls and forced tool choice. */
+function applyAliases(body, plan) {
+    if (plan.aliases.size === 0)
+        return;
+    const tools = body["tools"];
+    if (Array.isArray(tools)) {
+        body["tools"] = tools.map((tool) => {
+            if (!isRecord(tool) || tool["type"] !== "function")
+                return tool;
+            const name = tool["name"];
+            if (typeof name !== "string")
+                return tool;
+            const alias = plan.aliases.get(name);
+            return alias === undefined ? tool : { ...tool, name: alias };
+        });
+    }
+    const input = body["input"];
+    if (Array.isArray(input)) {
+        body["input"] = input.map((item) => {
+            if (!isRecord(item) || item["type"] !== "function_call")
+                return item;
+            const name = item["name"];
+            if (typeof name !== "string")
+                return item;
+            const alias = plan.aliases.get(name);
+            return alias === undefined ? item : { ...item, name: alias };
+        });
+    }
+    const choice = body["tool_choice"];
+    if (isRecord(choice) && choice["type"] === "function") {
+        const name = choice["name"];
+        if (typeof name === "string") {
+            const alias = plan.aliases.get(name);
+            if (alias !== undefined)
+                body["tool_choice"] = { ...choice, name: alias };
+        }
+    }
+}
+/**
+ * Apply the wire rules to one Responses/Chat request body.
+ *
+ * The input object is not mutated: a shallow copy is returned. Unknown fields
+ * are preserved untouched. Pass a plan from {@link planToolAliases} to reuse a
+ * mapping, for example the full-aliasing retry.
+ */
+export function transformRequestBody(body, plan) {
+    const next = { ...body };
+    const notes = [];
+    const chosen = plan ?? planToolAliases(next["tools"]);
+    if (chosen.aliases.size > 0) {
+        applyAliases(next, chosen);
+        notes.push(`aliased ${String(chosen.aliases.size)} tool name(s)`);
+    }
+    const choice = next["tool_choice"];
+    if (choice !== undefined && choice !== "auto") {
+        // Meta accepts only "auto"; named, "none" and "required" are rejected.
+        next["tool_choice"] = "auto";
+        notes.push("tool_choice=auto");
+    }
+    const effort = next["reasoning_effort"];
+    if (typeof effort === "string") {
+        const reasoning = isRecord(next["reasoning"]) ? next["reasoning"] : {};
+        next["reasoning"] = { ...reasoning, effort: reasoning["effort"] ?? effort };
+        delete next["reasoning_effort"];
+        notes.push("reasoning_effort->reasoning.effort");
+    }
+    const maxOutput = next["max_output_tokens"];
+    if (typeof maxOutput === "number" && maxOutput < 16) {
+        next["max_output_tokens"] = 16;
+        notes.push("max_output_tokens>=16");
+    }
+    const include = Array.isArray(next["include"]) ? next["include"] : [];
+    if (!include.includes("reasoning.encrypted_content")) {
+        next["include"] = [...include, "reasoning.encrypted_content"];
+        notes.push("include+reasoning.encrypted_content");
+    }
+    return { body: next, plan: chosen, notes };
+}
+/** Restore an aliased name on one wire object, in place. */
+function restoreItem(item, reverse) {
+    if (!isRecord(item))
+        return;
+    const type = item["type"];
+    if (type !== "function_call" && type !== "function")
+        return;
+    const name = item["name"];
+    if (typeof name !== "string")
+        return;
+    const original = reverse.get(name);
+    if (original !== undefined)
+        item["name"] = original;
+}
+/**
+ * Streaming name restorer.
+ *
+ * Feeds complete SSE lines and returns the line to relay. It restores aliased
+ * function-call names and repairs empty `arguments` from the streamed deltas:
+ * Meta's authoritative `response.output_item.done` sometimes ships "" even
+ * though the deltas carried the JSON.
+ */
+export class SseRestorer {
+    reverse;
+    arguments = new Map();
+    constructor(reverse) {
+        this.reverse = reverse;
+    }
+    /** Adapt one complete SSE line (without the trailing newline). */
+    feed(line) {
+        const trimmed = line.endsWith("\r") ? line.slice(0, -1) : line;
+        if (!trimmed.startsWith("data:"))
+            return line;
+        const payload = trimmed.slice(5).trim();
+        if (payload === "" || payload === "[DONE]")
+            return line;
+        let event;
+        try {
+            const parsed = JSON.parse(payload);
+            if (!isRecord(parsed))
+                return line;
+            event = parsed;
+        }
+        catch {
+            return line;
+        }
+        this.adapt(event);
+        return `data: ${JSON.stringify(event)}${line.endsWith("\r") ? "\r" : ""}`;
+    }
+    adapt(event) {
+        const type = event["type"];
+        // `response.function_call_arguments.done` echoes the tool name at the top level.
+        const topName = event["name"];
+        if (typeof topName === "string") {
+            const original = this.reverse.get(topName);
+            if (original !== undefined)
+                event["name"] = original;
+        }
+        if (type === "response.function_call_arguments.delta") {
+            const id = event["item_id"];
+            const delta = event["delta"];
+            if (typeof id === "string" && typeof delta === "string") {
+                this.arguments.set(id, (this.arguments.get(id) ?? "") + delta);
+            }
+        }
+        if (type === "response.output_item.added" || type === "response.output_item.done") {
+            const item = event["item"];
+            this.collectArguments(item);
+            restoreItem(item, this.reverse);
+            this.repairArguments(item);
+        }
+        const response = event["response"];
+        if (isRecord(response))
+            this.adaptResponse(response);
+    }
+    /** Restore names in an emitted response object (tools echo and output items). */
+    adaptResponse(response) {
+        const tools = response["tools"];
+        if (Array.isArray(tools)) {
+            for (const tool of tools)
+                restoreItem(tool, this.reverse);
+        }
+        const output = response["output"];
+        if (!Array.isArray(output))
+            return;
+        for (const item of output) {
+            this.collectArguments(item);
+            restoreItem(item, this.reverse);
+            this.repairArguments(item);
+        }
+    }
+    collectArguments(item) {
+        if (!isRecord(item) || item["type"] !== "function_call")
+            return;
+        const id = item["id"];
+        const args = item["arguments"];
+        if (typeof id === "string" && typeof args === "string" && args !== "") {
+            this.arguments.set(id, args);
+        }
+    }
+    repairArguments(item) {
+        if (!isRecord(item) || item["type"] !== "function_call")
+            return;
+        const id = item["id"];
+        if (typeof id !== "string")
+            return;
+        const args = item["arguments"];
+        if (args !== undefined && args !== "")
+            return;
+        const known = this.arguments.get(id);
+        if (known !== undefined && known !== "")
+            item["arguments"] = known;
+    }
+}
+/** Restore aliased names and empty arguments in a complete JSON response. */
+export function transformResponseBody(body, reverse) {
+    const output = body["output"];
+    if (!Array.isArray(output))
+        return body;
+    for (const item of output)
+        restoreItem(item, reverse);
+    return body;
+}
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        request.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("request body too large"));
+                request.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on("end", () => resolve(Buffer.concat(chunks)));
+        request.on("error", reject);
+    });
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                reject(new Error("adapter has no TCP address"));
+                return;
+            }
+            resolve(address.port);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, "127.0.0.1");
+    });
+}
+/** Hop-by-hop headers that must not be forwarded to the upstream origin. */
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+function upstreamHeaders(request) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value === undefined)
+            continue;
+        if (name === "host" || name === "content-length" || name === "accept-encoding")
+            continue;
+        if (HOP_BY_HOP.has(name))
+            continue;
+        if (Array.isArray(value))
+            headers.set(name, value.join(", "));
+        else
+            headers.set(name, value);
+    }
+    headers.set("accept-encoding", "identity");
+    if (!headers.has("x-api-version"))
+        headers.set("x-api-version", "1.0.0");
+    return headers;
+}
+function toNodeHeaders(response) {
+    const headers = {};
+    response.headers.forEach((value, name) => {
+        if (name === "content-length" || name === "content-encoding" || name === "transfer-encoding")
+            return;
+        headers[name] = value;
+    });
+    return headers;
+}
+/**
+ * Start the loopback adapter.
+ *
+ * The server binds 127.0.0.1 only. Requests to the Responses and Chat
+ * completion paths are adapted; every other path is relayed untouched, so
+ * the provider's model discovery keeps working through the same baseURL.
+ */
+export async function startMuseCodeAdapter(options = {}) {
+    const upstream = options.upstream ?? DEFAULT_UPSTREAM;
+    const passthrough = options.passthrough === true;
+    const log = options.log ?? (() => { });
+    const candidates = options.ports ?? DEFAULT_PORTS;
+    let lastError;
+    let server;
+    let port = 0;
+    for (const candidate of [...candidates, 0]) {
+        const attempt = http.createServer();
+        try {
+            port = await listen(attempt, candidate);
+            server = attempt;
+            break;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    if (server === undefined) {
+        throw new Error(`muse-code adapter could not bind a loopback port: ${String(lastError)}`);
+    }
+    const running = server;
+    running.on("request", (request, response) => {
+        void handle(request, response).catch((error) => {
+            log(`muse-code adapter error: ${error instanceof Error ? error.message : String(error)}`);
+            if (!response.headersSent) {
+                response.writeHead(502, { "content-type": "application/json" });
+            }
+            response.end(JSON.stringify({
+                error: {
+                    code: "muse_code_adapter_error",
+                    message: "The local Muse Code adapter could not relay this request.",
+                    type: "server_error",
+                },
+            }));
+        });
+    });
+    async function handle(request, response) {
+        const url = request.url ?? "/";
+        const pathname = url.split("?", 1)[0] ?? "/";
+        const method = request.method ?? "GET";
+        const raw = method === "POST" ? await readBody(request) : Buffer.alloc(0);
+        let body = raw;
+        let reverse = new Map();
+        const notes = [];
+        let parsedBody;
+        if (!passthrough && method === "POST" && isAdaptedPath(pathname) && raw.length > 0) {
+            try {
+                const parsed = JSON.parse(raw.toString("utf8"));
+                if (isRecord(parsed)) {
+                    parsedBody = parsed;
+                    const adapted = transformRequestBody(parsed);
+                    body = Buffer.from(JSON.stringify(adapted.body), "utf8");
+                    reverse = adapted.plan.reverse;
+                    notes.push(...adapted.notes);
+                }
+            }
+            catch {
+                notes.push("body not JSON; relayed as-is");
+            }
+        }
+        const send = (payload) => fetch(`${upstream}${url}`, {
+            method,
+            headers: upstreamHeaders(request),
+            ...(method === "POST" ? { body: payload } : {}),
+        });
+        let upstreamResponse = await send(body);
+        if (!passthrough && parsedBody !== undefined && upstreamResponse.status === 403) {
+            // A refusal can mean a builtin name this release does not know yet:
+            // retry once with every flat function tool aliased, so a new Muse tool
+            // name cannot take the subscription lane down.
+            const probe = await upstreamResponse.clone().text();
+            if (probe.includes("client_attestation_denied")) {
+                const allPlan = planToolAliases(parsedBody["tools"], { all: true });
+                if (allPlan.aliases.size > reverse.size) {
+                    const retry = transformRequestBody(parsedBody, allPlan);
+                    reverse = allPlan.reverse;
+                    notes.push(`gate refused; retried with all ${String(allPlan.aliases.size)} tools aliased`);
+                    upstreamResponse = await send(Buffer.from(JSON.stringify(retry.body), "utf8"));
+                }
+            }
+        }
+        const contentType = upstreamResponse.headers.get("content-type") ?? "";
+        if (notes.length > 0) {
+            log(`muse-code adapter: ${method} ${pathname} ${String(upstreamResponse.status)} | ${notes.join(", ")}`);
+        }
+        if (contentType.includes("text/event-stream") && upstreamResponse.body !== null) {
+            response.writeHead(upstreamResponse.status, toNodeHeaders(upstreamResponse));
+            const restorer = new SseRestorer(reverse);
+            const reader = upstreamResponse.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let index = buffer.indexOf("\n");
+                while (index >= 0) {
+                    const line = buffer.slice(0, index);
+                    buffer = buffer.slice(index + 1);
+                    response.write(`${restorer.feed(line)}\n`);
+                    index = buffer.indexOf("\n");
+                }
+            }
+            if (buffer.length > 0)
+                response.write(restorer.feed(buffer));
+            response.end();
+            return;
+        }
+        const text = await upstreamResponse.text();
+        let payload = text;
+        if (!passthrough && contentType.includes("application/json") && reverse.size > 0) {
+            try {
+                const parsed = JSON.parse(text);
+                if (isRecord(parsed))
+                    payload = JSON.stringify(transformResponseBody(parsed, reverse));
+            }
+            catch {
+                payload = text;
+            }
+        }
+        response.writeHead(upstreamResponse.status, {
+            ...toNodeHeaders(upstreamResponse),
+            "content-length": Buffer.byteLength(payload),
+        });
+        response.end(payload);
+    }
+    return {
+        baseUrl: `http://127.0.0.1:${String(port)}/v1`,
+        port,
+        close: () => new Promise((resolve, reject) => {
+            // The host keeps its sockets alive; do not wait for them to time out.
+            running.closeAllConnections();
+            running.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        }),
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,20 @@
 import type { Plugin } from "@opencode-ai/plugin";
 import { Plugin as V2Plugin } from "@opencode/plugin";
+import { type RunningAdapter } from "./adapter.js";
+/** The part of a running adapter the plugin needs. */
+type AdapterHandle = Pick<RunningAdapter, "baseUrl" | "close">;
+/** Starts the loopback adapter; tests inject a stub instead of binding a port. */
+export type AdapterFactory = () => Promise<AdapterHandle>;
+/** Options for {@link setupV2}; the adapter is a test seam. */
+export interface V2SetupOptions {
+    readonly adapter?: AdapterFactory;
+}
+/**
+ * V2 setup. Returns the cleanup function, which stops the adapter.
+ *
+ * @param options - test seam; production calls setup without options.
+ */
+export declare function setupV2(ctx: V2Plugin.Context, options?: V2SetupOptions): Promise<() => Promise<void>>;
 declare const _default: {
     id: string;
     setup: (context: V2Plugin.Context) => Promise<V2Plugin.Cleanup | void> | V2Plugin.Cleanup | void;

package/dist/index.js

@@ -1,6 +1,9 @@
 import { Plugin as V2Plugin, Integration } from "@opencode/plugin";
+import { DEFAULT_UPSTREAM, startMuseCodeAdapter } from "./adapter.js";
 import { writeCache, deviceAuthorize, pollToken, mintKey, resolveLoaderKey, } from "./auth.js";
 const TEN_YEARS_MS = 10 * 365 * 24 * 60 * 60 * 1000;
+/** Origin of the real Meta inference endpoint; the adapter forwards to it. */
+const META_ORIGIN = new URL(DEFAULT_UPSTREAM).origin;
 /** Keep diagnostics useful without ever copying a credential into a log line. */
 function describeError(error) {
     const text = error instanceof Error ? error.message : String(error);
@@ -25,6 +28,135 @@ async function logAuthFailure(client, error) {
         // Logging must never break the auth flow.
     }
 }
+/** Start the loopback adapter; `off` keeps the proxy but skips the reshaping. */
+function startLocalAdapter() {
+    return startMuseCodeAdapter({ passthrough: process.env["MUSE_CODE_ADAPTER"] === "off" });
+}
+/**
+ * Rewrite one direct Meta request onto the adapter origin.
+ *
+ * Only the origin changes: path, query, method, headers, body and signal are
+ * preserved. A request already targeting the adapter, or any other host, is
+ * returned untouched.
+ */
+function routeThroughAdapter(request, baseUrl) {
+    const url = new URL(request.url);
+    const target = new URL(baseUrl);
+    if (url.origin === target.origin || url.origin !== META_ORIGIN)
+        return request;
+    url.protocol = target.protocol;
+    url.hostname = target.hostname;
+    url.port = target.port;
+    const init = {
+        method: request.method,
+        headers: request.headers,
+        signal: request.signal,
+        redirect: request.redirect,
+    };
+    if (request.method !== "GET" && request.method !== "HEAD" && request.body !== null) {
+        init.body = request.body;
+        init.duplex = "half";
+    }
+    return new Request(url.toString(), init);
+}
+/**
+ * V2 setup. Returns the cleanup function, which stops the adapter.
+ *
+ * @param options - test seam; production calls setup without options.
+ */
+export async function setupV2(ctx, options = {}) {
+    const methodID = Integration.MethodID.make("muse-code-subscription");
+    await ctx.integration.transform((editor) => {
+        editor.method.update({
+            integrationID: "meta",
+            method: {
+                id: methodID,
+                type: "oauth",
+                label: "Muse Code subscription (Meta device login)",
+            },
+            async authorize() {
+                const device = await deviceAuthorize();
+                const url = device.verification_uri_complete || device.verification_uri;
+                const callback = (async () => {
+                    try {
+                        const access = await pollToken(device.device_code, device.interval, device.expires_in);
+                        const minted = await mintKey(access);
+                        return {
+                            type: "oauth",
+                            methodID,
+                            access: minted.apiKey,
+                            refresh: "",
+                            expires: Date.now() + TEN_YEARS_MS,
+                            metadata: { accountId: minted.accountId, ...(minted.email ? { email: minted.email } : {}) },
+                        };
+                    }
+                    catch (error) {
+                        throw new Error(`Muse Code login failed: ${describeError(error)}`);
+                    }
+                })();
+                // The runtime awaits this promise after displaying the device code.
+                // Attach a handler immediately in case the exchange fails first.
+                void callback.catch(() => { });
+                return {
+                    url,
+                    instructions: `Open ${url}\nEnter code: ${device.user_code}`,
+                    mode: "auto",
+                    expiresAt: Date.now() + device.expires_in * 1000,
+                    callback,
+                };
+            },
+            label: (credential) => typeof credential.metadata?.email === "string"
+                ? credential.metadata.email : "Muse Code subscription",
+        });
+    });
+    // Meta's gate inspects the declared tool names, so subscription inference
+    // goes through a loopback proxy that aliases the colliding names and
+    // restores them in the response. Failures keep the pre-adapter behavior.
+    let started;
+    try {
+        started = await (options.adapter ?? startLocalAdapter)();
+    }
+    catch (error) {
+        console.error(`opencode-muse-auth: the local request adapter could not start; ` +
+            `subscription requests will not be reshaped: ${describeError(error)}`);
+    }
+    const adapter = started;
+    async function subscription() {
+        const connection = await ctx.integration.connection.active("meta");
+        if (!connection)
+            return undefined;
+        const credential = await ctx.integration.connection.resolve(connection);
+        if (credential?.type !== "oauth" || credential.methodID !== methodID)
+            return undefined;
+        return credential;
+    }
+    if (adapter) {
+        // Primary mechanism: the provider uses the adapter's /v1 origin as its
+        // request base URL. Native provider drivers honor this override.
+        const baseUrl = adapter.baseUrl;
+        await ctx.session.hook("model.request", async (event) => {
+            if (await subscription())
+                event.baseURL = baseUrl;
+        }, { providerID: "meta" });
+    }
+    // Meta's native provider expects a bearer inference key, not the
+    // short-lived OAuth token used to mint it. Honor the active connection.
+    // AI SDK routes drop model.request.baseURL (opencode#55984), so this hook
+    // also rewrites the assembled request onto the adapter origin.
+    await ctx.session.hook("http.request", async (event) => {
+        const credential = await subscription();
+        if (!credential)
+            return;
+        event.request.headers.set("Authorization", `Bearer ${credential.access}`);
+        if (adapter)
+            event.request = routeThroughAdapter(event.request, adapter.baseUrl);
+    }, { providerID: "meta" });
+    return async () => {
+        await adapter?.close();
+    };
+}
+// V1 has no adapter: its inference keeps going straight to api.meta.ai and
+// still receives Meta's client-restriction 403.
 const MuseCodeAuth = async ({ client }) => {
     return {
         auth: {
@@ -66,63 +198,7 @@ const MuseCodeAuth = async ({ client }) => {
 export default {
     ...V2Plugin.define({
         id: "muse-code-auth",
-        async setup(ctx) {
-            const methodID = Integration.MethodID.make("muse-code-subscription");
-            await ctx.integration.transform((editor) => {
-                editor.method.update({
-                    integrationID: "meta",
-                    method: {
-                        id: methodID,
-                        type: "oauth",
-                        label: "Muse Code subscription (Meta device login)",
-                    },
-                    async authorize() {
-                        const device = await deviceAuthorize();
-                        const url = device.verification_uri_complete || device.verification_uri;
-                        const callback = (async () => {
-                            try {
-                                const access = await pollToken(device.device_code, device.interval, device.expires_in);
-                                const minted = await mintKey(access);
-                                return {
-                                    type: "oauth",
-                                    methodID,
-                                    access: minted.apiKey,
-                                    refresh: "",
-                                    expires: Date.now() + TEN_YEARS_MS,
-                                    metadata: { accountId: minted.accountId, ...(minted.email ? { email: minted.email } : {}) },
-                                };
-                            }
-                            catch (error) {
-                                throw new Error(`Muse Code login failed: ${describeError(error)}`);
-                            }
-                        })();
-                        // The runtime awaits this promise after displaying the device code.
-                        // Attach a handler immediately in case the exchange fails first.
-                        void callback.catch(() => { });
-                        return {
-                            url,
-                            instructions: `Open ${url}\nEnter code: ${device.user_code}`,
-                            mode: "auto",
-                            expiresAt: Date.now() + device.expires_in * 1000,
-                            callback,
-                        };
-                    },
-                    label: (credential) => typeof credential.metadata?.email === "string"
-                        ? credential.metadata.email : "Muse Code subscription",
-                });
-            });
-            // Meta's native provider expects a bearer inference key, not the
-            // short-lived OAuth token used to mint it. Honor the active connection.
-            await ctx.session.hook("http.request", async (event) => {
-                const connection = await ctx.integration.connection.active("meta");
-                if (!connection)
-                    return;
-                const credential = await ctx.integration.connection.resolve(connection);
-                if (credential?.type === "oauth" && credential.methodID === methodID) {
-                    event.request.headers.set("Authorization", `Bearer ${credential.access}`);
-                }
-            }, { providerID: "meta" });
-        },
+        setup: (ctx) => setupV2(ctx),
     }),
     server: MuseCodeAuth,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-muse-auth",
-  "version": "0.4.1",
-  "description": "Unofficial and experimental: Muse Spark in opencode using a Muse Code subscription credential. May conflict with Meta's terms; use at your own risk. See DISCLAIMER.md.",
+  "version": "0.5.0",
+  "description": "Unofficial and experimental: Muse Spark in opencode using a Muse Code subscription credential, with a local loopback adapter for Meta's subscription wire format. May conflict with Meta's terms; use at your own risk. See DISCLAIMER.md.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
@@ -33,7 +33,8 @@
     "LICENSE",
     "NOTICE",
     "DISCLAIMER.md",
-    "AUTH_CONTRACT.md"
+    "AUTH_CONTRACT.md",
+    "ADAPTER_CONTRACT.md"
   ],
   "scripts": {
     "build": "tsc",