@data-club/ai-hub-server 0.0.1

package/src/routes/admin/agents.ts

@@ -0,0 +1,574 @@
+/**
+ * `/admin/agents/*` — power_user + admin + super_admin catalog management.
+ *
+ * Three endpoints (no DELETE by design — agents are archive-only in v1):
+ *
+ * - `GET   /admin/agents` — every agent in the deployment, including archived
+ *   ones. Lets the admin UI render the catalog with the archived rows
+ *   filtered in/out via the `[☐ Show archived]` toggle ([06-admin-agents.md]).
+ * - `POST  /admin/agents` — body `{ display_name, letta_agent_id, tpm_recovery_enabled?, max_recovery_attempts?, default_retry_after_seconds? }`.
+ *   Validates `letta_agent_id` against Letta (Step 5 wires the real check;
+ *   Step 4 stubs it through with a `TODO`).
+ * - `PATCH /admin/agents/:id` — body `{ display_name?, letta_agent_id?, tpm_recovery_enabled?, max_recovery_attempts?, default_retry_after_seconds?, is_archived? }`.
+ *   Archive / unarchive is just `{ is_archived: true | false }`. All fields
+ *   optional; empty patch is a 200 no-op.
+ *
+ * **No DELETE.** Per §6.3.4 / §11, agents cannot be hard-deleted in v1 —
+ * archiving keeps existing sessions readable + writable while preventing new
+ * sessions from starting against the agent. Step 12's UI exposes only
+ * archive/unarchive; this server enforces the same.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin agents endpoints
+ * @see SPECIFICATIONS.md §6.5 — TPM recovery defaults
+ * @see ui-sketches/06-admin-agents.md
+ */
+
+import { randomUUID } from "node:crypto";
+
+import { asc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { protectedRoute } from "../../auth/middleware.js";
+import { agent, rotatingMessage } from "../../db/schema.js";
+import type { AgentRow } from "../../db/schema.js";
+import {
+  errorResponse,
+  jsonResponse,
+  notFound,
+  validationError,
+} 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                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Wire-format view of an `agent` row for admin consumption. Differs from the
+ * user-facing `/agents` response: this one includes `letta_agent_id` (admins
+ * need to see + edit it), the TPM-recovery fields, and the archive flag.
+ *
+ * @param row - the agent row.
+ * @returns the JSON-safe response shape.
+ */
+function adminAgentView(row: AgentRow): Record<string, unknown> {
+  return {
+    id: row.id,
+    display_name: row.displayName,
+    letta_agent_id: row.lettaAgentId,
+    tpm_recovery_enabled: row.tpmRecoveryEnabled,
+    max_recovery_attempts: row.maxRecoveryAttempts,
+    default_retry_after_seconds: row.defaultRetryAfterSeconds,
+    stream_idle_timeout_seconds: row.streamIdleTimeoutSeconds,
+    sandbox_seed_name: row.sandboxSeedName,
+    fork_source_conversation_id: row.forkSourceConversationId,
+    is_archived: row.isArchived,
+    created_at: row.createdAt,
+    updated_at: row.updatedAt,
+  };
+}
+
+/** ISO-8601 timestamp with millisecond precision. */
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Validates that `letta_agent_id` references a real Letta-side agent.
+ *
+ * Calls `ctx.lettaClient.retrieveAgent(...)` (which wraps
+ * `client.agents.retrieve` per §6.4 / §6.4.1) and returns `false` when the
+ * SDK reports the agent doesn't exist. The handler turns the `false` into
+ * a 400 `letta_agent_not_found` so the React modal can surface the error
+ * inline on the field ([06-admin-agents.md]). Any non-404 SDK error
+ * propagates so the route catch-all returns a 500.
+ *
+ * @param ctx - server context (carries the Letta client).
+ * @param lettaAgentId - candidate id.
+ * @returns `true` if the id resolves to a live Letta agent.
+ *
+ * @see SPECIFICATIONS.md §6.4.1 — first-class SDK surfaces
+ */
+async function validateLettaAgentId(
+  ctx: AIHubServerContext,
+  lettaAgentId: string,
+): Promise<boolean> {
+  const found = await ctx.lettaClient.retrieveAgent(lettaAgentId);
+  return found !== null;
+}
+
+/**
+ * Step-12.5 — outcome of validating the two new specialized-agent
+ * fields (`sandbox_seed_name`, `fork_source_conversation_id`) before a
+ * `POST` / `PATCH /admin/agents` row write. Each non-ok variant maps to
+ * a single inline-on-field error code the React modal surfaces.
+ */
+type SpecializedFieldsValidation =
+  | { kind: "ok" }
+  | { kind: "seed_name_invalid" }
+  | { kind: "seed_dir_not_found" }
+  | { kind: "fork_source_not_found" }
+  | { kind: "fork_source_agent_mismatch"; expectedAgentId: string; actualAgentId: string }
+  | { kind: "rotating_message_not_found" }
+  | { kind: "rotating_message_agent_mismatch"; expectedAgentId: string; actualAgentId: string };
+
+/**
+ * Validates the (optional) `sandbox_seed_name` and (optional)
+ * `fork_source_conversation_id` against the filesystem + Letta. Pure for
+ * the success / regex-fail cases; talks to Letta only when a fork source
+ * was supplied. The caller maps the outcome to one of:
+ * - `400 seed_name_invalid`
+ * - `400 seed_dir_not_found`
+ * - `400 fork_source_not_found`
+ * - `400 fork_source_agent_mismatch`
+ *
+ * `null` / `undefined` values short-circuit the corresponding check —
+ * those fields are explicitly opt-in.
+ *
+ * @param ctx - server context (filesDir + lettaClient).
+ * @param fields - candidate values.
+ * @returns the resolved outcome.
+ */
+async function validateSpecializedFields(
+  ctx: AIHubServerContext,
+  fields: {
+    sandboxSeedName: string | null | undefined;
+    forkSourceConversationId: string | null | undefined;
+    expectedLettaAgentId: string;
+  },
+): Promise<SpecializedFieldsValidation> {
+  if (
+    fields.sandboxSeedName !== undefined &&
+    fields.sandboxSeedName !== null &&
+    fields.sandboxSeedName.length > 0
+  ) {
+    const nameValidation = validateSeedName(fields.sandboxSeedName);
+    if (nameValidation !== "ok") {
+      return { kind: "seed_name_invalid" };
+    }
+    if (!seedDirExists(ctx.filesDir, fields.sandboxSeedName)) {
+      return { kind: "seed_dir_not_found" };
+    }
+  }
+  if (
+    fields.forkSourceConversationId !== undefined &&
+    fields.forkSourceConversationId !== null &&
+    fields.forkSourceConversationId.length > 0
+  ) {
+    const ref = fields.forkSourceConversationId;
+    if (ref.startsWith("rmsg-")) {
+      // The base is a rotating starting message. Validate against the
+      // `rotating_message` catalog instead of Letta — its prepared
+      // conversation may not exist yet (no rotation has run), which is fine
+      // at write time; `POST /sessions` handles the "not ready" case.
+      const rmsg = ctx.db
+        .select()
+        .from(rotatingMessage)
+        .where(eq(rotatingMessage.id, ref))
+        .get();
+      if (!rmsg || rmsg.isArchived) {
+        return { kind: "rotating_message_not_found" };
+      }
+      if (rmsg.lettaAgentId !== fields.expectedLettaAgentId) {
+        return {
+          kind: "rotating_message_agent_mismatch",
+          expectedAgentId: fields.expectedLettaAgentId,
+          actualAgentId: rmsg.lettaAgentId,
+        };
+      }
+    } else {
+      const conv = await ctx.lettaClient.retrieveConversation(ref);
+      if (!conv) {
+        return { kind: "fork_source_not_found" };
+      }
+      if (conv.agentId !== fields.expectedLettaAgentId) {
+        return {
+          kind: "fork_source_agent_mismatch",
+          expectedAgentId: fields.expectedLettaAgentId,
+          actualAgentId: conv.agentId,
+        };
+      }
+    }
+  }
+  return { kind: "ok" };
+}
+
+/**
+ * Maps a `SpecializedFieldsValidation` failure to the canonical
+ * `errorResponse(400, code, message)`. Keeps the create + patch handlers
+ * tidy.
+ */
+function respondSpecializedFailure(
+  failure: Exclude<SpecializedFieldsValidation, { kind: "ok" }>,
+): Response {
+  switch (failure.kind) {
+    case "seed_name_invalid":
+      return errorResponse(
+        400,
+        "seed_name_invalid",
+        "sandbox_seed_name must match ^[a-zA-Z0-9_-]+$ (no slashes, no dots).",
+      );
+    case "seed_dir_not_found":
+      return errorResponse(
+        400,
+        "seed_dir_not_found",
+        "No seed folder with that name was found under AI_HUB_FILES_DIR/seeds/.",
+      );
+    case "fork_source_not_found":
+      return errorResponse(
+        400,
+        "fork_source_not_found",
+        "No Letta conversation with that id was found.",
+      );
+    case "fork_source_agent_mismatch":
+      return errorResponse(
+        400,
+        "fork_source_agent_mismatch",
+        `The fork source belongs to Letta agent ${failure.actualAgentId}, ` +
+          `but this ai-hub agent points at ${failure.expectedAgentId}. Letta's fork ` +
+          `API requires the new conversation to share the source's agent.`,
+      );
+    case "rotating_message_not_found":
+      return errorResponse(
+        400,
+        "rotating_message_not_found",
+        "No active rotating starting message with that id was found.",
+      );
+    case "rotating_message_agent_mismatch":
+      return errorResponse(
+        400,
+        "rotating_message_agent_mismatch",
+        `The rotating starting message runs against Letta agent ${failure.actualAgentId}, ` +
+          `but this ai-hub agent points at ${failure.expectedAgentId}. A rotating message ` +
+          `can only back agents that share its Letta agent (Letta forks must be same-agent).`,
+      );
+  }
+}
+
+/**
+ * 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                                                         */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /admin/agents` — every agent in the deployment, archived rows
+ * included. The admin UI filters them client-side via the
+ * `[☐ Show archived]` toggle ([06-admin-agents.md]).
+ *
+ * Sorted by `display_name` for stable rendering.
+ *
+ * Available to `power_user`+ per the §8.2 matrix.
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ */
+export const handleListAgents: RouteHandler = protectedRoute(
+  { requiredRole: "power_user" },
+  async (_req, ctx) => {
+    const rows = ctx.db.select().from(agent).orderBy(asc(agent.displayName)).all();
+    return jsonResponse(200, { agents: rows.map(adminAgentView) });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/agents                                                        */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `POST /admin/agents`. */
+const createAgentSchema = z
+  .object({
+    display_name: z.string().min(1).max(255),
+    letta_agent_id: z.string().min(1).max(255),
+    tpm_recovery_enabled: z.boolean().optional(),
+    max_recovery_attempts: z.number().int().min(0).max(10).optional(),
+    default_retry_after_seconds: z.number().int().min(1).max(3600).optional(),
+    /** Per-agent inter-event idle watchdog (seconds). Default 60. */
+    stream_idle_timeout_seconds: z.number().int().min(5).max(3600).optional(),
+    /**
+     * Step-12.5 — name of the seed folder under `{AI_HUB_FILES_DIR}/seeds/`.
+     * `null` or `""` clears the field; non-null strings are validated
+     * against the safe-name regex + existence on disk.
+     */
+    sandbox_seed_name: z.string().max(128).nullable().optional(),
+    /**
+     * Step-12.5 — Letta conversation id (`conv-…`) to fork from at session
+     * create. `null` or `""` clears the field; non-null strings are
+     * validated via `client.conversations.retrieve` + agent-id match.
+     */
+    fork_source_conversation_id: z.string().max(255).nullable().optional(),
+  })
+  .strict();
+
+/**
+ * `POST /admin/agents` — create a new ai-hub agent (catalog entry).
+ *
+ * Validates the Letta-side id via `validateLettaAgentId` (Step 4 stub —
+ * always passes; Step 5 wires the real check against the Letta SDK). On a
+ * Letta-id miss returns 400 `letta_agent_not_found` with the offending field
+ * named, so the React modal can surface the error inline on the field
+ * ([06-admin-agents.md]).
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ * @see ui-sketches/06-admin-agents.md
+ */
+export const handleCreateAgent: RouteHandler = protectedRoute(
+  { requiredRole: "power_user" },
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = createAgentSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError(parsed.error.issues[0]?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+
+    const ok = await validateLettaAgentId(ctx, body.letta_agent_id);
+    if (!ok) {
+      return errorResponse(
+        400,
+        "letta_agent_not_found",
+        "No Letta agent with that id was found.",
+      );
+    }
+
+    // Step-12.5 — validate the optional sandbox + fork fields. Runs AFTER
+    // the letta_agent_id check so the agent-mismatch error has a clear
+    // expected value to compare against (and so an admin entering a bad
+    // letta_agent_id only sees that error, not the cascading 400 from
+    // the fork validator).
+    const specialized = await validateSpecializedFields(ctx, {
+      sandboxSeedName: body.sandbox_seed_name,
+      forkSourceConversationId: body.fork_source_conversation_id,
+      expectedLettaAgentId: body.letta_agent_id,
+    });
+    if (specialized.kind !== "ok") {
+      return respondSpecializedFailure(specialized);
+    }
+
+    const id = randomUUID();
+    // Empty strings normalize to null so the storage matches the
+    // "field cleared" semantics the React modal sends.
+    const normalizedSeedName =
+      body.sandbox_seed_name && body.sandbox_seed_name.length > 0
+        ? body.sandbox_seed_name
+        : null;
+    const normalizedForkSrc =
+      body.fork_source_conversation_id &&
+      body.fork_source_conversation_id.length > 0
+        ? body.fork_source_conversation_id
+        : null;
+    ctx.db
+      .insert(agent)
+      .values({
+        id,
+        displayName: body.display_name,
+        lettaAgentId: body.letta_agent_id,
+        tpmRecoveryEnabled: body.tpm_recovery_enabled ?? false,
+        maxRecoveryAttempts: body.max_recovery_attempts ?? 2,
+        defaultRetryAfterSeconds: body.default_retry_after_seconds ?? 65,
+        streamIdleTimeoutSeconds: body.stream_idle_timeout_seconds ?? 60,
+        sandboxSeedName: normalizedSeedName,
+        forkSourceConversationId: normalizedForkSrc,
+        isArchived: false,
+      })
+      .run();
+    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,
+        agent_id: row.id,
+        letta_agent_id: row.lettaAgentId,
+        event: "admin_agent_created",
+      },
+      "Admin created an ai-hub agent.",
+    );
+    return jsonResponse(201, adminAgentView(row));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /admin/agents/:id                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `PATCH /admin/agents/:id`. All fields optional; empty patch is a no-op. */
+const patchAgentSchema = z
+  .object({
+    display_name: z.string().min(1).max(255).optional(),
+    letta_agent_id: z.string().min(1).max(255).optional(),
+    tpm_recovery_enabled: z.boolean().optional(),
+    max_recovery_attempts: z.number().int().min(0).max(10).optional(),
+    default_retry_after_seconds: z.number().int().min(1).max(3600).optional(),
+    stream_idle_timeout_seconds: z.number().int().min(5).max(3600).optional(),
+    is_archived: z.boolean().optional(),
+    /** Step-12.5 — nullable to support explicit clear. */
+    sandbox_seed_name: z.string().max(128).nullable().optional(),
+    /** Step-12.5 — nullable to support explicit clear. */
+    fork_source_conversation_id: z.string().max(255).nullable().optional(),
+  })
+  .strict();
+
+/**
+ * `PATCH /admin/agents/:id` — partial update.
+ *
+ * If `letta_agent_id` is in the patch, the same Letta-side validation runs
+ * as on create. `is_archived` is the archive / unarchive toggle (no separate
+ * endpoint). All fields optional; an empty patch (`{}`) is a 200 no-op that
+ * echoes the row unchanged.
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ * @see ui-sketches/06-admin-agents.md
+ */
+export const handlePatchAgent: RouteHandler = protectedRoute(
+  { requiredRole: "power_user" },
+  async (req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = patchAgentSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError(parsed.error.issues[0]?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+
+    const existing = ctx.db.select().from(agent).where(eq(agent.id, id)).get();
+    if (!existing) return notFound("Agent not found.");
+
+    if (body.letta_agent_id !== undefined && body.letta_agent_id !== existing.lettaAgentId) {
+      const ok = await validateLettaAgentId(ctx, body.letta_agent_id);
+      if (!ok) {
+        return errorResponse(
+          400,
+          "letta_agent_not_found",
+          "No Letta agent with that id was found.",
+        );
+      }
+    }
+
+    // Step-12.5 — validate the specialized fields against the
+    // *effective* letta_agent_id (the patched value when supplied,
+    // otherwise the existing one). Only validates fields touched by
+    // this PATCH; unchanged fields are skipped.
+    const effectiveLettaAgentId = body.letta_agent_id ?? existing.lettaAgentId;
+    const seedTouched = body.sandbox_seed_name !== undefined;
+    const forkTouched = body.fork_source_conversation_id !== undefined;
+    if (seedTouched || forkTouched) {
+      const specialized = await validateSpecializedFields(ctx, {
+        sandboxSeedName: seedTouched ? body.sandbox_seed_name : null,
+        forkSourceConversationId: forkTouched
+          ? body.fork_source_conversation_id
+          : null,
+        expectedLettaAgentId: effectiveLettaAgentId,
+      });
+      if (specialized.kind !== "ok") {
+        return respondSpecializedFailure(specialized);
+      }
+    }
+
+    const update: Partial<typeof agent.$inferInsert> = { updatedAt: nowIso() };
+    if (body.display_name !== undefined) update.displayName = body.display_name;
+    if (body.letta_agent_id !== undefined) update.lettaAgentId = body.letta_agent_id;
+    if (body.tpm_recovery_enabled !== undefined)
+      update.tpmRecoveryEnabled = body.tpm_recovery_enabled;
+    if (body.max_recovery_attempts !== undefined)
+      update.maxRecoveryAttempts = body.max_recovery_attempts;
+    if (body.default_retry_after_seconds !== undefined)
+      update.defaultRetryAfterSeconds = body.default_retry_after_seconds;
+    if (body.stream_idle_timeout_seconds !== undefined)
+      update.streamIdleTimeoutSeconds = body.stream_idle_timeout_seconds;
+    if (body.is_archived !== undefined) update.isArchived = body.is_archived;
+    // Empty strings + null both normalize to null (consistent with create).
+    if (body.sandbox_seed_name !== undefined) {
+      update.sandboxSeedName =
+        body.sandbox_seed_name && body.sandbox_seed_name.length > 0
+          ? body.sandbox_seed_name
+          : null;
+    }
+    if (body.fork_source_conversation_id !== undefined) {
+      update.forkSourceConversationId =
+        body.fork_source_conversation_id &&
+        body.fork_source_conversation_id.length > 0
+          ? body.fork_source_conversation_id
+          : null;
+    }
+
+    ctx.db.update(agent).set(update).where(eq(agent.id, id)).run();
+    const fresh = ctx.db.select().from(agent).where(eq(agent.id, id)).get();
+    if (!fresh) return notFound();
+
+    // If the patch re-pointed the ai-hub agent at a different Letta agent,
+    // seed the new agent's toolset preference too. (We deliberately do NOT
+    // 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(
+      {
+        actor_id: auth.user.id,
+        agent_id: id,
+        patch_keys: Object.keys(body),
+        event: "admin_agent_patched",
+      },
+      "Admin updated an ai-hub agent.",
+    );
+    return jsonResponse(200, adminAgentView(fresh));
+  },
+);