@dudousxd/nestjs-agent-dashboard 0.7.0 → 0.9.0

package/dist/server/index.d.cts

@@ -1,7 +1,7 @@
-import { ActorSpendRow, AgentGovernanceQueries, ActorDirectory, AgentPricingStore, AgentApprovalPort, GovernanceRange, ModelSpendRow, UsageTrendPoint, ThreadSpendRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, ToolCallActivityRow, PendingApprovalRow, ToolStatRow, ThreadActivityRow, CurrentModelPrice, ActorResolver, ModelPriceInput } from '@dudousxd/nestjs-agent-core';
+import { ActorSpendRow, AgentGovernanceQueries, ActorDirectory, AgentPricingStore, AgentApprovalPort, GovernanceRange, ModelSpendRow, UsageTrendPoint, ThreadSpendRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, ToolCallActivityRow, GovernancePageQuery, ToolCallWhere, GovernancePage, RunWhere, PendingApprovalRow, ToolStatRow, ThreadActivityRow, ThreadWhere, CurrentModelPrice, ActorResolver, ModelPriceInput } from '@dudousxd/nestjs-agent-core';
 export { ActorDirectory } from '@dudousxd/nestjs-agent-core';
 import { Observable } from 'rxjs';
-import { DynamicModule, Type, CanActivate, StreamableFile } from '@nestjs/common';
+import { DynamicModule, Type, CanActivate, Provider, InjectionToken, OptionalFactoryDependency, StreamableFile } from '@nestjs/common';
 
 /** An actor-scoped row decorated with its resolved display label — `null` when unbound or unresolved. */
 interface WithActorLabel {
@@ -61,6 +61,10 @@ declare class DashboardService {
     recentRuns(limit: number): Promise<RecentRunRow[]>;
     /** Most recent tool calls (status/type/thread) for the Runs & tools activity feed. */
     recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
+    /** Paged, filterable tool calls for the Runs & tools activity table. */
+    toolCallsPage(query: GovernancePageQuery<ToolCallWhere>): Promise<GovernancePage<ToolCallActivityRow>>;
+    /** Paged, filterable runs for the Reliability recent-runs table. */
+    runsPage(query: GovernancePageQuery<RunWhere>): Promise<GovernancePage<RecentRunRow>>;
     /** Tool calls sitting `pending_approval`, oldest first, for the cross-thread approvals inbox. */
     pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
     /** Per-tool call/failure/rejection/latency rollup for a day range, for the Tools section. */
@@ -76,6 +80,11 @@ declare class DashboardService {
     decideApproval(toolCallId: string, body: unknown, executedByRef: string | undefined): Promise<void>;
     /** Most recent threads with rolled-up message/token counts. */
     recentThreads(limit: number): Promise<ThreadActivityRowWithLabel[]>;
+    /**
+     * Paged, filterable threads for the Runs & tools threads table — actor-labeled the same way
+     * {@link recentThreads} is.
+     */
+    threadsPage(query: GovernancePageQuery<ThreadWhere>): Promise<GovernancePage<ThreadActivityRowWithLabel>>;
     /**
      * Decorate actor-scoped rows with `actorLabel`, batching the distinct `actorRef`s into ONE
      * {@link ActorDirectory.resolveDisplay} call per response. `null` for every row when no directory
@@ -103,6 +112,10 @@ declare class DashboardService {
 /**
  * JSON + SSE API consumed by the AI-gateway console SPA. Mounted at `apiBasePath` (set by
  * `RouterModule` in {@link AgentDashboardModule.forRoot}), so the controller routes are relative.
+ *
+ * `@UseGuards(DashboardAuthGuard)` is a NO-OP unless the host configured `dashboardAuth` — see
+ * that guard's own doc. Host `guards` (see {@link AgentDashboardOptions.guards}) are APPENDED onto
+ * this baseline by `stampGuards` (`./guards.js`), never replacing it.
  */
 declare class AgentApiController {
     private readonly dashboard;
@@ -117,8 +130,20 @@ declare class AgentApiController {
     reliability(from?: string, to?: string): Promise<ReliabilityOverview>;
     /** Most recent runs (default 50, max 200) for the Reliability recent-runs table. */
     runs(limit?: string): Promise<RecentRunRow[]>;
+    /**
+     * Paged, filterable runs for the Reliability recent-runs table. `page` (default 1), `limit`
+     * (default 25, max 200), and `where[agentName]`/`where[status]`/`where[errorCode]`/
+     * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
+     */
+    runsPage(page?: string, limit?: string, where?: Record<string, string>): Promise<GovernancePage<RecentRunRow>>;
     /** Most recent tool calls (default 50, max 200) for the activity feed. */
     toolCalls(limit?: string): Promise<ToolCallActivityRow[]>;
+    /**
+     * Paged, filterable tool calls for the Runs & tools activity table. `page` (default 1), `limit`
+     * (default 25, max 200), and `where[toolName]`/`where[toolType]`/`where[status]`/`where[threadId]`/
+     * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
+     */
+    toolCallsPage(page?: string, limit?: string, where?: Record<string, string>): Promise<GovernancePage<ToolCallActivityRow>>;
     /** Tool calls sitting `pending_approval` (default 50, max 200), oldest first — the approvals inbox. */
     approvals(limit?: string): Promise<PendingApprovalRow[]>;
     /**
@@ -139,6 +164,12 @@ declare class AgentApiController {
     tools(from?: string, to?: string): Promise<ToolStatRow[]>;
     /** Most recent threads (default 50, max 200) with rolled-up counts. */
     threads(limit?: string): Promise<ThreadActivityRowWithLabel[]>;
+    /**
+     * Paged, filterable threads for the Runs & tools threads table. `page` (default 1), `limit`
+     * (default 25, max 200), and `where[actorRef]`/`where[title]` (case-insensitive substring)/
+     * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
+     */
+    threadsPage(page?: string, limit?: string, where?: Record<string, string>): Promise<GovernancePage<ThreadActivityRowWithLabel>>;
     /**
      * Current price row per model, for the pricing tab. 501s (via `DashboardService.listPrices`) when
      * no `AGENT_PRICING_STORE` is bound.
@@ -156,6 +187,96 @@ declare class AgentApiController {
     }>;
 }
 
+/** The session user the host's `login` hook returns to mint a cookie. */
+interface DashboardSessionUser {
+    id: string;
+    name?: string;
+    roles?: string[];
+}
+
+/** Host hook: validates submitted credentials for the built-in login screen. */
+type LoginHook = (username: string, password: string) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
+/**
+ * Author-facing `dashboardAuth` option (see `AgentDashboardOptions.dashboardAuth`). Gates the
+ * console (SPA + API) behind a built-in cookie-session login screen — no host frontend changes,
+ * no SSO required. Mirrors `@dudousxd/nestjs-telescope`'s `dashboardAuth` Mode B (`login`).
+ */
+interface DashboardAuthOptions {
+    /** REQUIRED HMAC-SHA256 signing key (32+ bytes recommended). Missing/empty => boot error (fail closed). */
+    secret: string;
+    /** Cookie TTL (duration string `'<n><ms|s|m|h|d>'`, e.g. `'30m'`, `'7d'`). Default `'8h'`. */
+    ttl?: string;
+    /**
+     * Validates submitted username/password. Return the session user to grant access, or `null` to
+     * deny — the login endpoint responds identically (generic failure) for an unknown user and a
+     * wrong password, so it never reveals which one was wrong.
+     */
+    login: LoginHook;
+}
+/** Resolved, validated `dashboardAuth` config used by the guards/controller. */
+interface ResolvedDashboardAuth {
+    secret: string;
+    ttlMs: number;
+    login: LoginHook;
+}
+/**
+ * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
+ * console stays open, front it with your own `guards`). Throws at boot (fail closed) when
+ * configured but missing a secret or a `login` hook — the host learns immediately rather than
+ * shipping an open or un-mintable console.
+ */
+declare function resolveDashboardAuth(options: DashboardAuthOptions | undefined): ResolvedDashboardAuth | null;
+
+/** The slice of the platform request this controller reads — structural, no Express/Fastify dependency. */
+interface AuthPageRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+/** The slice of the platform response this controller writes (passthrough mode — Nest still sends). */
+interface AuthPageResponse {
+    status(code: number): unknown;
+    setHeader(name: string, value: string): unknown;
+}
+interface LoginFormBody {
+    username?: unknown;
+    password?: unknown;
+    returnTo?: unknown;
+}
+/**
+ * Mounted directly on `AgentDashboardModule` at `<basePath>/auth/*` — a SEPARATE controller from
+ * `AgentUiController`/`AgentApiController` so it carries neither `DashboardAuthPageGuard`,
+ * `DashboardAuthGuard`, nor any host `guards`: these routes MINT (and clear) the session cookie the
+ * built-in gates check for, so they can never be made to require the very auth they grant. Mirrors
+ * `@dudousxd/nestjs-telescope`'s own auth controller staying outside its `stampGuards` call.
+ *
+ * A dependency-free, server-rendered login form (GET/POST) rather than a JSON API + client-side
+ * screen — the bundled React SPA in this package is a built Vite artifact with no auth-aware UI of
+ * its own, so gating the actual page navigation needs a self-contained flow that doesn't touch it.
+ *
+ * 404s every route when `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to `null`) — no
+ * dangling login page when the feature is off.
+ */
+declare class AgentDashboardAuthController {
+    private readonly auth;
+    private readonly basePath;
+    private readonly logger;
+    /** Warn once (not per request) so a broken hook can't be used to flood the logs. */
+    private warnedLoginHookThrow;
+    constructor(auth: ResolvedDashboardAuth | null, basePath: string);
+    loginPage(req: AuthPageRequest, res: AuthPageResponse, returnToQuery?: string, error?: string): string;
+    login(body: LoginFormBody, req: unknown, res: AuthPageResponse): Promise<string>;
+    logout(req: unknown, res: AuthPageResponse): string;
+    /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
+    private redirectToLoginError;
+    private currentSession;
+    /**
+     * Run the host's `login` hook defensively: a throw (sync or async) is treated as a denial
+     * (`null`) and warn-logged ONCE, so a buggy/unreachable hook never 500s the endpoint into a
+     * stack-trace leak nor floods the logs.
+     */
+    private runLoginHook;
+    private requireAuth;
+}
+
 /** Same shape {@link AgentDashboardModule.forRoot} accepts — kept local so this stays a pure, DI-free helper. */
 interface AgentDashboardMountPathsOptions {
     basePath?: string;
@@ -207,10 +328,9 @@ interface AgentDashboardOptions<TReq = unknown> {
     apiBasePath?: string;
     /**
      * Guard classes fronting BOTH dashboard controllers (the SPA at `basePath` and its JSON API at
-     * `apiBasePath`). Stamped onto each controller via `@nestjs/common`'s own `@UseGuards` metadata key
-     * — REPLACE semantics, so a second `forRoot(...)` call overwrites (not appends to) whatever a prior
-     * call stamped, same as re-applying `@UseGuards` by hand. Omit to leave the routes unguarded (the
-     * host fronts them another way, e.g. a global guard or reverse-proxy auth).
+     * `apiBasePath`) — APPENDED onto the built-in `dashboardAuth` gate (a no-op unless configured;
+     * see {@link dashboardAuth}), so a request must pass BOTH. Omit to leave the routes gated by
+     * `dashboardAuth` alone (or fully open when that's unset too).
      *
      * A guard's own DEPENDENCIES resolve from this module's `imports` (see {@link imports}) — the
      * dashboard module has no application context of its own to pull them from otherwise.
@@ -234,6 +354,36 @@ interface AgentDashboardOptions<TReq = unknown> {
      * override wins outright, with no resolver fallback.
      */
     approvalActorRef?: (req: TReq) => string | undefined;
+    /**
+     * Gate the console (SPA + API) behind a BUILT-IN cookie-session login screen — the simplest way
+     * to protect `basePath` when the host has no ready-made guard (e.g. header-only auth that a
+     * browser navigation can't attach). Omit to leave the console open, or fronted only by
+     * {@link guards}. When set, an unauthenticated page navigation is redirected (302) to
+     * `<basePath>/auth/login`; an unauthenticated API call gets a `401`. Composes with `guards` —
+     * BOTH gates must pass. See `DashboardAuthOptions` for the `secret`/`ttl`/`login` shape.
+     */
+    dashboardAuth?: DashboardAuthOptions;
+}
+/**
+ * Async variant of {@link AgentDashboardOptions}, for a `login` hook that needs injected services
+ * (e.g. an EntityManager to check credentials against a DB). Everything else stays static/sync —
+ * `basePath`/`apiBasePath`/`guards` are needed at module-build time (the same constraint
+ * `@dudousxd/nestjs-telescope`'s and `@dudousxd/nestjs-media`'s own `forRootAsync`s document), so
+ * only the auth piece itself is resolved through DI.
+ */
+interface AgentDashboardAsyncOptions<TReq = unknown> {
+    basePath?: string;
+    apiBasePath?: string;
+    guards?: Type<CanActivate>[];
+    imports?: DynamicModule['imports'];
+    approvalActorRef?: (req: TReq) => string | undefined;
+    /** Providers injected into `useDashboardAuth`, in order. Shared with a guard class's own deps via `imports`. */
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    /**
+     * Build the `dashboardAuth` config from injected deps, or return `undefined` to leave the
+     * console open (or fronted only by `guards`). See {@link AgentDashboardOptions.dashboardAuth}.
+     */
+    useDashboardAuth: (...deps: any[]) => DashboardAuthOptions | undefined | Promise<DashboardAuthOptions | undefined>;
 }
 /**
  * Holds the JSON API + SSE controller and its read service, mounted on its own path by `forRoot`.
@@ -248,16 +398,19 @@ declare class AgentApiModule {
         imports?: DynamicModule['imports'];
         guards?: Type<CanActivate>[];
         approvalActorRef?: (req: TReq) => string | undefined;
+        /** Provider for `DASHBOARD_AUTH` — a `useValue` (`forRoot`) or a `useFactory` (`forRootAsync`). */
+        dashboardAuth: Provider;
     }): DynamicModule;
 }
 /**
  * Mounts the AI-gateway governance console: the bundled React SPA at `basePath` and its JSON + SSE
- * API at `apiBasePath` (default `<basePath>/api`).
+ * API at `apiBasePath` (default `<basePath>/api`), plus the built-in login screen's routes at
+ * `<basePath>/auth/*` when {@link AgentDashboardOptions.dashboardAuth} is set.
  *
  * Import via `AgentDashboardModule.forRoot(...)` alongside your `@dudousxd/nestjs-agent` module
  * (global), which must provide `AGENT_GOVERNANCE_QUERIES` (bound by a store adapter). Front the
  * routes with the first-class `guards` option (plus `imports` for the guards' own dependencies) —
- * see {@link AgentDashboardOptions.guards}.
+ * see {@link AgentDashboardOptions.guards} — and/or the built-in `dashboardAuth` cookie login.
  *
  * Inertia hosts: the console is a full-page app, not an Inertia page. An in-app `<Link>` visit to
  * `basePath` (an XHR carrying `X-Inertia`) is bounced with the protocol's own external-redirect
@@ -267,6 +420,7 @@ declare class AgentApiModule {
  */
 declare class AgentDashboardModule {
     static forRoot<TReq = unknown>(options?: AgentDashboardOptions<TReq>): DynamicModule;
+    static forRootAsync<TReq = unknown>(options: AgentDashboardAsyncOptions<TReq>): DynamicModule;
 }
 
 /**
@@ -287,6 +441,12 @@ interface UiPageResponse {
  * Serves the bundled AI-gateway console SPA at the configured base (+ hashed assets at
  * `<base>/assets`). The path comes from `RouterModule` (set by
  * {@link AgentDashboardModule.forRoot}({ basePath })), so the controller routes are relative.
+ *
+ * `@UseGuards(DashboardAuthPageGuard)` is a NO-OP unless the host configured `dashboardAuth` — see
+ * that guard's own doc. Host `guards` (see {@link AgentDashboardOptions.guards}) are APPENDED onto
+ * this baseline by `stampGuards` (`./guards.js`), never replacing it. `@UseFilters` turns the
+ * guard's redirect-on-deny into an actual 302 response; it is a no-op when the guard never throws
+ * (i.e. `dashboardAuth` unconfigured).
  */
 declare class AgentUiController {
     private readonly basePath;
@@ -361,5 +521,13 @@ declare const DASHBOARD_API_PATH: unique symbol;
  * `@dudousxd/nestjs-agent`).
  */
 declare const DASHBOARD_APPROVAL_ACTOR_REF: unique symbol;
+/**
+ * DI token carrying the resolved `dashboardAuth` config (`ResolvedDashboardAuth | null`) — `null`
+ * when the host didn't configure it (the built-in guards are then a no-op, today's behavior
+ * byte-for-byte). Bound once by `AgentApiModule.register` and re-exported so `AgentUiController`
+ * and `AgentDashboardAuthController` (hosted directly by `AgentDashboardModule`, which imports
+ * `AgentApiModule`) resolve the SAME instance rather than re-running a host's async factory twice.
+ */
+declare const DASHBOARD_AUTH: unique symbol;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_BASE_PATH, DashboardService, type LiveAgentEvent, type ReliabilityOverview, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, type AgentDashboardAsyncOptions, AgentDashboardAuthController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_AUTH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type LiveAgentEvent, type LoginHook, type ReliabilityOverview, type ResolvedDashboardAuth, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
-import { ActorSpendRow, AgentGovernanceQueries, ActorDirectory, AgentPricingStore, AgentApprovalPort, GovernanceRange, ModelSpendRow, UsageTrendPoint, ThreadSpendRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, ToolCallActivityRow, PendingApprovalRow, ToolStatRow, ThreadActivityRow, CurrentModelPrice, ActorResolver, ModelPriceInput } from '@dudousxd/nestjs-agent-core';
+import { ActorSpendRow, AgentGovernanceQueries, ActorDirectory, AgentPricingStore, AgentApprovalPort, GovernanceRange, ModelSpendRow, UsageTrendPoint, ThreadSpendRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, ToolCallActivityRow, GovernancePageQuery, ToolCallWhere, GovernancePage, RunWhere, PendingApprovalRow, ToolStatRow, ThreadActivityRow, ThreadWhere, CurrentModelPrice, ActorResolver, ModelPriceInput } from '@dudousxd/nestjs-agent-core';
 export { ActorDirectory } from '@dudousxd/nestjs-agent-core';
 import { Observable } from 'rxjs';
-import { DynamicModule, Type, CanActivate, StreamableFile } from '@nestjs/common';
+import { DynamicModule, Type, CanActivate, Provider, InjectionToken, OptionalFactoryDependency, StreamableFile } from '@nestjs/common';
 
 /** An actor-scoped row decorated with its resolved display label — `null` when unbound or unresolved. */
 interface WithActorLabel {
@@ -61,6 +61,10 @@ declare class DashboardService {
     recentRuns(limit: number): Promise<RecentRunRow[]>;
     /** Most recent tool calls (status/type/thread) for the Runs & tools activity feed. */
     recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
+    /** Paged, filterable tool calls for the Runs & tools activity table. */
+    toolCallsPage(query: GovernancePageQuery<ToolCallWhere>): Promise<GovernancePage<ToolCallActivityRow>>;
+    /** Paged, filterable runs for the Reliability recent-runs table. */
+    runsPage(query: GovernancePageQuery<RunWhere>): Promise<GovernancePage<RecentRunRow>>;
     /** Tool calls sitting `pending_approval`, oldest first, for the cross-thread approvals inbox. */
     pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
     /** Per-tool call/failure/rejection/latency rollup for a day range, for the Tools section. */
@@ -76,6 +80,11 @@ declare class DashboardService {
     decideApproval(toolCallId: string, body: unknown, executedByRef: string | undefined): Promise<void>;
     /** Most recent threads with rolled-up message/token counts. */
     recentThreads(limit: number): Promise<ThreadActivityRowWithLabel[]>;
+    /**
+     * Paged, filterable threads for the Runs & tools threads table — actor-labeled the same way
+     * {@link recentThreads} is.
+     */
+    threadsPage(query: GovernancePageQuery<ThreadWhere>): Promise<GovernancePage<ThreadActivityRowWithLabel>>;
     /**
      * Decorate actor-scoped rows with `actorLabel`, batching the distinct `actorRef`s into ONE
      * {@link ActorDirectory.resolveDisplay} call per response. `null` for every row when no directory
@@ -103,6 +112,10 @@ declare class DashboardService {
 /**
  * JSON + SSE API consumed by the AI-gateway console SPA. Mounted at `apiBasePath` (set by
  * `RouterModule` in {@link AgentDashboardModule.forRoot}), so the controller routes are relative.
+ *
+ * `@UseGuards(DashboardAuthGuard)` is a NO-OP unless the host configured `dashboardAuth` — see
+ * that guard's own doc. Host `guards` (see {@link AgentDashboardOptions.guards}) are APPENDED onto
+ * this baseline by `stampGuards` (`./guards.js`), never replacing it.
  */
 declare class AgentApiController {
     private readonly dashboard;
@@ -117,8 +130,20 @@ declare class AgentApiController {
     reliability(from?: string, to?: string): Promise<ReliabilityOverview>;
     /** Most recent runs (default 50, max 200) for the Reliability recent-runs table. */
     runs(limit?: string): Promise<RecentRunRow[]>;
+    /**
+     * Paged, filterable runs for the Reliability recent-runs table. `page` (default 1), `limit`
+     * (default 25, max 200), and `where[agentName]`/`where[status]`/`where[errorCode]`/
+     * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
+     */
+    runsPage(page?: string, limit?: string, where?: Record<string, string>): Promise<GovernancePage<RecentRunRow>>;
     /** Most recent tool calls (default 50, max 200) for the activity feed. */
     toolCalls(limit?: string): Promise<ToolCallActivityRow[]>;
+    /**
+     * Paged, filterable tool calls for the Runs & tools activity table. `page` (default 1), `limit`
+     * (default 25, max 200), and `where[toolName]`/`where[toolType]`/`where[status]`/`where[threadId]`/
+     * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
+     */
+    toolCallsPage(page?: string, limit?: string, where?: Record<string, string>): Promise<GovernancePage<ToolCallActivityRow>>;
     /** Tool calls sitting `pending_approval` (default 50, max 200), oldest first — the approvals inbox. */
     approvals(limit?: string): Promise<PendingApprovalRow[]>;
     /**
@@ -139,6 +164,12 @@ declare class AgentApiController {
     tools(from?: string, to?: string): Promise<ToolStatRow[]>;
     /** Most recent threads (default 50, max 200) with rolled-up counts. */
     threads(limit?: string): Promise<ThreadActivityRowWithLabel[]>;
+    /**
+     * Paged, filterable threads for the Runs & tools threads table. `page` (default 1), `limit`
+     * (default 25, max 200), and `where[actorRef]`/`where[title]` (case-insensitive substring)/
+     * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
+     */
+    threadsPage(page?: string, limit?: string, where?: Record<string, string>): Promise<GovernancePage<ThreadActivityRowWithLabel>>;
     /**
      * Current price row per model, for the pricing tab. 501s (via `DashboardService.listPrices`) when
      * no `AGENT_PRICING_STORE` is bound.
@@ -156,6 +187,96 @@ declare class AgentApiController {
     }>;
 }
 
+/** The session user the host's `login` hook returns to mint a cookie. */
+interface DashboardSessionUser {
+    id: string;
+    name?: string;
+    roles?: string[];
+}
+
+/** Host hook: validates submitted credentials for the built-in login screen. */
+type LoginHook = (username: string, password: string) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
+/**
+ * Author-facing `dashboardAuth` option (see `AgentDashboardOptions.dashboardAuth`). Gates the
+ * console (SPA + API) behind a built-in cookie-session login screen — no host frontend changes,
+ * no SSO required. Mirrors `@dudousxd/nestjs-telescope`'s `dashboardAuth` Mode B (`login`).
+ */
+interface DashboardAuthOptions {
+    /** REQUIRED HMAC-SHA256 signing key (32+ bytes recommended). Missing/empty => boot error (fail closed). */
+    secret: string;
+    /** Cookie TTL (duration string `'<n><ms|s|m|h|d>'`, e.g. `'30m'`, `'7d'`). Default `'8h'`. */
+    ttl?: string;
+    /**
+     * Validates submitted username/password. Return the session user to grant access, or `null` to
+     * deny — the login endpoint responds identically (generic failure) for an unknown user and a
+     * wrong password, so it never reveals which one was wrong.
+     */
+    login: LoginHook;
+}
+/** Resolved, validated `dashboardAuth` config used by the guards/controller. */
+interface ResolvedDashboardAuth {
+    secret: string;
+    ttlMs: number;
+    login: LoginHook;
+}
+/**
+ * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
+ * console stays open, front it with your own `guards`). Throws at boot (fail closed) when
+ * configured but missing a secret or a `login` hook — the host learns immediately rather than
+ * shipping an open or un-mintable console.
+ */
+declare function resolveDashboardAuth(options: DashboardAuthOptions | undefined): ResolvedDashboardAuth | null;
+
+/** The slice of the platform request this controller reads — structural, no Express/Fastify dependency. */
+interface AuthPageRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+/** The slice of the platform response this controller writes (passthrough mode — Nest still sends). */
+interface AuthPageResponse {
+    status(code: number): unknown;
+    setHeader(name: string, value: string): unknown;
+}
+interface LoginFormBody {
+    username?: unknown;
+    password?: unknown;
+    returnTo?: unknown;
+}
+/**
+ * Mounted directly on `AgentDashboardModule` at `<basePath>/auth/*` — a SEPARATE controller from
+ * `AgentUiController`/`AgentApiController` so it carries neither `DashboardAuthPageGuard`,
+ * `DashboardAuthGuard`, nor any host `guards`: these routes MINT (and clear) the session cookie the
+ * built-in gates check for, so they can never be made to require the very auth they grant. Mirrors
+ * `@dudousxd/nestjs-telescope`'s own auth controller staying outside its `stampGuards` call.
+ *
+ * A dependency-free, server-rendered login form (GET/POST) rather than a JSON API + client-side
+ * screen — the bundled React SPA in this package is a built Vite artifact with no auth-aware UI of
+ * its own, so gating the actual page navigation needs a self-contained flow that doesn't touch it.
+ *
+ * 404s every route when `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to `null`) — no
+ * dangling login page when the feature is off.
+ */
+declare class AgentDashboardAuthController {
+    private readonly auth;
+    private readonly basePath;
+    private readonly logger;
+    /** Warn once (not per request) so a broken hook can't be used to flood the logs. */
+    private warnedLoginHookThrow;
+    constructor(auth: ResolvedDashboardAuth | null, basePath: string);
+    loginPage(req: AuthPageRequest, res: AuthPageResponse, returnToQuery?: string, error?: string): string;
+    login(body: LoginFormBody, req: unknown, res: AuthPageResponse): Promise<string>;
+    logout(req: unknown, res: AuthPageResponse): string;
+    /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
+    private redirectToLoginError;
+    private currentSession;
+    /**
+     * Run the host's `login` hook defensively: a throw (sync or async) is treated as a denial
+     * (`null`) and warn-logged ONCE, so a buggy/unreachable hook never 500s the endpoint into a
+     * stack-trace leak nor floods the logs.
+     */
+    private runLoginHook;
+    private requireAuth;
+}
+
 /** Same shape {@link AgentDashboardModule.forRoot} accepts — kept local so this stays a pure, DI-free helper. */
 interface AgentDashboardMountPathsOptions {
     basePath?: string;
@@ -207,10 +328,9 @@ interface AgentDashboardOptions<TReq = unknown> {
     apiBasePath?: string;
     /**
      * Guard classes fronting BOTH dashboard controllers (the SPA at `basePath` and its JSON API at
-     * `apiBasePath`). Stamped onto each controller via `@nestjs/common`'s own `@UseGuards` metadata key
-     * — REPLACE semantics, so a second `forRoot(...)` call overwrites (not appends to) whatever a prior
-     * call stamped, same as re-applying `@UseGuards` by hand. Omit to leave the routes unguarded (the
-     * host fronts them another way, e.g. a global guard or reverse-proxy auth).
+     * `apiBasePath`) — APPENDED onto the built-in `dashboardAuth` gate (a no-op unless configured;
+     * see {@link dashboardAuth}), so a request must pass BOTH. Omit to leave the routes gated by
+     * `dashboardAuth` alone (or fully open when that's unset too).
      *
      * A guard's own DEPENDENCIES resolve from this module's `imports` (see {@link imports}) — the
      * dashboard module has no application context of its own to pull them from otherwise.
@@ -234,6 +354,36 @@ interface AgentDashboardOptions<TReq = unknown> {
      * override wins outright, with no resolver fallback.
      */
     approvalActorRef?: (req: TReq) => string | undefined;
+    /**
+     * Gate the console (SPA + API) behind a BUILT-IN cookie-session login screen — the simplest way
+     * to protect `basePath` when the host has no ready-made guard (e.g. header-only auth that a
+     * browser navigation can't attach). Omit to leave the console open, or fronted only by
+     * {@link guards}. When set, an unauthenticated page navigation is redirected (302) to
+     * `<basePath>/auth/login`; an unauthenticated API call gets a `401`. Composes with `guards` —
+     * BOTH gates must pass. See `DashboardAuthOptions` for the `secret`/`ttl`/`login` shape.
+     */
+    dashboardAuth?: DashboardAuthOptions;
+}
+/**
+ * Async variant of {@link AgentDashboardOptions}, for a `login` hook that needs injected services
+ * (e.g. an EntityManager to check credentials against a DB). Everything else stays static/sync —
+ * `basePath`/`apiBasePath`/`guards` are needed at module-build time (the same constraint
+ * `@dudousxd/nestjs-telescope`'s and `@dudousxd/nestjs-media`'s own `forRootAsync`s document), so
+ * only the auth piece itself is resolved through DI.
+ */
+interface AgentDashboardAsyncOptions<TReq = unknown> {
+    basePath?: string;
+    apiBasePath?: string;
+    guards?: Type<CanActivate>[];
+    imports?: DynamicModule['imports'];
+    approvalActorRef?: (req: TReq) => string | undefined;
+    /** Providers injected into `useDashboardAuth`, in order. Shared with a guard class's own deps via `imports`. */
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    /**
+     * Build the `dashboardAuth` config from injected deps, or return `undefined` to leave the
+     * console open (or fronted only by `guards`). See {@link AgentDashboardOptions.dashboardAuth}.
+     */
+    useDashboardAuth: (...deps: any[]) => DashboardAuthOptions | undefined | Promise<DashboardAuthOptions | undefined>;
 }
 /**
  * Holds the JSON API + SSE controller and its read service, mounted on its own path by `forRoot`.
@@ -248,16 +398,19 @@ declare class AgentApiModule {
         imports?: DynamicModule['imports'];
         guards?: Type<CanActivate>[];
         approvalActorRef?: (req: TReq) => string | undefined;
+        /** Provider for `DASHBOARD_AUTH` — a `useValue` (`forRoot`) or a `useFactory` (`forRootAsync`). */
+        dashboardAuth: Provider;
     }): DynamicModule;
 }
 /**
  * Mounts the AI-gateway governance console: the bundled React SPA at `basePath` and its JSON + SSE
- * API at `apiBasePath` (default `<basePath>/api`).
+ * API at `apiBasePath` (default `<basePath>/api`), plus the built-in login screen's routes at
+ * `<basePath>/auth/*` when {@link AgentDashboardOptions.dashboardAuth} is set.
  *
  * Import via `AgentDashboardModule.forRoot(...)` alongside your `@dudousxd/nestjs-agent` module
  * (global), which must provide `AGENT_GOVERNANCE_QUERIES` (bound by a store adapter). Front the
  * routes with the first-class `guards` option (plus `imports` for the guards' own dependencies) —
- * see {@link AgentDashboardOptions.guards}.
+ * see {@link AgentDashboardOptions.guards} — and/or the built-in `dashboardAuth` cookie login.
  *
  * Inertia hosts: the console is a full-page app, not an Inertia page. An in-app `<Link>` visit to
  * `basePath` (an XHR carrying `X-Inertia`) is bounced with the protocol's own external-redirect
@@ -267,6 +420,7 @@ declare class AgentApiModule {
  */
 declare class AgentDashboardModule {
     static forRoot<TReq = unknown>(options?: AgentDashboardOptions<TReq>): DynamicModule;
+    static forRootAsync<TReq = unknown>(options: AgentDashboardAsyncOptions<TReq>): DynamicModule;
 }
 
 /**
@@ -287,6 +441,12 @@ interface UiPageResponse {
  * Serves the bundled AI-gateway console SPA at the configured base (+ hashed assets at
  * `<base>/assets`). The path comes from `RouterModule` (set by
  * {@link AgentDashboardModule.forRoot}({ basePath })), so the controller routes are relative.
+ *
+ * `@UseGuards(DashboardAuthPageGuard)` is a NO-OP unless the host configured `dashboardAuth` — see
+ * that guard's own doc. Host `guards` (see {@link AgentDashboardOptions.guards}) are APPENDED onto
+ * this baseline by `stampGuards` (`./guards.js`), never replacing it. `@UseFilters` turns the
+ * guard's redirect-on-deny into an actual 302 response; it is a no-op when the guard never throws
+ * (i.e. `dashboardAuth` unconfigured).
  */
 declare class AgentUiController {
     private readonly basePath;
@@ -361,5 +521,13 @@ declare const DASHBOARD_API_PATH: unique symbol;
  * `@dudousxd/nestjs-agent`).
  */
 declare const DASHBOARD_APPROVAL_ACTOR_REF: unique symbol;
+/**
+ * DI token carrying the resolved `dashboardAuth` config (`ResolvedDashboardAuth | null`) — `null`
+ * when the host didn't configure it (the built-in guards are then a no-op, today's behavior
+ * byte-for-byte). Bound once by `AgentApiModule.register` and re-exported so `AgentUiController`
+ * and `AgentDashboardAuthController` (hosted directly by `AgentDashboardModule`, which imports
+ * `AgentApiModule`) resolve the SAME instance rather than re-running a host's async factory twice.
+ */
+declare const DASHBOARD_AUTH: unique symbol;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_BASE_PATH, DashboardService, type LiveAgentEvent, type ReliabilityOverview, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, type AgentDashboardAsyncOptions, AgentDashboardAuthController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_AUTH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type LiveAgentEvent, type LoginHook, type ReliabilityOverview, type ResolvedDashboardAuth, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };