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

package/src/types.ts

@@ -109,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
 // ═══════════════════════════════════════════════════════════════
@@ -663,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`).
@@ -730,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);