@dudousxd/nestjs-agent-dashboard 0.20.0 → 0.21.0

package/dist/server/index.cjs

@@ -40,6 +40,7 @@ __export(index_exports, {
   AgentApiController: () => AgentApiController,
   AgentApiModule: () => AgentApiModule,
   AgentDashboardModule: () => AgentDashboardModule,
+  AgentDevToolsRegistration: () => AgentDevToolsRegistration,
   AgentUiController: () => AgentUiController,
   CONSOLE_AUTHORIZE_MISSING_WARNING: () => CONSOLE_AUTHORIZE_MISSING_WARNING,
   CONSOLE_GATE: () => CONSOLE_GATE,
@@ -52,10 +53,13 @@ __export(index_exports, {
   DASHBOARD_APPROVAL_ACTOR_REF: () => DASHBOARD_APPROVAL_ACTOR_REF,
   DASHBOARD_BASE_PATH: () => DASHBOARD_BASE_PATH,
   DASHBOARD_CONSOLE_OPTIONS: () => DASHBOARD_CONSOLE_OPTIONS,
+  DASHBOARD_DEV_TOOLS: () => DASHBOARD_DEV_TOOLS,
   DashboardConsoleAccess: () => DashboardConsoleAccess,
   DashboardService: () => DashboardService,
   UseConsoleAuthorize: () => UseConsoleAuthorize,
   agentDashboardMountPaths: () => agentDashboardMountPaths,
+  agentDevTools: () => agentDevTools,
+  anyAuthorize: () => anyAuthorize,
   authorizeByToken: () => authorizeByToken,
   normalizeConsoleResult: () => normalizeConsoleResult,
   parsePriceInput: () => parsePriceInput,
@@ -145,6 +149,7 @@ var DASHBOARD_BASE_PATH = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent-das
 var DASHBOARD_API_PATH = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent-dashboard:api-path");
 var DASHBOARD_APPROVAL_ACTOR_REF = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent-dashboard:approval-actor-ref");
 var DASHBOARD_CONSOLE_OPTIONS = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent-dashboard:console-options");
+var DASHBOARD_DEV_TOOLS = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent-dashboard:dev-tools");
 
 // src/server/dashboard.service.ts
 function _ts_decorate(decorators, target, key, desc) {
@@ -223,8 +228,8 @@ var DashboardService = class {
     };
   }
   /** Top threads by cost for a day range (default 10, highest cost first). */
-  async topThreads(range, limit = 10) {
-    const rows = await this.queries.spendByThread(range, limit);
+  async topThreads(range, limit2 = 10) {
+    const rows = await this.queries.spendByThread(range, limit2);
     return this.withActorLabels(rows);
   }
   /** Run reliability for a day range: metrics, by-agent/by-error breakdowns and the trend, in parallel. */
@@ -243,12 +248,12 @@ var DashboardService = class {
     };
   }
   /** Most recent runs (status/agent/duration/error) for the Reliability recent-runs table. */
-  recentRuns(limit) {
-    return this.queries.recentRuns(limit);
+  recentRuns(limit2) {
+    return this.queries.recentRuns(limit2);
   }
   /** Most recent tool calls (status/type/thread) for the Runs & tools activity feed. */
-  recentToolCalls(limit) {
-    return this.queries.recentToolCalls(limit);
+  recentToolCalls(limit2) {
+    return this.queries.recentToolCalls(limit2);
   }
   /** Paged, filterable tool calls for the Runs & tools activity table. */
   toolCallsPage(query) {
@@ -263,8 +268,8 @@ var DashboardService = class {
   * Capped and totalless — kept because the SPA still calls `GET approvals`; new callers want
   * {@link approvalsPage}, which reports how much of the backlog the cap hid.
   */
-  pendingApprovals(limit) {
-    return this.queries.pendingApprovals(limit);
+  pendingApprovals(limit2) {
+    return this.queries.pendingApprovals(limit2);
   }
   /** Paged, filterable approvals inbox with a total — the backlog-safe read of the HITL queue. */
   approvalsPage(query) {
@@ -352,8 +357,8 @@ var DashboardService = class {
     });
   }
   /** Most recent threads with rolled-up message/token counts. */
-  async recentThreads(limit) {
-    const rows = await this.queries.recentThreads(limit);
+  async recentThreads(limit2) {
+    const rows = await this.queries.recentThreads(limit2);
     return this.withActorLabels(rows);
   }
   /**
@@ -361,10 +366,10 @@ var DashboardService = class {
   * {@link recentThreads} is.
   */
   async threadsPage(query) {
-    const page = await this.queries.threadsPage(query);
-    const rows = await this.withActorLabels(page.rows);
+    const page2 = await this.queries.threadsPage(query);
+    const rows = await this.withActorLabels(page2.rows);
     return {
-      ...page,
+      ...page2,
       rows
     };
   }
@@ -685,27 +690,27 @@ var AgentApiController = class {
     return this.dashboard.spend(resolveRange(from, to));
   }
   /** Top threads by cost (default 10, max 200) for a day range (defaults to the last 30 days). */
-  topThreads(from, to, limit) {
-    return this.dashboard.topThreads(resolveRange(from, to), parseLimit(limit, 10));
+  topThreads(from, to, limit2) {
+    return this.dashboard.topThreads(resolveRange(from, to), parseLimit(limit2, 10));
   }
   /** `{ metrics, byAgent, errors, trend }` for a day range (defaults to the last 30 days). */
   reliability(from, to) {
     return this.dashboard.reliability(resolveRange(from, to));
   }
   /** Most recent runs (default 50, max 200) for the Reliability recent-runs table. */
-  runs(limit) {
-    return this.dashboard.recentRuns(parseLimit(limit, 50));
+  runs(limit2) {
+    return this.dashboard.recentRuns(parseLimit(limit2, 50));
   }
   /**
   * Paged, filterable runs for the Reliability recent-runs table. `page` (default 1), `limit`
   * (default 25, max 200), and `where[agentName]`/`where[status]`/`where[errorCode]`/
   * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
   */
-  runsPage(page, limit, where) {
-    const parsedWhere = parseRunWhere(where);
+  runsPage(page2, limit2, where2) {
+    const parsedWhere = parseRunWhere(where2);
     return this.dashboard.runsPage({
-      page: parsePageNumber(page),
-      pageSize: parseLimit(limit, 25),
+      page: parsePageNumber(page2),
+      pageSize: parseLimit(limit2, 25),
       ...parsedWhere !== void 0 ? {
         where: parsedWhere
       } : {}
@@ -722,19 +727,19 @@ var AgentApiController = class {
     return this.dashboard.runDetail(runId);
   }
   /** Most recent tool calls (default 50, max 200) for the activity feed. */
-  toolCalls(limit) {
-    return this.dashboard.recentToolCalls(parseLimit(limit, 50));
+  toolCalls(limit2) {
+    return this.dashboard.recentToolCalls(parseLimit(limit2, 50));
   }
   /**
   * Paged, filterable tool calls for the Runs & tools activity table. `page` (default 1), `limit`
   * (default 25, max 200), and `where[toolName]`/`where[toolType]`/`where[status]`/`where[threadId]`/
   * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
   */
-  toolCallsPage(page, limit, where) {
-    const parsedWhere = parseToolCallWhere(where);
+  toolCallsPage(page2, limit2, where2) {
+    const parsedWhere = parseToolCallWhere(where2);
     return this.dashboard.toolCallsPage({
-      page: parsePageNumber(page),
-      pageSize: parseLimit(limit, 25),
+      page: parsePageNumber(page2),
+      pageSize: parseLimit(limit2, 25),
       ...parsedWhere !== void 0 ? {
         where: parsedWhere
       } : {}
@@ -746,8 +751,8 @@ var AgentApiController = class {
   * Capped with NO total, so a backlog past `limit` is invisible from the response alone. Kept
   * because the SPA still calls it; anything new should call `approvals-page` instead.
   */
-  approvals(limit) {
-    return this.dashboard.pendingApprovals(parseLimit(limit, 50));
+  approvals(limit2) {
+    return this.dashboard.pendingApprovals(parseLimit(limit2, 50));
   }
   /**
   * Paged, filterable approvals inbox, oldest first. `page` (default 1), `limit` (default 25, max
@@ -757,11 +762,11 @@ var AgentApiController = class {
   * Unlike `GET approvals` this reports `total`, so the console can say "showing N of M" instead of
   * silently hiding pending decisions behind a row cap.
   */
-  approvalsPage(page, limit, where) {
-    const parsedWhere = parseApprovalWhere(where);
+  approvalsPage(page2, limit2, where2) {
+    const parsedWhere = parseApprovalWhere(where2);
     return this.dashboard.approvalsPage({
-      page: parsePageNumber(page),
-      pageSize: parseLimit(limit, 25),
+      page: parsePageNumber(page2),
+      pageSize: parseLimit(limit2, 25),
       ...parsedWhere !== void 0 ? {
         where: parsedWhere
       } : {}
@@ -808,19 +813,19 @@ var AgentApiController = class {
     return this.dashboard.genuiStats(resolveRange(from, to));
   }
   /** Most recent threads (default 50, max 200) with rolled-up counts. */
-  threads(limit) {
-    return this.dashboard.recentThreads(parseLimit(limit, 50));
+  threads(limit2) {
+    return this.dashboard.recentThreads(parseLimit(limit2, 50));
   }
   /**
   * Paged, filterable threads for the Runs & tools threads table. `page` (default 1), `limit`
   * (default 25, max 200), and `where[actorRef]`/`where[title]` (case-insensitive substring)/
   * `where[fromDay]`/`where[toDay]` (`YYYY-MM-DD`) — an unknown `where` field 400s naming it.
   */
-  threadsPage(page, limit, where) {
-    const parsedWhere = parseThreadWhere(where);
+  threadsPage(page2, limit2, where2) {
+    const parsedWhere = parseThreadWhere(where2);
     return this.dashboard.threadsPage({
-      page: parsePageNumber(page),
-      pageSize: parseLimit(limit, 25),
+      page: parsePageNumber(page2),
+      pageSize: parseLimit(limit2, 25),
       ...parsedWhere !== void 0 ? {
         where: parsedWhere
       } : {}
@@ -1106,8 +1111,8 @@ __name(agentDashboardMountPaths, "agentDashboardMountPaths");
 // src/server/agent-dashboard.module.ts
 var import_nestjs_agent_core3 = require("@dudousxd/nestjs-agent-core");
 var import_reflect_metadata = require("reflect-metadata");
-var import_common9 = require("@nestjs/common");
-var import_core2 = require("@nestjs/core");
+var import_common10 = require("@nestjs/common");
+var import_core3 = require("@nestjs/core");
 
 // src/server/agent-ui.controller.ts
 var import_node_fs = require("fs");
@@ -1118,19 +1123,23 @@ var import_common8 = require("@nestjs/common");
 
 // src/server/console-authorize.guard.ts
 var import_common7 = require("@nestjs/common");
-var import_core = require("@nestjs/core");
+var import_core2 = require("@nestjs/core");
 
 // src/server/console-authorize.ts
 var import_node_crypto = require("crypto");
 var import_common6 = require("@nestjs/common");
+var import_core = require("@nestjs/core");
 var CONSOLE_GATE = /* @__PURE__ */ Symbol.for("@dudousxd/aviary:console-gate");
 var PACKAGE = "@dudousxd/nestjs-agent-dashboard";
 var MODULE = "AgentDashboardModule";
 var logger = new import_common6.Logger(MODULE);
 var CONSOLE_AUTHORIZE_MISSING_WARNING = `[${PACKAGE}] console has no \`authorize\` configured: it is open outside production and denies every request in production. Set \`authorize\` in ${MODULE}.forRoot().`;
-var allow = /* @__PURE__ */ __name(() => ({
+var allow = /* @__PURE__ */ __name((caller) => caller !== void 0 && caller !== "" ? {
+  allowed: true,
+  caller
+} : {
   allowed: true
-}), "allow");
+}, "allow");
 var forbidden = /* @__PURE__ */ __name(() => ({
   allowed: false,
   reason: "forbidden"
@@ -1154,7 +1163,9 @@ function normalizeConsoleResult(result) {
       redirectTo: value.redirectTo
     };
   }
-  if (value.allowed === true) return allow();
+  if (value.allowed === true) {
+    return allow(typeof value.caller === "string" ? value.caller : void 0);
+  }
   return value.reason === "unauthenticated" ? unauthenticated() : forbidden();
 }
 __name(normalizeConsoleResult, "normalizeConsoleResult");
@@ -1230,7 +1241,7 @@ async function resolveConsoleAuthorize(authorize, moduleRef, options = {}) {
   if (authorize === void 0) {
     if (options.warnIfMissing !== false) log.warn(CONSOLE_AUTHORIZE_MISSING_WARNING);
     const production = isProduction();
-    return async () => production ? forbidden() : allow();
+    return async () => production ? forbidden() : allow("dev-open");
   }
   const instanceOf = classInstances(moduleRef);
   let decide;
@@ -1280,12 +1291,18 @@ function authorizeByToken(options) {
     throw new Error("authorizeByToken: `token` is empty; set it (e.g. from an env var).");
   }
   const expected = sha256(token);
+  const caller = `token:${expected.toString("hex").slice(0, 12)}`;
   return (context) => {
     const req = context.switchToHttp().getRequest();
     const header = req?.headers?.authorization;
     const value = Array.isArray(header) ? header[0] : header;
     const match = typeof value === "string" ? /^Bearer\s+(.+)$/i.exec(value.trim()) : null;
-    if (match?.[1] !== void 0 && (0, import_node_crypto.timingSafeEqual)(sha256(match[1]), expected)) return true;
+    if (match?.[1] !== void 0 && (0, import_node_crypto.timingSafeEqual)(sha256(match[1]), expected)) {
+      return {
+        allowed: true,
+        caller
+      };
+    }
     return {
       allowed: false,
       reason: "unauthenticated"
@@ -1293,6 +1310,48 @@ function authorizeByToken(options) {
   };
 }
 __name(authorizeByToken, "authorizeByToken");
+function anyAuthorize(...forms) {
+  if (forms.length === 0) throw new Error("anyAuthorize: pass at least one authorize form.");
+  let AnyConsoleAuthorizer = class AnyConsoleAuthorizer {
+    static {
+      __name(this, "AnyConsoleAuthorizer");
+    }
+    moduleRef;
+    #decides;
+    constructor(moduleRef) {
+      this.moduleRef = moduleRef;
+    }
+    async authorize(context) {
+      this.#decides ??= Promise.all(forms.map((form) => resolveConsoleAuthorize(form, this.moduleRef, {
+        warnIfMissing: false
+      })));
+      this.#decides.catch(() => {
+        this.#decides = void 0;
+      });
+      let unauthenticated2;
+      for (const decide of await this.#decides) {
+        const decision = await decide(context);
+        if (decision.allowed) return decision;
+        if (decision.reason === "unauthenticated") unauthenticated2 ??= decision;
+      }
+      if (unauthenticated2 === void 0) return {
+        allowed: false,
+        reason: "forbidden"
+      };
+      return "redirectTo" in unauthenticated2 && unauthenticated2.redirectTo !== void 0 ? {
+        redirectTo: unauthenticated2.redirectTo
+      } : {
+        allowed: false,
+        reason: "unauthenticated"
+      };
+    }
+  };
+  Reflect.defineMetadata("design:paramtypes", [
+    import_core.ModuleRef
+  ], AnyConsoleAuthorizer);
+  return AnyConsoleAuthorizer;
+}
+__name(anyAuthorize, "anyAuthorize");
 
 // src/server/console-authorize.guard.ts
 function _ts_decorate3(decorators, target, key, desc) {
@@ -1350,7 +1409,7 @@ DashboardConsoleAccess = _ts_decorate3([
   _ts_metadata3("design:type", Function),
   _ts_metadata3("design:paramtypes", [
     typeof DashboardConsoleOptions === "undefined" ? Object : DashboardConsoleOptions,
-    typeof import_core.ModuleRef === "undefined" ? Object : import_core.ModuleRef
+    typeof import_core2.ModuleRef === "undefined" ? Object : import_core2.ModuleRef
   ])
 ], DashboardConsoleAccess);
 var CONSOLE_PAGE_METADATA = "@dudousxd/nestjs-agent-dashboard:console-page";
@@ -1361,7 +1420,7 @@ var ConsoleAccessDenied = class extends import_common7.HttpException {
   }
   decision;
   page;
-  constructor(decision, page) {
+  constructor(decision, page2) {
     super(decision.reason === "forbidden" ? {
       error: "forbidden"
     } : {
@@ -1369,13 +1428,13 @@ var ConsoleAccessDenied = class extends import_common7.HttpException {
       ...decision.redirectTo !== void 0 ? {
         redirectTo: decision.redirectTo
       } : {}
-    }, decision.reason === "forbidden" ? 403 : 401), this.decision = decision, this.page = page;
+    }, decision.reason === "forbidden" ? 403 : 401), this.decision = decision, this.page = page2;
   }
 };
 function isPageNavigation(context) {
   if (context.getType() !== "http") return false;
-  const page = Reflect.getMetadata(CONSOLE_PAGE_METADATA, context.getHandler()) === true || Reflect.getMetadata(CONSOLE_PAGE_METADATA, context.getClass()) === true;
-  if (!page) return false;
+  const page2 = Reflect.getMetadata(CONSOLE_PAGE_METADATA, context.getHandler()) === true || Reflect.getMetadata(CONSOLE_PAGE_METADATA, context.getClass()) === true;
+  if (!page2) return false;
   const req = context.switchToHttp().getRequest();
   if ((req.method ?? "GET").toUpperCase() !== "GET") return false;
   const accept = req.headers?.accept;
@@ -1422,12 +1481,12 @@ var ConsoleAuthorizeFilter = class {
   catch(exception, host) {
     const adapter = this.adapterHost.httpAdapter;
     const res = host.switchToHttp().getResponse();
-    const { decision, page } = exception;
-    if (page && decision.reason === "unauthenticated" && decision.redirectTo !== void 0) {
+    const { decision, page: page2 } = exception;
+    if (page2 && decision.reason === "unauthenticated" && decision.redirectTo !== void 0) {
       adapter.redirect(res, 302, decision.redirectTo);
       return;
     }
-    if (page) {
+    if (page2) {
       const forbidden2 = decision.reason === "forbidden";
       adapter.setHeader(res, "Content-Type", "text/html; charset=utf-8");
       adapter.reply(res, forbidden2 ? FORBIDDEN_PAGE : UNAUTHENTICATED_PAGE, forbidden2 ? 403 : 401);
@@ -1441,7 +1500,7 @@ ConsoleAuthorizeFilter = _ts_decorate3([
   (0, import_common7.Injectable)(),
   _ts_metadata3("design:type", Function),
   _ts_metadata3("design:paramtypes", [
-    typeof import_core.HttpAdapterHost === "undefined" ? Object : import_core.HttpAdapterHost
+    typeof import_core2.HttpAdapterHost === "undefined" ? Object : import_core2.HttpAdapterHost
   ])
 ], ConsoleAuthorizeFilter);
 function UseConsoleAuthorize() {
@@ -1569,7 +1628,8 @@ AgentUiController = _ts_decorate4([
   ])
 ], AgentUiController);
 
-// src/server/agent-dashboard.module.ts
+// src/server/dev-tools.ts
+var import_common9 = require("@nestjs/common");
 function _ts_decorate5(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -1584,6 +1644,411 @@ function _ts_decorate5(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate5, "_ts_decorate");
+function _ts_metadata5(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata5, "_ts_metadata");
+function _ts_param5(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param5, "_ts_param");
+var DEV_TOOLS_SLOT = /* @__PURE__ */ Symbol.for("@dudousxd/aviary:dev-tools");
+function devToolsSlot() {
+  const holder = globalThis;
+  const existing = holder[DEV_TOOLS_SLOT];
+  if (existing !== void 0) return existing;
+  const libs = [];
+  const slot = {
+    version: 1,
+    libs,
+    register(lib) {
+      if (libs.some((entry) => entry.lib === lib.lib)) {
+        throw new Error(`dev tools: the lib "${lib.lib}" is already registered`);
+      }
+      libs.push(lib);
+      return () => {
+        const index = libs.indexOf(lib);
+        if (index !== -1) libs.splice(index, 1);
+      };
+    }
+  };
+  holder[DEV_TOOLS_SLOT] = slot;
+  return slot;
+}
+__name(devToolsSlot, "devToolsSlot");
+var DEFAULT_LIMIT = 20;
+var MAX_LIMIT = 100;
+var MESSAGE_LIMIT = 50;
+var MESSAGE_BYTES = 2 * 1024;
+var DAY_MS2 = 864e5;
+var ISO_DAY3 = /^\d{4}-\d{2}-\d{2}$/;
+var day = {
+  type: "string",
+  description: "UTC day, YYYY-MM-DD."
+};
+var page = {
+  type: "integer",
+  description: "Page, from 1. Pass the `next` of the previous page.",
+  minimum: 1
+};
+var limit = {
+  type: "integer",
+  description: `Rows per page (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}).`,
+  minimum: 1,
+  maximum: MAX_LIMIT
+};
+var str = /* @__PURE__ */ __name((value) => typeof value === "string" && value !== "" ? value : void 0, "str");
+function dayOf(input, key) {
+  const value = str(input[key]);
+  if (value !== void 0 && !ISO_DAY3.test(value)) throw new Error(`"${key}" must be YYYY-MM-DD`);
+  return value;
+}
+__name(dayOf, "dayOf");
+function rangeOf(input) {
+  const utcDay2 = /* @__PURE__ */ __name((daysAgo) => new Date(Date.now() - daysAgo * DAY_MS2).toISOString().slice(0, 10), "utcDay");
+  return {
+    fromDay: dayOf(input, "from") ?? utcDay2(29),
+    toDay: dayOf(input, "to") ?? utcDay2(0)
+  };
+}
+__name(rangeOf, "rangeOf");
+function pageOf(input) {
+  return {
+    page: typeof input.page === "number" ? input.page : 1,
+    pageSize: typeof input.limit === "number" ? input.limit : DEFAULT_LIMIT
+  };
+}
+__name(pageOf, "pageOf");
+function where(fields) {
+  const set = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== void 0));
+  return Object.keys(set).length > 0 ? {
+    where: set
+  } : {};
+}
+__name(where, "where");
+function listOf(result) {
+  return {
+    items: result.rows,
+    next: result.page * result.pageSize < result.total ? result.page + 1 : null,
+    total: result.total
+  };
+}
+__name(listOf, "listOf");
+function cut(text, maxBytes) {
+  const size = Buffer.byteLength(text, "utf8");
+  if (size <= maxBytes) return text;
+  const suffix = `\u2026(truncated, ${size} bytes)`;
+  const keep = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
+  let head = Buffer.from(text, "utf8").subarray(0, keep).toString("utf8");
+  if (head.endsWith("\uFFFD")) head = head.slice(0, -1);
+  return `${head}${suffix}`;
+}
+__name(cut, "cut");
+function agentDevTools(dashboard) {
+  return [
+    {
+      name: "agent_list_runs",
+      kind: "read",
+      description: "Agent runs, newest first: agent, actor, status, duration, cost, error. Filters: agent, status, errorCode, threadId, from/to (UTC days). Returns { items, next, total }; pass next as page.",
+      input: {
+        type: "object",
+        properties: {
+          agent: {
+            type: "string",
+            description: "Agent name."
+          },
+          status: {
+            type: "string",
+            enum: [
+              "running",
+              "completed",
+              "failed",
+              "cancelled"
+            ]
+          },
+          errorCode: {
+            type: "string"
+          },
+          threadId: {
+            type: "string"
+          },
+          from: day,
+          to: day,
+          page,
+          limit
+        }
+      },
+      async run(input) {
+        return listOf(await dashboard.runsPage({
+          ...pageOf(input),
+          ...where({
+            agentName: str(input.agent),
+            status: str(input.status),
+            errorCode: str(input.errorCode),
+            threadId: str(input.threadId),
+            fromDay: dayOf(input, "from"),
+            toDay: dayOf(input, "to")
+          })
+        }));
+      }
+    },
+    {
+      name: "agent_get_run",
+      kind: "read",
+      description: "One run: the run, its thread, its tool calls and timings. With includeMessages: true, the thread's latest 50 messages, each cut to 2 KB. An error when no run has that id.",
+      input: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: "Run id."
+          },
+          includeMessages: {
+            type: "boolean",
+            description: "Include messages (default false)."
+          }
+        },
+        required: [
+          "id"
+        ]
+      },
+      async run(input) {
+        let detail;
+        try {
+          detail = await dashboard.runDetail(String(input.id));
+        } catch (error) {
+          if (error instanceof import_common9.NotFoundException) throw new Error(`run ${String(input.id)} not found`);
+          throw error;
+        }
+        if (input.includeMessages !== true) return detail;
+        const thread = await dashboard.threadDetail({
+          threadId: detail.run.threadId,
+          messageLimit: MESSAGE_LIMIT,
+          runLimit: 1
+        });
+        return {
+          ...detail,
+          messages: thread.messages.map((message) => ({
+            ...message,
+            content: cut(message.content, MESSAGE_BYTES)
+          }))
+        };
+      }
+    },
+    {
+      name: "agent_get_spend",
+      kind: "read",
+      description: "Tokens and cost over UTC days from/to (default the last 30 days): by model, by actor, by feature and the daily trend. `by` returns one of them.",
+      input: {
+        type: "object",
+        properties: {
+          by: {
+            type: "string",
+            enum: [
+              "model",
+              "actor",
+              "feature"
+            ]
+          },
+          from: day,
+          to: day
+        }
+      },
+      async run(input) {
+        const spend = await dashboard.spend(rangeOf(input));
+        switch (input.by) {
+          case "model":
+            return {
+              items: spend.byModel
+            };
+          case "actor":
+            return {
+              items: spend.byActor
+            };
+          case "feature":
+            return {
+              items: spend.byFeature ?? []
+            };
+          default:
+            return spend;
+        }
+      }
+    },
+    {
+      name: "agent_get_tool_stats",
+      kind: "read",
+      description: "Per tool: calls, failures, rejections and latency, over UTC days from/to (default the last 30 days).",
+      input: {
+        type: "object",
+        properties: {
+          from: day,
+          to: day
+        }
+      },
+      async run(input) {
+        return {
+          items: await dashboard.toolStats(rangeOf(input))
+        };
+      }
+    },
+    {
+      name: "agent_get_reliability",
+      kind: "read",
+      description: "Run metrics, by-agent and by-error breakdowns and the trend, over UTC days from/to (default the last 30 days).",
+      input: {
+        type: "object",
+        properties: {
+          from: day,
+          to: day
+        }
+      },
+      async run(input) {
+        return dashboard.reliability(rangeOf(input));
+      }
+    },
+    {
+      name: "agent_list_pending_approvals",
+      kind: "read",
+      description: "Tool calls waiting for a human approval, oldest first. Read-only: approve them in the app. Returns { items, next, total }.",
+      input: {
+        type: "object",
+        properties: {
+          toolName: {
+            type: "string"
+          },
+          agent: {
+            type: "string",
+            description: "Agent name."
+          },
+          actor: {
+            type: "string",
+            description: "Actor ref of the thread owner."
+          },
+          threadId: {
+            type: "string"
+          },
+          from: day,
+          to: day,
+          page,
+          limit
+        }
+      },
+      async run(input) {
+        return listOf(await dashboard.approvalsPage({
+          ...pageOf(input),
+          ...where({
+            toolName: str(input.toolName),
+            agentName: str(input.agent),
+            actorRef: str(input.actor),
+            threadId: str(input.threadId),
+            fromDay: dayOf(input, "from"),
+            toDay: dayOf(input, "to")
+          })
+        }));
+      }
+    },
+    {
+      name: "agent_list_recent_tool_calls",
+      kind: "read",
+      description: "Tool calls of every agent, newest first. Filters: toolName, status, threadId, from/to (UTC days). Returns { items, next, total }.",
+      input: {
+        type: "object",
+        properties: {
+          toolName: {
+            type: "string"
+          },
+          status: {
+            type: "string"
+          },
+          threadId: {
+            type: "string"
+          },
+          from: day,
+          to: day,
+          page,
+          limit
+        }
+      },
+      async run(input) {
+        return listOf(await dashboard.toolCallsPage({
+          ...pageOf(input),
+          ...where({
+            toolName: str(input.toolName),
+            status: str(input.status),
+            threadId: str(input.threadId),
+            fromDay: dayOf(input, "from"),
+            toDay: dayOf(input, "to")
+          })
+        }));
+      }
+    }
+  ];
+}
+__name(agentDevTools, "agentDevTools");
+var logger2 = new import_common9.Logger("AgentDashboardModule");
+var AgentDevToolsRegistration = class {
+  static {
+    __name(this, "AgentDevToolsRegistration");
+  }
+  enabled;
+  dashboard;
+  access;
+  #unregister;
+  constructor(enabled, dashboard, access) {
+    this.enabled = enabled;
+    this.dashboard = dashboard;
+    this.access = access;
+  }
+  onModuleInit() {
+    if (!this.enabled) return;
+    const slot = devToolsSlot();
+    if (slot.version !== 1 || typeof slot.register !== "function") return;
+    try {
+      this.#unregister = slot.register({
+        lib: "agent",
+        title: "Agent governance",
+        authorize: /* @__PURE__ */ __name((context) => this.access.check(context), "authorize"),
+        tools: agentDevTools(this.dashboard)
+      });
+    } catch (error) {
+      logger2.warn(`agent dev tools not registered: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  onModuleDestroy() {
+    this.#unregister?.();
+    this.#unregister = void 0;
+  }
+};
+AgentDevToolsRegistration = _ts_decorate5([
+  (0, import_common9.Injectable)(),
+  _ts_param5(0, (0, import_common9.Inject)(DASHBOARD_DEV_TOOLS)),
+  _ts_metadata5("design:type", Function),
+  _ts_metadata5("design:paramtypes", [
+    Boolean,
+    typeof DashboardService === "undefined" ? Object : DashboardService,
+    typeof DashboardConsoleAccess === "undefined" ? Object : DashboardConsoleAccess
+  ])
+], AgentDevToolsRegistration);
+
+// src/server/agent-dashboard.module.ts
+function _ts_decorate6(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate6, "_ts_decorate");
 function normalize(path) {
   return normalizeDashboardPath(path);
 }
@@ -1591,8 +2056,8 @@ __name(normalize, "normalize");
 function consoleDecorators(decorators) {
   return [
     ...decorators ?? [],
-    (0, import_common9.UseGuards)(ConsoleAuthorizeGuard),
-    (0, import_common9.UseFilters)(ConsoleAuthorizeFilter)
+    (0, import_common10.UseGuards)(ConsoleAuthorizeGuard),
+    (0, import_common10.UseFilters)(ConsoleAuthorizeFilter)
   ];
 }
 __name(consoleDecorators, "consoleDecorators");
@@ -1626,7 +2091,12 @@ var AgentApiModule = class _AgentApiModule {
           provide: DASHBOARD_CONSOLE_OPTIONS,
           useValue: consoleOptions
         },
-        DashboardConsoleAccess
+        DashboardConsoleAccess,
+        {
+          provide: DASHBOARD_DEV_TOOLS,
+          useValue: options.devTools ?? options.routes !== false
+        },
+        AgentDevToolsRegistration
       ],
       // What a self-mounted `AgentApiController` subclass injects, too (`routes: false`), and the
       // access check `UseConsoleAuthorize()` runs.
@@ -1638,8 +2108,8 @@ var AgentApiModule = class _AgentApiModule {
     };
   }
 };
-AgentApiModule = _ts_decorate5([
-  (0, import_common9.Module)({})
+AgentApiModule = _ts_decorate6([
+  (0, import_common10.Module)({})
 ], AgentApiModule);
 var AgentDashboardModule = class _AgentDashboardModule {
   static {
@@ -1668,10 +2138,13 @@ var AgentDashboardModule = class _AgentDashboardModule {
           } : {},
           ...options.authorize !== void 0 ? {
             authorize: options.authorize
+          } : {},
+          ...options.devTools !== void 0 ? {
+            devTools: options.devTools
           } : {}
         }),
         ...options.routes === false ? [] : [
-          import_core2.RouterModule.register([
+          import_core3.RouterModule.register([
             {
               path: basePath,
               module: _AgentDashboardModule
@@ -1706,8 +2179,8 @@ var AgentDashboardModule = class _AgentDashboardModule {
     };
   }
 };
-AgentDashboardModule = _ts_decorate5([
-  (0, import_common9.Module)({})
+AgentDashboardModule = _ts_decorate6([
+  (0, import_common10.Module)({})
 ], AgentDashboardModule);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -1719,6 +2192,7 @@ AgentDashboardModule = _ts_decorate5([
   AgentApiController,
   AgentApiModule,
   AgentDashboardModule,
+  AgentDevToolsRegistration,
   AgentUiController,
   CONSOLE_AUTHORIZE_MISSING_WARNING,
   CONSOLE_GATE,
@@ -1731,10 +2205,13 @@ AgentDashboardModule = _ts_decorate5([
   DASHBOARD_APPROVAL_ACTOR_REF,
   DASHBOARD_BASE_PATH,
   DASHBOARD_CONSOLE_OPTIONS,
+  DASHBOARD_DEV_TOOLS,
   DashboardConsoleAccess,
   DashboardService,
   UseConsoleAuthorize,
   agentDashboardMountPaths,
+  agentDevTools,
+  anyAuthorize,
   authorizeByToken,
   normalizeConsoleResult,
   parsePriceInput,