@letta-ai/letta-client 1.0.0-alpha.17 → 1.0.0-alpha.19

package/src/resources/agents/messages.ts

@@ -20,8 +20,8 @@ export class Messages extends APIResource {
     agentID: string,
     query: MessageListParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<LettaMessageUnionsArrayPage, LettaMessageUnion> {
-    return this._client.getAPIList(path`/v1/agents/${agentID}/messages`, ArrayPage<LettaMessageUnion>, {
+  ): PagePromise<MessagesArrayPage, Message> {
+    return this._client.getAPIList(path`/v1/agents/${agentID}/messages`, ArrayPage<Message>, {
       query,
       ...options,
     });
@@ -147,11 +147,11 @@ export class Messages extends APIResource {
   }
 }
 
-export type LettaMessageUnionsArrayPage = ArrayPage<LettaMessageUnion>;
+export type MessagesArrayPage = ArrayPage<Message>;
 
 export type RunsArrayPage = ArrayPage<Run>;
 
-export type MessagesObjectPage = ObjectPage<Message>;
+export type InternalMessagesObjectPage = ObjectPage<InternalMessage>;
 
 /**
  * Input to approve or deny a tool call request
@@ -165,7 +165,7 @@ export interface ApprovalCreate {
   /**
    * The list of approval responses
    */
-  approvals?: Array<ApprovalCreate.ApprovalReturn | ToolReturn> | null;
+  approvals?: Array<ApprovalReturn | ToolReturn> | null;
 
   /**
    * @deprecated Whether the tool has been approved
@@ -188,30 +188,6 @@ export interface ApprovalCreate {
   type?: 'approval';
 }
 
-export namespace ApprovalCreate {
-  export interface ApprovalReturn {
-    /**
-     * Whether the tool has been approved
-     */
-    approve: boolean;
-
-    /**
-     * The ID of the tool call that corresponds to this approval
-     */
-    tool_call_id: string;
-
-    /**
-     * An optional explanation for the provided approval status
-     */
-    reason?: string | null;
-
-    /**
-     * The message type to be created.
-     */
-    type?: 'approval';
-  }
-}
-
 /**
  * A message representing a request for approval to call a tool (generated by the
  * LLM to trigger tool execution).
@@ -279,7 +255,7 @@ export interface ApprovalResponseMessage {
   /**
    * The list of approval responses
    */
-  approvals?: Array<ApprovalResponseMessage.ApprovalReturn | ToolReturn> | null;
+  approvals?: Array<ApprovalReturn | ToolReturn> | null;
 
   /**
    * @deprecated Whether the tool has been approved
@@ -311,28 +287,26 @@ export interface ApprovalResponseMessage {
   step_id?: string | null;
 }
 
-export namespace ApprovalResponseMessage {
-  export interface ApprovalReturn {
-    /**
-     * Whether the tool has been approved
-     */
-    approve: boolean;
+export interface ApprovalReturn {
+  /**
+   * Whether the tool has been approved
+   */
+  approve: boolean;
 
-    /**
-     * The ID of the tool call that corresponds to this approval
-     */
-    tool_call_id: string;
+  /**
+   * The ID of the tool call that corresponds to this approval
+   */
+  tool_call_id: string;
 
-    /**
-     * An optional explanation for the provided approval status
-     */
-    reason?: string | null;
+  /**
+   * An optional explanation for the provided approval status
+   */
+  reason?: string | null;
 
-    /**
-     * The message type to be created.
-     */
-    type?: 'approval';
-  }
+  /**
+   * The message type to be created.
+   */
+  type?: 'approval';
 }
 
 /**
@@ -521,113 +495,188 @@ export namespace ImageContent {
 }
 
 /**
- * Status of the job.
+ * Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.
+ *
+ *     Attributes:
+ *         id (str): The unique identifier of the message.
+ *         role (MessageRole): The role of the participant.
+ *         text (str): The text of the message.
+ *         user_id (str): The unique identifier of the user.
+ *         agent_id (str): The unique identifier of the agent.
+ *         model (str): The model used to make the function call.
+ *         name (str): The name of the participant.
+ *         created_at (datetime): The time the message was created.
+ *         tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.
+ *         tool_call_id (str): The id of the tool call.
+ *         step_id (str): The id of the step that this message was created in.
+ *         otid (str): The offline threading id associated with this message.
+ *         tool_returns (List[ToolReturn]): The list of tool returns requested.
+ *         group_id (str): The multi-agent group that the message was sent in.
+ *         sender_id (str): The id of the sender of the message, can be an identity id or agent id.
+ *
+ * t
  */
-export type JobStatus = 'created' | 'running' | 'completed' | 'failed' | 'pending' | 'cancelled' | 'expired';
+export interface InternalMessage {
+  /**
+   * The human-friendly ID of the Message
+   */
+  id: string;
 
-export type JobType = 'job' | 'run' | 'batch';
+  /**
+   * The role of the participant.
+   */
+  role: MessageRole;
 
-export interface LettaAssistantMessageContentUnion {
   /**
-   * The text content of the message.
+   * The unique identifier of the agent.
    */
-  text: string;
+  agent_id?: string | null;
 
   /**
-   * Stores a unique identifier for any reasoning associated with this text content.
+   * The id of the approval request if this message is associated with a tool call
+   * request.
    */
-  signature?: string | null;
+  approval_request_id?: string | null;
 
   /**
-   * The type of the message.
+   * The list of approvals for this message.
    */
-  type?: 'text';
-}
+  approvals?: Array<ApprovalReturn | InternalMessage.LettaSchemasMessageToolReturn> | null;
 
-/**
- * A message generated by the system. Never streamed back on a response, only used
- * for cursor pagination.
- *
- * Args: id (str): The ID of the message date (datetime): The date the message was
- * created in ISO format name (Optional[str]): The name of the sender of the
- * message content (str): The message content sent by the system
- */
-export type LettaMessageUnion =
-  | SystemMessage
-  | UserMessage
-  | ReasoningMessage
-  | HiddenReasoningMessage
-  | ToolCallMessage
-  | ToolsAPI.ToolReturnMessage
-  | AssistantMessage
-  | ApprovalRequestMessage
-  | ApprovalResponseMessage
-  | SummaryMessage
-  | EventMessage;
+  /**
+   * Whether tool call is approved.
+   */
+  approve?: boolean | null;
 
-export interface LettaRequest {
   /**
-   * @deprecated The name of the message argument in the designated message tool.
-   * Still supported for legacy agent types, but deprecated for letta_v1_agent
-   * onward.
+   * The id of the LLMBatchItem that this message is associated with
    */
-  assistant_message_tool_kwarg?: string;
+  batch_item_id?: string | null;
 
   /**
-   * @deprecated The name of the designated message tool. Still supported for legacy
-   * agent types, but deprecated for letta_v1_agent onward.
+   * The content of the message.
    */
-  assistant_message_tool_name?: string;
+  content?: Array<
+    | TextContent
+    | ImageContent
+    | ToolCallContent
+    | ToolReturnContent
+    | ReasoningContent
+    | RedactedReasoningContent
+    | OmittedReasoningContent
+    | InternalMessage.SummarizedReasoningContent
+  > | null;
 
   /**
-   * @deprecated If set to True, enables reasoning before responses or tool calls
-   * from the agent.
+   * The timestamp when the object was created.
    */
-  enable_thinking?: string;
+  created_at?: string;
 
   /**
-   * Only return specified message types in the response. If `None` (default) returns
-   * all messages.
+   * The id of the user that made this object.
    */
-  include_return_message_types?: Array<MessageType> | null;
+  created_by_id?: string | null;
 
   /**
-   * Syntactic sugar for a single user message. Equivalent to messages=[{'role':
-   * 'user', 'content': input}].
+   * The reason the tool call request was denied.
    */
-  input?:
-    | string
-    | Array<
-        | TextContent
-        | ImageContent
-        | ToolCallContent
-        | ToolReturnContent
-        | ReasoningContent
-        | RedactedReasoningContent
-        | OmittedReasoningContent
-        | LettaRequest.SummarizedReasoningContent
-      >
-    | null;
+  denial_reason?: string | null;
 
   /**
-   * Maximum number of steps the agent should take to process the request.
+   * The multi-agent group that the message was sent in
    */
-  max_steps?: number;
+  group_id?: string | null;
 
   /**
-   * The messages to be sent to the agent.
+   * Whether this message is part of an error step. Used only for debugging purposes.
    */
-  messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
+  is_err?: boolean | null;
 
   /**
-   * @deprecated Whether the server should parse specific tool call arguments
-   * (default `send_message`) as `AssistantMessage` objects. Still supported for
-   * legacy agent types, but deprecated for letta_v1_agent onward.
+   * The id of the user that made this object.
    */
-  use_assistant_message?: boolean;
+  last_updated_by_id?: string | null;
+
+  /**
+   * The model used to make the function call.
+   */
+  model?: string | null;
+
+  /**
+   * For role user/assistant: the (optional) name of the participant. For role
+   * tool/function: the name of the function called.
+   */
+  name?: string | null;
+
+  /**
+   * The offline threading id associated with this message
+   */
+  otid?: string | null;
+
+  /**
+   * The id of the run that this message was created in.
+   */
+  run_id?: string | null;
+
+  /**
+   * The id of the sender of the message, can be an identity id or agent id
+   */
+  sender_id?: string | null;
+
+  /**
+   * The id of the step that this message was created in.
+   */
+  step_id?: string | null;
+
+  /**
+   * The ID of the tool call. Only applicable for role tool.
+   */
+  tool_call_id?: string | null;
+
+  /**
+   * The list of tool calls requested. Only applicable for role assistant.
+   */
+  tool_calls?: Array<InternalMessage.ToolCall> | null;
+
+  /**
+   * Tool execution return information for prior tool calls
+   */
+  tool_returns?: Array<InternalMessage.ToolReturn> | null;
+
+  /**
+   * The timestamp when the object was last updated.
+   */
+  updated_at?: string | null;
 }
 
-export namespace LettaRequest {
+export namespace InternalMessage {
+  export interface LettaSchemasMessageToolReturn {
+    /**
+     * The status of the tool call
+     */
+    status: 'success' | 'error';
+
+    /**
+     * The function response string
+     */
+    func_response?: string | null;
+
+    /**
+     * Captured stderr from the tool invocation
+     */
+    stderr?: Array<string> | null;
+
+    /**
+     * Captured stdout (e.g. prints, logs) from the tool invocation
+     */
+    stdout?: Array<string> | null;
+
+    /**
+     * The ID for the tool call
+     */
+    tool_call_id?: unknown;
+  }
+
   /**
    * The style of reasoning content returned by the OpenAI Responses API
    */
@@ -666,22 +715,196 @@ export namespace LettaRequest {
       text: string;
     }
   }
-}
-
-/**
- * Response object from an agent interaction, consisting of the new messages
- * generated by the agent and usage statistics. The type of the returned messages
- * can be either `Message` or `LettaMessage`, depending on what was specified in
- * the request.
- *
- * Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned
- * by the agent. usage (LettaUsageStatistics): The usage statistics
- */
-export interface LettaResponse {
-  /**
-   * The messages returned by the agent.
-   */
-  messages: Array<LettaMessageUnion>;
+
+  export interface ToolCall {
+    id: string;
+
+    function: ToolCall.Function;
+
+    type: 'function';
+
+    [k: string]: unknown;
+  }
+
+  export namespace ToolCall {
+    export interface Function {
+      arguments: string;
+
+      name: string;
+
+      [k: string]: unknown;
+    }
+  }
+
+  export interface ToolReturn {
+    /**
+     * The status of the tool call
+     */
+    status: 'success' | 'error';
+
+    /**
+     * The function response string
+     */
+    func_response?: string | null;
+
+    /**
+     * Captured stderr from the tool invocation
+     */
+    stderr?: Array<string> | null;
+
+    /**
+     * Captured stdout (e.g. prints, logs) from the tool invocation
+     */
+    stdout?: Array<string> | null;
+
+    /**
+     * The ID for the tool call
+     */
+    tool_call_id?: unknown;
+  }
+}
+
+/**
+ * Status of the job.
+ */
+export type JobStatus = 'created' | 'running' | 'completed' | 'failed' | 'pending' | 'cancelled' | 'expired';
+
+export type JobType = 'job' | 'run' | 'batch';
+
+export interface LettaAssistantMessageContentUnion {
+  /**
+   * The text content of the message.
+   */
+  text: string;
+
+  /**
+   * Stores a unique identifier for any reasoning associated with this text content.
+   */
+  signature?: string | null;
+
+  /**
+   * The type of the message.
+   */
+  type?: 'text';
+}
+
+export interface LettaRequest {
+  /**
+   * @deprecated The name of the message argument in the designated message tool.
+   * Still supported for legacy agent types, but deprecated for letta_v1_agent
+   * onward.
+   */
+  assistant_message_tool_kwarg?: string;
+
+  /**
+   * @deprecated The name of the designated message tool. Still supported for legacy
+   * agent types, but deprecated for letta_v1_agent onward.
+   */
+  assistant_message_tool_name?: string;
+
+  /**
+   * @deprecated If set to True, enables reasoning before responses or tool calls
+   * from the agent.
+   */
+  enable_thinking?: string;
+
+  /**
+   * Only return specified message types in the response. If `None` (default) returns
+   * all messages.
+   */
+  include_return_message_types?: Array<MessageType> | null;
+
+  /**
+   * Syntactic sugar for a single user message. Equivalent to messages=[{'role':
+   * 'user', 'content': input}].
+   */
+  input?:
+    | string
+    | Array<
+        | TextContent
+        | ImageContent
+        | ToolCallContent
+        | ToolReturnContent
+        | ReasoningContent
+        | RedactedReasoningContent
+        | OmittedReasoningContent
+        | LettaRequest.SummarizedReasoningContent
+      >
+    | null;
+
+  /**
+   * Maximum number of steps the agent should take to process the request.
+   */
+  max_steps?: number;
+
+  /**
+   * The messages to be sent to the agent.
+   */
+  messages?: Array<AgentsAPI.MessageCreate | ApprovalCreate> | null;
+
+  /**
+   * @deprecated Whether the server should parse specific tool call arguments
+   * (default `send_message`) as `AssistantMessage` objects. Still supported for
+   * legacy agent types, but deprecated for letta_v1_agent onward.
+   */
+  use_assistant_message?: boolean;
+}
+
+export namespace LettaRequest {
+  /**
+   * The style of reasoning content returned by the OpenAI Responses API
+   */
+  export interface SummarizedReasoningContent {
+    /**
+     * The unique identifier for this reasoning step.
+     */
+    id: string;
+
+    /**
+     * Summaries of the reasoning content.
+     */
+    summary: Array<SummarizedReasoningContent.Summary>;
+
+    /**
+     * The encrypted reasoning content.
+     */
+    encrypted_content?: string;
+
+    /**
+     * Indicates this is a summarized reasoning step.
+     */
+    type?: 'summarized_reasoning';
+  }
+
+  export namespace SummarizedReasoningContent {
+    export interface Summary {
+      /**
+       * The index of the summary part.
+       */
+      index: number;
+
+      /**
+       * The text of the summary part.
+       */
+      text: string;
+    }
+  }
+}
+
+/**
+ * Response object from an agent interaction, consisting of the new messages
+ * generated by the agent and usage statistics. The type of the returned messages
+ * can be either `Message` or `LettaMessage`, depending on what was specified in
+ * the request.
+ *
+ * Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned
+ * by the agent. usage (LettaUsageStatistics): The usage statistics
+ */
+export interface LettaResponse {
+  /**
+   * The messages returned by the agent.
+   */
+  messages: Array<Message>;
 
   /**
    * The stop reason from Letta indicating why agent loop stopped execution.
@@ -956,296 +1179,25 @@ export namespace LettaStreamingResponse {
 export type LettaUserMessageContentUnion = TextContent | ImageContent;
 
 /**
- * Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.
- *
- *     Attributes:
- *         id (str): The unique identifier of the message.
- *         role (MessageRole): The role of the participant.
- *         text (str): The text of the message.
- *         user_id (str): The unique identifier of the user.
- *         agent_id (str): The unique identifier of the agent.
- *         model (str): The model used to make the function call.
- *         name (str): The name of the participant.
- *         created_at (datetime): The time the message was created.
- *         tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.
- *         tool_call_id (str): The id of the tool call.
- *         step_id (str): The id of the step that this message was created in.
- *         otid (str): The offline threading id associated with this message.
- *         tool_returns (List[ToolReturn]): The list of tool returns requested.
- *         group_id (str): The multi-agent group that the message was sent in.
- *         sender_id (str): The id of the sender of the message, can be an identity id or agent id.
+ * A message generated by the system. Never streamed back on a response, only used
+ * for cursor pagination.
  *
- * t
+ * Args: id (str): The ID of the message date (datetime): The date the message was
+ * created in ISO format name (Optional[str]): The name of the sender of the
+ * message content (str): The message content sent by the system
  */
-export interface Message {
-  /**
-   * The human-friendly ID of the Message
-   */
-  id: string;
-
-  /**
-   * The role of the participant.
-   */
-  role: MessageRole;
-
-  /**
-   * The unique identifier of the agent.
-   */
-  agent_id?: string | null;
-
-  /**
-   * The id of the approval request if this message is associated with a tool call
-   * request.
-   */
-  approval_request_id?: string | null;
-
-  /**
-   * The list of approvals for this message.
-   */
-  approvals?: Array<Message.ApprovalReturn | Message.LettaSchemasMessageToolReturn> | null;
-
-  /**
-   * Whether tool call is approved.
-   */
-  approve?: boolean | null;
-
-  /**
-   * The id of the LLMBatchItem that this message is associated with
-   */
-  batch_item_id?: string | null;
-
-  /**
-   * The content of the message.
-   */
-  content?: Array<
-    | TextContent
-    | ImageContent
-    | ToolCallContent
-    | ToolReturnContent
-    | ReasoningContent
-    | RedactedReasoningContent
-    | OmittedReasoningContent
-    | Message.SummarizedReasoningContent
-  > | null;
-
-  /**
-   * The timestamp when the object was created.
-   */
-  created_at?: string;
-
-  /**
-   * The id of the user that made this object.
-   */
-  created_by_id?: string | null;
-
-  /**
-   * The reason the tool call request was denied.
-   */
-  denial_reason?: string | null;
-
-  /**
-   * The multi-agent group that the message was sent in
-   */
-  group_id?: string | null;
-
-  /**
-   * Whether this message is part of an error step. Used only for debugging purposes.
-   */
-  is_err?: boolean | null;
-
-  /**
-   * The id of the user that made this object.
-   */
-  last_updated_by_id?: string | null;
-
-  /**
-   * The model used to make the function call.
-   */
-  model?: string | null;
-
-  /**
-   * For role user/assistant: the (optional) name of the participant. For role
-   * tool/function: the name of the function called.
-   */
-  name?: string | null;
-
-  /**
-   * The offline threading id associated with this message
-   */
-  otid?: string | null;
-
-  /**
-   * The id of the run that this message was created in.
-   */
-  run_id?: string | null;
-
-  /**
-   * The id of the sender of the message, can be an identity id or agent id
-   */
-  sender_id?: string | null;
-
-  /**
-   * The id of the step that this message was created in.
-   */
-  step_id?: string | null;
-
-  /**
-   * The ID of the tool call. Only applicable for role tool.
-   */
-  tool_call_id?: string | null;
-
-  /**
-   * The list of tool calls requested. Only applicable for role assistant.
-   */
-  tool_calls?: Array<Message.ToolCall> | null;
-
-  /**
-   * Tool execution return information for prior tool calls
-   */
-  tool_returns?: Array<Message.ToolReturn> | null;
-
-  /**
-   * The timestamp when the object was last updated.
-   */
-  updated_at?: string | null;
-}
-
-export namespace Message {
-  export interface ApprovalReturn {
-    /**
-     * Whether the tool has been approved
-     */
-    approve: boolean;
-
-    /**
-     * The ID of the tool call that corresponds to this approval
-     */
-    tool_call_id: string;
-
-    /**
-     * An optional explanation for the provided approval status
-     */
-    reason?: string | null;
-
-    /**
-     * The message type to be created.
-     */
-    type?: 'approval';
-  }
-
-  export interface LettaSchemasMessageToolReturn {
-    /**
-     * The status of the tool call
-     */
-    status: 'success' | 'error';
-
-    /**
-     * The function response string
-     */
-    func_response?: string | null;
-
-    /**
-     * Captured stderr from the tool invocation
-     */
-    stderr?: Array<string> | null;
-
-    /**
-     * Captured stdout (e.g. prints, logs) from the tool invocation
-     */
-    stdout?: Array<string> | null;
-
-    /**
-     * The ID for the tool call
-     */
-    tool_call_id?: unknown;
-  }
-
-  /**
-   * The style of reasoning content returned by the OpenAI Responses API
-   */
-  export interface SummarizedReasoningContent {
-    /**
-     * The unique identifier for this reasoning step.
-     */
-    id: string;
-
-    /**
-     * Summaries of the reasoning content.
-     */
-    summary: Array<SummarizedReasoningContent.Summary>;
-
-    /**
-     * The encrypted reasoning content.
-     */
-    encrypted_content?: string;
-
-    /**
-     * Indicates this is a summarized reasoning step.
-     */
-    type?: 'summarized_reasoning';
-  }
-
-  export namespace SummarizedReasoningContent {
-    export interface Summary {
-      /**
-       * The index of the summary part.
-       */
-      index: number;
-
-      /**
-       * The text of the summary part.
-       */
-      text: string;
-    }
-  }
-
-  export interface ToolCall {
-    id: string;
-
-    function: ToolCall.Function;
-
-    type: 'function';
-
-    [k: string]: unknown;
-  }
-
-  export namespace ToolCall {
-    export interface Function {
-      arguments: string;
-
-      name: string;
-
-      [k: string]: unknown;
-    }
-  }
-
-  export interface ToolReturn {
-    /**
-     * The status of the tool call
-     */
-    status: 'success' | 'error';
-
-    /**
-     * The function response string
-     */
-    func_response?: string | null;
-
-    /**
-     * Captured stderr from the tool invocation
-     */
-    stderr?: Array<string> | null;
-
-    /**
-     * Captured stdout (e.g. prints, logs) from the tool invocation
-     */
-    stdout?: Array<string> | null;
-
-    /**
-     * The ID for the tool call
-     */
-    tool_call_id?: unknown;
-  }
-}
+export type Message =
+  | SystemMessage
+  | UserMessage
+  | ReasoningMessage
+  | HiddenReasoningMessage
+  | ToolCallMessage
+  | ToolsAPI.ToolReturnMessage
+  | AssistantMessage
+  | ApprovalRequestMessage
+  | ApprovalResponseMessage
+  | SummaryMessage
+  | EventMessage;
 
 export type MessageRole = 'assistant' | 'user' | 'tool' | 'function' | 'system' | 'approval';
 
@@ -2289,14 +2241,15 @@ export declare namespace Messages {
     type ApprovalCreate as ApprovalCreate,
     type ApprovalRequestMessage as ApprovalRequestMessage,
     type ApprovalResponseMessage as ApprovalResponseMessage,
+    type ApprovalReturn as ApprovalReturn,
     type AssistantMessage as AssistantMessage,
     type EventMessage as EventMessage,
     type HiddenReasoningMessage as HiddenReasoningMessage,
     type ImageContent as ImageContent,
+    type InternalMessage as InternalMessage,
     type JobStatus as JobStatus,
     type JobType as JobType,
     type LettaAssistantMessageContentUnion as LettaAssistantMessageContentUnion,
-    type LettaMessageUnion as LettaMessageUnion,
     type LettaRequest as LettaRequest,
     type LettaResponse as LettaResponse,
     type LettaStreamingRequest as LettaStreamingRequest,
@@ -2326,7 +2279,7 @@ export declare namespace Messages {
     type UserMessage as UserMessage,
     type MessageCancelResponse as MessageCancelResponse,
     type MessageModifyResponse as MessageModifyResponse,
-    type LettaMessageUnionsArrayPage as LettaMessageUnionsArrayPage,
+    type MessagesArrayPage as MessagesArrayPage,
     type MessageListParams as MessageListParams,
     type MessageCancelParams as MessageCancelParams,
     type MessageModifyParams as MessageModifyParams,