@data-club/ai-hub-server 0.0.1

package/src/routes/admin/rotatingMessages.ts

@@ -0,0 +1,351 @@
+/**
+ * `/admin/rotating-messages/*` — power_user + admin + super_admin management of
+ * **rotating starting messages** (auto-refreshing, forkable base conversations).
+ *
+ * Mirrors `/admin/agents` conventions (Zod `.strict()`, `power_user`+ gate,
+ * snake_case wire view, archive-only — no DELETE):
+ *
+ * - `GET   /admin/rotating-messages` — every row, archived included.
+ * - `POST  /admin/rotating-messages` — create; validates `letta_agent_id`
+ *   against Letta + the schedule shape. Returns the row including its
+ *   `rmsg-…` `id` — the identifier callers paste into an agent's Base
+ *   conversation field. `next_rotation_at` is set to now so the first
+ *   rotation fires on the next scheduler tick.
+ * - `PATCH /admin/rotating-messages/:id` — partial update; recomputes
+ *   `next_rotation_at` when the schedule changes; re-validates the agent when
+ *   it changes; `is_archived` toggle.
+ * - `POST  /admin/rotating-messages/:id/rotate-now` — runs a rotation inline
+ *   (preview / on-demand refresh) and returns the refreshed row.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+
+import { randomUUID } from "node:crypto";
+
+import { asc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { protectedRoute } from "../../auth/middleware.js";
+import { rotatingMessage } from "../../db/schema.js";
+import type { RotatingMessageRow } from "../../db/schema.js";
+import {
+  errorResponse,
+  jsonResponse,
+  notFound,
+  validationError,
+} from "../../handlers/responses.js";
+import type { AIHubServerContext, RouteHandler } from "../../handlers/types.js";
+import {
+  computeNextRotation,
+  runRotation,
+  validateScheduleFields,
+  type RotationSchedule,
+} from "../../state/rotationRunner.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Helpers                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Wire-format view of a `rotating_message` row for admin consumption. */
+function rotatingMessageView(row: RotatingMessageRow): Record<string, unknown> {
+  return {
+    id: row.id,
+    display_name: row.displayName,
+    prompt: row.prompt,
+    letta_agent_id: row.lettaAgentId,
+    schedule_kind: row.scheduleKind,
+    interval_seconds: row.intervalSeconds,
+    daily_time: row.dailyTime,
+    cron_expression: row.cronExpression,
+    current_conversation_id: row.currentConversationId,
+    last_status: row.lastStatus,
+    last_error: row.lastError,
+    last_rotated_at: row.lastRotatedAt,
+    next_rotation_at: row.nextRotationAt,
+    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 `lettaAgentId` resolves to a live Letta agent. */
+async function lettaAgentExists(
+  ctx: AIHubServerContext,
+  lettaAgentId: string,
+): Promise<boolean> {
+  return (await ctx.lettaClient.retrieveAgent(lettaAgentId)) !== null;
+}
+
+/**
+ * Reduces a schedule config to exactly one populated field for the chosen
+ * kind (the others forced to null), so storage matches the discriminator.
+ */
+function normalizeSchedule(s: RotationSchedule): RotationSchedule {
+  return {
+    scheduleKind: s.scheduleKind,
+    intervalSeconds: s.scheduleKind === "every" ? s.intervalSeconds : null,
+    dailyTime: s.scheduleKind === "daily" ? s.dailyTime : null,
+    cronExpression: s.scheduleKind === "cron" ? s.cronExpression : null,
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /admin/rotating-messages                                              */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /admin/rotating-messages` — every rotating message, archived included.
+ * Sorted by `display_name`. `power_user`+ per the §8.2 matrix.
+ */
+export const handleListRotatingMessages: RouteHandler = protectedRoute(
+  { requiredRole: "power_user" },
+  async (_req, ctx) => {
+    const rows = ctx.db
+      .select()
+      .from(rotatingMessage)
+      .orderBy(asc(rotatingMessage.displayName))
+      .all();
+    return jsonResponse(200, { rotating_messages: rows.map(rotatingMessageView) });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/rotating-messages                                             */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+const scheduleKindSchema = z.enum(["every", "daily", "cron"]);
+
+/** Body for `POST /admin/rotating-messages`. */
+const createSchema = z
+  .object({
+    display_name: z.string().min(1).max(255),
+    prompt: z.string().min(1).max(10_000),
+    letta_agent_id: z.string().min(1).max(255),
+    schedule_kind: scheduleKindSchema,
+    interval_seconds: z.number().int().nullable().optional(),
+    daily_time: z.string().max(5).nullable().optional(),
+    cron_expression: z.string().max(255).nullable().optional(),
+  })
+  .strict();
+
+/**
+ * `POST /admin/rotating-messages` — create a rotating starting message.
+ *
+ * Validation order mirrors `/admin/agents`: Letta agent first (so a bad agent
+ * id surfaces alone), then the schedule shape.
+ */
+export const handleCreateRotatingMessage: 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 = createSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError(parsed.error.issues[0]?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+
+    if (!(await lettaAgentExists(ctx, body.letta_agent_id))) {
+      return errorResponse(400, "letta_agent_not_found", "No Letta agent with that id was found.");
+    }
+
+    const schedule = normalizeSchedule({
+      scheduleKind: body.schedule_kind,
+      intervalSeconds: body.interval_seconds ?? null,
+      dailyTime: body.daily_time ?? null,
+      cronExpression: body.cron_expression ?? null,
+    });
+    const scheduleCheck = validateScheduleFields(schedule);
+    if (!scheduleCheck.ok) {
+      return errorResponse(400, "invalid_schedule", scheduleCheck.message);
+    }
+
+    const id = `rmsg-${randomUUID()}`;
+    const ts = nowIso();
+    ctx.db
+      .insert(rotatingMessage)
+      .values({
+        id,
+        displayName: body.display_name,
+        prompt: body.prompt,
+        lettaAgentId: body.letta_agent_id,
+        scheduleKind: schedule.scheduleKind,
+        intervalSeconds: schedule.intervalSeconds,
+        dailyTime: schedule.dailyTime,
+        cronExpression: schedule.cronExpression,
+        currentConversationId: null,
+        lastStatus: "pending",
+        lastError: null,
+        lastRotatedAt: null,
+        // Due immediately — the scheduler picks it up on the next tick.
+        nextRotationAt: ts,
+        isArchived: false,
+        createdAt: ts,
+        updatedAt: ts,
+      })
+      .run();
+    const row = ctx.db.select().from(rotatingMessage).where(eq(rotatingMessage.id, id)).get();
+    if (!row) throw new Error("Just-inserted rotating message vanished.");
+
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        rotating_message_id: id,
+        letta_agent_id: body.letta_agent_id,
+        event: "admin_rotating_message_created",
+      },
+      "Admin created a rotating starting message.",
+    );
+    return jsonResponse(201, rotatingMessageView(row));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /admin/rotating-messages/:id                                        */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `PATCH /admin/rotating-messages/:id`. All fields optional. */
+const patchSchema = z
+  .object({
+    display_name: z.string().min(1).max(255).optional(),
+    prompt: z.string().min(1).max(10_000).optional(),
+    letta_agent_id: z.string().min(1).max(255).optional(),
+    schedule_kind: scheduleKindSchema.optional(),
+    interval_seconds: z.number().int().nullable().optional(),
+    daily_time: z.string().max(5).nullable().optional(),
+    cron_expression: z.string().max(255).nullable().optional(),
+    is_archived: z.boolean().optional(),
+  })
+  .strict();
+
+/**
+ * `PATCH /admin/rotating-messages/:id` — partial update.
+ *
+ * When any schedule-related field is present, the effective schedule (existing
+ * values overlaid with the patch) is re-validated and `next_rotation_at` is
+ * recomputed from now. When `letta_agent_id` changes it's re-validated against
+ * Letta.
+ */
+export const handlePatchRotatingMessage: 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 = patchSchema.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(rotatingMessage).where(eq(rotatingMessage.id, id)).get();
+    if (!existing) return notFound("Rotating message not found.");
+
+    if (body.letta_agent_id !== undefined && body.letta_agent_id !== existing.lettaAgentId) {
+      if (!(await lettaAgentExists(ctx, body.letta_agent_id))) {
+        return errorResponse(400, "letta_agent_not_found", "No Letta agent with that id was found.");
+      }
+    }
+
+    const update: Partial<typeof rotatingMessage.$inferInsert> = { updatedAt: nowIso() };
+    if (body.display_name !== undefined) update.displayName = body.display_name;
+    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;
+
+    const scheduleTouched =
+      body.schedule_kind !== undefined ||
+      body.interval_seconds !== undefined ||
+      body.daily_time !== undefined ||
+      body.cron_expression !== undefined;
+    if (scheduleTouched) {
+      const effective = normalizeSchedule({
+        scheduleKind: body.schedule_kind ?? existing.scheduleKind,
+        intervalSeconds:
+          body.interval_seconds !== undefined ? body.interval_seconds : existing.intervalSeconds,
+        dailyTime: body.daily_time !== undefined ? body.daily_time : existing.dailyTime,
+        cronExpression:
+          body.cron_expression !== undefined ? body.cron_expression : existing.cronExpression,
+      });
+      const scheduleCheck = validateScheduleFields(effective);
+      if (!scheduleCheck.ok) {
+        return errorResponse(400, "invalid_schedule", scheduleCheck.message);
+      }
+      update.scheduleKind = effective.scheduleKind;
+      update.intervalSeconds = effective.intervalSeconds;
+      update.dailyTime = effective.dailyTime;
+      update.cronExpression = effective.cronExpression;
+      update.nextRotationAt = computeNextRotation(effective, new Date());
+    }
+
+    ctx.db.update(rotatingMessage).set(update).where(eq(rotatingMessage.id, id)).run();
+    const fresh = ctx.db.select().from(rotatingMessage).where(eq(rotatingMessage.id, id)).get();
+    if (!fresh) return notFound();
+
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        rotating_message_id: id,
+        patch_keys: Object.keys(body),
+        event: "admin_rotating_message_patched",
+      },
+      "Admin updated a rotating starting message.",
+    );
+    return jsonResponse(200, rotatingMessageView(fresh));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/rotating-messages/:id/rotate-now                              */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `POST /admin/rotating-messages/:id/rotate-now` — runs a rotation inline so
+ * the operator can preview / force-refresh without waiting for the schedule.
+ * Returns the refreshed row plus the attempt's status. The run may take a
+ * while (it spawns the Letta Code subprocess like a real turn).
+ */
+export const handleRotateRotatingMessageNow: RouteHandler = protectedRoute(
+  { requiredRole: "power_user" },
+  async (_req, ctx, auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const row = ctx.db.select().from(rotatingMessage).where(eq(rotatingMessage.id, id)).get();
+    if (!row) return notFound("Rotating message not found.");
+
+    const outcome = await runRotation(
+      { db: ctx.db, lettaClient: ctx.lettaClient, logger: ctx.logger },
+      row,
+    );
+    const fresh = ctx.db.select().from(rotatingMessage).where(eq(rotatingMessage.id, id)).get();
+    if (!fresh) return notFound();
+
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        rotating_message_id: id,
+        outcome: outcome.status,
+        event: "admin_rotating_message_rotate_now",
+      },
+      "Admin triggered an on-demand rotation.",
+    );
+    return jsonResponse(200, {
+      rotating_message: rotatingMessageView(fresh),
+      outcome,
+    });
+  },
+);

package/src/routes/admin/sessions.ts

@@ -0,0 +1,283 @@
+/**
+ * `/admin/sessions` — read-only sessions overview (power_user + admin +
+ * super_admin).
+ *
+ * Cross-user browsing of every session in the deployment. Useful for
+ * operators debugging agent behavior or quoting recent conversations to
+ * support a customer ([07-admin-sessions-overview.md]).
+ *
+ * Query parameters:
+ *
+ * - `owner_id` — optional user-id filter.
+ * - `agent_id` — optional ai-hub agent-id filter.
+ * - `status` — optional, one of `"active" | "archived" | "all"`. Default
+ *   `"active"`. Mirrors the dropdown in [07-admin-sessions-overview.md]; no
+ *   other values are accepted (turn-level outcomes like failed/cancelled are
+ *   not surfaced as a session-level filter in v1).
+ * - `search` — optional free-text. Matched (case-insensitive) against the
+ *   session title server-side.
+ * - `cursor` — pagination cursor (opaque base64 of `{updated_at, id}`).
+ * - `limit` — page size; default 50, max 200.
+ *
+ * Response: `{ sessions: [...], next_cursor: string | null }`. Each session
+ * carries the owner's username + the agent's display name in addition to the
+ * raw row, so the admin table can render labels without a follow-up join
+ * round-trip.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin sessions endpoint
+ * @see ui-sketches/07-admin-sessions-overview.md
+ */
+
+import { and, asc, desc, eq, like, lt, or, sql } from "drizzle-orm";
+import { z } from "zod";
+
+import { protectedRoute } from "../../auth/middleware.js";
+import { agent, session, turn, user } from "../../db/schema.js";
+import {
+  conflictError,
+  internalError,
+  jsonResponse,
+  notFound,
+  validationError,
+} from "../../handlers/responses.js";
+import type { RouteHandler } from "../../handlers/types.js";
+import { purgeSandbox } from "../../letta/sandbox.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Pagination cursor                                                         */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Opaque cursor — base64 of `${updated_at}|${id}`. */
+interface ParsedCursor {
+  updatedAt: string;
+  id: string;
+}
+
+/**
+ * Encodes a cursor.
+ *
+ * @param updatedAt - the row's `updated_at`.
+ * @param id - the row's id.
+ * @returns the opaque cursor string.
+ */
+function encodeCursor(updatedAt: string, id: string): string {
+  return Buffer.from(`${updatedAt}|${id}`, "utf8").toString("base64url");
+}
+
+/**
+ * Decodes a cursor. Returns `null` on a malformed input — the handler treats
+ * that as "no cursor" (no enumeration leakage; bad cursors just yield the
+ * first page).
+ *
+ * @param raw - the cursor query-param value.
+ * @returns the parsed cursor or `null`.
+ */
+function decodeCursor(raw: string | null): ParsedCursor | null {
+  if (!raw) return null;
+  try {
+    const decoded = Buffer.from(raw, "base64url").toString("utf8");
+    const sep = decoded.indexOf("|");
+    if (sep === -1) return null;
+    return {
+      updatedAt: decoded.slice(0, sep),
+      id: decoded.slice(sep + 1),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Handler                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Allowed values for the `status` filter — see file-level comment. */
+const statusEnum = z.enum(["active", "archived", "all"]);
+
+/**
+ * `GET /admin/sessions` — paginated sessions overview.
+ *
+ * Power_user + above per §8.2. Returns `{ sessions, next_cursor }`. Each row
+ * is joined to its owner + agent so the admin table can render names without
+ * follow-up requests.
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ * @see ui-sketches/07-admin-sessions-overview.md
+ */
+export const handleListSessionsOverview: RouteHandler = protectedRoute(
+  { requiredRole: "power_user" },
+  async (req, ctx) => {
+    const url = new URL(req.url);
+    const ownerId = url.searchParams.get("owner_id");
+    const agentId = url.searchParams.get("agent_id");
+    const statusRaw = url.searchParams.get("status") ?? "active";
+    const statusParsed = statusEnum.safeParse(statusRaw);
+    if (!statusParsed.success) {
+      return validationError(
+        "status must be one of: active, archived, all.",
+        "invalid_status",
+      );
+    }
+    const status = statusParsed.data;
+    const search = url.searchParams.get("search")?.trim() ?? "";
+    const limitParam = url.searchParams.get("limit");
+    let limit = 50;
+    if (limitParam !== null) {
+      const n = Number.parseInt(limitParam, 10);
+      if (!Number.isFinite(n) || n < 1 || n > 200) {
+        return validationError(
+          "limit must be an integer in [1, 200].",
+          "invalid_limit",
+        );
+      }
+      limit = n;
+    }
+    const cursor = decodeCursor(url.searchParams.get("cursor"));
+
+    const conditions = [];
+    if (ownerId) conditions.push(eq(session.userId, ownerId));
+    if (agentId) conditions.push(eq(session.agentId, agentId));
+    if (status === "active") conditions.push(eq(session.isArchived, false));
+    if (status === "archived") conditions.push(eq(session.isArchived, true));
+    if (search.length > 0) {
+      conditions.push(like(sql`lower(${session.title})`, `%${search.toLowerCase()}%`));
+    }
+    if (cursor) {
+      // Strictly after `(updated_at, id)` in descending order.
+      conditions.push(
+        or(
+          lt(session.updatedAt, cursor.updatedAt),
+          and(eq(session.updatedAt, cursor.updatedAt), lt(session.id, cursor.id)),
+        )!,
+      );
+    }
+
+    const rows = ctx.db
+      .select({
+        sessionId: session.id,
+        sessionUserId: session.userId,
+        sessionAgentId: session.agentId,
+        sessionTitle: session.title,
+        sessionIsArchived: session.isArchived,
+        sessionSandboxDir: session.sandboxDir,
+        sessionCreatedAt: session.createdAt,
+        sessionUpdatedAt: session.updatedAt,
+        ownerUsername: user.username,
+        agentDisplayName: agent.displayName,
+      })
+      .from(session)
+      .innerJoin(user, eq(user.id, session.userId))
+      .innerJoin(agent, eq(agent.id, session.agentId))
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(session.updatedAt), asc(session.id))
+      .limit(limit + 1)
+      .all();
+
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const nextCursor =
+      hasMore && page.length > 0
+        ? encodeCursor(
+            page[page.length - 1]!.sessionUpdatedAt,
+            page[page.length - 1]!.sessionId,
+          )
+        : null;
+
+    return jsonResponse(200, {
+      sessions: page.map((r) => ({
+        id: r.sessionId,
+        user_id: r.sessionUserId,
+        agent_id: r.sessionAgentId,
+        title: r.sessionTitle,
+        is_archived: r.sessionIsArchived,
+        // Step-12.5 — surfaces whether the session has a sandbox folder
+        // to purge. We deliberately don't surface the absolute path (it
+        // leaks the server's filesystem layout); the boolean is enough
+        // for the React UI to decide whether to render the button.
+        has_sandbox: r.sessionSandboxDir !== null,
+        created_at: r.sessionCreatedAt,
+        updated_at: r.sessionUpdatedAt,
+        owner_username: r.ownerUsername,
+        agent_display_name: r.agentDisplayName,
+      })),
+      next_cursor: nextCursor,
+    });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/sessions/:id/purge-sandbox — Step 12.5                        */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `POST /admin/sessions/:id/purge-sandbox` — super_admin only.
+ *
+ * Removes the per-session sandbox folder from disk + clears
+ * `session.sandbox_dir`. Idempotent: a 204 is returned both when the
+ * folder was present (and is now gone) and when the session never had a
+ * sandbox in the first place.
+ *
+ * Rejects with `409 turn_running` if any turn for the session is
+ * currently `status = "running"` — purging the cwd out from under a
+ * live subprocess would be unfriendly to the agent and risks
+ * partial-write debris.
+ *
+ * Subsequent chat turns spawn with no `cwd` and the with-no-sandbox
+ * disallow-list, reverting the session to today's stateless shape.
+ *
+ * @see docs/server/session-sandboxes.md
+ */
+export const handlePurgeAdminSessionSandbox: RouteHandler = protectedRoute(
+  { requiredRole: "super_admin" },
+  async (_req, ctx, _auth, params) => {
+    const id = params.id;
+    if (!id) return notFound();
+    const row = ctx.db.select().from(session).where(eq(session.id, id)).get();
+    if (!row) return notFound();
+
+    // Reject while a turn is live — purging cwd mid-spawn would corrupt
+    // the running agent.
+    const liveTurn = ctx.db
+      .select({ id: turn.id })
+      .from(turn)
+      .where(and(eq(turn.sessionId, id), eq(turn.status, "running")))
+      .get();
+    if (liveTurn) {
+      return conflictError(
+        "turn_running",
+        "Cannot purge sandbox while a turn is running.",
+      );
+    }
+
+    // Idempotent: 204 whether or not the column had a value.
+    if (row.sandboxDir) {
+      try {
+        await purgeSandbox(row.sandboxDir);
+      } catch (err) {
+        ctx.logger.error(
+          {
+            event: "session_sandbox_purge_failed",
+            session_id: id,
+            sandbox_dir: row.sandboxDir,
+            err: err instanceof Error ? err.message : String(err),
+          },
+          "Failed to purge per-session sandbox folder.",
+        );
+        return internalError("Failed to purge sandbox.");
+      }
+      ctx.db
+        .update(session)
+        .set({ sandboxDir: null, updatedAt: new Date().toISOString() })
+        .where(eq(session.id, id))
+        .run();
+      ctx.logger.info(
+        {
+          event: "session_sandbox_purged",
+          session_id: id,
+        },
+        "Per-session sandbox folder purged.",
+      );
+    }
+    return new Response(null, { status: 204 });
+  },
+);