fix(api): normalize Letta URLs and avoid self-hosted conversations redirect (#31)

Use a shared URL builder across scripts and update createConversation to call /v1/conversations/ with query params to avoid HTTPS->HTTP redirect failures behind reverse proxies. This also deduplicates LETTA_API_BASE handling and adds regression tests for trailing-slash behavior.

👾 Generated with [Letta Code](https://letta.com)

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

Author: cpfiffer

scripts/agent_config.ts

@@ -15,12 +15,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+import { buildLettaApiUrl } from './letta_api_url.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const LETTA_BASE_URL = process.env.LETTA_BASE_URL || 'https://api.letta.com';
-const LETTA_API_BASE = `${LETTA_BASE_URL}/v1`;
 const CONFIG_DIR = path.join(process.env.HOME || '~', '.letta', 'claude-subconscious');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const DEFAULT_AGENT_FILE = path.join(__dirname, '..', 'Subconscious.af');
@@ -154,7 +153,7 @@ function getAgentNameFromFile(): string {
  * Rename an agent
  */
 async function renameAgent(apiKey: string, agentId: string, name: string): Promise<void> {
-  const url = `${LETTA_API_BASE}/agents/${agentId}`;
+  const url = buildLettaApiUrl(`/agents/${agentId}`);
 
   const response = await fetch(url, {
     method: 'PATCH',
@@ -175,7 +174,7 @@ async function renameAgent(apiKey: string, agentId: string, name: string): Promi
  * List available models from Letta server
  */
 async function listAvailableModels(apiKey: string): Promise<LettaModel[]> {
-  const url = `${LETTA_API_BASE}/models/`;
+  const url = buildLettaApiUrl('/models/');
 
   const response = await fetch(url, {
     method: 'GET',
@@ -195,7 +194,7 @@ async function listAvailableModels(apiKey: string): Promise<LettaModel[]> {
  * Get agent details including current model configuration
  */
 async function getAgentDetails(apiKey: string, agentId: string): Promise<AgentDetails> {
-  const url = `${LETTA_API_BASE}/agents/${agentId}`;
+  const url = buildLettaApiUrl(`/agents/${agentId}`);
 
   const response = await fetch(url, {
     method: 'GET',
@@ -402,7 +401,7 @@ async function updateAgentModel(
   currentConfig: LlmConfig | undefined,
   log: (msg: string) => void = console.log
 ): Promise<void> {
-  const url = `${LETTA_API_BASE}/agents/${agentId}`;
+  const url = buildLettaApiUrl(`/agents/${agentId}`);
 
   log(`Updating agent model to: ${modelHandle}`);
 
@@ -433,7 +432,7 @@ async function updateAgentModel(
  * Import agent from .af file
  */
 async function importDefaultAgent(apiKey: string): Promise<string> {
-  const url = `${LETTA_API_BASE}/agents/import`;
+  const url = buildLettaApiUrl('/agents/import');
 
   // Read the agent file
   const agentFileContent = fs.readFileSync(DEFAULT_AGENT_FILE);

scripts/conversation_utils.test.ts

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const fetchMock = vi.fn();
+
+vi.stubGlobal('fetch', fetchMock);
+
+describe('createConversation', () => {
+  afterEach(() => {
+    fetchMock.mockReset();
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('uses trailing-slash conversations endpoint with agent_id query', async () => {
+    vi.stubEnv('LETTA_BASE_URL', 'https://letta.example.com');
+
+    fetchMock.mockResolvedValue({
+      ok: true,
+      json: async () => ({ id: 'conversation-123' }),
+    });
+
+    const { createConversation } = await import('./conversation_utils.js');
+    const conversationId = await createConversation('test-key', 'agent-123');
+
+    expect(conversationId).toBe('conversation-123');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://letta.example.com/v1/conversations/?agent_id=agent-123',
+      expect.objectContaining({
+        method: 'POST',
+        headers: expect.objectContaining({
+          Authorization: 'Bearer test-key',
+        }),
+      }),
+    );
+  });
+});

scripts/conversation_utils.ts

@@ -8,14 +8,17 @@ import * as os from 'os';
 import * as path from 'path';
 import { spawn, ChildProcess } from 'child_process';
 import { fileURLToPath } from 'url';
+import {
+  buildLettaApiUrl,
+  LETTA_API_BASE,
+} from './letta_api_url.js';
 
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // Configuration
-const LETTA_BASE_URL = process.env.LETTA_BASE_URL || 'https://api.letta.com';
-export const LETTA_API_BASE = `${LETTA_BASE_URL}/v1`;
+export { LETTA_API_BASE };
 // Only show app URL for hosted service; self-hosted users get IDs directly
 const IS_HOSTED = !process.env.LETTA_BASE_URL;
 const LETTA_APP_BASE = 'https://app.letta.com';
@@ -202,7 +205,7 @@ export function saveConversationsMap(cwd: string, map: ConversationsMap): void {
  * Create a new conversation for an agent
  */
 export async function createConversation(apiKey: string, agentId: string, log: LogFn = noopLog): Promise<string> {
-  const url = `${LETTA_API_BASE}/conversations?agent_id=${agentId}`;
+  const url = buildLettaApiUrl('/conversations/', { agent_id: agentId });
 
   log(`Creating new conversation for agent ${agentId}`);
 
@@ -339,7 +342,9 @@ export interface Agent {
  * Fetch agent data from Letta API
  */
 export async function fetchAgent(apiKey: string, agentId: string): Promise<Agent> {
-  const url = `${LETTA_API_BASE}/agents/${agentId}?include=agent.blocks`;
+  const url = buildLettaApiUrl(`/agents/${agentId}`, {
+    include: 'agent.blocks',
+  });
 
   const response = await fetch(url, {
     method: 'GET',

scripts/letta_api_url.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  buildLettaApiUrl,
+  getLettaApiBase,
+  normalizeLettaBaseUrl,
+} from './letta_api_url.js';
+
+describe('letta_api_url', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('normalizes base URL by trimming trailing slash', () => {
+    expect(normalizeLettaBaseUrl('https://example.com/')).toBe(
+      'https://example.com',
+    );
+    expect(normalizeLettaBaseUrl('https://example.com///')).toBe(
+      'https://example.com',
+    );
+  });
+
+  it('builds /v1 base URL unless already present', () => {
+    expect(getLettaApiBase('https://example.com')).toBe(
+      'https://example.com/v1',
+    );
+    expect(getLettaApiBase('https://example.com/v1')).toBe(
+      'https://example.com/v1',
+    );
+  });
+
+  it('builds URLs with optional query params', () => {
+    const url = buildLettaApiUrl('/agents/agent-123', {
+      include: 'agent.blocks',
+      limit: 20,
+    });
+
+    expect(url).toBe(
+      'https://api.letta.com/v1/agents/agent-123?include=agent.blocks&limit=20',
+    );
+  });
+
+  it('preserves trailing slash path for conversations create endpoint', () => {
+    const url = buildLettaApiUrl('/conversations/', { agent_id: 'agent-123' });
+
+    expect(url).toBe(
+      'https://api.letta.com/v1/conversations/?agent_id=agent-123',
+    );
+  });
+});

scripts/letta_api_url.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared Letta API URL helpers.
+ *
+ * Centralizes base URL normalization and endpoint URL construction.
+ */
+
+export type LettaApiQueryValue = string | number | boolean | null | undefined;
+
+export type LettaApiQuery = Record<string, LettaApiQueryValue>;
+
+export function normalizeLettaBaseUrl(baseUrl = process.env.LETTA_BASE_URL): string {
+  const rawBase = baseUrl?.trim() || 'https://api.letta.com';
+  return rawBase.replace(/\/+$/, '');
+}
+
+export function getLettaApiBase(baseUrl = process.env.LETTA_BASE_URL): string {
+  const normalizedBase = normalizeLettaBaseUrl(baseUrl);
+  return normalizedBase.endsWith('/v1')
+    ? normalizedBase
+    : `${normalizedBase}/v1`;
+}
+
+export const LETTA_BASE_URL = normalizeLettaBaseUrl();
+export const LETTA_API_BASE = getLettaApiBase();
+
+export function buildLettaApiUrl(
+  path: string,
+  query: LettaApiQuery = {},
+  apiBase: string = LETTA_API_BASE,
+): string {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  const normalizedApiBase = apiBase.replace(/\/+$/, '');
+  const url = new URL(`${normalizedApiBase}${normalizedPath}`);
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    url.searchParams.set(key, String(value));
+  }
+
+  return url.toString();
+}

scripts/pretool_sync.ts

@@ -17,13 +17,13 @@
 import * as fs from 'fs';
 import * as readline from 'readline';
 import { getAgentId } from './agent_config.js';
+import { buildLettaApiUrl } from './letta_api_url.js';
 import {
   loadSyncState,
   saveSyncState,
   lookupConversation,
   SyncState,
   getMode,
-  LETTA_API_BASE,
 } from './conversation_utils.js';
 
 const DEBUG = process.env.LETTA_DEBUG === '1';
@@ -100,7 +100,9 @@ async function readHookInput(): Promise<HookInput | null> {
  * Fetch agent data from Letta API
  */
 async function fetchAgent(apiKey: string, agentId: string): Promise<Agent> {
-  const url = `${LETTA_API_BASE}/agents/${agentId}?include=agent.blocks`;
+  const url = buildLettaApiUrl(`/agents/${agentId}`, {
+    include: 'agent.blocks',
+  });
 
   const response = await fetch(url, {
     method: 'GET',
@@ -129,7 +131,9 @@ async function fetchNewMessages(
     return { messages: [], lastMessageId: null };
   }
 
-  const url = `${LETTA_API_BASE}/conversations/${conversationId}/messages?limit=20`;
+  const url = buildLettaApiUrl(`/conversations/${conversationId}/messages`, {
+    limit: 20,
+  });
 
   const response = await fetch(url, {
     method: 'GET',

scripts/session_start.ts

@@ -33,10 +33,9 @@ import {
   getTempStateDir,
   getSdkToolsMode,
 } from './conversation_utils.js';
+import { buildLettaApiUrl } from './letta_api_url.js';
 
 // Configuration
-const LETTA_BASE_URL = process.env.LETTA_BASE_URL || 'https://api.letta.com';
-const LETTA_API_BASE = `${LETTA_BASE_URL}/v1`;
 const TEMP_STATE_DIR = getTempStateDir();
 const LOG_FILE = path.join(TEMP_STATE_DIR, 'session_start.log');
 
@@ -173,7 +172,7 @@ async function sendSessionStartMessage(
   sessionId: string,
   cwd: string
 ): Promise<void> {
-  const url = `${LETTA_API_BASE}/conversations/${conversationId}/messages`;
+  const url = buildLettaApiUrl(`/conversations/${conversationId}/messages`);
 
   const projectName = path.basename(cwd);
   const timestamp = new Date().toISOString();

scripts/sync_letta_memory.ts

@@ -21,6 +21,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
 import { getAgentId } from './agent_config.js';
+import { buildLettaApiUrl } from './letta_api_url.js';
 import {
   loadSyncState,
   saveSyncState,
@@ -35,7 +36,6 @@ import {
   cleanLettaFromClaudeMd,
   getMode,
   getTempStateDir,
-  LETTA_API_BASE,
 } from './conversation_utils.js';
 
 // Configuration
@@ -198,7 +198,9 @@ async function fetchAssistantMessages(
 
   // Use a high limit because Letta returns multiple entries per logical message
   // (hidden_reasoning + assistant_message pairs), so limit=50 may not reach newest messages
-  const url = `${LETTA_API_BASE}/conversations/${conversationId}/messages?limit=300`;
+  const url = buildLettaApiUrl(`/conversations/${conversationId}/messages`, {
+    limit: 300,
+  });
 
   const response = await fetch(url, {
     method: 'GET',