@data-club/ai-hub-server 0.0.1

package/dist/routes/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/routes/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGvE,sDAAsD;AACtD,MAAM,CAAC,MAAM,YAAY,GAAiB,KAAK,IAAI,EAAE,CACnD,YAAY,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAiB,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IACjE,IAAI,CAAC;QACH,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,GAAG,EAAE,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,EACzC,yCAAyC,CAC1C,CAAC;QACF,OAAO,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,YAAY,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC,CAAC;AAEF,2DAA2D;AAC3D,SAAS,UAAU,CAAC,GAAY;IAC9B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/routes/metrics.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `GET /metrics` — Prometheus-text endpoint with a bearer-token gate.
+ *
+ * Unlike every other protected endpoint, `/metrics` does **not** speak the JWT
+ * + role pipeline: Prometheus / Alloy scrapers don't speak our login flow.
+ * Instead, the request must carry `Authorization: Bearer <token>` whose value
+ * **constant-time-matches** `admin_setting.metrics_scrape_token` (§6.10).
+ *
+ * Series exposed (Step 4 — these start at 0 and become live in Steps 5/6):
+ *
+ * - `chat_requests_total` — counter, total `/chat` requests received.
+ * - `tpm_recovery_attempts_total` — counter, TPM recovery attempts started.
+ * - `tpm_exhausted_total` — counter, TPM recovery exhausted (turn → failed).
+ * - `chat_duration_ms` — histogram-like (rendered as a Gauge in v1; Step 6
+ *   may upgrade to a proper Prometheus histogram).
+ * - `letta_request_duration_ms` — same shape as above for Letta calls.
+ *
+ * Step 4 ships the auth gate + the series scaffolding with all counters at
+ * zero; Steps 5 + 6 wire them up as the chat path is implemented.
+ *
+ * @see SPECIFICATIONS.md §6.10 — observability / metrics token
+ * @see SPECIFICATIONS.md §6.3.5 — /metrics in the API surface
+ */
+import type { RouteHandler } from "../handlers/types.js";
+/**
+ * `GET /metrics` — bearer-token-gated Prometheus exposition.
+ *
+ * Not behind `protectedRoute` — the auth is the bearer token, not the JWT
+ * pipeline. Returns 401 on missing / wrong token (with the same generic
+ * `unauthorized` envelope as the JWT paths, no scope leakage).
+ *
+ * @see SPECIFICATIONS.md §6.10
+ */
+export declare const handleMetrics: RouteHandler;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/routes/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/routes/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AA6CzD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,YA0B3B,CAAC"}

package/dist/routes/metrics.js

@@ -0,0 +1,106 @@
+/**
+ * `GET /metrics` — Prometheus-text endpoint with a bearer-token gate.
+ *
+ * Unlike every other protected endpoint, `/metrics` does **not** speak the JWT
+ * + role pipeline: Prometheus / Alloy scrapers don't speak our login flow.
+ * Instead, the request must carry `Authorization: Bearer <token>` whose value
+ * **constant-time-matches** `admin_setting.metrics_scrape_token` (§6.10).
+ *
+ * Series exposed (Step 4 — these start at 0 and become live in Steps 5/6):
+ *
+ * - `chat_requests_total` — counter, total `/chat` requests received.
+ * - `tpm_recovery_attempts_total` — counter, TPM recovery attempts started.
+ * - `tpm_exhausted_total` — counter, TPM recovery exhausted (turn → failed).
+ * - `chat_duration_ms` — histogram-like (rendered as a Gauge in v1; Step 6
+ *   may upgrade to a proper Prometheus histogram).
+ * - `letta_request_duration_ms` — same shape as above for Letta calls.
+ *
+ * Step 4 ships the auth gate + the series scaffolding with all counters at
+ * zero; Steps 5 + 6 wire them up as the chat path is implemented.
+ *
+ * @see SPECIFICATIONS.md §6.10 — observability / metrics token
+ * @see SPECIFICATIONS.md §6.3.5 — /metrics in the API surface
+ */
+import { timingSafeEqual } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { adminSetting } from "../db/schema.js";
+import { unauthorized } from "../handlers/responses.js";
+import { renderMetrics } from "../observability/metrics.js";
+/**
+ * Constant-time-compares the supplied bearer token against the stored
+ * scrape token. Returns `false` for any malformed input (no length leak).
+ *
+ * @param supplied - the bearer token from the request header.
+ * @param stored - the token from `admin_setting.metrics_scrape_token`.
+ * @returns `true` if the tokens match.
+ */
+function tokensEqual(supplied, stored) {
+    // Buffers must be the same length for timingSafeEqual. Pad the shorter one
+    // and compare lengths separately so we still don't reveal "supplied was
+    // shorter" via timing.
+    const a = Buffer.from(supplied, "utf8");
+    const b = Buffer.from(stored, "utf8");
+    if (a.length !== b.length) {
+        // Burn an equal-length compare so the timing of the rejection doesn't
+        // distinguish "wrong length" from "wrong value."
+        const dummy = Buffer.alloc(b.length, 0);
+        try {
+            timingSafeEqual(dummy, b);
+        }
+        catch {
+            /* ignored */
+        }
+        return false;
+    }
+    return timingSafeEqual(a, b);
+}
+/**
+ * Extracts the bearer token from the `Authorization` header value.
+ *
+ * @param value - the raw header value (or `null`).
+ * @returns the token or `null`.
+ */
+function extractBearer(value) {
+    if (!value)
+        return null;
+    const m = value.match(/^Bearer\s+(.+)$/i);
+    if (!m)
+        return null;
+    const token = m[1]?.trim() ?? "";
+    return token.length > 0 ? token : null;
+}
+/**
+ * `GET /metrics` — bearer-token-gated Prometheus exposition.
+ *
+ * Not behind `protectedRoute` — the auth is the bearer token, not the JWT
+ * pipeline. Returns 401 on missing / wrong token (with the same generic
+ * `unauthorized` envelope as the JWT paths, no scope leakage).
+ *
+ * @see SPECIFICATIONS.md §6.10
+ */
+export const handleMetrics = async (req, ctx) => {
+    const supplied = extractBearer(req.headers.get("authorization"));
+    if (!supplied)
+        return unauthorized();
+    const settings = ctx.db
+        .select({ token: adminSetting.metricsScrapeToken })
+        .from(adminSetting)
+        .where(eq(adminSetting.id, 1))
+        .get();
+    const stored = settings?.token;
+    if (!stored || !tokensEqual(supplied, stored)) {
+        return unauthorized();
+    }
+    // Step 5 wires `chat_requests_total`, `chat_duration_ms`, and
+    // `letta_request_duration_ms` to live values. Step 6 fills in the
+    // TPM-recovery counters. The registry lives in
+    // `observability/metrics.ts`.
+    const body = renderMetrics();
+    return new Response(body, {
+        status: 200,
+        headers: {
+            "Content-Type": "text/plain; version=0.0.4; charset=utf-8",
+        },
+    });
+};
+//# sourceMappingURL=metrics.js.map

package/dist/routes/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/routes/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,QAAgB,EAAE,MAAc;IACnD,2EAA2E;IAC3E,wEAAwE;IACxE,uBAAuB;IACvB,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,sEAAsE;QACtE,iDAAiD;QACjD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,aAAa;QACf,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAoB;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC1C,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACjC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAiB,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IAC5D,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC,QAAQ;QAAE,OAAO,YAAY,EAAE,CAAC;IAErC,MAAM,QAAQ,GAAG,GAAG,CAAC,EAAE;SACpB,MAAM,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,kBAAkB,EAAE,CAAC;SAClD,IAAI,CAAC,YAAY,CAAC;SAClB,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;SAC7B,GAAG,EAAE,CAAC;IACT,MAAM,MAAM,GAAG,QAAQ,EAAE,KAAK,CAAC;IAC/B,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;QAC9C,OAAO,YAAY,EAAE,CAAC;IACxB,CAAC;IAED,8DAA8D;IAC9D,kEAAkE;IAClE,+CAA+C;IAC/C,8BAA8B;IAC9B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAE7B,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,GAAG;QACX,OAAO,EAAE;YACP,cAAc,EAAE,0CAA0C;SAC3D;KACF,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/routes/sessions.d.ts

@@ -0,0 +1,161 @@
+/**
+ * User-facing `/sessions/*` — the caller's own sessions (never cross-user).
+ *
+ * Step 4 ships the four CRUD endpoints minus DELETE (sessions are archive-only
+ * in v1 — §6.3.1). The Letta-conversation-create call on `POST /sessions` is
+ * stubbed; Step 5 replaces the placeholder with `client.conversations.create`.
+ *
+ * - `POST /sessions` — body `{ agent_id, title }`; title required (1..80
+ *   chars). Creates a session owned by the caller against `agent_id`. The
+ *   server snapshots `agent.letta_agent_id` into `session.letta_agent_id` and
+ *   stores a placeholder `letta_conversation_id` (Step 5 fills the real one).
+ *   Rejects when the agent is archived (`agent_archived`).
+ * - `GET /sessions?agent_id=...&include_archived=false` — caller-scoped list.
+ *   `agent_id` is required; `include_archived` defaults to false.
+ * - `GET /sessions/:id` — single session if the caller owns it; 404 with no
+ *   enumeration leakage otherwise.
+ * - `PATCH /sessions/:id` — body `{ title?, is_archived? }`. Rename and / or
+ *   archive / unarchive. An empty patch is a 200 no-op.
+ * - `GET /sessions/:id/messages` — 501 stub; Step 5 wires
+ *   `client.conversations.messages.list`.
+ *
+ * @see SPECIFICATIONS.md §6.3.1 — Sessions
+ * @see SPECIFICATIONS.md §11 — `session` table
+ * @see SPECIFICATIONS.md §13.2 — user isolation
+ */
+import type { RouteHandler } from "../handlers/types.js";
+/**
+ * `POST /sessions` — create a new session for the caller against `agent_id`.
+ *
+ * Validates that the referenced ai-hub agent exists and is not archived.
+ * Snapshots `agent.letta_agent_id` so a future re-point of the catalog entry
+ * does not migrate existing conversations.
+ *
+ * Step 5 replaces the placeholder `letta_conversation_id` with a real SDK
+ * call to `client.conversations.create`.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export declare const handleCreateSession: RouteHandler;
+/**
+ * `GET /sessions` — list the caller's sessions for a given agent.
+ *
+ * Query parameters:
+ *
+ * - `agent_id` — required. The ai-hub agent (catalog entry) to scope the list
+ *   to. Sessions for other agents are not returned (a single GET is
+ *   per-agent, mirroring how the React sessions panel mounts inside an
+ *   opened agent — see [03-chat.md](../../../../docs/ui-sketches/03-chat.md)).
+ * - `include_archived` — optional, default `false`. When `true`, archived
+ *   rows are surfaced alongside active ones with their `is_archived` flag
+ *   set; the client distinguishes them visually (`--archived` modifier).
+ *
+ * Order: newest first by `updated_at`.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export declare const handleListSessions: RouteHandler;
+/**
+ * `GET /sessions/:id` — single session, owner-scoped.
+ *
+ * Returns 404 with `not_found` for both "no such session" and "exists but
+ * belongs to another user" — no enumeration leakage (§13.1).
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export declare const handleGetSession: RouteHandler;
+/**
+ * `PATCH /sessions/:id` — rename and / or archive / unarchive, owner-scoped.
+ *
+ * Accepts either field independently — the React UI sends just `title` for
+ * rename and just `is_archived` for archive/unarchive. An empty body
+ * (`{}`) is a 200 no-op that echoes the row unchanged.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export declare const handlePatchSession: RouteHandler;
+/**
+ * `PATCH /sessions/:id/reasoning` — update the user's per-session reasoning
+ * settings. Applied to the agent's `model_settings` automatically before
+ * the next chat turn.
+ *
+ * Owner-scoped: returns 404 for sessions the caller doesn't own.
+ *
+ * @see SPECIFICATIONS.md §6.3.1
+ */
+export declare const handlePatchSessionReasoning: RouteHandler;
+/**
+ * `GET /sessions/:id/messages` — paginated history pulled from Letta.
+ *
+ * Calls `client.conversations.messages.list(conversation_id)` per §6.4 and
+ * projects the result into the wire-shaped `AIHubMessage` array the
+ * React client consumes. Letta is the source of truth for message
+ * history (§6.8); ai-hub does not duplicate it in its SQLite.
+ *
+ * Owner-scoped: returns 404 for sessions not owned by the caller. The
+ * `power_user`+ "all-sessions overview" lives at `/admin/sessions`, not
+ * here.
+ *
+ * @see SPECIFICATIONS.md §6.3.1 — sessions
+ * @see SPECIFICATIONS.md §6.4 — SDK-only rule
+ * @see SPECIFICATIONS.md §6.8 — Letta owns message history
+ */
+export declare const handleGetSessionMessages: RouteHandler;
+/**
+ * `GET /admin/sessions/:id/messages` — read-only session detail for the
+ * admin sessions overview (§8.2, [07-admin-sessions-overview.md]).
+ *
+ * Mirrors `handleGetSessionMessages` but skips the owner check — power_user+
+ * can view any session in the deployment (no write surface; the React side
+ * mounts the same `<MessageBubble />`s without input controls).
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin sessions overview
+ * @see ui-sketches/07-admin-sessions-overview.md
+ */
+export declare const handleAdminGetSessionMessages: RouteHandler;
+/**
+ * `GET /sessions/:id/message-overrides` — list the caller's overrides for
+ * the session's underlying Letta conversation.
+ *
+ * Returns the rows sorted by `ordinal_position` ascending so consumers
+ * can render them alongside the message list at the matching index. An
+ * empty list (no overrides set) returns `{ overrides: [] }` with 200.
+ *
+ * Owner-scoped: 404 for sessions the caller doesn't own.
+ */
+export declare const handleListMessageOverrides: RouteHandler;
+/**
+ * `PUT /sessions/:id/message-overrides/:position` — upsert one or both
+ * override layers for the message at `position`.
+ *
+ * **Validation gates** (in order):
+ * - `404` — session not owned by caller (or doesn't exist).
+ * - `400 invalid_position` — path segment doesn't parse as a non-negative
+ *   integer.
+ * - `400 validation` — body missing both fields.
+ * - `409 turn_in_progress` — a `turn` row exists with `status = "running"`
+ *   for this session. Honoring writes while a turn is in flight would
+ *   race the post-turn writer, so we reject up front.
+ * - `409 message_not_found` — `position` is out of range for the current
+ *   Letta message list. The override would point at a message that
+ *   doesn't exist; callers must wait for the message to land before
+ *   overriding it.
+ *
+ * **Merge semantics.** Only the layers the body provides are written; an
+ * existing value on the other layer is preserved by reading the row,
+ * computing the merged tuple, and upserting the result. This lets the
+ * `/chat` post-turn writer set `user_override` (leaving `system_override`
+ * null) and a later operator PUT set `system_override` without
+ * clobbering the post-turn-written `user_override`.
+ *
+ * Idempotent: same body → same result. Returns 200 with the resulting view.
+ */
+export declare const handlePutMessageOverride: RouteHandler;
+/**
+ * `DELETE /sessions/:id/message-overrides/:position` — remove an override.
+ *
+ * Idempotent: returns 204 whether or not the row existed. Owner-scoped:
+ * 404 for sessions the caller doesn't own.
+ */
+export declare const handleDeleteMessageOverride: RouteHandler;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/routes/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/routes/sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA2BH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAmIzD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAkMjC,CAAC;AAMF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,EAAE,YAgChC,CAAC;AAMF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAiB9B,CAAC;AAcF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,YAoDhC,CAAC;AA0BF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,YA8CzC,CAAC;AAMF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,EAAE,YAStC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,EAAE,YAS3C,CAAC;AAsRF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,YAgBxC,CAAC;AA6BF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,wBAAwB,EAAE,YA+ItC,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAE,YA4BzC,CAAC"}