@data-club/ai-hub-server 0.0.1

package/dist/observability/logger.js

@@ -0,0 +1,81 @@
+/**
+ * Structured logging via pino.
+ *
+ * Production: raw JSON to stdout, one line per record (§6.10 — twelve-factor
+ * pattern). Dev: piped through `pino-pretty` for human-readable output, gated
+ * on `NODE_ENV !== "production"` or `LOG_LEVEL=debug`.
+ *
+ * **Redaction is a load-bearing security control** (§13.3). pino's built-in
+ * `redact` option is the single point of truth — every log call goes through
+ * the configured logger, and a regression test asserts a known-secret value
+ * never appears in captured stdout.
+ *
+ * @see SPECIFICATIONS.md §6.10 — observability
+ * @see SPECIFICATIONS.md §13.3 — secrets
+ */
+import { pino } from "pino";
+/**
+ * The redaction paths pino watches on every log record.
+ *
+ * The list explicitly covers the keys the spec calls out (`*_key`, `*_token`,
+ * `password`, `authorization`) plus their nested forms inside common places
+ * (`req.headers.authorization`, `body.password`, etc.). Adding a new
+ * sensitive field is a matter of appending a path here — there is no second
+ * redaction layer to keep in sync.
+ */
+const REDACT_PATHS = [
+    "password",
+    "current_password",
+    "new_password",
+    "passwordHash",
+    "password_hash",
+    "authorization",
+    "Authorization",
+    "headers.authorization",
+    "headers.Authorization",
+    "req.headers.authorization",
+    "req.headers.Authorization",
+    "request.headers.authorization",
+    "request.headers.Authorization",
+    "*.authorization",
+    "*.Authorization",
+    "service_token_signing_key",
+    "serviceTokenSigningKey",
+    "letta_api_key",
+    "lettaApiKey",
+    "metrics_scrape_token",
+    "metricsScrapeToken",
+    "encryption_key",
+    "encryptionKey",
+    "token",
+    "*.token",
+    "generated_password",
+    "*.generated_password",
+];
+/**
+ * Builds a pino logger with the project's redaction policy applied.
+ *
+ * @param opts - level + optional destination override.
+ * @returns the pino logger instance.
+ */
+export function createLogger(opts = {}) {
+    const config = {
+        level: opts.level ?? process.env.LOG_LEVEL ?? "info",
+        redact: {
+            paths: [...REDACT_PATHS],
+            censor: "[redacted]",
+            remove: false,
+        },
+    };
+    return opts.destination ? pino(config, opts.destination) : pino(config);
+}
+/**
+ * The redaction-path list — exposed for tests so a new path added in
+ * `REDACT_PATHS` is automatically covered without test churn.
+ *
+ * @returns a fresh array of the redaction paths used by `createLogger`.
+ */
+export function getRedactPaths() {
+    return [...REDACT_PATHS];
+}
+//# sourceMappingURL=logger.js.map

package/dist/observability/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAiD,MAAM,MAAM,CAAC;AAK3E;;;;;;;;GAQG;AACH,MAAM,YAAY,GAA0B;IAC1C,UAAU;IACV,kBAAkB;IAClB,cAAc;IACd,cAAc;IACd,eAAe;IACf,eAAe;IACf,eAAe;IACf,uBAAuB;IACvB,uBAAuB;IACvB,2BAA2B;IAC3B,2BAA2B;IAC3B,+BAA+B;IAC/B,+BAA+B;IAC/B,iBAAiB;IACjB,iBAAiB;IACjB,2BAA2B;IAC3B,wBAAwB;IACxB,eAAe;IACf,aAAa;IACb,sBAAsB;IACtB,oBAAoB;IACpB,gBAAgB;IAChB,eAAe;IACf,OAAO;IACP,SAAS;IACT,oBAAoB;IACpB,sBAAsB;CACvB,CAAC;AAkBF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B,EAAE;IACzD,MAAM,MAAM,GAAkB;QAC5B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;QACpD,MAAM,EAAE;YACN,KAAK,EAAE,CAAC,GAAG,YAAY,CAAC;YACxB,MAAM,EAAE,YAAY;YACpB,MAAM,EAAE,KAAK;SACd;KACF,CAAC;IACF,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,GAAG,YAAY,CAAC,CAAC;AAC3B,CAAC"}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Process-local Prometheus-shaped metrics registry.
+ *
+ * v1 keeps this tiny — three counters + two gauges — to avoid pulling
+ * `prom-client` for what is a five-series surface. The names + types
+ * match §6.10's contract verbatim so an operator's existing dashboards
+ * keep working when a future version swaps in a heavier library.
+ *
+ * Counters monotonically increment (and persist across the process'
+ * lifetime); gauges hold a single most-recent value. Step 5 wires the
+ * chat-side series; Step 6 fills in the TPM-recovery counters.
+ *
+ * @see SPECIFICATIONS.md §6.10 — observability / metrics
+ */
+/** A monotonic counter. */
+export interface Counter {
+    /** Adds `n` (default 1) to the counter. */
+    inc(n?: number): void;
+    /** Reads the current value. */
+    value(): number;
+}
+/** A single-value gauge. */
+export interface Gauge {
+    /** Replaces the gauge's current value. */
+    set(value: number): void;
+    /** Reads the current value. */
+    value(): number;
+}
+/** Total `/chat` requests received. Bumped on every accepted POST. */
+export declare const chatRequestsTotal: Counter;
+/** TPM recovery attempts started — populated by Step 6. */
+export declare const tpmRecoveryAttemptsTotal: Counter;
+/** TPM recoveries that exhausted their budget — populated by Step 6. */
+export declare const tpmExhaustedTotal: Counter;
+/** Most-recent `/chat` turn duration in ms. */
+export declare const chatDurationMs: Gauge;
+/** Most-recent Letta SDK call duration in ms. */
+export declare const lettaRequestDurationMs: Gauge;
+/**
+ * Renders the registry as a Prometheus-text v0.0.4 exposition.
+ *
+ * The route handler in `routes/metrics.ts` calls this after the bearer
+ * token gate passes.
+ *
+ * @returns the full response body.
+ */
+export declare function renderMetrics(): string;
+/**
+ * Resets every series. **Test-only** — production never calls this.
+ * Without it, vitest's module-cache means counters carry across tests.
+ */
+export declare function _resetMetricsForTests(): void;
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,2BAA2B;AAC3B,MAAM,WAAW,OAAO;IACtB,2CAA2C;IAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+BAA+B;IAC/B,KAAK,IAAI,MAAM,CAAC;CACjB;AAED,4BAA4B;AAC5B,MAAM,WAAW,KAAK;IACpB,0CAA0C;IAC1C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+BAA+B;IAC/B,KAAK,IAAI,MAAM,CAAC;CACjB;AA4BD,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,EAAE,OAAmB,CAAC;AACpD,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,EAAE,OAAmB,CAAC;AAC3D,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,EAAE,OAAmB,CAAC;AACpD,+CAA+C;AAC/C,eAAO,MAAM,cAAc,EAAE,KAAe,CAAC;AAC7C,iDAAiD;AACjD,eAAO,MAAM,sBAAsB,EAAE,KAAe,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAyBtC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAM5C"}

package/dist/observability/metrics.js

@@ -0,0 +1,92 @@
+/**
+ * Process-local Prometheus-shaped metrics registry.
+ *
+ * v1 keeps this tiny — three counters + two gauges — to avoid pulling
+ * `prom-client` for what is a five-series surface. The names + types
+ * match §6.10's contract verbatim so an operator's existing dashboards
+ * keep working when a future version swaps in a heavier library.
+ *
+ * Counters monotonically increment (and persist across the process'
+ * lifetime); gauges hold a single most-recent value. Step 5 wires the
+ * chat-side series; Step 6 fills in the TPM-recovery counters.
+ *
+ * @see SPECIFICATIONS.md §6.10 — observability / metrics
+ */
+/** Internal counter factory. */
+function counter() {
+    let v = 0;
+    return {
+        inc(n = 1) {
+            v += n;
+        },
+        value() {
+            return v;
+        },
+    };
+}
+/** Internal gauge factory. */
+function gauge() {
+    let v = 0;
+    return {
+        set(value) {
+            v = value;
+        },
+        value() {
+            return v;
+        },
+    };
+}
+/** Total `/chat` requests received. Bumped on every accepted POST. */
+export const chatRequestsTotal = counter();
+/** TPM recovery attempts started — populated by Step 6. */
+export const tpmRecoveryAttemptsTotal = counter();
+/** TPM recoveries that exhausted their budget — populated by Step 6. */
+export const tpmExhaustedTotal = counter();
+/** Most-recent `/chat` turn duration in ms. */
+export const chatDurationMs = gauge();
+/** Most-recent Letta SDK call duration in ms. */
+export const lettaRequestDurationMs = gauge();
+/**
+ * Renders the registry as a Prometheus-text v0.0.4 exposition.
+ *
+ * The route handler in `routes/metrics.ts` calls this after the bearer
+ * token gate passes.
+ *
+ * @returns the full response body.
+ */
+export function renderMetrics() {
+    return ([
+        "# HELP chat_requests_total Total /chat requests received.",
+        "# TYPE chat_requests_total counter",
+        `chat_requests_total ${chatRequestsTotal.value()}`,
+        "",
+        "# HELP tpm_recovery_attempts_total TPM recovery attempts started.",
+        "# TYPE tpm_recovery_attempts_total counter",
+        `tpm_recovery_attempts_total ${tpmRecoveryAttemptsTotal.value()}`,
+        "",
+        "# HELP tpm_exhausted_total TPM recoveries that exhausted their budget.",
+        "# TYPE tpm_exhausted_total counter",
+        `tpm_exhausted_total ${tpmExhaustedTotal.value()}`,
+        "",
+        "# HELP chat_duration_ms Most-recent /chat turn duration in ms.",
+        "# TYPE chat_duration_ms gauge",
+        `chat_duration_ms ${chatDurationMs.value()}`,
+        "",
+        "# HELP letta_request_duration_ms Most-recent Letta SDK call duration in ms.",
+        "# TYPE letta_request_duration_ms gauge",
+        `letta_request_duration_ms ${lettaRequestDurationMs.value()}`,
+        "",
+    ].join("\n"));
+}
+/**
+ * Resets every series. **Test-only** — production never calls this.
+ * Without it, vitest's module-cache means counters carry across tests.
+ */
+export function _resetMetricsForTests() {
+    chatRequestsTotal.inc(-chatRequestsTotal.value());
+    tpmRecoveryAttemptsTotal.inc(-tpmRecoveryAttemptsTotal.value());
+    tpmExhaustedTotal.inc(-tpmExhaustedTotal.value());
+    chatDurationMs.set(0);
+    lettaRequestDurationMs.set(0);
+}
+//# sourceMappingURL=metrics.js.map

package/dist/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkBH,gCAAgC;AAChC,SAAS,OAAO;IACd,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO;QACL,GAAG,CAAC,CAAC,GAAG,CAAC;YACP,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,KAAK;YACH,OAAO,CAAC,CAAC;QACX,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8BAA8B;AAC9B,SAAS,KAAK;IACZ,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO;QACL,GAAG,CAAC,KAAK;YACP,CAAC,GAAG,KAAK,CAAC;QACZ,CAAC;QACD,KAAK;YACH,OAAO,CAAC,CAAC;QACX,CAAC;KACF,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,EAAE,CAAC;AACpD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAAY,OAAO,EAAE,CAAC;AAC3D,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,EAAE,CAAC;AACpD,+CAA+C;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAU,KAAK,EAAE,CAAC;AAC7C,iDAAiD;AACjD,MAAM,CAAC,MAAM,sBAAsB,GAAU,KAAK,EAAE,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,CACL;QACE,2DAA2D;QAC3D,oCAAoC;QACpC,uBAAuB,iBAAiB,CAAC,KAAK,EAAE,EAAE;QAClD,EAAE;QACF,mEAAmE;QACnE,4CAA4C;QAC5C,+BAA+B,wBAAwB,CAAC,KAAK,EAAE,EAAE;QACjE,EAAE;QACF,wEAAwE;QACxE,oCAAoC;QACpC,uBAAuB,iBAAiB,CAAC,KAAK,EAAE,EAAE;QAClD,EAAE;QACF,gEAAgE;QAChE,+BAA+B;QAC/B,oBAAoB,cAAc,CAAC,KAAK,EAAE,EAAE;QAC5C,EAAE;QACF,6EAA6E;QAC7E,wCAAwC;QACxC,6BAA6B,sBAAsB,CAAC,KAAK,EAAE,EAAE;QAC7D,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,iBAAiB,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC,CAAC;IAClD,wBAAwB,CAAC,GAAG,CAAC,CAAC,wBAAwB,CAAC,KAAK,EAAE,CAAC,CAAC;IAChE,iBAAiB,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC,CAAC;IAClD,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtB,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC"}

package/dist/routes/admin/agents.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `/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 type { RouteHandler } from "../../handlers/types.js";
+/**
+ * `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 declare const handleListAgents: RouteHandler;
+/**
+ * `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 declare const handleCreateAgent: RouteHandler;
+/**
+ * `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 declare const handlePatchAgent: RouteHandler;
+//# sourceMappingURL=agents.d.ts.map

package/dist/routes/admin/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/routes/admin/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAgBH,OAAO,KAAK,EAAsB,YAAY,EAAE,MAAM,yBAAyB,CAAC;AA0PhF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAM9B,CAAC;AA+BF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAqF/B,CAAC;AAuBF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAyG9B,CAAC"}