@dudousxd/nestjs-agent-dashboard 0.21.0 → 0.23.0

package/dist/server/index.d.cts

@@ -4,6 +4,13 @@ import { Observable } from 'rxjs';
 import { ExecutionContext, Type, Logger, DynamicModule, StreamableFile, OnModuleInit, HttpException, ExceptionFilter, ArgumentsHost, CanActivate, OnModuleDestroy } from '@nestjs/common';
 import { ModuleRef, HttpAdapterHost } from '@nestjs/core';
 
+/** The agent's `tenancy` option, as `AgentModule.forRoot({ tenancy })` holds it. */
+type AgentTenancyOption = 'inherit' | false | {
+    enabled?: 'inherit' | boolean;
+    kinds?: string[];
+    nullRows?: 'tenantless' | 'shared';
+};
+
 /** An actor-scoped row decorated with its resolved display label — `null` when unbound or unresolved. */
 interface WithActorLabel {
     actorLabel: string | null;
@@ -68,7 +75,17 @@ declare class DashboardService {
     private readonly actorDirectory?;
     private readonly pricingStore?;
     private readonly approvalPort?;
-    constructor(queries: AgentGovernanceQueries, actorDirectory?: ActorDirectory | undefined, pricingStore?: AgentPricingStore | undefined, approvalPort?: AgentApprovalPort | undefined);
+    private readonly agentOptions?;
+    private readonly contextAccessor?;
+    constructor(queries: AgentGovernanceQueries, actorDirectory?: ActorDirectory | undefined, pricingStore?: AgentPricingStore | undefined, approvalPort?: AgentApprovalPort | undefined, agentOptions?: {
+        tenancy?: AgentTenancyOption;
+    } | undefined, contextAccessor?: unknown | undefined);
+    /**
+     * The read-model for this request: with the agent's tenancy on, narrowed to the viewer's context
+     * tenant (another tenant's thread or run is not found). A store without `forTenant` cannot be
+     * narrowed, so the console refuses (`501`) rather than show every tenant's rows.
+     */
+    private scoped;
     /** Spend/usage overview for a day range: by-model + by-actor spend and the daily trend, in parallel. */
     spend(range: GovernanceRange): Promise<SpendOverview>;
     /** Top threads by cost for a day range (default 10, highest cost first). */
@@ -473,6 +490,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 +507,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 +571,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;
@@ -641,6 +749,10 @@ declare const AGENT_APPROVAL_PORT: unique symbol;
  * unauthenticated), `executedByRef` is simply omitted.
  */
 declare const AGENT_ACTOR_RESOLVER: unique symbol;
+/** `AgentModule`'s options — read for their `tenancy`. Optional: absent → tenancy `'inherit'`. */
+declare const AGENT_OPTIONS: unique symbol;
+/** `@dudousxd/nestjs-context`'s accessor. Optional: absent → the global slot, else tenancy off. */
+declare const CONTEXT_ACCESSOR: unique symbol;
 /** DI token carrying the UI mount base (e.g. `/ai-gateway`). */
 declare const DASHBOARD_BASE_PATH: unique symbol;
 /** DI token carrying the JSON API base the SPA fetches from (e.g. `/ai-gateway/api`). */
@@ -658,4 +770,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_OPTIONS, 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, CONTEXT_ACCESSOR, 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

@@ -4,6 +4,13 @@ import { Observable } from 'rxjs';
 import { ExecutionContext, Type, Logger, DynamicModule, StreamableFile, OnModuleInit, HttpException, ExceptionFilter, ArgumentsHost, CanActivate, OnModuleDestroy } from '@nestjs/common';
 import { ModuleRef, HttpAdapterHost } from '@nestjs/core';
 
+/** The agent's `tenancy` option, as `AgentModule.forRoot({ tenancy })` holds it. */
+type AgentTenancyOption = 'inherit' | false | {
+    enabled?: 'inherit' | boolean;
+    kinds?: string[];
+    nullRows?: 'tenantless' | 'shared';
+};
+
 /** An actor-scoped row decorated with its resolved display label — `null` when unbound or unresolved. */
 interface WithActorLabel {
     actorLabel: string | null;
@@ -68,7 +75,17 @@ declare class DashboardService {
     private readonly actorDirectory?;
     private readonly pricingStore?;
     private readonly approvalPort?;
-    constructor(queries: AgentGovernanceQueries, actorDirectory?: ActorDirectory | undefined, pricingStore?: AgentPricingStore | undefined, approvalPort?: AgentApprovalPort | undefined);
+    private readonly agentOptions?;
+    private readonly contextAccessor?;
+    constructor(queries: AgentGovernanceQueries, actorDirectory?: ActorDirectory | undefined, pricingStore?: AgentPricingStore | undefined, approvalPort?: AgentApprovalPort | undefined, agentOptions?: {
+        tenancy?: AgentTenancyOption;
+    } | undefined, contextAccessor?: unknown | undefined);
+    /**
+     * The read-model for this request: with the agent's tenancy on, narrowed to the viewer's context
+     * tenant (another tenant's thread or run is not found). A store without `forTenant` cannot be
+     * narrowed, so the console refuses (`501`) rather than show every tenant's rows.
+     */
+    private scoped;
     /** Spend/usage overview for a day range: by-model + by-actor spend and the daily trend, in parallel. */
     spend(range: GovernanceRange): Promise<SpendOverview>;
     /** Top threads by cost for a day range (default 10, highest cost first). */
@@ -473,6 +490,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 +507,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 +571,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;
@@ -641,6 +749,10 @@ declare const AGENT_APPROVAL_PORT: unique symbol;
  * unauthenticated), `executedByRef` is simply omitted.
  */
 declare const AGENT_ACTOR_RESOLVER: unique symbol;
+/** `AgentModule`'s options — read for their `tenancy`. Optional: absent → tenancy `'inherit'`. */
+declare const AGENT_OPTIONS: unique symbol;
+/** `@dudousxd/nestjs-context`'s accessor. Optional: absent → the global slot, else tenancy off. */
+declare const CONTEXT_ACCESSOR: unique symbol;
 /** DI token carrying the UI mount base (e.g. `/ai-gateway`). */
 declare const DASHBOARD_BASE_PATH: unique symbol;
 /** DI token carrying the JSON API base the SPA fetches from (e.g. `/ai-gateway/api`). */
@@ -658,4 +770,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_OPTIONS, 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, CONTEXT_ACCESSOR, 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 };