@dudousxd/nestjs-agent-dashboard 0.19.1 → 0.21.0

package/dist/server/index.d.cts

@@ -1,7 +1,8 @@
 import { ActorSpendRow, AgentGovernanceQueries, ActorDirectory, AgentPricingStore, AgentApprovalPort, GovernanceRange, ModelSpendRow, UsageTrendPoint, FeatureSpendRow, ThreadSpendRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, ToolCallActivityRow, GovernancePageQuery, ToolCallWhere, GovernancePage, RunWhere, PendingApprovalRow, ApprovalWhere, GovernanceRunDetail, GovernanceThreadDetailQuery, GovernanceThreadDetail, ThreadActivityRow, ToolStatRow, GenuiStats, ThreadWhere, CurrentModelPrice, ActorResolver, ModelPriceInput } from '@dudousxd/nestjs-agent-core';
 export { ActorDirectory } from '@dudousxd/nestjs-agent-core';
 import { Observable } from 'rxjs';
-import { DynamicModule, StreamableFile } from '@nestjs/common';
+import { ExecutionContext, Type, Logger, DynamicModule, StreamableFile, OnModuleInit, HttpException, ExceptionFilter, ArgumentsHost, CanActivate, OnModuleDestroy } from '@nestjs/common';
+import { ModuleRef, HttpAdapterHost } from '@nestjs/core';
 
 /** An actor-scoped row decorated with its resolved display label — `null` when unbound or unresolved. */
 interface WithActorLabel {
@@ -151,8 +152,9 @@ 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.
  *
- * Who reaches it is the app's: `decorators` on `AgentDashboardModule.forRoot`, or the app mounts it
- * itself (`routes: false`) — with `@nestjs/authentication` / `@nestjs/authorization`.
+ * Who reaches it: `authorize` on `AgentDashboardModule.forRoot` (checked by `ConsoleAuthorizeGuard`,
+ * after the app's `decorators`). Mounted by the app itself (`routes: false`), apply
+ * `UseConsoleAuthorize()` to your subclass.
  */
 declare class AgentApiController {
     private readonly dashboard;
@@ -293,6 +295,90 @@ interface AgentDashboardMountPathsOptions {
  */
 declare function agentDashboardMountPaths(options?: AgentDashboardMountPathsOptions): string[];
 
+/**
+ * What an `authorize` check answers. An allow may name who it let in (`caller`, for example
+ * `'user:42'`): the dev MCP endpoint logs it as the caller of a developer tool. Never put a secret
+ * in it.
+ */
+type ConsoleAuthorizeResult = boolean | {
+    allowed: true;
+    caller?: string;
+} | {
+    allowed: false;
+    reason?: 'unauthenticated' | 'forbidden';
+} | {
+    redirectTo: string;
+};
+/** Class form: an @Injectable() provider (constructor injection works). */
+interface ConsoleAuthorizer {
+    authorize(context: ExecutionContext): ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>;
+}
+type ConsoleAuthorizerClass = Type<ConsoleAuthorizer>;
+/** @nestjs/authorization policy check: policy[ability](user). */
+interface ConsolePolicyCheck {
+    policy: Type<unknown>;
+    ability: string;
+}
+/** Who reaches the console. */
+type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>) | ConsoleAuthorizerClass | (() => Promise<{
+    default: ConsoleAuthorizerClass;
+}>) | ConsolePolicyCheck | string;
+/** A normalized `authorize` answer. */
+type ConsoleDecision = {
+    allowed: true;
+    caller?: string;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+};
+/** What a resolved `authorize` is: called once per request, never throws. */
+type ConsoleDecide = (context: ExecutionContext) => Promise<ConsoleDecision>;
+/**
+ * The provider that resolves gate names (`authorize: 'console.agent'`), bound globally by
+ * `@dudousxd/nestjs-authz`'s `AuthzModule`. A registry symbol, so it is found without depending on
+ * that package.
+ */
+declare const CONSOLE_GATE: unique symbol;
+interface ConsoleGate {
+    allows(name: string, context: ExecutionContext): Promise<ConsoleAuthorizeResult>;
+}
+/** The one boot warning for a console with no `authorize`. Same wording in every Aviary console. */
+declare const CONSOLE_AUTHORIZE_MISSING_WARNING = "[@dudousxd/nestjs-agent-dashboard] console has no `authorize` configured: it is open outside production and denies every request in production. Set `authorize` in AgentDashboardModule.forRoot().";
+/** Turns any {@link ConsoleAuthorizeResult} into a {@link ConsoleDecision}. */
+declare function normalizeConsoleResult(result: unknown): ConsoleDecision;
+/**
+ * Resolves `authorize` into one function the guard calls per request. Configuration mistakes (a
+ * gate name without nestjs-authz, a policy without `@nestjs/authorization`) throw here, so call it
+ * at boot. The returned function never throws: an error is a `forbidden`.
+ *
+ * `authorize` omitted: open outside production, `forbidden` for every request in production (read
+ * when this runs), and one warning logged (unless `warnIfMissing: false`).
+ */
+declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined, moduleRef: ModuleRef, options?: {
+    logger?: Logger;
+    warnIfMissing?: boolean;
+}): Promise<ConsoleDecide>;
+/**
+ * `authorize` by a bearer token: allows when `Authorization: Bearer <token>` matches (compared in
+ * constant time), else `unauthenticated`. Header only. An empty token throws here, at config time.
+ * The allow names its caller `token:<first 12 hex of sha256(token)>`, never the token.
+ */
+declare function authorizeByToken(options: {
+    token: string | undefined;
+}): (context: ExecutionContext) => ConsoleAuthorizeResult;
+/**
+ * One `authorize` from several: allowed when any form allows (checked in order, stopping at the
+ * first that does, whose `caller` it keeps); otherwise `unauthenticated` when any form said so (keeping the first
+ * `redirectTo`), else `forbidden`. Each form is any `authorize` value: a function, a class, a lazy
+ * import, `{ policy, ability }` or a gate name.
+ *
+ * ```ts
+ * authorize: anyAuthorize(authorizeByToken({ token: process.env.CONSOLE_TOKEN }), AdminSessionAuthorizer)
+ * ```
+ */
+declare function anyAuthorize(...forms: ConsoleAuthorize[]): ConsoleAuthorizerClass;
+
 /**
  * `TReq` mirrors core's `ActorResolver<TReq>` convention: the transport request type
  * {@link AgentDashboardOptions.approvalActorRef} receives. Defaults to `unknown`.
@@ -310,23 +396,28 @@ interface AgentDashboardOptions<TReq = unknown> {
      */
     apiBasePath?: string;
     /**
-     * Who reaches the console: class decorators applied to every controller this module mounts — the
-     * ecosystem's convention, like `@nestjs/mcp`'s `decorators` — with the official tools, e.g.
-     * `[UseGuards(AuthenticationGuard), Can(ConsolePolicy, 'view')]` from `@nestjs/authentication` /
-     * `@nestjs/authorization`, or a function as a guard instance, `UseGuards({ canActivate })`.
-     * Applied to a per-registration subclass, so nothing sticks to the shared classes.
+     * Who reaches the console (the SPA and every API/SSE route): an inline function
+     * `(ctx) => boolean | { allowed } | { redirectTo }`, an `@Injectable()` `ConsoleAuthorizer` class,
+     * a lazy import of one, `{ policy, ability }` (`@nestjs/authorization`), or a gate name
+     * (`@dudousxd/nestjs-authz`). `authorizeByToken({ token })` checks a bearer token.
      *
-     * In production (`NODE_ENV=production`) the console refuses to boot without them, unless the app
-     * mounts the routes itself (`routes: false`): a governance console is never served open there by
-     * default. Outside production the routes are open (and to `@nestjs/authorization`'s
-     * deny-by-default guard: `CanAnyone()`). Static wiring.
+     * Omitted: open outside production; in production every request answers 403 (and a warning is
+     * logged at boot).
+     */
+    authorize?: ConsoleAuthorize;
+    /**
+     * Class decorators applied to every controller this module mounts, before the console's own
+     * `authorize` check — e.g. `[UseGuards(AuthenticationGuard)]` so `request.user` is set when
+     * `authorize` runs. Applied to a per-registration subclass, so nothing sticks to the shared
+     * classes. They do not replace `authorize`. Static wiring.
      */
     decorators?: ClassDecorator[];
     /**
      * `false` mounts none of the console's routes, while its services still run — the way NestJS's
      * own packages leave routes to you: serve them from controllers of your own, protected with the
      * official tools, by extending the exported `AgentApiController` / `AgentUiController` under your
-     * own path and decorators (the module exports what they inject). Static wiring.
+     * own path and decorators (the module exports what they inject); `UseConsoleAuthorize()` applies
+     * this module's `authorize` to them. Static wiring.
      */
     routes?: boolean;
     /** Extra `imports` merged into the console's modules — what a decorator's guard injects. */
@@ -342,6 +433,12 @@ interface AgentDashboardOptions<TReq = unknown> {
      * `executedByRef` unset — the explicit override wins outright, with no resolver fallback.
      */
     approvalActorRef?: (req: TReq) => string | undefined;
+    /**
+     * Register the console's reads as developer tools on the agent MCP server's dev endpoint
+     * (`/mcp/aviary`), gated by this console's `authorize`. Default: on when the console's routes are
+     * mounted, off with `routes: false`.
+     */
+    devTools?: boolean;
 }
 /** Holds the JSON API + SSE controller and its read service, mounted on its own path. */
 declare class AgentApiModule {
@@ -350,12 +447,13 @@ declare class AgentApiModule {
         decorators?: ClassDecorator[];
         routes?: boolean;
         approvalActorRef?: (req: TReq) => string | undefined;
+        authorize?: ConsoleAuthorize;
+        devTools?: boolean;
     }): DynamicModule;
 }
 /**
  * The AI-gateway console: the SPA at `basePath` and its JSON API at `apiBasePath`. Who reaches them
- * is the app's — `decorators`, or the app mounts them itself (`routes: false`) — with
- * `@nestjs/authentication` / `@nestjs/authorization`.
+ * is `authorize` (see {@link AgentDashboardOptions.authorize}).
  */
 declare class AgentDashboardModule {
     static forRoot<TReq = unknown>(options?: AgentDashboardOptions<TReq>): DynamicModule;
@@ -380,8 +478,9 @@ interface UiPageResponse {
  * `<base>/assets`). The path comes from `RouterModule` (set by
  * {@link AgentDashboardModule.forRoot}({ basePath })), so the controller routes are relative.
  *
- * Who reaches it is the app's: `decorators` on `AgentDashboardModule.forRoot`, or the app mounts it
- * itself (`routes: false`) — with `@nestjs/authentication` / `@nestjs/authorization`.
+ * Who reaches it: `authorize` on `AgentDashboardModule.forRoot` (checked by `ConsoleAuthorizeGuard`,
+ * after the app's `decorators`). Mounted by the app itself (`routes: false`), apply
+ * `UseConsoleAuthorize()` to your subclass.
  */
 declare class AgentUiController {
     private readonly basePath;
@@ -392,6 +491,105 @@ declare class AgentUiController {
     asset(file: string): StreamableFile;
 }
 
+/** What {@link DashboardConsoleAccess} is built from (bound per `forRoot`). */
+interface DashboardConsoleOptions {
+    authorize?: ConsoleAuthorize;
+}
+/** Holds the console's resolved `authorize` check for one registration. */
+declare class DashboardConsoleAccess implements OnModuleInit {
+    #private;
+    private readonly options;
+    private readonly moduleRef;
+    constructor(options: DashboardConsoleOptions, moduleRef: ModuleRef);
+    /** Resolves `authorize` at boot: a configuration mistake fails the boot, and the warning logs once. */
+    onModuleInit(): Promise<void>;
+    /** The decision for one request. */
+    check(context: ExecutionContext): Promise<ConsoleDecision>;
+}
+/** Marks a controller or handler as serving pages: a denied browser navigation gets HTML or a 302. */
+declare const CONSOLE_PAGE_METADATA = "@dudousxd/nestjs-agent-dashboard:console-page";
+/**
+ * On a controller or a handler that serves pages: a denied `GET` that accepts HTML gets a page (or a
+ * 302 for `redirectTo`), not JSON.
+ */
+declare const ConsolePage: () => ClassDecorator & MethodDecorator;
+/** Thrown by {@link ConsoleAuthorizeGuard}; its body is the JSON answer even without the filter. */
+declare class ConsoleAccessDenied extends HttpException {
+    readonly decision: Exclude<ConsoleDecision, {
+        allowed: true;
+    }>;
+    readonly page: boolean;
+    constructor(decision: Exclude<ConsoleDecision, {
+        allowed: true;
+    }>, page: boolean);
+}
+/**
+ * Runs the console's `authorize` on every route of a controller it guards. Applied by the module
+ * after the app's `decorators` (so authentication guards have already set `request.user`); a
+ * self-mounted controller (`routes: false`) applies it with {@link UseConsoleAuthorize}.
+ */
+declare class ConsoleAuthorizeGuard implements CanActivate {
+    private readonly access;
+    constructor(access: DashboardConsoleAccess);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+/** Writes a console denial: JSON for API calls; a 302 or an HTML page (403 / 401) for page navigations. */
+declare class ConsoleAuthorizeFilter implements ExceptionFilter<ConsoleAccessDenied> {
+    private readonly adapterHost;
+    constructor(adapterHost: HttpAdapterHost);
+    catch(exception: ConsoleAccessDenied, host: ArgumentsHost): void;
+}
+/**
+ * The console's access check on a controller of your own (with `routes: false`): the
+ * {@link ConsoleAuthorizeGuard} plus the filter that writes its denials. Write it ABOVE your own
+ * authentication decorators: class decorators apply bottom-up, so it then runs after them and
+ * `request.user` is set.
+ */
+declare function UseConsoleAuthorize(): ClassDecorator & MethodDecorator;
+
+interface DevToolInputProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    description?: string;
+    enum?: readonly string[];
+    items?: {
+        type: 'string';
+    };
+    minimum?: number;
+    maximum?: number;
+}
+interface DevToolInputSchema {
+    type: 'object';
+    properties: Record<string, DevToolInputProperty>;
+    required?: string[];
+}
+/** One developer tool, as the dev-tools slot takes it. */
+interface AgentDevTool {
+    name: string;
+    kind: 'read' | 'action';
+    description: string;
+    input: DevToolInputSchema;
+    run(input: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * The agent's developer tools (lib `agent`): the governance console's reads, through the same
+ * {@link DashboardService} methods its API serves. No actions: approving a tool call over MCP would
+ * bypass the human approval it exists for.
+ */
+declare function agentDevTools(dashboard: DashboardService): AgentDevTool[];
+/**
+ * Registers the agent's tools into the dev-tools slot, gated by the console's own resolved
+ * `authorize`, when the console is mounted (or `devTools: true`). Removed again on shutdown.
+ */
+declare class AgentDevToolsRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly enabled;
+    private readonly dashboard;
+    private readonly access;
+    constructor(enabled: boolean, dashboard: DashboardService, access: DashboardConsoleAccess);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+}
+
 /**
  * Minimal shape guard for a `POST <api>/pricing` body — rejects junk before it reaches
  * `AgentPricingStore.upsertModelPrice`. Not a full schema validator (the store adapter owns real
@@ -455,5 +653,9 @@ declare const DASHBOARD_API_PATH: unique symbol;
  * injecting it needs no `@Optional()`.
  */
 declare const DASHBOARD_APPROVAL_ACTOR_REF: unique symbol;
+/** DI token carrying the console's `authorize` (and whether to warn when it is omitted). */
+declare const DASHBOARD_CONSOLE_OPTIONS: unique symbol;
+/** DI token: whether the agent's dev tools register into the dev-tools slot. */
+declare const DASHBOARD_DEV_TOOLS: 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 RunDetailWithLabel, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadDetailWithLabel, 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, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, type AgentDevTool, AgentDevToolsRegistration, AgentUiController, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, ConsoleAccessDenied, type ConsoleAuthorize, ConsoleAuthorizeFilter, ConsoleAuthorizeGuard, type ConsoleAuthorizeResult, type ConsoleAuthorizer, type ConsoleAuthorizerClass, type ConsoleDecide, type ConsoleDecision, type ConsoleGate, ConsolePage, type ConsolePolicyCheck, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_BASE_PATH, DASHBOARD_CONSOLE_OPTIONS, DASHBOARD_DEV_TOOLS, DashboardConsoleAccess, DashboardService, type LiveAgentEvent, type ReliabilityOverview, type RunDetailWithLabel, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadDetailWithLabel, type ThreadSpendRowWithLabel, UseConsoleAuthorize, type WithActorLabel, agentDashboardMountPaths, agentDevTools, anyAuthorize, authorizeByToken, normalizeConsoleResult, parsePriceInput, resolveConsoleAuthorize };

package/dist/server/index.d.ts

@@ -1,7 +1,8 @@
 import { ActorSpendRow, AgentGovernanceQueries, ActorDirectory, AgentPricingStore, AgentApprovalPort, GovernanceRange, ModelSpendRow, UsageTrendPoint, FeatureSpendRow, ThreadSpendRow, RunMetrics, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, RecentRunRow, ToolCallActivityRow, GovernancePageQuery, ToolCallWhere, GovernancePage, RunWhere, PendingApprovalRow, ApprovalWhere, GovernanceRunDetail, GovernanceThreadDetailQuery, GovernanceThreadDetail, ThreadActivityRow, ToolStatRow, GenuiStats, ThreadWhere, CurrentModelPrice, ActorResolver, ModelPriceInput } from '@dudousxd/nestjs-agent-core';
 export { ActorDirectory } from '@dudousxd/nestjs-agent-core';
 import { Observable } from 'rxjs';
-import { DynamicModule, StreamableFile } from '@nestjs/common';
+import { ExecutionContext, Type, Logger, DynamicModule, StreamableFile, OnModuleInit, HttpException, ExceptionFilter, ArgumentsHost, CanActivate, OnModuleDestroy } from '@nestjs/common';
+import { ModuleRef, HttpAdapterHost } from '@nestjs/core';
 
 /** An actor-scoped row decorated with its resolved display label — `null` when unbound or unresolved. */
 interface WithActorLabel {
@@ -151,8 +152,9 @@ 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.
  *
- * Who reaches it is the app's: `decorators` on `AgentDashboardModule.forRoot`, or the app mounts it
- * itself (`routes: false`) — with `@nestjs/authentication` / `@nestjs/authorization`.
+ * Who reaches it: `authorize` on `AgentDashboardModule.forRoot` (checked by `ConsoleAuthorizeGuard`,
+ * after the app's `decorators`). Mounted by the app itself (`routes: false`), apply
+ * `UseConsoleAuthorize()` to your subclass.
  */
 declare class AgentApiController {
     private readonly dashboard;
@@ -293,6 +295,90 @@ interface AgentDashboardMountPathsOptions {
  */
 declare function agentDashboardMountPaths(options?: AgentDashboardMountPathsOptions): string[];
 
+/**
+ * What an `authorize` check answers. An allow may name who it let in (`caller`, for example
+ * `'user:42'`): the dev MCP endpoint logs it as the caller of a developer tool. Never put a secret
+ * in it.
+ */
+type ConsoleAuthorizeResult = boolean | {
+    allowed: true;
+    caller?: string;
+} | {
+    allowed: false;
+    reason?: 'unauthenticated' | 'forbidden';
+} | {
+    redirectTo: string;
+};
+/** Class form: an @Injectable() provider (constructor injection works). */
+interface ConsoleAuthorizer {
+    authorize(context: ExecutionContext): ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>;
+}
+type ConsoleAuthorizerClass = Type<ConsoleAuthorizer>;
+/** @nestjs/authorization policy check: policy[ability](user). */
+interface ConsolePolicyCheck {
+    policy: Type<unknown>;
+    ability: string;
+}
+/** Who reaches the console. */
+type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>) | ConsoleAuthorizerClass | (() => Promise<{
+    default: ConsoleAuthorizerClass;
+}>) | ConsolePolicyCheck | string;
+/** A normalized `authorize` answer. */
+type ConsoleDecision = {
+    allowed: true;
+    caller?: string;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+};
+/** What a resolved `authorize` is: called once per request, never throws. */
+type ConsoleDecide = (context: ExecutionContext) => Promise<ConsoleDecision>;
+/**
+ * The provider that resolves gate names (`authorize: 'console.agent'`), bound globally by
+ * `@dudousxd/nestjs-authz`'s `AuthzModule`. A registry symbol, so it is found without depending on
+ * that package.
+ */
+declare const CONSOLE_GATE: unique symbol;
+interface ConsoleGate {
+    allows(name: string, context: ExecutionContext): Promise<ConsoleAuthorizeResult>;
+}
+/** The one boot warning for a console with no `authorize`. Same wording in every Aviary console. */
+declare const CONSOLE_AUTHORIZE_MISSING_WARNING = "[@dudousxd/nestjs-agent-dashboard] console has no `authorize` configured: it is open outside production and denies every request in production. Set `authorize` in AgentDashboardModule.forRoot().";
+/** Turns any {@link ConsoleAuthorizeResult} into a {@link ConsoleDecision}. */
+declare function normalizeConsoleResult(result: unknown): ConsoleDecision;
+/**
+ * Resolves `authorize` into one function the guard calls per request. Configuration mistakes (a
+ * gate name without nestjs-authz, a policy without `@nestjs/authorization`) throw here, so call it
+ * at boot. The returned function never throws: an error is a `forbidden`.
+ *
+ * `authorize` omitted: open outside production, `forbidden` for every request in production (read
+ * when this runs), and one warning logged (unless `warnIfMissing: false`).
+ */
+declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined, moduleRef: ModuleRef, options?: {
+    logger?: Logger;
+    warnIfMissing?: boolean;
+}): Promise<ConsoleDecide>;
+/**
+ * `authorize` by a bearer token: allows when `Authorization: Bearer <token>` matches (compared in
+ * constant time), else `unauthenticated`. Header only. An empty token throws here, at config time.
+ * The allow names its caller `token:<first 12 hex of sha256(token)>`, never the token.
+ */
+declare function authorizeByToken(options: {
+    token: string | undefined;
+}): (context: ExecutionContext) => ConsoleAuthorizeResult;
+/**
+ * One `authorize` from several: allowed when any form allows (checked in order, stopping at the
+ * first that does, whose `caller` it keeps); otherwise `unauthenticated` when any form said so (keeping the first
+ * `redirectTo`), else `forbidden`. Each form is any `authorize` value: a function, a class, a lazy
+ * import, `{ policy, ability }` or a gate name.
+ *
+ * ```ts
+ * authorize: anyAuthorize(authorizeByToken({ token: process.env.CONSOLE_TOKEN }), AdminSessionAuthorizer)
+ * ```
+ */
+declare function anyAuthorize(...forms: ConsoleAuthorize[]): ConsoleAuthorizerClass;
+
 /**
  * `TReq` mirrors core's `ActorResolver<TReq>` convention: the transport request type
  * {@link AgentDashboardOptions.approvalActorRef} receives. Defaults to `unknown`.
@@ -310,23 +396,28 @@ interface AgentDashboardOptions<TReq = unknown> {
      */
     apiBasePath?: string;
     /**
-     * Who reaches the console: class decorators applied to every controller this module mounts — the
-     * ecosystem's convention, like `@nestjs/mcp`'s `decorators` — with the official tools, e.g.
-     * `[UseGuards(AuthenticationGuard), Can(ConsolePolicy, 'view')]` from `@nestjs/authentication` /
-     * `@nestjs/authorization`, or a function as a guard instance, `UseGuards({ canActivate })`.
-     * Applied to a per-registration subclass, so nothing sticks to the shared classes.
+     * Who reaches the console (the SPA and every API/SSE route): an inline function
+     * `(ctx) => boolean | { allowed } | { redirectTo }`, an `@Injectable()` `ConsoleAuthorizer` class,
+     * a lazy import of one, `{ policy, ability }` (`@nestjs/authorization`), or a gate name
+     * (`@dudousxd/nestjs-authz`). `authorizeByToken({ token })` checks a bearer token.
      *
-     * In production (`NODE_ENV=production`) the console refuses to boot without them, unless the app
-     * mounts the routes itself (`routes: false`): a governance console is never served open there by
-     * default. Outside production the routes are open (and to `@nestjs/authorization`'s
-     * deny-by-default guard: `CanAnyone()`). Static wiring.
+     * Omitted: open outside production; in production every request answers 403 (and a warning is
+     * logged at boot).
+     */
+    authorize?: ConsoleAuthorize;
+    /**
+     * Class decorators applied to every controller this module mounts, before the console's own
+     * `authorize` check — e.g. `[UseGuards(AuthenticationGuard)]` so `request.user` is set when
+     * `authorize` runs. Applied to a per-registration subclass, so nothing sticks to the shared
+     * classes. They do not replace `authorize`. Static wiring.
      */
     decorators?: ClassDecorator[];
     /**
      * `false` mounts none of the console's routes, while its services still run — the way NestJS's
      * own packages leave routes to you: serve them from controllers of your own, protected with the
      * official tools, by extending the exported `AgentApiController` / `AgentUiController` under your
-     * own path and decorators (the module exports what they inject). Static wiring.
+     * own path and decorators (the module exports what they inject); `UseConsoleAuthorize()` applies
+     * this module's `authorize` to them. Static wiring.
      */
     routes?: boolean;
     /** Extra `imports` merged into the console's modules — what a decorator's guard injects. */
@@ -342,6 +433,12 @@ interface AgentDashboardOptions<TReq = unknown> {
      * `executedByRef` unset — the explicit override wins outright, with no resolver fallback.
      */
     approvalActorRef?: (req: TReq) => string | undefined;
+    /**
+     * Register the console's reads as developer tools on the agent MCP server's dev endpoint
+     * (`/mcp/aviary`), gated by this console's `authorize`. Default: on when the console's routes are
+     * mounted, off with `routes: false`.
+     */
+    devTools?: boolean;
 }
 /** Holds the JSON API + SSE controller and its read service, mounted on its own path. */
 declare class AgentApiModule {
@@ -350,12 +447,13 @@ declare class AgentApiModule {
         decorators?: ClassDecorator[];
         routes?: boolean;
         approvalActorRef?: (req: TReq) => string | undefined;
+        authorize?: ConsoleAuthorize;
+        devTools?: boolean;
     }): DynamicModule;
 }
 /**
  * The AI-gateway console: the SPA at `basePath` and its JSON API at `apiBasePath`. Who reaches them
- * is the app's — `decorators`, or the app mounts them itself (`routes: false`) — with
- * `@nestjs/authentication` / `@nestjs/authorization`.
+ * is `authorize` (see {@link AgentDashboardOptions.authorize}).
  */
 declare class AgentDashboardModule {
     static forRoot<TReq = unknown>(options?: AgentDashboardOptions<TReq>): DynamicModule;
@@ -380,8 +478,9 @@ interface UiPageResponse {
  * `<base>/assets`). The path comes from `RouterModule` (set by
  * {@link AgentDashboardModule.forRoot}({ basePath })), so the controller routes are relative.
  *
- * Who reaches it is the app's: `decorators` on `AgentDashboardModule.forRoot`, or the app mounts it
- * itself (`routes: false`) — with `@nestjs/authentication` / `@nestjs/authorization`.
+ * Who reaches it: `authorize` on `AgentDashboardModule.forRoot` (checked by `ConsoleAuthorizeGuard`,
+ * after the app's `decorators`). Mounted by the app itself (`routes: false`), apply
+ * `UseConsoleAuthorize()` to your subclass.
  */
 declare class AgentUiController {
     private readonly basePath;
@@ -392,6 +491,105 @@ declare class AgentUiController {
     asset(file: string): StreamableFile;
 }
 
+/** What {@link DashboardConsoleAccess} is built from (bound per `forRoot`). */
+interface DashboardConsoleOptions {
+    authorize?: ConsoleAuthorize;
+}
+/** Holds the console's resolved `authorize` check for one registration. */
+declare class DashboardConsoleAccess implements OnModuleInit {
+    #private;
+    private readonly options;
+    private readonly moduleRef;
+    constructor(options: DashboardConsoleOptions, moduleRef: ModuleRef);
+    /** Resolves `authorize` at boot: a configuration mistake fails the boot, and the warning logs once. */
+    onModuleInit(): Promise<void>;
+    /** The decision for one request. */
+    check(context: ExecutionContext): Promise<ConsoleDecision>;
+}
+/** Marks a controller or handler as serving pages: a denied browser navigation gets HTML or a 302. */
+declare const CONSOLE_PAGE_METADATA = "@dudousxd/nestjs-agent-dashboard:console-page";
+/**
+ * On a controller or a handler that serves pages: a denied `GET` that accepts HTML gets a page (or a
+ * 302 for `redirectTo`), not JSON.
+ */
+declare const ConsolePage: () => ClassDecorator & MethodDecorator;
+/** Thrown by {@link ConsoleAuthorizeGuard}; its body is the JSON answer even without the filter. */
+declare class ConsoleAccessDenied extends HttpException {
+    readonly decision: Exclude<ConsoleDecision, {
+        allowed: true;
+    }>;
+    readonly page: boolean;
+    constructor(decision: Exclude<ConsoleDecision, {
+        allowed: true;
+    }>, page: boolean);
+}
+/**
+ * Runs the console's `authorize` on every route of a controller it guards. Applied by the module
+ * after the app's `decorators` (so authentication guards have already set `request.user`); a
+ * self-mounted controller (`routes: false`) applies it with {@link UseConsoleAuthorize}.
+ */
+declare class ConsoleAuthorizeGuard implements CanActivate {
+    private readonly access;
+    constructor(access: DashboardConsoleAccess);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+/** Writes a console denial: JSON for API calls; a 302 or an HTML page (403 / 401) for page navigations. */
+declare class ConsoleAuthorizeFilter implements ExceptionFilter<ConsoleAccessDenied> {
+    private readonly adapterHost;
+    constructor(adapterHost: HttpAdapterHost);
+    catch(exception: ConsoleAccessDenied, host: ArgumentsHost): void;
+}
+/**
+ * The console's access check on a controller of your own (with `routes: false`): the
+ * {@link ConsoleAuthorizeGuard} plus the filter that writes its denials. Write it ABOVE your own
+ * authentication decorators: class decorators apply bottom-up, so it then runs after them and
+ * `request.user` is set.
+ */
+declare function UseConsoleAuthorize(): ClassDecorator & MethodDecorator;
+
+interface DevToolInputProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    description?: string;
+    enum?: readonly string[];
+    items?: {
+        type: 'string';
+    };
+    minimum?: number;
+    maximum?: number;
+}
+interface DevToolInputSchema {
+    type: 'object';
+    properties: Record<string, DevToolInputProperty>;
+    required?: string[];
+}
+/** One developer tool, as the dev-tools slot takes it. */
+interface AgentDevTool {
+    name: string;
+    kind: 'read' | 'action';
+    description: string;
+    input: DevToolInputSchema;
+    run(input: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * The agent's developer tools (lib `agent`): the governance console's reads, through the same
+ * {@link DashboardService} methods its API serves. No actions: approving a tool call over MCP would
+ * bypass the human approval it exists for.
+ */
+declare function agentDevTools(dashboard: DashboardService): AgentDevTool[];
+/**
+ * Registers the agent's tools into the dev-tools slot, gated by the console's own resolved
+ * `authorize`, when the console is mounted (or `devTools: true`). Removed again on shutdown.
+ */
+declare class AgentDevToolsRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly enabled;
+    private readonly dashboard;
+    private readonly access;
+    constructor(enabled: boolean, dashboard: DashboardService, access: DashboardConsoleAccess);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+}
+
 /**
  * Minimal shape guard for a `POST <api>/pricing` body — rejects junk before it reaches
  * `AgentPricingStore.upsertModelPrice`. Not a full schema validator (the store adapter owns real
@@ -455,5 +653,9 @@ declare const DASHBOARD_API_PATH: unique symbol;
  * injecting it needs no `@Optional()`.
  */
 declare const DASHBOARD_APPROVAL_ACTOR_REF: unique symbol;
+/** DI token carrying the console's `authorize` (and whether to warn when it is omitted). */
+declare const DASHBOARD_CONSOLE_OPTIONS: unique symbol;
+/** DI token: whether the agent's dev tools register into the dev-tools slot. */
+declare const DASHBOARD_DEV_TOOLS: 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 RunDetailWithLabel, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadDetailWithLabel, 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, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, type AgentDevTool, AgentDevToolsRegistration, AgentUiController, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, ConsoleAccessDenied, type ConsoleAuthorize, ConsoleAuthorizeFilter, ConsoleAuthorizeGuard, type ConsoleAuthorizeResult, type ConsoleAuthorizer, type ConsoleAuthorizerClass, type ConsoleDecide, type ConsoleDecision, type ConsoleGate, ConsolePage, type ConsolePolicyCheck, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_BASE_PATH, DASHBOARD_CONSOLE_OPTIONS, DASHBOARD_DEV_TOOLS, DashboardConsoleAccess, DashboardService, type LiveAgentEvent, type ReliabilityOverview, type RunDetailWithLabel, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadDetailWithLabel, type ThreadSpendRowWithLabel, UseConsoleAuthorize, type WithActorLabel, agentDashboardMountPaths, agentDevTools, anyAuthorize, authorizeByToken, normalizeConsoleResult, parsePriceInput, resolveConsoleAuthorize };