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

package/src/letta/settingsFileSeed.ts

@@ -1,254 +0,0 @@
-/**
- * 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;
-}