@noodleseed/one 0.148.0 → 0.149.0

package/node_modules/@noodle-borg/assistant-gateway/dist/public-session.js

@@ -1,7 +1,8 @@
+import { visitorBucket, } from '@noodle-borg/admission-limits/portable';
 import { isPublicEmbedId } from './embed-store.js';
 import { surfaceEnvelope } from './surface-budget.js';
-function refuse(status, code, message) {
-    return { ok: false, status, code, message };
+function refuse(status, code, message, embed) {
+    return { ok: false, status, code, message, ...(embed === undefined ? {} : { embed }) };
 }
 export async function mintPublicSession(request, envelope, ports) {
     if (typeof request.embedId !== 'string' || !isPublicEmbedId(request.embedId)) {
@@ -22,17 +23,33 @@ export async function mintPublicSession(request, envelope, ports) {
         return refuse(403, 'embed_not_found', 'embed is not available');
     const surface = await ports.resolveActiveSurface(embed);
     if (surface === undefined) {
-        return refuse(409, 'surface_unavailable', 'assistant deployment is unavailable');
+        return refuse(409, 'surface_unavailable', 'assistant deployment is unavailable', embed);
     }
     // Origins come from the live artifact, so `noodle deploy` alone updates a pasted snippet.
     if (!surface.origins.includes(request.origin)) {
-        return refuse(403, 'origin_not_allowed', 'origin is not allowed');
+        return refuse(403, 'origin_not_allowed', 'origin is not allowed', embed);
     }
     // The surface's own budget, which an operator may have lowered — or set to zero, which is the kill
     // switch. Resolved after the embed is known and before anything is spent.
     const budgetBounds = await ports.resolveBudgetBounds?.(embed);
     const surfaceLimits = surfaceEnvelope(envelope, embed, budgetBounds);
     const now = ports.now();
+    // Tier 4 before tier 3, which is before solvency. A visitor at their own hourly ceiling is refused
+    // without spending any of the shared address allowance, so one person behind a corporate NAT cannot
+    // consume the allowance the other three hundred are also using. An abuser who rotates the
+    // identifier simply never meets this tier and lands on the address bound below, which is the point:
+    // this is fairness, that is abuse control, and they are deliberately not the same limit.
+    const visitor = visitorBucket(request.visitorId);
+    if (visitor !== undefined) {
+        const perVisitor = await ports.counters.consume({
+            key: `mints:vis:${embed.embedId}:${visitor}`,
+            limit: surfaceLimits.mintsPerVisitorHour,
+            window: 'hour',
+        }, now);
+        if (!perVisitor.allowed) {
+            return refuse(429, 'visitor_session_budget_exhausted', 'assistant is unavailable right now', embed);
+        }
+    }
     // Fairness before solvency: an address at its hourly ceiling is refused without spending any of the
     // surface's day, so one visitor cannot burn the customer's budget on refusals.
     if (typeof request.addressBucket === 'string') {
@@ -42,14 +59,14 @@ export async function mintPublicSession(request, envelope, ports) {
             window: 'hour',
         }, now);
         if (!perAddress.allowed) {
-            return refuse(429, 'address_session_budget_exhausted', 'assistant is unavailable right now');
+            return refuse(429, 'address_session_budget_exhausted', 'assistant is unavailable right now', embed);
         }
     }
     const mints = await ports.counters.consume({ key: `mints:${embed.embedId}`, limit: surfaceLimits.mintsPerDay }, now);
     if (!mints.allowed) {
         // Distinct from a hard error: the widget renders this calmly, and an operator sees a surface that
         // is switched off (limit 0) or spent, not a broken embed.
-        return refuse(429, 'daily_session_budget_exhausted', 'assistant is unavailable right now');
+        return refuse(429, 'daily_session_budget_exhausted', 'assistant is unavailable right now', embed);
     }
     const session = await ports.createSession({
         embed,

package/node_modules/@noodle-borg/assistant-gateway/dist/public-turn.js

@@ -125,6 +125,28 @@ export async function admitPublicTurn(request, defaults, ports) {
             message: 'assistant is unavailable right now',
         };
     }
+    // Platform spend last, when someone other than the customer is paying. Every counter here is
+    // all-or-nothing with no refund, so whichever runs first is charged for turns the ones after it
+    // refuse — and a session ending at its length limit is ordinary traffic, many times a day, while
+    // spend exhaustion is rare and for one day only. Charging the sponsor for every visitor's last
+    // turn is the worse of the two leaks, so this is the counter that goes last.
+    //
+    // It reports the surface's own exhaustion code on purpose: every published widget already treats
+    // `daily_turn_budget_exhausted` as final, and a new code would be read as retryable by all of them
+    // — precisely the load this ceiling exists to refuse. At the ladder's closing rung the surface
+    // ceiling is already zero, so that refusal arrives above; this is the backstop between rungs.
+    if (budgetBounds?.spend !== undefined) {
+        const { key, units, allowance } = budgetBounds.spend;
+        const spend = await ports.counters.consume({ key, limit: allowance, amount: units }, ports.now());
+        if (!spend.allowed) {
+            return {
+                ok: false,
+                status: 429,
+                code: 'daily_turn_budget_exhausted',
+                message: 'assistant is unavailable right now',
+            };
+        }
+    }
     return { ok: true, turnCount: session.turnCount };
 }
 export async function admitBridgeToolCall(request, defaults, ports) {

package/node_modules/@noodle-borg/assistant-gateway/dist/surface-budget.d.ts

@@ -4,6 +4,20 @@ import type { PublicEmbedRecord } from './embed-store.js';
 export interface SurfaceBudgetBounds {
     readonly defaults: Pick<AdmissionEnvelope, 'turnsPerSession' | 'turnsPerDay' | 'mintsPerDay'>;
     readonly ceiling: Pick<AdmissionEnvelope, 'turnsPerDay' | 'mintsPerDay'>;
+    /**
+     * Platform spend accounting for this turn, present only when someone other than the customer is
+     * paying. Absent means customer-funded, and nothing is charged.
+     *
+     * `units` is what this turn costs at the tenant's current rung and `allowance` is its ceiling for
+     * the day; the ladder that produces both lives in `managed-spend.ts`. The ceilings above remain the
+     * primary mechanism — this counter is the exact backstop for the window in which a cached rung
+     * read still says "plenty left".
+     */
+    readonly spend?: {
+        readonly key: string;
+        readonly units: number;
+        readonly allowance: number;
+    };
 }
 /**
  * One surface's daily budget, resolved from the operator's override and the deployment's defaults.
@@ -17,5 +31,5 @@ export interface SurfaceBudgetBounds {
  * operator any more than by app code, so an over-eager `--turns-per-day 999999999` degrades to the
  * ceiling instead of becoming the ceiling. Zero survives clamping and is the kill switch.
  */
-export declare function surfaceEnvelope(base: AdmissionEnvelope, embed: Pick<PublicEmbedRecord, 'turnsPerDay' | 'mintsPerDay'>, bounds?: SurfaceBudgetBounds): AdmissionEnvelope;
+export declare function surfaceEnvelope(base: AdmissionEnvelope, embed: Pick<PublicEmbedRecord, 'turnsPerDay' | 'mintsPerDay' | 'mintsPerAddressHour' | 'turnsPerAddressHour'>, bounds?: SurfaceBudgetBounds): AdmissionEnvelope;
 //# sourceMappingURL=surface-budget.d.ts.map

package/node_modules/@noodle-borg/assistant-gateway/dist/surface-budget.js

@@ -17,6 +17,20 @@ export function surfaceEnvelope(base, embed, bounds) {
         ...effectiveBase,
         ...(embed.turnsPerDay !== undefined ? { turnsPerDay: embed.turnsPerDay } : {}),
         ...(embed.mintsPerDay !== undefined ? { mintsPerDay: embed.mintsPerDay } : {}),
+        // The per-address bounds carry no hosted ceiling, because they govern abuse rather than spend —
+        // so the deployed default is what caps them, and an operator may only lower it. A surface that
+        // could raise its own abuse bound toward the structural maximum would be turning the bound off
+        // for everyone behind one address, which is not a budget an operator gets to spend.
+        ...(embed.mintsPerAddressHour !== undefined
+            ? {
+                mintsPerAddressHour: Math.min(embed.mintsPerAddressHour, effectiveBase.mintsPerAddressHour),
+            }
+            : {}),
+        ...(embed.turnsPerAddressHour !== undefined
+            ? {
+                turnsPerAddressHour: Math.min(embed.turnsPerAddressHour, effectiveBase.turnsPerAddressHour),
+            }
+            : {}),
     });
     if (bounds === undefined)
         return requested;

package/node_modules/@noodle-borg/assistant-gateway/package.json

@@ -41,7 +41,7 @@
     "@noodle-borg/module": "0.0.0",
     "@noodle-borg/protocol": "0.0.0",
     "@noodle-borg/runtime": "0.0.0",
-    "@noodleseed/assistant": "1.28.0",
+    "@noodleseed/assistant": "1.29.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/node_modules/@noodle-borg/cli-catalog/dist/catalog-data-assistant.js

@@ -96,7 +96,7 @@ const EMBEDS_SUBCOMMAND = subcommand({
 const BUDGET_SUBCOMMAND = subcommand({
     ...SUBCOMMAND_FIELDS,
     name: 'budget',
-    summary: 'Set what a public website surface may spend per day. Zero is the kill switch.',
+    summary: 'Set what a public website surface may spend, per day and per source address.',
     subcommands: [
         clientLeaf('set', 'Raise, lower, or switch off a public surface’s daily caps.', {
             ...LEAF_FIELDS,
@@ -115,6 +115,20 @@ const BUDGET_SUBCOMMAND = subcommand({
                     value: '<count>',
                     summary: 'Sessions this surface may open per UTC day. 0 stops it serving anyone.',
                 }),
+                flag({
+                    ...FLAG_FIELDS,
+                    name: 'mints-per-address-hour',
+                    type: 'string',
+                    value: '<count>',
+                    summary: 'Sessions one source address may open per hour. The abuse bound, not fairness.',
+                }),
+                flag({
+                    ...FLAG_FIELDS,
+                    name: 'turns-per-address-hour',
+                    type: 'string',
+                    value: '<count>',
+                    summary: 'Model turns one source address may run per hour. The abuse bound, not fairness.',
+                }),
                 flag({
                     ...FLAG_FIELDS,
                     name: 'surface',

package/node_modules/@noodle-borg/module/dist/request-analytics.d.ts

@@ -5,6 +5,16 @@ export type RequestOutcome = 'ok' | 'tool_error' | 'mcp_error';
 export type RequestKind = 'usage' | 'discovery';
 /** How the session id was derived (stateless transport mints synthetic ids). */
 export type SessionSource = 'mcp' | 'synthetic' | 'none';
+/**
+ * Which product surface the request arrived through. One vocabulary for the whole stream: the MCP
+ * endpoint, either embedded-assistant surface, and a browser agent calling through the WebMCP
+ * provider bridge ([ADR 0220](../../../docs/decisions/0220-webmcp-provider-bridge.md)). Attribution
+ * only — no code may read this to decide what a caller is allowed to do, because the bridge value
+ * originates in a client-declared marker.
+ */
+export type RequestSurface = 'mcp' | 'assistant-public' | 'assistant-authenticated' | 'webmcp';
+export declare const REQUEST_SURFACES: readonly ["mcp", "assistant-public", "assistant-authenticated", "webmcp"];
+export declare function isRequestSurface(value: unknown): value is RequestSurface;
 /** Whether the caller was an anonymous or an authenticated identity (never the raw subject). */
 export type SubjectKind = 'anonymous' | 'authenticated';
 /**
@@ -31,6 +41,8 @@ export interface RequestEventInput {
     /** Bounded client family; always present in practice (`unknown` when nothing safe was supplied). */
     readonly clientFamily?: string;
     readonly accessMode?: AccessMode;
+    /** Originating surface; absent on rows written before schema v3, which read back as unknown. */
+    readonly surface?: RequestSurface;
     readonly subjectKind: SubjectKind;
     readonly method: string;
     readonly kind: RequestKind;
@@ -64,6 +76,7 @@ export interface RequestEventFilter {
     readonly outcome?: RequestOutcome;
     readonly toolName?: string;
     readonly clientName?: string;
+    readonly surface?: RequestSurface;
     readonly sessionId?: string;
     readonly since?: string;
     readonly until?: string;
@@ -75,6 +88,10 @@ export interface RequestEventSink {
 export interface RequestEventStore extends RequestEventSink {
     list(filter: RequestEventFilter): Promise<readonly RequestEvent[]>;
 }
-/** v2 (issue #1309): adds `clientFamily`, `queueMs`, `execMs`, and connector-attribution `details`. */
-export declare const REQUEST_EVENT_SCHEMA_VERSION = 2;
+/**
+ * v2 (issue #1309): adds `clientFamily`, `queueMs`, `execMs`, and connector-attribution `details`.
+ * v3 (ADR 0220): adds `surface`. Additive and unbackfilled — a row at v2 or below simply has no
+ * surface, which a reader must render as unknown rather than as any particular surface.
+ */
+export declare const REQUEST_EVENT_SCHEMA_VERSION = 3;
 //# sourceMappingURL=request-analytics.d.ts.map

package/node_modules/@noodle-borg/module/dist/request-analytics.js

@@ -1,3 +1,12 @@
+export const REQUEST_SURFACES = [
+    'mcp',
+    'assistant-public',
+    'assistant-authenticated',
+    'webmcp',
+];
+export function isRequestSurface(value) {
+    return REQUEST_SURFACES.includes(value);
+}
 /**
  * Bounded client-family projection (issue #1309): a stable low-cardinality token derived from MCP
  * `clientInfo` when supplied, else from a closed table of known HTTP client user agents (`other`
@@ -5,6 +14,10 @@
  */
 export const CLIENT_FAMILY_UNKNOWN = 'unknown';
 export const CLIENT_FAMILY_OTHER = 'other';
-/** v2 (issue #1309): adds `clientFamily`, `queueMs`, `execMs`, and connector-attribution `details`. */
-export const REQUEST_EVENT_SCHEMA_VERSION = 2;
+/**
+ * v2 (issue #1309): adds `clientFamily`, `queueMs`, `execMs`, and connector-attribution `details`.
+ * v3 (ADR 0220): adds `surface`. Additive and unbackfilled — a row at v2 or below simply has no
+ * surface, which a reader must render as unknown rather than as any particular surface.
+ */
+export const REQUEST_EVENT_SCHEMA_VERSION = 3;
 //# sourceMappingURL=request-analytics.js.map

package/node_modules/@noodle-borg/observability/dist/assistant-usage.js

@@ -34,6 +34,40 @@ export function assistantTurnUsageRequestEvent(session, input) {
         ...(input.errorKind === undefined ? {} : { errorKind: input.errorKind }),
     });
 }
+/**
+ * A mint refused before any session existed. There is no session id and no turn to count: the event
+ * carries the tenant it was refused for and the code that refused it, and nothing else.
+ */
+export function assistantRefusedSessionUsageRequestEvent(input) {
+    return assistantUsageRequestEvent({
+        ...input.tenant,
+        deploymentId: input.deploymentId ?? '',
+        eventKind: 'session',
+        surface: 'public',
+        outcome: 'refused',
+        errorKind: input.code,
+        durationMs: input.durationMs,
+    });
+}
+/**
+ * Record a refused mint, when it belongs to a tenant.
+ *
+ * Only attributable refusals are recorded: an unknown or malformed embed id is prober noise and
+ * belongs in platform logs, not in a customer's usage. What an operator actually needs — the surface
+ * is out of budget, one address is at its hourly ceiling, the origin is not on the live allowlist —
+ * all know the embed by the time they refuse, which is why the decision lives here rather than at
+ * the call site: a route that forgets it produces silence, and silence reads as health.
+ */
+export function captureRefusedAssistantSession(capture, refusal, durationMs) {
+    if (refusal.embed === undefined)
+        return;
+    const { org, app, env } = refusal.embed;
+    captureAssistantUsage(capture, assistantRefusedSessionUsageRequestEvent({
+        tenant: { org, app, env },
+        code: refusal.code,
+        durationMs,
+    }));
+}
 export function assistantRefusedTurnUsageRequestEvent(session, errorKind, durationMs) {
     return assistantTurnUsageRequestEvent(session, {
         outcome: 'refused',
@@ -64,9 +98,11 @@ export function captureAssistantUsage(capture, event) {
  * credentials, and page context have no field to enter through.
  */
 export function assistantUsageRequestEvent(input) {
+    const refused = input.eventKind === 'session' ? input.outcome === 'refused' : false;
     const details = {
         eventKind: input.eventKind,
         surface: input.surface,
+        ...(refused ? { assistantOutcome: 'refused' } : {}),
         ...(input.modelSource === undefined ? {} : { modelSource: input.modelSource }),
         ...(input.eventKind === 'turn'
             ? {
@@ -90,26 +126,29 @@ export function assistantUsageRequestEvent(input) {
         env: input.env,
         deploymentId: input.deploymentId,
         requestId: randomUUID(),
-        sessionId: input.sessionId,
+        ...(input.sessionId === undefined ? {} : { sessionId: input.sessionId }),
         sessionSource: 'synthetic',
         subjectKind: input.surface === 'public' ? 'anonymous' : 'authenticated',
         accessMode: input.surface === 'public' ? 'public' : 'authenticated',
+        // The shared stream vocabulary, not the assistant's own: `details.surface` keeps the internal
+        // spelling for the assistant's own aggregates, while this field is what the whole request
+        // stream groups by.
+        surface: input.surface === 'public' ? 'assistant-public' : 'assistant-authenticated',
         method: ASSISTANT_USAGE_METHOD,
         kind: 'usage',
-        outcome: input.eventKind === 'session' || input.outcome === 'delivered'
-            ? 'ok'
-            : input.outcome === 'refused'
-                ? 'tool_error'
+        outcome: input.outcome === 'refused'
+            ? 'tool_error'
+            : input.eventKind === 'session' || input.outcome === 'delivered'
+                ? 'ok'
                 : 'mcp_error',
-        ...(input.eventKind === 'turn' && input.errorKind !== undefined
-            ? { errorKind: input.errorKind }
-            : {}),
+        ...(input.errorKind === undefined ? {} : { errorKind: input.errorKind }),
         durationMs: finiteNonNegative(input.durationMs),
         details,
     };
 }
 export function aggregateAssistantUsage(events) {
     let minted = 0;
+    let refusedSessions = 0;
     let publicSessions = 0;
     let authenticatedSessions = 0;
     let delivered = 0;
@@ -125,7 +164,13 @@ export function aggregateAssistantUsage(events) {
     let noodleManaged = 0;
     let operator = 0;
     const latencies = [];
+    const refusalsByCode = new Map();
     const sessionDepth = new Map();
+    const countRefusal = (code) => {
+        if (code === undefined)
+            return;
+        refusalsByCode.set(code, (refusalsByCode.get(code) ?? 0) + 1);
+    };
     for (const event of events) {
         if (event.method !== ASSISTANT_USAGE_METHOD)
             continue;
@@ -133,6 +178,11 @@ export function aggregateAssistantUsage(events) {
         const eventKind = scalarString(details?.eventKind);
         const surface = scalarString(details?.surface);
         if (eventKind === 'session') {
+            if (scalarString(details?.assistantOutcome) === 'refused') {
+                refusedSessions += 1;
+                countRefusal(event.errorKind);
+                continue;
+            }
             minted += 1;
             if (surface === 'public')
                 publicSessions += 1;
@@ -145,8 +195,10 @@ export function aggregateAssistantUsage(events) {
         const outcome = scalarString(details?.assistantOutcome);
         if (outcome === 'delivered')
             delivered += 1;
-        else if (outcome === 'refused')
+        else if (outcome === 'refused') {
             refused += 1;
+            countRefusal(event.errorKind);
+        }
         else if (outcome === 'failed')
             failed += 1;
         else
@@ -174,7 +226,12 @@ export function aggregateAssistantUsage(events) {
     const depths = [...sessionDepth.values()].sort((a, b) => a - b);
     const sortedLatencies = latencies.sort((a, b) => a - b);
     return {
-        sessions: { minted, public: publicSessions, authenticated: authenticatedSessions },
+        sessions: {
+            minted,
+            public: publicSessions,
+            authenticated: authenticatedSessions,
+            refused: refusedSessions,
+        },
         turns: {
             attempted: delivered + failed + refused,
             delivered,
@@ -197,6 +254,7 @@ export function aggregateAssistantUsage(events) {
         },
         tokens: { prompt, completion, reasoning, total },
         byModelSource: { noodleManaged, operator },
+        refusalsByCode: Object.fromEntries([...refusalsByCode].sort(([a], [b]) => a.localeCompare(b))),
     };
 }
 function scalarString(value) {

package/node_modules/@noodle-borg/observability/dist/index.js

@@ -2,6 +2,7 @@ export * from './assistant-usage.js';
 export * from './intent-capture.js';
 export * from './request-event-buffer.js';
 export * from './request-event-metrics.js';
+export * from './request-event-query.js';
 export * from './request-events.js';
 export * from './request-events-postgres.js';
 export * from './runtime.js';

package/node_modules/@noodle-borg/observability/dist/request-event-query.js

@@ -0,0 +1,48 @@
+import { isRequestSurface, REQUEST_SURFACES, } from '@noodle-borg/module';
+/**
+ * Query parsing for the tenant-facing analytics event listing. It lives beside the store rather
+ * than in the HTTP route because the vocabulary it validates — outcomes, surfaces, the bounded page
+ * size — belongs to the analytics stream, not to one transport. The route keeps the HTTP concern:
+ * this returns a filter or a reason, and never a response.
+ */
+/** Bounded page size: a tenant may ask for fewer, never for more. */
+const MAX_REQUEST_EVENTS_LIMIT = 500;
+const DEFAULT_LIMIT = 100;
+const OUTCOMES = new Set(['ok', 'tool_error', 'mcp_error']);
+export function parseRequestEventQuery(params, tenant) {
+    const limitParam = params.get('limit');
+    let limit = DEFAULT_LIMIT;
+    if (limitParam !== null) {
+        limit = Number(limitParam);
+        if (!Number.isInteger(limit) || limit < 1 || limit > MAX_REQUEST_EVENTS_LIMIT) {
+            return {
+                ok: false,
+                error: `"limit" must be an integer from 1 to ${MAX_REQUEST_EVENTS_LIMIT}`,
+            };
+        }
+    }
+    const status = params.get('status') ?? undefined;
+    if (status !== undefined && !OUTCOMES.has(status)) {
+        return { ok: false, error: '"status" must be one of ok, tool_error, mcp_error' };
+    }
+    const surface = params.get('surface') ?? undefined;
+    if (surface !== undefined && !isRequestSurface(surface)) {
+        return { ok: false, error: `"surface" must be one of ${REQUEST_SURFACES.join(', ')}` };
+    }
+    const tool = params.get('tool') ?? undefined;
+    const client = params.get('client') ?? undefined;
+    return {
+        ok: true,
+        filter: {
+            org: tenant.org,
+            ...(tenant.app !== undefined ? { app: tenant.app } : {}),
+            ...(tenant.env !== undefined ? { env: tenant.env } : {}),
+            limit,
+            ...(status !== undefined ? { outcome: status } : {}),
+            ...(tool !== undefined ? { toolName: tool } : {}),
+            ...(client !== undefined ? { clientName: client } : {}),
+            ...(surface !== undefined ? { surface } : {}),
+        },
+    };
+}
+//# sourceMappingURL=request-event-query.js.map

package/node_modules/@noodle-borg/observability/dist/request-events-postgres.js

@@ -31,6 +31,7 @@ export async function ensureRequestEventSchema(pool) {
       client_version       text,
       client_family        text,
       access_mode          text,
+      surface              text,
       subject_kind         text NOT NULL,
       method               text NOT NULL,
       kind                 text NOT NULL,
@@ -57,6 +58,12 @@ export async function ensureRequestEventSchema(pool) {
       ADD COLUMN IF NOT EXISTS client_family text,
       ADD COLUMN IF NOT EXISTS queue_ms double precision,
       ADD COLUMN IF NOT EXISTS exec_ms double precision
+  `);
+    // Schema v3 (ADR 0220): the originating surface. Additive and unbackfilled — existing rows keep
+    // a NULL surface and read back as unknown.
+    await pool.query(`
+    ALTER TABLE request_events
+      ADD COLUMN IF NOT EXISTS surface text
   `);
     await pool.query(`
     CREATE INDEX IF NOT EXISTS request_events_tenant_time_idx
@@ -97,10 +104,10 @@ export class PostgresRequestEventStore {
         await this.#pool.query(`INSERT INTO request_events
         (id, schema_version, created_at, org_slug, app_slug, environment, deployment_id,
          server_version, sdk_protocol_version, protocol_era, request_id, session_id, session_source,
-         client_name, client_version, client_family, access_mode, subject_kind, method, kind,
+         client_name, client_version, client_family, access_mode, surface, subject_kind, method, kind,
          tool_name, resource_name, prompt_name, outcome, error_kind, duration_ms, queue_ms, exec_ms,
          output_tokens_est, country, details)
-       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24,$25,$26,$27,$28,$29,$30,$31)`, [
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24,$25,$26,$27,$28,$29,$30,$31,$32)`, [
             randomUUID(),
             REQUEST_EVENT_SCHEMA_VERSION,
             this.#now(),
@@ -118,6 +125,7 @@ export class PostgresRequestEventStore {
             input.clientVersion ?? null,
             input.clientFamily ?? null,
             input.accessMode ?? null,
+            input.surface ?? null,
             input.subjectKind,
             input.method,
             input.kind,
@@ -153,6 +161,8 @@ export class PostgresRequestEventStore {
             add('tool_name', filter.toolName);
         if (filter.clientName !== undefined)
             add('client_name', filter.clientName);
+        if (filter.surface !== undefined)
+            add('surface', filter.surface);
         if (filter.sessionId !== undefined)
             add('session_id', filter.sessionId);
         if (filter.since !== undefined) {
@@ -203,6 +213,7 @@ function rowToEvent(row) {
         ...(row.client_version !== null ? { clientVersion: row.client_version } : {}),
         ...(row.client_family !== null ? { clientFamily: row.client_family } : {}),
         ...(row.access_mode !== null ? { accessMode: row.access_mode } : {}),
+        ...(row.surface !== null ? { surface: row.surface } : {}),
         ...(row.tool_name !== null ? { toolName: row.tool_name } : {}),
         ...(row.resource_name !== null ? { resourceName: row.resource_name } : {}),
         ...(row.prompt_name !== null ? { promptName: row.prompt_name } : {}),

package/node_modules/@noodle-borg/observability/dist/request-events.js

@@ -28,6 +28,7 @@ function toRequestEvent(input) {
         ...(input.clientVersion !== undefined ? { clientVersion: input.clientVersion } : {}),
         ...(input.clientFamily !== undefined ? { clientFamily: input.clientFamily } : {}),
         ...(input.accessMode !== undefined ? { accessMode: input.accessMode } : {}),
+        ...(input.surface !== undefined ? { surface: input.surface } : {}),
         ...(input.toolName !== undefined ? { toolName: input.toolName } : {}),
         ...(input.resourceName !== undefined ? { resourceName: input.resourceName } : {}),
         ...(input.promptName !== undefined ? { promptName: input.promptName } : {}),
@@ -52,6 +53,8 @@ function matches(event, filter) {
         return false;
     if (filter.clientName !== undefined && event.clientName !== filter.clientName)
         return false;
+    if (filter.surface !== undefined && event.surface !== filter.surface)
+        return false;
     if (filter.sessionId !== undefined && event.sessionId !== filter.sessionId)
         return false;
     if (filter.since !== undefined && event.createdAt < filter.since)

package/node_modules/@noodle-borg/service/dist/routes/analytics.js

@@ -1,4 +1,4 @@
-import { aggregateRequestEvents } from '@noodle-borg/observability';
+import { aggregateRequestEvents, parseRequestEventQuery } from '@noodle-borg/observability';
 import { normalizedTimestamps, sendJson } from '../http-util.js';
 import { authorizeTenantControl, developerGrantRouteAccess } from './control-plane.js';
 /**
@@ -13,8 +13,6 @@ const WINDOWS_MS = new Map([
     ['7d', 7 * 24 * 60 * 60 * 1000],
     ['30d', 30 * 24 * 60 * 60 * 1000],
 ]);
-const OUTCOMES = new Set(['ok', 'tool_error', 'mcp_error']);
-const MAX_EVENTS_LIMIT = 500;
 /** Session replay cap: newest N of one session, rendered chronologically. */
 const SESSION_EVENTS_LIMIT = 1000;
 /** Aggregation reads a bounded slice; pre-aggregated rollups are the Stage-F scale path. */
@@ -60,33 +58,11 @@ export async function handleTenantEvents(req, res, gate, controlPlane, events, r
     const identity = await authorizeTenantControl(req, res, gate, controlPlane, ref.org, developerGrantRouteAccess(developerGrants, 'cloud:read'));
     if (identity === false)
         return;
-    const limitParam = url.searchParams.get('limit');
-    let limit = 100;
-    if (limitParam !== null) {
-        limit = Number(limitParam);
-        if (!Number.isInteger(limit) || limit < 1 || limit > MAX_EVENTS_LIMIT) {
-            return sendJson(res, 400, {
-                error: `"limit" must be an integer from 1 to ${MAX_EVENTS_LIMIT}`,
-            });
-        }
-    }
-    const status = url.searchParams.get('status') ?? undefined;
-    if (status !== undefined && !OUTCOMES.has(status)) {
-        return sendJson(res, 400, { error: '"status" must be one of ok, tool_error, mcp_error' });
-    }
-    const tool = url.searchParams.get('tool') ?? undefined;
-    const client = url.searchParams.get('client') ?? undefined;
-    const filter = {
-        org: ref.org,
-        app: ref.app,
-        env: ref.env,
-        limit,
-        ...(status !== undefined ? { outcome: status } : {}),
-        ...(tool !== undefined ? { toolName: tool } : {}),
-        ...(client !== undefined ? { clientName: client } : {}),
-    };
+    const query = parseRequestEventQuery(url.searchParams, ref);
+    if (!query.ok)
+        return sendJson(res, 400, { error: query.error });
     // Store rejections surface as the dispatcher's 500 (validation above already handled 400s).
-    return sendJson(res, 200, { ok: true, events: await events.list(filter) });
+    return sendJson(res, 200, { ok: true, events: await events.list(query.filter) });
 }
 export async function handleTenantSession(req, res, gate, controlPlane, events, ref, sessionId, developerGrants) {
     const identity = await authorizeTenantControl(req, res, gate, controlPlane, ref.org, developerGrantRouteAccess(developerGrants, 'cloud:read'));