@data-club/ai-hub-server 0.0.1

package/src/letta/client.ts

@@ -0,0 +1,860 @@
+/**
+ * Hybrid Letta access layer.
+ *
+ * **Two SDKs, two roles:**
+ *
+ * - **`@letta-ai/letta-client`** owns *direct REST operations* —
+ *   `retrieveAgent`, `createConversation`, `listMessages`. These are
+ *   stable agent / conversation / message CRUD against the Letta
+ *   server's REST surface; they don't involve model routing or
+ *   provider shape.
+ * - **`@letta-ai/letta-code-sdk`** owns the *chat-streaming path* —
+ *   `streamUserMessage`. Spawns a Letta Code CLI subprocess per turn;
+ *   the CLI's internal Pi (Provider Interface) + bundled `models.json`
+ *   handle model selection, reasoning-tier presets, and provider
+ *   fallback routing (e.g. Anthropic → Bedrock Opus 4.7). This is what
+ *   keeps ai-hub current with model releases without code changes.
+ *
+ * **The hard rule from §6.4 is preserved** — every Letta interaction
+ * goes through one of these two SDKs; no raw HTTP, no parallel fetch.
+ *
+ * Configuration source: `admin_setting.letta_base_url` +
+ * `admin_setting.letta_api_key_encrypted` (decrypted with
+ * `AI_HUB_ENCRYPTION_KEY`). The Letta-Client wrapper memoizes one SDK
+ * instance per `(apiKey, baseURL)` pair so super-admin connection
+ * edits propagate without restart. The Letta-Code subprocess inherits
+ * `process.env` (which must carry `LETTA_BASE_URL` + `LETTA_API_KEY` —
+ * the boot script sets these from the same decrypted DB row).
+ *
+ * @see SPECIFICATIONS.md §6.4 — Letta integration
+ * @see SPECIFICATIONS.md §6.4.1 — first-class SDK surfaces
+ */
+
+import { eq } from "drizzle-orm";
+
+import LettaSdkDefault, {
+  NotFoundError,
+} from "@letta-ai/letta-client";
+import {
+  resumeSession,
+  type SDKMessage,
+  type Session,
+} from "@letta-ai/letta-code-sdk";
+
+import { decryptString } from "../auth/encryption.js";
+import { adminSetting } from "../db/schema.js";
+import type { DrizzleDB } from "../db/connection.js";
+
+import { seedAgentToolsetNone } from "./settingsFileSeed.js";
+import {
+  type SubprocessThrottle,
+  type ThrottleLease,
+} from "./subprocessThrottle.js";
+
+import type {
+  LettaMessage,
+  LettaSdk,
+} from "./types.js";
+
+// Re-export so consumers don't need to know about the throttle module.
+export { ServerOverloadedError, SubprocessThrottle } from "./subprocessThrottle.js";
+
+/**
+ * Thrown when `forkConversation(sourceId)` or `retrieveConversation(id)`
+ * resolves to "no such conversation" (Letta 404). The admin agents
+ * validator catches this and returns `400 fork_source_not_found` inline
+ * on the field; the chat route surfaces it as a 500 (admin-side
+ * validation should have caught it before any user-facing session
+ * create reached the fork path).
+ *
+ * @see docs/server/session-sandboxes.md
+ */
+export class ForkSourceNotFoundError extends Error {
+  constructor(public readonly conversationId: string) {
+    super(`Letta conversation not found: ${conversationId}`);
+    this.name = "ForkSourceNotFoundError";
+  }
+}
+
+/**
+ * Letta Code's bundled tools that are ALWAYS disallowed regardless of
+ * whether a per-session sandbox is configured.
+ *
+ * Includes:
+ * - Memory tools (the v1 no-memory stance keeps these forbidden; see
+ *   docs/admin/agent-management.md).
+ * - Sub-agent management (`Task` / `TaskOutput` / `TaskStop` / `TodoWrite`
+ *   / `Skill`) — not exposed to ai-hub end users.
+ * - Interactive tools (`AskUserQuestion` / `EnterPlanMode` /
+ *   `ExitPlanMode`) — hang the headless code path.
+ * - Web tools (`WebFetch` / `WebSearch`) — operator-curated agents
+ *   should reach the web through ADE-attached MCP tools, not Letta
+ *   Code's defaults.
+ *
+ * The filesystem tools (Read / Write / Edit / etc.) live in
+ * `FILESYSTEM_TOOLS` below and are disallowed ONLY when no sandbox is
+ * configured for the session.
+ *
+ * @see docs/server/session-sandboxes.md — the disallow-list split (Step 12.5)
+ */
+const ALWAYS_DISALLOWED_TOOLS: ReadonlyArray<string> = [
+  // Sub-agent + task management
+  "Task",
+  "TaskOutput",
+  "TaskStop",
+  "TodoWrite",
+  // Skills + slash invocation
+  "Skill",
+  // Memory (Letta Code's built-in memory file convenience tool) — the v1
+  // no-memory stance keeps these forbidden even when a sandbox is enabled.
+  "memory",
+  "memory_apply_patch",
+  "memory_insert",
+  "memory_replace",
+  "memory_rethink",
+  // Interactive tools that require runtime user input
+  "AskUserQuestion",
+  "EnterPlanMode",
+  "ExitPlanMode",
+  // Web tools (Letta Code adds these in the Claude toolset; harmless to
+  // disallow here if absent; future-proofs against upstream additions)
+  "WebFetch",
+  "WebSearch",
+];
+
+/**
+ * Letta Code's bundled filesystem / shell tools — disallowed when the
+ * session has NO sandbox configured (no `cwd` to confine them to), and
+ * re-enabled when the parent agent's `sandbox_seed_name` is set so the
+ * agent can actually use the seeded files (Step 12.5).
+ */
+const FILESYSTEM_TOOLS: ReadonlyArray<string> = [
+  // File / shell — every preset toolset's core set
+  "Read",
+  "Write",
+  "Edit",
+  "ApplyPatch",
+  "Bash",
+  "Glob",
+  "Grep",
+  // Snake-case variants from the codex_snake / gemini_snake toolsets
+  "read_file_lc",
+  "write_file_lc",
+  "edit_file_lc",
+  "execute_shell_lc",
+];
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Project surface                                                           */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Provider-reported token usage for a single Letta run + the run's
+ * last assistant-message id (so callers can stamp the badge on the
+ * visible bubble). All token fields are nullable because the
+ * producing provider may not report every dimension — Anthropic
+ * reports `cache_write_tokens`, others don't; reasoning tokens come
+ * back only when the model produced any; etc.
+ *
+ * Sourced via a single `GET /v1/runs/{run_id}/messages` call.
+ */
+export interface RunUsageStats {
+  /**
+   * Id of the LAST `assistant_message`-typed entry in the run. `null`
+   * when the run had no assistant messages (rare — error-only runs).
+   * Callers stamp `message_usage` against this id.
+   */
+  lastAssistantMessageId: string | null;
+  promptTokens: number | null;
+  completionTokens: number | null;
+  totalTokens: number | null;
+  cachedInputTokens: number | null;
+  cacheWriteTokens: number | null;
+  reasoningTokens: number | null;
+  contextTokens: number | null;
+}
+
+/** Parameters for `streamUserMessage`. */
+export interface StreamUserMessageOpts {
+  /** The Letta conversation id (`session.letta_conversation_id`). */
+  conversationId: string;
+  /**
+   * The Letta agent id the session is against. Required so we can
+   * re-seed `~/.letta/settings.json` on every spawn — concurrent CLI
+   * subprocesses race on writes and can wipe the entry, so the
+   * agent-registration-time seed isn't reliable on its own. The
+   * seed-on-spawn call below is idempotent (no-op when the entry
+   * is already present with the same value).
+   */
+  lettaAgentId: string;
+  /**
+   * Plain-text user message body. Sent verbatim to Letta. The admin's
+   * system prompt is delivered through Letta's normal channel (the
+   * agent's persisted `system` field), so we don't re-inject it here.
+   */
+  userMessage: string;
+  /**
+   * Step-12.5 — optional working directory for the spawned Letta Code
+   * subprocess. When set, threaded into the SDK's `resumeSession({ cwd })`
+   * option (maps to the CLI's `--cwd` flag). Used to confine the agent's
+   * filesystem-tool access to a per-session sandbox folder; when
+   * provided, the spawn ALSO drops the `FILESYSTEM_TOOLS` group from
+   * the `disallowedTools` list so the agent can actually read / write
+   * inside that folder.
+   *
+   * When `undefined`, no `cwd` is passed (the CLI inherits the
+   * ai-hub-server process's working directory, as it always has) AND
+   * the filesystem tools remain disallowed — today's stateless agent
+   * shape.
+   *
+   * @see docs/server/session-sandboxes.md
+   */
+  cwd?: string;
+}
+
+/**
+ * Handle returned by `streamUserMessage`. Wraps the Letta Code SDK
+ * `Session` + the subprocess-throttle lease so the caller owns one
+ * resource bundle to drain, cancel, and clean up.
+ *
+ * Lifecycle expectations:
+ *
+ * 1. Caller iterates `events` to consume `SDKMessage`s in real time.
+ * 2. At any point, calling `abort()` sends an `interrupt` control to
+ *    the spawned CLI. Behavior depends on what the CLI is doing —
+ *    during model generation interrupts work cleanly; during a
+ *    long-running tool call the interrupt is currently queued (see
+ *    migration plan §7 open question 5).
+ * 3. Caller MUST call `close()` in a `finally` regardless of how the
+ *    iteration ended (done, cancelled, error). `close()` terminates
+ *    the CLI subprocess + releases the throttle lease. Idempotent.
+ */
+export interface ChatTurnHandle {
+  /** Async iterable of Letta Code SDK messages — caller drains this. */
+  events: AsyncIterable<SDKMessage>;
+  /**
+   * Sends an `interrupt` control to the spawned CLI. Best-effort; if
+   * the CLI is mid-tool the interrupt may be queued. The caller still
+   * needs to call `close()` to release subprocess + lease.
+   */
+  abort(): Promise<void>;
+  /**
+   * Tears down the Letta Code subprocess + releases the throttle slot.
+   * Idempotent — safe to call twice. Caller MUST invoke this in a
+   * `finally`. Sync because the SDK's `session.close()` is sync.
+   */
+  close(): void;
+}
+
+/**
+ * Project-shaped Letta client. The handlers depend on this interface,
+ * not on the underlying SDKs, so tests can plug a mock implementation
+ * in via `getLettaClient` on the server context.
+ *
+ * @see SPECIFICATIONS.md §6.4
+ */
+export interface LettaClient {
+  /**
+   * Retrieves a Letta agent by id (via `@letta-ai/letta-client`).
+   * Returns `null` (not throws) on miss so the agent-validation flow
+   * on `POST/PATCH /admin/agents` can return a 400
+   * `letta_agent_not_found` without try/catch noise. Any non-404 SDK
+   * error rethrows — the admin handler returns 500.
+   *
+   * @param lettaAgentId - candidate Letta-side agent id.
+   * @returns the agent state or `null` if not found.
+   */
+  retrieveAgent(lettaAgentId: string): Promise<{
+    id: string;
+    name: string;
+    /** Provider-prefixed model handle (e.g. `"anthropic/claude-opus-4-7"`). */
+    model: string;
+  } | null>;
+  /**
+   * Creates a fresh conversation against the given Letta agent (via
+   * `@letta-ai/letta-client`). Returns the conversation id we store
+   * on the new session row.
+   *
+   * @param lettaAgentId - the Letta-side agent id.
+   * @returns the new conversation's id.
+   */
+  createConversation(lettaAgentId: string): Promise<{ id: string }>;
+  /**
+   * Step-12.5 — retrieves a Letta conversation by id (via
+   * `client.conversations.retrieve`). Used by the admin agents
+   * validator to verify `fork_source_conversation_id` resolves to a
+   * real conversation AND that its `agent_id` matches the agent's
+   * `letta_agent_id` (Letta's fork API requires same-agent forking).
+   *
+   * Returns `null` on Letta 404 so the handler can surface
+   * `400 fork_source_not_found` without try/catch noise; non-404
+   * SDK errors propagate.
+   *
+   * @param conversationId - the candidate Letta conversation id.
+   * @returns `{ id, agentId }` or `null` if not found.
+   */
+  retrieveConversation(
+    conversationId: string,
+  ): Promise<{ id: string; agentId: string } | null>;
+  /**
+   * Step-12.5 — forks an existing Letta conversation into a new
+   * conversation belonging to the same agent (via
+   * `client.conversations.fork`). The new conversation shares the
+   * source's in-context messages and gets a freshly compiled system
+   * message reflecting the agent's current memory-block values.
+   *
+   * Used by `POST /sessions` when the parent agent's
+   * `fork_source_conversation_id` is set. The admin endpoint validates
+   * source existence + agent match at write time, so this call is
+   * expected to succeed in the happy path; a 404 here is treated as
+   * "operator deleted the source conversation between admin-validate
+   * and user-session-create" and surfaced as `ForkSourceNotFoundError`.
+   *
+   * @param sourceConversationId - the Letta conversation id to fork.
+   * @returns the new conversation's `{ id, agentId }`.
+   * @throws ForkSourceNotFoundError on Letta 404.
+   */
+  forkConversation(
+    sourceConversationId: string,
+  ): Promise<{ id: string; agentId: string }>;
+  /**
+   * Lists every message in a conversation, oldest first (via
+   * `@letta-ai/letta-client`). Used for `GET /sessions/{id}/messages`
+   * history rendering.
+   *
+   * @param conversationId - the Letta conversation id.
+   * @returns the (oldest-first) array of messages.
+   */
+  listMessages(conversationId: string): Promise<ReadonlyArray<LettaMessage>>;
+  /**
+   * Deletes a single message from an agent's history by id.
+   *
+   * The typed SDK only exposes `create` / `list` on conversation messages,
+   * so this reaches the Letta server's `DELETE /v1/agents/{agent_id}/messages/{message_id}`
+   * endpoint via the SDK's raw HTTP escape hatch (`sdk.delete(...)`) — the
+   * same pattern `getRunUsageStats` uses for `sdk.get(...)`. A 404 is treated
+   * as "already gone" and swallowed; other errors propagate.
+   *
+   * Used by the rotation runner to remove the prompt's `user_message` so a
+   * rotating starting message's prepared conversation opens with the agent's
+   * reply.
+   *
+   * @param lettaAgentId - the agent the message belongs to.
+   * @param messageId - the message id (from `listMessages`).
+   */
+  deleteMessage(lettaAgentId: string, messageId: string): Promise<void>;
+  /**
+   * Deletes an entire Letta conversation (via `client.conversations.delete`).
+   * Best-effort cleanup of a rotating message's previous prepared
+   * conversation after a successful rotation produces a fresh one — a 404 is
+   * swallowed; other errors propagate to the caller (which logs + continues).
+   *
+   * @param conversationId - the Letta conversation id to delete.
+   */
+  deleteConversation(conversationId: string): Promise<void>;
+  /**
+   * Fetches provider-reported token usage for a Letta run, including
+   * prompt-cache hit / write counts. The SDK's `session.stream()`
+   * drops `usage_statistics` messages, so we re-fetch via REST after
+   * the turn lands; the runner uses this to stamp a usage badge on
+   * the last assistant message.
+   *
+   * Returns `null` when:
+   *   - the run id is unknown to Letta (404),
+   *   - the run hasn't emitted a usage_statistics message yet,
+   *   - the network call fails (best-effort — the badge is a nicety,
+   *     not load-bearing).
+   *
+   * @param runId - Letta run id captured from `SDKAssistantMessage.runId`.
+   */
+  getRunUsageStats(runId: string): Promise<RunUsageStats | null>;
+  /**
+   * Spawns a Letta Code CLI subprocess and streams a chat turn against
+   * the given conversation. Returns a `ChatTurnHandle` the caller
+   * drains + cancels + closes.
+   *
+   * Pre-flight checks (in order, all may throw):
+   * 1. **Subprocess throttle.** `SubprocessThrottle.acquire()` runs
+   *    first — throws `ServerOverloadedError` if RAM is under the
+   *    threshold or the hard-cap is reached. The chat route catches
+   *    this and returns HTTP 503 `server_overloaded`.
+   * 2. **Session initialization.** `session.initialize()` may throw if
+   *    the CLI subprocess fails to spawn or can't reach Letta. The
+   *    lease is released before the throw so the throttle counter
+   *    doesn't leak.
+   *
+   * The Letta Code session is configured for the ai-hub use case:
+   * - `permissionMode: "bypassPermissions"` — no interactive approvals
+   *   (we don't expose them to end-users in v1).
+   * - `skillSources: []` — no auto-loaded skills (challenge 2 in the
+   *   migration brief).
+   * - `systemInfoReminder: false` — no first-turn environment dump.
+   * - `memfsStartup: "skip"` — no git-backed memory filesystem.
+   * - `disallowedTools: ["AskUserQuestion", "EnterPlanMode",
+   *   "ExitPlanMode"]` — tools that require runtime user input.
+   *
+   * Toolset suppression is handled out-of-band by the
+   * `seedAgentToolsetNone` upsert into `~/.letta/settings.json` at
+   * agent-registration time.
+   *
+   * @param opts - see `StreamUserMessageOpts`.
+   * @returns a `ChatTurnHandle` the caller drains and closes.
+   * @throws `ServerOverloadedError` when the throttle rejects.
+   */
+  streamUserMessage(opts: StreamUserMessageOpts): Promise<ChatTurnHandle>;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Default implementation                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Dependency bundle for `createDefaultLettaClient`. */
+export interface CreateLettaClientDeps {
+  /** Drizzle handle. */
+  db: DrizzleDB;
+  /** Parsed encryption key for decrypting the Letta API key at rest. */
+  encryptionKey: Buffer;
+  /** Subprocess-spawn throttle (shared across the server instance). */
+  subprocessThrottle: SubprocessThrottle;
+  /**
+   * Env source — used as the fallback when the DB column is empty or
+   * whitespace. Production passes `process.env`; tests pass a synthesized
+   * record so the env precedence behaviour is exercisable without
+   * touching the real environment. Re-read on every `getSdk()` call so a
+   * server restart with a different `.env` reflects immediately.
+   */
+  envSource?: Record<string, string | undefined>;
+  /**
+   * Override the Letta Client SDK constructor — only used by tests.
+   * Production passes the SDK's `Letta` class (or omits to use the
+   * default).
+   */
+  sdkConstructor?: typeof LettaSdkDefault;
+  /**
+   * Override `resumeSession` from `@letta-ai/letta-code-sdk` — only
+   * used by tests, which inject a fake session factory.
+   */
+  resumeSessionFn?: typeof resumeSession;
+}
+
+/**
+ * Constructs the default `LettaClient` implementation.
+ *
+ * Reads `admin_setting.letta_base_url` + `letta_api_key_encrypted` on
+ * each Letta-Client call (no in-flight polling — fresh-on-demand) and
+ * memoizes the underlying SDK instance against `(apiKey, baseURL)` so
+ * super-admin connection-settings edits propagate without restart.
+ *
+ * Throws on the first Letta-Client call if `admin_setting` has no
+ * `letta_base_url` or no decryptable API key.
+ *
+ * @param deps - see `CreateLettaClientDeps`.
+ * @returns the project-shaped Letta client.
+ *
+ * @see SPECIFICATIONS.md §6.4
+ * @see SPECIFICATIONS.md §11 — `admin_setting` schema
+ */
+export function createDefaultLettaClient(
+  deps: CreateLettaClientDeps,
+): LettaClient {
+  const SdkCtor = deps.sdkConstructor ?? LettaSdkDefault;
+  const resume = deps.resumeSessionFn ?? resumeSession;
+  let cached:
+    | { apiKey: string; baseURL: string; sdk: LettaSdk }
+    | null = null;
+
+  const envSource = deps.envSource ?? (process.env as Record<string, string | undefined>);
+
+  /**
+   * Resolves the current `(apiKey, baseURL)` pair and returns a memoized
+   * Letta-Client SDK instance.
+   *
+   * **API key precedence** (per the operator-spec'd model):
+   * 1. If `admin_setting.letta_api_key_encrypted` decrypts to a non-empty,
+   *    non-whitespace string → use that (super-admin set it via the
+   *    admin panel; DB wins over env).
+   * 2. Otherwise → fall back to `env.LETTA_API_KEY` (whitespace-trimmed).
+   * 3. Otherwise → throw — neither source has a usable value.
+   *
+   * Evaluated on every call, so:
+   *  - A super-admin PATCH to /admin/settings takes effect immediately.
+   *  - Clearing the value via the admin panel (empty/whitespace) falls
+   *    back to env on the very next request.
+   *  - A new `.env` after a restart is reflected immediately when the DB
+   *    column is empty.
+   */
+  function resolveApiKey(): { apiKey: string; source: "db" | "env" } {
+    const settings = deps.db
+      .select()
+      .from(adminSetting)
+      .where(eq(adminSetting.id, 1))
+      .get();
+    if (settings?.lettaApiKeyEncrypted) {
+      const decrypted = decryptString(deps.encryptionKey, settings.lettaApiKeyEncrypted);
+      if (decrypted.trim().length > 0) {
+        return { apiKey: decrypted, source: "db" };
+      }
+    }
+    const envKey = envSource.LETTA_API_KEY;
+    if (envKey && envKey.trim().length > 0) {
+      return { apiKey: envKey, source: "env" };
+    }
+    throw new Error(
+      "No Letta API key configured. Set LETTA_API_KEY in .env, OR PATCH it via /admin/settings.",
+    );
+  }
+
+  function getSdk(): LettaSdk {
+    const settings = deps.db
+      .select()
+      .from(adminSetting)
+      .where(eq(adminSetting.id, 1))
+      .get();
+    if (!settings?.lettaBaseUrl) {
+      throw new Error(
+        "admin_setting.letta_base_url is empty — configure it via /admin/settings or LETTA_BASE_URL.",
+      );
+    }
+    const { apiKey } = resolveApiKey();
+    // The Letta Client SDK appends its own `/v1/...` paths, so a
+    // `letta_base_url` like `http://localhost:8283/v1` produces
+    // double-v1 calls. Strip a trailing `/v1` defensively.
+    const baseURL = settings.lettaBaseUrl.replace(/\/v1\/?$/i, "");
+    if (cached && cached.apiKey === apiKey && cached.baseURL === baseURL) {
+      return cached.sdk;
+    }
+    const sdk = new SdkCtor({ apiKey, baseURL });
+    cached = { apiKey, baseURL, sdk };
+    return sdk;
+  }
+
+  return {
+    async retrieveAgent(lettaAgentId) {
+      const sdk = getSdk();
+      try {
+        const state = await sdk.agents.retrieve(lettaAgentId);
+        return { id: state.id, name: state.name, model: state.model ?? "" };
+      } catch (err) {
+        if (err instanceof NotFoundError) return null;
+        throw err;
+      }
+    },
+
+    async createConversation(lettaAgentId) {
+      const sdk = getSdk();
+      const conv = await sdk.conversations.create({ agent_id: lettaAgentId });
+      return { id: conv.id };
+    },
+
+    async retrieveConversation(conversationId) {
+      const sdk = getSdk();
+      try {
+        const conv = await sdk.conversations.retrieve(conversationId);
+        return { id: conv.id, agentId: conv.agent_id };
+      } catch (err) {
+        if (err instanceof NotFoundError) return null;
+        throw err;
+      }
+    },
+
+    async forkConversation(sourceConversationId) {
+      const sdk = getSdk();
+      try {
+        // The Letta-Client SDK exposes `fork(conversationId, params?)`.
+        // We don't pass a body — defaults are fine for our use case
+        // (forked conversation is not hidden, no extra params needed).
+        const conv = await sdk.conversations.fork(sourceConversationId);
+        return { id: conv.id, agentId: conv.agent_id };
+      } catch (err) {
+        if (err instanceof NotFoundError) {
+          throw new ForkSourceNotFoundError(sourceConversationId);
+        }
+        throw err;
+      }
+    },
+
+    async listMessages(conversationId) {
+      const sdk = getSdk();
+      const out: LettaMessage[] = [];
+      const page = await sdk.conversations.messages.list(conversationId);
+      for await (const msg of page) {
+        out.push(msg);
+      }
+      return out;
+    },
+
+    async deleteMessage(lettaAgentId, messageId) {
+      const sdk = getSdk();
+      try {
+        // The typed `conversations.messages` resource is create/list-only;
+        // the message-delete capability lives on the agent-scoped REST route.
+        // Same raw-HTTP escape hatch `getRunUsageStats` uses for `sdk.get`.
+        await sdk.delete(
+          `/v1/agents/${encodeURIComponent(lettaAgentId)}/messages/${encodeURIComponent(messageId)}`,
+        );
+      } catch (err) {
+        // Already gone is fine — the goal state (message absent) is reached.
+        if (err instanceof NotFoundError) return;
+        throw err;
+      }
+    },
+
+    async deleteConversation(conversationId) {
+      const sdk = getSdk();
+      try {
+        await sdk.conversations.delete(conversationId);
+      } catch (err) {
+        if (err instanceof NotFoundError) return;
+        throw err;
+      }
+    },
+
+    async getRunUsageStats(runId) {
+      const sdk = getSdk();
+      // Two endpoints in parallel:
+      //   - `/v1/runs/{id}/messages` carries persisted assistant
+      //     messages — we need the LAST one's id to stamp the badge.
+      //     The `usage_statistics` SDK stream event is NOT persisted
+      //     here; we used to look for it but it's stream-only.
+      //   - `/v1/runs/{id}/steps` carries per-LLM-call usage with the
+      //     full cache breakdown (`cached_input_tokens`,
+      //     `cache_write_tokens`, `reasoning_tokens`). For multi-step
+      //     turns we sum across steps; for single-step turns we just
+      //     read the one row.
+      //
+      // Best-effort: any failure on either side returns null and the
+      // badge just doesn't render. Never blocks the chat turn.
+      let messagesRaw: unknown;
+      let stepsRaw: unknown;
+      try {
+        [messagesRaw, stepsRaw] = await Promise.all([
+          sdk.get(`/v1/runs/${runId}/messages`),
+          sdk.get(`/v1/runs/${runId}/steps`),
+        ]);
+      } catch {
+        return null;
+      }
+
+      // Pull the last assistant message id (anchor for the badge).
+      let lastAssistantMessageId: string | null = null;
+      if (Array.isArray(messagesRaw)) {
+        for (const item of messagesRaw) {
+          if (!item || typeof item !== "object") continue;
+          const m = item as Record<string, unknown>;
+          if (m["message_type"] === "assistant_message" && typeof m["id"] === "string") {
+            lastAssistantMessageId = m["id"];
+          }
+        }
+      }
+
+      // Sum tokens across steps. Missing fields stay null in the sum
+      // (the sum only goes non-null if at least one step reported it),
+      // so providers that don't expose cache_write keep it null at the
+      // top level rather than silently appearing as 0.
+      if (!Array.isArray(stepsRaw)) return null;
+      const sum = {
+        promptTokens: null as number | null,
+        completionTokens: null as number | null,
+        totalTokens: null as number | null,
+        cachedInputTokens: null as number | null,
+        cacheWriteTokens: null as number | null,
+        reasoningTokens: null as number | null,
+        contextTokens: null as number | null,
+      };
+      const addInto = (key: keyof typeof sum, v: unknown): void => {
+        if (typeof v !== "number") return;
+        sum[key] = (sum[key] ?? 0) + v;
+      };
+      let anyStep = false;
+      for (const item of stepsRaw) {
+        if (!item || typeof item !== "object") continue;
+        anyStep = true;
+        const s = item as Record<string, unknown>;
+        addInto("promptTokens", s["prompt_tokens"]);
+        addInto("completionTokens", s["completion_tokens"]);
+        addInto("totalTokens", s["total_tokens"]);
+        addInto("cachedInputTokens", s["cached_input_tokens"]);
+        addInto("cacheWriteTokens", s["cache_write_tokens"]);
+        addInto("reasoningTokens", s["reasoning_tokens"]);
+      }
+      if (!anyStep) return null;
+      return {
+        lastAssistantMessageId,
+        ...sum,
+      };
+    },
+
+    async streamUserMessage(opts) {
+      // Throttle gate first — synchronous, throws ServerOverloadedError.
+      // Caller's chat-route catch turns that into HTTP 503.
+      const lease: ThrottleLease = deps.subprocessThrottle.acquire();
+
+      // Sync `process.env.LETTA_API_KEY` to the currently-resolved value
+      // (DB > env precedence — see `resolveApiKey`). The Letta Code
+      // subprocess inherits `{...process.env}`, so whatever is in
+      // process.env at spawn time is what the CLI sends to Letta. Mutating
+      // it here on every spawn means a super-admin's PATCH to
+      // /admin/settings takes effect on the very next chat turn without
+      // a process restart — matches the same hot-reload behavior the
+      // direct-REST `getSdk()` path already had via SDK memoization on
+      // the `(apiKey, baseURL)` pair.
+      //
+      // If resolveApiKey throws (no usable value anywhere), we release
+      // the throttle lease before propagating — otherwise the slot would
+      // be leaked.
+      try {
+        const resolved = resolveApiKey();
+        process.env.LETTA_API_KEY = resolved.apiKey;
+      } catch (err) {
+        lease.release();
+        throw err;
+      }
+
+      // Letta Code's CLI reads `LETTA_BASE_URL` from env and appends
+      // `/v1/...` to it. If the operator set the env to
+      // `http://localhost:8283/v1` (matching the Letta Client SDK's
+      // expectation), the CLI produces double-v1 URLs that 404 — the
+      // CLI surfaces this as "Failed to connect to Letta server /
+      // credentials may be invalid", which is misleading. Strip the
+      // trailing `/v1` in process.env on every spawn (idempotent —
+      // already-stripped values pass through unchanged). Operators
+      // who use the bare-host form aren't affected. (Also done in
+      // `bootstrap.ts` at boot for the primary case; this is
+      // defense-in-depth.)
+      const rawBaseUrl = process.env.LETTA_BASE_URL;
+      if (rawBaseUrl) {
+        const stripped = rawBaseUrl.replace(/\/v1\/?$/i, "");
+        if (stripped !== rawBaseUrl) {
+          process.env.LETTA_BASE_URL = stripped;
+        }
+      }
+
+      // Re-seed `~/.letta/settings.json` with `{toolset: "none"}` for
+      // this agent on every spawn. Necessary because concurrent CLI
+      // subprocesses race on settings-file writes (each maintains its
+      // own in-memory snapshot, writes back on exit, last-writer-wins)
+      // and the agent-registration-time seed can be wiped between
+      // spawns. Idempotent — when the entry already matches, this is
+      // a no-op (doesn't touch the file's mtime). Best-effort: a
+      // write failure logs but doesn't block the chat turn (the shim
+      // is the primary mechanism; the settings file is defense-in-
+      // depth + TUI-compatibility).
+      try {
+        seedAgentToolsetNone({
+          agentId: opts.lettaAgentId,
+          lettaBaseUrl: process.env.LETTA_BASE_URL,
+        });
+      } catch {
+        // intentionally ignored — see above
+      }
+
+      // Point the SDK at our CLI shim. The shim injects `--tools ""`
+      // into argv before invoking the real Letta Code CLI, which
+      // mimics the TUI `/toolset none` action — both end up with an
+      // empty `toolRegistry` so the LLM sees only the agent's
+      // ADE-attached tools (no Read/Write/Bash/etc. from Letta
+      // Code's bundled presets). See `lettaCliShim.mjs` for the
+      // full rationale + traceability to the Letta Code source.
+      //
+      // This is set once per spawn (cheap — just a process.env write).
+      // We use the migration's source path so the shim is in the
+      // same repo and ships with ai-hub-server.
+      if (process.env.LETTA_CLI_PATH === undefined) {
+        const { dirname, join } = await import("node:path");
+        const { fileURLToPath } = await import("node:url");
+        const here = dirname(fileURLToPath(import.meta.url));
+        process.env.LETTA_CLI_PATH = join(here, "lettaCliShim.mjs");
+      }
+
+      // We send the raw user message verbatim; the admin's system prompt
+      // flows through Letta's normal channel (the agent's persisted
+      // `system` field).
+      const userContent: string = opts.userMessage;
+
+      // Step-12.5 — disallow-list composition.
+      //
+      // When the parent session has a sandbox folder (opts.cwd set), the
+      // filesystem tools are RE-ENABLED so the agent can use the seeded
+      // files. Without a sandbox, those tools stay disallowed (today's
+      // stateless agent shape; regression-locked by a snapshot test).
+      //
+      // The always-disallowed group (memory / sub-agent / interactive /
+      // web) stays disallowed regardless — the v1 no-memory stance is
+      // unchanged. See docs/server/session-sandboxes.md.
+      const disallowedTools: string[] =
+        opts.cwd === undefined
+          ? [...ALWAYS_DISALLOWED_TOOLS, ...FILESYSTEM_TOOLS]
+          : [...ALWAYS_DISALLOWED_TOOLS];
+
+      let session: Session | null = null;
+      try {
+        session = resume(opts.conversationId, {
+          permissionMode: "bypassPermissions",
+          skillSources: [],
+          systemInfoReminder: false,
+          memfsStartup: "skip",
+          // `disallowedTools` mirrors the effect of TUI `/toolset none` —
+          // the persisted-setting approach (`~/.letta/settings.json`) is
+          // only consulted by Letta Code's interactive code path, NOT
+          // the headless `--input-format stream-json` mode the SDK uses.
+          // And `--toolset none` is rejected as a CLI arg in headless
+          // mode (only auto/codex/default/gemini accepted there).
+          //
+          // Adding tools to this list as Letta Code adds them upstream
+          // is maintenance debt — grep `ALWAYS_DISALLOWED_TOOLS` /
+          // `FILESYSTEM_TOOLS` to find the constants. The longer-term
+          // fix is upstream: either accept `--toolset none` in headless
+          // mode or expose a `--no-tools` flag. Filed against
+          // letta-ai/letta-code (TBD).
+          disallowedTools,
+          // Step-12.5 — per-session sandbox folder; see opts.cwd JSDoc.
+          ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        });
+        await session.initialize();
+        await session.send(userContent);
+      } catch (err) {
+        // Spawn / init / send failure — release lease + tear down the
+        // subprocess if we got that far, then re-throw for the caller.
+        if (session) {
+          try {
+            session.close();
+          } catch {
+            // best-effort
+          }
+        }
+        lease.release();
+        throw err;
+      }
+
+      const activeSession = session;
+      let closed = false;
+      return {
+        events: activeSession.stream(),
+        async abort() {
+          try {
+            await activeSession.abort();
+          } catch {
+            // The CLI may already be tearing down — swallow to keep
+            // the cancel route idempotent. `close()` still runs.
+          }
+        },
+        close() {
+          if (closed) return;
+          closed = true;
+          try {
+            activeSession.close();
+          } catch {
+            // best-effort
+          }
+          lease.release();
+        },
+      };
+    },
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Re-exports                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+export type { LettaMessage, LettaSdk } from "./types.js";