chainlesschain 0.162.147 → 0.162.149

package/src/gateways/ws/message-dispatcher.js

@@ -7,6 +7,61 @@ import {
   PERSONAL_DATA_HUB_HANDLERS,
   PERSONAL_DATA_HUB_STREAMING_HANDLERS,
 } from "./personal-data-hub-protocol.js";
+import {
+  handleRemoteSessionAudit,
+  handleRemoteSessionCreate,
+  handleRemoteSessionClose,
+  handleRemoteSessionDevices,
+  handleRemoteSessionJoin,
+  handleRemoteSessionPairingToken,
+  handleRemoteSessionPolicy,
+  handleRemoteSessionPublish,
+  handleRemoteSessionPushRegister,
+  handleRemoteSessionRevoke,
+} from "./remote-session-protocol.js";
+
+/**
+ * Reconnect-safe command execution. When a message carries a stable
+ * `commandId`, route it through the server's RemoteCommandLedger so the side
+ * effect runs AT MOST ONCE: a client that re-sends the same command after a
+ * dropped ACK / reconnect gets a `replayed` ack instead of a second execution
+ * (Phase 5 acceptance "断网恢复后不会重复执行工具调用"). Messages WITHOUT a
+ * commandId are unchanged — they call `_executeCommand` directly, so existing
+ * clients behave exactly as before. A revoked device / stale-seq command is
+ * rejected without executing.
+ */
+async function executeWithIdempotency(server, id, ws, message, stream) {
+  const commandId = message.commandId;
+  if (!commandId) {
+    return server._executeCommand(id, ws, message.command, stream);
+  }
+  if (!server._commandLedger) {
+    const { RemoteCommandLedger } =
+      await import("../../harness/remote-command-ledger.js");
+    server._commandLedger = new RemoteCommandLedger();
+  }
+  const outcome = await server._commandLedger.apply(
+    { commandId, deviceId: message.deviceId ?? null, seq: message.seq },
+    () => server._executeCommand(id, ws, message.command, stream),
+  );
+  if (outcome.status === "replayed") {
+    server._send(ws, {
+      id,
+      type: "replayed",
+      commandId,
+      applyIndex: outcome.applyIndex,
+    });
+  } else if (outcome.status === "rejected") {
+    server._send(ws, {
+      id,
+      type: "error",
+      code: "COMMAND_REJECTED",
+      commandId,
+      message: outcome.reason,
+    });
+  }
+  return outcome;
+}
 
 export function createWsMessageDispatcher(server) {
   return {
@@ -40,8 +95,8 @@ export function createWsMessageDispatcher(server) {
         auth: () => server._handleAuth(clientId, ws, message),
         ping: () =>
           server._send(ws, { id, type: "pong", serverTime: Date.now() }),
-        execute: () => server._executeCommand(id, ws, message.command, false),
-        stream: () => server._executeCommand(id, ws, message.command, true),
+        execute: () => executeWithIdempotency(server, id, ws, message, false),
+        stream: () => executeWithIdempotency(server, id, ws, message, true),
         cancel: () => server._cancelRequest(id, ws),
         "session-create": () => server._handleSessionCreate(id, ws, message),
         "session-resume": () => server._handleSessionResume(id, ws, message),
@@ -54,6 +109,26 @@ export function createWsMessageDispatcher(server) {
           server._handleSessionInterrupt(id, ws, message),
         "slash-command": () => server._handleSlashCommand(id, ws, message),
         "session-answer": () => server._handleSessionAnswer(id, ws, message),
+        "remote-session-create": () =>
+          handleRemoteSessionCreate(server, clientId, ws, message),
+        "remote-session-close": () =>
+          handleRemoteSessionClose(server, clientId, ws, message),
+        "remote-session-pairing-token": () =>
+          handleRemoteSessionPairingToken(server, clientId, ws, message),
+        "remote-session-join": () =>
+          handleRemoteSessionJoin(server, clientId, ws, message),
+        "remote-session-devices": () =>
+          handleRemoteSessionDevices(server, clientId, ws, message),
+        "remote-session-audit": () =>
+          handleRemoteSessionAudit(server, clientId, ws, message),
+        "remote-session-policy": () =>
+          handleRemoteSessionPolicy(server, clientId, ws, message),
+        "remote-session-push-register": () =>
+          handleRemoteSessionPushRegister(server, clientId, ws, message),
+        "remote-session-revoke": () =>
+          handleRemoteSessionRevoke(server, clientId, ws, message),
+        "remote-session-publish": () =>
+          handleRemoteSessionPublish(server, clientId, ws, message),
         "host-tool-result": () => server._handleHostToolResult(id, ws, message),
         orchestrate: () => server._handleOrchestrate(id, ws, message),
         "cowork-task": () => server._handleCoworkTask(id, ws, message),

package/src/gateways/ws/remote-session-protocol.js

@@ -0,0 +1,466 @@
+import {
+  handleSessionAnswer,
+  handleSessionInterrupt,
+  handleSessionMessage,
+} from "./session-protocol.js";
+import {
+  RemoteSessionCryptoContext,
+  createRemotePairingUri,
+} from "../../harness/remote-session-crypto.js";
+
+const CLIENT_EVENT_SCOPES = Object.freeze({
+  prompt: "prompt",
+  "approval.resolve": "approve",
+  interrupt: "interrupt",
+});
+
+function reply(server, ws, id, type, payload = {}) {
+  server._send(ws, { id, type, ...payload });
+}
+
+function audit(server, entry) {
+  server.remoteSessionAudit?.record(entry);
+}
+
+function attachPairingUri(server, result) {
+  const relayUrl = server.remoteSessionRelayUrl;
+  const hostPeerId = server.remoteSessionPeerId;
+  if (!relayUrl || !hostPeerId) return result;
+  server.remoteSessionPairingSecrets.set(
+    result.session.sessionId,
+    result.pairing.token,
+  );
+  let crypto = server.remoteSessionCrypto.get(result.session.sessionId);
+  if (!crypto) {
+    crypto = new RemoteSessionCryptoContext({
+      sessionId: result.session.sessionId,
+      localPeerId: hostPeerId,
+    });
+    server.remoteSessionCrypto.set(result.session.sessionId, crypto);
+  }
+  return {
+    ...result,
+    pairing: {
+      ...result.pairing,
+      hostPublicKey: crypto.publicKey,
+      uri: createRemotePairingUri({
+        relayUrl,
+        remoteSessionId: result.session.sessionId,
+        hostPeerId,
+        hostPublicKey: crypto.publicKey,
+        pairingToken: result.pairing.token,
+        expiresAt: result.pairing.expiresAt,
+      }),
+    },
+  };
+}
+
+export function handleRemoteSessionCreate(server, clientId, ws, message) {
+  try {
+    const result = server.remoteSessions.create({
+      hostClientId: clientId,
+      agentSessionId: message.sessionId,
+      name: message.name,
+      scopes: message.scopes,
+    });
+    audit(server, {
+      sessionId: result.session.sessionId,
+      actor: clientId,
+      action: "session.created",
+      detail: { agentSessionId: message.sessionId, name: message.name || null },
+    });
+    reply(
+      server,
+      ws,
+      message.id,
+      "remote-session-created",
+      attachPairingUri(server, result),
+    );
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_CREATE_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionPairingToken(server, clientId, ws, message) {
+  try {
+    const { session } = server.remoteSessions.authorize(
+      message.remoteSessionId,
+      clientId,
+      "observe",
+    );
+    if (session.hostClientId !== clientId) {
+      throw new Error("Only the host can issue pairing tokens");
+    }
+    const pairing = server.remoteSessions.issuePairingToken(
+      message.remoteSessionId,
+      { scopes: message.scopes },
+    );
+    const result = attachPairingUri(server, {
+      session: {
+        sessionId: message.remoteSessionId,
+      },
+      pairing,
+    });
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "pairing-token.issued",
+      detail: { scopes: message.scopes || null, expiresAt: pairing.expiresAt },
+    });
+    reply(server, ws, message.id, "remote-session-pairing-token", {
+      pairing: result.pairing,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_PAIRING_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionJoin(server, clientId, ws, message) {
+  try {
+    const result = server.remoteSessions.join({
+      sessionId: message.remoteSessionId,
+      clientId,
+      token: message.token,
+      pushToken: message.pushToken,
+      pushProvider: message.pushProvider,
+    });
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "device.joined",
+      detail: {
+        scopes: result.member.scopes,
+        via: "direct",
+        hasPush: result.member.pushToken ? true : false,
+      },
+    });
+    reply(server, ws, message.id, "remote-session-joined", result);
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_JOIN_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionPushRegister(server, clientId, ws, message) {
+  try {
+    // A device may only register its OWN token (clientId is the authenticated
+    // caller). Storing no push value clears it.
+    const result = server.remoteSessions.registerPush(
+      message.remoteSessionId,
+      clientId,
+      { token: message.pushToken, provider: message.pushProvider },
+    );
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "push.registered",
+      detail: { hasPush: result.hasPush, provider: result.provider },
+    });
+    reply(server, ws, message.id, "remote-session-push-registered", result);
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_PUSH_REGISTER_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionDevices(server, clientId, ws, message) {
+  try {
+    const result = server.remoteSessions.listDevices(
+      message.remoteSessionId,
+      clientId,
+    );
+    reply(server, ws, message.id, "remote-session-devices", result);
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_DEVICES_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionPolicy(server, clientId, ws, message) {
+  try {
+    // The active org policy is not sensitive — any authenticated client may
+    // read it (e.g. to pre-check allowed scopes before requesting a session).
+    const policy = server.remoteSessions?.policy;
+    reply(server, ws, message.id, "remote-session-policy", {
+      policy: policy ? policy.describe() : null,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_POLICY_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionAudit(server, clientId, ws, message) {
+  try {
+    // Host-only: authorize proves membership, the host check proves ownership.
+    const { session } = server.remoteSessions.authorize(
+      message.remoteSessionId,
+      clientId,
+      "observe",
+    );
+    if (session.hostClientId !== clientId) {
+      throw new Error("Only the host can read the audit log");
+    }
+    const auditLog = server.remoteSessionAudit;
+    const entries = auditLog
+      ? auditLog.list({
+          sessionId: message.remoteSessionId,
+          limit: message.limit || 200,
+        })
+      : [];
+    const stats = auditLog
+      ? auditLog.stats(message.remoteSessionId)
+      : { total: 0, byAction: {} };
+    reply(server, ws, message.id, "remote-session-audit", {
+      remoteSessionId: message.remoteSessionId,
+      entries,
+      stats,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_AUDIT_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+/**
+ * Tell a revoked device it is no longer paired. Locally connected clients get a
+ * plaintext `remote-session-revoked` push; relay-paired mobile devices get an
+ * encrypted `session.revoked` control event so they stop auto-reconnecting.
+ */
+function notifyRevokedDevice(
+  server,
+  remoteSessionId,
+  agentSessionId,
+  clientId,
+) {
+  const target = server.clients.get(clientId);
+  if (target) {
+    server._send(target.ws, {
+      type: "remote-session-revoked",
+      remoteSessionId,
+      agentSessionId,
+    });
+    return;
+  }
+  if (!server.remoteSessionRelay) return;
+  const crypto = server.remoteSessionCrypto.get(remoteSessionId);
+  if (!crypto) return;
+  try {
+    server.remoteSessionRelay.sendEncrypted(
+      clientId,
+      crypto.encrypt(clientId, { type: "session.revoked", remoteSessionId }),
+    );
+  } catch {
+    // Peer key may already be gone; the registry removal is what actually
+    // enforces revocation, so a failed courtesy notice is non-fatal.
+  }
+}
+
+export function handleRemoteSessionRevoke(server, clientId, ws, message) {
+  try {
+    const targetClientId = message.clientId || message.deviceId;
+    const { session, member } = server.remoteSessions.revokeMember(
+      message.remoteSessionId,
+      clientId,
+      targetClientId,
+    );
+    notifyRevokedDevice(
+      server,
+      message.remoteSessionId,
+      session.agentSessionId,
+      member.clientId,
+    );
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "device.revoked",
+      detail: { revoked: member.clientId },
+    });
+    reply(server, ws, message.id, "remote-session-revoked", {
+      session,
+      revoked: member.clientId,
+      devices: server.remoteSessions.listDevices(
+        message.remoteSessionId,
+        clientId,
+      ).devices,
+    });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_REVOKE_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export function handleRemoteSessionClose(server, clientId, ws, message) {
+  try {
+    const session = server.remoteSessions.close(
+      message.remoteSessionId,
+      clientId,
+    );
+    server.remoteSessionCrypto.delete(message.remoteSessionId);
+    server.remoteSessionPairingSecrets.delete(message.remoteSessionId);
+    audit(server, {
+      sessionId: message.remoteSessionId,
+      actor: clientId,
+      action: "session.closed",
+      detail: { reason: "host-closed" },
+    });
+    reply(server, ws, message.id, "remote-session-closed", { session });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_CLOSE_ERROR",
+      message: error.message,
+    });
+  }
+}
+
+export async function handleRemoteSessionPublish(
+  server,
+  clientId,
+  ws,
+  message,
+) {
+  try {
+    if (!message.event || typeof message.event.type !== "string") {
+      throw new Error("event.type is required");
+    }
+    // A paired device (incl. relay-only mobiles) refreshing its own vendor push
+    // token — e.g. after FCM onNewToken. Self-scoped: authorize proves
+    // membership and registerPush keys off the authenticated clientId, so a
+    // device can only ever set its OWN token. Omitting the token clears it.
+    if (message.event.type === "push.register") {
+      server.remoteSessions.authorize(
+        message.remoteSessionId,
+        clientId,
+        "observe",
+      );
+      const registered = server.remoteSessions.registerPush(
+        message.remoteSessionId,
+        clientId,
+        {
+          token: message.event.pushToken,
+          provider: message.event.pushProvider,
+        },
+      );
+      audit(server, {
+        sessionId: message.remoteSessionId,
+        actor: clientId,
+        action: "push.registered",
+        detail: {
+          hasPush: registered.hasPush,
+          provider: registered.provider,
+          via: "relay",
+        },
+      });
+      reply(
+        server,
+        ws,
+        message.id,
+        "remote-session-push-registered",
+        registered,
+      );
+      return;
+    }
+    const requiredScope = CLIENT_EVENT_SCOPES[message.event.type];
+    const { session } = server.remoteSessions.authorize(
+      message.remoteSessionId,
+      clientId,
+      requiredScope || "observe",
+    );
+    // Runtime/output events are host-only. Remote clients may publish only the
+    // three explicitly scoped control event types above.
+    if (!requiredScope && session.hostClientId !== clientId) {
+      throw new Error("Only the host can publish runtime events");
+    }
+
+    if (requiredScope && session.hostClientId !== clientId) {
+      const controlMessage = {
+        id: message.id,
+        sessionId: session.agentSessionId,
+      };
+      if (message.event.type === "prompt") {
+        if (
+          typeof message.event.content !== "string" ||
+          !message.event.content.trim()
+        ) {
+          throw new Error("prompt content is required");
+        }
+        // Record the shape, not the content — the audit trail must stay useful
+        // without hoarding potentially sensitive session prompts.
+        audit(server, {
+          sessionId: message.remoteSessionId,
+          actor: clientId,
+          action: "control.prompt",
+          detail: { chars: message.event.content.length },
+        });
+        handleSessionMessage(server, message.id, ws, {
+          ...controlMessage,
+          content: message.event.content,
+        });
+      } else if (message.event.type === "approval.resolve") {
+        audit(server, {
+          sessionId: message.remoteSessionId,
+          actor: clientId,
+          action: "control.approval",
+          detail: {
+            requestId: message.event.requestId || message.event.approvalId,
+            approved: message.event.answer ?? message.event.approved,
+          },
+        });
+        await handleSessionAnswer(server, message.id, ws, {
+          ...controlMessage,
+          requestId: message.event.requestId || message.event.approvalId,
+          answer: message.event.answer ?? message.event.approved,
+        });
+      } else if (message.event.type === "interrupt") {
+        audit(server, {
+          sessionId: message.remoteSessionId,
+          actor: clientId,
+          action: "control.interrupt",
+          detail: null,
+        });
+        await handleSessionInterrupt(server, message.id, ws, controlMessage);
+      }
+      return;
+    }
+
+    let delivered = 0;
+    for (const member of server.remoteSessions.members(
+      message.remoteSessionId,
+    )) {
+      if (member.clientId === clientId) continue;
+      const target = server.clients.get(member.clientId);
+      if (!target) continue;
+      server._send(target.ws, {
+        type: "remote-session-event",
+        remoteSessionId: message.remoteSessionId,
+        agentSessionId: session.agentSessionId,
+        event: message.event,
+      });
+      delivered += 1;
+    }
+    reply(server, ws, message.id, "remote-session-published", { delivered });
+  } catch (error) {
+    reply(server, ws, message.id, "error", {
+      code: "REMOTE_SESSION_PUBLISH_ERROR",
+      message: error.message,
+    });
+  }
+}