@data-club/ai-hub-server 0.0.1

package/src/letta/index.ts

@@ -0,0 +1,46 @@
+/**
+ * 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
+ */
+
+export {
+  createDefaultLettaClient,
+  type CreateLettaClientDeps,
+  type LettaClient,
+  type StreamUserMessageOpts,
+} from "./client.js";
+export {
+  finalizeAssistantMessage,
+  finalizeTerminal,
+  initialTranslatorState,
+  translateSdkMessage,
+  type TranslateStep,
+  type TranslatorState,
+  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";

package/src/letta/lettaCliShim.mjs

@@ -0,0 +1,40 @@
+#!/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);

package/src/letta/sandbox.ts

@@ -0,0 +1,167 @@
+/**
+ * Per-session sandbox + seed directory helpers (Step 12.5).
+ *
+ * The "sandbox" is a per-session working directory under
+ * `{AI_HUB_FILES_DIR}/sandboxes/{session_id}/` that the Letta Code
+ * subprocess for that session runs with as its `cwd`. At session-create
+ * time the server recursively copies the per-agent seed folder
+ * (`{AI_HUB_FILES_DIR}/seeds/{name}/`) into the sandbox. The seed is the
+ * starting state; the sandbox is what the agent's tools mutate during
+ * chat turns.
+ *
+ * Security stance: filesystem-isolation convention, not a security
+ * boundary — see [docs/server/session-sandboxes.md](../../../docs/server/session-sandboxes.md).
+ *
+ * @see SPECIFICATIONS.md §6.4 — Letta integration
+ * @see docs/server/session-sandboxes.md
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { cp, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Result of validating a `sandbox_seed_name` against the safe-name regex.
+ * The admin endpoint maps these to HTTP 400 codes.
+ */
+export type SeedNameValidation = "ok" | "invalid_chars" | "empty";
+
+/**
+ * Regex of allowed `sandbox_seed_name` characters. Restrictive on purpose:
+ * letters / digits / underscore / dash. No dots (rules out `..` traversal),
+ * no slashes (rules out absolute paths and subdir refs), no spaces.
+ */
+const SAFE_SEED_NAME_REGEX = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Validates a candidate seed name for the agent editor. Defense-in-depth —
+ * `resolveSeedDir` also enforces the same check before computing a path.
+ *
+ * @param name - raw value from the request body.
+ * @returns `"ok"` if it passes; otherwise the specific failure reason.
+ */
+export function validateSeedName(name: string): SeedNameValidation {
+  if (name.length === 0) return "empty";
+  if (!SAFE_SEED_NAME_REGEX.test(name)) return "invalid_chars";
+  return "ok";
+}
+
+/**
+ * Resolves the absolute base files directory (the parent of `seeds/` and
+ * `sandboxes/`). Reads `AI_HUB_FILES_DIR` from `env`; falls back to
+ * `{AI_HUB_DATA_DIR}/files` and then `./data/files`. Creates the directory
+ * tree (`<base>/seeds`, `<base>/sandboxes`) if missing — mkdir-recursive
+ * is idempotent, so the boot path can call this freely.
+ *
+ * @param env - env-var record (`process.env` in production, synthesized in
+ *   tests).
+ * @returns the resolved absolute path of the base files directory.
+ */
+export function resolveFilesDir(
+  env: Record<string, string | undefined>,
+): string {
+  const explicit = env.AI_HUB_FILES_DIR;
+  if (explicit && explicit.trim().length > 0) {
+    const base = explicit.trim();
+    mkdirSync(join(base, "seeds"), { recursive: true });
+    mkdirSync(join(base, "sandboxes"), { recursive: true });
+    return base;
+  }
+  const dataDir = env.AI_HUB_DATA_DIR?.trim() || "./data";
+  const base = join(dataDir, "files");
+  mkdirSync(join(base, "seeds"), { recursive: true });
+  mkdirSync(join(base, "sandboxes"), { recursive: true });
+  return base;
+}
+
+/**
+ * Resolves the absolute path of a per-session sandbox folder.
+ *
+ * @param filesDir - the base files directory from `resolveFilesDir`.
+ * @param sessionId - the ai-hub session id.
+ * @returns the absolute path (no I/O; caller decides whether to copy
+ *   into it or `rm`).
+ */
+export function resolveSandboxDir(filesDir: string, sessionId: string): string {
+  // Session ids are server-generated UUIDs (see randomUUID in
+  // routes/sessions.ts); they cannot contain slashes or path separators.
+  // The join is defensive against future id-shape changes.
+  return join(filesDir, "sandboxes", sessionId);
+}
+
+/**
+ * Resolves the absolute path of a seed folder by name. Validates the name
+ * defensively — production callers should have already called
+ * `validateSeedName` and reported a 400 to the user, so reaching the
+ * invalid-name branch here would be a programmer error.
+ *
+ * @param filesDir - the base files directory from `resolveFilesDir`.
+ * @param seedName - the operator-supplied seed-folder name.
+ * @returns the absolute path.
+ * @throws when `seedName` fails the safe-name regex.
+ */
+export function resolveSeedDir(filesDir: string, seedName: string): string {
+  if (validateSeedName(seedName) !== "ok") {
+    throw new Error(`Invalid seed name: ${seedName}`);
+  }
+  return join(filesDir, "seeds", seedName);
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @param seedDir - source folder (must exist).
+ * @param targetDir - destination folder (must NOT exist).
+ */
+export async function materializeSandbox(
+  seedDir: string,
+  targetDir: string,
+): Promise<void> {
+  if (!existsSync(seedDir)) {
+    throw new Error(`Seed folder does not exist on disk: ${seedDir}`);
+  }
+  // `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
+  // copy lands the seed contents on top of whatever was there. We do
+  // NOT pass `force: false` (which would refuse on conflicts) because
+  // an existing sandbox in our state machine should never block a new
+  // session.
+  await cp(seedDir, targetDir, { recursive: true, errorOnExist: false });
+}
+
+/**
+ * Removes a sandbox folder and all its contents. Idempotent: a no-op when
+ * the folder doesn't exist. Used by `POST /admin/sessions/:id/purge-sandbox`
+ * and by the rollback path in `POST /sessions` when something downstream
+ * of materialization throws.
+ *
+ * @param targetDir - absolute path of the sandbox folder.
+ */
+export async function purgeSandbox(targetDir: string): Promise<void> {
+  await rm(targetDir, { recursive: true, force: true });
+}
+
+/**
+ * Checks whether a seed folder is present on disk. Used by the admin
+ * `POST` / `PATCH /admin/agents` validators to surface the 400 inline
+ * before storing a name that wouldn't resolve at session-create time.
+ *
+ * @param filesDir - base files dir from `resolveFilesDir`.
+ * @param seedName - the operator-supplied name (must already pass
+ *   `validateSeedName`).
+ * @returns `true` if `<filesDir>/seeds/<seedName>` exists.
+ */
+export function seedDirExists(filesDir: string, seedName: string): boolean {
+  if (validateSeedName(seedName) !== "ok") return false;
+  return existsSync(resolveSeedDir(filesDir, seedName));
+}

package/src/letta/settingsFileSeed.ts

@@ -0,0 +1,254 @@
+/**
+ * Seeds Letta Code's global agent-settings file (`~/.letta/settings.json`)
+ * with `{toolset: "none"}` for each ai-hub-registered Letta agent.
+ *
+ * **Why this matters.** Letta Code's bundled CLI auto-attaches a "toolset"
+ * (a set of file-edit / shell / search tools — `Read`, `Write`, `Edit`,
+ * `Bash`, etc.) to every agent at session start, based on the model handle.
+ * ai-hub doesn't want those tools — we want only the tools the ADE admin
+ * explicitly attached to the agent. The CLI honors a per-agent
+ * `toolset: "none"` preference stored in its global settings file, which
+ * suppresses the entire auto-toolset.
+ *
+ * **Why global, not project-local.** Letta Code's `SettingsManager` reads
+ * the toolset preference from `~/.letta/settings.json` (the global file),
+ * not `<cwd>/.letta/settings.local.json` (the project file). The global
+ * settings carry agent records keyed by `(agentId, normalizedBaseUrl)`
+ * where `normalizedBaseUrl` is the value of `LETTA_BASE_URL` with the
+ * scheme and trailing slash stripped, or `undefined` when the agent lives
+ * on Letta Cloud. Self-hosted Letta deployments always have a non-default
+ * `LETTA_BASE_URL` so the agent record always has the `baseUrl` field set.
+ *
+ * The `LETTA_CLI_PATH` shim (which injects `--tools ""`) is the primary
+ * mechanism that forces an empty tool registry; this settings-file seed
+ * is the defense-in-depth fallback the TUI also honors.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import type { Logger } from "../observability/logger.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Settings file shape                                                       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Toolset preference values accepted by Letta Code. `"none"` is the
+ * documented-but-not-help-listed value that suppresses every auto-attached
+ * tool; the named toolsets (`codex`, `gemini`, `default`) attach specific
+ * sets of file/shell tools that ai-hub doesn't want.
+ *
+ * The string is treated as an opaque scalar by Letta Code's persistence
+ * layer; we still narrow the TypeScript type here so a typo in this file
+ * fails at compile time.
+ */
+export type ToolsetPreference = "none" | "auto" | "codex" | "codex_snake" | "gemini" | "gemini_snake" | "default";
+
+/** One agent entry inside the global settings file. Mirrors Letta Code's
+ *  internal shape so our writes round-trip with its own writes. Optional
+ *  fields are intentionally absent when unset, matching Letta Code's
+ *  delete-when-falsy convention. */
+export interface AgentSettingsEntry {
+  agentId: string;
+  /** Normalized base URL ("localhost:8283/v1" style — no scheme, no
+   *  trailing slash). Omitted for Letta Cloud agents. */
+  baseUrl?: string;
+  pinned?: boolean;
+  memfs?: boolean;
+  toolset?: ToolsetPreference;
+  systemPromptPreset?: string;
+}
+
+/** Shape of `~/.letta/settings.json` that we touch. We pass through every
+ *  unknown top-level field unchanged so concurrent Letta Code edits don't
+ *  lose data. */
+export interface LettaCodeSettingsFile {
+  agents?: AgentSettingsEntry[];
+  /** Any other fields Letta Code writes (oauth state, env vars, …). We
+   *  treat them as opaque on read + write. */
+  [other: string]: unknown;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Path resolution                                                           */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Returns the absolute path to Letta Code's global settings file. Tests
+ * override `HOME` to point at a tmp dir.
+ *
+ * @returns the path. (Doesn't check existence — caller does.)
+ */
+export function resolveGlobalSettingsPath(): string {
+  return join(homedir(), ".letta", "settings.json");
+}
+
+/**
+ * Normalizes `LETTA_BASE_URL` to match the key Letta Code's CLI uses to
+ * look up agent settings AFTER ai-hub-server's `bootstrap.ts` runs its
+ * own `/v1` stripping. The CLI itself only strips scheme + trailing
+ * slash (so `http://host:p/v1` → `host:p/v1`), but bootstrap.ts mutates
+ * `process.env.LETTA_BASE_URL` at boot to drop the `/v1` (because the
+ * Letta Client SDK that the CLI uses internally appends `/v1` itself —
+ * leaving it in the env produces double-`/v1` requests that 404).
+ *
+ * So by the time the spawned CLI looks up the agent settings, its
+ * `getCurrentServerKey` reads `http://host:p` from env and produces
+ * `host:p`. The settings file entry must use the same key — hence the
+ * extra `/v1` strip here. If `bootstrap.ts` changes its policy, this
+ * helper has to change in lockstep.
+ *
+ * Returns `undefined` for the Letta Cloud default URL (so the agent
+ * record omits the `baseUrl` field, matching Letta Code's behavior on
+ * Cloud).
+ *
+ * @param baseUrl - raw `LETTA_BASE_URL` value.
+ * @returns the normalized form, or `undefined` for Letta Cloud.
+ */
+export function normalizeLettaBaseUrl(baseUrl: string | undefined): string | undefined {
+  if (!baseUrl) return undefined;
+  const stripped = baseUrl
+    .replace(/^https?:\/\//, "")
+    .replace(/\/v1\/?$/i, "")
+    .replace(/\/$/, "");
+  if (stripped === "api.letta.com") return undefined;
+  return stripped;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Read + write                                                              */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Reads the settings file from disk. Returns an empty object if the file
+ * doesn't exist or is unparseable — both cases are recoverable by an
+ * idempotent upsert that recreates the file.
+ *
+ * @param path - the resolved settings path.
+ * @returns the parsed settings (or `{}`).
+ */
+export function readSettingsFile(path: string): LettaCodeSettingsFile {
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf8");
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as LettaCodeSettingsFile;
+    }
+    return {};
+  } catch {
+    // Malformed file (concurrent write, disk corruption) — treat as empty
+    // so the seed proceeds. Worst case the operator's other settings (if
+    // any) are clobbered, which is acceptable when the file was already
+    // broken.
+    return {};
+  }
+}
+
+/**
+ * Writes the settings file atomically: write to `<path>.tmp` then rename.
+ * The rename is atomic on every filesystem the ai-hub-server supports
+ * (ext4, xfs, btrfs, apfs). Creates `~/.letta/` if missing.
+ *
+ * @param path - the resolved settings path.
+ * @param settings - the new contents.
+ */
+export function writeSettingsFile(path: string, settings: LettaCodeSettingsFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(settings, null, 2), { encoding: "utf8", mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Upsert                                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Outcome of a single seed call. Useful for tests and observability.
+ */
+export type SeedOutcome =
+  | { kind: "created"; previousToolset: undefined }
+  | { kind: "updated"; previousToolset: ToolsetPreference | undefined }
+  | { kind: "noop"; previousToolset: ToolsetPreference };
+
+/**
+ * Idempotent upsert of `{toolset: "none"}` for a single agent in the
+ * global settings file.
+ *
+ * Matching is by `(agentId, baseUrl)` — same composite key Letta Code
+ * uses. If the agent record exists with a different toolset (`"auto"`,
+ * `"codex"`, etc.), it's replaced. If it exists already with `"none"`,
+ * we no-op (don't churn the file's mtime).
+ *
+ * @param opts.agentId - the Letta agent id (e.g. `agent-xxx`).
+ * @param opts.lettaBaseUrl - the raw `LETTA_BASE_URL` value (so the
+ *   helper can normalize it the same way Letta Code does). Pass
+ *   `process.env.LETTA_BASE_URL` from the caller.
+ * @param opts.settingsPath - override the settings-file path. Defaults to
+ *   `~/.letta/settings.json`. Tests inject a tmp path.
+ * @param opts.logger - optional pino logger for observability lines.
+ * @returns the outcome (created / updated / noop) so the caller can log.
+ */
+export function seedAgentToolsetNone(opts: {
+  agentId: string;
+  lettaBaseUrl: string | undefined;
+  settingsPath?: string;
+  logger?: Logger;
+}): SeedOutcome {
+  const path = opts.settingsPath ?? resolveGlobalSettingsPath();
+  const normalizedBaseUrl = normalizeLettaBaseUrl(opts.lettaBaseUrl);
+  const settings = readSettingsFile(path);
+  const agents: AgentSettingsEntry[] = Array.isArray(settings.agents) ? [...settings.agents] : [];
+
+  const matchIdx = agents.findIndex(
+    (a) => a.agentId === opts.agentId && (a.baseUrl ?? undefined) === normalizedBaseUrl,
+  );
+
+  let outcome: SeedOutcome;
+
+  if (matchIdx >= 0) {
+    const existing = agents[matchIdx]!;
+    const prev = existing.toolset;
+    if (prev === "none") {
+      outcome = { kind: "noop", previousToolset: "none" };
+      opts.logger?.debug({ agentId: opts.agentId, baseUrl: normalizedBaseUrl }, "letta_code_settings_seed_noop");
+      return outcome;
+    }
+    agents[matchIdx] = { ...existing, toolset: "none" };
+    outcome = { kind: "updated", previousToolset: prev };
+  } else {
+    const entry: AgentSettingsEntry = {
+      agentId: opts.agentId,
+      toolset: "none",
+    };
+    if (normalizedBaseUrl !== undefined) entry.baseUrl = normalizedBaseUrl;
+    agents.push(entry);
+    outcome = { kind: "created", previousToolset: undefined };
+  }
+
+  const next: LettaCodeSettingsFile = { ...settings, agents };
+  writeSettingsFile(path, next);
+
+  opts.logger?.info(
+    {
+      agentId: opts.agentId,
+      baseUrl: normalizedBaseUrl,
+      outcome: outcome.kind,
+      previousToolset: outcome.previousToolset,
+      settingsPath: path,
+    },
+    "letta_code_settings_seed",
+  );
+
+  return outcome;
+}