opencode-muse-auth 0.4.0 → 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/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 TheStreamCode
+Copyright (c) 2026 Michael Gasperini (Mikesoft)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,16 +1,26 @@
 # opencode-muse-auth
 
-Use Meta **Muse Spark** in [opencode](https://opencode.ai) billed to your
-**Muse Code monthly subscription** — no pay-as-you-go API key, no third-party CLI.
+Muse Code subscription sign-in for opencode
 
-> **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 Meta may suspend or revoke accounts or
-> credentials. Use it at your own risk; the authors cannot recover an account.
-> Read [DISCLAIMER.md](DISCLAIMER.md) before installing.
+[![CI](https://github.com/TheStreamCode/opencode-muse-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/TheStreamCode/opencode-muse-auth/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![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. 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
+> Meta may suspend or revoke accounts or credentials. Use it at your own risk; the authors cannot
+> recover an account. Read [DISCLAIMER.md](DISCLAIMER.md) before installing.
 
 ## Install
 
+Add the plugin to `opencode.json`; opencode installs it from npm:
+
 ```jsonc
 // opencode.json
 {
@@ -19,64 +29,152 @@ Use Meta **Muse Spark** in [opencode](https://opencode.ai) billed to your
 }
 ```
 
-Then run `/connect` in opencode, pick the `meta` provider and the
-*Muse Code subscription* method: it shows a Meta device page URL and a code.
-Enter the code in your browser (your own Meta account) and the login
-completes by itself.
-
-Verified end-to-end against the published package: isolated project with
-only `"plugins": ["opencode-muse-auth"]`, live chat on `meta/muse-spark-1.3`
-billed to subscription.
+## Sign in
+
+1. Run `/connect` in opencode.
+2. Pick the `meta` provider and the **Muse Code subscription** method.
+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`.
+   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.
+
+## Features
+
+- Registers an `auth` hook for the built-in `meta` provider; there is no separate provider id to
+  configure.
+- Runs the Meta device-code exchange (RFC 8628) inside `/connect`, then mints the subscription
+  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
+  written on this path.
+- Never re-mints on its own; re-run `/connect` only after a 401, because the mint endpoint is
+  aggressively rate-limited.
+- Flow parameters are compatible with the published behavior of oh-my-pi (MIT); see [NOTICE](NOTICE)
+  and [AUTH_CONTRACT.md](AUTH_CONTRACT.md).
 
 ## Requirements
 
-- opencode with plugin support
-- A Meta account with an active Muse Code subscription
-
-## How it works
-
-The plugin registers an `auth` hook for the built-in `meta` provider
-(Routes through the Responses API, `meta.txt` system prompt applies
-automatically to `muse-*` model ids):
-
-- **Login** — Meta device-code exchange (RFC 8628) inside `/connect`, then
-  mints the stable account-bound inference key via the Model API. The key is
-  never printed and the OAuth access token from the login flow is kept in
-  memory only.
-- **V1 storage** — OpenCode's auth store is the primary source; the auth
-  `loader` falls back to the legacy cache
-  (`~/.config/opencode/muse-code-sub.json`) only when the store has no key.
-  The cache is still written so upgrades keep working.
-- **V2 storage** — the credential lives in OpenCode's integration store; the
-  plugin does not write the local cache on this path.
-- **Runtime** — the mint endpoint is aggressively rate-limited, so the plugin
-  never re-mints on its own; re-run `/connect` only if access is revoked (401).
-
-Flow parameters are compatible with the published behavior of oh-my-pi (MIT);
-see [NOTICE](NOTICE) and [AUTH_CONTRACT.md](AUTH_CONTRACT.md).
-
-## Credentials and removal
-
-The inference key is held by OpenCode (V1 auth store or V2 integration store);
-the legacy cache, when present, stores only `apiKey`, `accountId`, and `email`.
-The OAuth access token is never written to disk. To remove access:
-
-- disconnect the provider or log out in OpenCode (this removes the key OpenCode
-  uses; the store is `~/.local/share/opencode/auth.json`);
-- delete `~/.config/opencode/muse-code-sub.json` if it exists from an older
-  version;
+- 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.
+
+## Configuration
+
+| Setting | Purpose | Default |
+| --- | --- | --- |
+| `plugins` entry in `opencode.json` | Loads the plugin. | not set |
+| 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. 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:
+
+- disconnect the provider or log out in opencode (the store is
+  `~/.local/share/opencode/auth.json`);
+- delete `~/.config/opencode/muse-code-sub.json` if an older version created it;
 - run `muse logout` if you also want to clear the Muse Code CLI session;
 - remove `opencode-muse-auth` from `opencode.json`.
 
+## Troubleshooting
+
+### `/connect` shows no Muse Code subscription method
+
+The plugin is not loaded. Check the JSON syntax of `opencode.json`, the plugin name spelling, and
+the package installation, then restart opencode.
+
+### Requests fail with 401 or access was revoked
+
+A 401 may indicate a rotated or revoked key. Re-run `/connect` once; the plugin never re-mints on
+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. 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
+
+Approve the printed code in the browser before the flow expires, then retry. A login rejected by
+Meta usually means the account has no active Muse Code subscription.
+
+### A legacy cache file is still present
+
+It is harmless: the V1 loader prefers the OpenCode auth store and reads the cache only when the
+store has no key. Delete the file if you are migrating to V2 storage.
+
 ## Development
 
-```sh
+Requirements: Node.js 22.6 or newer and npm.
+
+```bash
+git clone https://github.com/TheStreamCode/opencode-muse-auth.git
+cd opencode-muse-auth
 npm install
 npm run build
 npm test
 ```
 
+`npm test` builds with `tsc` and runs the TypeScript test suite with the Node test runner. CI runs
+the same gate on Node.js 22 and 24; Node 22 needs 22.6 or newer for test-runner type stripping.
+No Meta account is needed for the test suite.
+
+## Support
+
+Usage questions and workflows belong in GitHub Discussions; reproducible defects belong in GitHub
+Issues using the bug report form. See [SUPPORT.md](SUPPORT.md). Problems in opencode or Meta
+themselves belong to their respective projects.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests must pass the required CI checks.
+
 ## License
 
-MIT — see [LICENSE](LICENSE). The software is provided "as is"; see
+MIT — see [`LICENSE`](LICENSE). The software is provided "as is"; see
 [DISCLAIMER.md](DISCLAIMER.md) for the risk notice and liability terms.
+
+---
+
+Maintained by [Michael Gasperini (Mikesoft)](https://mikesoft.it).
+If this project is useful to you, consider
+[sponsoring its maintenance](https://github.com/sponsors/TheStreamCode).

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 {};