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

package/src/letta/index.ts

@@ -1,15 +1,18 @@
 /**
  * Public exports for the `letta/` module — the single entry point the rest
- * of the server uses to reach Letta. Per §6.4, **every Letta interaction
- * goes through `LettaClient`**; no raw HTTP, no other entry points.
- *
- * @see SPECIFICATIONS.md §6.4
+ * of the server uses to reach Letta. Every Letta interaction goes through
+ * `LettaClient` (implemented over `@data-club/letta-runtime`'s server-less
+ * local backend); no raw HTTP, no other entry points.
  */
 
 export {
   createDefaultLettaClient,
+  ForkSourceNotFoundError,
+  ServerOverloadedError,
+  type ChatTurnHandle,
   type CreateLettaClientDeps,
   type LettaClient,
+  type LettaMessage,
   type StreamUserMessageOpts,
 } from "./client.js";
 export {
@@ -22,25 +25,9 @@ export {
   type UnsequencedEvent,
 } from "./eventTranslator.js";
 export {
-  ServerOverloadedError,
   SubprocessThrottle,
   readThrottleConfigFromEnv,
   type ThrottleConfig,
   type ThrottleLease,
 } from "./subprocessThrottle.js";
-export {
-  seedAgentToolsetNone,
-  type SeedOutcome,
-  type ToolsetPreference,
-} from "./settingsFileSeed.js";
-export type {
-  LettaAssistantMessage,
-  LettaHiddenReasoningMessage,
-  LettaMessage,
-  LettaReasoningMessage,
-  LettaSdk,
-  LettaStreamEvent,
-  LettaToolCallMessage,
-  LettaToolReturnMessage,
-  LettaUserMessage,
-} from "./types.js";
+export type { SDKMessage } from "./types.js";

package/src/letta/sandbox.ts

@@ -16,8 +16,8 @@
  * @see docs/server/session-sandboxes.md
  */
 
-import { existsSync, mkdirSync } from "node:fs";
-import { cp, rm } from "node:fs/promises";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { cp, link, mkdir, readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 
 /**
@@ -108,16 +108,150 @@ export function resolveSeedDir(filesDir: string, seedName: string): string {
 }
 
 /**
- * Recursively copies the seed folder into the (not-yet-existing) sandbox
- * target. The target's parent is created via `mkdir -p` if needed; the
- * target itself is created by `cp({ recursive: true })`. Throws on any
- * I/O failure — the caller is responsible for rolling back the just-
- * created Letta conversation if this throws.
+ * Filename of the optional per-seed materialization manifest, looked up in
+ * the seed folder's root. When absent, `materializeSandbox` behaves exactly
+ * as before (full recursive copy). The manifest itself is never
+ * materialized into the sandbox.
+ */
+export const SEED_MANIFEST_FILENAME = "seed.manifest.json";
+
+/**
+ * Parsed shape of `seed.manifest.json`.
+ *
+ * `link` — glob patterns (relative to the seed root, `/`-separated) of
+ * files to **hardlink** into the sandbox instead of copying. Intended for
+ * large read-only assets (multi-hundred-MB SQLite databases) where a
+ * per-session copy would cost seconds of latency and gigabytes of disk.
+ *
+ * Operator contract for linked files (documented in
+ * docs/server/session-sandboxes.md):
+ * - make them read-only (`chmod 444`) — a hardlink shares the inode, so a
+ *   write through any sandbox would mutate every session's view;
+ * - update them by replace-and-rename (new inode), never in place —
+ *   running sessions then keep the old data, new sessions get the new;
+ * - SQLite seeds should be in `journal_mode=DELETE` (not WAL) so read-only
+ *   opens need no `-shm`/`-wal` sidecar writes.
+ */
+export interface SeedManifest {
+  link?: string[];
+}
+
+/**
+ * Converts a manifest glob into an anchored RegExp over the seed-relative
+ * posix path. Supported syntax (deliberately minimal, dependency-free):
+ * `**` matches any depth, `*` matches within one path segment, `?` matches
+ * a single non-separator char. Everything else is literal.
+ */
+function globToRegExp(glob: string): RegExp {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i] as string;
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        out += ".*";
+        i++;
+      } else {
+        out += "[^/]*";
+      }
+    } else if (ch === "?") {
+      out += "[^/]";
+    } else {
+      out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/**
+ * Reads and validates the seed manifest, if present. Returns `null` when
+ * the seed has no manifest (the common case — plain full-copy seeds).
+ * Throws with an operator-actionable message on malformed JSON or shape —
+ * a broken manifest should fail session-create loudly, not silently fall
+ * back to copying a 500 MB database per session.
+ *
+ * @param seedDir - absolute seed folder path.
+ */
+export function readSeedManifest(seedDir: string): SeedManifest | null {
+  const manifestPath = join(seedDir, SEED_MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Seed manifest is not valid JSON: ${manifestPath} (${String(err)})`,
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Seed manifest must be a JSON object: ${manifestPath}`);
+  }
+  const linkRaw = (parsed as Record<string, unknown>).link;
+  if (linkRaw !== undefined) {
+    if (
+      !Array.isArray(linkRaw) ||
+      linkRaw.some((p) => typeof p !== "string" || p.length === 0)
+    ) {
+      throw new Error(
+        `Seed manifest "link" must be an array of non-empty glob strings: ${manifestPath}`,
+      );
+    }
+  }
+  return linkRaw === undefined ? {} : { link: linkRaw as string[] };
+}
+
+/**
+ * Recursively materializes one directory level of the seed into the
+ * sandbox: entries whose seed-relative path matches a `link` glob are
+ * hardlinked (zero-copy, instant — seeds and sandboxes live under the same
+ * `AI_HUB_FILES_DIR`, hence the same filesystem); everything else is
+ * copied. A hardlink attempt that fails with `EXDEV` (cross-device — some
+ * exotic bind-mount layout) degrades to a copy rather than failing the
+ * session.
+ */
+async function materializeWithManifest(
+  seedDir: string,
+  targetDir: string,
+  relDir: string,
+  linkMatchers: RegExp[],
+): Promise<void> {
+  const srcDir = relDir === "" ? seedDir : join(seedDir, relDir);
+  const dstDir = relDir === "" ? targetDir : join(targetDir, relDir);
+  await mkdir(dstDir, { recursive: true });
+  const entries = await readdir(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = relDir === "" ? entry.name : `${relDir}/${entry.name}`;
+    if (rel === SEED_MANIFEST_FILENAME) continue;
+    if (entry.isDirectory()) {
+      await materializeWithManifest(seedDir, targetDir, rel, linkMatchers);
+      continue;
+    }
+    const src = join(seedDir, rel);
+    const dst = join(targetDir, rel);
+    if (entry.isFile() && linkMatchers.some((m) => m.test(rel))) {
+      try {
+        await link(src, dst);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "EXDEV") throw err;
+        await cp(src, dst);
+      }
+      continue;
+    }
+    // Non-linked files and symlinks: same per-entry semantics as the
+    // full-copy path below.
+    await cp(src, dst, { errorOnExist: false });
+  }
+}
+
+/**
+ * Materializes the seed folder into the (not-yet-existing) sandbox target.
  *
- * Symlinks in the seed are followed (`{ verbatimSymlinks: false }` is
- * Node's default). Permissions are preserved. The implementation uses
- * `fs.promises.cp` so it's a single syscall sequence per file with no
- * intermediate I/O on our side.
+ * Without a `seed.manifest.json` in the seed root this is a full recursive
+ * copy — byte-for-byte the pre-manifest behavior. With a manifest, files
+ * matching its `link` globs are hardlinked instead of copied (see
+ * {@link SeedManifest}); the manifest file itself is skipped.
+ *
+ * Throws on any I/O failure — the caller is responsible for rolling back
+ * the just-created Letta conversation if this throws.
  *
  * @param seedDir - source folder (must exist).
  * @param targetDir - destination folder (must NOT exist).
@@ -129,6 +263,12 @@ export async function materializeSandbox(
   if (!existsSync(seedDir)) {
     throw new Error(`Seed folder does not exist on disk: ${seedDir}`);
   }
+  const manifest = readSeedManifest(seedDir);
+  if (manifest !== null) {
+    const linkMatchers = (manifest.link ?? []).map(globToRegExp);
+    await materializeWithManifest(seedDir, targetDir, "", linkMatchers);
+    return;
+  }
   // `recursive: true` + `errorOnExist: false` matches `cp -R` semantics —
   // if `targetDir` somehow already exists (impossible in the happy path
   // since session ids are fresh UUIDs, but cheap to be safe), the

package/src/letta/types.ts

@@ -1,65 +1,14 @@
 /**
  * Project-shaped Letta types.
  *
- * Re-exports only the SDK surfaces ai-hub uses, so the rest of the server
- * code never has to traverse `@letta-ai/letta-client`'s deep namespace
- * structure. **No raw HTTP, ever** — these are aliases over the SDK's own
- * types, not parallel inventions (§6.4).
- *
- * If the SDK rev removes or renames one of these, the typechecker flags it
- * at upgrade time and `letta/client.ts` is the single place to adapt.
- *
- * @see SPECIFICATIONS.md §6.4 — SDK-only access pattern
- * @see SPECIFICATIONS.md §6.4.1 — first-class surfaces we depend on
- */
-
-import type Letta from "@letta-ai/letta-client";
-import type {
-  AssistantMessage,
-  HiddenReasoningMessage,
-  Message as LettaSdkMessage,
-  ReasoningMessage,
-  ToolCallMessage,
-  UserMessage,
-} from "@letta-ai/letta-client/resources/agents/messages.js";
-import type { LettaStreamingResponse } from "@letta-ai/letta-client/resources/agents/messages.js";
-import type { ToolReturnMessage } from "@letta-ai/letta-client/resources/tools.js";
-
-/**
- * The underlying SDK client. We `import type` everywhere except in
- * `letta/client.ts` (where the constructor actually runs) so the rest of the
- * codebase stays SDK-version-agnostic in shape.
- */
-export type LettaSdk = Letta;
-
-/**
- * One streaming event from `client.conversations.messages.create({ streaming: true })`.
- *
- * The union spans every variant Letta emits in an SSE stream — assistant
- * text, reasoning, tool calls, tool returns, errors, pings, stop reasons,
- * usage stats. `letta/eventTranslator.ts` is the pure function from this
- * union to ai-hub's wire-protocol events (§9).
- *
- * @see SPECIFICATIONS.md §9 — wire protocol
- */
-export type LettaStreamEvent = LettaStreamingResponse;
-
-/**
- * Alias for `AssistantMessage` — used by the translator + tests. See
- * `letta/eventTranslator.ts` for the streamed-delta vs. cumulative-content
- * note.
+ * Post-migration (server-less local backend), the message shape comes from
+ * `@data-club/letta-runtime` — the fork's `messages list` subcommand prints
+ * the backend's Letta-format records verbatim, and `LettaMessageRecord`
+ * types the fields AI Hub's renderers actually read. The old
+ * `@letta-ai/letta-client` aliases are gone with the server.
  */
-export type LettaAssistantMessage = AssistantMessage;
-/** Alias for `ReasoningMessage` — see `eventTranslator.ts`. */
-export type LettaReasoningMessage = ReasoningMessage;
-/** Alias for `HiddenReasoningMessage` — see `eventTranslator.ts`. */
-export type LettaHiddenReasoningMessage = HiddenReasoningMessage;
-/** Alias for `ToolCallMessage` — see `eventTranslator.ts`. */
-export type LettaToolCallMessage = ToolCallMessage;
-/** Alias for `ToolReturnMessage` — see `eventTranslator.ts`. */
-export type LettaToolReturnMessage = ToolReturnMessage;
-/** Alias for `UserMessage` — only appears in history reads, not in streams. */
-export type LettaUserMessage = UserMessage;
 
-/** Full assembled Letta message (used by `messages.list`). */
-export type LettaMessage = LettaSdkMessage;
+export type {
+  LettaMessageRecord as LettaMessage,
+  SDKMessage,
+} from "@data-club/letta-runtime";

package/src/observability/logger.ts

@@ -46,8 +46,6 @@ const REDACT_PATHS: ReadonlyArray<string> = [
   "*.Authorization",
   "service_token_signing_key",
   "serviceTokenSigningKey",
-  "letta_api_key",
-  "lettaApiKey",
   "metrics_scrape_token",
   "metricsScrapeToken",
   "encryption_key",

package/src/routes/admin/agents.ts

@@ -39,7 +39,6 @@ import {
 } from "../../handlers/responses.js";
 import type { AIHubServerContext, RouteHandler } from "../../handlers/types.js";
 import { seedDirExists, validateSeedName } from "../../letta/sandbox.js";
-import { seedAgentToolsetNone } from "../../letta/settingsFileSeed.js";
 
 /* ────────────────────────────────────────────────────────────────────────── */
 /*  Helpers                                                                   */
@@ -247,42 +246,6 @@ function respondSpecializedFailure(
   }
 }
 
-/**
- * Best-effort seed of `~/.letta/settings.json` with `{toolset: "none"}` for
- * the given Letta agent id. Idempotent. Logs the outcome but **does not
- * throw**: if seeding fails (read-only home dir, permission denied, …) the
- * agent creation should still succeed — the toolset suppression is then
- * a runtime concern the operator notices when chats start producing weird
- * file-edit tool calls. The intent here is hands-off automation, not a
- * required precondition.
- *
- * @param ctx - server context (for logging).
- * @param lettaAgentId - id to seed the toolset preference for.
- *
- * @see ../../letta/settingsFileSeed.ts
- */
-function seedToolsetNoneBestEffort(
-  ctx: AIHubServerContext,
-  lettaAgentId: string,
-): void {
-  try {
-    seedAgentToolsetNone({
-      agentId: lettaAgentId,
-      lettaBaseUrl: process.env.LETTA_BASE_URL,
-      logger: ctx.logger,
-    });
-  } catch (err) {
-    ctx.logger.warn(
-      {
-        agent_id: lettaAgentId,
-        err: err instanceof Error ? err.message : String(err),
-        event: "letta_code_settings_seed_failed",
-      },
-      "Failed to seed Letta Code toolset preference; continuing anyway.",
-    );
-  }
-}
-
 /* ────────────────────────────────────────────────────────────────────────── */
 /*  GET /admin/agents                                                         */
 /* ────────────────────────────────────────────────────────────────────────── */
@@ -415,12 +378,6 @@ export const handleCreateAgent: RouteHandler = protectedRoute(
     const row = ctx.db.select().from(agent).where(eq(agent.id, id)).get();
     if (!row) throw new Error("Just-inserted agent vanished.");
 
-    // Seed `~/.letta/settings.json` so Letta Code's bundled CLI suppresses
-    // its auto-toolset (Read/Write/Bash/etc.) when chat sessions spawn
-    // against this agent. ai-hub wants only the tools the ADE admin
-    // explicitly attached. Best-effort: a write failure logs + continues.
-    seedToolsetNoneBestEffort(ctx, row.lettaAgentId);
-
     ctx.logger.info(
       {
         actor_id: auth.user.id,
@@ -553,12 +510,6 @@ export const handlePatchAgent: RouteHandler = protectedRoute(
     // remove the old agent's seeded record — it may still be backing live
     // sessions per the §11 schema note: existing sessions keep their
     // original `letta_conversation_id` against the original Letta agent.)
-    if (
-      body.letta_agent_id !== undefined &&
-      body.letta_agent_id !== existing.lettaAgentId
-    ) {
-      seedToolsetNoneBestEffort(ctx, body.letta_agent_id);
-    }
 
     ctx.logger.info(
       {

package/src/routes/admin/rotatingMessages.ts

@@ -35,6 +35,7 @@ import {
   validationError,
 } from "../../handlers/responses.js";
 import type { AIHubServerContext, RouteHandler } from "../../handlers/types.js";
+import { seedDirExists, validateSeedName } from "../../letta/sandbox.js";
 import {
   computeNextRotation,
   runRotation,
@@ -42,6 +43,39 @@ import {
   type RotationSchedule,
 } from "../../state/rotationRunner.js";
 
+/**
+ * Validates a `sandbox_seed_name` patch/create value the same way
+ * `/admin/agents` does. `null`/`""` mean "clear" and normalize to `null`.
+ * Returns an error Response, or the normalized value.
+ */
+function checkSandboxSeedName(
+  ctx: AIHubServerContext,
+  value: string | null,
+): { ok: true; normalized: string | null } | { ok: false; response: Response } {
+  if (value === null || value === "") return { ok: true, normalized: null };
+  if (validateSeedName(value) !== "ok") {
+    return {
+      ok: false,
+      response: errorResponse(
+        400,
+        "invalid_seed_name",
+        "sandbox_seed_name may only contain letters, digits, underscores and dashes.",
+      ),
+    };
+  }
+  if (!seedDirExists(ctx.filesDir, value)) {
+    return {
+      ok: false,
+      response: errorResponse(
+        400,
+        "seed_dir_not_found",
+        "No seed folder with that name exists on disk.",
+      ),
+    };
+  }
+  return { ok: true, normalized: value };
+}
+
 /* ────────────────────────────────────────────────────────────────────────── */
 /*  Helpers                                                                   */
 /* ────────────────────────────────────────────────────────────────────────── */
@@ -63,6 +97,7 @@ function rotatingMessageView(row: RotatingMessageRow): Record<string, unknown> {
     last_rotated_at: row.lastRotatedAt,
     next_rotation_at: row.nextRotationAt,
     is_archived: row.isArchived,
+    sandbox_seed_name: row.sandboxSeedName,
     reasoning_visible: row.reasoningVisible,
     tool_calls_visible: row.toolCallsVisible,
     created_at: row.createdAt,
@@ -132,6 +167,7 @@ const createSchema = z
     interval_seconds: z.number().int().nullable().optional(),
     daily_time: z.string().max(5).nullable().optional(),
     cron_expression: z.string().max(255).nullable().optional(),
+    sandbox_seed_name: z.string().max(128).nullable().optional(),
     reasoning_visible: z.boolean().optional(),
     tool_calls_visible: z.boolean().optional(),
   })
@@ -173,6 +209,9 @@ export const handleCreateRotatingMessage: RouteHandler = protectedRoute(
       return errorResponse(400, "invalid_schedule", scheduleCheck.message);
     }
 
+    const seedCheck = checkSandboxSeedName(ctx, body.sandbox_seed_name ?? null);
+    if (!seedCheck.ok) return seedCheck.response;
+
     const id = `rmsg-${randomUUID()}`;
     const ts = nowIso();
     ctx.db
@@ -193,6 +232,7 @@ export const handleCreateRotatingMessage: RouteHandler = protectedRoute(
         // Due immediately — the scheduler picks it up on the next tick.
         nextRotationAt: ts,
         isArchived: false,
+        sandboxSeedName: seedCheck.normalized,
         reasoningVisible: body.reasoning_visible ?? true,
         toolCallsVisible: body.tool_calls_visible ?? true,
         createdAt: ts,
@@ -230,6 +270,7 @@ const patchSchema = z
     daily_time: z.string().max(5).nullable().optional(),
     cron_expression: z.string().max(255).nullable().optional(),
     is_archived: z.boolean().optional(),
+    sandbox_seed_name: z.string().max(128).nullable().optional(),
     reasoning_visible: z.boolean().optional(),
     tool_calls_visible: z.boolean().optional(),
   })
@@ -274,6 +315,11 @@ export const handlePatchRotatingMessage: RouteHandler = protectedRoute(
     if (body.prompt !== undefined) update.prompt = body.prompt;
     if (body.letta_agent_id !== undefined) update.lettaAgentId = body.letta_agent_id;
     if (body.is_archived !== undefined) update.isArchived = body.is_archived;
+    if (body.sandbox_seed_name !== undefined) {
+      const seedCheck = checkSandboxSeedName(ctx, body.sandbox_seed_name);
+      if (!seedCheck.ok) return seedCheck.response;
+      update.sandboxSeedName = seedCheck.normalized;
+    }
     if (body.reasoning_visible !== undefined)
       update.reasoningVisible = body.reasoning_visible;
     if (body.tool_calls_visible !== undefined)
@@ -340,7 +386,7 @@ export const handleRotateRotatingMessageNow: RouteHandler = protectedRoute(
     if (!row) return notFound("Rotating message not found.");
 
     const outcome = await runRotation(
-      { db: ctx.db, lettaClient: ctx.lettaClient, logger: ctx.logger },
+      { db: ctx.db, lettaClient: ctx.lettaClient, logger: ctx.logger, filesDir: ctx.filesDir },
       row,
     );
     const fresh = ctx.db.select().from(rotatingMessage).where(eq(rotatingMessage.id, id)).get();