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

package/src/types.ts

@@ -17,6 +17,7 @@ import type {
 import type { Message as LettaMessage } from "@letta-ai/letta-client/resources/agents/messages";
 import type { CreateBlock } from "@letta-ai/letta-client/resources/blocks/blocks";
 import type { LettaCodeCloudSandboxOptions } from "./cloud-sandbox.js";
+import type { ComputerSelector } from "./computers.js";
 export type { CreateBlock } from "@letta-ai/letta-client/resources/blocks/blocks";
 export type {
   GitHubRepositoryRef,
@@ -108,6 +109,25 @@ export type MessageContentItem = TextContent | ImageContent;
  */
 export type SendMessage = string | MessageContentItem[];
 
+/**
+ * Per-turn options accepted by `send()`.
+ */
+export interface SendOptions {
+  /**
+   * Caller-supplied offline threading id (OTID) for this user message.
+   *
+   * The OTID is the canonical optimistic-input-matching key: stamp the row you
+   * render optimistically with the same value and you can correlate it with the
+   * persisted user message that comes back from the stream or from
+   * `listMessages()`. It is also used as the turn's `clientMessageId`, so it
+   * shows up on `SDKQueueItem.clientMessageId` while the message is queued.
+   *
+   * When omitted the SDK generates one. Must be a non-empty string; reuse the
+   * same value when retrying a send so the runtime can deduplicate it.
+   */
+  otid?: string;
+}
+
 // ═══════════════════════════════════════════════════════════════
 // SKILLS / REMINDER / DREAMING TYPES
 // ═══════════════════════════════════════════════════════════════
@@ -301,18 +321,8 @@ export type McpServers = Record<string, McpServerConfig>;
  */
 export type LettaCodeBackend = "local" | "remote" | "cloud";
 
-/**
- * Stable execution target for remote/cloud runtimes.
- *
- * Strings are treated as human-readable environment names. Object forms allow
- * callers to avoid relying on names as unique identifiers.
- */
-export type LettaCodeEnvironment =
-  | string
-  | { name: string }
-  | { id: string }
-  | { connectionId: string }
-  | { deviceId: string };
+/** @deprecated Use `ComputerSelector` from the package root. */
+export type LettaCodeEnvironment = ComputerSelector;
 
 export interface LettaCodeLocalAppServerOptions {
   /**
@@ -383,11 +393,13 @@ export interface LettaCodeCloudClientOptions {
   /** Heartbeat interval for the Cloud status websocket. Defaults to 30s. */
   pingIntervalMs?: number;
   /**
-   * Execution target for Letta Cloud sessions. If omitted, the SDK creates
-   * and owns a sandbox for the session.
+   * Computer where Letta Cloud sessions run. If omitted, the SDK creates and
+   * owns a managed sandbox for the session.
    */
+  computer?: ComputerSelector;
+  /** @deprecated Use `computer`. */
   environment?: LettaCodeEnvironment;
-  /** Options for SDK-managed sandboxes when environment is omitted. */
+  /** Options for SDK-managed sandboxes when no computer is selected. */
   sandbox?: LettaCodeCloudSandboxOptions;
 }
 
@@ -670,6 +682,13 @@ export interface CreateSessionOptions {
   /** Working directory for the CLI process */
   cwd?: string;
 
+  /**
+   * Run without loading or changing the agent's MemFS. The agent and
+   * conversation remain persistent; this only changes the session's local
+   * memory, agent-skill, agent-mod, transcript, and reflection behavior.
+   */
+  stateless?: boolean;
+
   /**
    * Restrict available skills by source.
    * Empty array disables all skills (`--no-skills`).
@@ -709,12 +728,14 @@ export interface CreateSessionOptions {
 /**
  * Session options accepted by LettaAgentClient methods.
  *
- * `environment` is a cloud execution-target override. It is deliberately
+ * `computer` is a Cloud execution-target override. It is deliberately
  * session-scoped rather than part of createAgent() options.
  */
 export interface LettaCodeClientSessionOptions extends CreateSessionOptions {
+  computer?: ComputerSelector;
+  /** @deprecated Use `computer`. */
   environment?: LettaCodeEnvironment;
-  /** Per-session SDK-managed sandbox options when environment is omitted. */
+  /** Per-session SDK-managed sandbox options when no computer is selected. */
   sandbox?: LettaCodeCloudSandboxOptions;
   /**
    * Extra environment variables for the session's harness process. Each
@@ -735,7 +756,11 @@ export interface LettaCodeClientSessionOptions extends CreateSessionOptions {
 }
 
 export interface LettaCodeSession extends AsyncDisposable {
-  send(message: SendMessage): Promise<void>;
+  /**
+   * Send a user message. Pass `{ otid }` to supply your own correlation id for
+   * optimistic reconciliation; the SDK generates one when omitted.
+   */
+  send(message: SendMessage, options?: SendOptions): Promise<void>;
   stream(): AsyncGenerator<SDKMessage>;
   abort(): Promise<void>;
   sendCommand(command: SDKProtocolCommand): Promise<void>;

package/src/validation.ts

@@ -223,6 +223,22 @@ function validateMcpServers(servers: McpServers | undefined): void {
  * Validate CreateSessionOptions (used by createSession and resumeSession).
  */
 export function validateCreateSessionOptions(options: CreateSessionOptions): void {
+  if (options.stateless !== undefined && typeof options.stateless !== "boolean") {
+    throw new Error("Invalid stateless. Expected a boolean.");
+  }
+  if (options.stateless) {
+    const persistedOption = [
+      ["model", options.model],
+      ["reasoningEffort", options.reasoningEffort],
+      ["dreaming", options.dreaming],
+      ["resources", options.resources],
+    ].find(([, value]) => value !== undefined);
+    if (persistedOption) {
+      throw new Error(
+        `stateless sessions cannot set ${persistedOption[0]} because it changes persisted agent configuration.`,
+      );
+    }
+  }
   validateClientToolset(options.toolset);
   validateSkillSources(options.skillSources);
   validateMcpServers(options.mcpServers);