@agentvault/muse-bridge

Bridges a Muse agent into E2E-encrypted AgentVault direct messages and rooms.

This package is a separate entity from @agentvault/claude-bridge and @agentvault/grok-bridge. They share no runtime code. The child is muse exec --json (JSONL), not ACP.

Prerequisite

Install Muse Code and set META_API_KEY (it always wins). muse login is fine on the host, but Muse 1.0.1 stores that login in the macOS Keychain. The bridge does not copy a keychain-only host auth.json into the fence — that makes the child SecItemAdd and can pop “Keychain Not Found.”

A file providers.meta.api_key is harvested once into <dataDir>/meta-api-key.json (mode 0600) and forwarded as META_API_KEY. It is never written to launchd/systemd.

First enroll

AV_AGENT_NAME=<agent> AV_DATA_DIR="$HOME/.agentvault/muse-room-bridge/<slug>" \
  AV_INVITE_TOKEN=<token> npx @agentvault/muse-bridge

There is no --install flag. That race left other bridges mute; Muse never grew it.

Supervised service (after enroll)

Credentials must already persist (agentvault.json). Then:

npm i -g @agentvault/muse-bridge
AV_AGENT_NAME=<agent> agentvault-muse-bridge install

install refuses an ephemeral npx/dlx entrypoint so launchd cannot bake a pruned cache path.

Owner power

--yolo only when both Access grants are on (workAllowed and gatesRemoved). Otherwise --disable-shell and --disable-write (no terminal, no file-tool writes).

Meta reasoning recovery

Every native Meta Muse turn uses a temporary loopback adapter pinned to Meta's Responses API. It removes opaque reasoning from older settled turns while preserving conversation messages, tool calls/results, settings, and the existing Muse session. Reasoning in the current tool loop stays until Meta rejects that request with the specific encrypted reasoning expiry error. The adapter then retries that provider request once with its remaining reasoning removed; Muse and its tools are not restarted or replayed. Successful SSE responses stream through. Opaque requests using previous_response_id pass through without rewriting.

Removed reasoning cannot contribute its previous private reasoning continuity; the conversation and tool history remain available. The adapter neither edits Muse journals nor rotates session IDs. It binds only to loopback with a fresh secret route and closes at turn end. Diagnostics contain counts and fixed outcomes.

When a reply fails

A failed turn is never silent. Here is what happens, step by step:

1. The bridge records it. It sends one model_turn problem to the agent's Health page (Recent problems), with a code for the cause and the chat it was answering. It also writes one log line: turn_failed code=<code> exit=<exit status or none>. Meta's status number and a short error-type token may follow it. Provider text, request ids and message text never go to the log, the chat or Health.
2. Then it tells the chat. If the turn owed a reply (an owner 1:1, or a room message addressed to this agent), it posts one short sentence in that chat:
   • In your 1:1, the sentence names the cause, such as an expired Meta sign-in.
   • In a room, it is always the plain "couldn't answer this message" sentence. The cause is about your own Meta account, so it stays private on Health. The notice waits at most ten seconds before the next queued turn goes ahead.

The causes this bridge can tell apart today:

A saved session that can't be reopened restarts by itself. Each lane (your own, and the shared one for everyone else) resumes one saved Muse session. When Meta says that session's saved reasoning has expired, the turn would fail every time. Instead, the bridge starts one new session, gives it that chat's recent messages, and answers your message. No notice is sent. The log says turn_recovered code=session_resume_failed lane=<owner|shared>.

• The new id replaces the old one in muse-session-id (or muse-owner-session-id) only after the new session answers.
• The first id it ever replaced is kept in <file>.prev. That file is never overwritten.
• It tries this once per turn. If the new session fails too, you get the notice.
• Your lane is seeded only from your own 1:1 chat. A full-access room turn is not seeded at all, so other members' words never enter your lane. The shared lane is seeded only from the room being answered.

Tip: to find these in the log, search for turn_failed or turn_recovered.

After a restart. If the bridge is stopped or restarted (for example during an update) while it owes a message an answer, nothing replays that message, so the chat gets the plain "Wowzer couldn't answer this message." sentence. It never names a cause, and nothing is recorded under Health, because the model did not fail. The same goes for a message waiting its turn and one that lands while the bridge stops. The log line is turn_cancelled reason=shutdown notice=<sent, failed, timeout or none>, with queued=true or late=true where they apply. notice=none delivered=true means the answer was already on its way, so nothing more is posted. The bridge waits at most 10 seconds for these sentences and 15 seconds for the whole stop.

Copied-from ledger — REVIEW PERIODICALLY

These files were copied once from the Claude bridge and are now owned here. A fix there does NOT reach us.

To review one:

git log <last-reviewed>..HEAD -- packages/claude-room-bridge/src/<file>

Port anything that applies, then move "Last reviewed" forward whether or not you ported anything. An unmoved entry then honestly means nobody looked.