@letta-ai/letta-agent-sdk 0.3.3 → 0.5.0

package/src/cloud-session.ts

@@ -1,9 +1,6 @@
 import {
   createAppServerClient,
   type AppServerClient,
-  type AppServerSocketConstructor,
-  type AppServerSocketLike,
-  type AppServerSocketOptions,
 } from "@letta-ai/letta-code/app-server-client";
 import {
   AppServerRuntimeController,
@@ -13,6 +10,7 @@ import {
   externalToolGroups,
   registerAppServerControlRequestHandler,
 } from "./app-server-session.js";
+import { createCloudStatusTransportConstructor } from "./cloud-status-transport.js";
 import {
   RemoteEnvironmentClient,
   type RemoteEnvironmentTarget,
@@ -33,7 +31,6 @@ import type {
   LettaCodeCloudClientOptions,
   LettaCodeEnvironment,
   LettaCodeSocketConstructor,
-  LettaCodeSocketLike,
   RepositoryResource,
 } from "./types.js";
 import {
@@ -53,24 +50,6 @@ const SDK_AGENT_ORIGIN = "@letta-ai/letta-agent-sdk";
 
 type FetchLike = typeof fetch;
 
-type CloudStatusMessage = ProtocolMessage & {
-  type: string;
-  seq?: unknown;
-  event_seq?: unknown;
-  idempotency_key?: unknown;
-  runId?: unknown;
-  run_id?: unknown;
-  stopReason?: unknown;
-  stop_reason?: unknown;
-  conversation_id?: unknown;
-  conversationId?: unknown;
-  agent_id?: unknown;
-  agentId?: unknown;
-  request?: unknown;
-  loop_status?: unknown;
-  delta?: unknown;
-};
-
 type CloudRuntimeStartResponse = ProtocolMessage & {
   type: "runtime_start_response";
   success: boolean;
@@ -328,231 +307,6 @@ function buildCloudStatusWebSocketUrl(params: {
   return base.toString();
 }
 
-function addSocketListener(
-  socket: LettaCodeSocketLike,
-  type: string,
-  listener: (event: unknown) => void,
-): () => void {
-  if (socket.addEventListener) {
-    socket.addEventListener(type, listener);
-    return () => socket.removeEventListener?.(type, listener);
-  }
-  if (socket.on) {
-    socket.on(type, listener);
-    return () => socket.off?.(type, listener);
-  }
-  throw new Error("WebSocket implementation does not support event listeners.");
-}
-
-function messageEventData(event: unknown): string | null {
-  if (typeof event === "string") return event;
-  if (event && typeof event === "object") {
-    const data = (event as { data?: unknown }).data;
-    if (typeof data === "string") return data;
-    if (data instanceof ArrayBuffer) {
-      return new TextDecoder().decode(data);
-    }
-    if (data instanceof Uint8Array) {
-      return new TextDecoder().decode(data);
-    }
-  }
-  return null;
-}
-
-type CloudStatusSocketControl = AppServerSocketLike & {
-  sendCloudCommand(command: Record<string, unknown>): void;
-};
-
-type CloudStatusSocketState = {
-  runtime: RuntimeScope;
-  seenIdempotencyKeys: Set<string>;
-  seenIdempotencyOrder: string[];
-  lastEventSeq: number | null;
-  controlSocket: CloudStatusSocketControl | null;
-};
-
-function createCloudStatusWebSocketConstructor(params: {
-  cloudOptions: LettaCodeCloudClientOptions;
-  runtime: RuntimeScope;
-}): AppServerSocketConstructor {
-  const WebSocketCtor = getWebSocketConstructor(params.cloudOptions.WebSocket);
-  const authMode = params.cloudOptions.webSocketAuth ?? "header";
-  const cloudHeaders = authMode === "header" ? cloudWebSocketHeaders(params.cloudOptions) : undefined;
-  const pingIntervalMs = params.cloudOptions.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
-  const state: CloudStatusSocketState = {
-    runtime: params.runtime,
-    seenIdempotencyKeys: new Set<string>(),
-    seenIdempotencyOrder: [],
-    lastEventSeq: null,
-    controlSocket: null,
-  };
-
-  class CloudStatusSocketAdapter implements AppServerSocketLike {
-    private readonly socket: LettaCodeSocketLike;
-    private readonly channel: string | null;
-    private readonly listenerRemovers = new Map<string, Map<(event: unknown) => void, () => void>>();
-    private pingTimer: ReturnType<typeof setInterval> | null = null;
-    private removeCloseListener: (() => void) | null = null;
-
-    constructor(url: string, options?: AppServerSocketOptions) {
-      this.channel = new URL(url).searchParams.get("channel");
-      const mergedHeaders = authMode === "header"
-        ? {
-            ...(options?.headers ?? {}),
-            ...(cloudHeaders ?? {}),
-          }
-        : undefined;
-      const socketOptions = mergedHeaders && Object.keys(mergedHeaders).length > 0
-        ? { headers: mergedHeaders }
-        : undefined;
-      this.socket = new WebSocketCtor(url, socketOptions);
-      if (this.channel === "control") {
-        state.controlSocket = this;
-      }
-      this.removeCloseListener = addSocketListener(this.socket, "close", () => {
-        this.stopPing();
-        if (state.controlSocket === this) state.controlSocket = null;
-      });
-      this.startPing(pingIntervalMs);
-    }
-
-    get readyState(): number {
-      return this.socket.readyState;
-    }
-
-    send(data: string): void {
-      this.socket.send(data);
-    }
-
-    close(): void {
-      this.stopPing();
-      this.removeCloseListener?.();
-      this.removeCloseListener = null;
-      if (state.controlSocket === this) state.controlSocket = null;
-      this.socket.close();
-    }
-
-    addEventListener(type: string, listener: (event: unknown) => void): void {
-      const wrapped = type === "message"
-        ? (event: unknown) => {
-            if (this.handleIncomingMessage(event)) {
-              listener(event);
-            }
-          }
-        : listener;
-      const remove = addSocketListener(this.socket, type, wrapped);
-      let typeRemovers = this.listenerRemovers.get(type);
-      if (!typeRemovers) {
-        typeRemovers = new Map();
-        this.listenerRemovers.set(type, typeRemovers);
-      }
-      typeRemovers.set(listener, remove);
-    }
-
-    removeEventListener(type: string, listener: (event: unknown) => void): void {
-      const typeRemovers = this.listenerRemovers.get(type);
-      const remove = typeRemovers?.get(listener);
-      if (!remove) return;
-      remove();
-      typeRemovers?.delete(listener);
-      if (typeRemovers?.size === 0) {
-        this.listenerRemovers.delete(type);
-      }
-    }
-
-    private handleIncomingMessage(event: unknown): boolean {
-      const data = messageEventData(event);
-      if (!data) return true;
-
-      let message: CloudStatusMessage;
-      try {
-        message = JSON.parse(data) as CloudStatusMessage;
-      } catch {
-        return true;
-      }
-
-      this.ackIfSequenced(message);
-
-      // The status gateway can mirror device stream frames to the control
-      // subscriber. Drop them at the Cloud transport boundary instead of making
-      // shared app-server session code understand Cloud fanout quirks. Do this
-      // before idempotency/event tracking so the canonical stream-channel frame
-      // is still delivered and sequenced.
-      if (this.channel === "control" && message.type === "stream_delta") {
-        return false;
-      }
-
-      if (this.isDuplicate(message)) return false;
-      this.trackEventSeq(message);
-      return true;
-    }
-
-    private ackIfSequenced(message: CloudStatusMessage): void {
-      if (typeof message.seq !== "number") return;
-      this.sendCloudCommand({ type: "ack", seq: message.seq });
-    }
-
-    private isDuplicate(message: CloudStatusMessage): boolean {
-      const idempotencyKey =
-        typeof message.idempotency_key === "string" ? message.idempotency_key : undefined;
-      if (!idempotencyKey) return false;
-      if (state.seenIdempotencyKeys.has(idempotencyKey)) return true;
-      state.seenIdempotencyKeys.add(idempotencyKey);
-      state.seenIdempotencyOrder.push(idempotencyKey);
-      while (state.seenIdempotencyOrder.length > 1_000) {
-        const oldest = state.seenIdempotencyOrder.shift();
-        if (oldest) state.seenIdempotencyKeys.delete(oldest);
-      }
-      return false;
-    }
-
-    private trackEventSeq(message: CloudStatusMessage): void {
-      if (typeof message.event_seq !== "number") return;
-      if (state.lastEventSeq !== null && message.event_seq > state.lastEventSeq + 1) {
-        this.sendSync(true);
-      }
-      if (state.lastEventSeq === null || message.event_seq > state.lastEventSeq) {
-        state.lastEventSeq = message.event_seq;
-      }
-    }
-
-    private sendSync(recoverApprovals: boolean): void {
-      const target = state.controlSocket?.readyState === 1 ? state.controlSocket : this;
-      target.sendCloudCommand({
-        type: "sync",
-        runtime: state.runtime,
-        recover_approvals: recoverApprovals,
-        force_device_status: true,
-      });
-    }
-
-    sendCloudCommand(command: Record<string, unknown>): void {
-      if (this.readyState !== 1) return;
-      try {
-        this.socket.send(JSON.stringify(command));
-      } catch {
-        // Best-effort Cloud status reliability command.
-      }
-    }
-
-    private startPing(intervalMs: number): void {
-      if (this.pingTimer) return;
-      this.pingTimer = setInterval(() => {
-        this.sendCloudCommand({ type: "ping" });
-      }, intervalMs);
-      (this.pingTimer as { unref?: () => void }).unref?.();
-    }
-
-    private stopPing(): void {
-      if (!this.pingTimer) return;
-      clearInterval(this.pingTimer);
-      this.pingTimer = null;
-    }
-  }
-
-  return CloudStatusSocketAdapter as AppServerSocketConstructor;
-}
-
 function isCloudConversation(value: unknown): value is CloudConversation & { id: string } {
   return Boolean(value && typeof value === "object" && typeof (value as CloudConversation).id === "string");
 }
@@ -638,24 +392,6 @@ export function assertCloudSessionOptionsSupported(
   if (options.environment !== undefined && options.sandbox !== undefined) {
     throw new Error(`Letta Cloud ${action}() cannot specify both environment and sandbox options.`);
   }
-  if (options.systemPrompt !== undefined) {
-    throw new Error(`Letta Cloud ${action}() cannot rewrite an existing agent's systemPrompt from the SDK adapter yet.`);
-  }
-  if (options.disallowedTools !== undefined) {
-    throw new Error(`Letta Cloud ${action}() has not wired disallowedTools to the remote device protocol yet.`);
-  }
-  if (options.systemInfoReminder !== undefined) {
-    throw new Error(`Letta Cloud ${action}() has not wired systemInfoReminder to the remote device protocol yet.`);
-  }
-  if (options.dreaming?.behavior !== undefined) {
-    throw new Error(`Letta Cloud ${action}() does not yet support dreaming.behavior overrides.`);
-  }
-  if ((options as { memfsStartup?: unknown }).memfsStartup !== undefined) {
-    throw new Error(`Letta Cloud ${action}() does not support memfsStartup.`);
-  }
-  if (options.includePartialMessages !== undefined) {
-    throw new Error(`Letta Cloud ${action}() streams Remote Client deltas directly; includePartialMessages is not a separate toggle.`);
-  }
 }
 
 export class CloudEnvironmentSession extends RemoteClientSessionCore {
@@ -699,8 +435,14 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     });
     const client = applyUniqueRequestIds(createAppServerClient({
       url,
-      WebSocket: createCloudStatusWebSocketConstructor({
-        cloudOptions: this.cloudOptions,
+      WebSocket: createCloudStatusTransportConstructor({
+        url,
+        WebSocket: getWebSocketConstructor(this.cloudOptions.WebSocket),
+        ...((this.cloudOptions.webSocketAuth ?? "header") === "header"
+          ? { headers: cloudWebSocketHeaders(this.cloudOptions) }
+          : {}),
+        pingIntervalMs:
+          this.cloudOptions.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS,
         runtime: resolved.runtime,
       }),
       requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS,

package/src/cloud-status-transport.ts

@@ -0,0 +1,305 @@
+import type {
+  AppServerSocketConstructor,
+  AppServerSocketLike,
+  AppServerSocketOptions,
+} from "@letta-ai/letta-code/app-server-client";
+import type { ProtocolMessage, RuntimeScope } from "./remote-session-protocol.js";
+import type {
+  LettaCodeSocketConstructor,
+  LettaCodeSocketLike,
+} from "./types.js";
+
+type CloudStatusMessage = ProtocolMessage & {
+  type: string;
+  seq?: unknown;
+  event_seq?: unknown;
+  idempotency_key?: unknown;
+};
+
+type CloudStatusTransportOptions = {
+  url: string;
+  WebSocket: LettaCodeSocketConstructor;
+  headers?: Record<string, string>;
+  pingIntervalMs: number;
+  runtime: RuntimeScope;
+};
+
+type SocketChannel = "control" | "stream";
+type Listener = (event: unknown) => void;
+
+const CONNECTING = 0;
+const OPEN = 1;
+const CLOSING = 2;
+const CLOSED = 3;
+const MAX_IDEMPOTENCY_KEYS = 1_000;
+
+function addSocketListener(
+  socket: LettaCodeSocketLike,
+  type: string,
+  listener: Listener,
+): () => void {
+  if (socket.addEventListener) {
+    socket.addEventListener(type, listener);
+    return () => socket.removeEventListener?.(type, listener);
+  }
+  if (socket.on) {
+    socket.on(type, listener);
+    return () => socket.off?.(type, listener);
+  }
+  throw new Error("WebSocket implementation does not support event listeners.");
+}
+
+function messageEventData(event: unknown): string | null {
+  if (typeof event === "string") return event;
+  if (!event || typeof event !== "object") return null;
+  const data = (event as { data?: unknown }).data;
+  if (typeof data === "string") return data;
+  if (data instanceof ArrayBuffer) {
+    return new TextDecoder().decode(data);
+  }
+  if (data instanceof Uint8Array) {
+    return new TextDecoder().decode(data);
+  }
+  return null;
+}
+
+function channelUrl(url: string, channel: SocketChannel): string {
+  const parsed = new URL(url);
+  parsed.searchParams.set("channel", channel);
+  return parsed.toString();
+}
+
+/**
+ * Cloud's status relay still exposes separate control and stream sockets.
+ *
+ * This adapter presents those two relay sockets as one AppServerSocketLike,
+ * allowing CloudSession to reuse AppServerClient's request correlation and
+ * the SDK's shared runtime controller without weakening the local app-server's
+ * strict one-socket contract. Remove it when LET-10236 migrates the relay.
+ */
+export class CloudStatusTransport implements AppServerSocketLike {
+  readonly controlSocket: LettaCodeSocketLike;
+  readonly streamSocket: LettaCodeSocketLike;
+
+  private state = CONNECTING;
+  private openedChannels = new Set<SocketChannel>();
+  private listeners = new Map<string, Set<Listener>>();
+  private removers: Array<() => void> = [];
+  private seenIdempotencyKeys = new Set<string>();
+  private seenIdempotencyOrder: string[] = [];
+  private lastEventSeq: number | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private closeEmitted = false;
+
+  constructor(private readonly options: CloudStatusTransportOptions) {
+    const socketOptions = options.headers
+      ? { headers: options.headers }
+      : undefined;
+    this.controlSocket = new options.WebSocket(
+      channelUrl(options.url, "control"),
+      socketOptions,
+    );
+    this.streamSocket = new options.WebSocket(
+      channelUrl(options.url, "stream"),
+      socketOptions,
+    );
+    this.bindSocket("control", this.controlSocket);
+    this.bindSocket("stream", this.streamSocket);
+    this.startPing();
+  }
+
+  get readyState(): number {
+    return this.state;
+  }
+
+  send(data: string): void {
+    if (this.state !== OPEN || this.controlSocket.readyState !== OPEN) {
+      throw new Error("Cloud status control socket is not open");
+    }
+    this.controlSocket.send(data);
+  }
+
+  close(): void {
+    if (this.state === CLOSED || this.state === CLOSING) return;
+    this.state = CLOSING;
+    this.stopPing();
+    this.closeUnderlyingSockets();
+    this.finishClose({});
+  }
+
+  addEventListener(type: string, listener: Listener): void {
+    let listeners = this.listeners.get(type);
+    if (!listeners) {
+      listeners = new Set();
+      this.listeners.set(type, listeners);
+    }
+    listeners.add(listener);
+  }
+
+  removeEventListener(type: string, listener: Listener): void {
+    this.listeners.get(type)?.delete(listener);
+  }
+
+  private bindSocket(
+    channel: SocketChannel,
+    socket: LettaCodeSocketLike,
+  ): void {
+    this.removers.push(
+      addSocketListener(socket, "open", () => {
+        this.openedChannels.add(channel);
+        if (this.openedChannels.size === 2 && this.state === CONNECTING) {
+          this.state = OPEN;
+          this.emit("open", {});
+        }
+      }),
+      addSocketListener(socket, "message", (event) => {
+        if (this.shouldForwardMessage(channel, socket, event)) {
+          this.emit("message", event);
+        }
+      }),
+      addSocketListener(socket, "error", (event) => {
+        this.emit("error", event);
+      }),
+      addSocketListener(socket, "close", (event) => {
+        if (this.state !== CLOSED) {
+          this.state = CLOSING;
+          this.stopPing();
+          this.closeUnderlyingSockets(socket);
+          this.finishClose(event);
+        }
+      }),
+    );
+  }
+
+  private shouldForwardMessage(
+    channel: SocketChannel,
+    socket: LettaCodeSocketLike,
+    event: unknown,
+  ): boolean {
+    const data = messageEventData(event);
+    if (!data) return true;
+    let message: CloudStatusMessage;
+    try {
+      message = JSON.parse(data) as CloudStatusMessage;
+    } catch {
+      return true;
+    }
+
+    this.ackIfSequenced(socket, message);
+    if (channel === "control" && message.type === "stream_delta") {
+      return false;
+    }
+    if (this.isDuplicate(message)) return false;
+    this.trackEventSequence(message);
+    return true;
+  }
+
+  private ackIfSequenced(
+    socket: LettaCodeSocketLike,
+    message: CloudStatusMessage,
+  ): void {
+    if (typeof message.seq !== "number") return;
+    this.sendCommand(socket, { type: "ack", seq: message.seq });
+  }
+
+  private isDuplicate(message: CloudStatusMessage): boolean {
+    const key =
+      typeof message.idempotency_key === "string"
+        ? message.idempotency_key
+        : null;
+    if (!key) return false;
+    if (this.seenIdempotencyKeys.has(key)) return true;
+    this.seenIdempotencyKeys.add(key);
+    this.seenIdempotencyOrder.push(key);
+    while (this.seenIdempotencyOrder.length > MAX_IDEMPOTENCY_KEYS) {
+      const oldest = this.seenIdempotencyOrder.shift();
+      if (oldest) this.seenIdempotencyKeys.delete(oldest);
+    }
+    return false;
+  }
+
+  private trackEventSequence(message: CloudStatusMessage): void {
+    if (typeof message.event_seq !== "number") return;
+    if (
+      this.lastEventSeq !== null &&
+      message.event_seq > this.lastEventSeq + 1
+    ) {
+      this.sendCommand(this.controlSocket, {
+        type: "sync",
+        runtime: this.options.runtime,
+        recover_approvals: true,
+        force_device_status: true,
+      });
+    }
+    if (
+      this.lastEventSeq === null ||
+      message.event_seq > this.lastEventSeq
+    ) {
+      this.lastEventSeq = message.event_seq;
+    }
+  }
+
+  private sendCommand(
+    socket: LettaCodeSocketLike,
+    command: Record<string, unknown>,
+  ): void {
+    if (socket.readyState !== OPEN) return;
+    try {
+      socket.send(JSON.stringify(command));
+    } catch {
+      // ACK, sync recovery, and ping are best-effort relay reliability frames.
+    }
+  }
+
+  private startPing(): void {
+    this.pingTimer = setInterval(() => {
+      this.sendCommand(this.controlSocket, { type: "ping" });
+      this.sendCommand(this.streamSocket, { type: "ping" });
+    }, this.options.pingIntervalMs);
+    (this.pingTimer as { unref?: () => void }).unref?.();
+  }
+
+  private stopPing(): void {
+    if (!this.pingTimer) return;
+    clearInterval(this.pingTimer);
+    this.pingTimer = null;
+  }
+
+  private closeUnderlyingSockets(
+    except?: LettaCodeSocketLike,
+  ): void {
+    for (const socket of [this.controlSocket, this.streamSocket]) {
+      if (
+        socket !== except &&
+        (socket.readyState === CONNECTING || socket.readyState === OPEN)
+      ) {
+        socket.close();
+      }
+    }
+  }
+
+  private finishClose(event: unknown): void {
+    if (this.closeEmitted) return;
+    this.closeEmitted = true;
+    this.state = CLOSED;
+    this.stopPing();
+    for (const remove of this.removers.splice(0)) remove();
+    this.emit("close", event);
+  }
+
+  private emit(type: string, event: unknown): void {
+    for (const listener of this.listeners.get(type) ?? []) {
+      listener(event);
+    }
+  }
+}
+
+export function createCloudStatusTransportConstructor(
+  options: CloudStatusTransportOptions,
+): AppServerSocketConstructor {
+  return class CloudStatusTransportSocket extends CloudStatusTransport {
+    constructor(_url: string, _socketOptions?: AppServerSocketOptions) {
+      super(options);
+    }
+  };
+}