@letta-ai/letta-client 1.0.0-alpha.15 → 1.0.0-alpha.16

package/src/resources/agents/folders.ts

@@ -5,6 +5,7 @@ import * as ArchivesAPI from '../archives';
 import * as AgentsAPI from './agents';
 import * as ModelsAPI from '../models/models';
 import { APIPromise } from '../../core/api-promise';
+import { ArrayPage, type ArrayPageParams, PagePromise } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -16,8 +17,11 @@ export class Folders extends APIResource {
     agentID: string,
     query: FolderListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<FolderListResponse> {
-    return this._client.get(path`/v1/agents/${agentID}/folders`, { query, ...options });
+  ): PagePromise<FolderListResponsesArrayPage, FolderListResponse> {
+    return this._client.getAPIList(path`/v1/agents/${agentID}/folders`, ArrayPage<FolderListResponse>, {
+      query,
+      ...options,
+    });
   }
 
   /**
@@ -45,106 +49,76 @@ export class Folders extends APIResource {
   }
 }
 
-export type FolderListResponse = Array<FolderListResponse.FolderListResponseItem>;
-
-export namespace FolderListResponse {
-  /**
-   * Representation of a source, which is a collection of files and passages.
-   *
-   * Parameters: id (str): The ID of the source name (str): The name of the source.
-   * embedding_config (EmbeddingConfig): The embedding configuration used by the
-   * source. user_id (str): The ID of the user that created the source. metadata
-   * (dict): Metadata associated with the source. description (str): The description
-   * of the source.
-   */
-  export interface FolderListResponseItem {
-    /**
-     * The embedding configuration used by the source.
-     */
-    embedding_config: ModelsAPI.EmbeddingConfig;
-
-    /**
-     * The name of the source.
-     */
-    name: string;
-
-    /**
-     * The human-friendly ID of the Source
-     */
-    id?: string;
-
-    /**
-     * The timestamp when the source was created.
-     */
-    created_at?: string | null;
-
-    /**
-     * The id of the user that made this Tool.
-     */
-    created_by_id?: string | null;
-
-    /**
-     * The description of the source.
-     */
-    description?: string | null;
-
-    /**
-     * Instructions for how to use the source.
-     */
-    instructions?: string | null;
-
-    /**
-     * The id of the user that made this Tool.
-     */
-    last_updated_by_id?: string | null;
-
-    /**
-     * Metadata associated with the source.
-     */
-    metadata?: { [key: string]: unknown } | null;
-
-    /**
-     * The timestamp when the source was last updated.
-     */
-    updated_at?: string | null;
-
-    /**
-     * The vector database provider used for this source's passages
-     */
-    vector_db_provider?: ArchivesAPI.VectorDBProvider;
-  }
-}
+export type FolderListResponsesArrayPage = ArrayPage<FolderListResponse>;
+
+/**
+ * Representation of a source, which is a collection of files and passages.
+ *
+ * Parameters: id (str): The ID of the source name (str): The name of the source.
+ * embedding_config (EmbeddingConfig): The embedding configuration used by the
+ * source. user_id (str): The ID of the user that created the source. metadata
+ * (dict): Metadata associated with the source. description (str): The description
+ * of the source.
+ */
+export interface FolderListResponse {
+  /**
+   * The human-friendly ID of the Source
+   */
+  id: string;
+
+  /**
+   * The embedding configuration used by the source.
+   */
+  embedding_config: ModelsAPI.EmbeddingConfig;
+
+  /**
+   * The name of the source.
+   */
+  name: string;
 
-export interface FolderListParams {
   /**
-   * Source ID cursor for pagination. Returns sources that come after this source ID
-   * in the specified sort order
+   * The timestamp when the source was created.
    */
-  after?: string | null;
+  created_at?: string | null;
 
   /**
-   * Source ID cursor for pagination. Returns sources that come before this source ID
-   * in the specified sort order
+   * The id of the user that made this Tool.
    */
-  before?: string | null;
+  created_by_id?: string | null;
 
   /**
-   * Maximum number of sources to return
+   * The description of the source.
    */
-  limit?: number | null;
+  description?: string | null;
 
   /**
-   * Sort order for sources by creation time. 'asc' for oldest first, 'desc' for
-   * newest first
+   * Instructions for how to use the source.
    */
-  order?: 'asc' | 'desc';
+  instructions?: string | null;
 
   /**
-   * Field to sort by
+   * The id of the user that made this Tool.
    */
-  order_by?: 'created_at';
+  last_updated_by_id?: string | null;
+
+  /**
+   * Metadata associated with the source.
+   */
+  metadata?: { [key: string]: unknown } | null;
+
+  /**
+   * The timestamp when the source was last updated.
+   */
+  updated_at?: string | null;
+
+  /**
+   * The vector database provider used for this source's passages
+   */
+  vector_db_provider?: ArchivesAPI.VectorDBProvider;
 }
 
+export interface FolderListParams extends ArrayPageParams {}
+
 export interface FolderAttachParams {
   /**
    * The ID of the agent in the format 'agent-<uuid4>'
@@ -162,6 +136,7 @@ export interface FolderDetachParams {
 export declare namespace Folders {
   export {
     type FolderListResponse as FolderListResponse,
+    type FolderListResponsesArrayPage as FolderListResponsesArrayPage,
     type FolderListParams as FolderListParams,
     type FolderAttachParams as FolderAttachParams,
     type FolderDetachParams as FolderDetachParams,

package/src/resources/agents/index.ts

@@ -20,7 +20,6 @@ export {
   type TerminalToolRule,
   type TextResponseFormat,
   type AgentDeleteResponse,
-  type AgentCountResponse,
   type AgentExportFileResponse,
   type AgentImportFileResponse,
   type AgentCreateParams,
@@ -58,6 +57,7 @@ export {
   type FolderListParams,
   type FolderAttachParams,
   type FolderDetachParams,
+  type FolderListResponsesArrayPage,
 } from './folders';
 export { Groups, type GroupListParams } from './groups';
 export {
@@ -107,13 +107,16 @@ export {
   type MessageModifyParams,
   type MessageResetParams,
   type MessageSendParams,
+  type MessageSendParamsNonStreaming,
+  type MessageSendParamsStreaming,
   type MessageSendAsyncParams,
   type MessageStreamParams,
   type LettaMessageUnionsArrayPage,
+  type RunsArrayPage,
+  type MessagesObjectPage,
 } from './messages';
 export {
   Tools,
-  type ToolListResponse,
   type ToolListParams,
   type ToolAttachParams,
   type ToolDetachParams,

package/src/resources/agents/messages.ts

@@ -6,7 +6,7 @@ import * as ToolsAPI from '../tools';
 import * as AgentsAPI from './agents';
 import * as RunsAPI from '../runs/runs';
 import { APIPromise } from '../../core/api-promise';
-import { ArrayPage, type ArrayPageParams, PagePromise } from '../../core/pagination';
+import { ArrayPage, type ArrayPageParams, ObjectPage, PagePromise } from '../../core/pagination';
 import { Stream } from '../../core/streaming';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
@@ -67,9 +67,44 @@ export class Messages extends APIResource {
   /**
    * Process a user message and return the agent's response. This endpoint accepts a
    * message from a user and processes it through the agent.
+   *
+   * The response format is controlled by the `streaming` field in the request body:
+   *
+   * - If `streaming=false` (default): Returns a complete LettaResponse with all
+   *   messages
+   * - If `streaming=true`: Returns a Server-Sent Events (SSE) stream
+   *
+   * Additional streaming options (only used when streaming=true):
+   *
+   * - `stream_tokens`: Stream individual tokens instead of complete steps
+   * - `include_pings`: Include keepalive pings to prevent connection timeouts
+   * - `background`: Process the request in the background
    */
-  send(agentID: string, body: MessageSendParams, options?: RequestOptions): APIPromise<LettaResponse> {
-    return this._client.post(path`/v1/agents/${agentID}/messages`, { body, ...options });
+  send(
+    agentID: string,
+    body: MessageSendParamsNonStreaming,
+    options?: RequestOptions,
+  ): APIPromise<LettaResponse>;
+  send(
+    agentID: string,
+    body: MessageSendParamsStreaming,
+    options?: RequestOptions,
+  ): APIPromise<Stream<LettaStreamingResponse>>;
+  send(
+    agentID: string,
+    body: MessageSendParamsBase,
+    options?: RequestOptions,
+  ): APIPromise<Stream<LettaStreamingResponse> | LettaResponse>;
+  send(
+    agentID: string,
+    body: MessageSendParams,
+    options?: RequestOptions,
+  ): APIPromise<LettaResponse> | APIPromise<Stream<LettaStreamingResponse>> {
+    return this._client.post(path`/v1/agents/${agentID}/messages`, {
+      body,
+      ...options,
+      stream: body.streaming ?? false,
+    }) as APIPromise<LettaResponse> | APIPromise<Stream<LettaStreamingResponse>>;
   }
 
   /**
@@ -114,6 +149,10 @@ export class Messages extends APIResource {
 
 export type LettaMessageUnionsArrayPage = ArrayPage<LettaMessageUnion>;
 
+export type RunsArrayPage = ArrayPage<Run>;
+
+export type MessagesObjectPage = ObjectPage<Message>;
+
 /**
  * Input to approve or deny a tool call request
  */
@@ -133,6 +172,11 @@ export interface ApprovalCreate {
    */
   approve?: boolean | null;
 
+  /**
+   * The multi-agent group that the message was sent in
+   */
+  group_id?: string | null;
+
   /**
    * @deprecated An optional explanation for the provided approval status
    */
@@ -714,7 +758,8 @@ export interface LettaStreamingRequest {
   assistant_message_tool_name?: string;
 
   /**
-   * Whether to process the request in the background.
+   * Whether to process the request in the background (only used when
+   * streaming=true).
    */
   background?: boolean;
 
@@ -726,7 +771,7 @@ export interface LettaStreamingRequest {
 
   /**
    * Whether to include periodic keepalive ping messages in the stream to prevent
-   * connection timeouts.
+   * connection timeouts (only used when streaming=true).
    */
   include_pings?: boolean;
 
@@ -766,10 +811,16 @@ export interface LettaStreamingRequest {
 
   /**
    * Flag to determine if individual tokens should be streamed, rather than streaming
-   * per step.
+   * per step (only used when streaming=true).
    */
   stream_tokens?: boolean;
 
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: boolean;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -928,14 +979,14 @@ export type LettaUserMessageContentUnion = TextContent | ImageContent;
  */
 export interface Message {
   /**
-   * The role of the participant.
+   * The human-friendly ID of the Message
    */
-  role: MessageRole;
+  id: string;
 
   /**
-   * The human-friendly ID of the Message
+   * The role of the participant.
    */
-  id?: string;
+  role: MessageRole;
 
   /**
    * The unique identifier of the agent.
@@ -1324,14 +1375,14 @@ export interface RedactedReasoningContent {
  */
 export interface Run {
   /**
-   * The unique identifier of the agent associated with the run.
+   * The human-friendly ID of the Run
    */
-  agent_id: string;
+  id: string;
 
   /**
-   * The human-friendly ID of the Run
+   * The unique identifier of the agent associated with the run.
    */
-  id?: string;
+  agent_id: string;
 
   /**
    * Whether the run was created in background mode.
@@ -1860,7 +1911,9 @@ export interface MessageResetParams {
   add_default_initial_messages?: boolean;
 }
 
-export interface MessageSendParams {
+export type MessageSendParams = MessageSendParamsNonStreaming | MessageSendParamsStreaming;
+
+export interface MessageSendParamsBase {
   /**
    * @deprecated The name of the message argument in the designated message tool.
    * Still supported for legacy agent types, but deprecated for letta_v1_agent
@@ -1874,12 +1927,24 @@ export interface MessageSendParams {
    */
   assistant_message_tool_name?: string;
 
+  /**
+   * Whether to process the request in the background (only used when
+   * streaming=true).
+   */
+  background?: boolean;
+
   /**
    * @deprecated If set to True, enables reasoning before responses or tool calls
    * from the agent.
    */
   enable_thinking?: string;
 
+  /**
+   * Whether to include periodic keepalive ping messages in the stream to prevent
+   * connection timeouts (only used when streaming=true).
+   */
+  include_pings?: boolean;
+
   /**
    * Only return specified message types in the response. If `None` (default) returns
    * all messages.
@@ -1914,6 +1979,18 @@ export interface MessageSendParams {
    */
   messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
 
+  /**
+   * Flag to determine if individual tokens should be streamed, rather than streaming
+   * per step (only used when streaming=true).
+   */
+  stream_tokens?: boolean;
+
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: boolean;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -1961,6 +2038,25 @@ export namespace MessageSendParams {
       text: string;
     }
   }
+
+  export type MessageSendParamsNonStreaming = MessagesAPI.MessageSendParamsNonStreaming;
+  export type MessageSendParamsStreaming = MessagesAPI.MessageSendParamsStreaming;
+}
+
+export interface MessageSendParamsNonStreaming extends MessageSendParamsBase {
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: false;
+}
+
+export interface MessageSendParamsStreaming extends MessageSendParamsBase {
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming: true;
 }
 
 export interface MessageSendAsyncParams {
@@ -2086,7 +2182,8 @@ export interface MessageStreamParams {
   assistant_message_tool_name?: string;
 
   /**
-   * Whether to process the request in the background.
+   * Whether to process the request in the background (only used when
+   * streaming=true).
    */
   background?: boolean;
 
@@ -2098,7 +2195,7 @@ export interface MessageStreamParams {
 
   /**
    * Whether to include periodic keepalive ping messages in the stream to prevent
-   * connection timeouts.
+   * connection timeouts (only used when streaming=true).
    */
   include_pings?: boolean;
 
@@ -2138,10 +2235,16 @@ export interface MessageStreamParams {
 
   /**
    * Flag to determine if individual tokens should be streamed, rather than streaming
-   * per step.
+   * per step (only used when streaming=true).
    */
   stream_tokens?: boolean;
 
+  /**
+   * If True, returns a streaming response (Server-Sent Events). If False (default),
+   * returns a complete response.
+   */
+  streaming?: boolean;
+
   /**
    * @deprecated Whether the server should parse specific tool call arguments
    * (default `send_message`) as `AssistantMessage` objects. Still supported for
@@ -2239,6 +2342,8 @@ export declare namespace Messages {
     type MessageModifyParams as MessageModifyParams,
     type MessageResetParams as MessageResetParams,
     type MessageSendParams as MessageSendParams,
+    type MessageSendParamsNonStreaming as MessageSendParamsNonStreaming,
+    type MessageSendParamsStreaming as MessageSendParamsStreaming,
     type MessageSendAsyncParams as MessageSendAsyncParams,
     type MessageStreamParams as MessageStreamParams,
   };

package/src/resources/agents/tools.ts

@@ -2,8 +2,10 @@
 
 import { APIResource } from '../../core/resource';
 import * as ToolsAPI from '../tools';
+import { ToolsArrayPage } from '../tools';
 import * as AgentsAPI from './agents';
 import { APIPromise } from '../../core/api-promise';
+import { ArrayPage, type ArrayPageParams, PagePromise } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -15,8 +17,11 @@ export class Tools extends APIResource {
     agentID: string,
     query: ToolListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<ToolListResponse> {
-    return this._client.get(path`/v1/agents/${agentID}/tools`, { query, ...options });
+  ): PagePromise<ToolsArrayPage, ToolsAPI.Tool> {
+    return this._client.getAPIList(path`/v1/agents/${agentID}/tools`, ArrayPage<ToolsAPI.Tool>, {
+      query,
+      ...options,
+    });
   }
 
   /**
@@ -63,37 +68,7 @@ export class Tools extends APIResource {
   }
 }
 
-export type ToolListResponse = Array<ToolsAPI.Tool>;
-
-export interface ToolListParams {
-  /**
-   * Tool ID cursor for pagination. Returns tools that come after this tool ID in the
-   * specified sort order
-   */
-  after?: string | null;
-
-  /**
-   * Tool ID cursor for pagination. Returns tools that come before this tool ID in
-   * the specified sort order
-   */
-  before?: string | null;
-
-  /**
-   * Maximum number of tools to return
-   */
-  limit?: number | null;
-
-  /**
-   * Sort order for tools by creation time. 'asc' for oldest first, 'desc' for newest
-   * first
-   */
-  order?: 'asc' | 'desc';
-
-  /**
-   * Field to sort by
-   */
-  order_by?: 'created_at';
-}
+export interface ToolListParams extends ArrayPageParams {}
 
 export interface ToolAttachParams {
   /**
@@ -128,10 +103,11 @@ export interface ToolUpdateApprovalParams {
 
 export declare namespace Tools {
   export {
-    type ToolListResponse as ToolListResponse,
     type ToolListParams as ToolListParams,
     type ToolAttachParams as ToolAttachParams,
     type ToolDetachParams as ToolDetachParams,
     type ToolUpdateApprovalParams as ToolUpdateApprovalParams,
   };
 }
+
+export { type ToolsArrayPage };

package/src/resources/archives.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../core/resource';
 import * as ModelsAPI from './models/models';
 import { APIPromise } from '../core/api-promise';
+import { ArrayPage, type ArrayPageParams, PagePromise } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
@@ -28,8 +29,8 @@ export class Archives extends APIResource {
   list(
     query: ArchiveListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<ArchiveListResponse> {
-    return this._client.get('/v1/archives/', { query, ...options });
+  ): PagePromise<ArchivesArrayPage, Archive> {
+    return this._client.getAPIList('/v1/archives/', ArrayPage<Archive>, { query, ...options });
   }
 
   /**
@@ -47,6 +48,8 @@ export class Archives extends APIResource {
   }
 }
 
+export type ArchivesArrayPage = ArrayPage<Archive>;
+
 /**
  * Representation of an archive - a collection of archival passages that can be
  * shared between agents.
@@ -58,6 +61,11 @@ export class Archives extends APIResource {
  * archive.
  */
 export interface Archive {
+  /**
+   * The human-friendly ID of the Archive
+   */
+  id: string;
+
   /**
    * The creation date of the archive
    */
@@ -73,11 +81,6 @@ export interface Archive {
    */
   name: string;
 
-  /**
-   * The human-friendly ID of the Archive
-   */
-  id?: string;
-
   /**
    * The id of the user that made this object.
    */
@@ -114,8 +117,6 @@ export interface Archive {
  */
 export type VectorDBProvider = 'native' | 'tpuf' | 'pinecone';
 
-export type ArchiveListResponse = Array<Archive>;
-
 export interface ArchiveCreateParams {
   /**
    * Embedding configuration for the archive
@@ -127,44 +128,16 @@ export interface ArchiveCreateParams {
   description?: string | null;
 }
 
-export interface ArchiveListParams {
-  /**
-   * Archive ID cursor for pagination. Returns archives that come after this archive
-   * ID in the specified sort order
-   */
-  after?: string | null;
-
+export interface ArchiveListParams extends ArrayPageParams {
   /**
    * Only archives attached to this agent ID
    */
   agent_id?: string | null;
 
-  /**
-   * Archive ID cursor for pagination. Returns archives that come before this archive
-   * ID in the specified sort order
-   */
-  before?: string | null;
-
-  /**
-   * Maximum number of archives to return
-   */
-  limit?: number | null;
-
   /**
    * Filter by archive name (exact match)
    */
   name?: string | null;
-
-  /**
-   * Sort order for archives by creation time. 'asc' for oldest first, 'desc' for
-   * newest first
-   */
-  order?: 'asc' | 'desc';
-
-  /**
-   * Field to sort by
-   */
-  order_by?: 'created_at';
 }
 
 export interface ArchiveModifyParams {
@@ -177,7 +150,7 @@ export declare namespace Archives {
   export {
     type Archive as Archive,
     type VectorDBProvider as VectorDBProvider,
-    type ArchiveListResponse as ArchiveListResponse,
+    type ArchivesArrayPage as ArchivesArrayPage,
     type ArchiveCreateParams as ArchiveCreateParams,
     type ArchiveListParams as ArchiveListParams,
     type ArchiveModifyParams as ArchiveModifyParams,