@ganglion/xacpx-relay 0.11.3 → 0.12.0

package/dist/cli.js

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // packages/relay/src/cli.ts
-import { randomUUID as randomUUID4 } from "node:crypto";
+import { randomUUID as randomUUID5 } from "node:crypto";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname as dirname3, join as join2, resolve } from "node:path";
@@ -140,6 +140,7 @@ function initSchema(db) {
       name TEXT NOT NULL,
       credential_hash TEXT NOT NULL,
       core_version TEXT,
+      capabilities_json TEXT,
       last_seen_at TEXT,
       created_at TEXT NOT NULL
     );
@@ -181,6 +182,10 @@ function initSchema(db) {
   if (!messageCols.some((c) => c.name === "prompt_request_id")) {
     db.exec("ALTER TABLE messages ADD COLUMN prompt_request_id TEXT");
   }
+  const instanceCols = db.all("PRAGMA table_info(instances)");
+  if (!instanceCols.some((c) => c.name === "capabilities_json")) {
+    db.exec("ALTER TABLE instances ADD COLUMN capabilities_json TEXT");
+  }
   db.exec(`
     CREATE INDEX IF NOT EXISTS idx_messages_origin_queue ON messages (instance_id, session_alias, origin_queue_item_id);
     CREATE INDEX IF NOT EXISTS idx_messages_prompt_request ON messages (prompt_request_id);
@@ -452,16 +457,31 @@ class InstanceStore {
       return null;
     return toInstanceRow(row);
   }
-  touch(instanceId, coreVersion) {
+  touch(instanceId, coreVersion, capabilities) {
+    const nowIso = this.now().toISOString();
+    if (capabilities !== undefined && coreVersion !== undefined) {
+      this.db.run("UPDATE instances SET last_seen_at = ?, core_version = ?, capabilities_json = ? WHERE id = ?", [nowIso, coreVersion, JSON.stringify(capabilities), instanceId]);
+      return;
+    }
+    if (capabilities !== undefined) {
+      this.db.run("UPDATE instances SET last_seen_at = ?, capabilities_json = ? WHERE id = ?", [nowIso, JSON.stringify(capabilities), instanceId]);
+      return;
+    }
     if (coreVersion !== undefined) {
       this.db.run("UPDATE instances SET last_seen_at = ?, core_version = ? WHERE id = ?", [
-        this.now().toISOString(),
+        nowIso,
         coreVersion,
         instanceId
       ]);
       return;
     }
-    this.db.run("UPDATE instances SET last_seen_at = ? WHERE id = ?", [this.now().toISOString(), instanceId]);
+    this.db.run("UPDATE instances SET last_seen_at = ? WHERE id = ?", [nowIso, instanceId]);
+  }
+  setCapabilities(instanceId, capabilities) {
+    this.db.run("UPDATE instances SET capabilities_json = ? WHERE id = ?", [
+      JSON.stringify(capabilities),
+      instanceId
+    ]);
   }
   listByAccount(accountId) {
     return this.db.all("SELECT * FROM instances WHERE account_id = ? ORDER BY created_at", [accountId]).map(toInstanceRow);
@@ -489,12 +509,23 @@ class InstanceStore {
     return row?.n ?? 0;
   }
 }
+function parseCapabilitiesJson(raw) {
+  if (raw == null || raw === "")
+    return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+  } catch {
+    return [];
+  }
+}
 function toInstanceRow(row) {
   return {
     id: row.id,
     accountId: row.account_id,
     name: row.name,
     coreVersion: row.core_version,
+    capabilities: parseCapabilitiesJson(row.capabilities_json),
     lastSeenAt: row.last_seen_at,
     createdAt: row.created_at
   };
@@ -650,9 +681,11 @@ class RecoveryReceiptStore {
 import {
   MSG,
   RELAY_PROTOCOL_VERSION,
+  TERMINAL_HUB_REQUEST_TIMEOUT_MS,
   decodeEnvelope,
   encodeEnvelope,
-  errorPayload
+  errorPayload,
+  normalizeCapabilities
 } from "@ganglion/xacpx-relay-protocol";
 
 // packages/relay/src/logging.ts
@@ -736,6 +769,7 @@ function startHeartbeat(socket, intervalMs = HEARTBEAT_INTERVAL_MS, maxMissed =
 // packages/relay/src/gateway/instance-gateway.ts
 var DEFAULT_REQUEST_TIMEOUT_MS = 120000;
 var REQUEST_RESPONSE_RESERVE_MS = 15000;
+var TERMINAL_REQUEST_TIMEOUT_MS = TERMINAL_HUB_REQUEST_TIMEOUT_MS;
 
 class InstanceGateway {
   deps;
@@ -873,7 +907,7 @@ class InstanceGateway {
         result = redeemed;
       }
       respond({ instanceId: result.instanceId, credential: result.credential });
-      this.deps.instances.touch(result.instanceId);
+      this.deps.instances.touch(result.instanceId, payload?.coreVersion, normalizeCapabilities(payload?.capabilities));
       return { instanceId: result.instanceId, accountId: result.accountId };
     }
     if (envelope.type === MSG.instanceAuth) {
@@ -886,7 +920,7 @@ class InstanceGateway {
         return null;
       }
       respond({ ok: true });
-      this.deps.instances.touch(instance.id, payload?.coreVersion);
+      this.deps.instances.touch(instance.id, payload?.coreVersion, normalizeCapabilities(payload?.capabilities));
       return { instanceId: instance.id, accountId: instance.accountId };
     }
     this.logger.info("relay.instance.handshake_failed", "handshake rejected", { reason: "unknown-message-type" });
@@ -912,13 +946,13 @@ class InstanceGateway {
       this.logger.debug("relay.instance.disconnect_failed", "closing revoked instance socket failed", { instanceId, error: String(err) });
     }
   }
-  async sendRequest(instanceId, type, payload) {
+  async sendRequest(instanceId, type, payload, options) {
     const connection = this.connections.get(instanceId);
     if (!connection) {
       throw new Error("instance-offline");
     }
     const id = `relay-${++this.seq}`;
-    const timeoutMs = this.deps.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const timeoutMs = options?.timeoutMs ?? this.deps.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     const requestBudgetMs = Math.max(timeoutMs - REQUEST_RESPONSE_RESERVE_MS, 1);
     const requestDeadlineAt = Date.now() + requestBudgetMs;
     return await new Promise((resolve, reject) => {
@@ -950,14 +984,24 @@ class InstanceGateway {
 }
 
 // packages/relay/src/gateway/web-gateway.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { encodeEnvelope as encodeEnvelope2, webEventEnvelope } from "@ganglion/xacpx-relay-protocol";
 var WS_OPEN = 1;
 var BACKPRESSURE_MAX = 4 * 1024 * 1024;
+function terminalKey(instanceId, terminalId) {
+  return `${instanceId}\x00${terminalId}`;
+}
 
 class WebGateway {
   options;
   byAccount = new Map;
   subscriptions = new Map;
+  viewerBySocket = new Map;
+  accountBySocket = new Map;
+  attachmentsBySocket = new Map;
+  socketByAttachment = new Map;
+  bindingByAttachment = new Map;
+  attachmentsByTerminal = new Map;
   constructor(options = {}) {
     this.options = options;
   }
@@ -965,19 +1009,105 @@ class WebGateway {
     const set = this.byAccount.get(accountId) ?? new Set;
     set.add(socket);
     this.byAccount.set(accountId, set);
+    const viewerId = randomUUID3();
+    this.viewerBySocket.set(socket, viewerId);
+    this.accountBySocket.set(socket, accountId);
+    this.attachmentsBySocket.set(socket, new Set);
     this.options.logger?.debug("relay.web.connected", "web client connected", { accountId });
     startHeartbeat(socket, this.options.heartbeatIntervalMs, undefined, this.options.logger);
     socket.on("close", () => {
+      this.clearSocketAttachments(socket);
       set.delete(socket);
       this.subscriptions.delete(socket);
+      this.viewerBySocket.delete(socket);
+      this.accountBySocket.delete(socket);
+      this.attachmentsBySocket.delete(socket);
       if (set.size === 0)
         this.byAccount.delete(accountId);
       this.options.logger?.debug("relay.web.disconnected", "web client disconnected", { accountId });
     });
+    return viewerId;
+  }
+  getViewerId(socket) {
+    return this.viewerBySocket.get(socket);
   }
   setSubscription(socket, instanceIds) {
     this.subscriptions.set(socket, new Set(instanceIds));
   }
+  bindAttachment(input) {
+    const viewerId = this.viewerBySocket.get(input.socket);
+    if (!viewerId) {
+      throw new Error("socket has no viewerId; register() before bindAttachment");
+    }
+    this.unbindAttachment(input.attachmentId, { notifyDetach: false });
+    const binding = {
+      attachmentId: input.attachmentId,
+      viewerId,
+      terminalId: input.terminalId,
+      instanceId: input.instanceId,
+      socket: input.socket
+    };
+    this.bindingByAttachment.set(input.attachmentId, binding);
+    this.socketByAttachment.set(input.attachmentId, input.socket);
+    const sockSet = this.attachmentsBySocket.get(input.socket) ?? new Set;
+    sockSet.add(input.attachmentId);
+    this.attachmentsBySocket.set(input.socket, sockSet);
+    const tKey = terminalKey(input.instanceId, input.terminalId);
+    const termSet = this.attachmentsByTerminal.get(tKey) ?? new Set;
+    termSet.add(input.attachmentId);
+    this.attachmentsByTerminal.set(tKey, termSet);
+  }
+  unbindAttachment(attachmentId, opts = {}) {
+    const binding = this.bindingByAttachment.get(attachmentId);
+    if (!binding)
+      return;
+    this.bindingByAttachment.delete(attachmentId);
+    this.socketByAttachment.delete(attachmentId);
+    this.attachmentsBySocket.get(binding.socket)?.delete(attachmentId);
+    const tKey = terminalKey(binding.instanceId, binding.terminalId);
+    const termSet = this.attachmentsByTerminal.get(tKey);
+    if (termSet) {
+      termSet.delete(attachmentId);
+      if (termSet.size === 0)
+        this.attachmentsByTerminal.delete(tKey);
+    }
+    if (opts.notifyDetach !== false) {
+      this.options.onAttachmentDetached?.({
+        instanceId: binding.instanceId,
+        attachmentId: binding.attachmentId,
+        viewerId: binding.viewerId
+      });
+    }
+    return binding;
+  }
+  getAttachmentBinding(attachmentId) {
+    return this.bindingByAttachment.get(attachmentId);
+  }
+  socketOwnsAttachment(socket, attachmentId) {
+    return this.socketByAttachment.get(attachmentId) === socket;
+  }
+  sendToAttachment(viewerId, attachmentId, event) {
+    const binding = this.bindingByAttachment.get(attachmentId);
+    if (!binding)
+      return false;
+    if (binding.viewerId !== viewerId)
+      return false;
+    if (this.socketByAttachment.get(attachmentId) !== binding.socket)
+      return false;
+    return this.send(binding.socket, event);
+  }
+  fanoutTerminalExit(instanceId, terminalId, event) {
+    const ids = this.attachmentsByTerminal.get(terminalKey(instanceId, terminalId));
+    if (!ids)
+      return;
+    for (const attachmentId of [...ids]) {
+      const binding = this.bindingByAttachment.get(attachmentId);
+      if (!binding)
+        continue;
+      this.send(binding.socket, event);
+      this.unbindAttachment(attachmentId, { notifyDetach: false });
+    }
+  }
   send(socket, event) {
     return this.sendEncoded(socket, encodeEnvelope2(webEventEnvelope(event)));
   }
@@ -989,6 +1119,7 @@ class WebGateway {
         ...accountId ? { accountId } : {},
         bufferedAmount: socket.bufferedAmount
       });
+      this.clearSocketAttachments(socket);
       try {
         socket.terminate?.();
       } catch {}
@@ -996,11 +1127,17 @@ class WebGateway {
     }
     try {
       socket.send(data);
-      return true;
     } catch (err) {
       this.options.logger?.error("relay.web.broadcast_failed", "web event send failed", { error: String(err) });
       return false;
     }
+    return true;
+  }
+  clearSocketAttachments(socket) {
+    const ids = [...this.attachmentsBySocket.get(socket) ?? []];
+    for (const attachmentId of ids) {
+      this.unbindAttachment(attachmentId, { notifyDetach: true });
+    }
   }
   broadcast(accountId, event) {
     const set = this.byAccount.get(accountId);
@@ -1020,8 +1157,38 @@ class WebGateway {
 }
 
 // packages/relay/src/gateway/web-inbound.ts
-import { decodeEnvelope as decodeEnvelope2, MSG as MSG2, parseWebClientMessage } from "@ganglion/xacpx-relay-protocol";
+import {
+  decodeEnvelope as decodeEnvelope2,
+  isErrorPayload,
+  MSG as MSG2,
+  parseTerminalEventPayload,
+  parseWebClientMessage
+} from "@ganglion/xacpx-relay-protocol";
+function fail(deps, socket, requestId, instanceId, code, message) {
+  deps.webGateway.send(socket, {
+    kind: "terminal-request-failed",
+    requestId,
+    instanceId,
+    code,
+    message
+  });
+}
+function mapConnectorError(err) {
+  if (err instanceof Error) {
+    if (err.message === "instance-offline" || err.message === "instance-reconnected") {
+      return { code: "instance-offline", message: err.message };
+    }
+    if (err.message === "timeout") {
+      return { code: "terminal-timeout", message: "terminal request timed out" };
+    }
+    return { code: "terminal-protocol-error", message: err.message };
+  }
+  return { code: "terminal-protocol-error", message: String(err) };
+}
 function handleWebClientMessage(deps, accountId, socket, raw) {
+  handleWebClientMessageAsync(deps, accountId, socket, raw);
+}
+async function handleWebClientMessageAsync(deps, accountId, socket, raw) {
   const decoded = decodeEnvelope2(raw);
   if (!decoded.ok)
     return;
@@ -1033,26 +1200,373 @@ function handleWebClientMessage(deps, accountId, socket, raw) {
     const instanceIds = [...new Set(msg.instanceIds)].filter((id) => ownedIds.has(id));
     deps.webGateway.setSubscription(socket, instanceIds);
     for (const instanceId of instanceIds) {
-      deps.webGateway.send(socket, { kind: "state-snapshot", instanceId, ...deps.stateSnapshot(instanceId) });
+      deps.webGateway.send(socket, {
+        kind: "state-snapshot",
+        instanceId,
+        ...deps.stateSnapshot(instanceId)
+      });
     }
     return;
   }
   if (!deps.instances.getOwned(msg.instanceId, accountId))
     return;
-  if (msg.kind === "terminal-input")
-    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalInput, { terminalId: msg.terminalId, data: msg.data });
-  else if (msg.kind === "terminal-resize")
-    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalResize, { terminalId: msg.terminalId, cols: msg.cols, rows: msg.rows });
-  else if (msg.kind === "terminal-close")
+  if (msg.kind === "terminal-open") {
+    await handleTerminalOpen(deps, accountId, socket, msg);
+    return;
+  }
+  if (msg.kind === "terminal-stream-start") {
+    const viewerId = deps.webGateway.getViewerId(socket);
+    if (!viewerId || !deps.webGateway.socketOwnsAttachment(socket, msg.attachmentId))
+      return;
+    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalStreamStart, {
+      attachmentId: msg.attachmentId,
+      viewerId
+    });
+    return;
+  }
+  if (msg.kind === "terminal-take-control") {
+    await handleTakeControl(deps, socket, msg);
+    return;
+  }
+  if (msg.kind === "terminal-resync") {
+    await handleResync(deps, socket, msg);
+    return;
+  }
+  if (msg.kind === "terminal-terminate") {
+    await handleTerminate(deps, socket, msg);
+    return;
+  }
+  if (msg.kind === "terminal-input" && "attachmentId" in msg) {
+    const viewerId = deps.webGateway.getViewerId(socket);
+    if (!viewerId || !deps.webGateway.socketOwnsAttachment(socket, msg.attachmentId))
+      return;
+    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalInput, {
+      attachmentId: msg.attachmentId,
+      generation: msg.generation,
+      viewerId,
+      dataBase64: msg.dataBase64
+    });
+    return;
+  }
+  if (msg.kind === "terminal-resize" && "attachmentId" in msg) {
+    const viewerId = deps.webGateway.getViewerId(socket);
+    if (!viewerId || !deps.webGateway.socketOwnsAttachment(socket, msg.attachmentId))
+      return;
+    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalResize, {
+      attachmentId: msg.attachmentId,
+      generation: msg.generation,
+      viewerId,
+      cols: msg.cols,
+      rows: msg.rows
+    });
+    return;
+  }
+  if (msg.kind === "terminal-heartbeat") {
+    const viewerId = deps.webGateway.getViewerId(socket);
+    if (!viewerId || !deps.webGateway.socketOwnsAttachment(socket, msg.attachmentId))
+      return;
+    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalHeartbeat, {
+      attachmentId: msg.attachmentId,
+      viewerId
+    });
+    return;
+  }
+  if (msg.kind === "terminal-detach") {
+    if (!deps.webGateway.socketOwnsAttachment(socket, msg.attachmentId))
+      return;
+    const binding = deps.webGateway.unbindAttachment(msg.attachmentId);
+    if (binding) {
+      deps.gateway.sendEvent(msg.instanceId, MSG2.terminalDetach, {
+        attachmentId: msg.attachmentId,
+        viewerId: binding.viewerId
+      });
+    }
+    return;
+  }
+  if (msg.kind === "terminal-input" && "terminalId" in msg) {
+    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalInput, {
+      terminalId: msg.terminalId,
+      data: msg.data
+    });
+  } else if (msg.kind === "terminal-resize" && "terminalId" in msg) {
+    deps.gateway.sendEvent(msg.instanceId, MSG2.terminalResize, {
+      terminalId: msg.terminalId,
+      cols: msg.cols,
+      rows: msg.rows
+    });
+  } else if (msg.kind === "terminal-close") {
     deps.gateway.sendEvent(msg.instanceId, MSG2.terminalClose, { terminalId: msg.terminalId });
+  }
+}
+async function handleTerminalOpen(deps, accountId, socket, msg) {
+  const viewerId = deps.webGateway.getViewerId(socket);
+  if (!viewerId) {
+    fail(deps, socket, msg.requestId, msg.instanceId, "terminal-protocol-error", "missing viewer identity");
+    return;
+  }
+  if (!deps.gateway.isOnline(msg.instanceId)) {
+    fail(deps, socket, msg.requestId, msg.instanceId, "instance-offline", "instance is offline");
+    return;
+  }
+  let payload;
+  try {
+    payload = await deps.gateway.sendRequest(msg.instanceId, MSG2.terminalOpen, {
+      chatKey: `relay:${accountId}`,
+      sessionAlias: msg.sessionAlias,
+      viewerId,
+      cols: msg.cols,
+      rows: msg.rows
+    }, { timeoutMs: TERMINAL_REQUEST_TIMEOUT_MS });
+  } catch (err) {
+    const mapped = mapConnectorError(err);
+    fail(deps, socket, msg.requestId, msg.instanceId, mapped.code, mapped.message);
+    return;
+  }
+  if (isErrorPayload(payload)) {
+    fail(deps, socket, msg.requestId, msg.instanceId, payload.error.code, payload.error.message);
+    return;
+  }
+  const result = payload;
+  if (!result || typeof result.terminalId !== "string" || typeof result.generation !== "string" || typeof result.attachmentId !== "string") {
+    fail(deps, socket, msg.requestId, msg.instanceId, "terminal-protocol-error", "malformed open result");
+    return;
+  }
+  if (deps.webGateway.getViewerId(socket) !== viewerId) {
+    detachConnectorAttachment(deps, msg.instanceId, result.attachmentId, viewerId);
+    fail(deps, socket, msg.requestId, msg.instanceId, "terminal-unavailable", "viewer disconnected");
+    return;
+  }
+  try {
+    deps.webGateway.bindAttachment({
+      socket,
+      attachmentId: result.attachmentId,
+      terminalId: result.terminalId,
+      instanceId: msg.instanceId
+    });
+  } catch {
+    detachConnectorAttachment(deps, msg.instanceId, result.attachmentId, viewerId);
+    fail(deps, socket, msg.requestId, msg.instanceId, "terminal-unavailable", "viewer disconnected");
+    return;
+  }
+  const sent = deps.webGateway.send(socket, {
+    kind: "terminal-opened",
+    requestId: msg.requestId,
+    instanceId: msg.instanceId,
+    terminalId: result.terminalId,
+    generation: result.generation,
+    attachmentId: result.attachmentId,
+    role: result.role,
+    viewerCount: result.viewerCount
+  });
+  if (!sent) {
+    deps.webGateway.unbindAttachment(result.attachmentId);
+    detachConnectorAttachment(deps, msg.instanceId, result.attachmentId, viewerId);
+  }
+}
+function detachConnectorAttachment(deps, instanceId, attachmentId, viewerId) {
+  deps.gateway.sendEvent(instanceId, MSG2.terminalDetach, {
+    attachmentId,
+    viewerId
+  });
+}
+async function handleTakeControl(deps, socket, msg) {
+  const viewerId = deps.webGateway.getViewerId(socket);
+  if (!viewerId || !deps.webGateway.socketOwnsAttachment(socket, msg.attachmentId)) {
+    fail(deps, socket, msg.requestId, msg.instanceId, "terminal-attachment-not-found", "attachment not bound");
+    return;
+  }
+  try {
+    const payload = await deps.gateway.sendRequest(msg.instanceId, MSG2.terminalTakeControl, { attachmentId: msg.attachmentId, generation: msg.generation, viewerId }, { timeoutMs: TERMINAL_REQUEST_TIMEOUT_MS });
+    if (isErrorPayload(payload)) {
+      fail(deps, socket, msg.requestId, msg.instanceId, payload.error.code, payload.error.message);
+      return;
+    }
+    const result = payload;
+    deps.webGateway.send(socket, {
+      kind: "terminal-opened",
+      requestId: msg.requestId,
+      instanceId: msg.instanceId,
+      terminalId: result.terminalId,
+      generation: result.generation,
+      attachmentId: result.attachmentId,
+      role: result.role,
+      viewerCount: result.viewerCount
+    });
+  } catch (err) {
+    const mapped = mapConnectorError(err);
+    fail(deps, socket, msg.requestId, msg.instanceId, mapped.code, mapped.message);
+  }
+}
+async function handleResync(deps, socket, msg) {
+  const viewerId = deps.webGateway.getViewerId(socket);
+  if (!viewerId || !deps.webGateway.socketOwnsAttachment(socket, msg.attachmentId)) {
+    fail(deps, socket, msg.requestId, msg.instanceId, "terminal-attachment-not-found", "attachment not bound");
+    return;
+  }
+  try {
+    const payload = await deps.gateway.sendRequest(msg.instanceId, MSG2.terminalResync, { attachmentId: msg.attachmentId, generation: msg.generation, viewerId }, { timeoutMs: TERMINAL_REQUEST_TIMEOUT_MS });
+    if (isErrorPayload(payload)) {
+      fail(deps, socket, msg.requestId, msg.instanceId, payload.error.code, payload.error.message);
+      return;
+    }
+    deps.webGateway.send(socket, {
+      kind: "terminal-request-failed",
+      requestId: msg.requestId,
+      instanceId: msg.instanceId,
+      code: "ok",
+      message: "resync-accepted"
+    });
+  } catch (err) {
+    const mapped = mapConnectorError(err);
+    fail(deps, socket, msg.requestId, msg.instanceId, mapped.code, mapped.message);
+  }
+}
+async function handleTerminate(deps, socket, msg) {
+  try {
+    const payload = await deps.gateway.sendRequest(msg.instanceId, MSG2.terminalTerminate, { terminalId: msg.terminalId, generation: msg.generation }, { timeoutMs: TERMINAL_REQUEST_TIMEOUT_MS });
+    if (isErrorPayload(payload)) {
+      fail(deps, socket, msg.requestId, msg.instanceId, payload.error.code, payload.error.message);
+      return;
+    }
+    const result = payload;
+    deps.webGateway.send(socket, {
+      kind: "terminal-exit",
+      instanceId: msg.instanceId,
+      terminalId: msg.terminalId,
+      generation: msg.generation,
+      reason: result.status === "cleanup-pending" ? "cleanup-pending" : "terminated"
+    });
+    deps.webGateway.send(socket, {
+      kind: "terminal-request-failed",
+      requestId: msg.requestId,
+      instanceId: msg.instanceId,
+      code: result.status,
+      message: result.status
+    });
+  } catch (err) {
+    const mapped = mapConnectorError(err);
+    fail(deps, socket, msg.requestId, msg.instanceId, mapped.code, mapped.message);
+  }
+}
+function handleConnectorTerminalEvent(webGateway, instanceId, envelopeType, payload) {
+  if (envelopeType === MSG2.terminalViewerEvent) {
+    const parsed = parseTerminalEventPayload(MSG2.terminalViewerEvent, payload);
+    if (!parsed)
+      return true;
+    const p = parsed;
+    if (!p?.viewerId || !p?.attachmentId || !p?.event)
+      return true;
+    const inner = p.event;
+    let event = null;
+    switch (inner.kind) {
+      case "terminal-rebase-start":
+        event = {
+          kind: "terminal-rebase-start",
+          instanceId,
+          attachmentId: p.attachmentId,
+          generation: inner.generation,
+          epoch: inner.epoch,
+          nextSequence: inner.nextSequence,
+          cols: inner.cols,
+          rows: inner.rows,
+          alternate: inner.alternate,
+          totalBytes: inner.totalBytes,
+          chunkCount: inner.chunkCount
+        };
+        break;
+      case "terminal-rebase-chunk":
+        event = {
+          kind: "terminal-rebase-chunk",
+          instanceId,
+          attachmentId: p.attachmentId,
+          generation: inner.generation,
+          epoch: inner.epoch,
+          index: inner.index,
+          dataBase64: inner.dataBase64
+        };
+        break;
+      case "terminal-rebase-end":
+        event = {
+          kind: "terminal-rebase-end",
+          instanceId,
+          attachmentId: p.attachmentId,
+          generation: inner.generation,
+          epoch: inner.epoch
+        };
+        break;
+      case "terminal-bytes":
+        event = {
+          kind: "terminal-bytes",
+          instanceId,
+          attachmentId: p.attachmentId,
+          generation: inner.generation,
+          epoch: inner.epoch,
+          sequence: inner.sequence,
+          dataBase64: inner.dataBase64
+        };
+        break;
+      case "terminal-role-changed":
+        event = {
+          kind: "terminal-role-changed",
+          instanceId,
+          attachmentId: p.attachmentId,
+          terminalId: inner.terminalId,
+          role: inner.role,
+          viewerCount: inner.viewerCount
+        };
+        break;
+      case "terminal-request-failed":
+        event = {
+          kind: "terminal-request-failed",
+          requestId: inner.requestId ?? "",
+          instanceId,
+          code: inner.code,
+          message: inner.message
+        };
+        break;
+      case "terminal-recovery-failed":
+        event = {
+          kind: "terminal-recovery-failed",
+          instanceId,
+          attachmentId: p.attachmentId,
+          generation: inner.generation,
+          code: inner.code,
+          message: inner.message
+        };
+        break;
+      default:
+        return true;
+    }
+    if (event)
+      webGateway.sendToAttachment(p.viewerId, p.attachmentId, event);
+    return true;
+  }
+  if (envelopeType === MSG2.terminalResourceExit) {
+    const parsed = parseTerminalEventPayload(MSG2.terminalResourceExit, payload);
+    if (!parsed)
+      return true;
+    const p = parsed;
+    if (!p?.terminalId || !p?.generation)
+      return true;
+    webGateway.fanoutTerminalExit(instanceId, p.terminalId, {
+      kind: "terminal-exit",
+      instanceId,
+      terminalId: p.terminalId,
+      generation: p.generation,
+      reason: p.reason,
+      ...p.code !== undefined ? { code: p.code } : {}
+    });
+    return true;
+  }
+  return false;
 }
 
 // packages/relay/src/http/app.ts
 import { Hono } from "hono";
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import { serveStatic } from "@hono/node-server/serve-static";
-import { randomUUID as randomUUID3 } from "node:crypto";
-import { isErrorPayload, MSG as MSG3, parseControlPayload } from "@ganglion/xacpx-relay-protocol";
+import { randomUUID as randomUUID4 } from "node:crypto";
+import { isErrorPayload as isErrorPayload2, MSG as MSG3, parseControlPayload } from "@ganglion/xacpx-relay-protocol";
 
 // packages/relay/src/http/client-ip.ts
 import { getConnInfo } from "@hono/node-server/conninfo";
@@ -1583,7 +2097,7 @@ function createApp(deps) {
               ...previewUrl ? { previewUrl } : {}
             };
           });
-          const promptRequestId = randomUUID3();
+          const promptRequestId = randomUUID4();
           persistedPromptId = deps.messages.append(instance.id, p.sessionAlias, "in", p.text, undefined, attachments, promptRequestId);
           if (body.type === MSG3.prompt && typeof payload === "object" && payload !== null) {
             payload.promptRequestId = promptRequestId;
@@ -1599,7 +2113,7 @@ function createApp(deps) {
           queueItemId: result.queueItemId
         });
       }
-      if (removeInput && !isErrorPayload(result)) {
+      if (removeInput && !isErrorPayload2(result)) {
         deps.messages.deleteBySession(instance.id, removeInput.alias);
       }
       if (body.type === MSG3.commandExecute) {
@@ -1733,7 +2247,16 @@ async function createRelayRuntime(dbPath, options = {}) {
   const accounts = new AccountStore(db);
   const instances = new InstanceStore(db);
   const messages = new MessageStore(db);
-  const webGateway = new WebGateway({ logger });
+  let gatewayRef = null;
+  const webGateway = new WebGateway({
+    logger,
+    onAttachmentDetached: (info) => {
+      gatewayRef?.sendEvent(info.instanceId, MSG4.terminalDetach, {
+        attachmentId: info.attachmentId,
+        viewerId: info.viewerId
+      });
+    }
+  });
   const turnBuffers = new Map;
   const key = (instanceId, alias) => `${instanceId}\x00${alias}`;
   const recoveredFingerprints = new Set;
@@ -1832,6 +2355,9 @@ async function createRelayRuntime(dbPath, options = {}) {
       webGateway.broadcast(accountId, { kind: "instance-status", instanceId, online });
     },
     onEvent: (instanceId, accountId, envelope) => {
+      if (handleConnectorTerminalEvent(webGateway, instanceId, envelope.type, envelope.payload)) {
+        return;
+      }
       const recentRows = (sessionAlias) => messages.listBySession(accountId, instanceId, sessionAlias, { limit: 5 }).messages;
       const hasTrailingPrompt = (sessionAlias, prompt) => {
         const rows = recentRows(sessionAlias);
@@ -2086,6 +2612,7 @@ async function createRelayRuntime(dbPath, options = {}) {
       }
     }
   });
+  gatewayRef = gateway;
   const app = createApp({
     accounts,
     instances,
@@ -2329,7 +2856,7 @@ async function runRelayCli(args, io) {
     const label = flag(args, "--label");
     const runtime = await createRelayRuntime(dbPath);
     try {
-      const username = "u-" + randomUUID4();
+      const username = "u-" + randomUUID5();
       const acc = runtime.accounts.createAccount(username);
       const { token } = runtime.accounts.createLoginToken(acc.id, label);
       io.print(`access token: ${token}`);