@agentvault/muse-bridge 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @agentvault/muse-bridge
+
+Bridges a [Muse](https://dev.meta.ai/) 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 run `muse login` (or set `META_API_KEY`). The bridge
+copies host `~/.config/muse/auth.json` into its fence once, at first run, and
+never overwrites it.
+
+## First enroll
+
+```sh
+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:
+
+```sh
+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).

package/dist/bridge.d.ts

@@ -0,0 +1,83 @@
+/** Muse-owned room/DM wiring. Owner power is two raw booleans from
+ *  `arming_snapshot` (`=== true` only). Do not copy grok grant-trim.
+ *  Do not call decideArming, host-trust, or osIsolated. */
+import type { RoomSession } from "./muse-session.js";
+export declare function workAllowed(): boolean;
+export declare function gatesRemoved(): boolean;
+export declare function resetOwnerPower(): void;
+export interface RoomMessage {
+    roomId: string;
+    senderName: string;
+    plaintext: string;
+    senderIsAgent?: boolean;
+}
+export interface MessageMeta {
+    roomId?: string;
+    ownerDm1to1?: boolean;
+}
+export interface RoomHushed {
+    roomId: string;
+    hushedUntil: string | null;
+}
+export interface ArmingSnapshot {
+    workAllowed?: unknown;
+    gatesRemoved?: unknown;
+}
+export interface RoomChannel {
+    on(ev: "room_message", cb: (e: RoomMessage) => void): unknown;
+    on(ev: "room_joined", cb: (e: {
+        roomId: string;
+        name?: string;
+    }) => void): unknown;
+    on(ev: "message", cb: (text: string, metadata: MessageMeta) => void): unknown;
+    on(ev: "room_hushed", cb: (e: RoomHushed) => void): unknown;
+    on(ev: "arming_snapshot", cb: (e: ArmingSnapshot) => void): unknown;
+    on(ev: "error", cb: (err: unknown) => void): unknown;
+    on(ev: "ready", cb: () => void): unknown;
+    on(ev: "state", cb: (s: string) => void): unknown;
+    sendToRoom(roomId: string, text: string): Promise<void>;
+    send(text: string): Promise<void>;
+}
+export declare class RoomHushState {
+    private until;
+    set(roomId: string, hushedUntilIso: string | null): void;
+    isHushed(roomId: string, now?: number): boolean;
+}
+export type BridgeTarget = {
+    kind: "room";
+    roomId: string;
+} | {
+    kind: "dm";
+};
+export interface ReplyChannel {
+    sendToRoom(roomId: string, text: string): Promise<void>;
+    send(text: string): Promise<void>;
+}
+export declare class ActiveTarget {
+    private target;
+    setRoom(roomId: string): void;
+    setDm(): void;
+    get current(): BridgeTarget | null;
+    snapshotReply(channel: ReplyChannel, log?: (msg: string) => void): (text: string) => Promise<void>;
+}
+export interface LifecycleChannel {
+    on(ev: "auth_failed", cb: (e: {
+        reason: string;
+    }) => void): unknown;
+    on(ev: "session_replaced", cb: (e: {
+        code?: number;
+    }) => void): unknown;
+    on(ev: "error", cb: (err: unknown) => void): unknown;
+}
+export declare function attachLifecycle(channel: LifecycleChannel, opts?: {
+    log?: (msg: string) => void;
+    onTerminal?: (reason: string, o: {
+        restart: boolean;
+    }) => void;
+}): void;
+export declare function roomTurnPrefix(roomId: string, senderName: string, roomName?: string): string;
+export declare function wireBridge(channel: RoomChannel, session: RoomSession, target: ActiveTarget, opts?: {
+    roomFilter?: string;
+    log?: (msg: string) => void;
+}): void;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+export declare function hasPersistedCreds(dataDir: string): boolean;
+export declare function slugify(name: string): string;
+export interface BridgeConfig {
+    inviteToken: string;
+    dataDir: string;
+    agentName: string;
+    /** Per-agent filesystem sandbox. Sibling of dataDir unless AV_WORKSPACE_DIR. */
+    workspaceDir: string;
+    /** Absolute path to the muse binary, or the PATH name "muse". */
+    musePath: string;
+    /** The agent's fenced HOME. Defaults to <dataDir>/fence. This is Muse HOME. */
+    fenceHome: string;
+    /** Meta key forwarded to the muse child as META_API_KEY. Never logged. */
+    apiKey?: string;
+    /** process HOME — seed source for fence auth.json only, never Muse HOME. */
+    hostHome: string;
+    /** Backend API. Same default as grok-bridge. */
+    apiUrl: string;
+}
+export declare const VERSION_FLAGS: readonly ["--version", "-v"];
+export declare const HELP_FLAGS: readonly ["--help", "-h"];
+/** Pure argv read. Independent of loadConfig so `--version` needs no token. */
+export declare function parseInfoFlags(argv: string[]): {
+    showVersion: boolean;
+    showHelp: boolean;
+};
+/**
+ * Package-manager scratch caches. `service/subcommand.ts` bakes `process.argv[1]`
+ * into the launcher, so a service installed from one of these dies when the
+ * cache is pruned.
+ */
+export declare function isEphemeralEntrypoint(entrypoint: string): boolean;
+/** Throw unless `entrypoint` is durable enough to bake into a supervised service. */
+export declare function assertInstallableEntrypoint(entrypoint: string): void;
+export declare function loadConfig(env: NodeJS.ProcessEnv, argv?: string[]): BridgeConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/fence-auth.d.ts

@@ -0,0 +1,14 @@
+export type SeedResult = "seeded" | "already-present" | "no-host-credential";
+/**
+ * Copy the host's Muse credential into the agent's fence, ONCE.
+ *
+ * Copies auth.json alone — never host settings.json, skills, or trust.json.
+ * Never overwrite an existing fence credential (a fenced child refreshes its
+ * own token in place). Never log file contents.
+ */
+export declare function seedFenceCredential(opts: {
+    fenceHome: string;
+    hostHome: string;
+    log?: (m: string) => void;
+}): SeedResult;
+//# sourceMappingURL=fence-auth.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { type BridgeConfig } from "./config.js";
+import { MuseSession } from "./muse-session.js";
+import { MuseDriver, type MuseSpawnFn } from "./muse-driver.js";
+import { type RoomMcpServer } from "./muse-room-http.js";
+import { type LifecycleChannel, type RoomChannel } from "./bridge.js";
+import type { ServiceBackend } from "./service/backend.js";
+export type BootChannel = RoomChannel & LifecycleChannel & {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+};
+export interface MainOpts {
+    env?: NodeJS.ProcessEnv;
+    argv?: string[];
+    spawnFn?: MuseSpawnFn;
+    path?: string;
+    createChannel?: (opts: {
+        inviteToken: string;
+        dataDir: string;
+        apiUrl: string;
+        agentName: string;
+        platform: string;
+        clientVersion: string;
+    }) => BootChannel;
+    exit?: (code: number) => void;
+    backend?: ServiceBackend;
+    entrypoint?: string;
+}
+export interface MainHandle {
+    driver: MuseDriver;
+    session: MuseSession;
+    mcp: RoomMcpServer;
+    cfg: BridgeConfig;
+    shutdown: (code?: number) => Promise<void>;
+    shuttingDown: () => boolean;
+}
+export declare function main(opts?: MainOpts): Promise<MainHandle | undefined>;
+//# sourceMappingURL=index.d.ts.map