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

package/src/remote-session-protocol.ts

@@ -55,6 +55,8 @@ export type RuntimeTurnResult = {
 
 export type RuntimeSendTurnOptions = {
   clientMessageId: string;
+  /** Caller-supplied OTID for the user message, when one was provided. */
+  otid?: string;
 };
 
 export type RuntimeRequestOptions = {
@@ -128,6 +130,8 @@ export type TurnTracker = {
   id: number;
   runtime: RuntimeScope;
   clientMessageId: string;
+  /** Caller-supplied OTID for this turn's user message, when one was provided. */
+  otid?: string;
   queuedAt: number;
   startedAt: number;
   assistantText: string;
@@ -677,3 +681,23 @@ export function toSessionDeviceStatus(
 export function normalizeSendMessage(message: SendMessage): string | MessageContentItem[] {
   return message;
 }
+
+/**
+ * Validate a caller-supplied OTID. Empty/whitespace-only values would silently
+ * defeat correlation, so they are rejected instead of being dropped.
+ */
+export function normalizeCallerOtid(otid: string | undefined): string | undefined {
+  if (otid === undefined) return undefined;
+  if (typeof otid !== "string" || otid.trim() === "") {
+    throw new Error("send() otid must be a non-empty string");
+  }
+  return otid;
+}
+
+/** Wire correlation options for a tracked turn. */
+export function turnSendOptions(turn: TurnTracker): RuntimeSendTurnOptions {
+  return {
+    clientMessageId: turn.clientMessageId,
+    ...(turn.otid !== undefined ? { otid: turn.otid } : {}),
+  };
+}

package/src/remote-turn-coordinator.ts

@@ -15,6 +15,7 @@ import {
   isApprovalConflictSignal,
   loopStatusRunIds,
   loopStatusValue,
+  normalizeCallerOtid,
   queueItems,
   sameRuntime,
   streamDeltaMessageType,
@@ -76,11 +77,19 @@ export class RemoteTurnCoordinator {
     return this.activeTurn !== null || this.pendingTurns.length > 0;
   }
 
-  trackSentTurn(runtime: RuntimeScope): TurnTracker {
+  /**
+   * Start tracking a turn. A caller-supplied OTID doubles as the turn's
+   * `clientMessageId` so queue updates carry the same correlation id the
+   * persisted message will; otherwise the SDK mints one.
+   */
+  trackSentTurn(runtime: RuntimeScope, callerOtid?: string): TurnTracker {
+    const otid = normalizeCallerOtid(callerOtid);
     const turn: TurnTracker = {
       id: ++this.nextTurnId,
       runtime,
-      clientMessageId: `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
+      ...(otid !== undefined ? { otid } : {}),
+      clientMessageId:
+        otid ?? `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
       queuedAt: Date.now(),
       startedAt: 0,
       assistantText: "",