@spinabot/brigade 1.13.0 → 1.15.0

package/dist/core/server.js

@@ -28,7 +28,9 @@ import { createServer as createTcpServer } from "node:net";
 import { pathToFileURL } from "node:url";
 import { ModelRegistry, } from "@earendil-works/pi-coding-agent";
 import { WebSocketServer } from "ws";
-import { DEFAULT_PORT, isFrame, modelToSummary, TICK_INTERVAL_MS, } from "../protocol.js";
+import { DEFAULT_PORT, EVENT_NAMES, isFrame, modelToSummary, REQUEST_METHODS, TICK_INTERVAL_MS, } from "../protocol.js";
+import { PROTOCOL_VERSION } from "../protocol/handshake.js";
+import { nextSeq } from "../protocol/stream-seq.js";
 // Per-turn execution path (the single canonical runtime). The gateway no
 // longer holds a long-lived Pi session: every inbound `prompt` builds a
 // fresh session via `runResilientTurn`, resumes the JSONL transcript by
@@ -135,6 +137,17 @@ import { mutateConfigAtomic } from "../config/io.js";
 import { acquireGatewayLock } from "./gateway-lock.js";
 import { clearHeartbeatFile, clearPidFile, writeHeartbeatFile, writePidFile } from "./gateway-probe.js";
 import { extractToken, matchesAnyToken, resolveGatewayAuth } from "./gateway-auth.js";
+import { handleConfigGet, handleConfigList, handleConfigSchema, handleConfigSet, handleConfigUnset, handleConfigValidate, } from "./config-ops.js";
+import { handleExecAllow, handleExecAllowPattern, handleExecDenyTest, handleExecList, handleExecRemove, } from "./exec-ops.js";
+import { handleAgentsBind, handleAgentsBindings, handleAgentsUnbind } from "./agents-ops.js";
+import { handlePairingApprove, handlePairingList, handlePairingRevoke } from "./pairing-ops.js";
+import { handleSessionsCleanup } from "./sessions-ops.js";
+import { handleMemoryManage, handleMemoryWrite } from "./memory-ops.js";
+import { handleAgentsAdd, handleAgentsDelete, handleAgentsSetIdentity } from "./agents-crud-ops.js";
+import { handleSkillsCreate, handleSkillsDelete, handleSkillsWriteFile } from "./skills-ops.js";
+import { handleChannelsAllowAdd, handleChannelsAllowList, handleChannelsAllowRemove, handleChannelsConnect, handleChannelsDisconnect, } from "./channels-ops.js";
+import { handleProviderRemove } from "./provider-ops.js";
+import { handleComposio, handleOauth } from "./integrations-ops.js";
 // Persist a model selection to brigade.json's new wizard-shape (the lifted
 // code expected the older flat `defaultProvider`/`defaultModelId` fields).
 // Writes through the same `agents.defaults.{provider, model.primary}` path
@@ -1491,6 +1504,32 @@ async function continueBoot(args) {
     const clientConnIds = new WeakMap();
     const clientAgentSubs = new Map();
     const clientSessionSubs = new Map();
+    /**
+     * Per-session monotonic sequence for the ordered, recoverable stream.
+     * `broadcast` stamps the next value onto every ORDERED frame tagged with a
+     * sessionId (= sessionKey): top-level `pi`, `approval-request`, and
+     * `system-event` (they SHARE one counter per session, so a client detects a
+     * gap in any of them and `resume`s). A client tracks the last seq it saw per
+     * session; a jump means it missed a frame. `resume` returns the current value
+     * as `headSeq`. One int per session — negligible; never pruned so a session's
+     * seq stays monotonic across turns. A gateway restart resets these to 0 — the
+     * client detects that via the `epoch` change on its next `HelloOk` and
+     * invalidates its cursor.
+     */
+    const seqCounters = new Map();
+    /**
+     * Bounded per-session tail of recent `system-event` notices (cron announces /
+     * channel-health), so a client that was disconnected when one fired can still
+     * recover it via `resume`. Oldest-first, capped at RECENT_SYSTEM_EVENTS_MAX.
+     */
+    const recentSystemEvents = new Map();
+    const RECENT_SYSTEM_EVENTS_MAX = 30;
+    /**
+     * Process boot id (session generation / "epoch"). Constant for this gateway
+     * process; a restart yields a new value. Advertised in `HelloOk` so a client
+     * can tell a restart (→ invalidate seq cursors) from a normal reconnect.
+     */
+    const gatewayEpoch = crypto.randomUUID();
     const subscribeAgent = (connId, agentIdValue) => {
         let set = clientAgentSubs.get(connId);
         if (!set) {
@@ -1522,13 +1561,42 @@ async function continueBoot(args) {
     const connWantsFrame = (connId, frameAgentId, frameSessionId) => shouldDeliverFrame(clientAgentSubs.get(connId), clientSessionSubs.get(connId), { agentId: frameAgentId, sessionId: frameSessionId });
     /** Send one event to all connected clients (or a filtered subset). */
     const broadcast = (event, payload) => {
-        const frame = { type: "event", event, payload };
-        const json = JSON.stringify(frame);
         // Untagged payloads broadcast to everyone (state, error, basic log).
         // Tagged payloads (pi, log with agent/session, approval-request,
         // system-event with target) consult the subscription filter so the
         // approval prompt for agent A doesn't pop on operator B's TUI.
         const { agentId: frameAgentId, sessionId: frameSessionId } = extractFrameTags(payload);
+        // Stamp a per-session monotonic seq on the ordered transcript stream
+        // (`pi`). This is the gap detector: a client that sees seq jump knows it
+        // missed a frame and issues `resume`. Only `pi` frames carry seq — they
+        // are the transcript; state/error/log are unordered side-channels a
+        // client never gap-checks. Same `json` goes to every subscriber, so the
+        // seq is shared across all clients watching this session.
+        //
+        // The ordered, recoverable stream = top-level `pi` + `approval-request` +
+        // `system-event`, sharing one per-session counter so a client detects a
+        // gap in ANY of them and `resume`s. EXCLUDED (no seq):
+        //  - sub-agent `pi` frames (subagentDepth>0): they carry the child's own
+        //    session id (a UUID) and live in a separate child transcript the
+        //    parent's `resume` can't backfill — ephemeral nested decoration.
+        //  - `state` (self-healing cumulative snapshot), `error`, `log` (on disk).
+        const subDepth = event === "pi" ? Number(payload.subagentDepth) || 0 : 0;
+        const isOrderedFrame = (event === "pi" && subDepth === 0) ||
+            event === "approval-request" ||
+            event === "system-event";
+        const seq = isOrderedFrame ? nextSeq(seqCounters, frameSessionId) : undefined;
+        // Retain a bounded per-session tail of system-events for `resume` recovery.
+        if (event === "system-event" && frameSessionId) {
+            const ring = recentSystemEvents.get(frameSessionId) ?? [];
+            ring.push(payload);
+            while (ring.length > RECENT_SYSTEM_EVENTS_MAX)
+                ring.shift();
+            recentSystemEvents.set(frameSessionId, ring);
+        }
+        const frame = seq !== undefined
+            ? { type: "event", event, payload, seq }
+            : { type: "event", event, payload };
+        const json = JSON.stringify(frame);
         for (const ws of clients) {
             if (ws.readyState !== ws.OPEN)
                 continue;
@@ -2902,6 +2970,57 @@ async function continueBoot(args) {
             case "get-state": {
                 return buildSnapshot();
             }
+            case "resume": {
+                // Reliable-streaming recovery. Return the session's committed
+                // transcript (the single source of truth — works in BOTH
+                // filesystem + Convex mode via `readSessionTranscriptMessages`)
+                // plus the session's current head seq and the header snapshot.
+                // The client re-materialises from this on (re)connect or a
+                // detected seq gap, then keeps applying live `pi` frames keyed by
+                // identity — so a dropped/reordered frame self-heals. Any
+                // in-flight (not-yet-committed) message is NOT in the transcript
+                // yet; the live `message_update` stream paints it after resume and
+                // the identity-keyed renderer dedupes it on commit. Read-only;
+                // default-pass session guard (the local WS client is the operator).
+                const guardErr = defaultPassSessionGuard(rawParams, "list");
+                if (guardErr)
+                    throw guardErr;
+                const p = (params ?? {});
+                const targetAgentId = p.agentId?.trim() || agentId;
+                const targetSessionKey = p.sessionKey?.trim() || defaultSessionKey(targetAgentId);
+                const messages = await readSessionTranscriptMessages({ sessionKey: targetSessionKey });
+                const headSeq = seqCounters.get(targetSessionKey) ?? 0;
+                // Recovery for the two non-transcript event types so a (re)connecting
+                // client loses NOTHING: tool-approval prompts still pending on this
+                // session (else the turn hangs to auto-deny), and the recent
+                // system-event tail. Pending approvals are filtered to this session.
+                const pendingApprovals = approvalBridge
+                    .listPending()
+                    .filter((a) => a.sessionId === targetSessionKey)
+                    .map((a) => ({
+                    id: a.id,
+                    command: a.command,
+                    toolName: a.toolName,
+                    timeoutMs: a.timeoutMs,
+                    decisions: a.decisions,
+                    ...(a.cwd !== undefined ? { cwd: a.cwd } : {}),
+                    ...(a.subagentLabel !== undefined ? { subagentLabel: a.subagentLabel } : {}),
+                    ...(a.subagentDepth !== undefined ? { subagentDepth: a.subagentDepth } : {}),
+                    ...(a.parentRunId !== undefined ? { parentRunId: a.parentRunId } : {}),
+                    ...(a.agentId !== undefined ? { agentId: a.agentId } : {}),
+                    ...(a.sessionId !== undefined ? { sessionId: a.sessionId } : {}),
+                }));
+                return {
+                    sessionKey: targetSessionKey,
+                    agentId: targetAgentId,
+                    messages: messages,
+                    headSeq,
+                    pendingApprovals,
+                    recentSystemEvents: recentSystemEvents.get(targetSessionKey) ?? [],
+                    epoch: gatewayEpoch,
+                    snapshot: buildSnapshot(targetAgentId),
+                };
+            }
             case "memory-graph": {
                 // Memory Graph dashboard data — nodes + typed edges + topic clusters
                 // + stats, for an agent's workspace. Read; default-pass access guard
@@ -3106,8 +3225,32 @@ async function continueBoot(args) {
         // already enforced regardless, so plugins that declare a scope
         // today won't need a code change when multi-user lands.
         const caller = { id: "local", scopes: ["operator.admin", "operator.write", "operator.read"] };
-        // Send the initial snapshot so the client can render its header
-        // before any user action.
+        // Champion-tier handshake: the FIRST frame is `hello-ok`, handing the
+        // client everything it needs to subscribe without hardcoding — the
+        // protocol version, its connId, the gateway's build version + epoch
+        // (session generation, for restart detection), the full list of callable
+        // methods (core wire methods + registered control-plane RPCs) and
+        // subscribable events, and the policy limits (payload/buffer caps + tick
+        // interval). A client that ignores it still works (the `state` frame
+        // below preserves the legacy boot path).
+        const helloOk = {
+            type: "hello-ok",
+            protocol: PROTOCOL_VERSION,
+            server: { version: getBuildInfo().version, connId, epoch: gatewayEpoch },
+            features: {
+                methods: [...REQUEST_METHODS, ...customMethods.keys()],
+                events: [...EVENT_NAMES],
+            },
+            policy: {
+                maxPayload: MAX_WS_PAYLOAD_BYTES,
+                maxBufferedBytes: MAX_WS_BUFFERED_BYTES,
+                tickIntervalMs: TICK_INTERVAL_MS,
+            },
+            auth: { role: "operator" },
+        };
+        ws.send(JSON.stringify(helloOk));
+        // Then the initial snapshot so the client can render its header before
+        // any user action (also the back-compat boot frame for older clients).
         ws.send(JSON.stringify({ type: "event", event: "state", payload: buildSnapshot() }));
         // Per-connection ring of RPC timestamps powering the sliding-window check.
         const rateRing = [];
@@ -3247,16 +3390,31 @@ async function continueBoot(args) {
         });
     });
     /* ──────────────── tick heartbeat ──────────────── */
-    // Push an empty `state` snapshot every TICK_INTERVAL_MS so clients can
-    // detect a dead server (no frames in 2× this interval = close + reconnect).
-    // Sending the snapshot doubles as keep-alive AND consistency check.
-    //
-    // The tick is also the heartbeat-file beat: refreshing the heartbeat from
-    // inside the event-loop tick proves the loop is healthy. A process whose
-    // loop is starved (deadlock, runaway sync compute, exhausted FDs) misses
-    // the refresh and the external supervisor restarts it.
+    // Send a raw (non-`event`) frame to every open client. Used for the cheap
+    // `tick` keepalive + the graceful `shutdown` notice — each a single tiny
+    // frame, so no backpressure gate (the ping reaper handles a truly dead one).
+    const sendRawToAll = (frame) => {
+        const json = JSON.stringify(frame);
+        for (const ws of clients) {
+            if (ws.readyState !== ws.OPEN)
+                continue;
+            try {
+                ws.send(json);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    };
+    // Emit a cheap `tick` frame every TICK_INTERVAL_MS so clients detect a dead
+    // server (no frames in 2× this interval = close + reconnect). Was a full
+    // `state` snapshot to every binding; a tick is far lighter (battery/bandwidth
+    // on mobile) and `state` is still pushed on every real mutation + on connect,
+    // so idle clients stay consistent. The tick also doubles as the heartbeat-file
+    // beat: refreshing it from inside the event-loop tick proves the loop is
+    // healthy — a starved loop misses it and the supervisor restarts the process.
     const tickTimer = setInterval(() => {
-        broadcastStateAllBindings();
+        sendRawToAll({ type: "tick", ts: Date.now() });
         void writeHeartbeatFile().catch(() => {
             /* best-effort */
         });
@@ -4093,6 +4251,86 @@ async function continueBoot(args) {
     disposeHandlers.push(registerGatewayHandler("org.snapshot", (_params) => handleOrgSnapshot(undefined, {
         loadConfig: () => loadConfig(),
     })));
+    // `config.*` — operator-level config CRUD over the wire (the `brigade
+    // config` CLI, reachable from a remote client). Path/value/redact shape:
+    // never session-targeted, so the guard-sweep correctly needs no per-session
+    // access check. Reads/writes go through the mode-aware loadConfig/saveConfig,
+    // so this works in filesystem AND Convex mode.
+    disposeHandlers.push(registerGatewayHandler("config.get", handleConfigGet));
+    disposeHandlers.push(registerGatewayHandler("config.set", handleConfigSet));
+    disposeHandlers.push(registerGatewayHandler("config.unset", handleConfigUnset));
+    disposeHandlers.push(registerGatewayHandler("config.list", handleConfigList));
+    disposeHandlers.push(registerGatewayHandler("config.schema", handleConfigSchema));
+    disposeHandlers.push(registerGatewayHandler("config.validate", handleConfigValidate));
+    // `exec.*` — operator-level exec-approval allowlist CRUD (the `brigade exec`
+    // CLI over the wire). Per-agent + operator-scoped (the operator manages
+    // their OWN agents' bash-approval allowlist), the same posture as the
+    // allowlisted exec-allow-all / exec-grant-skill RPCs — no per-session guard
+    // (see ALLOWLIST_NO_GUARD_NEEDED in server.guard-sweep.test.ts). The
+    // hard-deny safety net in exec-approvals.ts still applies on every allow.
+    disposeHandlers.push(registerGatewayHandler("exec.list", handleExecList));
+    disposeHandlers.push(registerGatewayHandler("exec.allow", handleExecAllow));
+    disposeHandlers.push(registerGatewayHandler("exec.allow-pattern", handleExecAllowPattern));
+    disposeHandlers.push(registerGatewayHandler("exec.remove", handleExecRemove));
+    disposeHandlers.push(registerGatewayHandler("exec.deny-test", handleExecDenyTest));
+    // `agents.*` — operator-level routing-binding management (which agent owns
+    // which channel/account). The genuine no-other-path gap: agent add/delete/
+    // set-identity are already reachable via the `manage_agent` tool, but
+    // bindings had no remote path. Operator-scoped config mutation, no per-
+    // session guard (allowlisted in server.guard-sweep.test.ts).
+    disposeHandlers.push(registerGatewayHandler("agents.bindings", handleAgentsBindings));
+    disposeHandlers.push(registerGatewayHandler("agents.bind", handleAgentsBind));
+    disposeHandlers.push(registerGatewayHandler("agents.unbind", handleAgentsUnbind));
+    // `pairing.*` — operator-level channel pairing (approve/revoke strangers who
+    // DM the bot). Per-channel + operator-scoped, no per-session guard. The RPCs
+    // require an explicit channel (a client gets the channel list from
+    // system.capabilities), unlike the CLI's single-channel auto-pick.
+    disposeHandlers.push(registerGatewayHandler("pairing.list", handlePairingList));
+    disposeHandlers.push(registerGatewayHandler("pairing.approve", handlePairingApprove));
+    disposeHandlers.push(registerGatewayHandler("pairing.revoke", handlePairingRevoke));
+    // `sessions.cleanup` — operator maintenance: delete an agent's stale idle
+    // transcript files (the gateway regenerates the store entry on next access).
+    // NOT session-content access (unlike sessions.list/history), so no per-
+    // session guard (allowlisted in server.guard-sweep.test.ts).
+    disposeHandlers.push(registerGatewayHandler("sessions.cleanup", handleSessionsCleanup));
+    // `memory.*` — Tideline write + governance (write_memory / manage_memory).
+    // Memory lives in facts.jsonl (NOT config), so config.set can't reach it;
+    // these are the only typed remote path to MUTATE memory (read is covered by
+    // memory-query / memory-graph). Operator-scoped owner origin, no per-session
+    // guard (allowlisted in server.guard-sweep.test.ts).
+    disposeHandlers.push(registerGatewayHandler("memory.write", handleMemoryWrite));
+    disposeHandlers.push(registerGatewayHandler("memory.manage", handleMemoryManage));
+    // agents.add/delete/set-identity — agent CRUD (reuses the manage_agent tool,
+    // which wraps `brigade agents add/delete/set-identity`). Seeds/soft-deletes a
+    // workspace, so config.set alone can't do it. Operator-scoped (allowlisted).
+    disposeHandlers.push(registerGatewayHandler("agents.add", handleAgentsAdd));
+    disposeHandlers.push(registerGatewayHandler("agents.delete", handleAgentsDelete));
+    disposeHandlers.push(registerGatewayHandler("agents.set-identity", handleAgentsSetIdentity));
+    // skills.create/delete/write-file — skill authoring (reuses the manage_skill
+    // tool). SKILL.md files on disk, not config. (status/install/update already
+    // cover read/install/enable.) Operator-scoped (allowlisted).
+    disposeHandlers.push(registerGatewayHandler("skills.create", handleSkillsCreate));
+    disposeHandlers.push(registerGatewayHandler("skills.delete", handleSkillsDelete));
+    disposeHandlers.push(registerGatewayHandler("skills.write-file", handleSkillsWriteFile));
+    // channels.* — LIVE connect/disconnect (runtime adapter via the global
+    // channel manager) + DM allow-from (a per-channel file store, not config).
+    // Channel enable/disable/policy are already config.set-reachable. Operator-
+    // scoped (allowlisted). connect reuses the owner-scoped connect_channel tool.
+    disposeHandlers.push(registerGatewayHandler("channels.connect", handleChannelsConnect));
+    disposeHandlers.push(registerGatewayHandler("channels.disconnect", handleChannelsDisconnect));
+    disposeHandlers.push(registerGatewayHandler("channels.allow-add", handleChannelsAllowAdd));
+    disposeHandlers.push(registerGatewayHandler("channels.allow-remove", handleChannelsAllowRemove));
+    disposeHandlers.push(registerGatewayHandler("channels.allow-list", handleChannelsAllowList));
+    // provider.remove — delete a provider key (auth-profiles.json, not config;
+    // add-provider exists, removal had no gateway path). Operator-scoped.
+    disposeHandlers.push(registerGatewayHandler("provider.remove", handleProviderRemove));
+    // composio + oauth — integrations. `composio` is remote-clean (Composio
+    // hosts the OAuth callback; the gateway hands over a click-link + polls).
+    // `oauth` is the DIY loopback flow (callback on the gateway host — completes
+    // only for a local/tunneled operator; status/token work remotely). Both
+    // reuse the owner-scoped tools. Operator-scoped (allowlisted).
+    disposeHandlers.push(registerGatewayHandler("composio", handleComposio));
+    disposeHandlers.push(registerGatewayHandler("oauth", handleOauth));
     // Wave O0.8 GAP 11 — opt the session inbox into JSONL persistence at
     // gateway boot. The disk write surface defaults off so the existing
     // unit-test fleet (which doesn't tempdir-isolate ~/.brigade) keeps
@@ -4955,6 +5193,15 @@ async function continueBoot(args) {
             catch {
                 /* best-effort */
             }
+            // Tell connected clients we're going down gracefully BEFORE the
+            // sockets close, so a web/mobile UI shows "reconnecting…" and
+            // pre-empts the resume instead of treating the drop as an error.
+            try {
+                sendRawToAll({ type: "shutdown", reason: "gateway shutting down" });
+            }
+            catch {
+                /* best-effort */
+            }
             // Stop the heartbeat runner first so its wake handler unregisters
             // before the rest of the wires unwire — prevents a late wake
             // from firing through a half-torn-down dispatcher.