@letta-ai/letta-client 1.3.2 → 1.4.0

package/src/resources/agents/agents.ts

@@ -106,6 +106,18 @@ import {
   UpdateUserMessage,
   UserMessage,
 } from './messages';
+import * as PassagesAPI from './passages';
+import {
+  PassageCreateParams,
+  PassageCreateResponse,
+  PassageDeleteParams,
+  PassageDeleteResponse,
+  PassageListParams,
+  PassageListResponse,
+  PassageSearchParams,
+  PassageSearchResponse,
+  Passages,
+} from './passages';
 import * as AgentsToolsAPI from './tools';
 import {
   ToolAttachParams,
@@ -139,6 +151,7 @@ export class Agents extends APIResource {
   files: FilesAPI.Files = new FilesAPI.Files(this._client);
   groups: GroupsAPI.Groups = new GroupsAPI.Groups(this._client);
   archives: ArchivesAPI.Archives = new ArchivesAPI.Archives(this._client);
+  passages: PassagesAPI.Passages = new PassagesAPI.Passages(this._client);
   identities: IdentitiesAPI.Identities = new IdentitiesAPI.Identities(this._client);
 
   /**
@@ -346,6 +359,15 @@ export interface AgentState {
    */
   base_template_id?: string | null;
 
+  /**
+   * Configuration for conversation compaction / summarization.
+   *
+   * `model` is the only required user-facing field – it specifies the summarizer
+   * model handle (e.g. `"openai/gpt-4o-mini"`). Per-model settings (temperature, max
+   * tokens, etc.) are derived from the default configuration for that handle.
+   */
+  compaction_settings?: AgentState.CompactionSettings | null;
+
   /**
    * The timestamp when the object was created.
    */
@@ -732,6 +754,64 @@ export namespace AgentState {
      */
     vector_db_provider?: ArchivesArchivesAPI.VectorDBProvider;
   }
+
+  /**
+   * Configuration for conversation compaction / summarization.
+   *
+   * `model` is the only required user-facing field – it specifies the summarizer
+   * model handle (e.g. `"openai/gpt-4o-mini"`). Per-model settings (temperature, max
+   * tokens, etc.) are derived from the default configuration for that handle.
+   */
+  export interface CompactionSettings {
+    /**
+     * Model handle to use for summarization (format: provider/model-name).
+     */
+    model: string;
+
+    /**
+     * The maximum length of the summary in characters. If none, no clipping is
+     * performed.
+     */
+    clip_chars?: number | null;
+
+    /**
+     * The type of summarization technique use.
+     */
+    mode?: 'all' | 'sliding_window';
+
+    /**
+     * Optional model settings used to override defaults for the summarizer model.
+     */
+    model_settings?:
+      | AgentsAPI.OpenAIModelSettings
+      | AgentsAPI.AnthropicModelSettings
+      | AgentsAPI.GoogleAIModelSettings
+      | AgentsAPI.GoogleVertexModelSettings
+      | AgentsAPI.AzureModelSettings
+      | AgentsAPI.XaiModelSettings
+      | AgentsAPI.GroqModelSettings
+      | AgentsAPI.DeepseekModelSettings
+      | AgentsAPI.TogetherModelSettings
+      | AgentsAPI.BedrockModelSettings
+      | null;
+
+    /**
+     * The prompt to use for summarization.
+     */
+    prompt?: string;
+
+    /**
+     * Whether to include an acknowledgement post-prompt (helps prevent non-summary
+     * outputs).
+     */
+    prompt_acknowledgement?: boolean;
+
+    /**
+     * The percentage of the context window to keep post-summarization (only used in
+     * sliding window mode).
+     */
+    sliding_window_percentage?: number;
+  }
 }
 
 /**
@@ -1299,7 +1379,7 @@ export namespace OpenAIModelSettings {
     /**
      * The reasoning effort to use when generating text reasoning models
      */
-    reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high';
+    reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
   }
 }
 
@@ -1481,6 +1561,15 @@ export interface AgentCreateParams {
    */
   block_ids?: Array<string> | null;
 
+  /**
+   * Configuration for conversation compaction / summarization.
+   *
+   * `model` is the only required user-facing field – it specifies the summarizer
+   * model handle (e.g. `"openai/gpt-4o-mini"`). Per-model settings (temperature, max
+   * tokens, etc.) are derived from the default configuration for that handle.
+   */
+  compaction_settings?: AgentCreateParams.CompactionSettings | null;
+
   /**
    * The context window limit used by the agent.
    */
@@ -1751,6 +1840,66 @@ export interface AgentCreateParams {
   tools?: Array<string> | null;
 }
 
+export namespace AgentCreateParams {
+  /**
+   * Configuration for conversation compaction / summarization.
+   *
+   * `model` is the only required user-facing field – it specifies the summarizer
+   * model handle (e.g. `"openai/gpt-4o-mini"`). Per-model settings (temperature, max
+   * tokens, etc.) are derived from the default configuration for that handle.
+   */
+  export interface CompactionSettings {
+    /**
+     * Model handle to use for summarization (format: provider/model-name).
+     */
+    model: string;
+
+    /**
+     * The maximum length of the summary in characters. If none, no clipping is
+     * performed.
+     */
+    clip_chars?: number | null;
+
+    /**
+     * The type of summarization technique use.
+     */
+    mode?: 'all' | 'sliding_window';
+
+    /**
+     * Optional model settings used to override defaults for the summarizer model.
+     */
+    model_settings?:
+      | AgentsAPI.OpenAIModelSettings
+      | AgentsAPI.AnthropicModelSettings
+      | AgentsAPI.GoogleAIModelSettings
+      | AgentsAPI.GoogleVertexModelSettings
+      | AgentsAPI.AzureModelSettings
+      | AgentsAPI.XaiModelSettings
+      | AgentsAPI.GroqModelSettings
+      | AgentsAPI.DeepseekModelSettings
+      | AgentsAPI.TogetherModelSettings
+      | AgentsAPI.BedrockModelSettings
+      | null;
+
+    /**
+     * The prompt to use for summarization.
+     */
+    prompt?: string;
+
+    /**
+     * Whether to include an acknowledgement post-prompt (helps prevent non-summary
+     * outputs).
+     */
+    prompt_acknowledgement?: boolean;
+
+    /**
+     * The percentage of the context window to keep post-summarization (only used in
+     * sliding window mode).
+     */
+    sliding_window_percentage?: number;
+  }
+}
+
 export interface AgentRetrieveParams {
   /**
    * Specify which relational fields to include in the response. No relationships are
@@ -1786,6 +1935,15 @@ export interface AgentUpdateParams {
    */
   block_ids?: Array<string> | null;
 
+  /**
+   * Configuration for conversation compaction / summarization.
+   *
+   * `model` is the only required user-facing field – it specifies the summarizer
+   * model handle (e.g. `"openai/gpt-4o-mini"`). Per-model settings (temperature, max
+   * tokens, etc.) are derived from the default configuration for that handle.
+   */
+  compaction_settings?: AgentUpdateParams.CompactionSettings | null;
+
   /**
    * The context window limit used by the agent.
    */
@@ -1992,6 +2150,66 @@ export interface AgentUpdateParams {
   > | null;
 }
 
+export namespace AgentUpdateParams {
+  /**
+   * Configuration for conversation compaction / summarization.
+   *
+   * `model` is the only required user-facing field – it specifies the summarizer
+   * model handle (e.g. `"openai/gpt-4o-mini"`). Per-model settings (temperature, max
+   * tokens, etc.) are derived from the default configuration for that handle.
+   */
+  export interface CompactionSettings {
+    /**
+     * Model handle to use for summarization (format: provider/model-name).
+     */
+    model: string;
+
+    /**
+     * The maximum length of the summary in characters. If none, no clipping is
+     * performed.
+     */
+    clip_chars?: number | null;
+
+    /**
+     * The type of summarization technique use.
+     */
+    mode?: 'all' | 'sliding_window';
+
+    /**
+     * Optional model settings used to override defaults for the summarizer model.
+     */
+    model_settings?:
+      | AgentsAPI.OpenAIModelSettings
+      | AgentsAPI.AnthropicModelSettings
+      | AgentsAPI.GoogleAIModelSettings
+      | AgentsAPI.GoogleVertexModelSettings
+      | AgentsAPI.AzureModelSettings
+      | AgentsAPI.XaiModelSettings
+      | AgentsAPI.GroqModelSettings
+      | AgentsAPI.DeepseekModelSettings
+      | AgentsAPI.TogetherModelSettings
+      | AgentsAPI.BedrockModelSettings
+      | null;
+
+    /**
+     * The prompt to use for summarization.
+     */
+    prompt?: string;
+
+    /**
+     * Whether to include an acknowledgement post-prompt (helps prevent non-summary
+     * outputs).
+     */
+    prompt_acknowledgement?: boolean;
+
+    /**
+     * The percentage of the context window to keep post-summarization (only used in
+     * sliding window mode).
+     */
+    sliding_window_percentage?: number;
+  }
+}
+
 export interface AgentListParams extends ArrayPageParams {
   /**
    * @deprecated Whether to sort agents oldest to newest (True) or newest to oldest
@@ -2169,6 +2387,7 @@ Agents.Folders = Folders;
 Agents.Files = Files;
 Agents.Groups = Groups;
 Agents.Archives = Archives;
+Agents.Passages = Passages;
 Agents.Identities = Identities;
 
 export declare namespace Agents {
@@ -2318,6 +2537,18 @@ export declare namespace Agents {
     type ArchiveDetachParams as ArchiveDetachParams,
   };
 
+  export {
+    Passages as Passages,
+    type PassageCreateResponse as PassageCreateResponse,
+    type PassageListResponse as PassageListResponse,
+    type PassageDeleteResponse as PassageDeleteResponse,
+    type PassageSearchResponse as PassageSearchResponse,
+    type PassageCreateParams as PassageCreateParams,
+    type PassageListParams as PassageListParams,
+    type PassageDeleteParams as PassageDeleteParams,
+    type PassageSearchParams as PassageSearchParams,
+  };
+
   export {
     Identities as Identities,
     type IdentityAttachResponse as IdentityAttachResponse,

package/src/resources/agents/index.ts

@@ -138,6 +138,17 @@ export {
   type MessagesArrayPage,
   type InternalMessagesObjectPage,
 } from './messages';
+export {
+  Passages,
+  type PassageCreateResponse,
+  type PassageListResponse,
+  type PassageDeleteResponse,
+  type PassageSearchResponse,
+  type PassageCreateParams,
+  type PassageListParams,
+  type PassageDeleteParams,
+  type PassageSearchParams,
+} from './passages';
 export {
   Tools,
   type ToolExecuteRequest,

package/src/resources/agents/messages.ts

@@ -704,9 +704,15 @@ export namespace InternalMessage {
     }
   }
 
+  /**
+   * A call to a function tool created by the model.
+   */
   export interface ToolCall {
     id: string;
 
+    /**
+     * The function that the model called.
+     */
     function: ToolCall.Function;
 
     type: 'function';
@@ -715,6 +721,9 @@ export namespace InternalMessage {
   }
 
   export namespace ToolCall {
+    /**
+     * The function that the model called.
+     */
     export interface Function {
       arguments: string;
 

package/src/resources/agents/passages.ts

@@ -0,0 +1,199 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as PassagesAPI from '../passages';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Passages extends APIResource {
+  /**
+   * Insert a memory into an agent's archival memory store.
+   *
+   * @deprecated
+   */
+  create(
+    agentID: string,
+    body: PassageCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<PassageCreateResponse> {
+    return this._client.post(path`/v1/agents/${agentID}/archival-memory`, { body, ...options });
+  }
+
+  /**
+   * Retrieve the memories in an agent's archival memory store (paginated query).
+   *
+   * @deprecated
+   */
+  list(
+    agentID: string,
+    query: PassageListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PassageListResponse> {
+    return this._client.get(path`/v1/agents/${agentID}/archival-memory`, { query, ...options });
+  }
+
+  /**
+   * Delete a memory from an agent's archival memory store.
+   *
+   * @deprecated
+   */
+  delete(memoryID: string, params: PassageDeleteParams, options?: RequestOptions): APIPromise<unknown> {
+    const { agent_id } = params;
+    return this._client.delete(path`/v1/agents/${agent_id}/archival-memory/${memoryID}`, options);
+  }
+
+  /**
+   * Search archival memory using semantic (embedding-based) search with optional
+   * temporal filtering.
+   *
+   * This endpoint allows manual triggering of archival memory searches, enabling
+   * users to query an agent's archival memory store directly via the API. The search
+   * uses the same functionality as the agent's archival_memory_search tool but is
+   * accessible for external API usage.
+   *
+   * @deprecated
+   */
+  search(
+    agentID: string,
+    query: PassageSearchParams,
+    options?: RequestOptions,
+  ): APIPromise<PassageSearchResponse> {
+    return this._client.get(path`/v1/agents/${agentID}/archival-memory/search`, { query, ...options });
+  }
+}
+
+export type PassageCreateResponse = Array<PassagesAPI.Passage>;
+
+export type PassageListResponse = Array<PassagesAPI.Passage>;
+
+export type PassageDeleteResponse = unknown;
+
+export interface PassageSearchResponse {
+  /**
+   * Total number of results returned
+   */
+  count: number;
+
+  /**
+   * List of search results matching the query
+   */
+  results: Array<PassageSearchResponse.Result>;
+}
+
+export namespace PassageSearchResponse {
+  export interface Result {
+    /**
+     * Text content of the archival memory passage
+     */
+    content: string;
+
+    /**
+     * Timestamp of when the memory was created, formatted in agent's timezone
+     */
+    timestamp: string;
+
+    /**
+     * List of tags associated with this memory
+     */
+    tags?: Array<string>;
+  }
+}
+
+export interface PassageCreateParams {
+  /**
+   * Text to write to archival memory.
+   */
+  text: string;
+
+  /**
+   * Optional timestamp for the memory (defaults to current UTC time).
+   */
+  created_at?: string | null;
+
+  /**
+   * Optional list of tags to attach to the memory.
+   */
+  tags?: Array<string> | null;
+}
+
+export interface PassageListParams {
+  /**
+   * Unique ID of the memory to start the query range at.
+   */
+  after?: string | null;
+
+  /**
+   * Whether to sort passages oldest to newest (True, default) or newest to oldest
+   * (False)
+   */
+  ascending?: boolean | null;
+
+  /**
+   * Unique ID of the memory to end the query range at.
+   */
+  before?: string | null;
+
+  /**
+   * How many results to include in the response.
+   */
+  limit?: number | null;
+
+  /**
+   * Search passages by text
+   */
+  search?: string | null;
+}
+
+export interface PassageDeleteParams {
+  /**
+   * The ID of the agent in the format 'agent-<uuid4>'
+   */
+  agent_id: string;
+}
+
+export interface PassageSearchParams {
+  /**
+   * String to search for using semantic similarity
+   */
+  query: string;
+
+  /**
+   * Filter results to passages created before this datetime
+   */
+  end_datetime?: string | null;
+
+  /**
+   * Filter results to passages created after this datetime
+   */
+  start_datetime?: string | null;
+
+  /**
+   * How to match tags - 'any' to match passages with any of the tags, 'all' to match
+   * only passages with all tags
+   */
+  tag_match_mode?: 'any' | 'all';
+
+  /**
+   * Optional list of tags to filter search results
+   */
+  tags?: Array<string> | null;
+
+  /**
+   * Maximum number of results to return. Uses system default if not specified
+   */
+  top_k?: number | null;
+}
+
+export declare namespace Passages {
+  export {
+    type PassageCreateResponse as PassageCreateResponse,
+    type PassageListResponse as PassageListResponse,
+    type PassageDeleteResponse as PassageDeleteResponse,
+    type PassageSearchResponse as PassageSearchResponse,
+    type PassageCreateParams as PassageCreateParams,
+    type PassageListParams as PassageListParams,
+    type PassageDeleteParams as PassageDeleteParams,
+    type PassageSearchParams as PassageSearchParams,
+  };
+}

package/src/resources/messages.ts

@@ -1,7 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
-import * as ToolsAPI from './tools';
 import * as AgentsMessagesAPI from './agents/messages';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
@@ -88,19 +87,110 @@ export interface MessageSearchResult {
 export type MessageListResponse = Array<AgentsMessagesAPI.Message>;
 
 export type MessageSearchResponse = Array<
-  | AgentsMessagesAPI.SystemMessage
-  | AgentsMessagesAPI.UserMessage
-  | AgentsMessagesAPI.ReasoningMessage
-  | AgentsMessagesAPI.HiddenReasoningMessage
-  | AgentsMessagesAPI.ToolCallMessage
-  | ToolsAPI.ToolReturnMessage
-  | AgentsMessagesAPI.AssistantMessage
-  | AgentsMessagesAPI.ApprovalRequestMessage
-  | AgentsMessagesAPI.ApprovalResponseMessage
-  | AgentsMessagesAPI.SummaryMessage
-  | AgentsMessagesAPI.EventMessage
+  | MessageSearchResponse.SystemMessageListResult
+  | MessageSearchResponse.UserMessageListResult
+  | MessageSearchResponse.ReasoningMessageListResult
+  | MessageSearchResponse.AssistantMessageListResult
 >;
 
+export namespace MessageSearchResponse {
+  /**
+   * System message list result with agent context.
+   *
+   * Shape is identical to UpdateSystemMessage but includes the owning agent_id.
+   */
+  export interface SystemMessageListResult {
+    /**
+     * The message content sent by the system (can be a string or an array of
+     * multi-modal content parts)
+     */
+    content: string;
+
+    /**
+     * The time the message was created in ISO format.
+     */
+    created_at: string;
+
+    /**
+     * The unique identifier of the agent that owns the message.
+     */
+    agent_id?: string | null;
+
+    message_type?: 'system_message';
+  }
+
+  /**
+   * User message list result with agent context.
+   *
+   * Shape is identical to UpdateUserMessage but includes the owning agent_id.
+   */
+  export interface UserMessageListResult {
+    /**
+     * The message content sent by the user (can be a string or an array of multi-modal
+     * content parts)
+     */
+    content: Array<AgentsMessagesAPI.LettaUserMessageContentUnion> | string;
+
+    /**
+     * The time the message was created in ISO format.
+     */
+    created_at: string;
+
+    /**
+     * The unique identifier of the agent that owns the message.
+     */
+    agent_id?: string | null;
+
+    message_type?: 'user_message';
+  }
+
+  /**
+   * Reasoning message list result with agent context.
+   *
+   * Shape is identical to UpdateReasoningMessage but includes the owning agent_id.
+   */
+  export interface ReasoningMessageListResult {
+    /**
+     * The time the message was created in ISO format.
+     */
+    created_at: string;
+
+    reasoning: string;
+
+    /**
+     * The unique identifier of the agent that owns the message.
+     */
+    agent_id?: string | null;
+
+    message_type?: 'reasoning_message';
+  }
+
+  /**
+   * Assistant message list result with agent context.
+   *
+   * Shape is identical to UpdateAssistantMessage but includes the owning agent_id.
+   */
+  export interface AssistantMessageListResult {
+    /**
+     * The message content sent by the assistant (can be a string or an array of
+     * content parts)
+     */
+    content: Array<AgentsMessagesAPI.LettaAssistantMessageContentUnion> | string;
+
+    /**
+     * The time the message was created in ISO format.
+     */
+    created_at: string;
+
+    /**
+     * The unique identifier of the agent that owns the message.
+     */
+    agent_id?: string | null;
+
+    message_type?: 'assistant_message';
+  }
+}
+
 export interface MessageListParams {
   /**
    * Message ID cursor for pagination. Returns messages that come after this message

package/src/resources/models/models.ts

@@ -325,7 +325,7 @@ export interface LlmConfig {
   /**
    * The reasoning effort to use when generating text reasoning models
    */
-  reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | null;
+  reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | null;
 
   /**
    * The response format for the model's output. Supports text, json_object, and
@@ -490,7 +490,7 @@ export interface Model {
    * @deprecated Deprecated: The reasoning effort to use when generating text
    * reasoning models.
    */
-  reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | null;
+  reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | null;
 
   /**
    * The response format for the model's output. Supports text, json_object, and

package/src/resources/runs/runs.ts

@@ -140,10 +140,12 @@ export type StopReasonType =
   | 'invalid_llm_response'
   | 'invalid_tool_call'
   | 'max_steps'
+  | 'max_tokens_exceeded'
   | 'no_tool_call'
   | 'tool_rule'
   | 'cancelled'
-  | 'requires_approval';
+  | 'requires_approval'
+  | 'context_window_overflow_in_system_prompt';
 
 export interface RunListParams extends ArrayPageParams {
   /**