@data-club/ai-hub-server 0.0.9 → 0.0.11

package/src/letta/client.ts

@@ -1,71 +1,62 @@
 /**
- * Hybrid Letta access layer.
+ * Letta access layer — server-less local backend.
  *
- * **Two SDKs, two roles:**
+ * AI Hub drives **Letta Code's local backend** through
+ * `@data-club/letta-runtime`: agent/conversation state lives on the local
+ * filesystem (`AI_HUB_LETTA_STORE_DIR`), chat turns run in an SDK-spawned
+ * Letta Code CLI subprocess, and inference is client-side (Letta Code's Pi
+ * provider layer calling Anthropic / AWS Bedrock directly). There is no
+ * Letta server and no `@letta-ai/letta-client` anywhere in this path — the
+ * server-backed implementation was removed in the local-backend migration
+ * (see docs/investigations/2026-07-01-letta-code-local-backend-migration.md).
  *
- * - **`@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.
+ * **MCP tools.** Letta Code is not an MCP client; with no Letta server, AI
+ * Hub is the MCP host. On the first chat turn this module connects to the
+ * servers configured in `AI_HUB_MCP_SERVERS` (`name=url,name2=url2`,
+ * Streamable HTTP) and injects their tools into every session via the
+ * runtime's `tools` option; tool executions round-trip through the SDK's
+ * `execute_external_tool` control channel in this process.
  *
- * **The hard rule from §6.4 is preserved** — every Letta interaction
- * goes through one of these two SDKs; no raw HTTP, no parallel fetch.
+ * **Tool suppression.** Letta Code's bundled tools are hidden from the
+ * model via `disallowedTools` (the headless-mode equivalent of the TUI's
+ * `/toolset none`). The old `--tools ""` CLI shim is gone — emptying the
+ * CLI's tool registry also strips SDK-injected MCP tools (verified
+ * empirically), so the disallow list is the only suppression mechanism.
  *
- * 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
+ * This module composes AI-Hub policy (subprocess throttle, tool
+ * disallow-lists, sandbox cwd) around the runtime; everything Letta-shaped
+ * lives in `@data-club/letta-runtime`.
  */
 
-import { eq } from "drizzle-orm";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
 
-import LettaSdkDefault, {
-  NotFoundError,
-} from "@letta-ai/letta-client";
 import {
-  resumeSession,
+  ConversationNotFoundError,
+  connectMcpServers,
+  LocalLettaRuntime,
+  parseMcpServersConfig,
+  type AnyAgentTool,
+  type LettaMessageRecord,
+  type LettaRuntime,
   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";
+  type TurnHandle,
+} from "@data-club/letta-runtime";
 
-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).
+ * Thrown when `forkConversation(sourceId)` resolves to "no such
+ * conversation". 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 earlier).
  *
  * @see docs/server/session-sandboxes.md
  */
@@ -78,35 +69,32 @@ export class ForkSourceNotFoundError extends Error {
 
 /**
  * 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.
+ * whether a per-session sandbox is configured:
  *
- * The filesystem tools (Read / Write / Edit / etc.) live in
- * `FILESYSTEM_TOOLS` below and are disallowed ONLY when no sandbox is
- * configured for the session.
+ * - Memory tools — the v1 no-memory stance (memfs is off store-wide via the
+ *   runtime, this is defense-in-depth).
+ * - Sub-agent / task management — not exposed to ai-hub end users.
+ * - Interactive tools — hang the headless code path.
+ * - Web tools — operator-curated agents reach the web through MCP tools.
  *
- * @see docs/server/session-sandboxes.md — the disallow-list split (Step 12.5)
+ * Grep-anchor: ALWAYS_DISALLOWED_TOOLS. Extend when Letta Code adds new
+ * bundled tools upstream (check the headless init message's `tools` list
+ * after a fork sync).
  */
 const ALWAYS_DISALLOWED_TOOLS: ReadonlyArray<string> = [
   // Sub-agent + task management
   "Task",
   "TaskOutput",
   "TaskStop",
+  "TaskCreate",
+  "TaskGet",
+  "TaskList",
+  "TaskUpdate",
   "TodoWrite",
+  "Agent",
   // 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 (kept forbidden even with a sandbox)
   "memory",
   "memory_apply_patch",
   "memory_insert",
@@ -116,8 +104,8 @@ const ALWAYS_DISALLOWED_TOOLS: ReadonlyArray<string> = [
   "AskUserQuestion",
   "EnterPlanMode",
   "ExitPlanMode",
-  // Web tools (Letta Code adds these in the Claude toolset; harmless to
-  // disallow here if absent; future-proofs against upstream additions)
+  "EnterWorktree",
+  // Web tools
   "WebFetch",
   "WebSearch",
 ];
@@ -129,7 +117,6 @@ const ALWAYS_DISALLOWED_TOOLS: ReadonlyArray<string> = [
  * 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",
@@ -148,64 +135,26 @@ const FILESYSTEM_TOOLS: ReadonlyArray<string> = [
 /*  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).
+   * The Letta agent id the session is against. Not needed to spawn a turn
+   * on the local backend (the conversation record carries its agent), but
+   * kept on the opts shape for logging and interface stability.
    */
   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.
+   * Plain-text user message body. Sent verbatim. The admin's system prompt
+   * is delivered through the agent record's persisted `system` field.
    */
   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.
+   * subprocess (per-session sandbox folder). When set, the filesystem
+   * tools are re-enabled so the agent can use the seeded files; when
+   * `undefined`, they stay disallowed.
    *
    * @see docs/server/session-sandboxes.md
    */
@@ -213,360 +162,176 @@ export interface StreamUserMessageOpts {
 }
 
 /**
- * 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:
+ * Handle returned by `streamUserMessage`. Wraps the runtime's turn handle +
+ * the subprocess-throttle lease so the caller owns one resource bundle to
+ * drain, cancel, and clean up.
  *
- * 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.
+ * Lifecycle: iterate `events`; `abort()` to interrupt; ALWAYS `close()` in
+ * a `finally` (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.
-   */
+  /** Sends an `interrupt` control to the spawned CLI. Best-effort. */
   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.
-   */
+  /** Tears down the subprocess + releases the throttle slot. Idempotent. */
   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
+ * Project-shaped Letta client. The handlers depend on this interface, not
+ * on the underlying runtime, so tests can plug a mock implementation in via
+ * `getLettaClient` on the server context.
  */
 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.
+   * Retrieves a Letta agent by id from the local store. 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.
    */
   retrieveAgent(lettaAgentId: string): Promise<{
     id: string;
     name: string;
-    /** Provider-prefixed model handle (e.g. `"anthropic/claude-opus-4-7"`). */
+    /** Provider-prefixed model handle (e.g. `"bedrock/eu.anthropic.claude-opus-4-6-v1"`). */
     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.
-   */
+  /** Creates a fresh conversation against the given agent. */
   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.
+   * Retrieves a conversation by id (admin fork-source validation). Returns
+   * `null` on miss.
    */
   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`.
+   * Clones an existing conversation (transcript included) into a new one
+   * on the same agent. Powers session creation from a rotating message's
+   * prepared conversation.
    *
-   * @param sourceConversationId - the Letta conversation id to fork.
-   * @returns the new conversation's `{ id, agentId }`.
-   * @throws ForkSourceNotFoundError on Letta 404.
+   * @throws ForkSourceNotFoundError when the source no longer exists.
    */
   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.
-   */
+  /** Lists every message in a conversation, oldest first. */
   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`).
+   * NO-OP on the local backend. Message deletion was a Letta-server REST
+   * capability; per the migration decision, rotating messages now keep
+   * their initial prompt message instead of deleting it. The method stays
+   * on the interface so the rotation runner's flow is unchanged.
    */
   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.
+   * NO-OP on the local backend. Old prepared conversations are left in the
+   * local store (orphans are harmless files); a cleanup pass can come later.
    */
   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.
+   * Spawns a Letta Code CLI subprocess and streams a chat turn.
    *
-   * @param opts - see `StreamUserMessageOpts`.
-   * @returns a `ChatTurnHandle` the caller drains and closes.
-   * @throws `ServerOverloadedError` when the throttle rejects.
+   * Pre-flight (in order, both may throw):
+   * 1. `SubprocessThrottle.acquire()` — `ServerOverloadedError` → HTTP 503.
+   * 2. MCP bridge connect (first turn only, cached after) — a configured
+   *    MCP server that can't be reached fails the turn rather than
+   *    presenting a differently-capable agent.
    */
   streamUserMessage(opts: StreamUserMessageOpts): Promise<ChatTurnHandle>;
 }
 
+/** One Letta-format message as consumed by history renderers. */
+export type LettaMessage = LettaMessageRecord;
+
 /* ────────────────────────────────────────────────────────────────────────── */
 /*  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.
+   * Env source. Reads:
+   * - `AI_HUB_LETTA_STORE_DIR` — local-backend store (default
+   *   `~/.letta/lc-local-backend`; on deployments point this at the
+   *   persistent encrypted volume, shared with operator SSH sessions).
+   * - `AI_HUB_LETTA_CLI_PATH` — Letta Code CLI entry override (default:
+   *   the installed `@data-club/letta-code` package).
+   * - `AI_HUB_MCP_SERVERS` — MCP servers to host (`name=url,...`); empty
+   *   or unset → no MCP tools.
    */
   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;
+  /** Override the runtime — only used by tests. */
+  runtime?: LettaRuntime;
+}
+
+/** Resolves the Letta Code CLI entry (`letta.js`) from the installed fork. */
+function resolveDefaultCliPath(): string {
+  const require = createRequire(import.meta.url);
+  return require.resolve("@data-club/letta-code");
 }
 
 /**
- * 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
+ * Constructs the default `LettaClient` implementation over the local
+ * backend. See the module doc for the architecture.
  */
 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>);
+  const envSource =
+    deps.envSource ?? (process.env as Record<string, string | undefined>);
+
+  const runtime: LettaRuntime =
+    deps.runtime ??
+    new LocalLettaRuntime({
+      cliPath: envSource.AI_HUB_LETTA_CLI_PATH ?? resolveDefaultCliPath(),
+      storeDir:
+        envSource.AI_HUB_LETTA_STORE_DIR ??
+        join(homedir(), ".letta", "lc-local-backend"),
+      memfs: false,
+    });
 
   /**
-   * 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.
+   * MCP tools, connected lazily on the first chat turn and cached for the
+   * process lifetime. A failed connect is NOT cached — the next turn
+   * retries, so a briefly-down MCP server doesn't wedge the deployment.
    */
-  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" };
+  let mcpToolsPromise: Promise<AnyAgentTool[]> | null = null;
+  function getMcpTools(): Promise<AnyAgentTool[]> {
+    if (mcpToolsPromise === null) {
+      const servers = parseMcpServersConfig(envSource.AI_HUB_MCP_SERVERS);
+      mcpToolsPromise =
+        servers.length === 0
+          ? Promise.resolve([])
+          : connectMcpServers(servers).then((bridge) => bridge.tools);
+      mcpToolsPromise.catch(() => {
+        mcpToolsPromise = null;
+      });
     }
-    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 mcpToolsPromise;
   }
 
   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;
-      }
+      return runtime.retrieveAgent(lettaAgentId);
     },
 
     async createConversation(lettaAgentId) {
-      const sdk = getSdk();
-      const conv = await sdk.conversations.create({ agent_id: lettaAgentId });
-      return { id: conv.id };
+      return runtime.createConversation(lettaAgentId);
     },
 
     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;
-      }
+      return runtime.retrieveConversation(conversationId);
     },
 
     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 };
+        return await runtime.forkConversation(sourceConversationId);
       } catch (err) {
-        if (err instanceof NotFoundError) {
+        if (err instanceof ConversationNotFoundError) {
           throw new ForkSourceNotFoundError(sourceConversationId);
         }
         throw err;
@@ -574,114 +339,15 @@ export function createDefaultLettaClient(
     },
 
     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;
+      return runtime.listMessages(conversationId);
     },
 
-    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 deleteMessage(_lettaAgentId, _messageId) {
+      // Intentional no-op — see the interface doc.
     },
 
-    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 deleteConversation(_conversationId) {
+      // Intentional no-op — see the interface doc.
     },
 
     async streamUserMessage(opts) {
@@ -689,172 +355,42 @@ export function createDefaultLettaClient(
       // 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.
+      // Step-12.5 — disallow-list composition. With a sandbox folder
+      // (opts.cwd set) the filesystem tools are re-enabled so the agent can
+      // use the seeded files; without one they stay disallowed.
       const disallowedTools: string[] =
         opts.cwd === undefined
           ? [...ALWAYS_DISALLOWED_TOOLS, ...FILESYSTEM_TOOLS]
           : [...ALWAYS_DISALLOWED_TOOLS];
 
-      let session: Session | null = null;
+      let handle: TurnHandle;
       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).
+        const tools = await getMcpTools();
+        handle = await runtime.streamTurn({
+          conversationId: opts.conversationId,
+          userMessage: opts.userMessage,
           disallowedTools,
-          // Step-12.5 — per-session sandbox folder; see opts.cwd JSDoc.
+          ...(tools.length > 0 ? { tools } : {}),
           ...(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(),
+        events: handle.events,
         async abort() {
-          try {
-            await activeSession.abort();
-          } catch {
-            // The CLI may already be tearing down — swallow to keep
-            // the cancel route idempotent. `close()` still runs.
-          }
+          await handle.abort();
         },
         close() {
           if (closed) return;
           closed = true;
-          try {
-            activeSession.close();
-          } catch {
-            // best-effort
-          }
+          handle.close();
           lease.release();
         },
       };
     },
   };
 }
-
-/* ────────────────────────────────────────────────────────────────────────── */
-/*  Re-exports                                                                */
-/* ────────────────────────────────────────────────────────────────────────── */
-
-export type { LettaMessage, LettaSdk } from "./types.js";