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

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);
+    }
+  };
+}

package/src/index.ts

@@ -11,9 +11,6 @@
  * const agentId = await client.createAgent();
  * const clientSession = client.resumeSession(agentId);
  *
- * // Start session with default agent + new conversation (like `letta`)
- * const session = createSession();
- *
  * // Create a new agent explicitly
  * const agentId = await createAgent();
  *
@@ -26,13 +23,11 @@
  * // Create new conversation on specific agent
  * const session = createSession(agentId);
  *
- * // One-shot prompt (uses default agent)
- * const result = await prompt('Hello');
- * const result = await prompt('Hello', agentId);  // specific agent
+ * // One-shot prompt in a new conversation
+ * const result = await prompt('Hello', agentId);
  * ```
  */
 
-import { Session } from "./session.js";
 import { LettaAgentClient } from "./client.js";
 import type {
   CreateSessionOptions,
@@ -98,6 +93,7 @@ export type {
   SessionDiffPreview,
   SkillSource,
   DreamingOptions,
+  SessionDreamingOptions,
   DreamingTrigger,
   DreamingBehavior,
   EffectiveDreamingSettings,
@@ -164,7 +160,6 @@ export type {
   ConversationMessagesResult,
 } from "./management-types.js";
 
-export { Session } from "./session.js";
 export { RepositoriesClient } from "./repositories.js";
 export { LettaAgentClient } from "./client.js";
 export { CloudManagedSandboxExpiredError } from "./cloud-session.js";
@@ -210,29 +205,20 @@ export async function createAgent(options: CreateAgentOptions = {}): Promise<str
 /**
  * Create a new conversation (session).
  *
- * - Without agentId: uses default/LRU agent with new conversation (like `letta`)
- * - With agentId: creates new conversation on specified agent
+ * Creates a new conversation on the specified agent.
  *
  * @example
  * ```typescript
- * // New conversation on default agent (like `letta`)
- * await using session = createSession();
- *
  * // New conversation on specific agent
  * await using session = createSession(agentId);
  * ```
  */
 export function createSession(
-  agentId?: string,
+  agentId: string,
   options: CreateSessionOptions = {},
 ): LettaCodeSession {
   validateCreateSessionOptions(options);
-  if (agentId) {
-    return new LettaAgentClient().createSession(agentId, options);
-  }
-  // The app-server runtime_start protocol requires an explicit agent id. Keep
-  // the historical default/LRU-agent helper on the legacy stdio transport.
-  return new LettaAgentClient({ backend: "local", transport: "stdio" }).createSession(options);
+  return new LettaAgentClient().createSession(agentId, options);
 }
 
 /**
@@ -264,13 +250,11 @@ export function resumeSession(
 /**
  * One-shot prompt convenience function.
  *
- * - Without agentId: uses default agent (like `letta -p`), new conversation
- * - With agentId: uses specific agent, new conversation
+ * Uses the specified agent in a new conversation.
  * - Uses a short-lived session and returns the final turn result.
  *
  * @example
  * ```typescript
- * const result = await prompt('What is 2+2?');  // default agent
  * const result = await prompt('What is the capital of France?', agentId);  // specific agent
  * ```
  */
@@ -283,13 +267,11 @@ type InitializableSession = LettaCodeSession & {
 };
 
 export async function prompt(
-  message: string,
-  agentId?: string
+  message: SendMessage,
+  agentId: string,
+  options: CreateSessionOptions = {},
 ): Promise<SDKResultMessage> {
-  // Use default agent behavior (like letta -p) when no agentId specified
-  const session = agentId
-    ? createSession(agentId)
-    : createSession();
+  const session = createSession(agentId, options);
 
   try {
     return await (session as TurnSession).runTurn(message);

package/src/local-app-server-session.ts

@@ -4,12 +4,14 @@ import {
   type AppServerSessionOptions,
 } from "./app-server-session.js";
 import { startLocalAppServer } from "./local-app-server.js";
-import type { LettaCodeLocalAppServerOptions } from "./types.js";
+import type {
+  LettaCodeClientSessionOptions,
+  LettaCodeLocalAppServerOptions,
+} from "./types.js";
 
 export function createLocalAppServerSession(
   options: LettaCodeLocalAppServerOptions | undefined,
   mode: AppServerSessionMode,
-  beforeConnect?: () => Promise<void>,
 ): AppServerSession {
   const appServer = options ?? {};
   const sessionOptions: AppServerSessionOptions = {
@@ -22,6 +24,15 @@ export function createLocalAppServerSession(
               backend: appServer.harnessBackend ?? "local",
               startupTimeoutMs: appServer.startupTimeoutMs,
               env: sessionEnv,
+              filesystemConfinement:
+                mode.kind === "session"
+                  ? (mode.options as LettaCodeClientSessionOptions)
+                      .filesystemConfinement
+                  : undefined,
+              agentId:
+                mode.kind === "session" && "agentId" in mode
+                  ? mode.agentId
+                  : undefined,
             }),
         }),
     ...(appServer.WebSocket !== undefined
@@ -33,7 +44,6 @@ export function createLocalAppServerSession(
     ...(appServer.pinGlobalAgent !== undefined
       ? { pinGlobalAgent: appServer.pinGlobalAgent }
       : {}),
-    ...(beforeConnect ? { beforeConnect } : {}),
   };
   return new AppServerSession(sessionOptions, mode);
 }

package/src/local-app-server.ts

@@ -1,4 +1,11 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  createMemoryConfinementLauncher,
+  type MemoryConfinementLauncherInput,
+  type MemoryConfinementLauncherResult,
+} from "@letta-ai/letta-code/memory-confinement";
 import { findLettaCli } from "./cli-resolver.js";
 
 export interface LocalAppServerHandle {
@@ -12,12 +19,70 @@ export interface StartLocalAppServerOptions {
   startupTimeoutMs?: number;
   cliPath?: string;
   env?: Record<string, string | undefined>;
+  filesystemConfinement?: "memory";
+  agentId?: string;
 }
 
+interface LocalAppServerProcess {
+  command: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+}
+
+type MemoryConfinementLauncher = (
+  input: MemoryConfinementLauncherInput,
+) => MemoryConfinementLauncherResult;
+
 const DEFAULT_LISTEN_URL = "ws://127.0.0.1:0";
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
 const LISTENING_RE = /^Listening on\s+(ws:\/\/\S+)\s*$/m;
 
+function targetHomeDirectory(env: NodeJS.ProcessEnv): string {
+  if (process.platform === "win32") {
+    const profile = env.USERPROFILE?.trim();
+    if (profile) return profile;
+    const drive = env.HOMEDRIVE?.trim();
+    const path = env.HOMEPATH?.trim();
+    if (drive && path) return `${drive}${path}`;
+    return homedir();
+  }
+  return env.HOME?.trim() || homedir();
+}
+
+function withDefaultMemoryDirectory(
+  env: NodeJS.ProcessEnv,
+  options: StartLocalAppServerOptions,
+): NodeJS.ProcessEnv {
+  const explicitMemoryDir = options.env?.MEMORY_DIR?.trim();
+  const explicitLettaMemoryDir = options.env?.LETTA_MEMORY_DIR?.trim();
+  const scopedEnv = { ...env };
+  if (explicitMemoryDir || explicitLettaMemoryDir) {
+    if (!explicitMemoryDir) delete scopedEnv.MEMORY_DIR;
+    if (!explicitLettaMemoryDir) delete scopedEnv.LETTA_MEMORY_DIR;
+    return scopedEnv;
+  }
+
+  // Never inherit the SDK process's agent scope into a different session.
+  delete scopedEnv.MEMORY_DIR;
+  delete scopedEnv.LETTA_MEMORY_DIR;
+  if (!options.agentId) return scopedEnv;
+
+  const homeDir = targetHomeDirectory(env);
+  // Mirrors Letta Code's getScopedMemoryFilesystemRoot contract. The SDK pins
+  // an exact Letta Code version so the launch policy and layout move together.
+  const memoryDir =
+    options.backend === "api"
+      ? join(homeDir, ".letta", "agents", options.agentId, "memory")
+      : join(
+          env.LETTA_LOCAL_BACKEND_DIR?.trim() ||
+            join(homeDir, ".letta", "lc-local-backend"),
+          "memfs",
+          options.agentId,
+          "memory",
+        );
+  return { ...scopedEnv, MEMORY_DIR: memoryDir };
+}
+
 function appendLine(buffer: string, chunk: unknown): string {
   return buffer + String(chunk);
 }
@@ -40,6 +105,35 @@ export function buildLocalAppServerArgs(
   ];
 }
 
+export function buildLocalAppServerProcess(
+  cliPath: string,
+  options: StartLocalAppServerOptions = {},
+  confineMemory: MemoryConfinementLauncher = createMemoryConfinementLauncher,
+): LocalAppServerProcess {
+  const env = { ...process.env, ...(options.env ?? {}) };
+  const launcher = [
+    process.execPath,
+    ...buildLocalAppServerArgs(cliPath, options),
+  ];
+  if (options.filesystemConfinement !== "memory") {
+    return {
+      command: launcher[0] as string,
+      args: launcher.slice(1),
+      env,
+    };
+  }
+
+  const confined = confineMemory({
+    launcher,
+    env: withDefaultMemoryDirectory(env, options),
+  });
+  return {
+    command: confined.launcher[0] as string,
+    args: confined.launcher.slice(1),
+    env: confined.env,
+  };
+}
+
 function terminateProcess(child: ChildProcess): void {
   if (child.exitCode !== null || child.signalCode !== null) return;
   child.kill("SIGTERM");
@@ -57,13 +151,13 @@ export function startLocalAppServer(
   options: StartLocalAppServerOptions = {},
 ): Promise<LocalAppServerHandle> {
   const cliPath = options.cliPath ?? findLettaCli();
-  const args = buildLocalAppServerArgs(cliPath, options);
+  const processSpec = buildLocalAppServerProcess(cliPath, options);
   const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
 
   return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, args, {
+    const child = spawn(processSpec.command, processSpec.args, {
       stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, ...(options.env ?? {}) },
+      env: processSpec.env,
     });
 
     let settled = false;

package/src/management.ts

@@ -45,13 +45,6 @@ export interface ManagementTransport {
     conversationId: string,
     query: ManagementQuery,
   ): Promise<ConversationMessagesResult>;
-  /**
-   * Release the pooled connection, waiting for in-flight work when necessary,
-   * so other clients of the same backend (for example sessions, which compete
-   * for the app-server's single control-client slot) can connect. Optional;
-   * transports whose backend has no such contention (Cloud REST) omit it.
-   */
-  releaseIdleConnection?(): Promise<void> | void;
 }
 
 type TransportProvider = () => ManagementTransport;

package/src/remote-session-protocol.ts

@@ -450,6 +450,20 @@ export function streamDeltaRunId(delta: Record<string, unknown>): string | undef
   return typeof delta.run_id === "string" ? delta.run_id : undefined;
 }
 
+export function streamDeltaOtid(
+  delta: Record<string, unknown>,
+): string | null | undefined {
+  return typeof delta.otid === "string" || delta.otid === null
+    ? delta.otid
+    : undefined;
+}
+
+export function streamDeltaSeqId(
+  delta: Record<string, unknown>,
+): number | undefined {
+  return typeof delta.seq_id === "number" ? delta.seq_id : undefined;
+}
+
 export function streamDeltaStopReason(delta: Record<string, unknown>): string | null | undefined {
   return typeof delta.stop_reason === "string" ? delta.stop_reason : undefined;
 }
@@ -650,6 +664,10 @@ export function toSessionDeviceStatus(
     isProcessing: status.is_processing,
     permissionMode,
     workingDirectory: status.current_working_directory,
+    memoryDirectory:
+      typeof status.memory_directory === "string"
+        ? status.memory_directory
+        : null,
     pendingControlRequests: pendingControlRequests(status),
     raw: { ...status },
   };

package/src/remote-turn-coordinator.ts

@@ -18,8 +18,10 @@ import {
   queueItems,
   sameRuntime,
   streamDeltaMessageType,
+  streamDeltaOtid,
   streamDeltaRecord,
   streamDeltaRunId,
+  streamDeltaSeqId,
   streamDeltaStopReason,
   toSdkErrorCode,
   toSessionDeviceStatus,
@@ -303,6 +305,8 @@ export class RemoteTurnCoordinator {
     const messageType =
       typeof delta.message_type === "string" ? delta.message_type : undefined;
     const runId = typeof delta.run_id === "string" ? delta.run_id : undefined;
+    const otid = streamDeltaOtid(delta);
+    const seqId = streamDeltaSeqId(delta);
     const uuid =
       typeof delta.id === "string"
         ? delta.id
@@ -312,7 +316,14 @@ export class RemoteTurnCoordinator {
       const content = extractTextFromContent(delta.content);
       if (!content) return null;
       if (this.activeTurn) this.activeTurn.assistantText += content;
-      return { type: "assistant", content, uuid, runId };
+      return {
+        type: "assistant",
+        content,
+        uuid,
+        ...(otid !== undefined ? { otid } : {}),
+        ...(seqId !== undefined ? { seqId } : {}),
+        runId,
+      };
     }
 
     if (messageType === "reasoning_message") {
@@ -321,7 +332,14 @@ export class RemoteTurnCoordinator {
           ? delta.reasoning
           : extractTextFromContent(delta.content);
       if (!content) return null;
-      return { type: "reasoning", content, uuid, runId };
+      return {
+        type: "reasoning",
+        content,
+        uuid,
+        ...(otid !== undefined ? { otid } : {}),
+        ...(seqId !== undefined ? { seqId } : {}),
+        runId,
+      };
     }
 
     if (