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

package/src/routes/admin/settings.ts

@@ -3,13 +3,10 @@
  *
  * Five endpoints:
  *
- * - `GET    /admin/settings` — Letta connection (api key **masked**), theme,
- *   metrics + signing-key rotation timestamps. Encrypted Letta API key
- *   surfaces only as `letta_api_key_masked` (`••••••••<last4>`); plaintext
- *   never leaves the server outside the `Reveal once` flow (Step 12).
- * - `PATCH  /admin/settings` — body `{ letta_base_url?, letta_ade_url?, letta_api_key?, theme?: { default?, switcher_enabled? } }`.
- *   API key, when supplied, is encrypted under `AI_HUB_ENCRYPTION_KEY`. Theme
- *   fields live as **separate columns**, not in `feature_toggles`.
+ * - `GET    /admin/settings` — theme / language / agents settings plus
+ *   metrics + signing-key rotation timestamps.
+ * - `PATCH  /admin/settings` — body `{ theme?: { default?, switcher_enabled? }, language?, agents? }`.
+ *   Theme fields live as **separate columns**, not in `feature_toggles`.
  * - `GET    /admin/settings/feature-toggles` — flat JSON blob from §8.4.
  * - `PATCH  /admin/settings/feature-toggles` — merge-patch the same blob.
  *   Unknown keys are accepted (forward-compat for future toggles).
@@ -36,7 +33,6 @@ import { randomBytes } from "node:crypto";
 import { eq } from "drizzle-orm";
 import { z } from "zod";
 
-import { encryptString } from "../../auth/encryption.js";
 import { protectedRoute } from "../../auth/middleware.js";
 import { adminSetting } from "../../db/schema.js";
 import type { AdminSettingRow } from "../../db/schema.js";
@@ -56,60 +52,6 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
-/**
- * Computes a privacy-preserving display of the encrypted Letta API key.
- *
- * Per [08-admin-settings.md], the UI shows `••••••••` while the value is in
- * the field — operators reveal-once if they need to copy. The server's
- * `GET /admin/settings` never returns plaintext.
- *
- * @param row - the admin_setting row.
- * @returns a masked string, or `null` when no key is stored.
- */
-function maskLettaApiKey(row: AdminSettingRow): string | null {
-  if (!row.lettaApiKeyEncrypted) return null;
-  // We can't decrypt without the key, and decrypting just to show "<last 4>"
-  // would defeat the purpose of encrypting at rest. Use a constant placeholder
-  // so the UI knows a key is configured without revealing length / contents.
-  return "••••••••";
-}
-
-/** Possible sources for the effective Letta API key at runtime. */
-type LettaApiKeySource = "db" | "env" | "none";
-
-/**
- * Determines the *effective* source of the Letta API key at this moment.
- * Mirrors `letta/client.ts:resolveApiKey` (DB → env → throw) so the admin
- * UI can show the truth about which source the runtime will use, not just
- * what's stored in the DB.
- *
- * Returning the SOURCE — not the value — keeps plaintext off the wire.
- *
- * @param row - the admin_setting row (may be missing).
- * @param envSource - env-var record from the server context. Lets tests
- *   exercise the source-resolution without touching the real `process.env`.
- * @returns `"db"` when DB column has a non-empty value (the runtime will
- *   use it); `"env"` when DB is empty AND `LETTA_API_KEY` in `envSource`
- *   is set and non-empty; `"none"` otherwise.
- */
-function resolveApiKeySource(
-  row: AdminSettingRow | null,
-  envSource: Record<string, string | undefined>,
-): LettaApiKeySource {
-  // We deliberately can't tell here whether the DB-encrypted bytes decrypt
-  // to a non-whitespace string without doing the decrypt — but the rule is
-  // "non-empty bytes ⇒ candidate." The runtime resolver does the actual
-  // whitespace check; the UI source is just "is there a DB value worth
-  // showing?" The mismatch (DB has whitespace-only after decrypt) is rare
-  // enough that we don't pay the cost of decrypting here just to detect
-  // it; `letta_api_key_set` aligned with `lettaApiKeyEncrypted IS NOT NULL`
-  // matches the existing PATCH semantics (we never write whitespace).
-  if (row?.lettaApiKeyEncrypted) return "db";
-  const envKey = envSource.LETTA_API_KEY;
-  if (envKey && envKey.trim().length > 0) return "env";
-  return "none";
-}
-
 /**
  * Reads the singleton admin-settings row. Throws if the row hasn't been
  * seeded — should not happen after first-boot.
@@ -130,27 +72,8 @@ function readSettings(ctx: {
  * @param row - the admin_setting row.
  * @returns the JSON-safe response shape.
  */
-function settingsView(
-  row: AdminSettingRow,
-  envSource: Record<string, string | undefined>,
-): Record<string, unknown> {
-  const source = resolveApiKeySource(row, envSource);
+function settingsView(row: AdminSettingRow): Record<string, unknown> {
   return {
-    letta_base_url: row.lettaBaseUrl ?? null,
-    letta_ade_url: row.lettaAdeUrl ?? null,
-    letta_api_key_masked: maskLettaApiKey(row),
-    // True when EITHER the DB column is populated OR env.LETTA_API_KEY is
-    // set — matches the runtime resolver's "is the chat path going to
-    // work?" answer. The admin UI uses this to decide whether to render a
-    // "configured" badge vs. a "missing" warning, regardless of which
-    // source supplies the value.
-    letta_api_key_set: source !== "none",
-    // Source the runtime is *currently* using (per resolveApiKey precedence
-    // in letta/client.ts). Drives the admin UI's source-indicator text —
-    // "(from env)" vs "(from admin panel)" vs "(not configured)" — so
-    // operators don't get confused when the DB row is empty but chat
-    // still works (env fallback) or vice versa.
-    letta_api_key_source: source,
     theme: {
       default: row.themeDefault,
       switcher_enabled: row.themeSwitcherEnabled,
@@ -179,11 +102,6 @@ function settingsView(
 /**
  * `GET /admin/settings` — super_admin-only deployment configuration.
  *
- * Encrypted Letta API key surfaces only as the masked placeholder
- * (`letta_api_key_masked: "••••••••"`) + the boolean `letta_api_key_set`;
- * plaintext never leaves the server through this endpoint. Step 12 wires the
- * `Reveal once` flow as a separate UI affordance.
- *
  * @see SPECIFICATIONS.md §6.3.4
  * @see ui-sketches/08-admin-settings.md
  */
@@ -192,7 +110,7 @@ export const handleGetSettings: RouteHandler = protectedRoute(
   async (_req, ctx) => {
     const row = readSettings(ctx);
     if (!row) return internalError("Admin settings row is missing — server misconfigured.");
-    return jsonResponse(200, settingsView(row, ctx.envSource));
+    return jsonResponse(200, settingsView(row));
   },
 );
 
@@ -203,16 +121,6 @@ export const handleGetSettings: RouteHandler = protectedRoute(
 /** Body for `PATCH /admin/settings`. Every field optional; empty body is a no-op. */
 const patchSettingsSchema = z
   .object({
-    letta_base_url: z.string().url().nullable().optional(),
-    letta_ade_url: z.string().url().nullable().optional(),
-    // The API key accepts:
-    //   - a non-empty string → encrypt + store; runtime will use this DB
-    //     value over env on the next request.
-    //   - an empty/whitespace string → clear the DB column to NULL; the
-    //     runtime then falls back to env.LETTA_API_KEY (the operator-spec'd
-    //     "if admin panel is empty, use env" precedence).
-    //   - omitted → no change.
-    letta_api_key: z.string().max(2048).optional(),
     theme: z
       .object({
         default: z.enum(["light", "dark"]).optional(),
@@ -241,9 +149,8 @@ const patchSettingsSchema = z
 /**
  * `PATCH /admin/settings` — partial update of deployment configuration.
  *
- * The Letta API key, when supplied, is encrypted under
- * `AI_HUB_ENCRYPTION_KEY` (env-only) before write. Theme fields live as
- * separate columns (`theme_default`, `theme_switcher_enabled`) per §8.4.
+ * Theme fields live as separate columns (`theme_default`,
+ * `theme_switcher_enabled`) per §8.4.
  *
  * @see SPECIFICATIONS.md §6.3.4
  * @see SPECIFICATIONS.md §8.4 — theme settings are explicit columns
@@ -264,17 +171,6 @@ export const handlePatchSettings: RouteHandler = protectedRoute(
     const body = parsed.data;
 
     const update: Partial<typeof adminSetting.$inferInsert> = { updatedAt: nowIso() };
-    if (body.letta_base_url !== undefined) update.lettaBaseUrl = body.letta_base_url;
-    if (body.letta_ade_url !== undefined) update.lettaAdeUrl = body.letta_ade_url;
-    if (body.letta_api_key !== undefined) {
-      // Empty / whitespace-only string clears the DB column to NULL. The
-      // runtime then falls back to env.LETTA_API_KEY (see
-      // letta/client.ts:resolveApiKey). Non-empty values are encrypted +
-      // stored as the operator's override of env.
-      const trimmed = body.letta_api_key.trim();
-      update.lettaApiKeyEncrypted =
-        trimmed.length === 0 ? null : encryptString(ctx.encryptionKey, body.letta_api_key);
-    }
     if (body.theme?.default !== undefined) update.themeDefault = body.theme.default;
     if (body.theme?.switcher_enabled !== undefined)
       update.themeSwitcherEnabled = body.theme.switcher_enabled;
@@ -305,7 +201,7 @@ export const handlePatchSettings: RouteHandler = protectedRoute(
 
     const fresh = readSettings(ctx);
     if (!fresh) return internalError();
-    return jsonResponse(200, settingsView(fresh, ctx.envSource));
+    return jsonResponse(200, settingsView(fresh));
   },
 );
 

package/src/routes/auth.ts

@@ -384,10 +384,6 @@ export const handleLogout: RouteHandler = protectedRoute({}, async () => {
 /**
  * `GET /auth/me` — returns the `{ user, deployment }` envelope.
  *
- * `deployment.letta_ade_url` is included only for callers with role >=
- * `power_user` (handled inside `buildDeploymentView`); `user`-role callers
- * don't even see the field exists — by design (§6.3.4).
- *
  * The resolved theme is computed client-side from
  * `user.theme_preference + deployment.{theme_default, theme_switcher_enabled}`
  * per §7.6 — the server does not pre-compute it.
@@ -493,7 +489,7 @@ export const handleMePreferences: RouteHandler = protectedRoute(
       .get();
     return jsonResponse(200, {
       user: buildUserView(freshRow),
-      deployment: buildDeploymentView(settings ?? null, freshRow.role),
+      deployment: buildDeploymentView(settings ?? null),
     });
   },
 );

package/src/routes/sessions.ts

@@ -35,7 +35,6 @@ import { protectedRoute } from "../auth/middleware.js";
 import {
   agent,
   messageOverride,
-  messageUsage,
   rotatingMessage,
   session,
   turn,
@@ -893,45 +892,21 @@ function projectAndRespond(
       }
     }
 
-    // Per-assistant-message usage (cache hits/writes + token counts).
-    // Stamped by the runner on the last assistant message of each
-    // turn (see turnRunner.ts step 5.5). Renders as the cache badge
-    // on the chat UI's assistant bubbles.
-    const usageRows = ctx.db
-      .select()
-      .from(messageUsage)
-      .where(eq(messageUsage.sessionId, row.id))
-      .all();
-    const usageByMessageId = new Map<string, AIHubMessage["usage"]>();
-    for (const u of usageRows) {
-      usageByMessageId.set(u.lettaMessageId, {
-        input: u.promptTokens,
-        output: u.completionTokens,
-        cache_read: u.cachedInputTokens,
-        cache_write: u.cacheWriteTokens,
-        reasoning: u.reasoningTokens,
-        context: u.contextTokens,
-        total: u.totalTokens,
-      });
-    }
-
     const projected = sorted.map((msg): AIHubMessage => {
       const pos = positionByLettaId.get(msg.id);
-      const usage = usageByMessageId.get(msg.id);
-      const withUsage = usage !== undefined ? { ...msg, usage } : msg;
       if (pos !== undefined) {
         const explicit = overrideByPosition.get(pos);
         if (explicit !== undefined) {
-          return { ...withUsage, content: explicit };
+          return { ...msg, content: explicit };
         }
       }
       if (msg.role === "system") {
         const stripped = stripMemoryMetadata(msg.content);
         if (stripped !== msg.content) {
-          return { ...withUsage, content: stripped };
+          return { ...msg, content: stripped };
         }
       }
-      return withUsage;
+      return msg;
     });
 
     const finalMessages = applyRotationDisplayFilter
@@ -1882,21 +1857,21 @@ function toWireMessage(msg: LettaMessage): AIHubMessage | null {
         id: msg.id,
         role: "user",
         content: extractTextContent(msg.content),
-        created_at: msg.date,
+        created_at: msg.date ?? "",
       };
     case "assistant_message":
       return {
         id: msg.id,
         role: "assistant",
         content: extractTextContent(msg.content),
-        created_at: msg.date,
+        created_at: msg.date ?? "",
       };
     case "system_message":
       return {
         id: msg.id,
         role: "system",
         content: extractTextContent(msg.content),
-        created_at: msg.date,
+        created_at: msg.date ?? "",
       };
     default:
       // reasoning_message / hidden_reasoning_message / tool_call_message /
@@ -1921,8 +1896,12 @@ function toWireMessage(msg: LettaMessage): AIHubMessage | null {
  * consistent regardless of where reminders end up.
  */
 function extractTextContent(
-  content: string | Array<{ type?: string; text?: string }>,
+  content:
+    | string
+    | ReadonlyArray<{ type?: string; text?: string }>
+    | undefined,
 ): string {
+  if (content === undefined) return "";
   if (typeof content === "string") return stripSystemReminders(content);
   if (!Array.isArray(content)) return "";
   let out = "";

package/src/state/rotationRunner.ts

@@ -24,11 +24,18 @@
  * @see docs/server/rotating-messages.md
  */
 
+import { join } from "node:path";
+
 import { eq } from "drizzle-orm";
 
 import type { DrizzleDB } from "../db/connection.js";
 import { rotatingMessage, type RotatingMessageRow } from "../db/schema.js";
 import type { LettaClient } from "../letta/client.js";
+import {
+  materializeSandbox,
+  purgeSandbox,
+  resolveSeedDir,
+} from "../letta/sandbox.js";
 import type { Logger } from "../observability/logger.js";
 
 import { CronParseError, cronNextRun, parseCron } from "./cron.js";
@@ -157,6 +164,12 @@ export interface RotationRunnerDeps {
   lettaClient: LettaClient;
   /** Logger for this rotation. */
   logger: Logger;
+  /**
+   * Base files dir (`resolveFilesDir`) — parent of `seeds/` + `sandboxes/`.
+   * Needed to materialize the rotation sandbox when the row has a
+   * `sandbox_seed_name`.
+   */
+  filesDir: string;
   /** Override "now" for deterministic tests. Defaults to `new Date()`. */
   now?: () => Date;
 }
@@ -189,10 +202,31 @@ export async function runRotation(
 
   let createdConversationId: string | null = null;
   try {
+    // Rotation sandbox — when the row names a seed, materialize a fresh
+    // working directory for THIS rotation run so the agent's filesystem/Bash
+    // tools are enabled (streamUserMessage widens the toolset when `cwd` is
+    // set) and the prompt can query the seeded data. The dir is rebuilt from
+    // the seed on every rotation (purge + materialize) and keyed by the
+    // rotating-message id (`rmsg-<uuid>` — safe path chars), NOT by
+    // conversation, so failed runs never accumulate orphan dirs.
+    let sandboxDir: string | undefined;
+    if (row.sandboxSeedName) {
+      const seedDir = resolveSeedDir(deps.filesDir, row.sandboxSeedName);
+      sandboxDir = join(deps.filesDir, "sandboxes", row.id);
+      await purgeSandbox(sandboxDir);
+      await materializeSandbox(seedDir, sandboxDir);
+    }
+
     const conv = await deps.lettaClient.createConversation(row.lettaAgentId);
     createdConversationId = conv.id;
 
-    await sendPromptAndDrain(deps.lettaClient, conv.id, row.lettaAgentId, row.prompt);
+    await sendPromptAndDrain(
+      deps.lettaClient,
+      conv.id,
+      row.lettaAgentId,
+      row.prompt,
+      sandboxDir,
+    );
 
     // Delete the prompt's user message so the conversation opens with the
     // agent's reply. listMessages is oldest-first; the first user_message is
@@ -299,11 +333,13 @@ async function sendPromptAndDrain(
   conversationId: string,
   lettaAgentId: string,
   prompt: string,
+  cwd?: string,
 ): Promise<void> {
   const handle = await client.streamUserMessage({
     conversationId,
     lettaAgentId,
     userMessage: prompt,
+    ...(cwd !== undefined ? { cwd } : {}),
   });
   let sawResult = false;
   let success = false;

package/src/state/rotationScheduler.ts

@@ -38,6 +38,8 @@ export interface RotationSchedulerDeps {
   db: DrizzleDB;
   lettaClient: LettaClient;
   logger: Logger;
+  /** Base files dir — forwarded to `runRotation` for rotation sandboxes. */
+  filesDir: string;
 }
 
 /** Handle for stopping a running scheduler. */

package/src/state/turnRunner.ts

@@ -45,7 +45,7 @@ import type {
   TurnStatus,
 } from "@data-club/ai-hub";
 
-import { messageUsage, turn, turnEvent } from "../db/schema.js";
+import { turn, turnEvent } from "../db/schema.js";
 import type { DrizzleDB } from "../db/connection.js";
 import { ServerOverloadedError, type ChatTurnHandle, type LettaClient } from "../letta/client.js";
 import {
@@ -269,20 +269,8 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
     cancelController.signal.addEventListener("abort", onCancel, { once: true });
 
     // Step 5 — drain the SDK message stream.
-    // Track the last Letta run id we see — used to fetch usage stats
-    // after the terminal `result`. The SDK strips Letta message ids
-    // from its translated payloads, so we re-fetch via REST
-    // (`getRunUsageStats(runId)`) to get both the usage_statistics
-    // and the last assistant message id we'll stamp the badge on.
-    let lastRunId: string | null = null;
     try {
       for await (const sdkMsg of handle.events) {
-        // SDKAssistantMessage / SDKReasoningMessage / SDKToolCallMessage
-        // each carry `runId`. Take the most recent — a multi-step turn
-        // can have several runs, and we want the latest.
-        if ((sdkMsg as { runId?: string }).runId) {
-          lastRunId = (sdkMsg as { runId: string }).runId;
-        }
         if (sdkMsg.type === "result") {
           // Terminal — finalizeTerminal emits the right closing events
           // based on success / interrupted / error.
@@ -315,70 +303,6 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
       metrics.lettaRequestDurationMs.set(Date.now() - lettaStartedMs);
     }
 
-    // Step 5.5 — usage emission + persistence. Only fire on successful
-    // termination (cancelled / failed turns may or may not have a
-    // usable runId, and the badge isn't load-bearing). Best-effort:
-    // any failure here logs and continues — we already emitted
-    // stream_end above, so the turn is "done" from the client's POV.
-    if (
-      lastRunId !== null &&
-      translatorState.status === "done"
-    ) {
-      try {
-        const usage = await opts.lettaClient.getRunUsageStats(lastRunId);
-        if (usage && usage.lastAssistantMessageId) {
-          // Persist for /sessions/{id}/messages history rendering.
-          opts.db
-            .insert(messageUsage)
-            .values({
-              lettaMessageId: usage.lastAssistantMessageId,
-              sessionId: opts.sessionId,
-              promptTokens: usage.promptTokens,
-              completionTokens: usage.completionTokens,
-              totalTokens: usage.totalTokens,
-              cachedInputTokens: usage.cachedInputTokens,
-              cacheWriteTokens: usage.cacheWriteTokens,
-              reasoningTokens: usage.reasoningTokens,
-              contextTokens: usage.contextTokens,
-              runId: lastRunId,
-            })
-            .onConflictDoUpdate({
-              target: messageUsage.lettaMessageId,
-              set: {
-                promptTokens: usage.promptTokens,
-                completionTokens: usage.completionTokens,
-                totalTokens: usage.totalTokens,
-                cachedInputTokens: usage.cachedInputTokens,
-                cacheWriteTokens: usage.cacheWriteTokens,
-                reasoningTokens: usage.reasoningTokens,
-                contextTokens: usage.contextTokens,
-                runId: lastRunId,
-              },
-            })
-            .run();
-          // Live wire event — UI can attach the badge immediately
-          // without waiting for a /messages refetch.
-          opts.onEvent({
-            seq: 0, // emit() bypassed here; the stream's already drained.
-            event: "usage",
-            data: {
-              letta_message_id: usage.lastAssistantMessageId,
-              ...(usage.promptTokens !== null ? { input: usage.promptTokens } : {}),
-              ...(usage.completionTokens !== null ? { output: usage.completionTokens } : {}),
-              ...(usage.cachedInputTokens !== null ? { cache_read: usage.cachedInputTokens } : {}),
-              ...(usage.cacheWriteTokens !== null ? { cache_write: usage.cacheWriteTokens } : {}),
-              ...(usage.reasoningTokens !== null ? { reasoning: usage.reasoningTokens } : {}),
-              ...(usage.contextTokens !== null ? { context: usage.contextTokens } : {}),
-              ...(usage.totalTokens !== null ? { total: usage.totalTokens } : {}),
-            },
-            state: { status: "done", phase: null } satisfies AIHubEventState,
-          });
-        }
-      } catch (err) {
-        opts.logger.warn({ err, runId: lastRunId }, "usage-stats fetch/persist failed");
-      }
-    }
-
     publisher.close();
     opts.onEvent(null);
     metrics.chatDurationMs.set(Date.now() - startedMs);

package/src/letta/lettaCliShim.mjs

@@ -1,40 +0,0 @@
-#!/usr/bin/env node
-/**
- * Letta Code CLI shim — runs in front of the spawned CLI subprocess
- * (via `LETTA_CLI_PATH`) and injects `--tools ""` into argv before
- * loading the CLI bundle.
- *
- * **Why `--tools ""`.** The SDK doesn't expose the flag that actually
- * empties the CLI's tool registry. It only exposes `--allowedTools` /
- * `--disallowedTools`, which are runtime permission gates, not
- * registry filters. The `--tools` flag is the only mechanism that
- * makes the LLM see ONLY the agent's ADE-attached tools (equivalent
- * to the TUI `/toolset none` action).
- *
- * **CLI resolution** — `require.resolve("@data-club/letta-code")` from
- * node_modules. The DataClub fork is published to npmjs.org under the
- * `@data-club` scope (forked from `@letta-ai/letta-code`); locally it's
- * `link:`-overridden to `../letta-code-fork` via `pnpm.overrides`.
- */
-
-import { createRequire } from "node:module";
-
-const require = createRequire(import.meta.url);
-const lettaCliPath = require.resolve("@data-club/letta-code");
-
-// Rewrite argv to point at the real CLI + inject `--tools ""`. argv[0]
-// (the node binary path) is preserved; argv[1] becomes the real CLI
-// path so any path-relative resolution inside the CLI (e.g. finding
-// the bundled `skills/` dir) works correctly.
-process.argv = [
-  process.argv[0],
-  lettaCliPath,
-  "--tools",
-  "",
-  ...process.argv.slice(2),
-];
-
-// Load the real CLI. The bundle's top-level code parses argv, sees
-// our injected `--tools ""`, calls `toolFilter.setEnabledTools("")`,
-// and starts up with an empty tool-registration allowlist.
-await import(lettaCliPath);