@dudousxd/nestjs-durable-dashboard 0.56.0 → 0.58.0

package/dist/server/index.d.cts

@@ -1,4 +1,4 @@
-import { HttpException, ExecutionContext, Type, ExceptionFilter, ArgumentsHost, CanActivate, Logger, DynamicModule, StreamableFile } from '@nestjs/common';
+import { HttpException, ExecutionContext, Type, ExceptionFilter, ArgumentsHost, CanActivate, Logger, DynamicModule, StreamableFile, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
 import { HttpAdapterHost, ModuleRef } from '@nestjs/core';
 import * as _dudousxd_nestjs_durable_core from '@dudousxd/nestjs-durable-core';
 import { RunGateway, StateStore, WorkflowEngine, ScheduleListQuery, ScheduleDescription, RunResult, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, DurableTopology, GroupHealth, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RepublishLifecycleResult, WorkflowLifecycleLinks, UpdateResult, EngineEvent, AttributeFilter } from '@dudousxd/nestjs-durable-core';
@@ -8,8 +8,14 @@ import { Observable } from 'rxjs';
 import * as _dudousxd_nestjs_filter from '@dudousxd/nestjs-filter';
 import { FilterRunner } from '@dudousxd/nestjs-filter';
 
+/**
+ * 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';
@@ -31,6 +37,7 @@ type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult |
 }>) | ConsolePolicyCheck | string;
 type ConsoleDecision = {
     allowed: true;
+    caller?: string;
 } | {
     allowed: false;
     reason: 'unauthenticated' | 'forbidden';
@@ -65,11 +72,23 @@ declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined
 /**
  * Allows a request carrying `Authorization: Bearer <token>` (compared timing-safe); anything else
  * is `unauthenticated`. Header only: no query string, no custom header. Throws when `token` is
- * empty, so a missing env var fails at config time instead of opening the console.
+ * empty, so a missing env var fails at config time instead of opening the console. The allow names
+ * its caller `token:<first 12 hex of sha256(token)>`, never the token.
  */
 declare function authorizeByToken(options: {
     token: string | undefined;
 }): ConsoleAuthorize;
+/**
+ * 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;
 /** DI token of the resolved {@link ConsoleDecide} the guard runs. */
 declare const CONSOLE_AUTHORIZE_DECIDE: unique symbol;
 /** Marks a controller as serving pages: a denied `GET` that accepts HTML gets a page, not JSON. */
@@ -88,6 +107,12 @@ declare class ConsoleAccessDenied extends HttpException {
         allowed: false;
     }>, page: boolean);
 }
+/**
+ * Marks a console route that is not part of the console: `authorize` does not apply to it. Used on
+ * the `ctx.webhook()` callback, which third parties call with the token as the secret.
+ */
+declare const CONSOLE_PUBLIC_METADATA = "@dudousxd/nestjs-durable-dashboard:console-public";
+declare const ConsolePublic: () => MethodDecorator;
 declare class ConsoleAuthorizeGuard implements CanActivate {
     private readonly decide;
     constructor(decide: ConsoleDecide);
@@ -235,6 +260,22 @@ declare class DashboardService {
      * rows behind or signal non-webhook tokens. Control-plane-only.
      */
     deliverWebhook(token: string, body: unknown): Promise<RunResult | null>;
+    /**
+     * What this deployment can serve: `controlPlane` (signals, run events, updates, metrics) and
+     * `schedules` (persisted schedules). Both are false on a store-less tenant.
+     */
+    capabilities(): {
+        controlPlane: boolean;
+        schedules: boolean;
+    };
+    /** Whether `runId` names a run the caller may see (tenancy applies). */
+    runExists(runId: string): Promise<boolean>;
+    /**
+     * Deliver `payload` to the run waiting on `token` (`engine.signal`). Null when no run the caller
+     * may see waits on it yet: the engine then buffers the payload for the run that waits next.
+     * Control-plane-only.
+     */
+    signal(token: string, payload: unknown): Promise<RunResult | null>;
     /** Side-effect-free read of a value a run published via `ctx.setEvent` (a live query). Control-plane-only. */
     getEvent(runId: string, key: string): Promise<unknown>;
     /** Deliver a validated `ctx.onUpdate` to a run; the validator may reject it (see UpdateResult). Control-plane-only. */
@@ -422,9 +463,9 @@ declare class DurableApiControllerBase {
     }>;
     /**
      * Public callback endpoint for `ctx.webhook()`: a third party POSTs here (the url handed to it),
-     * and the body resumes the waiting run. NOTE: this is reachable by external systems — protect it
-     * by treating the token as a secret (it embeds runId:seq) and/or fronting it with signature
-     * verification in your own middleware.
+     * and the body resumes the waiting run. Not a console route: the console's `authorize` does not
+     * apply, the token is the secret. The app's `decorators` still do. Treat the token as a secret
+     * and/or front it with signature verification in your own middleware.
      */
     webhook(token: string, body: unknown): Promise<_dudousxd_nestjs_durable_core.RunResult>;
     /** Live query: the latest value a run published for `key` via `ctx.setEvent` (no side effect). */
@@ -443,7 +484,9 @@ declare class DurableApiController extends DurableApiControllerBase {
 
 interface DurableDashboardOptions {
     /**
-     * Who may use the console (the SPA, its JSON API, the run stream and the webhook route). One of:
+     * Who may use the console (the SPA, its JSON API and the run stream). Not the `ctx.webhook()`
+     * callback (`POST <apiBasePath>/webhooks/:token`), which third parties call with the token as the
+     * secret; {@link decorators} still apply to it. One of:
      *
      * - a function `(context) => boolean | { allowed } | { redirectTo }` (may be async);
      * - an `@Injectable()` class implementing {@link ConsoleAuthorizer} (constructor injection works;
@@ -525,6 +568,12 @@ interface DurableDashboardOptions {
      * strings that keep their meaning (where the console lives) whether or not this module mounts it.
      */
     routes?: boolean;
+    /**
+     * Register the console's reads and run/schedule actions 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 controller + its read service, mounted on its own path by `forRoot`. Its own
@@ -540,6 +589,8 @@ declare class DurableApiModule {
         decorators?: ClassDecorator[];
         /** See {@link DurableDashboardOptions.authorize}. */
         authorize?: ConsoleAuthorize;
+        /** See {@link DurableDashboardOptions.devTools}. Default: on when the routes are mounted. */
+        devTools?: boolean;
     }): DynamicModule;
 }
 /**
@@ -557,9 +608,12 @@ declare class DurableDashboardModule {
 }
 
 /** DI token carrying the UI mount base (e.g. `/durable`). */
-declare const DASHBOARD_BASE_PATH: unique symbol;
+declare const DASHBOARD_BASE_PATH: symbol;
 /** DI token carrying the JSON API base the SPA fetches from (e.g. `/api/durable`). */
-declare const DASHBOARD_API_PATH: unique symbol;
+declare const DASHBOARD_API_PATH: symbol;
+
+/** The id of the page's JSON config block. */
+declare const DURABLE_DASHBOARD_CONFIG_ID = "durable-dashboard-config";
 /**
  * Serves the bundled control-plane SPA at the configured base (+ hashed assets at `<base>/assets`).
  * The controller routes are relative: the mounted {@link DurableUiController} gets its path from
@@ -577,6 +631,11 @@ declare class DurableUiControllerBase {
     private readonly dir;
     constructor(basePath: string, apiBasePath: string);
     index(): string;
+    /**
+     * The page's JSON config block (`durable-dashboard-config`, CSP-safe: data, not script). It
+     * carries `switcher` only when another Aviary console is registered.
+     */
+    private configBlock;
     asset(file: string): StreamableFile;
 }
 /**
@@ -588,4 +647,165 @@ declare class DurableUiControllerBase {
 declare class DurableUiController extends DurableUiControllerBase {
 }
 
-export { CONSOLE_AUTHORIZE_DECIDE, 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_BASE_PATH, DashboardService, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiControllerBase, UseConsoleAuthorize, type WorkflowLifecyclePage, authorizeByToken, normalizeConsoleResult, resolveConsoleAuthorize };
+/** The process-wide slot `@dudousxd/nestjs-agent-mcp-server` serves on its dev MCP endpoint. */
+declare const DEV_TOOLS_SLOT: symbol;
+/** One property of a {@link DevToolInputSchema}. */
+interface DevToolInputProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    description?: string;
+    enum?: readonly string[];
+    /** Arrays hold strings only. */
+    items?: {
+        type: 'string';
+    };
+    minimum?: number;
+    maximum?: number;
+}
+/** An object of scalar / enum / array-of-string properties. */
+interface DevToolInputSchema {
+    type: 'object';
+    properties: Record<string, DevToolInputProperty>;
+    required?: string[];
+}
+/** What the slot's `authorize` answers: the console's resolved decision. */
+type DevToolsDecision = {
+    allowed: true;
+    caller?: string;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+};
+/** What a tool's `run` receives besides its input. */
+interface DevToolCall {
+    context: ExecutionContext;
+    caller: {
+        id: string;
+        via: 'token' | 'session' | 'open';
+    };
+    limits: {
+        maxRows: number;
+        maxBytes: number;
+    };
+}
+/** One developer tool, as the dev-tools slot takes it. */
+interface DurableDevTool {
+    /** `durable_<verb>_<noun>`. */
+    name: string;
+    /** `read` tools are listed by default; `action` tools only when the app opts in. */
+    kind: 'read' | 'action';
+    description: string;
+    input: DevToolInputSchema;
+    /** Set on actions that cancel. */
+    destructive?: boolean;
+    /** Capability, not access: hides a tool this deployment cannot run. */
+    available?(): boolean | Promise<boolean>;
+    run(input: Record<string, unknown>, call?: DevToolCall): Promise<unknown>;
+}
+/** Runs `durable_retry_run` / `durable_cancel_run` act on at most per call. */
+declare const MAX_RUN_IDS = 100;
+/**
+ * The durable developer tools (lib `durable`): the console's reads and its run and schedule
+ * actions, through the same {@link DashboardService} methods its API serves, so tenancy and the
+ * app's redaction apply. Signals, run events and schedules are available only on the control plane.
+ */
+declare function durableDevTools(service: DashboardService): DurableDevTool[];
+/**
+ * Registers the durable 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 DurableDevToolsRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly enabled;
+    private readonly service;
+    private readonly decide;
+    constructor(enabled: boolean, service: DashboardService, decide: ConsoleDecide);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+}
+
+/** The process-wide slot every Aviary console registers into (created by whichever boots first). */
+declare const AVIARY_CONSOLES_SLOT: 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 (`/durable`). */
+    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: number;
+/**
+ * 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 durable console's id in the registry. */
+declare const DURABLE_CONSOLE_ID: string;
+/**
+ * Registers the durable 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 DurableConsoleRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly basePath;
+    private readonly decide;
+    constructor(basePath: string, decide: ConsoleDecide);
+    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 DurableConsolesController {
+    consoles(current: CurrentContext): Promise<VisibleConsoles>;
+}
+
+export { AVIARY_CONSOLES_SLOT, type AviaryConsoleDecision, type AviaryConsoleEntry, type AviaryConsoleIcon, type AviaryConsoleRegistry, CONSOLE_AUTHORIZE_DECIDE, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, CONSOLE_PROBE_TIMEOUT_MS, CONSOLE_PUBLIC_METADATA, ConsoleAccessDenied, type ConsoleAuthorize, ConsoleAuthorizeFilter, ConsoleAuthorizeGuard, type ConsoleAuthorizeResult, type ConsoleAuthorizer, type ConsoleAuthorizerClass, type ConsoleDecide, type ConsoleDecision, type ConsoleGate, ConsolePage, type ConsolePolicyCheck, ConsolePublic, DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DEV_TOOLS_SLOT, DURABLE_CONSOLE_ID, DURABLE_DASHBOARD_CONFIG_ID, DashboardService, type DevToolCall, type DevToolInputProperty, type DevToolInputSchema, type DevToolsDecision, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableConsoleRegistration, DurableConsolesController, DurableDashboardModule, type DurableDashboardOptions, type DurableDevTool, DurableDevToolsRegistration, DurableUiController, DurableUiControllerBase, MAX_RUN_IDS, UseConsoleAuthorize, type VisibleConsole, type VisibleConsoles, type WorkflowLifecyclePage, anyAuthorize, authorizeByToken, durableDevTools, listVisibleConsoles, normalizeConsoleResult, registerAviaryConsole, resolveConsoleAuthorize };

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-import { HttpException, ExecutionContext, Type, ExceptionFilter, ArgumentsHost, CanActivate, Logger, DynamicModule, StreamableFile } from '@nestjs/common';
+import { HttpException, ExecutionContext, Type, ExceptionFilter, ArgumentsHost, CanActivate, Logger, DynamicModule, StreamableFile, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
 import { HttpAdapterHost, ModuleRef } from '@nestjs/core';
 import * as _dudousxd_nestjs_durable_core from '@dudousxd/nestjs-durable-core';
 import { RunGateway, StateStore, WorkflowEngine, ScheduleListQuery, ScheduleDescription, RunResult, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, DurableTopology, GroupHealth, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RepublishLifecycleResult, WorkflowLifecycleLinks, UpdateResult, EngineEvent, AttributeFilter } from '@dudousxd/nestjs-durable-core';
@@ -8,8 +8,14 @@ import { Observable } from 'rxjs';
 import * as _dudousxd_nestjs_filter from '@dudousxd/nestjs-filter';
 import { FilterRunner } from '@dudousxd/nestjs-filter';
 
+/**
+ * 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';
@@ -31,6 +37,7 @@ type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult |
 }>) | ConsolePolicyCheck | string;
 type ConsoleDecision = {
     allowed: true;
+    caller?: string;
 } | {
     allowed: false;
     reason: 'unauthenticated' | 'forbidden';
@@ -65,11 +72,23 @@ declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined
 /**
  * Allows a request carrying `Authorization: Bearer <token>` (compared timing-safe); anything else
  * is `unauthenticated`. Header only: no query string, no custom header. Throws when `token` is
- * empty, so a missing env var fails at config time instead of opening the console.
+ * empty, so a missing env var fails at config time instead of opening the console. The allow names
+ * its caller `token:<first 12 hex of sha256(token)>`, never the token.
  */
 declare function authorizeByToken(options: {
     token: string | undefined;
 }): ConsoleAuthorize;
+/**
+ * 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;
 /** DI token of the resolved {@link ConsoleDecide} the guard runs. */
 declare const CONSOLE_AUTHORIZE_DECIDE: unique symbol;
 /** Marks a controller as serving pages: a denied `GET` that accepts HTML gets a page, not JSON. */
@@ -88,6 +107,12 @@ declare class ConsoleAccessDenied extends HttpException {
         allowed: false;
     }>, page: boolean);
 }
+/**
+ * Marks a console route that is not part of the console: `authorize` does not apply to it. Used on
+ * the `ctx.webhook()` callback, which third parties call with the token as the secret.
+ */
+declare const CONSOLE_PUBLIC_METADATA = "@dudousxd/nestjs-durable-dashboard:console-public";
+declare const ConsolePublic: () => MethodDecorator;
 declare class ConsoleAuthorizeGuard implements CanActivate {
     private readonly decide;
     constructor(decide: ConsoleDecide);
@@ -235,6 +260,22 @@ declare class DashboardService {
      * rows behind or signal non-webhook tokens. Control-plane-only.
      */
     deliverWebhook(token: string, body: unknown): Promise<RunResult | null>;
+    /**
+     * What this deployment can serve: `controlPlane` (signals, run events, updates, metrics) and
+     * `schedules` (persisted schedules). Both are false on a store-less tenant.
+     */
+    capabilities(): {
+        controlPlane: boolean;
+        schedules: boolean;
+    };
+    /** Whether `runId` names a run the caller may see (tenancy applies). */
+    runExists(runId: string): Promise<boolean>;
+    /**
+     * Deliver `payload` to the run waiting on `token` (`engine.signal`). Null when no run the caller
+     * may see waits on it yet: the engine then buffers the payload for the run that waits next.
+     * Control-plane-only.
+     */
+    signal(token: string, payload: unknown): Promise<RunResult | null>;
     /** Side-effect-free read of a value a run published via `ctx.setEvent` (a live query). Control-plane-only. */
     getEvent(runId: string, key: string): Promise<unknown>;
     /** Deliver a validated `ctx.onUpdate` to a run; the validator may reject it (see UpdateResult). Control-plane-only. */
@@ -422,9 +463,9 @@ declare class DurableApiControllerBase {
     }>;
     /**
      * Public callback endpoint for `ctx.webhook()`: a third party POSTs here (the url handed to it),
-     * and the body resumes the waiting run. NOTE: this is reachable by external systems — protect it
-     * by treating the token as a secret (it embeds runId:seq) and/or fronting it with signature
-     * verification in your own middleware.
+     * and the body resumes the waiting run. Not a console route: the console's `authorize` does not
+     * apply, the token is the secret. The app's `decorators` still do. Treat the token as a secret
+     * and/or front it with signature verification in your own middleware.
      */
     webhook(token: string, body: unknown): Promise<_dudousxd_nestjs_durable_core.RunResult>;
     /** Live query: the latest value a run published for `key` via `ctx.setEvent` (no side effect). */
@@ -443,7 +484,9 @@ declare class DurableApiController extends DurableApiControllerBase {
 
 interface DurableDashboardOptions {
     /**
-     * Who may use the console (the SPA, its JSON API, the run stream and the webhook route). One of:
+     * Who may use the console (the SPA, its JSON API and the run stream). Not the `ctx.webhook()`
+     * callback (`POST <apiBasePath>/webhooks/:token`), which third parties call with the token as the
+     * secret; {@link decorators} still apply to it. One of:
      *
      * - a function `(context) => boolean | { allowed } | { redirectTo }` (may be async);
      * - an `@Injectable()` class implementing {@link ConsoleAuthorizer} (constructor injection works;
@@ -525,6 +568,12 @@ interface DurableDashboardOptions {
      * strings that keep their meaning (where the console lives) whether or not this module mounts it.
      */
     routes?: boolean;
+    /**
+     * Register the console's reads and run/schedule actions 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 controller + its read service, mounted on its own path by `forRoot`. Its own
@@ -540,6 +589,8 @@ declare class DurableApiModule {
         decorators?: ClassDecorator[];
         /** See {@link DurableDashboardOptions.authorize}. */
         authorize?: ConsoleAuthorize;
+        /** See {@link DurableDashboardOptions.devTools}. Default: on when the routes are mounted. */
+        devTools?: boolean;
     }): DynamicModule;
 }
 /**
@@ -557,9 +608,12 @@ declare class DurableDashboardModule {
 }
 
 /** DI token carrying the UI mount base (e.g. `/durable`). */
-declare const DASHBOARD_BASE_PATH: unique symbol;
+declare const DASHBOARD_BASE_PATH: symbol;
 /** DI token carrying the JSON API base the SPA fetches from (e.g. `/api/durable`). */
-declare const DASHBOARD_API_PATH: unique symbol;
+declare const DASHBOARD_API_PATH: symbol;
+
+/** The id of the page's JSON config block. */
+declare const DURABLE_DASHBOARD_CONFIG_ID = "durable-dashboard-config";
 /**
  * Serves the bundled control-plane SPA at the configured base (+ hashed assets at `<base>/assets`).
  * The controller routes are relative: the mounted {@link DurableUiController} gets its path from
@@ -577,6 +631,11 @@ declare class DurableUiControllerBase {
     private readonly dir;
     constructor(basePath: string, apiBasePath: string);
     index(): string;
+    /**
+     * The page's JSON config block (`durable-dashboard-config`, CSP-safe: data, not script). It
+     * carries `switcher` only when another Aviary console is registered.
+     */
+    private configBlock;
     asset(file: string): StreamableFile;
 }
 /**
@@ -588,4 +647,165 @@ declare class DurableUiControllerBase {
 declare class DurableUiController extends DurableUiControllerBase {
 }
 
-export { CONSOLE_AUTHORIZE_DECIDE, 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_BASE_PATH, DashboardService, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiControllerBase, UseConsoleAuthorize, type WorkflowLifecyclePage, authorizeByToken, normalizeConsoleResult, resolveConsoleAuthorize };
+/** The process-wide slot `@dudousxd/nestjs-agent-mcp-server` serves on its dev MCP endpoint. */
+declare const DEV_TOOLS_SLOT: symbol;
+/** One property of a {@link DevToolInputSchema}. */
+interface DevToolInputProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    description?: string;
+    enum?: readonly string[];
+    /** Arrays hold strings only. */
+    items?: {
+        type: 'string';
+    };
+    minimum?: number;
+    maximum?: number;
+}
+/** An object of scalar / enum / array-of-string properties. */
+interface DevToolInputSchema {
+    type: 'object';
+    properties: Record<string, DevToolInputProperty>;
+    required?: string[];
+}
+/** What the slot's `authorize` answers: the console's resolved decision. */
+type DevToolsDecision = {
+    allowed: true;
+    caller?: string;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+};
+/** What a tool's `run` receives besides its input. */
+interface DevToolCall {
+    context: ExecutionContext;
+    caller: {
+        id: string;
+        via: 'token' | 'session' | 'open';
+    };
+    limits: {
+        maxRows: number;
+        maxBytes: number;
+    };
+}
+/** One developer tool, as the dev-tools slot takes it. */
+interface DurableDevTool {
+    /** `durable_<verb>_<noun>`. */
+    name: string;
+    /** `read` tools are listed by default; `action` tools only when the app opts in. */
+    kind: 'read' | 'action';
+    description: string;
+    input: DevToolInputSchema;
+    /** Set on actions that cancel. */
+    destructive?: boolean;
+    /** Capability, not access: hides a tool this deployment cannot run. */
+    available?(): boolean | Promise<boolean>;
+    run(input: Record<string, unknown>, call?: DevToolCall): Promise<unknown>;
+}
+/** Runs `durable_retry_run` / `durable_cancel_run` act on at most per call. */
+declare const MAX_RUN_IDS = 100;
+/**
+ * The durable developer tools (lib `durable`): the console's reads and its run and schedule
+ * actions, through the same {@link DashboardService} methods its API serves, so tenancy and the
+ * app's redaction apply. Signals, run events and schedules are available only on the control plane.
+ */
+declare function durableDevTools(service: DashboardService): DurableDevTool[];
+/**
+ * Registers the durable 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 DurableDevToolsRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly enabled;
+    private readonly service;
+    private readonly decide;
+    constructor(enabled: boolean, service: DashboardService, decide: ConsoleDecide);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+}
+
+/** The process-wide slot every Aviary console registers into (created by whichever boots first). */
+declare const AVIARY_CONSOLES_SLOT: 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 (`/durable`). */
+    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: number;
+/**
+ * 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 durable console's id in the registry. */
+declare const DURABLE_CONSOLE_ID: string;
+/**
+ * Registers the durable 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 DurableConsoleRegistration implements OnModuleInit, OnModuleDestroy {
+    #private;
+    private readonly basePath;
+    private readonly decide;
+    constructor(basePath: string, decide: ConsoleDecide);
+    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 DurableConsolesController {
+    consoles(current: CurrentContext): Promise<VisibleConsoles>;
+}
+
+export { AVIARY_CONSOLES_SLOT, type AviaryConsoleDecision, type AviaryConsoleEntry, type AviaryConsoleIcon, type AviaryConsoleRegistry, CONSOLE_AUTHORIZE_DECIDE, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, CONSOLE_PROBE_TIMEOUT_MS, CONSOLE_PUBLIC_METADATA, ConsoleAccessDenied, type ConsoleAuthorize, ConsoleAuthorizeFilter, ConsoleAuthorizeGuard, type ConsoleAuthorizeResult, type ConsoleAuthorizer, type ConsoleAuthorizerClass, type ConsoleDecide, type ConsoleDecision, type ConsoleGate, ConsolePage, type ConsolePolicyCheck, ConsolePublic, DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DEV_TOOLS_SLOT, DURABLE_CONSOLE_ID, DURABLE_DASHBOARD_CONFIG_ID, DashboardService, type DevToolCall, type DevToolInputProperty, type DevToolInputSchema, type DevToolsDecision, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableConsoleRegistration, DurableConsolesController, DurableDashboardModule, type DurableDashboardOptions, type DurableDevTool, DurableDevToolsRegistration, DurableUiController, DurableUiControllerBase, MAX_RUN_IDS, UseConsoleAuthorize, type VisibleConsole, type VisibleConsoles, type WorkflowLifecyclePage, anyAuthorize, authorizeByToken, durableDevTools, listVisibleConsoles, normalizeConsoleResult, registerAviaryConsole, resolveConsoleAuthorize };