feat: add support for default conversation via --conv default (#580)

Co-authored-by: Letta <noreply@letta.com>

src/agent/message.ts

@@ -18,6 +18,10 @@ export const STREAM_REQUEST_START_TIME = Symbol("streamRequestStartTime");
 /**
  * Send a message to a conversation and return a streaming response.
  * Uses the conversations API for proper message isolation per session.
+ *
+ * For the "default" conversation (agent's primary message history without
+ * an explicit conversation object), pass conversationId="default" and
+ * provide agentId in opts. This uses the agents messages API instead.
  */
 export async function sendMessageStream(
   conversationId: string,
@@ -25,7 +29,7 @@ export async function sendMessageStream(
   opts: {
     streamTokens?: boolean;
     background?: boolean;
-    // add more later: includePings, request timeouts, etc.
+    agentId?: string; // Required when conversationId is "default"
   } = { streamTokens: true, background: true },
   // TODO: Re-enable once issues are resolved - disabled retries were causing problems
   // Disable SDK retries by default - state management happens outside the stream,
@@ -37,17 +41,47 @@ export async function sendMessageStream(
   const requestStartTime = isTimingsEnabled() ? performance.now() : undefined;
 
   const client = await getClient();
-  const stream = await client.conversations.messages.create(
-    conversationId,
-    {
-      messages: messages,
-      streaming: true,
-      stream_tokens: opts.streamTokens ?? true,
-      background: opts.background ?? true,
-      client_tools: getClientToolsFromRegistry(),
-    },
-    requestOptions,
-  );
+
+  let stream: Stream<LettaStreamingResponse>;
+
+  if (process.env.DEBUG) {
+    console.log(
+      `[DEBUG] sendMessageStream: conversationId=${conversationId}, useAgentsRoute=${conversationId === "default"}`,
+    );
+  }
+
+  if (conversationId === "default") {
+    // Use agents route for default conversation (agent's primary message history)
+    if (!opts.agentId) {
+      throw new Error(
+        "agentId is required in opts when using default conversation",
+      );
+    }
+    stream = await client.agents.messages.create(
+      opts.agentId,
+      {
+        messages: messages,
+        streaming: true,
+        stream_tokens: opts.streamTokens ?? true,
+        background: opts.background ?? true,
+        client_tools: getClientToolsFromRegistry(),
+      },
+      requestOptions,
+    );
+  } else {
+    // Use conversations route for explicit conversations
+    stream = await client.conversations.messages.create(
+      conversationId,
+      {
+        messages: messages,
+        streaming: true,
+        stream_tokens: opts.streamTokens ?? true,
+        background: opts.background ?? true,
+        client_tools: getClientToolsFromRegistry(),
+      },
+      requestOptions,
+    );
+  }
 
   // Attach start time to stream for TTFT calculation in drainStream
   if (requestStartTime !== undefined) {