@dudousxd/nestjs-agent-dashboard 0.20.0 → 0.21.0

package/dist/server/index.d.cts

@@ -1,7 +1,7 @@
 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 { ExecutionContext, Type, Logger, DynamicModule, StreamableFile, HttpException, ExceptionFilter, ArgumentsHost, CanActivate, OnModuleInit } 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. */
@@ -295,9 +295,14 @@ interface AgentDashboardMountPathsOptions {
  */
 declare function agentDashboardMountPaths(options?: AgentDashboardMountPathsOptions): string[];
 
-/** What an `authorize` check answers. */
+/**
+ * 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';
@@ -321,6 +326,7 @@ type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult |
 /** A normalized `authorize` answer. */
 type ConsoleDecision = {
     allowed: true;
+    caller?: string;
 } | {
     allowed: false;
     reason: 'unauthenticated' | 'forbidden';
@@ -356,10 +362,22 @@ declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined
 /**
  * `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
@@ -415,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 {
@@ -424,6 +448,7 @@ declare class AgentApiModule {
         routes?: boolean;
         approvalActorRef?: (req: TReq) => string | undefined;
         authorize?: ConsoleAuthorize;
+        devTools?: boolean;
     }): DynamicModule;
 }
 /**
@@ -522,6 +547,49 @@ declare class ConsoleAuthorizeFilter implements ExceptionFilter<ConsoleAccessDen
  */
 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
@@ -587,5 +655,7 @@ declare const DASHBOARD_API_PATH: unique symbol;
 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, 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, DashboardConsoleAccess, DashboardService, type LiveAgentEvent, type ReliabilityOverview, type RunDetailWithLabel, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadDetailWithLabel, type ThreadSpendRowWithLabel, UseConsoleAuthorize, type WithActorLabel, agentDashboardMountPaths, authorizeByToken, normalizeConsoleResult, parsePriceInput, resolveConsoleAuthorize };
+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,7 @@
 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 { ExecutionContext, Type, Logger, DynamicModule, StreamableFile, HttpException, ExceptionFilter, ArgumentsHost, CanActivate, OnModuleInit } 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. */
@@ -295,9 +295,14 @@ interface AgentDashboardMountPathsOptions {
  */
 declare function agentDashboardMountPaths(options?: AgentDashboardMountPathsOptions): string[];
 
-/** What an `authorize` check answers. */
+/**
+ * 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';
@@ -321,6 +326,7 @@ type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult |
 /** A normalized `authorize` answer. */
 type ConsoleDecision = {
     allowed: true;
+    caller?: string;
 } | {
     allowed: false;
     reason: 'unauthenticated' | 'forbidden';
@@ -356,10 +362,22 @@ declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined
 /**
  * `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
@@ -415,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 {
@@ -424,6 +448,7 @@ declare class AgentApiModule {
         routes?: boolean;
         approvalActorRef?: (req: TReq) => string | undefined;
         authorize?: ConsoleAuthorize;
+        devTools?: boolean;
     }): DynamicModule;
 }
 /**
@@ -522,6 +547,49 @@ declare class ConsoleAuthorizeFilter implements ExceptionFilter<ConsoleAccessDen
  */
 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
@@ -587,5 +655,7 @@ declare const DASHBOARD_API_PATH: unique symbol;
 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, 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, DashboardConsoleAccess, DashboardService, type LiveAgentEvent, type ReliabilityOverview, type RunDetailWithLabel, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadDetailWithLabel, type ThreadSpendRowWithLabel, UseConsoleAuthorize, type WithActorLabel, agentDashboardMountPaths, authorizeByToken, normalizeConsoleResult, parsePriceInput, resolveConsoleAuthorize };
+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 };