@letta-ai/letta-agent-sdk 0.6.0 → 0.6.2

package/src/app-server-session.ts

@@ -11,12 +11,7 @@ import type {
   RuntimeStartResponseMessage,
   UpdateModelResponseMessage,
 } from "@letta-ai/letta-code/app-server-protocol";
-import {
-  buildSystemPrompt,
-  GIT_MEMORY_ENABLED_TAG,
-  LETTA_CODE_ORIGIN_TAG,
-} from "@letta-ai/letta-code/agent-presets";
-import { buildInitialAgentBody } from "./agent-creation.js";
+import { createAgentBody } from "./agent-creation.js";
 import { normalizeAppServerModels } from "./app-server-models.js";
 import {
   buildCanUseToolContext,
@@ -99,152 +94,10 @@ export type AppServerSessionOptions = Partial<LettaCodeRemoteClientOptions> & {
   connect?: (
     sessionEnv?: Record<string, string>,
   ) => Promise<{ url: string; close(): void }>;
-  /** Whether SDK create-agent payloads should add the origin tag automatically. */
-  includeSdkOriginTag?: boolean;
 };
 
 export type AppServerSessionMode = RuntimeSessionMode;
 
-function isPresetSystemPrompt(value: string): boolean {
-  return [
-    "default",
-    "letta-claude",
-    "letta-codex",
-    "letta-gemini",
-    "claude",
-    "codex",
-    "gemini",
-  ].includes(value);
-}
-
-function assertRemoteCreateAgentOptionsSupported(options: CreateAgentOptions): void {
-  if (options.allowedTools !== undefined || options.disallowedTools !== undefined) {
-    throw new Error("App-server createAgent() does not yet support allowedTools/disallowedTools.");
-  }
-  if (options.canUseTool !== undefined) {
-    throw new Error("App-server createAgent() does not yet support canUseTool callbacks.");
-  }
-  if (options.systemInfoReminder !== undefined) {
-    throw new Error("App-server createAgent() does not yet support systemInfoReminder overrides.");
-  }
-  if (options.dreaming?.behavior !== undefined) {
-    throw new Error("App-server createAgent() does not yet support dreaming.behavior overrides.");
-  }
-}
-
-function normalizeMemoryBlock(block: Record<string, unknown>): Record<string, unknown> {
-  const normalized = { ...block };
-  if (normalized.value === undefined && typeof normalized.content === "string") {
-    normalized.value = normalized.content;
-  }
-  return normalized;
-}
-
-function upsertMemoryBlock(
-  blocks: Array<Record<string, unknown>>,
-  block: Record<string, unknown>,
-): void {
-  const label = block.label;
-  if (typeof label === "string") {
-    const existingIndex = blocks.findIndex((candidate) => candidate.label === label);
-    if (existingIndex >= 0) {
-      blocks[existingIndex] = block;
-      return;
-    }
-  }
-  blocks.push(block);
-}
-
-export async function createAgentBody(
-  options: CreateAgentOptions,
-  settings: { includeSdkOriginTag?: boolean } = {},
-): Promise<Record<string, unknown>> {
-  assertRemoteCreateAgentOptionsSupported(options);
-
-  const includeOriginTag = settings.includeSdkOriginTag ?? true;
-  const body = await buildInitialAgentBody(options);
-
-  if (Array.isArray(body.tags)) {
-    body.tags = body.tags.filter(
-      (tag) =>
-        (includeOriginTag || tag !== LETTA_CODE_ORIGIN_TAG) &&
-        (options.memfs !== false || tag !== GIT_MEMORY_ENABLED_TAG),
-    );
-  }
-
-  if (options.embedding !== undefined) body.embedding = options.embedding;
-  if (options.hidden !== undefined) body.hidden = options.hidden;
-  // When baseTools is omitted, the harness applies its created-agent
-  // defaults (web_search, fetch_webpage). An explicit list is pinned exactly:
-  // `tools` alone does not suppress the Letta agent type's defaults, so both
-  // default tool attachment and its default tool rules are disabled here.
-  if (options.baseTools === undefined) {
-    delete body.tools;
-    delete body.include_base_tools;
-    delete body.include_base_tool_rules;
-  } else {
-    body.tools = options.baseTools;
-    body.include_base_tools = false;
-    body.include_base_tool_rules = false;
-  }
-
-  if (options.systemPrompt === undefined) {
-    if (options.memfs === false) {
-      body.system = buildSystemPrompt("default", "standard");
-    }
-  } else {
-    if (typeof options.systemPrompt === "string") {
-      if (isPresetSystemPrompt(options.systemPrompt)) {
-        throw new Error("createAgent() does not yet support system prompt presets for this backend.");
-      }
-      body.system = options.systemPrompt;
-    } else {
-      throw new Error("createAgent() does not yet support system prompt preset objects for this backend.");
-    }
-  }
-
-  const hasMemoryConfiguration =
-    Array.isArray(body.memory_blocks) ||
-    options.memory !== undefined ||
-    options.persona !== undefined ||
-    options.human !== undefined;
-  const memoryBlocks = Array.isArray(body.memory_blocks)
-    ? body.memory_blocks
-        .filter(
-          (block): block is Record<string, unknown> =>
-            block !== null && typeof block === "object",
-        )
-        .map((block) => ({ ...block }))
-    : [];
-  const blockIds: string[] = [];
-  for (const item of options.memory ?? []) {
-    if (typeof item === "string") {
-      throw new Error("App-server createAgent() does not yet support memory preset names.");
-    }
-    if ("blockId" in item) {
-      blockIds.push(item.blockId);
-    } else {
-      upsertMemoryBlock(
-        memoryBlocks,
-        normalizeMemoryBlock(item as unknown as Record<string, unknown>),
-      );
-    }
-  }
-  if (options.persona !== undefined) {
-    upsertMemoryBlock(memoryBlocks, {
-      label: "persona",
-      value: options.persona,
-    });
-  }
-  if (options.human !== undefined) {
-    upsertMemoryBlock(memoryBlocks, { label: "human", value: options.human });
-  }
-  if (hasMemoryConfiguration) body.memory_blocks = memoryBlocks;
-  if (blockIds.length > 0) body.block_ids = blockIds;
-
-  return body;
-}
-
 export function externalToolGroups(tools: AnyAgentTool[] | undefined): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return [
@@ -779,6 +632,8 @@ export class AppServerSession extends RemoteClientSessionCore {
         throw new Error(response.error ?? "Failed to start app-server runtime");
       }
 
+      this.watchTransportDisconnect(client);
+
       const tools = agentToolNames(response.agent);
       const skillSources = options.skillSources;
       const clientToolset = "toolset" in options ? options.toolset : undefined;
@@ -883,9 +738,7 @@ export class AppServerSession extends RemoteClientSessionCore {
 
     if (this.mode.kind === "create-agent") {
       command.create_agent = {
-        body: await createAgentBody(this.mode.options, {
-          includeSdkOriginTag: this.remoteOptions.includeSdkOriginTag,
-        }),
+        body: await createAgentBody(this.mode.options),
         // Hidden (worker-style) agents default to unpinned.
         pin_global:
           this.remoteOptions.pinGlobalAgent ??

package/src/client-base.ts

@@ -86,8 +86,8 @@ function looksLikeConversationId(id: string): boolean {
   return id.startsWith("conv-") || id.startsWith("local-conv-");
 }
 
-type TurnSession = LettaCodeSession & {
-  runTurn(message: SendMessage): Promise<SDKResultMessage>;
+type OneShotSession = LettaCodeSession & {
+  sendAndWaitForResult(message: SendMessage): Promise<SDKResultMessage>;
 };
 
 /**
@@ -314,7 +314,10 @@ export class LettaAgentClientBase {
     return this.resumeLocalSession(id, options);
   }
 
-  /** One-shot prompt convenience helper using a new conversation. */
+  /**
+   * One-shot convenience for scripts, smoke tests, and evals.
+   * Applications should use a session when they need interactive turn state.
+   */
   async prompt(
     message: SendMessage,
     agentId: string,
@@ -323,7 +326,7 @@ export class LettaAgentClientBase {
     const session = this.createSession(agentId, options);
 
     try {
-      return await (session as TurnSession).runTurn(message);
+      return await (session as OneShotSession).sendAndWaitForResult(message);
     } finally {
       session.close();
     }

package/src/cloud-management.ts

@@ -74,6 +74,23 @@ function isNotFound(error: unknown): boolean {
   return error instanceof APIError && error.status === 404;
 }
 
+/**
+ * The SDK cursor contract is chronological: `before` always means older and
+ * `after` always means newer. The Cloud REST API interprets cursors relative
+ * to sort order instead, and its default order is newest-first, so descending
+ * requests need their cursor keys swapped at this boundary. The app-server
+ * transport already receives chronological cursors and must not swap.
+ */
+function toOrderRelativeCursors(query: MessageListParams): MessageListParams {
+  if ((query.order ?? "desc") !== "desc") return query;
+  const { before, after, ...rest } = query;
+  return {
+    ...rest,
+    ...(after != null ? { before: after } : {}),
+    ...(before != null ? { after: before } : {}),
+  };
+}
+
 /** Cloud management backed by the canonical generated Letta TypeScript client. */
 export class CloudManagementTransport implements ManagementTransport {
   constructor(private readonly client: Letta) {}
@@ -206,7 +223,7 @@ export class CloudManagementTransport implements ManagementTransport {
   ): Promise<ConversationMessagesResult> {
     const page = await this.client.conversations.messages.list(
       conversationId,
-      query,
+      toOrderRelativeCursors(query),
     );
     return { messages: page.items };
   }

package/src/cloud-session.ts

@@ -5,10 +5,10 @@ import {
   createAppServerClient,
   type AppServerClient,
 } from "@letta-ai/letta-code/app-server-client";
+import { createAgentBody } from "./agent-creation.js";
 import {
   AppServerRuntimeController,
   agentToolNames,
-  createAgentBody,
   createExternalToolCallHandler,
   externalToolGroups,
   registerAppServerControlRequestHandler,
@@ -398,6 +398,8 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
         throw new Error(response.error ?? "Failed to start Cloud status runtime");
       }
 
+      this.watchTransportDisconnect(client);
+
       const tools = agentToolNames(response.agent);
       const skillSources = options.skillSources;
       const clientToolset = "toolset" in options ? options.toolset : undefined;

package/src/index.ts

@@ -5,7 +5,7 @@
  *
  * @example
  * ```typescript
- * import { LettaAgentClient, createAgent, createSession, resumeSession, prompt } from '@letta-ai/letta-agent-sdk';
+ * import { LettaAgentClient, createAgent, createSession, resumeSession } from '@letta-ai/letta-agent-sdk';
  *
  * const client = new LettaAgentClient({ backend: 'local' });
  * const agentId = await client.createAgent();
@@ -23,8 +23,6 @@
  * // Create new conversation on specific agent
  * const session = createSession(agentId);
  *
- * // One-shot prompt in a new conversation
- * const result = await prompt('Hello', agentId);
  * ```
  */
 
@@ -83,7 +81,6 @@ export type {
   SDKProtocolMessage,
   SDKProtocolCommand,
   SendCommandOptions,
-  RunTurnOptions,
   RecoverPendingApprovalsOptions,
   RecoverPendingApprovalsResult,
   ChangeDeviceStateOptions,
@@ -265,18 +262,20 @@ export function resumeSession(
 }
 
 /**
- * One-shot prompt convenience function.
+ * One-shot convenience for scripts, smoke tests, and evals.
  *
- * Uses the specified agent in a new conversation.
- * - Uses a short-lived session and returns the final turn result.
+ * Creates a short-lived conversation, waits for the final result, and closes
+ * the session. Applications that need streaming, approvals, cancellation,
+ * queueing, or continued interaction should use createSession() with send()
+ * and stream() instead.
  *
  * @example
  * ```typescript
  * const result = await prompt('What is the capital of France?', agentId);  // specific agent
  * ```
  */
-type TurnSession = LettaCodeSession & {
-  runTurn(message: SendMessage): Promise<SDKResultMessage>;
+type OneShotSession = LettaCodeSession & {
+  sendAndWaitForResult(message: SendMessage): Promise<SDKResultMessage>;
 };
 
 type InitializableSession = LettaCodeSession & {
@@ -291,7 +290,7 @@ export async function prompt(
   const session = createSession(agentId, options);
 
   try {
-    return await (session as TurnSession).runTurn(message);
+    return await (session as OneShotSession).sendAndWaitForResult(message);
   } finally {
     session.close();
   }

package/src/management-types.ts

@@ -81,8 +81,11 @@ export interface UpdateConversationOptions {
 }
 
 export interface ConversationMessagesOptions {
+  /** Return messages before this message ID (cursor for older pages, regardless of `order`). */
   before?: Present<MessageListParams["before"]>;
+  /** Return messages after this message ID (cursor for newer pages, regardless of `order`). */
   after?: Present<MessageListParams["after"]>;
+  /** Sort order of the returned page. Defaults to "desc" (newest first). */
   order?: "asc" | "desc";
   limit?: Present<MessageListParams["limit"]>;
 }

package/src/remote-client-session-core.ts

@@ -13,7 +13,6 @@ import type {
   RecoverPendingApprovalsOptions,
   RecoverPendingApprovalsResult,
   RemoveQueuedMessageResult,
-  RunTurnOptions,
   SDKInitMessage,
   SDKMessage,
   SDKProtocolCommand,
@@ -78,6 +77,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
   private readonly requestTimeoutMs: number | undefined;
   private initializePromise: Promise<SDKInitMessage> | null = null;
   private removeMessageHandler: (() => void) | null = null;
+  private detachTransportDisconnect: (() => void) | null = null;
   private readonly turns: RemoteTurnCoordinator;
   private toolNames: string[] | undefined;
   private deviceStatusListeners = new Set<(status: SessionDeviceStatus) => void>();
@@ -189,6 +189,8 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
   private cleanupFailedInitialize(): void {
     this.removeMessageHandler?.();
     this.removeMessageHandler = null;
+    this.detachTransportDisconnect?.();
+    this.detachTransportDisconnect = null;
     this.controller?.close();
     this.controller = null;
     // Subclass-owned resources (spawned connections, sandboxes, handlers)
@@ -225,10 +227,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     }
   }
 
-  async runTurn(
-    message: SendMessage,
-    _options: RunTurnOptions = {},
-  ): Promise<SDKResultMessage> {
+  async sendAndWaitForResult(message: SendMessage): Promise<SDKResultMessage> {
     if (this.turns.hasInFlightTurn()) {
       throw new Error(
         `A turn is already in flight for this ${this.label} session. Use send() and stream() to let the listener queue messages.`,
@@ -547,6 +546,8 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     this.closed = true;
     this.removeMessageHandler?.();
     this.removeMessageHandler = null;
+    this.detachTransportDisconnect?.();
+    this.detachTransportDisconnect = null;
     this.turns.close();
     for (const cancel of [...this.deviceStatusRefreshCancels]) {
       cancel(new Error(`Session closed while waiting for ${this.label} device status`));
@@ -623,6 +624,35 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
 
   protected abstract initializeRuntimeController(): Promise<RuntimeSessionInit>;
 
+  /**
+   * Fail the session when its transport drops unexpectedly.
+   *
+   * Without this an in-flight turn parks forever: nextMessage() only settles
+   * through the coordinator, and the socket's own pending-request rejection
+   * covers request/response commands, not streaming turns.
+   *
+   * The session is not revived — the runtime lived on the dead socket. The
+   * caller observes the error and rebuilds via resumeSession().
+   *
+   * Subclasses call this only once their runtime is live: a drop before that
+   * already surfaces as a rejected connect or runtime-start, and failing the
+   * session there would defeat initialize()'s retry path. Explicit closes do
+   * not notify, so this fires for faults only. Detaching stays here so every
+   * teardown path — clean close and failed initialize alike — covers it.
+   */
+  protected watchTransportDisconnect(client: {
+    onDisconnect(handler: () => void): () => void;
+  }): void {
+    this.detachTransportDisconnect?.();
+    this.detachTransportDisconnect = client.onDisconnect(() => {
+      if (this.closed) return;
+      this.turns.closeWithError(
+        `The ${this.label} connection closed unexpectedly; resume the conversation to continue.`,
+      );
+      this.close();
+    });
+  }
+
   protected async afterRuntimeInitialized(): Promise<void> {
     // Optional hook for subclasses to send transport-specific startup frames.
   }

package/src/remote-turn-coordinator.ts

@@ -160,6 +160,33 @@ export class RemoteTurnCoordinator {
     });
   }
 
+  /**
+   * Close after the transport dropped, surfacing the failure to stream
+   * consumers first.
+   *
+   * A plain close() resolves waiting consumers with `null`, which is
+   * indistinguishable from a conversation ending normally. A dead socket
+   * cannot deliver a turn-scoped failure of its own, so the error is
+   * synthesized here before the queue drains.
+   */
+  closeWithError(detail: string): void {
+    if (this.closed) return;
+    const active = this.activeTurn;
+    if (active) {
+      this.failTurn(active, detail);
+    } else {
+      this.enqueue({
+        type: "error",
+        message: detail,
+        errorCode: "error",
+        stopReason: "error",
+        errorDetail: detail,
+        recoverable: false,
+      });
+    }
+    this.close();
+  }
+
   close(): void {
     if (this.closed) return;
     this.closed = true;

package/src/types.ts

@@ -68,20 +68,6 @@ export interface TextContent {
   text: string;
 }
 
-export interface RunTurnOptions {
-  /**
-   * Max automatic approval-conflict recovery attempts for this turn.
-   * Overrides session-level maxApprovalRecoveryAttempts when provided.
-   */
-  maxApprovalRecoveryAttempts?: number;
-
-  /**
-   * Timeout in milliseconds for each approval recovery request.
-   * Overrides session-level approvalRecoveryTimeoutMs when provided.
-   */
-  recoveryTimeoutMs?: number;
-}
-
 export interface RecoverPendingApprovalsOptions {
   /**
    * Timeout in milliseconds for the recovery control request.
@@ -711,17 +697,6 @@ export interface CreateSessionOptions {
    */
   mcpServers?: McpServers;
 
-  /**
-   * 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;
-
   /**
    * Cloud repository resources to attach for the lifetime of the SDK session.
    * For relationships that should outlive the session, use

package/src/validation.ts

@@ -54,28 +54,6 @@ function getBlockLabels(memory: MemoryItem[]): string[] {
     .filter((label): label is string => label !== null);
 }
 
-function validateApprovalRecoveryOptions(options: CreateSessionOptions): void {
-  if (
-    options.maxApprovalRecoveryAttempts !== undefined &&
-    (!Number.isInteger(options.maxApprovalRecoveryAttempts) ||
-      options.maxApprovalRecoveryAttempts < 0)
-  ) {
-    throw new Error(
-      "Invalid maxApprovalRecoveryAttempts. Expected a non-negative integer."
-    );
-  }
-
-  if (
-    options.approvalRecoveryTimeoutMs !== undefined &&
-    (!Number.isInteger(options.approvalRecoveryTimeoutMs) ||
-      options.approvalRecoveryTimeoutMs <= 0)
-  ) {
-    throw new Error(
-      "Invalid approvalRecoveryTimeoutMs. Expected a positive integer."
-    );
-  }
-}
-
 function validateRemovedSessionOptions(options: CreateSessionOptions): void {
   const removedOptions = options as CreateSessionOptions & Record<string, unknown>;
   if (removedOptions.systemPrompt !== undefined) {
@@ -250,7 +228,6 @@ export function validateCreateSessionOptions(options: CreateSessionOptions): voi
   validateMcpServers(options.mcpServers);
   validateReasoningEffort(options.reasoningEffort);
   validateDreamingOptions(options.dreaming);
-  validateApprovalRecoveryOptions(options);
   validateRemovedSessionOptions(options);
 }