@dudousxd/nestjs-agent-dashboard 0.21.0 → 0.22.0

package/dist/server/index.d.cts

@@ -473,6 +473,8 @@ interface UiPageResponse {
     status(code: number): unknown;
     setHeader(name: string, value: string): unknown;
 }
+/** The id of the page's JSON config block. */
+declare const AGENT_DASHBOARD_CONFIG_ID = "agent-dashboard-config";
 /**
  * Serves the bundled AI-gateway console SPA at the configured base (+ hashed assets at
  * `<base>/assets`). The path comes from `RouterModule` (set by
@@ -488,6 +490,11 @@ declare class AgentUiController {
     private readonly dir;
     constructor(basePath: string, apiBasePath: string);
     index(req: UiPageRequest, res: UiPageResponse): string;
+    /**
+     * The page's JSON config block (`agent-dashboard-config`, CSP-safe: data, not script). It carries
+     * `switcher` only when another Aviary console is registered.
+     */
+    private configBlock;
     asset(file: string): StreamableFile;
 }
 
@@ -547,6 +554,90 @@ declare class ConsoleAuthorizeFilter implements ExceptionFilter<ConsoleAccessDen
  */
 declare function UseConsoleAuthorize(): ClassDecorator & MethodDecorator;
 
+/** The process-wide slot every Aviary console registers into (created by whichever boots first). */
+declare const AVIARY_CONSOLES_SLOT: unique symbol;
+/** The icon a console shows in the switcher. An unknown value renders as `generic`. */
+type AviaryConsoleIcon = 'workflow' | 'telescope' | 'media' | 'payments' | 'agent' | 'identity' | 'generic';
+/** What a console's `authorize` answers; only `allowed: true` lists it. */
+interface AviaryConsoleDecision {
+    allowed: boolean;
+    reason?: string;
+    redirectTo?: string;
+}
+/** One console the switcher can list. */
+interface AviaryConsoleEntry {
+    /** `/^[a-z][a-z0-9-]*$/`: `'durable'`, `'telescope'`, `'agent'`, `'media'`, … */
+    id: string;
+    /** Product title: `'Workflows'`, `'Telescope'`, `'Agents'`, `'Media'`. */
+    title: string;
+    icon: AviaryConsoleIcon;
+    /** Same-origin absolute path of the console's page (`/ai-gateway`). */
+    path: string;
+    /** Sort key: durable 10, telescope 20, agent 30, media 50. */
+    order: number;
+    /** The console's resolved gate (what its own routes run). Never throws. */
+    authorize(context: ExecutionContext): Promise<AviaryConsoleDecision>;
+}
+/** The value at {@link AVIARY_CONSOLES_SLOT}. Data only, so every console's copy is identical. */
+interface AviaryConsoleRegistry {
+    readonly version: 1;
+    readonly entries: AviaryConsoleEntry[];
+}
+/** One console as `GET <api>/consoles` returns it. */
+interface VisibleConsole {
+    id: string;
+    title: string;
+    icon: AviaryConsoleIcon;
+    href: string;
+}
+/** The answer of `GET <api>/consoles`. */
+interface VisibleConsoles {
+    version: 1;
+    current: string;
+    consoles: VisibleConsole[];
+}
+/** How long another console's `authorize` may take before it is left out. */
+declare const CONSOLE_PROBE_TIMEOUT_MS = 300;
+/**
+ * Adds a console to the process's switcher registry, creating it when absent. Returns a function
+ * that removes the entry again, or `undefined` when it was not added (another registry version, or
+ * the id is taken: logged as a warning). A bad `id` or `path` throws.
+ */
+declare function registerAviaryConsole(entry: AviaryConsoleEntry, logger?: {
+    warn(message: string): void;
+}): (() => void) | undefined;
+/**
+ * The consoles other than `selfId` the viewer may open, by `order` then `id`. Every other entry's
+ * `authorize` runs in parallel, each given `timeoutMs`; a timeout, a rejection or any denial hides
+ * it. No reason is ever returned.
+ */
+declare function listVisibleConsoles(registry: AviaryConsoleRegistry | undefined, selfId: string, context: ExecutionContext, timeoutMs?: number): Promise<VisibleConsoles>;
+/** The agent console's id in the registry. */
+declare const AGENT_CONSOLE_ID = "agent";
+/**
+ * Registers the agent console into the switcher registry (the console's page path, gated by its
+ * resolved `authorize`). Provided only when the console's routes are mounted; removed on shutdown.
+ */
+declare class AgentConsoleRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly basePath;
+    private readonly access;
+    constructor(basePath: string, access: DashboardConsoleAccess);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+}
+/** What the route hands on to the other consoles' `authorize`: this request's `ExecutionContext`. */
+interface CurrentContext {
+    context: ExecutionContext;
+}
+/**
+ * `GET <api>/consoles`: the other Aviary consoles this viewer may open. Behind the console's own
+ * access check, like every API route, so only someone who may open this console learns the list.
+ */
+declare class AgentConsolesController {
+    consoles(current: CurrentContext): Promise<VisibleConsoles>;
+}
+
 interface DevToolInputProperty {
     type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
     description?: string;
@@ -658,4 +749,4 @@ 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, 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 };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_CONSOLE_ID, AGENT_DASHBOARD_CONFIG_ID, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, AVIARY_CONSOLES_SLOT, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, AgentConsoleRegistration, AgentConsolesController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, type AgentDevTool, AgentDevToolsRegistration, AgentUiController, type AviaryConsoleDecision, type AviaryConsoleEntry, type AviaryConsoleIcon, type AviaryConsoleRegistry, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, CONSOLE_PROBE_TIMEOUT_MS, 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 VisibleConsole, type VisibleConsoles, type WithActorLabel, agentDashboardMountPaths, agentDevTools, anyAuthorize, authorizeByToken, listVisibleConsoles, normalizeConsoleResult, parsePriceInput, registerAviaryConsole, resolveConsoleAuthorize };

package/dist/server/index.d.ts

@@ -473,6 +473,8 @@ interface UiPageResponse {
     status(code: number): unknown;
     setHeader(name: string, value: string): unknown;
 }
+/** The id of the page's JSON config block. */
+declare const AGENT_DASHBOARD_CONFIG_ID = "agent-dashboard-config";
 /**
  * Serves the bundled AI-gateway console SPA at the configured base (+ hashed assets at
  * `<base>/assets`). The path comes from `RouterModule` (set by
@@ -488,6 +490,11 @@ declare class AgentUiController {
     private readonly dir;
     constructor(basePath: string, apiBasePath: string);
     index(req: UiPageRequest, res: UiPageResponse): string;
+    /**
+     * The page's JSON config block (`agent-dashboard-config`, CSP-safe: data, not script). It carries
+     * `switcher` only when another Aviary console is registered.
+     */
+    private configBlock;
     asset(file: string): StreamableFile;
 }
 
@@ -547,6 +554,90 @@ declare class ConsoleAuthorizeFilter implements ExceptionFilter<ConsoleAccessDen
  */
 declare function UseConsoleAuthorize(): ClassDecorator & MethodDecorator;
 
+/** The process-wide slot every Aviary console registers into (created by whichever boots first). */
+declare const AVIARY_CONSOLES_SLOT: unique symbol;
+/** The icon a console shows in the switcher. An unknown value renders as `generic`. */
+type AviaryConsoleIcon = 'workflow' | 'telescope' | 'media' | 'payments' | 'agent' | 'identity' | 'generic';
+/** What a console's `authorize` answers; only `allowed: true` lists it. */
+interface AviaryConsoleDecision {
+    allowed: boolean;
+    reason?: string;
+    redirectTo?: string;
+}
+/** One console the switcher can list. */
+interface AviaryConsoleEntry {
+    /** `/^[a-z][a-z0-9-]*$/`: `'durable'`, `'telescope'`, `'agent'`, `'media'`, … */
+    id: string;
+    /** Product title: `'Workflows'`, `'Telescope'`, `'Agents'`, `'Media'`. */
+    title: string;
+    icon: AviaryConsoleIcon;
+    /** Same-origin absolute path of the console's page (`/ai-gateway`). */
+    path: string;
+    /** Sort key: durable 10, telescope 20, agent 30, media 50. */
+    order: number;
+    /** The console's resolved gate (what its own routes run). Never throws. */
+    authorize(context: ExecutionContext): Promise<AviaryConsoleDecision>;
+}
+/** The value at {@link AVIARY_CONSOLES_SLOT}. Data only, so every console's copy is identical. */
+interface AviaryConsoleRegistry {
+    readonly version: 1;
+    readonly entries: AviaryConsoleEntry[];
+}
+/** One console as `GET <api>/consoles` returns it. */
+interface VisibleConsole {
+    id: string;
+    title: string;
+    icon: AviaryConsoleIcon;
+    href: string;
+}
+/** The answer of `GET <api>/consoles`. */
+interface VisibleConsoles {
+    version: 1;
+    current: string;
+    consoles: VisibleConsole[];
+}
+/** How long another console's `authorize` may take before it is left out. */
+declare const CONSOLE_PROBE_TIMEOUT_MS = 300;
+/**
+ * Adds a console to the process's switcher registry, creating it when absent. Returns a function
+ * that removes the entry again, or `undefined` when it was not added (another registry version, or
+ * the id is taken: logged as a warning). A bad `id` or `path` throws.
+ */
+declare function registerAviaryConsole(entry: AviaryConsoleEntry, logger?: {
+    warn(message: string): void;
+}): (() => void) | undefined;
+/**
+ * The consoles other than `selfId` the viewer may open, by `order` then `id`. Every other entry's
+ * `authorize` runs in parallel, each given `timeoutMs`; a timeout, a rejection or any denial hides
+ * it. No reason is ever returned.
+ */
+declare function listVisibleConsoles(registry: AviaryConsoleRegistry | undefined, selfId: string, context: ExecutionContext, timeoutMs?: number): Promise<VisibleConsoles>;
+/** The agent console's id in the registry. */
+declare const AGENT_CONSOLE_ID = "agent";
+/**
+ * Registers the agent console into the switcher registry (the console's page path, gated by its
+ * resolved `authorize`). Provided only when the console's routes are mounted; removed on shutdown.
+ */
+declare class AgentConsoleRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly basePath;
+    private readonly access;
+    constructor(basePath: string, access: DashboardConsoleAccess);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+}
+/** What the route hands on to the other consoles' `authorize`: this request's `ExecutionContext`. */
+interface CurrentContext {
+    context: ExecutionContext;
+}
+/**
+ * `GET <api>/consoles`: the other Aviary consoles this viewer may open. Behind the console's own
+ * access check, like every API route, so only someone who may open this console learns the list.
+ */
+declare class AgentConsolesController {
+    consoles(current: CurrentContext): Promise<VisibleConsoles>;
+}
+
 interface DevToolInputProperty {
     type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
     description?: string;
@@ -658,4 +749,4 @@ 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, 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 };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_CONSOLE_ID, AGENT_DASHBOARD_CONFIG_ID, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, AVIARY_CONSOLES_SLOT, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, AgentConsoleRegistration, AgentConsolesController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, type AgentDevTool, AgentDevToolsRegistration, AgentUiController, type AviaryConsoleDecision, type AviaryConsoleEntry, type AviaryConsoleIcon, type AviaryConsoleRegistry, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, CONSOLE_PROBE_TIMEOUT_MS, 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 VisibleConsole, type VisibleConsoles, type WithActorLabel, agentDashboardMountPaths, agentDevTools, anyAuthorize, authorizeByToken, listVisibleConsoles, normalizeConsoleResult, parsePriceInput, registerAviaryConsole, resolveConsoleAuthorize };