@letta-ai/letta-agent-sdk 0.7.3 → 0.7.4

package/dist/management-errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The App Server created a fork but the SDK could not retrieve its full state.
+ * `conversationId` remains available so the caller can inspect or archive it.
+ */
+export declare class ConversationForkHydrationError extends Error {
+    readonly conversationId: string;
+    constructor(conversationId: string, cause: unknown);
+}
+//# sourceMappingURL=management-errors.d.ts.map

package/dist/management-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"management-errors.d.ts","sourceRoot":"","sources":["../src/management-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAEpB,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAQnD"}

package/dist/management-types.d.ts

@@ -1,6 +1,6 @@
 import type { AgentListParams, AgentState, AgentUpdateParams } from "@letta-ai/letta-client/resources/agents/agents";
 import type { Message } from "@letta-ai/letta-client/resources/agents/messages";
-import type { Conversation, ConversationCreateParams, ConversationListParams, ConversationUpdateParams } from "@letta-ai/letta-client/resources/conversations/conversations";
+import type { Conversation, ConversationCreateParams, ConversationForkParams, ConversationListParams, ConversationUpdateParams } from "@letta-ai/letta-client/resources/conversations/conversations";
 import type { MessageListParams } from "@letta-ai/letta-client/resources/conversations/messages";
 import type { ListMessagesResult, ListModelsResult } from "./types.js";
 /** Agent state returned by either the Cloud API or Letta Code app-server. */
@@ -61,6 +61,12 @@ export interface UpdateConversationOptions {
     contextWindowLimit?: ConversationUpdateParams["context_window_limit"];
     archived?: ConversationUpdateParams["archived"];
 }
+export interface ForkConversationOptions {
+    /** Include source messages through this message, inclusive. */
+    messageId?: Present<ConversationForkParams["message_id"]>;
+    /** Hide the fork from normal conversation listings. */
+    hidden?: Present<ConversationForkParams["hidden"]>;
+}
 export interface ConversationMessagesOptions {
     /** Return messages before this message ID (cursor for older pages, regardless of `order`). */
     before?: Present<MessageListParams["before"]>;
@@ -128,6 +134,12 @@ export interface ConversationsClient {
     retrieve(conversationId: string): Promise<LettaConversation>;
     create(options: CreateConversationOptions): Promise<LettaConversation>;
     update(conversationId: string, options: UpdateConversationOptions): Promise<LettaConversation>;
+    /**
+     * Create a persistent conversation from the source's in-context history.
+     * Use `update()` to change the fork's model. Archive a temporary fork with
+     * `update(fork.id, { archived: true })` when it is done.
+     */
+    fork(sourceConversationId: string, options?: ForkConversationOptions): Promise<LettaConversation>;
     listMessages(conversationId: string, options?: ConversationMessagesOptions): Promise<ConversationMessagesResult>;
 }
 export {};

package/dist/management-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"management-types.d.ts","sourceRoot":"","sources":["../src/management-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"management-types.d.ts","sourceRoot":"","sources":["../src/management-types.ts"],"names":[],"mappings":"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"}

package/dist/management.d.ts

@@ -1,5 +1,5 @@
 import type { AgentListParams, AgentUpdateParams } from "@letta-ai/letta-client/resources/agents/agents";
-import type { ConversationCreateParams, ConversationListParams, ConversationUpdateParams } from "@letta-ai/letta-client/resources/conversations/conversations";
+import type { ConversationCreateParams, ConversationForkParams, ConversationListParams, ConversationUpdateParams } from "@letta-ai/letta-client/resources/conversations/conversations";
 import type { MessageListParams } from "@letta-ai/letta-client/resources/conversations/messages";
 import type { AgentRepositoriesClient, AgentsClient, ConversationsClient, ConversationMessagesResult, LettaAgent, LettaConversation, ModelsClient } from "./management-types.js";
 import type { ListModelsResult } from "./types.js";
@@ -13,6 +13,7 @@ export interface ManagementTransport {
     retrieveConversation(conversationId: string): Promise<LettaConversation>;
     createConversation(body: ConversationCreateParams): Promise<LettaConversation>;
     updateConversation(conversationId: string, body: ConversationUpdateParams): Promise<LettaConversation>;
+    forkConversation(conversationId: string, query: ConversationForkParams): Promise<LettaConversation>;
     listConversationMessages(conversationId: string, query: MessageListParams): Promise<ConversationMessagesResult>;
 }
 type TransportProvider = () => ManagementTransport;

package/dist/management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EACV,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACzB,MAAM,8DAA8D,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAC;AACjG,OAAO,KAAK,EACV,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,0BAA0B,EAE1B,UAAU,EACV,iBAAiB,EAGjB,YAAY,EAIb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACpD,WAAW,CACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxC,iBAAiB,CACf,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAChC,oBAAoB,CAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,kBAAkB,CAChB,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,kBAAkB,CAChB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,wBAAwB,CACtB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,0BAA0B,CAAC,CAAC;CACxC;AAED,KAAK,iBAAiB,GAAG,MAAM,mBAAmB,CAAC;AAqGnD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,MAAM,uBAAuB,GAC1C,YAAY,CAed;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,iBAAiB,GAC3B,YAAY,CAId;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,iBAAiB,GAC3B,mBAAmB,CAmBrB"}
+{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EACV,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACzB,MAAM,8DAA8D,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAC;AACjG,OAAO,KAAK,EACV,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,0BAA0B,EAG1B,UAAU,EACV,iBAAiB,EAGjB,YAAY,EAIb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACpD,WAAW,CACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxC,iBAAiB,CACf,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAChC,oBAAoB,CAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,kBAAkB,CAChB,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,kBAAkB,CAChB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,gBAAgB,CACd,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,wBAAwB,CACtB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,0BAA0B,CAAC,CAAC;CACxC;AAED,KAAK,iBAAiB,GAAG,MAAM,mBAAmB,CAAC;AA8GnD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,MAAM,uBAAuB,GAC1C,YAAY,CAed;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,iBAAiB,GAC3B,YAAY,CAId;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,iBAAiB,GAC3B,mBAAmB,CA6BrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-agent-sdk",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "packageManager": "bun@1.3.0",
   "description": "SDK for programmatic control of Letta agents",
   "type": "module",

package/src/app-server-management.ts

@@ -10,6 +10,7 @@ import type {
   AgentRetrieveResponseMessage,
   AgentUpdateResponseMessage,
   ConversationCreateResponseMessage,
+  ConversationForkResponseMessage,
   ConversationListResponseMessage,
   ConversationMessagesListResponseMessage,
   ConversationRetrieveResponseMessage,
@@ -22,11 +23,13 @@ import type {
 } from "@letta-ai/letta-client/resources/agents/agents";
 import type {
   ConversationCreateParams,
+  ConversationForkParams,
   ConversationListParams,
   ConversationUpdateParams,
 } from "@letta-ai/letta-client/resources/conversations/conversations";
 import type { MessageListParams } from "@letta-ai/letta-client/resources/conversations/messages";
 import { normalizeAppServerModels } from "./app-server-models.js";
+import { ConversationForkHydrationError } from "./management-errors.js";
 import type { ManagementTransport } from "./management.js";
 import { applyUniqueRequestIds } from "./request-ids.js";
 import type {
@@ -199,6 +202,27 @@ export class AppServerManagementTransport
     );
   }
 
+  async forkConversation(
+    conversationId: string,
+    body: ConversationForkParams,
+  ): Promise<LettaConversation> {
+    const response = await this.request<ConversationForkResponseMessage>(
+      "conversation_fork",
+      { conversation_id: conversationId, body },
+      "conversation_fork_response",
+    );
+    const fork = ensureResponse(
+      response,
+      response.conversation,
+      `Failed to fork conversation ${conversationId}.`,
+    );
+    try {
+      return await this.retrieveConversation(fork.id);
+    } catch (error) {
+      throw new ConversationForkHydrationError(fork.id, error);
+    }
+  }
+
   async listConversationMessages(
     conversationId: string,
     query: MessageListParams,

package/src/client-entry.ts

@@ -24,6 +24,7 @@ export class LettaAgentClient extends LettaAgentClientBase {
 }
 
 export { CloudManagedSandboxExpiredError } from "./cloud-session.js";
+export { ConversationForkHydrationError } from "./management-errors.js";
 export { RepositoriesClient } from "./repositories.js";
 export type {
   Computer,

package/src/cloud-management.ts

@@ -6,6 +6,7 @@ import type {
 } from "@letta-ai/letta-client/resources/agents/agents";
 import type {
   ConversationCreateParams,
+  ConversationForkParams,
   ConversationListParams,
   ConversationUpdateParams,
 } from "@letta-ai/letta-client/resources/conversations/conversations";
@@ -217,6 +218,13 @@ export class CloudManagementTransport implements ManagementTransport {
     return this.client.conversations.update(conversationId, body);
   }
 
+  async forkConversation(
+    conversationId: string,
+    query: ConversationForkParams,
+  ): Promise<LettaConversation> {
+    return this.client.conversations.fork(conversationId, query);
+  }
+
   async listConversationMessages(
     conversationId: string,
     query: MessageListParams,

package/src/index.ts

@@ -166,6 +166,7 @@ export type {
   UpdateAgentOptions,
   ListConversationsOptions,
   CreateConversationOptions,
+  ForkConversationOptions,
   UpdateConversationOptions,
   ConversationMessagesOptions,
   ConversationMessagesResult,
@@ -174,6 +175,7 @@ export type {
 } from "./management-types.js";
 
 export { RepositoriesClient } from "./repositories.js";
+export { ConversationForkHydrationError } from "./management-errors.js";
 export type {
   Computer,
   ComputerMetadata,

package/src/management-errors.ts

@@ -0,0 +1,16 @@
+/**
+ * The App Server created a fork but the SDK could not retrieve its full state.
+ * `conversationId` remains available so the caller can inspect or archive it.
+ */
+export class ConversationForkHydrationError extends Error {
+  readonly conversationId: string;
+
+  constructor(conversationId: string, cause: unknown) {
+    super(
+      `Conversation ${conversationId} was forked, but its state could not be retrieved.`,
+      { cause },
+    );
+    this.name = "ConversationForkHydrationError";
+    this.conversationId = conversationId;
+  }
+}

package/src/management-types.ts

@@ -7,6 +7,7 @@ import type { Message } from "@letta-ai/letta-client/resources/agents/messages";
 import type {
   Conversation,
   ConversationCreateParams,
+  ConversationForkParams,
   ConversationListParams,
   ConversationUpdateParams,
 } from "@letta-ai/letta-client/resources/conversations/conversations";
@@ -80,6 +81,13 @@ export interface UpdateConversationOptions {
   archived?: ConversationUpdateParams["archived"];
 }
 
+export interface ForkConversationOptions {
+  /** Include source messages through this message, inclusive. */
+  messageId?: Present<ConversationForkParams["message_id"]>;
+  /** Hide the fork from normal conversation listings. */
+  hidden?: Present<ConversationForkParams["hidden"]>;
+}
+
 export interface ConversationMessagesOptions {
   /** Return messages before this message ID (cursor for older pages, regardless of `order`). */
   before?: Present<MessageListParams["before"]>;
@@ -172,6 +180,15 @@ export interface ConversationsClient {
     conversationId: string,
     options: UpdateConversationOptions,
   ): Promise<LettaConversation>;
+  /**
+   * Create a persistent conversation from the source's in-context history.
+   * Use `update()` to change the fork's model. Archive a temporary fork with
+   * `update(fork.id, { archived: true })` when it is done.
+   */
+  fork(
+    sourceConversationId: string,
+    options?: ForkConversationOptions,
+  ): Promise<LettaConversation>;
   listMessages(
     conversationId: string,
     options?: ConversationMessagesOptions,

package/src/management.ts

@@ -4,6 +4,7 @@ import type {
 } from "@letta-ai/letta-client/resources/agents/agents";
 import type {
   ConversationCreateParams,
+  ConversationForkParams,
   ConversationListParams,
   ConversationUpdateParams,
 } from "@letta-ai/letta-client/resources/conversations/conversations";
@@ -14,6 +15,7 @@ import type {
   ConversationsClient,
   ConversationMessagesResult,
   CreateConversationOptions,
+  ForkConversationOptions,
   LettaAgent,
   LettaConversation,
   ListAgentsOptions,
@@ -47,6 +49,10 @@ export interface ManagementTransport {
     conversationId: string,
     body: ConversationUpdateParams,
   ): Promise<LettaConversation>;
+  forkConversation(
+    conversationId: string,
+    query: ConversationForkParams,
+  ): Promise<LettaConversation>;
   listConversationMessages(
     conversationId: string,
     query: MessageListParams,
@@ -143,6 +149,15 @@ function conversationUpdateBody(
   };
 }
 
+function conversationForkQuery(
+  options: ForkConversationOptions,
+): ConversationForkParams {
+  return {
+    message_id: options.messageId,
+    hidden: options.hidden,
+  };
+}
+
 function conversationMessagesQuery(
   options: ConversationMessagesOptions,
 ): MessageListParams {
@@ -197,6 +212,16 @@ export function createConversationsClient(
         conversationId,
         conversationUpdateBody(options),
       ),
+    fork: async (sourceConversationId, options = {}) => {
+      assertNonEmptyId(sourceConversationId, "conversation id");
+      if (options.messageId !== undefined) {
+        assertNonEmptyId(options.messageId, "message id");
+      }
+      return await transport().forkConversation(
+        sourceConversationId,
+        conversationForkQuery(options),
+      );
+    },
     listMessages: (conversationId, options = {}) =>
       transport().listConversationMessages(
         conversationId,