happy-imou-cloud 2.0.18 → 2.0.19

package/dist/{api-DLI3Zloa.mjs → api-B922KGF8.mjs}

@@ -4,9 +4,9 @@ import { appendFileSync } from 'fs';
 import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, basename } from 'node:path';
+import { z } from 'zod';
 import { EventEmitter } from 'node:events';
 import { io } from 'socket.io-client';
-import { z } from 'zod';
 import { randomBytes, createCipheriv, createDecipheriv, randomUUID, createHash as createHash$1, createHmac, hkdfSync } from 'node:crypto';
 import tweetnacl from 'tweetnacl';
 import { readFile, stat, writeFile, readdir } from 'fs/promises';
@@ -16,7 +16,7 @@ import { spawn } from 'node:child_process';
 import { Expo } from 'expo-server-sdk';
 
 var name = "happy-imou-cloud";
-var version = "2.0.18";
+var version = "2.0.19";
 var description = "hicloud - Imou 企业定制版。关键是 happy！移动端远程 AI 编程工具，支持 Claude Code、Codex 和 Gemini CLI";
 var author = "long.zhu";
 var license = "MIT";
@@ -430,7 +430,7 @@ async function listDaemonLogFiles(limit = 50) {
       return { file, path: fullPath, modified: stats.mtime };
     }).sort((a, b) => b.modified.getTime() - a.modified.getTime());
     try {
-      const { readDaemonState } = await import('./persistence-DicQpgl6.mjs');
+      const { readDaemonState } = await import('./persistence-BfGHkCeJ.mjs');
       const state = await readDaemonState();
       if (!state) {
         return logs;
@@ -564,16 +564,54 @@ function decrypt(key, variant, data) {
   }
 }
 
+const SessionRuntimeIndexSchema = z.object({
+  machineId: z.string().nullish(),
+  hostPid: z.number().int().nullish(),
+  startedBy: z.string().nullish(),
+  lifecycleState: z.string().nullish(),
+  flavor: z.string().nullish()
+});
+const ProtocolV3DescriptorSchema = z.object({
+  protocolVersion: z.string(),
+  serverVersion: z.string().optional(),
+  capabilities: z.array(z.string()),
+  legacyFallback: z.object({
+    http: z.array(z.string()),
+    websocketPath: z.string()
+  }).optional()
+});
+const ProtocolV3CapabilitiesResponseSchema = z.object({
+  protocol: ProtocolV3DescriptorSchema
+});
 const SessionMessageContentSchema = z.object({
   c: z.string(),
   // Base64 encoded encrypted content
   t: z.literal("encrypted")
 });
+const NewSessionBodySchema = z.object({
+  t: z.literal("new-session"),
+  id: z.string(),
+  seq: z.number(),
+  title: z.string().nullable().optional(),
+  metadata: z.string(),
+  metadataVersion: z.number(),
+  agentState: z.string().nullable(),
+  agentStateVersion: z.number(),
+  dataEncryptionKey: z.string().nullable().optional(),
+  active: z.boolean().optional(),
+  activeAt: z.number().optional(),
+  createdAt: z.number().optional(),
+  updatedAt: z.number().optional(),
+  sessionIndex: SessionRuntimeIndexSchema.nullish()
+});
 const UpdateBodySchema = z.object({
   message: z.object({
     id: z.string(),
     seq: z.number(),
-    content: SessionMessageContentSchema
+    content: SessionMessageContentSchema,
+    localId: z.string().nullable().optional(),
+    createdAt: z.number().optional(),
+    updatedAt: z.number().optional()
   }),
   sid: z.string(),
   // Session ID
@@ -581,16 +619,25 @@ const UpdateBodySchema = z.object({
 });
 const UpdateSessionBodySchema = z.object({
   t: z.literal("update-session"),
-  sid: z.string(),
+  sid: z.string().optional(),
+  id: z.string().optional(),
+  changeSeq: z.number().optional(),
+  title: z.string().nullable().optional(),
   metadata: z.object({
     version: z.number(),
     value: z.string()
   }).nullish(),
+  sessionIndex: SessionRuntimeIndexSchema.nullish(),
   agentState: z.object({
     version: z.number(),
     value: z.string()
   }).nullish()
 });
+const DeleteSessionBodySchema = z.object({
+  t: z.literal("delete-session"),
+  sid: z.string(),
+  changeSeq: z.number().optional()
+});
 const UpdateMachineBodySchema = z.object({
   t: z.literal("update-machine"),
   machineId: z.string(),
@@ -607,9 +654,11 @@ z.object({
   id: z.string(),
   seq: z.number(),
   body: z.union([
+    NewSessionBodySchema,
     UpdateBodySchema,
     UpdateSessionBodySchema,
-    UpdateMachineBodySchema
+    UpdateMachineBodySchema,
+    DeleteSessionBodySchema
   ]),
   createdAt: z.number()
 });
@@ -644,6 +693,87 @@ z.object({
   seq: z.number(),
   updatedAt: z.number()
 });
+const ProtocolV3SessionSchema = z.object({
+  id: z.string(),
+  lastChangeSeq: z.number(),
+  title: z.string().nullable().optional(),
+  metadata: z.string().optional(),
+  metadataVersion: z.number().optional(),
+  agentState: z.string().nullable().optional(),
+  agentStateVersion: z.number().optional(),
+  dataEncryptionKey: z.string().nullable().optional(),
+  active: z.boolean().optional(),
+  activeAt: z.number().optional(),
+  pendingCount: z.number().optional(),
+  pendingVersion: z.number().optional(),
+  createdAt: z.number().optional(),
+  updatedAt: z.number().optional(),
+  deleted: z.boolean().optional()
+});
+const ProtocolV3SessionMessageSchema = z.object({
+  id: z.string(),
+  seq: z.number(),
+  localId: z.string().nullable(),
+  content: SessionMessageContentSchema,
+  createdAt: z.number(),
+  updatedAt: z.number()
+});
+const ProtocolV3SessionSnapshotSchema = z.object({
+  messages: z.array(ProtocolV3SessionMessageSchema),
+  truncated: z.boolean(),
+  oldestRetainedSeq: z.number().nullable()
+});
+const ProtocolV3SessionSnapshotResponseSchema = z.object({
+  protocol: ProtocolV3DescriptorSchema,
+  session: ProtocolV3SessionSchema,
+  snapshot: ProtocolV3SessionSnapshotSchema
+});
+const ProtocolV3SessionChangeSchema = z.object({
+  changeSeq: z.number(),
+  changeType: z.string(),
+  createdAt: z.number(),
+  payload: z.record(z.string(), z.unknown())
+});
+z.object({
+  protocol: ProtocolV3DescriptorSchema,
+  connectionType: z.enum(["session-scoped", "user-scoped", "machine-scoped"])
+});
+z.object({
+  sessionId: z.string(),
+  change: ProtocolV3SessionChangeSchema
+});
+const SessionListItemSchema = z.object({
+  id: z.string(),
+  seq: z.number(),
+  title: z.string().nullable().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  active: z.boolean(),
+  activeAt: z.number(),
+  metadata: z.string(),
+  metadataVersion: z.number(),
+  agentState: z.string().nullable(),
+  agentStateVersion: z.number(),
+  dataEncryptionKey: z.string().nullable().optional(),
+  pendingCount: z.number().optional(),
+  pendingVersion: z.number().optional(),
+  lastMessage: z.unknown().nullable().optional(),
+  sessionIndex: SessionRuntimeIndexSchema.nullish()
+});
+const SessionListResponseSchema = z.object({
+  sessions: z.array(SessionListItemSchema)
+});
+const ProtocolV3SessionChangesCursorSchema = z.object({
+  afterSeq: z.number(),
+  lastChangeSeq: z.number(),
+  hasMore: z.boolean()
+});
+const ProtocolV3SessionChangesResponseSchema = z.object({
+  protocol: ProtocolV3DescriptorSchema,
+  session: ProtocolV3SessionSchema,
+  cursor: ProtocolV3SessionChangesCursorSchema,
+  changes: z.array(ProtocolV3SessionChangeSchema)
+});
 const MessageMetaSchema = z.object({
   sentFrom: z.string().optional(),
   // Source identifier
@@ -695,6 +825,27 @@ const AgentMessageSchema = z.object({
 });
 z.union([UserMessageSchema, AgentMessageSchema]);
 
+function buildSessionRuntimeIndex(metadata) {
+  if (!metadata) {
+    return null;
+  }
+  const machineId = typeof metadata.machineId === "string" && metadata.machineId ? metadata.machineId : null;
+  const hostPid = typeof metadata.hostPid === "number" && Number.isInteger(metadata.hostPid) ? metadata.hostPid : null;
+  const startedBy = typeof metadata.startedBy === "string" && metadata.startedBy ? metadata.startedBy : null;
+  const lifecycleState = typeof metadata.lifecycleState === "string" && metadata.lifecycleState ? metadata.lifecycleState : null;
+  const flavor = typeof metadata.flavor === "string" && metadata.flavor ? metadata.flavor : null;
+  if (!machineId && hostPid === null && !startedBy && !lifecycleState && !flavor) {
+    return null;
+  }
+  return {
+    ...machineId ? { machineId } : {},
+    ...hostPid !== null ? { hostPid } : {},
+    ...startedBy ? { startedBy } : {},
+    ...lifecycleState ? { lifecycleState } : {},
+    ...flavor ? { flavor } : {}
+  };
+}
+
 async function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1501,6 +1652,9 @@ function buildSocketAuth(opts) {
 
 const MAX_PENDING_RELIABLE_CODEX_MESSAGES = 200;
 const MAX_PENDING_RELIABLE_CODEX_MESSAGE_BYTES = 512 * 1024;
+const PROTOCOL_V3_INITIAL_SNAPSHOT_LIMIT = 150;
+const PROTOCOL_V3_CHANGES_PAGE_LIMIT = 200;
+const PROTOCOL_V3_CAPABILITIES_WAIT_MS = 250;
 class ApiSessionClient extends EventEmitter {
   credentials;
   sessionId;
@@ -1520,6 +1674,15 @@ class ApiSessionClient extends EventEmitter {
   pendingReliableCodexMessageBytes = 0;
   reconnectAfterServerDisconnectTimer = null;
   lastSocketServerError = null;
+  protocolV3SessionSync = null;
+  protocolV3SessionSyncGeneration = 0;
+  protocolV3SessionSyncInProgress = false;
+  bufferedLiveSessionEventsDuringProtocolSync = [];
+  initialProtocolV3SnapshotComplete = false;
+  lastChangeSeq;
+  protocolV3Descriptor = null;
+  protocolV3SocketCapabilities = null;
+  protocolV3SessionSyncWaitTimer = null;
   constructor(credentials, session) {
     super();
     this.credentials = credentials;
@@ -1530,6 +1693,7 @@ class ApiSessionClient extends EventEmitter {
     this.agentStateVersion = session.agentStateVersion;
     this.encryptionKey = session.encryptionKey;
     this.encryptionVariant = session.encryptionVariant;
+    this.lastChangeSeq = session.seq;
     this.rpcHandlerManager = new RpcHandlerManager({
       scopePrefix: this.sessionId,
       encryptionKey: this.encryptionKey,
@@ -1558,6 +1722,9 @@ class ApiSessionClient extends EventEmitter {
       this.lastSocketServerError = null;
       this.rpcHandlerManager.onSocketConnect(this.socket);
       this.flushReliableCodexMessages();
+      this.protocolV3Descriptor = null;
+      this.protocolV3SocketCapabilities = null;
+      this.scheduleProtocolV3SessionSync();
     });
     this.socket.on("rpc-request", async (data, callback) => {
       callback(await this.rpcHandlerManager.handleRequest(data));
@@ -1565,6 +1732,7 @@ class ApiSessionClient extends EventEmitter {
     this.socket.on("disconnect", (reason) => {
       logger.debug("[API] Socket disconnected:", reason);
       this.rpcHandlerManager.onSocketDisconnect();
+      this.invalidateProtocolV3SessionSync();
       this.retryAfterServerDisconnect(reason);
     });
     this.socket.on("connect_error", (error) => {
@@ -1574,43 +1742,42 @@ class ApiSessionClient extends EventEmitter {
     this.socket.on("update", (data) => {
       try {
         logger.debugLargeJson("[SOCKET] [UPDATE] Received update:", data);
-        if (!data.body) {
-          logger.debug("[SOCKET] [UPDATE] [ERROR] No body in update!");
+        if (this.protocolV3SessionSyncInProgress) {
+          this.bufferLiveSessionEvent({ type: "update", payload: data });
           return;
         }
-        if (data.body.t === "new-message" && data.body.message.content.t === "encrypted") {
-          const body = decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(data.body.message.content.c));
-          logger.debugLargeJson("[SOCKET] [UPDATE] Received update:", body);
-          const userResult = UserMessageSchema.safeParse(body);
-          if (userResult.success) {
-            if (this.pendingMessageCallback) {
-              this.pendingMessageCallback(userResult.data);
-            } else {
-              this.pendingMessages.push(userResult.data);
-            }
-          } else {
-            this.emit("message", body);
-          }
-        } else if (data.body.t === "update-session") {
-          if (data.body.metadata && data.body.metadata.version > this.metadataVersion) {
-            this.metadata = decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(data.body.metadata.value));
-            this.metadataVersion = data.body.metadata.version;
-            this.emit("metadata-updated", this.metadata);
-          }
-          if (data.body.agentState && data.body.agentState.version > this.agentStateVersion) {
-            this.agentState = data.body.agentState.value ? decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(data.body.agentState.value)) : null;
-            this.agentStateVersion = data.body.agentState.version;
-            this.emit("agent-state-updated", this.agentState);
-          }
-        } else if (data.body.t === "update-machine") {
-          logger.debug(`[SOCKET] WARNING: Session client received unexpected machine update - ignoring`);
-        } else {
-          this.emit("message", data.body);
-        }
+        this.handleSocketUpdate(data);
       } catch (error) {
         logger.debug("[SOCKET] [UPDATE] [ERROR] Error handling update", { error });
       }
     });
+    this.socket.on("capabilities", (data) => {
+      try {
+        this.protocolV3SocketCapabilities = data;
+        this.protocolV3Descriptor = data.protocol;
+        logger.debug("[API] Received websocket protocol capabilities", {
+          sessionId: this.sessionId,
+          connectionType: data.connectionType,
+          capabilities: data.protocol.capabilities
+        });
+        this.clearProtocolV3SessionSyncWaitTimer();
+        this.scheduleProtocolV3SessionSync({ waitForCapabilities: false });
+      } catch (error) {
+        logger.debug("[SOCKET] [CAPABILITIES] [ERROR] Error handling capabilities event", { error });
+      }
+    });
+    this.socket.on("session-change", (data) => {
+      try {
+        logger.debugLargeJson("[SOCKET] [SESSION-CHANGE] Received session change:", data);
+        if (this.protocolV3SessionSyncInProgress) {
+          this.bufferLiveSessionEvent({ type: "session-change", payload: data });
+          return;
+        }
+        this.handleProtocolV3SessionChangeEvent(data);
+      } catch (error) {
+        logger.debug("[SOCKET] [SESSION-CHANGE] [ERROR] Error handling session change", { error });
+      }
+    });
     this.socket.on("error", (error) => {
       logger.debug("[API] Socket error:", error);
       this.lastSocketServerError = this.normalizeSocketError(error);
@@ -1623,6 +1790,20 @@ class ApiSessionClient extends EventEmitter {
       callback(this.pendingMessages.shift());
     }
   }
+  configureProtocolV3Sync(options) {
+    this.invalidateProtocolV3SessionSync();
+    this.protocolV3SessionSync = options;
+    this.initialProtocolV3SnapshotComplete = false;
+    if (this.protocolV3SessionSync && this.socket.connected) {
+      this.scheduleProtocolV3SessionSync();
+    }
+  }
+  getProtocolV3DescriptorSnapshot() {
+    return this.protocolV3Descriptor;
+  }
+  getProtocolV3SocketCapabilitiesSnapshot() {
+    return this.protocolV3SocketCapabilities;
+  }
   getMetadataSnapshot() {
     return this.metadata;
   }
@@ -1781,11 +1962,13 @@ class ApiSessionClient extends EventEmitter {
     if (process.env.DEBUG) {
       logger.debug(`[API] Sending keep alive message: ${thinking}`);
     }
+    const sessionIndex = buildSessionRuntimeIndex(this.metadata);
     this.socket.volatile.emit("session-alive", {
       sid: this.sessionId,
       time: Date.now(),
       thinking,
-      mode
+      mode,
+      ...sessionIndex ? { sessionIndex } : {}
     });
   }
   /**
@@ -1827,7 +2010,13 @@ class ApiSessionClient extends EventEmitter {
     this.metadataLock.inLock(async () => {
       await backoff(async () => {
         let updated = handler(this.metadata);
-        const answer = await this.socket.emitWithAck("update-metadata", { sid: this.sessionId, expectedVersion: this.metadataVersion, metadata: encodeBase64(encrypt(this.encryptionKey, this.encryptionVariant, updated)) });
+        const sessionIndex = buildSessionRuntimeIndex(updated);
+        const answer = await this.socket.emitWithAck("update-metadata", {
+          sid: this.sessionId,
+          expectedVersion: this.metadataVersion,
+          metadata: encodeBase64(encrypt(this.encryptionKey, this.encryptionVariant, updated)),
+          ...sessionIndex ? { sessionIndex } : {}
+        });
         if (answer.result === "success") {
           this.metadata = decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(answer.metadata));
           this.metadataVersion = answer.version;
@@ -1888,8 +2077,280 @@ class ApiSessionClient extends EventEmitter {
   async close() {
     logger.debug("[API] socket.close() called");
     this.clearReconnectAfterServerDisconnectTimer();
+    this.invalidateProtocolV3SessionSync();
     this.socket.close();
   }
+  handleSocketUpdate(data) {
+    if (!data.body) {
+      logger.debug("[SOCKET] [UPDATE] [ERROR] No body in update!");
+      return;
+    }
+    if (data.body.t === "new-message" && data.body.message.content.t === "encrypted") {
+      const messageSeq = typeof data.body.message.seq === "number" ? data.body.message.seq : null;
+      if (messageSeq !== null && messageSeq <= this.lastChangeSeq) {
+        return;
+      }
+      this.dispatchEncryptedSessionMessage(data.body.message.content.c);
+      if (messageSeq !== null) {
+        this.lastChangeSeq = Math.max(this.lastChangeSeq, messageSeq);
+      }
+      return;
+    }
+    if (data.body.t === "update-session") {
+      const sessionBody = data.body;
+      const changeSeq = typeof sessionBody.changeSeq === "number" ? sessionBody.changeSeq : null;
+      if (changeSeq !== null && changeSeq <= this.lastChangeSeq) {
+        return;
+      }
+      if (sessionBody.metadata && sessionBody.metadata.version > this.metadataVersion) {
+        this.metadata = decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(sessionBody.metadata.value));
+        this.metadataVersion = sessionBody.metadata.version;
+        this.emit("metadata-updated", this.metadata);
+      }
+      if (sessionBody.agentState && sessionBody.agentState.version > this.agentStateVersion) {
+        this.agentState = sessionBody.agentState.value ? decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(sessionBody.agentState.value)) : null;
+        this.agentStateVersion = sessionBody.agentState.version;
+        this.emit("agent-state-updated", this.agentState);
+      }
+      if (changeSeq !== null) {
+        this.lastChangeSeq = Math.max(this.lastChangeSeq, changeSeq);
+      }
+      return;
+    }
+    if (data.body.t === "update-machine") {
+      logger.debug(`[SOCKET] WARNING: Session client received unexpected machine update - ignoring`);
+      return;
+    }
+    if (data.body.t === "delete-session") {
+      const deleteBody = data.body;
+      const changeSeq = typeof deleteBody.changeSeq === "number" ? deleteBody.changeSeq : null;
+      if (changeSeq !== null) {
+        if (changeSeq <= this.lastChangeSeq) {
+          return;
+        }
+        this.lastChangeSeq = Math.max(this.lastChangeSeq, changeSeq);
+      }
+    }
+    this.emit("message", data.body);
+  }
+  dispatchEncryptedSessionMessage(encryptedMessage) {
+    const body = decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(encryptedMessage));
+    logger.debugLargeJson("[SOCKET] [UPDATE] Received update:", body);
+    const userResult = UserMessageSchema.safeParse(body);
+    if (userResult.success) {
+      if (this.pendingMessageCallback) {
+        this.pendingMessageCallback(userResult.data);
+      } else {
+        this.pendingMessages.push(userResult.data);
+      }
+      return;
+    }
+    this.emit("message", body);
+  }
+  invalidateProtocolV3SessionSync() {
+    this.protocolV3SessionSyncGeneration += 1;
+    this.protocolV3SessionSyncInProgress = false;
+    this.bufferedLiveSessionEventsDuringProtocolSync = [];
+    this.protocolV3Descriptor = null;
+    this.protocolV3SocketCapabilities = null;
+    this.clearProtocolV3SessionSyncWaitTimer();
+  }
+  scheduleProtocolV3SessionSync(options) {
+    if (!this.protocolV3SessionSync || !this.socket.connected) {
+      return;
+    }
+    const shouldWaitForCapabilities = options?.waitForCapabilities ?? (Boolean(this.credentials.signing) && this.protocolV3Descriptor === null);
+    if (shouldWaitForCapabilities) {
+      this.clearProtocolV3SessionSyncWaitTimer();
+      this.protocolV3SessionSyncWaitTimer = setTimeout(() => {
+        this.protocolV3SessionSyncWaitTimer = null;
+        void this.runProtocolV3SessionSync();
+      }, PROTOCOL_V3_CAPABILITIES_WAIT_MS);
+      return;
+    }
+    void this.runProtocolV3SessionSync();
+  }
+  clearProtocolV3SessionSyncWaitTimer() {
+    if (!this.protocolV3SessionSyncWaitTimer) {
+      return;
+    }
+    clearTimeout(this.protocolV3SessionSyncWaitTimer);
+    this.protocolV3SessionSyncWaitTimer = null;
+  }
+  async runProtocolV3SessionSync() {
+    if (!this.protocolV3SessionSync || this.protocolV3SessionSyncInProgress || !this.socket.connected) {
+      return;
+    }
+    if (this.protocolV3Descriptor && !this.supportsKnownProtocolCapability("session_changes_v3")) {
+      logger.debug("[API] Skipping protocol v3 session catch-up because websocket capabilities do not advertise session_changes_v3", {
+        sessionId: this.sessionId
+      });
+      return;
+    }
+    const generation = this.protocolV3SessionSyncGeneration + 1;
+    this.protocolV3SessionSyncGeneration = generation;
+    this.protocolV3SessionSyncInProgress = true;
+    this.bufferedLiveSessionEventsDuringProtocolSync = [];
+    try {
+      logger.debug("[API] Starting protocol v3 session catch-up", {
+        sessionId: this.sessionId,
+        lastChangeSeq: this.lastChangeSeq
+      });
+      if (!this.initialProtocolV3SnapshotComplete && this.lastChangeSeq === 0 && (!this.protocolV3Descriptor || this.supportsKnownProtocolCapability("session_snapshot_v3"))) {
+        const snapshot = await this.protocolV3SessionSync.getSessionSnapshot(
+          this.sessionId,
+          this.protocolV3SessionSync.snapshotLimit ?? PROTOCOL_V3_INITIAL_SNAPSHOT_LIMIT
+        );
+        if (!this.isActiveProtocolV3SessionSync(generation)) {
+          return;
+        }
+        if (snapshot) {
+          this.applyProtocolV3Snapshot(snapshot);
+          this.initialProtocolV3SnapshotComplete = true;
+        }
+      }
+      while (this.isActiveProtocolV3SessionSync(generation)) {
+        const afterSeq = this.lastChangeSeq;
+        const page = await this.protocolV3SessionSync.getSessionChanges(
+          this.sessionId,
+          afterSeq,
+          this.protocolV3SessionSync.changesLimit ?? PROTOCOL_V3_CHANGES_PAGE_LIMIT
+        );
+        if (!this.isActiveProtocolV3SessionSync(generation)) {
+          return;
+        }
+        if (!page) {
+          break;
+        }
+        this.applyProtocolV3SessionOverlay(page.session);
+        for (const change of page.changes) {
+          this.applyProtocolV3Change(change);
+        }
+        if (!page.cursor.hasMore || page.changes.length === 0) {
+          break;
+        }
+      }
+    } catch (error) {
+      logger.debug("[API] Protocol v3 session catch-up failed", {
+        sessionId: this.sessionId,
+        error
+      });
+    } finally {
+      if (generation !== this.protocolV3SessionSyncGeneration) {
+        return;
+      }
+      this.protocolV3SessionSyncInProgress = false;
+      const bufferedLiveEvents = this.bufferedLiveSessionEventsDuringProtocolSync;
+      this.bufferedLiveSessionEventsDuringProtocolSync = [];
+      for (const liveEvent of bufferedLiveEvents) {
+        this.replayBufferedLiveSessionEvent(liveEvent);
+      }
+    }
+  }
+  isActiveProtocolV3SessionSync(generation) {
+    return generation === this.protocolV3SessionSyncGeneration && this.socket.connected;
+  }
+  applyProtocolV3Snapshot(snapshot) {
+    this.applyProtocolV3SessionOverlay(snapshot.session);
+    for (const message of snapshot.snapshot.messages) {
+      if (message.seq <= this.lastChangeSeq) {
+        continue;
+      }
+      if (message.content.t === "encrypted") {
+        this.dispatchEncryptedSessionMessage(message.content.c);
+      }
+      this.lastChangeSeq = Math.max(this.lastChangeSeq, message.seq);
+    }
+    this.lastChangeSeq = Math.max(this.lastChangeSeq, snapshot.session.lastChangeSeq);
+  }
+  applyProtocolV3SessionOverlay(session) {
+    if (typeof session.metadataVersion === "number" && typeof session.metadata === "string" && session.metadataVersion > this.metadataVersion) {
+      this.metadata = decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(session.metadata));
+      this.metadataVersion = session.metadataVersion;
+      this.emit("metadata-updated", this.metadata);
+    }
+    if (typeof session.agentStateVersion === "number" && session.agentStateVersion > this.agentStateVersion) {
+      this.agentState = typeof session.agentState === "string" ? decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(session.agentState)) : null;
+      this.agentStateVersion = session.agentStateVersion;
+      this.emit("agent-state-updated", this.agentState);
+    }
+  }
+  applyProtocolV3Change(change) {
+    if (change.changeSeq <= this.lastChangeSeq) {
+      return;
+    }
+    const payload = change.payload && typeof change.payload === "object" ? change.payload : {};
+    switch (change.changeType) {
+      case "message.created": {
+        const message = payload.message;
+        if (message && typeof message === "object") {
+          const content = message.content;
+          if (content && typeof content === "object" && content.t === "encrypted" && typeof content.c === "string") {
+            this.dispatchEncryptedSessionMessage(content.c);
+          }
+        }
+        break;
+      }
+      case "session.metadata.updated": {
+        const metadataUpdate = payload.metadata;
+        if (metadataUpdate && typeof metadataUpdate === "object" && typeof metadataUpdate.version === "number" && typeof metadataUpdate.value === "string") {
+          const version = metadataUpdate.version;
+          if (version <= this.metadataVersion) {
+            break;
+          }
+          this.metadata = decrypt(
+            this.encryptionKey,
+            this.encryptionVariant,
+            decodeBase64(metadataUpdate.value)
+          );
+          this.metadataVersion = version;
+          this.emit("metadata-updated", this.metadata);
+        }
+        break;
+      }
+      case "session.agent-state.updated": {
+        const agentStateUpdate = payload.agentState;
+        if (agentStateUpdate && typeof agentStateUpdate === "object" && typeof agentStateUpdate.version === "number") {
+          const version = agentStateUpdate.version;
+          if (version <= this.agentStateVersion) {
+            break;
+          }
+          const encodedAgentState = agentStateUpdate.value;
+          this.agentState = typeof encodedAgentState === "string" ? decrypt(this.encryptionKey, this.encryptionVariant, decodeBase64(encodedAgentState)) : null;
+          this.agentStateVersion = version;
+          this.emit("agent-state-updated", this.agentState);
+        }
+        break;
+      }
+      case "session.deleted":
+        this.emit("message", {
+          t: "delete-session",
+          sid: this.sessionId,
+          changeSeq: change.changeSeq
+        });
+        break;
+    }
+    this.lastChangeSeq = Math.max(this.lastChangeSeq, change.changeSeq);
+  }
+  handleProtocolV3SessionChangeEvent(data) {
+    if (data.sessionId !== this.sessionId) {
+      return;
+    }
+    this.applyProtocolV3Change(data.change);
+  }
+  replayBufferedLiveSessionEvent(event) {
+    if (event.type === "update") {
+      this.handleSocketUpdate(event.payload);
+      return;
+    }
+    this.handleProtocolV3SessionChangeEvent(event.payload);
+  }
+  bufferLiveSessionEvent(event) {
+    this.bufferedLiveSessionEventsDuringProtocolSync.push(event);
+  }
+  supportsKnownProtocolCapability(capability) {
+    return Array.isArray(this.protocolV3Descriptor?.capabilities) && this.protocolV3Descriptor.capabilities.includes(capability);
+  }
   emitEncryptedSessionMessage(encrypted) {
     this.socket.emit("message", {
       sid: this.sessionId,
@@ -2198,6 +2659,141 @@ class ApiMachineClient {
   }
 }
 
+class ApiUserObserverClient extends EventEmitter {
+  constructor(credentials) {
+    super();
+    this.credentials = credentials;
+    this.socket = io(configuration.serverUrl, {
+      auth: (cb) => cb(buildSocketAuth({
+        credentials: this.credentials,
+        clientType: "user-scoped"
+      })),
+      path: "/v1/updates",
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: 1e3,
+      reconnectionDelayMax: 5e3,
+      transports: ["websocket"],
+      withCredentials: true,
+      autoConnect: false
+    });
+    this.socket.on("connect", () => {
+      logger.debug("[API USER OBSERVER] Socket connected successfully");
+      this.clearReconnectAfterServerDisconnectTimer();
+      this.lastSocketServerError = null;
+      this.protocolV3Descriptor = null;
+      this.protocolV3SocketCapabilities = null;
+    });
+    this.socket.on("disconnect", (reason) => {
+      logger.debug("[API USER OBSERVER] Socket disconnected:", reason);
+      this.protocolV3Descriptor = null;
+      this.protocolV3SocketCapabilities = null;
+      this.retryAfterServerDisconnect(reason);
+    });
+    this.socket.on("connect_error", (error) => {
+      logger.debug("[API USER OBSERVER] Socket connection error:", error);
+    });
+    this.socket.on("capabilities", (data) => {
+      this.protocolV3SocketCapabilities = data;
+      this.protocolV3Descriptor = data.protocol;
+      this.emit("protocol-capabilities", data);
+    });
+    this.socket.on("update", (data) => {
+      this.emit("update", data);
+    });
+    this.socket.on("ephemeral", (data) => {
+      this.emit("ephemeral", data);
+    });
+    this.socket.on("error", (error) => {
+      logger.debug("[API USER OBSERVER] Socket error:", error);
+      this.lastSocketServerError = this.normalizeSocketError(error);
+    });
+    this.socket.connect();
+  }
+  socket;
+  protocolV3Descriptor = null;
+  protocolV3SocketCapabilities = null;
+  reconnectAfterServerDisconnectTimer = null;
+  lastSocketServerError = null;
+  isConnected() {
+    return this.socket.connected;
+  }
+  getProtocolV3DescriptorSnapshot() {
+    return this.protocolV3Descriptor;
+  }
+  getProtocolV3SocketCapabilitiesSnapshot() {
+    return this.protocolV3SocketCapabilities;
+  }
+  onEphemeral(callback) {
+    this.on("ephemeral", callback);
+  }
+  offEphemeral(callback) {
+    this.off("ephemeral", callback);
+  }
+  onUpdate(callback) {
+    this.on("update", callback);
+  }
+  offUpdate(callback) {
+    this.off("update", callback);
+  }
+  async close() {
+    this.clearReconnectAfterServerDisconnectTimer();
+    this.protocolV3Descriptor = null;
+    this.protocolV3SocketCapabilities = null;
+    this.socket.close();
+  }
+  retryAfterServerDisconnect(reason) {
+    if (reason !== "io server disconnect") {
+      return;
+    }
+    const errorCode = this.lastSocketServerError?.error;
+    if (errorCode !== "REQUEST_EXPIRED" && errorCode !== "REQUEST_REPLAYED") {
+      return;
+    }
+    if (this.reconnectAfterServerDisconnectTimer || this.socket.connected) {
+      return;
+    }
+    logger.debug("[API USER OBSERVER] Scheduling manual reconnect after retryable server disconnect", {
+      reason,
+      errorCode,
+      message: this.lastSocketServerError?.message
+    });
+    this.reconnectAfterServerDisconnectTimer = setTimeout(() => {
+      this.reconnectAfterServerDisconnectTimer = null;
+      if (this.socket.connected) {
+        return;
+      }
+      logger.debug("[API USER OBSERVER] Retrying socket connection after server disconnect", {
+        errorCode,
+        message: this.lastSocketServerError?.message
+      });
+      this.socket.connect();
+    }, 1e3);
+  }
+  clearReconnectAfterServerDisconnectTimer() {
+    if (!this.reconnectAfterServerDisconnectTimer) {
+      return;
+    }
+    clearTimeout(this.reconnectAfterServerDisconnectTimer);
+    this.reconnectAfterServerDisconnectTimer = null;
+  }
+  normalizeSocketError(error) {
+    if (!error || typeof error !== "object") {
+      return null;
+    }
+    const candidate = error;
+    const errorCode = typeof candidate.error === "string" ? candidate.error : void 0;
+    const message = typeof candidate.message === "string" ? candidate.message : void 0;
+    if (!errorCode && !message) {
+      return null;
+    }
+    return {
+      error: errorCode,
+      message
+    };
+  }
+}
+
 class PushNotificationClient {
   credentials;
   baseUrl;
@@ -2518,6 +3114,39 @@ class ApiClient {
     }
     return new AuthenticationRequiredError(AUTHENTICATION_REQUIRED_MESSAGE);
   }
+  async requestProtocolV3Resource(opts) {
+    if (!this.credential.signing) {
+      logger.debug(`[API] Skipping ${opts.logLabel} because signing credentials are unavailable`);
+      return null;
+    }
+    try {
+      const response = await this.request({
+        method: "GET",
+        url: opts.url,
+        timeout: 5e3
+      });
+      const parsed = opts.schema.safeParse(response.data);
+      if (!parsed.success) {
+        logger.debug(`[API] ${opts.logLabel} returned an unexpected payload`, response.data);
+        return null;
+      }
+      return parsed.data;
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        const status = error.response?.status;
+        if (status === 401 || status === 403 || status === 404) {
+          logger.debug(`[API] ${opts.logLabel} unavailable (${status ?? "unknown"})`);
+          return null;
+        }
+        if (error.code && isNetworkError(error.code)) {
+          logger.debug(`[API] ${opts.logLabel} probe failed due to network error`, error.code);
+          return null;
+        }
+      }
+      logger.debug(`[API] Failed to fetch ${opts.logLabel}`, error);
+      return null;
+    }
+  }
   async request(opts) {
     return axios.request({
       method: opts.method,
@@ -2536,6 +3165,72 @@ class ApiClient {
       timeout: opts.timeout
     });
   }
+  async getProtocolV3Descriptor() {
+    const url = `${configuration.serverUrl}/v3/capabilities`;
+    const payload = await this.requestProtocolV3Resource({
+      url,
+      schema: ProtocolV3CapabilitiesResponseSchema,
+      logLabel: "/v3/capabilities"
+    });
+    return payload?.protocol ?? null;
+  }
+  async getSessionSnapshotV3(sessionId, limit = 150) {
+    const url = new URL(`/v3/sessions/${encodeURIComponent(sessionId)}/snapshot`, configuration.serverUrl);
+    url.searchParams.set("limit", String(limit));
+    return await this.requestProtocolV3Resource({
+      url: url.toString(),
+      schema: ProtocolV3SessionSnapshotResponseSchema,
+      logLabel: `/v3/sessions/${sessionId}/snapshot`
+    });
+  }
+  async getSessionChangesV3(sessionId, afterSeq, limit = 200) {
+    const url = new URL(`/v3/sessions/${encodeURIComponent(sessionId)}/changes`, configuration.serverUrl);
+    url.searchParams.set("afterSeq", String(afterSeq));
+    url.searchParams.set("limit", String(limit));
+    return await this.requestProtocolV3Resource({
+      url: url.toString(),
+      schema: ProtocolV3SessionChangesResponseSchema,
+      logLabel: `/v3/sessions/${sessionId}/changes`
+    });
+  }
+  async listSessionsIndex() {
+    try {
+      const response = await this.request({
+        method: "GET",
+        url: `${configuration.serverUrl}/v1/sessions`,
+        timeout: 5e3
+      });
+      const parsed = SessionListResponseSchema.safeParse(response.data);
+      if (!parsed.success) {
+        logger.debug("[API] /v1/sessions returned an unexpected payload while listing session index", response.data);
+        return [];
+      }
+      return parsed.data.sessions.map((session) => ({
+        id: session.id,
+        seq: session.seq,
+        title: session.title ?? null,
+        active: session.active,
+        activeAt: session.activeAt,
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+        sessionIndex: session.sessionIndex ?? null
+      }));
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        const status = error.response?.status;
+        if (status === 401 || status === 403 || status === 404) {
+          logger.debug(`[API] Session index unavailable (${status ?? "unknown"})`);
+          return [];
+        }
+        if (error.code && isNetworkError(error.code)) {
+          logger.debug("[API] Session index probe failed due to network error", error.code);
+          return [];
+        }
+      }
+      logger.debug("[API] Failed to list session index", error);
+      return [];
+    }
+  }
   /**
    * Create a new session or load existing one with the given tag
    */
@@ -2555,6 +3250,7 @@ class ApiClient {
       encryptionVariant = "legacy";
     }
     try {
+      const sessionIndex = buildSessionRuntimeIndex(opts.metadata);
       const response = await this.request({
         method: "POST",
         url: `${configuration.serverUrl}/v1/sessions`,
@@ -2562,7 +3258,8 @@ class ApiClient {
           tag: opts.tag,
           metadata: encodeBase64(encrypt(encryptionKey, encryptionVariant, opts.metadata)),
           agentState: opts.state ? encodeBase64(encrypt(encryptionKey, encryptionVariant, opts.state)) : null,
-          dataEncryptionKey: dataEncryptionKey ? encodeBase64(dataEncryptionKey) : null
+          dataEncryptionKey: dataEncryptionKey ? encodeBase64(dataEncryptionKey) : null,
+          ...sessionIndex ? { sessionIndex } : {}
         },
         timeout: 6e4
       });
@@ -2731,11 +3428,21 @@ class ApiClient {
     }
   }
   sessionSyncClient(session) {
-    return new ApiSessionClient(this.credential, session);
+    const client = new ApiSessionClient(this.credential, session);
+    if (this.credential.signing) {
+      client.configureProtocolV3Sync({
+        getSessionSnapshot: (sessionId, limit) => this.getSessionSnapshotV3(sessionId, limit),
+        getSessionChanges: (sessionId, afterSeq, limit) => this.getSessionChangesV3(sessionId, afterSeq, limit)
+      });
+    }
+    return client;
   }
   machineSyncClient(machine) {
     return new ApiMachineClient(this.credential, machine);
   }
+  userScopedObserverClient() {
+    return new ApiUserObserverClient(this.credential);
+  }
   push() {
     return this.pushClient;
   }