@adonis-agora/agent 0.20.0 → 0.22.0

package/dist/src/dashboard/define_config.js

@@ -0,0 +1,56 @@
+/** Fill defaults for the optional dashboard config block. */
+export function resolveDashboardConfig(config) {
+    const resolved = { enabled: config?.enabled ?? true };
+    if (config?.path !== undefined)
+        resolved.path = config.path;
+    if (config?.authorize !== undefined)
+        resolved.authorize = config.authorize;
+    return resolved;
+}
+/**
+ * The exact wording the provider logs when it declines to mount. Mirrors the agent provider's own
+ * governance boot warning — same three facts, same vocabulary — so a reader who sees one recognises
+ * the other.
+ */
+const NO_GOVERNANCE_GATE_WARNING = '[@adonis-agora/agent-dashboard] the governance console was NOT mounted: every panel but Quota reads the cross-actor `/agent/governance/*` routes, and those are themselves not mounted because no `governanceAuthorize` gate is configured — so the console would load and then fail on every panel. Set `governanceAuthorize` in config/agent.ts (e.g. an ADMIN check) to mount the routes and this console gated, or `governanceAuthorize: () => true` to deliberately restore the old behaviour of letting ANY authenticated actor read them. `GET /agent/approvals/mine` is unaffected — it stays mounted and scoped to the calling actor. To keep the console off on purpose and silence this, set `dashboard: { enabled: false }`.';
+/**
+ * The wording logged when the read-model itself was turned off. Deliberately distinct from
+ * {@link NO_GOVERNANCE_GATE_WARNING}: both produce the same dead console, and an operator staring at
+ * a 404 must be able to tell from the log ALONE which of the two knobs is responsible. A shared
+ * "governance is not configured" message would recreate exactly the diagnosability problem this
+ * check exists to remove.
+ */
+const NO_GOVERNANCE_QUERIES_WARNING = '[@adonis-agora/agent-dashboard] the governance console was NOT mounted: `governanceQueries` is set to `false` in config/agent.ts, so the cross-actor read-model was never built and the `/agent/governance/*` routes it serves do not exist — the console would load and then fail on every panel but Quota. A `governanceAuthorize` gate is NOT the missing piece here; it is already configured. Remove `governanceQueries: false` (omit it to get the Lucid read-model when the main store is Lucid, or pass a store/factory explicitly) to mount the read-model and this console. To keep the console off on purpose and silence this, set `dashboard: { enabled: false }`.';
+/**
+ * Decide whether to register the console's routes at all — the router-free core of the provider's
+ * mount check, extracted so it can be unit tested without booting an app.
+ *
+ * The console is a pure consumer of the agent's cross-actor `/agent/governance/*` read routes, and
+ * those routes are not mounted unless the agent config carries a `governanceAuthorize` gate. Serving
+ * a shell that can only 404 its own data is worse than not serving it: the failure shows up as seven
+ * dead panels at click time with nothing anywhere explaining why. So the console follows the same
+ * fail-closed-by-omission rule one layer down — no gate, no routes — and says so at boot.
+ *
+ * This costs nothing that still works: every app affected is an app whose console is ALREADY dead in
+ * every view but Quota. `dashboard.authorize` is deliberately NOT the trigger; it gates the shell,
+ * not the data, and an app can set it and still have a console with nothing to render.
+ */
+export function decideDashboardMount(enabled, governanceAuthorize, governanceQueries) {
+    if (!enabled)
+        return { mount: false, reason: 'disabled' };
+    if (governanceAuthorize === undefined) {
+        return { mount: false, reason: 'no-governance-gate', warning: NO_GOVERNANCE_GATE_WARNING };
+    }
+    // ONLY an explicit `false` is decidable here. `undefined` does NOT mean "no read-model": the agent
+    // provider's `#resolveGovernance` defaults it to the Lucid read-model whenever the main store is
+    // Lucid, and reproducing that resolution would duplicate provider logic in the dashboard.
+    if (governanceQueries === false) {
+        return {
+            mount: false,
+            reason: 'no-governance-queries',
+            warning: NO_GOVERNANCE_QUERIES_WARNING,
+        };
+    }
+    return { mount: true };
+}
+//# sourceMappingURL=define_config.js.map

package/dist/src/dashboard/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/dashboard/define_config.ts"],"names":[],"mappings":"AAiDA,6DAA6D;AAC7D,MAAM,UAAU,sBAAsB,CACpC,MAAwC;IAExC,MAAM,QAAQ,GAAiC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,IAAI,EAAE,CAAC;IACpF,IAAI,MAAM,EAAE,IAAI,KAAK,SAAS;QAAE,QAAQ,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC5D,IAAI,MAAM,EAAE,SAAS,KAAK,SAAS;QAAE,QAAQ,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IAC3E,OAAO,QAAQ,CAAC;AAClB,CAAC;AASD;;;;GAIG;AACH,MAAM,0BAA0B,GAC9B,0sBAA0sB,CAAC;AAE7sB;;;;;;GAMG;AACH,MAAM,6BAA6B,GACjC,ipBAAipB,CAAC;AAEppB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAgB,EAChB,mBAAyD,EACzD,iBAA2B;IAE3B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC1D,IAAI,mBAAmB,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;IAC7F,CAAC;IACD,mGAAmG;IACnG,iGAAiG;IACjG,0FAA0F;IAC1F,IAAI,iBAAiB,KAAK,KAAK,EAAE,CAAC;QAChC,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,uBAAuB;YAC/B,OAAO,EAAE,6BAA6B;SACvC,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/src/dashboard/gate.d.ts

@@ -0,0 +1,33 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ActorResolver } from '../spi/actor-resolver.js';
+import type { AgentDashboardAuthorize } from './define_config.js';
+/** The outcome of the dashboard access gate: proceed, or deny with an HTTP status + message. */
+export type DashboardGateVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    status: 401 | 403;
+    error: string;
+};
+/**
+ * Decide whether a request may reach the dashboard, WITHOUT touching the response — so it is unit
+ * testable free of the AdonisJS router/app: resolve the actor through the agent config's resolver
+ * (missing/failed → `401`), then run the optional `authorize` gate over the resolved actor
+ * (denied/threw → `403`).
+ *
+ * This gates the SPA **shell**, and only the shell. It is NOT what decides whether the console's data
+ * is readable, and it is no longer the last line of defence it once had to be:
+ *
+ * - Whether the console mounts at all is decided earlier, by {@link decideDashboardMount} — the
+ *   routes are not registered unless the agent config carries a `governanceAuthorize` gate AND its
+ *   `governanceQueries` read-model exists. So this function never runs for a console that could only
+ *   404 its own panels.
+ * - Whether the DATA is readable is decided by the agent's own `governanceAuthorize` on the
+ *   `/agent/governance/*` routes, not here. Omitting `authorize` while a gate is configured leaves
+ *   the shell open to any resolved actor but exposes no cross-actor data.
+ *
+ * Omitting BOTH the resolver and `authorize` would expose the shell to any request; the provider is
+ * expected to short-circuit on a missing resolver via the `401` here.
+ */
+export declare function evaluateDashboardGate(ctx: HttpContext, actorResolver: ActorResolver | undefined, authorize?: AgentDashboardAuthorize): Promise<DashboardGateVerdict>;
+//# sourceMappingURL=gate.d.ts.map

package/dist/src/dashboard/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/dashboard/gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElE,gGAAgG;AAChG,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,WAAW,EAChB,aAAa,EAAE,aAAa,GAAG,SAAS,EACxC,SAAS,CAAC,EAAE,uBAAuB,GAClC,OAAO,CAAC,oBAAoB,CAAC,CA4B/B"}

package/dist/src/dashboard/gate.js

@@ -0,0 +1,52 @@
+/**
+ * Decide whether a request may reach the dashboard, WITHOUT touching the response — so it is unit
+ * testable free of the AdonisJS router/app: resolve the actor through the agent config's resolver
+ * (missing/failed → `401`), then run the optional `authorize` gate over the resolved actor
+ * (denied/threw → `403`).
+ *
+ * This gates the SPA **shell**, and only the shell. It is NOT what decides whether the console's data
+ * is readable, and it is no longer the last line of defence it once had to be:
+ *
+ * - Whether the console mounts at all is decided earlier, by {@link decideDashboardMount} — the
+ *   routes are not registered unless the agent config carries a `governanceAuthorize` gate AND its
+ *   `governanceQueries` read-model exists. So this function never runs for a console that could only
+ *   404 its own panels.
+ * - Whether the DATA is readable is decided by the agent's own `governanceAuthorize` on the
+ *   `/agent/governance/*` routes, not here. Omitting `authorize` while a gate is configured leaves
+ *   the shell open to any resolved actor but exposes no cross-actor data.
+ *
+ * Omitting BOTH the resolver and `authorize` would expose the shell to any request; the provider is
+ * expected to short-circuit on a missing resolver via the `401` here.
+ */
+export async function evaluateDashboardGate(ctx, actorResolver, authorize) {
+    if (actorResolver === undefined) {
+        return { ok: false, status: 401, error: 'no actor resolver configured' };
+    }
+    let actor;
+    try {
+        actor = await actorResolver.resolve(ctx);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 401,
+            error: error instanceof Error ? error.message : 'unauthorized',
+        };
+    }
+    if (authorize !== undefined) {
+        try {
+            if (!(await authorize(actor, ctx))) {
+                return { ok: false, status: 403, error: 'forbidden' };
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                status: 403,
+                error: error instanceof Error ? error.message : 'forbidden',
+            };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=gate.js.map

package/dist/src/dashboard/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/dashboard/gate.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAgB,EAChB,aAAwC,EACxC,SAAmC;IAEnC,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC;IAC3E,CAAC;IACD,IAAI,KAAoD,CAAC;IACzD,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc;SAC/D,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;gBACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;YACxD,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW;aAC5D,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/src/dashboard/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Serving helpers for the `@adonis-agora/agent-dashboard` governance SPA — the config shape, the
+ * mount/gate decisions, and the pure path/asset helpers. Framework-light (no AdonisJS router/app
+ * dependency), so they're unit-testable in isolation and reusable by BOTH dashboard providers:
+ *
+ * - `@adonis-agora/agent/dashboard_provider` (this package, `providers/dashboard_provider.ts`) —
+ *   embedded: registered automatically by `node ace configure @adonis-agora/agent`, serves the SPA
+ *   bundle copied into THIS package's own `dist/assets/spa` at build time.
+ * - `@adonis-agora/agent-dashboard`'s own provider (`agent_dashboard_provider.ts`) — standalone: an
+ *   independently installable/registrable package some apps already depend on directly.
+ *
+ * Living here (rather than in `@adonis-agora/agent-dashboard`) keeps the dependency direction
+ * one-way: the dashboard package already depends on this one for `AgentConfig`/`ActorResolver`/etc.,
+ * so a package.json edge back from here to there would be circular. See
+ * `providers/dashboard_provider.ts`'s module doc for the full story.
+ */
+export { type AgentDashboardAuthorize, type AgentDashboardConfig, type DashboardMountDecision, type ResolvedAgentDashboardConfig, decideDashboardMount, resolveDashboardConfig, } from './define_config.js';
+export { type DashboardGateVerdict, evaluateDashboardGate } from './gate.js';
+export { apiBaseFor, contentTypeFor, injectApiBase, injectBaseHref, mountPathFor, safeAssetSegments, trimSlashes, } from './paths.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/dashboard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,UAAU,EACV,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/src/dashboard/index.js

@@ -0,0 +1,20 @@
+/**
+ * Serving helpers for the `@adonis-agora/agent-dashboard` governance SPA — the config shape, the
+ * mount/gate decisions, and the pure path/asset helpers. Framework-light (no AdonisJS router/app
+ * dependency), so they're unit-testable in isolation and reusable by BOTH dashboard providers:
+ *
+ * - `@adonis-agora/agent/dashboard_provider` (this package, `providers/dashboard_provider.ts`) —
+ *   embedded: registered automatically by `node ace configure @adonis-agora/agent`, serves the SPA
+ *   bundle copied into THIS package's own `dist/assets/spa` at build time.
+ * - `@adonis-agora/agent-dashboard`'s own provider (`agent_dashboard_provider.ts`) — standalone: an
+ *   independently installable/registrable package some apps already depend on directly.
+ *
+ * Living here (rather than in `@adonis-agora/agent-dashboard`) keeps the dependency direction
+ * one-way: the dashboard package already depends on this one for `AgentConfig`/`ActorResolver`/etc.,
+ * so a package.json edge back from here to there would be circular. See
+ * `providers/dashboard_provider.ts`'s module doc for the full story.
+ */
+export { decideDashboardMount, resolveDashboardConfig, } from './define_config.js';
+export { evaluateDashboardGate } from './gate.js';
+export { apiBaseFor, contentTypeFor, injectApiBase, injectBaseHref, mountPathFor, safeAssetSegments, trimSlashes, } from './paths.js';
+//# sourceMappingURL=index.js.map

package/dist/src/dashboard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAKL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAA6B,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EACL,UAAU,EACV,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/src/dashboard/paths.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure path/asset helpers for serving the `@adonis-agora/agent-dashboard` governance SPA — extracted
+ * so they can be unit-tested without booting an AdonisJS app. Both dashboard providers compose these;
+ * each holds only the router wiring + I/O. Owned here (rather than in `@adonis-agora/agent-dashboard`)
+ * so `packages/adonis`'s OWN embedded dashboard provider (`providers/dashboard_provider.ts`) can reuse
+ * them without depending on the dashboard package at runtime — the dashboard package already depends
+ * on THIS one (for `AgentConfig`/`ActorResolver`/...), and a package.json edge the other way would be
+ * circular. See `providers/dashboard_provider.ts`'s module doc for the full story.
+ */
+/** Collapse duplicate slashes and strip leading/trailing ones: `/agent//` → `agent`. */
+export declare function trimSlashes(path: string): string;
+/** The agent API base as an absolute path with a single leading slash: `agent` → `/agent`. */
+export declare function apiBaseFor(agentPath: string): string;
+/**
+ * The canonical dashboard mount path (no trailing slash), default `<agentPath>/dashboard`. A caller
+ * may override with an explicit `dashboardPath`; both are normalized to a single leading slash.
+ */
+export declare function mountPathFor(agentPath: string, dashboardPath?: string): string;
+/** MIME type for a filename by extension; `application/octet-stream` for anything unknown. */
+export declare function contentTypeFor(filename: string): string;
+/**
+ * Reject a wildcard asset request that tries to escape the SPA root via `..` or an absolute path.
+ * Returns the safe, normalized relative segments (never starting with `..`), or `null` to deny.
+ */
+export declare function safeAssetSegments(wildcard: string | string[] | undefined): string[] | null;
+/**
+ * Inject the resolved agent API base into the served `index.html` as a global the SPA reads before
+ * boot, so the client calls the exact base the provider mounted (no build-time coupling). Idempotent
+ * per response — inserted right before `</head>`.
+ */
+export declare function injectApiBase(html: string, apiBase: string): string;
+/**
+ * Inject a `<base href="${mount}/">` as the FIRST thing inside `<head>`, so the SPA's relative
+ * `./assets/*` URLs (Vite `base: './'`) resolve against the mount directory no matter whether the
+ * browser's URL carries a trailing slash. This replaces the old trailing-slash redirect, which the
+ * AdonisJS router (it normalizes trailing slashes) turned into a duplicate-route crash. `mount` is a
+ * leading-slash, no-trailing-slash path (e.g. `/agent/dashboard`).
+ */
+export declare function injectBaseHref(html: string, mount: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/src/dashboard/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/dashboard/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,8FAA8F;AAC9F,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAM9E;AAsBD,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,CAU1F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQlE"}

package/dist/src/dashboard/paths.js

@@ -0,0 +1,99 @@
+/**
+ * Pure path/asset helpers for serving the `@adonis-agora/agent-dashboard` governance SPA — extracted
+ * so they can be unit-tested without booting an AdonisJS app. Both dashboard providers compose these;
+ * each holds only the router wiring + I/O. Owned here (rather than in `@adonis-agora/agent-dashboard`)
+ * so `packages/adonis`'s OWN embedded dashboard provider (`providers/dashboard_provider.ts`) can reuse
+ * them without depending on the dashboard package at runtime — the dashboard package already depends
+ * on THIS one (for `AgentConfig`/`ActorResolver`/...), and a package.json edge the other way would be
+ * circular. See `providers/dashboard_provider.ts`'s module doc for the full story.
+ */
+/** Collapse duplicate slashes and strip leading/trailing ones: `/agent//` → `agent`. */
+export function trimSlashes(path) {
+    return path.replace(/\/+/g, '/').replace(/^\/+|\/+$/g, '');
+}
+/** The agent API base as an absolute path with a single leading slash: `agent` → `/agent`. */
+export function apiBaseFor(agentPath) {
+    const trimmed = trimSlashes(agentPath);
+    return trimmed === '' ? '/' : `/${trimmed}`;
+}
+/**
+ * The canonical dashboard mount path (no trailing slash), default `<agentPath>/dashboard`. A caller
+ * may override with an explicit `dashboardPath`; both are normalized to a single leading slash.
+ */
+export function mountPathFor(agentPath, dashboardPath) {
+    if (dashboardPath !== undefined && trimSlashes(dashboardPath) !== '') {
+        return `/${trimSlashes(dashboardPath)}`;
+    }
+    const trimmed = trimSlashes(agentPath);
+    return trimmed === '' ? '/dashboard' : `/${trimmed}/dashboard`;
+}
+const CONTENT_TYPES = {
+    html: 'text/html; charset=utf-8',
+    js: 'text/javascript; charset=utf-8',
+    mjs: 'text/javascript; charset=utf-8',
+    css: 'text/css; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    ico: 'image/x-icon',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    ttf: 'font/ttf',
+    map: 'application/json; charset=utf-8',
+    txt: 'text/plain; charset=utf-8',
+};
+/** MIME type for a filename by extension; `application/octet-stream` for anything unknown. */
+export function contentTypeFor(filename) {
+    const dot = filename.lastIndexOf('.');
+    const ext = dot === -1 ? '' : filename.slice(dot + 1).toLowerCase();
+    return CONTENT_TYPES[ext] ?? 'application/octet-stream';
+}
+/**
+ * Reject a wildcard asset request that tries to escape the SPA root via `..` or an absolute path.
+ * Returns the safe, normalized relative segments (never starting with `..`), or `null` to deny.
+ */
+export function safeAssetSegments(wildcard) {
+    const parts = Array.isArray(wildcard) ? wildcard : (wildcard ?? '').split('/');
+    const segments = [];
+    for (const raw of parts) {
+        const part = raw.trim();
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..' || part.includes('\0') || part.includes('\\'))
+            return null;
+        segments.push(part);
+    }
+    return segments;
+}
+/**
+ * Inject the resolved agent API base into the served `index.html` as a global the SPA reads before
+ * boot, so the client calls the exact base the provider mounted (no build-time coupling). Idempotent
+ * per response — inserted right before `</head>`.
+ */
+export function injectApiBase(html, apiBase) {
+    const tag = `<script>window.__AGENT_DASHBOARD_BASE__=${JSON.stringify(apiBase)}</script>`;
+    if (html.includes('</head>'))
+        return html.replace('</head>', `${tag}</head>`);
+    return `${tag}${html}`;
+}
+/**
+ * Inject a `<base href="${mount}/">` as the FIRST thing inside `<head>`, so the SPA's relative
+ * `./assets/*` URLs (Vite `base: './'`) resolve against the mount directory no matter whether the
+ * browser's URL carries a trailing slash. This replaces the old trailing-slash redirect, which the
+ * AdonisJS router (it normalizes trailing slashes) turned into a duplicate-route crash. `mount` is a
+ * leading-slash, no-trailing-slash path (e.g. `/agent/dashboard`).
+ */
+export function injectBaseHref(html, mount) {
+    const tag = `<base href="${mount}/">`;
+    const headOpen = html.match(/<head[^>]*>/i);
+    if (headOpen?.index !== undefined) {
+        const at = headOpen.index + headOpen[0].length;
+        return html.slice(0, at) + tag + html.slice(at);
+    }
+    return `${tag}${html}`;
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/dashboard/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/dashboard/paths.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.20.0";
+export declare const VERSION = "0.22.0";
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.20.0';
+export const VERSION = '0.22.0';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/telescope/agent-governance-providers.d.ts

@@ -0,0 +1,67 @@
+import type { DataProvider } from './telescope-sdk.js';
+/** Shift a `YYYY-MM-DD` UTC day by `deltaDays` (negative goes back in time). */
+export declare function shiftUtcDay(day: string, deltaDays: number): string;
+/**
+ * Derive the query range: honour explicit `fromDay`/`toDay` (validated ISO days), otherwise default
+ * to the trailing {@link DEFAULT_TREND_WINDOW_DAYS}-day window ending today (UTC).
+ */
+export declare function resolveRange(query: Record<string, unknown> | undefined): {
+    fromDay: string;
+    toDay: string;
+};
+/** Cap a run's error message to {@link ERROR_MESSAGE_CAP} characters. `resolve()` output bypasses
+ * Telescope's entry redaction pipeline (that only runs on Watcher-recorded entries) — this cap is a
+ * stopgap so an unbounded stack trace never rides straight into a table cell unbounded. */
+export declare function capErrorMessage(message: string | null): string;
+/** stat → authoritative total spend (USD) over the range. */
+export declare function agentSpendTotalProvider(): DataProvider;
+/** stat → authoritative total tokens (input + output) over the range. */
+export declare function agentTokensTotalProvider(): DataProvider;
+/** breakdown → spend share per model (models with zero cost dropped from the donut). */
+export declare function agentSpendByModelProvider(): DataProvider;
+/** table → per-model requests / in+out tokens / cost. */
+export declare function agentModelSpendTableProvider(): DataProvider;
+/** timeseries → daily spend + tokens trend. */
+export declare function agentUsageTrendProvider(): DataProvider;
+/** table → spend per acting ref (user/tenant). */
+export declare function agentActorSpendTableProvider(): DataProvider;
+/** breakdown → spend share per actor (actors with zero cost dropped). */
+export declare function agentSpendByActorProvider(): DataProvider;
+/** stat → total runs over the range. */
+export declare function agentRunsTotalProvider(): DataProvider;
+/** stat → completed/total success rate over the range. */
+export declare function agentRunsSuccessRateProvider(): DataProvider;
+/** stat → failed run count over the range. */
+export declare function agentRunsFailedProvider(): DataProvider;
+/**
+ * stat → MEAN settled-run duration over the range. Not a percentile: `RunReliability` exposes only
+ * `avgDurationMs` (see this file's header) — there is no p50/p95 to select between, unlike the Nest
+ * reference's `query.metric` switch. `null` (no settled runs) resolves to 0.
+ */
+export declare function agentRunsDurationProvider(): DataProvider;
+/** table → run/failure rollup per agent (empty when the adapter predates `byAgent`). */
+export declare function agentRunsByAgentTableProvider(): DataProvider;
+/** timeseries → daily runs + failures trend (empty when the adapter predates `trend`). */
+export declare function agentRunsTrendProvider(): DataProvider;
+/** table → most recent runs (newest first), via `listRuns`' first page — see this file's header for
+ * why this isn't the paged-table protocol. errorMessage capped per {@link capErrorMessage}. */
+export declare function agentRecentRunsTableProvider(): DataProvider;
+/** table → most recent tool calls (newest first), from the durable read-model. */
+export declare function agentRecentToolCallsTableProvider(): DataProvider;
+/** table → most recently active threads, with rolled-up message/token counts. */
+export declare function agentRecentThreadsTableProvider(): DataProvider;
+/**
+ * stat → an APPROXIMATE count of tool calls sitting `pending_approval`, capped at
+ * {@link MAX_RECENT_LIMIT}. `AgentGovernanceQueries.pendingApprovals` has no `total` — unlike the
+ * Nest reference's exact `approvalsPage({ page: 1, pageSize: 1 }).total`, there is no cheap "how
+ * many, without listing them" query on this SPI (see this file's header). A backlog past the cap
+ * undercounts here exactly the way Nest's OLD `pendingApprovals(500).length` did before it got an
+ * exact query — that regression is accepted, not fixed, until `AgentGovernanceQueries` grows one.
+ */
+export declare function agentPendingApprovalsCountProvider(): DataProvider;
+/** table → the pending-approvals inbox, oldest request first. */
+export declare function agentPendingApprovalsTableProvider(): DataProvider;
+/** table → per-tool call/failure/rejection/latency rollup over the range. Only ONE latency column
+ * (`avgDurationMs`) — `PerToolStatRow` has no p50/p95 split, unlike the Nest reference's table. */
+export declare function agentToolStatsTableProvider(): DataProvider;
+//# sourceMappingURL=agent-governance-providers.d.ts.map

package/dist/src/telescope/agent-governance-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-governance-providers.d.ts","sourceRoot":"","sources":["../../../src/telescope/agent-governance-providers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AA4DzE,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,CAOA;AA+BD;;2FAE2F;AAC3F,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAG9D;AA2CD,6DAA6D;AAC7D,wBAAgB,uBAAuB,IAAI,YAAY,CAStD;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,IAAI,YAAY,CASvD;AAED,wFAAwF;AACxF,wBAAgB,yBAAyB,IAAI,YAAY,CAWxD;AAED,yDAAyD;AACzD,wBAAgB,4BAA4B,IAAI,YAAY,CAS3D;AAED,+CAA+C;AAC/C,wBAAgB,uBAAuB,IAAI,YAAY,CAetD;AAED,kDAAkD;AAClD,wBAAgB,4BAA4B,IAAI,YAAY,CAS3D;AAED,yEAAyE;AACzE,wBAAgB,yBAAyB,IAAI,YAAY,CAWxD;AAgED,wCAAwC;AACxC,wBAAgB,sBAAsB,IAAI,YAAY,CAErD;AAED,0DAA0D;AAC1D,wBAAgB,4BAA4B,IAAI,YAAY,CAI3D;AAED,8CAA8C;AAC9C,wBAAgB,uBAAuB,IAAI,YAAY,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,YAAY,CAIxD;AAED,wFAAwF;AACxF,wBAAgB,6BAA6B,IAAI,YAAY,CAU5D;AAED,0FAA0F;AAC1F,wBAAgB,sBAAsB,IAAI,YAAY,CAMrD;AA+BD;+FAC+F;AAC/F,wBAAgB,4BAA4B,IAAI,YAAY,CA0B3D;AAED,kFAAkF;AAClF,wBAAgB,iCAAiC,IAAI,YAAY,CAOhE;AAED,iFAAiF;AACjF,wBAAgB,+BAA+B,IAAI,YAAY,CAO9D;AAWD;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,IAAI,YAAY,CAUjE;AAED,iEAAiE;AACjE,wBAAgB,kCAAkC,IAAI,YAAY,CA2BjE;AAWD;mGACmG;AACnG,wBAAgB,2BAA2B,IAAI,YAAY,CA2B1D"}