@agentvault/grok-bridge 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# @agentvault/grok-bridge
+
+Bridges a Grok agent into E2E-encrypted AgentVault direct messages and rooms.
+
+**This package is a separate entity from `@agentvault/claude-bridge`.** They share
+no runtime code. The only shared dependency is `@agentvault/agentvault`, the
+protocol and crypto library.
+
+## 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.
+
+| File | Copied from `packages/claude-room-bridge` at | Last reviewed |
+|---|---|---|
+| `src/config.ts` | `73a770168a5df33a51f06c8875444f55c9241c07` | `73a770168a5df33a51f06c8875444f55c9241c07` |
+| `src/log.ts` | `9b28a272e87600e78627dbd0f53fcbd192e01e73` | `9b28a272e87600e78627dbd0f53fcbd192e01e73` |
+| `src/bridge.ts` | `f3a7d53f67246e59c471891aee667e002a23b701` | `f3a7d53f67246e59c471891aee667e002a23b701` |
+| `src/service/` | `16c95f46c654a34613aeb2a4ff94eeede9e671ef` | `16c95f46c654a34613aeb2a4ff94eeede9e671ef` |
+
+To review one:
+
+```bash
+git log <last-reviewed-sha>..HEAD -- packages/claude-room-bridge/src/<file>
+```
+
+Triage the diff, port anything that applies, then **move the "Last reviewed" SHA
+forward whether or not you ported anything**. Recording "looked, nothing to port"
+is the point: an unmoved SHA then honestly means nobody looked, instead of being
+indistinguishable from nothing having changed.
+
+⚠️ **Do not port `ActiveTarget.reply()`.** It reads the live target and reopens
+the DM→room leak. It has no production callers on the Claude side either.
+
+## Ship gates — NOT done yet
+
+| Gate | Status |
+|---|---|
+| HTTP MCP loopback on **macOS/Seatbelt** | ✅ **CLOSED 2026-08-15.** `npm run gate:mac` (`src/__tests__/sandbox-gate.mac.test.ts`). Real grok 1.0.4, real sandbox: asserts `ProfileApplied … enforced: true`, `platform: macos/seatbelt`, `restrict_network: true`, **then** that the loopback listener received `tools/list`. Order matters — a sandbox that failed to apply would otherwise report a false pass. Mutation-verified: pointing the plugin at a dead port fails it with `ConnectionRefused`. Authenticates the way production does (seeded `auth.json`), so it needs **no `XAI_API_KEY`** |
+| HTTP MCP loopback on **Linux/Landlock** | ⏸️ **DEFERRED 2026-08-15** — owner call: Mac first, Linux later. Landlock filters TCP connect and may refuse the loopback that Seatbelt allows, so macOS proves nothing about Linux. The test exists (`landlock-gate.linux.test.ts`) and its workflow is **manual dispatch only**; it cannot pass until someone mints an xAI API key and adds it as the `XAI_API_KEY` repo secret. **No such key exists anywhere today** |
+| **CI runs this suite** | ✅ **CLOSED 2026-08-15.** `.github/workflows/grok-bridge-test.yml` runs `vitest` on every PR touching this package. First real run: 172 passed / 3 skipped. The 3 skips are the live + Landlock + macOS gates, all of which need a real grok and are opt-in by env var |
+| **Fenced fail-closed** | ✅ **CLOSED 2026-08-15.** Verified against the real `grok` 1.0.3, fenced, with a seeded `auth.json`: the agent raised `session/request_permission` twice, `Bash` was refused (`stopReason: "cancelled"`, `FENCED_BASH_REACHED` never ran) and `room__say` was allowed. The gate is a real control, not an untested branch. ⚠️ That same run found the gate was **too** closed — see below |
+
+## The fenced-mute bug (2026-08-15)
+
+A blanket `cancelled` on every agent-initiated request made a **fenced agent permanently mute**.
+
+A clean fence loads no permissions, so grok raises `session/request_permission` for *every* tool
+call — including `room__say`, the agent's only voice. The bridge refused it, and the turn ended with
+`stopReason: "cancelled"`, `spoke: false`, and nothing said. The skeleton's entire milestone
+("reply in a 1:1 DM, and `room__say` in a room") was impossible as shipped.
+
+The design spec predicted it verbatim: *"clean fence ⇒ everything asks … the bridge must explicitly
+allow it or the agent goes mute."*
+
+**Why 156 tests missed it.** `FakeAcpChild` never raises a permission request on its own, so
+`onRequest` was only ever exercised by tests that constructed the request themselves — and none did.
+The earlier **unfenced** spike could not see it either: unfenced, grok asks for nothing at all, which
+is exactly why that run looked healthy.
+
+`GrokDriver.onAgentRequest` now allows exactly one tool — `GROK_ROOM_SAY_TOOL_NAME`, imported rather
+than restated so the allowlist cannot drift from the tool actually shipped — by selecting the
+agent's own offered `allow_once` option. Everything else, and any non-permission request, still
+ends the turn. If a future grok stops offering `allow_once`, it refuses rather than inventing an id.
+
+Four tests now cover the branch, using the frame shape captured from the real binary.
+
+## Security notes
+
+- 🔐 **Never run grok with `--debug-file`.** It writes the OAuth bearer token in
+  plaintext. Use `RUST_LOG=xai_grok_shell=trace`.
+- The room MCP URL carries an auth token. `.mcp.json` is written `0600` and the
+  URL is never passed in argv. It is still a credential anywhere it is echoed —
+  traces, crash reports, `lsof`. Treat any diagnostic capture as a secret.
+- Daemon auth is `XAI_API_KEY` in the process env (not baked into the
+  launchd/systemd plist) or a seeded `auth.json` inside the fence.
+- The fence (`HOME` + `GROK_HOME`) is required **even with tools off**. Unfenced,
+  grok loads the operator's entire personal MCP fleet.
+
+## Testing
+
+```bash
+npx vitest run          # the gate — run locally before every commit
+npm run typecheck       # a BASELINE, not a gate. Observed: 2 errors
+```

package/dist/acp-connection.d.ts

@@ -0,0 +1,86 @@
+import type { EventEmitter } from "node:events";
+/** The structural shape both a real ChildProcess and the test fake satisfy. */
+export interface AcpChildLike {
+    stdin: {
+        write(chunk: string): boolean;
+        on?(event: "error", cb: (e: Error) => void): unknown;
+    };
+    stdout: EventEmitter;
+    on(event: "exit", cb: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    /** Present on a real ChildProcess, absent on the test fake. `stop()` uses it
+     *  to actually end the process: disposing the connection alone leaves the
+     *  grok child running (measured 2026-08-15). */
+    kill?(signal?: NodeJS.Signals): unknown;
+}
+export declare class AcpChildDied extends Error {
+    readonly method: string;
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    constructor(method: string, code: number | null, signal: NodeJS.Signals | null);
+}
+export declare class AcpTimeout extends Error {
+    readonly method: string;
+    readonly ms: number;
+    constructor(method: string, ms: number);
+}
+/**
+ * JSON-RPC over a child's stdio. Transport only — it knows nothing about ACP
+ * methods, sessions or Grok.
+ *
+ * stdout is JSON-RPC ONLY on a real grok child (measured: zero parse failures
+ * across every spike run; logs go to stderr), so an unparseable line is a real
+ * anomaly rather than expected noise. It is counted, not silently dropped.
+ */
+export declare class AcpConnection {
+    private readonly child;
+    private nextId;
+    private readonly pending;
+    /** Undecoded leftover. Decode UTF-8 only on complete lines so a 4-byte
+     *  character split across two `data` events cannot become U+FFFD. */
+    private buf;
+    private notify;
+    private handle;
+    private unparseable;
+    private unmatchedResponses;
+    private failedNotifications;
+    private stdinErrors;
+    private disposed;
+    private timedOut;
+    private readonly defaultTimeoutMs;
+    private readonly onData;
+    private death;
+    constructor(child: AcpChildLike, opts?: {
+        defaultTimeoutMs?: number;
+    });
+    timedOutCount(): number;
+    onNotification(cb: (method: string, params: any) => void): void;
+    /** Agent-initiated requests (e.g. session/request_permission). */
+    onRequest(cb: (method: string, params: any) => unknown): void;
+    request<T>(method: string, params: unknown, opts?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Fire-and-forget JSON-RPC notification: no id, no pending entry, no response
+     * expected. Never throws — callers such as a driver's abort() are
+     * contractually non-throwing, and there is no promise to reject.
+     *
+     * Named `sendNotification`, not `notify`: the class already has a private
+     * `notify` field holding the inbound-notification callback registered via
+     * `onNotification()`. A method of the same name is a duplicate class member —
+     * the field silently wins at runtime (esbuild warns, but does not fail the
+     * build) — so this is the outbound counterpart's own name, not a collision.
+     */
+    sendNotification(method: string, params: unknown): void;
+    failedNotificationCount(): number;
+    /** Reject every in-flight request. Called on child death — see Task 3. */
+    failAll(err: Error): void;
+    dispose(): void;
+    unparseableCount(): number;
+    unmatchedResponseCount(): number;
+    stdinErrorCount(): number;
+    private send;
+    private clearPending;
+    private handleData;
+    private dispatch;
+}
+//# sourceMappingURL=acp-connection.d.ts.map

package/dist/agent-driver.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The boundary the Grok bridge drives its model through.
+ *
+ * GROK-INTERNAL. This interface has exactly ONE implementation (`GrokDriver`)
+ * and it is not a shared abstraction: the Claude bridge is a separate entity
+ * with its own session type and MUST NOT be put behind this. An interface that
+ * fits the single implementation it was written against confirms nothing.
+ *
+ * Two properties callers depend on:
+ *  - `start()` is the two-frame ACP HANDSHAKE (`initialize` + `session/new`).
+ *    It is not a run loop, and it resolves before any turn happens.
+ *  - `deliver()` is ONE turn, and it is serialized: it throws if a turn is
+ *    already in flight. `GrokSession` relies on that to route the session-level
+ *    `onSay` to the correct per-message reply sink.
+ */
+export interface TurnResult {
+    /** ACP `stopReason` from the session/prompt RESULT. Never inferred from updates. */
+    stopReason: string;
+    /** Did the agent actually address the conversation? Assistant prose is NOT
+     *  speaking — only a room__say tool call is. These are different bits. */
+    spoke: boolean;
+    /** Assistant prose for this turn, for observe-only paths. */
+    text: string;
+    telemetry?: {
+        modelId?: string;
+        totalTokens?: number;
+        numTurns?: number;
+        apiDurationMs?: number;
+    };
+}
+export interface AgentDriverOpts {
+    /** The agent's ONLY way to address the conversation. */
+    onSay: (text: string) => void | Promise<void>;
+    onTurnEnd?: (result: TurnResult) => void;
+}
+export interface AgentDriver {
+    start(): Promise<void>;
+    deliver(text: string): Promise<TurnResult>;
+    /** Queue timeout / cancellation. Must not throw if nothing is in flight. */
+    abort(): void;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=agent-driver.d.ts.map

package/dist/bridge.d.ts

@@ -0,0 +1,164 @@
+/**
+ * COPIED from packages/claude-room-bridge/src/bridge.ts at
+ * f3a7d53f67246e59c471891aee667e002a23b701, then trimmed.
+ * This file is OWNED by the Grok bridge — edit it freely. It is NOT shared, and
+ * a fix on the Claude side does NOT reach it. See README.md for the port review
+ * process.
+ *
+ * Removed on copy: arming, approvals, audit and the worker tool gate (spec §7).
+ * Those are Claude-shaped; Grok's gate is the pre_tool_use hook and arrives with
+ * the tools-on posture.
+ */
+/** `RoomSession` is declared ONCE in this package, by grok-session.ts. The Claude
+ *  bridge declares its own in its bridge.ts; that declaration was NOT copied.
+ *  Type-only, so this cannot create a runtime import cycle. */
+import type { RoomSession } from "./grok-session.js";
+export interface RoomMessage {
+    roomId: string;
+    senderName: string;
+    plaintext: string;
+    /** True when the sender is another agent (SecureChannel derives this from the
+     *  room roster). Used to decide reply expectation: a human/owner speaking in a
+     *  room always expects a reply; agent-authored traffic does not (the agent may
+     *  stay silent, and it prevents agent↔agent reply loops). Absent on older
+     *  payloads / tests → treated as "not an agent" is NOT assumed: replyExpected is
+     *  set only when we affirmatively know the sender is a human (=== false). */
+    senderIsAgent?: boolean;
+}
+/** Metadata SecureChannel attaches to a 1:1 `message` event. `roomId` is set only
+ *  when the `message` actually originated in a room (handled by room_message), so
+ *  its ABSENCE is how we identify a true owner↔agent 1:1 DM. */
+export interface MessageMeta {
+    roomId?: string;
+    /** #621 — set by SecureChannel when the message decrypted under the owner's
+     *  1:1 material. Gates the plain-text reply fallback; see the `message` handler. */
+    ownerDm1to1?: boolean;
+}
+/** #392 room hush (advisory) — emitted by SecureChannel from the backend's
+ *  `room_hushed` event. ``hushedUntil`` is an ISO string, or null when cleared. */
+export interface RoomHushed {
+    roomId: string;
+    hushedUntil: string | null;
+}
+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: "error", cb: (err: unknown) => void): unknown;
+    /** Fires when the WS (re)opens. */
+    on(ev: "ready", cb: () => void): unknown;
+    /** SecureChannel's connection lifecycle signal. It never emits a bare
+     *  `"close"` — a WS drop is reported as `state` moving to `"disconnected"`
+     *  (or `"error"`), and a completed reconnect as `"ready"` (both the dedicated
+     *  `state` value AND the separate `"ready"` event). */
+    on(ev: "state", cb: (s: string) => void): unknown;
+    sendToRoom(roomId: string, text: string): Promise<void>;
+    send(text: string): Promise<void>;
+}
+/**
+ * #392 cooperative quiet: tracks per-room hush windows so the native agent holds
+ * (does not room_say) while the owner has hushed the room. Advisory — the agent
+ * cooperates; the hard backstops are owner mute / remove (enforced server-side).
+ */
+export declare class RoomHushState {
+    private until;
+    set(roomId: string, hushedUntilIso: string | null): void;
+    isHushed(roomId: string, now?: number): boolean;
+}
+/** Where a reply should go: a room (sendToRoom) or a 1:1 DM (send). */
+export type BridgeTarget = {
+    kind: "room";
+    roomId: string;
+} | {
+    kind: "dm";
+};
+/** Channel surface ActiveTarget needs to route an outbound reply. */
+export interface ReplyChannel {
+    sendToRoom(roomId: string, text: string): Promise<void>;
+    send(text: string): Promise<void>;
+}
+/**
+ * Tracks the destination of the most recent inbound message so a single Grok
+ * session can answer BOTH room traffic and 1:1 owner DMs.
+ *
+ * `current` is deliberately mutable and always points at the NEWEST inbound.
+ * Outbound replies never read it: the bridge calls `snapshotReply()` once per
+ * inbound and hands the resulting closure to the session, which holds it for
+ * that message's whole turn. A room message arriving mid-compose therefore
+ * cannot redirect a private 1:1 reply into the room.
+ *
+ * There is intentionally NO method that sends using the live target. The Claude
+ * bridge still carries one (`reply()`); it has no production callers there and
+ * reopens the leak the moment it is called. Do not port it.
+ */
+export declare class ActiveTarget {
+    private target;
+    setRoom(roomId: string): void;
+    setDm(): void;
+    get current(): BridgeTarget | null;
+    /**
+     * Capture the CURRENT target into an immutable reply closure. This is the leak
+     * fix: a reply built here routes to where its inbound message came from, even if
+     * a later inbound flips the live `current` target. The bridge captures one of
+     * these per inbound (at push time) and hands it to the session, so a room message
+     * arriving mid-compose can never redirect a private 1:1 reply into the room.
+     */
+    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;
+}
+/**
+ * Wire terminal lifecycle events — conditions SecureChannel can't recover from
+ * by reconnecting, after which the daemon would otherwise idle forever. We log
+ * clearly and exit. Three terminal signals:
+ *   - `auth_failed`      — device revoked / JWT expired (needs re-enroll).
+ *   - `session_replaced` — another session took over (close code 4000/4001).
+ *   - `error` matching "Reconnect loop detected" — the one terminal error the
+ *     channel emits AFTER it has given up reconnecting.
+ * All OTHER `error` events are transient (handled + survived by wireBridge's
+ * own `error` listener, #387) and recover via the built-in reconnect — so we
+ * deliberately do NOT exit on the generic `error`/`"error"`-state, which would
+ * regress that survival behavior.
+ */
+export declare function attachLifecycle(channel: LifecycleChannel, opts?: {
+    log?: (msg: string) => void;
+    onTerminal?: (reason: string, o: {
+        restart: boolean;
+    }) => void;
+}): void;
+/**
+ * How a ROOM turn is announced to the model (#366 / #499 Facet A).
+ *
+ * Reproduced live 2026-07-29: asked "what room are you in?" *in* a room, the
+ * agent answered "This is our 1:1 DM, so no room name to report." Everything
+ * beneath the model was correct — the bridge logged `inbound from chris in
+ * c6a2734d` then `said to room c6a2734d`, and the message is recorded against
+ * room "New Test" in the database. The turn was simply pushed as
+ * `[chris]: <text>`, which carries no channel context whatsoever, so the model
+ * had nothing to distinguish a room from a DM and defaulted to DM.
+ *
+ * The room NAME is best-effort (learned from `room_joined`), but the fact that
+ * this is a room is not: when the name is unknown we still say "room" and fall
+ * back to a short id. Getting "which room" wrong is a cosmetic answer; getting
+ * "am I in a room" wrong changes how the agent addresses everyone in it.
+ *
+ * A 1:1 DM is deliberately left unlabelled — that path is not broken, and an
+ * unmarked turn already reads as a DM, which is what the model assumes.
+ */
+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,43 @@
+export declare function hasPersistedCreds(dataDir: string): boolean;
+export declare function slugify(name: string): string;
+export type DataDirSource = "explicit" | "per-agent";
+export declare function resolveDataDir(env: NodeJS.ProcessEnv): {
+    dataDir: string;
+    source: DataDirSource;
+};
+export interface BridgeConfig {
+    inviteToken: string;
+    dataDir: string;
+    dataDirSource: DataDirSource;
+    apiUrl: string;
+    agentName: string;
+    roomFilter?: string;
+    /** Per-agent filesystem sandbox. Always set: auto-defaults to a sibling of
+     *  the key/data dir unless AV_WORKSPACE_DIR overrides it. */
+    workspaceDir: string;
+    /** Absolute path to the grok binary. Optional — `grokSpawnArgs` falls back to
+     *  resolving "grok" from PATH. Set it in production: a launchd daemon's PATH
+     *  normally does NOT contain ~/.grok/bin, so the PATH fallback fails with
+     *  ENOENT on the very first spawn. */
+    grokPath?: string;
+    /** Sandbox profile passed to grok via GROK_SANDBOX. Default "workspace". */
+    sandboxProfile: string;
+    /** The agent's fenced HOME. Defaults to <dataDir>/fence. REQUIRED even with
+     *  tools off: unfenced, grok loads the operator's entire personal MCP fleet
+     *  (measured 2026-08-15 — imessage, twilio-docs, amplitude). */
+    fenceHome: string;
+    /** xAI key forwarded to the grok child as `XAI_API_KEY`. Not baked into the
+     *  launchd/systemd plist — lives in the process env or a seeded auth.json
+     *  inside the fence. */
+    apiKey?: string;
+    /** Agent identity + speaking instructions, prepended to every prompt.
+     *  Overridable via AV_SYSTEM_PROMPT; index.ts supplies a default.
+     *
+     *  RE-ADDED 2026-08-15 after the first live run. An earlier ruling dropped
+     *  this field on the reasoning that the say tool's own description already
+     *  instructs the agent. It does not: given a bare message the model answered
+     *  in prose and never called room__say, so the reply was discarded. */
+    systemPrompt?: string;
+}
+export declare function loadConfig(env: NodeJS.ProcessEnv, argv?: string[]): BridgeConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/fence-auth.d.ts

@@ -0,0 +1,25 @@
+export type SeedResult = "seeded" | "already-present" | "no-host-credential";
+/**
+ * Copy the host's grok OAuth credential into the agent's fence, ONCE.
+ *
+ * The fence deliberately hides `~/.grok`, which is what lets one machine run
+ * several agents without them sharing state. But the onboarding story is
+ * "run `grok login` and it works" — so the bridge has to bring exactly one
+ * file across that boundary.
+ *
+ * ⚠️ NEVER overwrite an existing fence credential. MEASURED 2026-08-15: a
+ * fenced child refreshes its own token and rewrites this file in place (the
+ * expiry moved forward 7h while the host file stayed byte-identical). Copying
+ * on every start would therefore replace a LIVE credential with a stale host
+ * one, and the agent would die at the host token's expiry instead of running
+ * indefinitely.
+ *
+ * Copies auth.json alone — never the rest of ~/.grok, which holds the
+ * operator's own config, sessions and MCP fleet.
+ */
+export declare function seedFenceCredential(opts: {
+    fenceHome: string;
+    hostHome: string;
+    log?: (m: string) => void;
+}): SeedResult;
+//# sourceMappingURL=fence-auth.d.ts.map

package/dist/grok-driver.d.ts

@@ -0,0 +1,65 @@
+import { type AcpChildLike } from "./acp-connection.js";
+import type { AgentDriver, AgentDriverOpts, TurnResult } from "./agent-driver.js";
+export interface GrokDriverOpts extends AgentDriverOpts {
+    cwd: string;
+    /** A turn can legitimately run for minutes while the model thinks. This is
+     *  DELIBERATELY separate from AcpConnection's short handshake default — one
+     *  blanket timeout would kill healthy turns. */
+    turnTimeoutMs?: number;
+}
+/**
+ * Drives `grok agent stdio` over ACP.
+ *
+ * The child is injected rather than spawned here: the spec's acceptance test for
+ * this seam is that the driver can be exercised end-to-end against a fake stdio
+ * child, with no binary, network or credentials.
+ */
+export declare class GrokDriver implements AgentDriver {
+    private readonly child;
+    private readonly opts;
+    private readonly acp;
+    private session;
+    /** State for the turn currently in flight. Null between turns, so a late
+     *  update frame after a turn ends cannot bleed into the next one. */
+    private current;
+    constructor(child: AcpChildLike, opts: GrokDriverOpts);
+    sessionId(): string | null;
+    start(): Promise<void>;
+    deliver(text: string): Promise<TurnResult>;
+    abort(): void;
+    stop(): Promise<void>;
+    /** Called by index.ts HTTP `onSay` (and tests). That is the only production
+     *  writer of `TurnResult.spoke` — constructor `onSay` is an empty stub so
+     *  this method does not double-route the say.
+     *
+     *  `onSay` is typed `void | Promise<void>`, so a plain function that throws
+     *  synchronously is legal to pass in. `Promise.resolve(f())` evaluates `f()`
+     *  first, so wrapping only the rejection case leaves a synchronous throw free
+     *  to propagate straight out of this method. The whole body is wrapped so
+     *  neither failure mode escapes. */
+    noteSaid(text: string): void;
+    /**
+     * Answer an agent-initiated request. Fail-closed with ONE exception: the
+     * agent's own voice.
+     *
+     * MEASURED 2026-08-15 against grok 1.0.3, fenced: a clean fence has no
+     * permissions loaded, so the agent raises `session/request_permission` for
+     * EVERY tool call — including `room__say`. A blanket `cancelled` therefore
+     * made the agent MUTE: it asked to speak, the bridge refused, and the turn
+     * ended with stopReason "cancelled" and spoke=false. The design spec named
+     * this trap exactly — "clean fence ⇒ everything asks … the bridge must
+     * explicitly allow it or the agent goes mute" — and the blanket handler
+     * walked into it. No unit test caught it because the fake child never raises
+     * a permission request of its own, and the UNFENCED spike could not see it
+     * because unfenced grok asks for nothing at all.
+     *
+     * Allowing exactly one tool is not a weakening of the gate. `room__say` is
+     * the agent's only channel to the conversation, it is the capability this
+     * bridge exists to provide, and it is delivered solely through our own
+     * `--plugin-dir` MCP server. Everything else — Bash included, verified in the
+     * same run — still ends the turn.
+     */
+    private onAgentRequest;
+    private onNotification;
+}
+//# sourceMappingURL=grok-driver.d.ts.map

package/dist/grok-room-http.d.ts

@@ -0,0 +1,34 @@
+/** Strip a credential from a log line. Empty secret is a no-op — `split("")`
+ *  would insert the replacement between every character. */
+export declare function redactCredential(text: string, secret: string): string;
+export interface RoomMcpServer {
+    /** JSON-RPC methods this listener has received, in order.
+     *
+     *  Diagnostic only — it changes no behaviour. It exists because "did the
+     *  sandboxed child actually reach this listener?" is otherwise unanswerable
+     *  from outside: a successful `tools/list` is silent, and its absence looks
+     *  identical to an agent that simply had nothing to say. The Landlock gate
+     *  asserts on it. */
+    seenMethods(): string[];
+    /** Full tokened URL to place in .mcp.json. TREAT AS A CREDENTIAL. */
+    url: string;
+    token: string;
+    close(): Promise<void>;
+}
+/**
+ * Serve the room MCP over loopback, IN THIS PROCESS.
+ *
+ * Why HTTP rather than a stdio child: `handleMcpFrame` running in a child means
+ * the say never reaches the driver, so `TurnResult.spoke` is permanently false
+ * (measured 2026-08-15). In-process keeps `onSay` a closure and makes `spoke`
+ * real — which is also what makes the DM auto-reply fallback safe.
+ *
+ * SECURITY. Any local process can reach a loopback port, so the path carries a
+ * random token and a mismatch is refused. The token must never be logged, and
+ * the URL must never be passed in argv (it would be visible in `ps`).
+ */
+export declare function startRoomMcpServer(opts: {
+    onSay: (text: string) => void;
+    log?: (m: string) => void;
+}): Promise<RoomMcpServer>;
+//# sourceMappingURL=grok-room-http.d.ts.map

package/dist/grok-room-mcp.d.ts

@@ -0,0 +1,2 @@
+export declare function handleMcpFrame(frame: any, onSay: (text: string) => void): object | null;
+//# sourceMappingURL=grok-room-mcp.d.ts.map

package/dist/grok-room-plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The tool name as the MODEL sees it: <mcp server key> + "__" + <tool name>.
+ * The MCP server itself receives `say`. Not `mcp__room__say` — that is Claude's
+ * convention and would silently match nothing here.
+ */
+export declare const GROK_ROOM_SAY_TOOL_NAME = "room__say";
+/**
+ * Write a Grok plugin directory exposing exactly one capability.
+ *
+ * Passed via `--plugin-dir`, which is process-scoped and always trusted — so
+ * this never touches the user's ~/.grok/config.toml or the workspace.
+ */
+export declare function writeRoomPlugin(dir: string, mcpCommand: string, mcpArgs: string[]): void;
+/**
+ * Write a plugin dir whose room server is reached over loopback HTTP.
+ *
+ * The URL carries the listener's auth token, so the file is 0600. It must NOT
+ * be passed on a command line — argv is world-readable via `ps`. The token is
+ * still a credential anywhere it is echoed: traces, crash reports, lsof. Treat
+ * any diagnostic capture as a secret.
+ */
+export declare function writeRoomPluginHttp(dir: string, url: string): void;
+//# sourceMappingURL=grok-room-plugin.d.ts.map

package/dist/grok-session.d.ts

@@ -0,0 +1,80 @@
+import type { TurnResult } from "./agent-driver.js";
+/** Grok's OWN copy of the room-session contract. The Claude bridge has its own;
+ *  the two are deliberately unrelated and must not be unified. */
+export interface RoomSession {
+    push(text: string, reply?: (text: string) => Promise<void>, opts?: {
+        autoReplyOnText?: boolean;
+        replyExpected?: boolean;
+    }): void;
+}
+export interface DriverLike {
+    deliver(text: string): Promise<TurnResult>;
+}
+/**
+ * Serializes inbound messages onto the driver and routes the say back.
+ *
+ * THE LEAK THIS CLOSES. The destination is captured PER MESSAGE and held for
+ * the duration of that message's turn. A room message arriving while the agent
+ * is mid-compose on a DM cannot redirect the private reply into the room,
+ * because the newer message only becomes active when its own turn starts.
+ *
+ * This is safe with the driver's single session-level `onSay` because
+ * `deliver()` is serialized — one turn owns `current` at a time.
+ */
+export declare class GrokSession implements RoomSession {
+    private readonly driver;
+    private readonly opts;
+    private queue;
+    private running;
+    /** The message whose turn is in flight, or null between turns. Null is a
+     *  DISTINCT state from "a message that carries no reply sink" — conflating
+     *  them is what let a post-turn say fall through to the session-level sink. */
+    private current;
+    private saidThisTurn;
+    private drain;
+    constructor(driver: DriverLike, opts?: {
+        onSay?: (text: string) => Promise<void>;
+        log?: (m: string) => void;
+        /**
+         * Agent identity + speaking instructions, prepended to EVERY prompt.
+         *
+         * FOUND LIVE 2026-08-15: without this the model receives a bare message
+         * with a `room__say` tool available and no framing that calling it is how
+         * it speaks. It answered in prose and said nothing. The tool's own
+         * description was NOT sufficient — an earlier ruling assumed it would be,
+         * and the first real DM disproved it.
+         *
+         * Prepended per turn rather than sent once, deliberately: a session-level
+         * hook exists (`session/new` `_meta.agentProfile`, measured 2026-08-15 as
+         * applied) but its schema is unverified, and this codebase has already met
+         * three flags that were accepted and silently did nothing. A prompt prefix
+         * cannot fail silently — if it is missing, the prompt is visibly missing
+         * it. Revisit once `_meta.agentProfile` is probed properly.
+         */
+        identity?: string;
+    });
+    push(text: string, reply?: (text: string) => Promise<void>, opts?: {
+        autoReplyOnText?: boolean;
+        replyExpected?: boolean;
+    }): void;
+    /** Hand this to startRoomMcpServer({ onSay }). The behaviour is stable for
+     *  the life of the session — the per-message routing happens HERE, not in
+     *  the listener — but each call returns a NEW closure; do not rely on
+     *  identity (e.g. for `===` comparisons or `removeListener`-style APIs). */
+    sayHandler(): (text: string) => void;
+    /** Resolves when the queue is empty. For tests and shutdown. */
+    idle(): Promise<void>;
+    private log;
+    private run;
+    /**
+     * #416: when the owner expects an answer and the model produced prose but
+     * never called the say tool, send the prose rather than dropping it.
+     *
+     * ONLY SAFE BECAUSE `spoke` IS REAL. Over a stdio MCP child the say never
+     * reaches the driver, so `spoke` is permanently false and this would fire on
+     * every turn — double-posting everything the agent said. It depends on the
+     * in-process HTTP listener.
+     */
+    private maybeFallback;
+}
+//# sourceMappingURL=grok-session.d.ts.map