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

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

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 (

package/src/types.ts

@@ -5,27 +5,6 @@
  * Protocol types are defined locally to avoid relying on broken package subpath exports.
  */
 
-// Re-export protocol types for internal use
-export type {
-  WireMessage,
-  SystemInitMessage,
-  MessageWire,
-  ResultMessage,
-  ErrorMessage,
-  StreamEvent,
-  ControlRequest,
-  ControlResponse,
-  CanUseToolControlRequest,
-  CanUseToolResponse,
-  CanUseToolResponseAllow,
-  CanUseToolResponseDeny,
-  // Configuration types
-  SystemPromptPresetConfig,
-  CreateBlock,
-} from "./protocol.js";
-
-// Import types for use in this file
-import type { CreateBlock, CanUseToolResponse } from "./protocol.js";
 import type { PersonalityId } from "@letta-ai/letta-code/agent-presets";
 import type { LettaCodeCloudSandboxOptions } from "./cloud-sandbox.js";
 export type {
@@ -36,6 +15,26 @@ export type {
 /** Letta Code personality preset used to seed a new agent. */
 export type LettaCodePersonalityId = PersonalityId;
 
+/** Custom memory block definition accepted when creating agents. */
+export interface CreateBlock {
+  label: string;
+  value: string;
+  base_template_id?: string | null;
+  deployment_id?: string | null;
+  description?: string | null;
+  entity_id?: string | null;
+  hidden?: boolean | null;
+  is_template?: boolean;
+  limit?: number;
+  metadata?: Record<string, unknown> | null;
+  preserve_on_migration?: boolean | null;
+  project_id?: string | null;
+  read_only?: boolean;
+  tags?: string[] | null;
+  template_id?: string | null;
+  template_name?: string | null;
+}
+
 export interface LettaCodeSocketLike {
   readyState: number;
   send(data: string): void;
@@ -152,6 +151,9 @@ export interface DreamingOptions {
   stepCount?: number;
 }
 
+/** Dreaming settings that can be changed when opening an existing agent session. */
+export type SessionDreamingOptions = Omit<DreamingOptions, "behavior">;
+
 /**
  * Fully-resolved dreaming settings emitted by init messages.
  */
@@ -319,8 +321,6 @@ export interface LettaCodeLocalAppServerOptions {
   WebSocket?: LettaCodeSocketConstructor;
   /** Timeout for websocket protocol request/turn correlation. */
   requestTimeoutMs?: number;
-  /** Milliseconds an idle management connection may be reused before release. Defaults to 250. */
-  idleLingerMs?: number;
   /** Whether agents created through this app-server are added to Letta Code's global pinned-agent list. */
   pinGlobalAgent?: boolean;
   /** Local app-server listen URL when the SDK spawns it. Defaults to ws://127.0.0.1:0. */
@@ -331,9 +331,7 @@ export interface LettaCodeLocalAppServerOptions {
 
 export interface LettaCodeLocalClientOptions {
   backend?: "local";
-  /** Advanced local transport override. Defaults to app-server. */
-  transport?: "app-server" | "stdio";
-  /** Advanced app-server overrides for local transport. */
+  /** Advanced app-server overrides for local execution. */
   appServer?: LettaCodeLocalAppServerOptions;
 }
 
@@ -347,8 +345,6 @@ export interface LettaCodeRemoteClientOptions {
   WebSocket?: LettaCodeSocketConstructor;
   /** Timeout for websocket protocol request/turn correlation. */
   requestTimeoutMs?: number;
-  /** Milliseconds an idle management connection may be reused before release. Defaults to 250. */
-  idleLingerMs?: number;
   /** Whether agents created through this app-server are added to Letta Code's global pinned-agent list. */
   pinGlobalAgent?: boolean;
 }
@@ -496,6 +492,23 @@ export interface CanUseToolPermissionSuggestion {
   text: string;
 }
 
+export interface CanUseToolResponseAllow {
+  behavior: "allow";
+  message?: string;
+  updatedInput?: Record<string, unknown> | null;
+  updatedPermissions?: unknown[];
+}
+
+export interface CanUseToolResponseDeny {
+  behavior: "deny";
+  message: string;
+  interrupt?: boolean;
+}
+
+export type CanUseToolResponse =
+  | CanUseToolResponseAllow
+  | CanUseToolResponseDeny;
+
 /**
  * Additional context for a `can_use_tool` approval request, passed as the
  * optional third argument to {@link CanUseToolCallback}.
@@ -532,69 +545,6 @@ export type CanUseToolCallback = (
   context?: CanUseToolContext,
 ) => Promise<CanUseToolResponse> | CanUseToolResponse;
 
-/**
- * Internal session options used by Session/Transport classes.
- * Not user-facing - use CreateSessionOptions or CreateAgentOptions instead.
- * @internal
- */
-export interface InternalSessionOptions {
-  // Agent/conversation routing
-  agentId?: string;
-  conversationId?: string;
-  newConversation?: boolean;
-  defaultConversation?: boolean;
-  createOnly?: boolean;
-
-  // Agent configuration
-  model?: string;
-  reasoningEffort?: ReasoningEffort;
-  embedding?: string;
-  systemPrompt?: SystemPromptConfig;
-
-  // Memory blocks (only for new agents)
-  memory?: MemoryItem[];
-  persona?: string;  // Convenience for persona block
-  human?: string;    // Convenience for human block
-
-  // Tags (only for new agents)
-  tags?: string[];
-
-  // Skills/reminders
-  skillSources?: SkillSource[];
-  systemInfoReminder?: boolean;
-  dreaming?: DreamingOptions;
-
-  // Permissions
-  allowedTools?: string[];
-  disallowedTools?: string[];
-  permissionMode?: PermissionMode;
-  canUseTool?: CanUseToolCallback;
-
-  // Server-side tools (only for new agents); omitted -> harness defaults.
-  baseTools?: string[];
-
-  // Custom tools
-  tools?: AnyAgentTool[];
-
-  // Process settings
-  cwd?: string;
-
-  /** If true, pass --include-partial-messages to CLI for token-level stream_event chunks */
-  includePartialMessages?: boolean;
-
-  /**
-   * Max automatic approval-conflict recovery attempts per runTurn() call.
-   * Set to 0 to disable automatic recovery.
-   */
-  maxApprovalRecoveryAttempts?: number;
-
-  /**
-   * Timeout in milliseconds for a single approval recovery request.
-   */
-  approvalRecoveryTimeoutMs?: number;
-
-}
-
 export type PermissionMode =
   | "standard"
   | "acceptEdits"
@@ -662,7 +612,8 @@ export interface SendCommandOptions<TResponseType extends string = string> {
 }
 
 /**
- * Options for createSession() and resumeSession() - restricted to options that can be applied to existing agents (LRU/Memo).
+ * Options for createSession() and resumeSession() restricted to settings that
+ * can be applied to existing agents.
  * For creating new agents with custom memory/persona, use createAgent().
  */
 export interface CreateSessionOptions {
@@ -672,9 +623,6 @@ export interface CreateSessionOptions {
   /** Reasoning effort tier to use with the selected/current model on websocket protocol sessions. */
   reasoningEffort?: ReasoningEffort;
 
-  /** System prompt preset (only presets, no custom strings or append) - updates the agent */
-  systemPrompt?: SystemPromptPreset;
-
   /**
    * Exact client-side tool allowlist for the session, including custom SDK
    * tools. When omitted, the harness default toolset and registered custom
@@ -683,9 +631,6 @@ export interface CreateSessionOptions {
    */
   allowedTools?: string[];
 
-  /** List of disallowed tool names */
-  disallowedTools?: string[];
-
   /** Permission mode */
   permissionMode?: PermissionMode;
 
@@ -698,16 +643,10 @@ export interface CreateSessionOptions {
    */
   skillSources?: SkillSource[];
 
-  /**
-   * Toggle first-turn system info reminder (device/git/cwd context).
-   * false -> `--no-system-info-reminder`.
-   */
-  systemInfoReminder?: boolean;
-
   /**
    * Configure dreaming settings.
    */
-  dreaming?: DreamingOptions;
+  dreaming?: SessionDreamingOptions;
 
   /** Custom permission callback - called when tool needs approval */
   canUseTool?: CanUseToolCallback;
@@ -718,12 +657,6 @@ export interface CreateSessionOptions {
    */
   tools?: AnyAgentTool[];
 
-  /**
-   * If true, pass --include-partial-messages to CLI to receive token-level
-   * stream_event chunks for incremental assistant/reasoning rendering.
-   */
-  includePartialMessages?: boolean;
-
   /**
    * Max automatic approval-conflict recovery attempts per runTurn() call.
    * Set to 0 to disable automatic recovery.
@@ -758,6 +691,14 @@ export interface LettaCodeClientSessionOptions extends CreateSessionOptions {
    * memory copy. Ignored on remote and cloud transports.
    */
   env?: Record<string, string>;
+  /**
+   * Constrain an SDK-owned local session harness to memory-worker filesystem
+   * access. Agent-ID sessions derive the standard root; set `MEMORY_DIR` or
+   * `LETTA_MEMORY_DIR` for overrides and conversation-ID resumes. Fails closed
+   * without a root or supported kernel sandbox. Excludes agent creation,
+   * management calls, and remote/Cloud runtimes.
+   */
+  filesystemConfinement?: "memory";
 }
 
 export interface LettaCodeSession extends AsyncDisposable {
@@ -1044,7 +985,12 @@ export interface SDKInitMessage {
 export interface SDKAssistantMessage {
   type: "assistant";
   content: string;
+  /** Legacy transport identifier. Prefer `otid` for message lineage. */
   uuid: string;
+  /** Stable lineage key for this typed message slice, when provided. */
+  otid?: string | null;
+  /** Per-run replay cursor. Compare only within the same `runId`. */
+  seqId?: number;
   /** Run ID from the Letta API for this event (used for stale-run detection). */
   runId?: string;
 }
@@ -1074,7 +1020,12 @@ export interface SDKToolResultMessage {
 export interface SDKReasoningMessage {
   type: "reasoning";
   content: string;
+  /** Legacy transport identifier. Prefer `otid` for message lineage. */
   uuid: string;
+  /** Stable lineage key for this typed message slice, when provided. */
+  otid?: string | null;
+  /** Per-run replay cursor. Compare only within the same `runId`. */
+  seqId?: number;
   /** Run ID from the Letta API for this event (used for stale-run detection). */
   runId?: string;
 }
@@ -1126,6 +1077,8 @@ export interface SDKStreamEventMessagePayload {
   message_type: string;
   id?: string;
   otid?: string | null;
+  seq_id?: number;
+  run_id?: string;
   content?: unknown;
   reasoning?: string;
   name?: string;