@agent-native/dispatch 0.16.1 → 0.16.3

package/dist/server/plugins/agent-chat.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-chat.js","sourceRoot":"","sources":["../../../src/server/plugins/agent-chat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,kBAAkB,GAAG;IACzB,aAAa;IACb,qBAAqB;IACrB,uBAAuB;IACvB,SAAS;IACT,UAAU;IACV,0BAA0B;IAC1B,2BAA2B;IAC3B,2BAA2B;IAC3B,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,aAAa;IACb,8BAA8B;IAC9B,oCAAoC;IACpC,sBAAsB;IACtB,mBAAmB;IACnB,sBAAsB;IACtB,sBAAsB;IACtB,UAAU;CACX,CAAC;AAEF,eAAe,qBAAqB,CAAC;IACnC,KAAK,EAAE,UAAU;IACjB,gBAAgB,EAAE,kBAAkB;IACpC,gBAAgB,EAAE,CAAC,oCAAoC,CAAC;IACxD,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,OAAO,EAAE,eAAe;IACxB,aAAa,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE;IAC1C,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;4EAwB4D;CAC3E,CAAC,CAAC","sourcesContent":["import { getOrgContext } from \"@agent-native/core/org\";\nimport { createAgentChatPlugin } from \"@agent-native/core/server\";\n\nimport { dispatchActions } from \"../../actions/index.js\";\n\nconst INITIAL_TOOL_NAMES = [\n  \"view-screen\",\n  \"list-workspace-apps\",\n  \"list-connected-agents\",\n  \"ask_app\",\n  \"open_app\",\n  \"list-workspace-resources\",\n  \"create-workspace-resource\",\n  \"update-workspace-resource\",\n  \"list-vault-secrets\",\n  \"request-vault-secret\",\n  \"create-vault-secret\",\n  \"list-destinations\",\n  \"upsert-destination\",\n  \"list-dreams\",\n  \"start-workspace-app-creation\",\n  \"list-available-workspace-templates\",\n  \"provider-api-catalog\",\n  \"provider-api-docs\",\n  \"provider-api-request\",\n  \"query-staged-dataset\",\n  \"navigate\",\n];\n\nexport default createAgentChatPlugin({\n  appId: \"dispatch\",\n  initialToolNames: INITIAL_TOOL_NAMES,\n  connectorCatalog: [\"resolve-integration-source-context\"],\n  // Without this, AGENT_ORG_ID is never set on agent action calls and every\n  // row written through the frontend (vault secrets, destinations, workspace\n  // resources) lands with org_id=NULL — breaking data isolation across orgs.\n  resolveOrgId: async (event) => {\n    const ctx = await getOrgContext(event);\n    return ctx.orgId;\n  },\n  // Read actions directly from the package's own action map rather than from\n  // a build-time-generated `.generated/actions-registry.ts` (the latter is a\n  // template-only construct that the Vite plugin emits next to actions/).\n  actions: dispatchActions,\n  codeExecution: { production: \"sandboxed\" },\n  systemPrompt: `You are the central dispatch for this workspace.\n\nDefault posture:\n- Treat Slack and Telegram as shared entrypoints into the workspace.\n- Heavily delegate domain work to specialized agents through A2A when another app owns the job.\n- Keep durable memory and operating instructions in resources rather than ephemeral chat.\n- Prefer replying in the current external thread unless the user explicitly asks you to send to a saved destination.\n\nUse the standard workspace primitives:\n- Read and update resources like AGENTS.md, LEARNINGS.md, jobs/*.md, agents/*.md, and remote-agents/*.json when appropriate.\n- Use recurring jobs for scheduled behavior.\n- Use custom agent profiles in agents/*.md for local spawned work and remote-agents/*.json for remote A2A apps.\n- You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.\n- Hosted/connected A2A neighbors such as Analytics and Content come from the available-apps context or list-connected-agents. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.\n- When answering whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.\n- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.\n- If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible \"Chat\", \"Starter\", \"Blank app\", or \"New app\" UI behind.\n- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.\n- Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.\n- For broad provider searches, joins, classification, corpus counts, or absence claims, fetch every relevant page or an explicitly bounded cohort, stage/save large responses with stageAs/saveToFile/fetchAllPages, and reduce them with query-staged-dataset or run-code. Report source, filters, row counts, pagination, truncation, failed pages, and uncovered gaps.\n\nWhen a user asks for something like a digest, reminder, routing rule, or saved behavior:\n- First decide whether it should be a resource, a recurring job, a destination, or a delegated task.\n- Keep responses concise and operational.\n- Avoid inventing integrations or destinations that are not configured yet.`,\n});\n"]}
+{"version":3,"file":"agent-chat.js","sourceRoot":"","sources":["../../../src/server/plugins/agent-chat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,kBAAkB,GAAG;IACzB,aAAa;IACb,qBAAqB;IACrB,uBAAuB;IACvB,SAAS;IACT,UAAU;IACV,0BAA0B;IAC1B,2BAA2B;IAC3B,2BAA2B;IAC3B,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,aAAa;IACb,8BAA8B;IAC9B,oCAAoC;IACpC,sBAAsB;IACtB,mBAAmB;IACnB,sBAAsB;IACtB,sBAAsB;IACtB,UAAU;CACX,CAAC;AAEF,eAAe,qBAAqB,CAAC;IACnC,KAAK,EAAE,UAAU;IACjB,qBAAqB,EAAE,IAAI;IAC3B,gBAAgB,EAAE,kBAAkB;IACpC,gBAAgB,EAAE,CAAC,oCAAoC,CAAC;IACxD,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,OAAO,EAAE,eAAe;IACxB,aAAa,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE;IAC1C,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;4EAwB4D;CAC3E,CAAC,CAAC","sourcesContent":["import { getOrgContext } from \"@agent-native/core/org\";\nimport { createAgentChatPlugin } from \"@agent-native/core/server\";\n\nimport { dispatchActions } from \"../../actions/index.js\";\n\nconst INITIAL_TOOL_NAMES = [\n  \"view-screen\",\n  \"list-workspace-apps\",\n  \"list-connected-agents\",\n  \"ask_app\",\n  \"open_app\",\n  \"list-workspace-resources\",\n  \"create-workspace-resource\",\n  \"update-workspace-resource\",\n  \"list-vault-secrets\",\n  \"request-vault-secret\",\n  \"create-vault-secret\",\n  \"list-destinations\",\n  \"upsert-destination\",\n  \"list-dreams\",\n  \"start-workspace-app-creation\",\n  \"list-available-workspace-templates\",\n  \"provider-api-catalog\",\n  \"provider-api-docs\",\n  \"provider-api-request\",\n  \"query-staged-dataset\",\n  \"navigate\",\n];\n\nexport default createAgentChatPlugin({\n  appId: \"dispatch\",\n  durableBackgroundRuns: true,\n  initialToolNames: INITIAL_TOOL_NAMES,\n  connectorCatalog: [\"resolve-integration-source-context\"],\n  // Without this, AGENT_ORG_ID is never set on agent action calls and every\n  // row written through the frontend (vault secrets, destinations, workspace\n  // resources) lands with org_id=NULL — breaking data isolation across orgs.\n  resolveOrgId: async (event) => {\n    const ctx = await getOrgContext(event);\n    return ctx.orgId;\n  },\n  // Read actions directly from the package's own action map rather than from\n  // a build-time-generated `.generated/actions-registry.ts` (the latter is a\n  // template-only construct that the Vite plugin emits next to actions/).\n  actions: dispatchActions,\n  codeExecution: { production: \"sandboxed\" },\n  systemPrompt: `You are the central dispatch for this workspace.\n\nDefault posture:\n- Treat Slack and Telegram as shared entrypoints into the workspace.\n- Heavily delegate domain work to specialized agents through A2A when another app owns the job.\n- Keep durable memory and operating instructions in resources rather than ephemeral chat.\n- Prefer replying in the current external thread unless the user explicitly asks you to send to a saved destination.\n\nUse the standard workspace primitives:\n- Read and update resources like AGENTS.md, LEARNINGS.md, jobs/*.md, agents/*.md, and remote-agents/*.json when appropriate.\n- Use recurring jobs for scheduled behavior.\n- Use custom agent profiles in agents/*.md for local spawned work and remote-agents/*.json for remote A2A apps.\n- You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.\n- Hosted/connected A2A neighbors such as Analytics and Content come from the available-apps context or list-connected-agents. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.\n- When answering whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.\n- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.\n- If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible \"Chat\", \"Starter\", \"Blank app\", or \"New app\" UI behind.\n- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.\n- Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.\n- For broad provider searches, joins, classification, corpus counts, or absence claims, fetch every relevant page or an explicitly bounded cohort, stage/save large responses with stageAs/saveToFile/fetchAllPages, and reduce them with query-staged-dataset or run-code. Report source, filters, row counts, pagination, truncation, failed pages, and uncovered gaps.\n\nWhen a user asks for something like a digest, reminder, routing rule, or saved behavior:\n- First decide whether it should be a resource, a recurring job, a destination, or a delegated task.\n- Keep responses concise and operational.\n- Avoid inventing integrations or destinations that are not configured yet.`,\n});\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/dispatch",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "Dispatch — workspace control plane for agent-native apps. Vault, integrations, destinations, scheduled jobs, and cross-app delegation, shipped as a single drop-in package.",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -84,7 +84,7 @@
     "tailwind-merge": "^3.5.0",
     "vaul": "^1.1.2",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "0.11.1"
+    "@agent-native/toolkit": "0.12.0"
   },
   "devDependencies": {
     "@react-router/dev": "^8.1.0",
@@ -98,7 +98,7 @@
     "typescript-7": "npm:typescript@^7.0.2",
     "vite": "8.1.0",
     "vitest": "^4.1.5",
-    "@agent-native/core": "0.131.2"
+    "@agent-native/core": "0.131.6"
   },
   "peerDependencies": {
     "@agent-native/core": ">=0.8.0",

package/src/actions/index.ts

@@ -31,6 +31,7 @@ import getWorkspaceInfo from "./get-workspace-info.js";
 import getWorkspaceResourceEffectiveContext from "./get-workspace-resource-effective-context.js";
 import grantVaultSecretsToApp from "./grant-vault-secrets-to-app.js";
 import grantWorkspaceResourcesToApp from "./grant-workspace-resources-to-app.js";
+import listAgentRunFailures from "./list-agent-run-failures.js";
 import listAgentThreadSources from "./list-agent-thread-sources.js";
 import listAvailableWorkspaceTemplates from "./list-available-workspace-templates.js";
 import listConnectedAgents from "./list-connected-agents.js";
@@ -132,6 +133,7 @@ export const dispatchActions: Record<string, ActionEntry> = {
   "grant-workspace-resources-to-app": grantWorkspaceResourcesToApp,
   "grant-vault-secrets-to-app": grantVaultSecretsToApp,
   "list-agent-thread-sources": listAgentThreadSources,
+  "list-agent-run-failures": listAgentRunFailures,
   "list-available-workspace-templates": listAvailableWorkspaceTemplates,
   "list-curated-workspace-templates": listCuratedWorkspaceTemplates,
   "list-connected-agents": listConnectedAgents,

package/src/actions/list-agent-run-failures.ts

@@ -0,0 +1,44 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listAgentRunFailures } from "../server/lib/thread-debug-store.js";
+
+export default defineAction({
+  description:
+    "List recent failed, aborted, or truncated agent runs across the connected thread-debug sources the caller may inspect. Returns source health and run diagnostics; use get-agent-thread-debug with a returned source and run ID for the full transcript and event history.",
+  schema: z.object({
+    sourceId: z
+      .string()
+      .default("all")
+      .describe(
+        "Thread debug source id from list-agent-thread-sources, or 'all' to merge every connected source available to the caller.",
+      ),
+    ownerEmail: z
+      .string()
+      .optional()
+      .describe(
+        "Optional owner email filter. Organization admins may only select members of their current organization.",
+      ),
+    status: z
+      .enum(["all", "errored", "aborted", "truncated"])
+      .default("all")
+      .describe("Unsuccessful run status to include."),
+    lookbackHours: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(720)
+      .default(168)
+      .describe("Lookback window in hours."),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .default(25)
+      .describe("Maximum failures returned after merging and sorting sources."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (input) => listAgentRunFailures(input),
+});

package/src/actions/view-screen.spec.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  navigation: {} as Record<string, unknown>,
+  listAgentRunFailures: vi.fn(),
+  listThreadDebugSources: vi.fn(),
+}));
+
+vi.mock("@agent-native/core", () => ({
+  defineAction: (action: unknown) => action,
+}));
+
+vi.mock("@agent-native/core/application-state", () => ({
+  readAppState: vi.fn(async () => mocks.navigation),
+}));
+
+vi.mock("../server/lib/app-creation-store.js", () => ({
+  listWorkspaceApps: vi.fn(),
+}));
+
+vi.mock("../server/lib/dispatch-store.js", () => ({
+  listOverview: vi.fn(async () => ({
+    counts: {},
+    settings: {},
+  })),
+}));
+
+vi.mock("../server/lib/thread-debug-store.js", () => ({
+  getAgentThreadDebug: vi.fn(),
+  listAgentRunFailures: mocks.listAgentRunFailures,
+  listThreadDebugSources: mocks.listThreadDebugSources,
+  searchAgentThreads: vi.fn(),
+}));
+
+vi.mock("../server/lib/usage-metrics-store.js", () => ({
+  listDispatchUsageMetrics: vi.fn(),
+}));
+
+vi.mock("../server/lib/vault-store.js", () => ({
+  getVaultAccessSettings: vi.fn(),
+  listGrants: vi.fn(),
+  listRequests: vi.fn(),
+  listSecrets: vi.fn(),
+  listVaultOverview: vi.fn(async () => ({})),
+}));
+
+vi.mock("../server/lib/workspace-resources-store.js", () => ({
+  listWorkspaceResourceOptions: vi.fn(),
+  listWorkspaceResourcesForApp: vi.fn(),
+}));
+
+import viewScreen from "./view-screen.js";
+
+describe("view-screen Thread Debug summary", () => {
+  beforeEach(() => {
+    mocks.navigation = { view: "thread-debug" };
+    mocks.listAgentRunFailures.mockReset();
+    mocks.listAgentRunFailures.mockResolvedValue({ failures: [] });
+    mocks.listThreadDebugSources.mockReset();
+    mocks.listThreadDebugSources.mockResolvedValue({ sources: [] });
+  });
+
+  it("matches the UI's default 24-hour failed-run range", async () => {
+    await viewScreen.run({});
+
+    expect(mocks.listAgentRunFailures).toHaveBeenCalledWith({
+      sourceId: "all",
+      ownerEmail: undefined,
+      status: "all",
+      lookbackHours: 24,
+      limit: 10,
+    });
+  });
+
+  it("normalizes invalid status and range query state", async () => {
+    mocks.navigation = {
+      view: "thread-debug",
+      failureStatus: "timed-out",
+      range: "forever",
+    };
+
+    await viewScreen.run({});
+
+    expect(mocks.listAgentRunFailures).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: "all",
+        lookbackHours: 24,
+      }),
+    );
+  });
+});

package/src/actions/view-screen.ts

@@ -15,6 +15,7 @@ import { listWorkspaceApps } from "../server/lib/app-creation-store.js";
 import { listOverview } from "../server/lib/dispatch-store.js";
 import {
   getAgentThreadDebug,
+  listAgentRunFailures,
   listThreadDebugSources,
   searchAgentThreads,
 } from "../server/lib/thread-debug-store.js";
@@ -51,6 +52,20 @@ function stripUndefined(args: Record<string, unknown>) {
   );
 }
 
+function threadDebugLookbackHours(value: unknown): number {
+  if (value === "7d") return 168;
+  if (value === "30d") return 720;
+  return 24;
+}
+
+function threadDebugFailureStatus(
+  value: unknown,
+): "all" | "errored" | "aborted" | "truncated" {
+  return value === "errored" || value === "aborted" || value === "truncated"
+    ? value
+    : "all";
+}
+
 export default defineAction({
   description:
     "See what the user is currently looking at in the dispatch UI, including navigation state and a compact operational summary.",
@@ -190,7 +205,15 @@ export default defineAction({
       try {
         const nav = navigation as Record<string, any>;
         screen.threadDebugSources = await listThreadDebugSources();
-        if (nav.query) {
+        if (nav.threadDebugMode !== "threads") {
+          screen.agentRunFailures = await listAgentRunFailures({
+            sourceId: nav.sourceId ?? "all",
+            ownerEmail: nav.ownerEmail,
+            status: threadDebugFailureStatus(nav.failureStatus),
+            lookbackHours: threadDebugLookbackHours(nav.range),
+            limit: 10,
+          });
+        } else if (nav.query) {
           screen.threadDebugResults = await searchAgentThreads({
             sourceId: nav.sourceId,
             query: nav.query,
@@ -198,10 +221,14 @@ export default defineAction({
             limit: 10,
           });
         }
-        if (nav.threadId) {
+        if (nav.threadId || nav.runId) {
           const detail = await getAgentThreadDebug({
-            sourceId: nav.sourceId,
-            threadId: nav.threadId,
+            sourceId:
+              nav.runId && nav.inspectSourceId
+                ? nav.inspectSourceId
+                : nav.sourceId,
+            threadId: nav.runId ? undefined : nav.threadId,
+            runId: nav.runId,
             ownerEmail: nav.ownerEmail,
             maxRuns: 5,
             maxEvents: 80,
@@ -215,6 +242,9 @@ export default defineAction({
             debug: detail.debug,
             debugRuns: (detail as any).debugRuns?.slice(-5) ?? [],
             messages: detail.messages.slice(-6),
+            runs: detail.runs
+              .slice(0, 5)
+              .map(({ events: _events, ...run }) => run),
           };
         }
       } catch (error) {

package/src/hooks/use-navigation-state.spec.ts

@@ -49,4 +49,49 @@ describe("buildDispatchNavigationState", () => {
       path: "/automations",
     });
   });
+
+  it("preserves thread debug filters and selection", () => {
+    expect(
+      buildDispatchNavigationState(
+        "/thread-debug",
+        "?mode=failures&source=all&inspectSource=mail&owner=ops%40example.com&status=errored&range=7d&query=timeout&runId=run-1&threadId=thread-1",
+      ),
+    ).toEqual({
+      view: "thread-debug",
+      path: "/thread-debug",
+      threadDebugMode: "failures",
+      sourceId: "all",
+      inspectSourceId: "mail",
+      ownerEmail: "ops@example.com",
+      failureStatus: "errored",
+      range: "7d",
+      query: "timeout",
+      runId: "run-1",
+      threadId: "thread-1",
+    });
+  });
+
+  it("omits empty thread debug query values", () => {
+    expect(
+      buildDispatchNavigationState(
+        "/thread-debug",
+        "?mode=&source=&inspectSource=&owner=&status=&range=&query=&runId=&threadId=",
+      ),
+    ).toEqual({
+      view: "thread-debug",
+      path: "/thread-debug",
+    });
+  });
+
+  it("does not expose thread debug query state on unrelated routes", () => {
+    expect(
+      buildDispatchNavigationState(
+        "/overview",
+        "?mode=failures&source=all&inspectSource=mail&owner=ops%40example.com&status=errored&range=7d&query=timeout&runId=run-1&threadId=thread-1",
+      ),
+    ).toEqual({
+      view: "overview",
+      path: "/overview",
+    });
+  });
 });

package/src/hooks/use-navigation-state.ts

@@ -23,8 +23,14 @@ export interface NavigationState {
   extensionId?: string;
   extensionSlug?: string;
   dreamId?: string;
+  threadDebugMode?: string;
   sourceId?: string;
+  inspectSourceId?: string;
+  ownerEmail?: string;
+  failureStatus?: string;
+  range?: string;
   query?: string;
+  runId?: string;
   threadId?: string;
 }
 
@@ -149,6 +155,28 @@ export function buildDispatchNavigationState(
     if (query) state.query = query;
   }
 
+  if (state.view === "thread-debug") {
+    const params = new URLSearchParams(search);
+    const mode = params.get("mode");
+    const sourceId = params.get("source");
+    const inspectSourceId = params.get("inspectSource");
+    const ownerEmail = params.get("owner");
+    const status = params.get("status");
+    const range = params.get("range");
+    const query = params.get("query");
+    const runId = params.get("runId");
+    const selectedThreadId = params.get("threadId");
+    if (mode) state.threadDebugMode = mode;
+    if (sourceId) state.sourceId = sourceId;
+    if (inspectSourceId) state.inspectSourceId = inspectSourceId;
+    if (ownerEmail) state.ownerEmail = ownerEmail;
+    if (status) state.failureStatus = status;
+    if (range) state.range = range;
+    if (query) state.query = query;
+    if (runId) state.runId = runId;
+    if (selectedThreadId) state.threadId = selectedThreadId;
+  }
+
   return state;
 }
 

package/src/routes/pages/thread-debug.spec.tsx

@@ -0,0 +1,272 @@
+// @vitest-environment happy-dom
+import { act, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { MemoryRouter } from "react-router";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import ThreadDebugRoute from "./thread-debug";
+
+const queryState = vi.hoisted(() => ({
+  calls: [] as Array<{
+    name: string;
+    params: Record<string, unknown>;
+    enabled: boolean;
+  }>,
+}));
+
+const failedRun = {
+  id: "run-mail-1",
+  threadId: "thread-mail-1",
+  source: {
+    id: "mail",
+    label: "Mail",
+    kind: "configured",
+    databaseUrlEnv: "MAIL_DATABASE_URL",
+  },
+  ownerEmail: "ops@example.com",
+  threadTitle: "Mail agent failed",
+  threadPreview: "Provider timed out",
+  status: "errored",
+  errorCode: "provider_timeout",
+  errorDetail: "The provider did not respond.",
+  terminalReason: "provider_timeout",
+  abortReason: null,
+  dispatchMode: "background-processing",
+  diagStage: null,
+  workerStage: "model",
+  startedAt: 1_722_400_000_000,
+  completedAt: 1_722_400_030_000,
+  durationMs: 30_000,
+};
+
+const detail = {
+  source: failedRun.source,
+  access: {
+    viewerEmail: "ops@example.com",
+    scope: "current organization",
+    canInspectAll: true,
+  },
+  thread: {
+    id: failedRun.threadId,
+    ownerEmail: failedRun.ownerEmail,
+    title: failedRun.threadTitle,
+    preview: failedRun.threadPreview,
+    messageCount: 0,
+    createdAt: failedRun.startedAt,
+    updatedAt: failedRun.completedAt,
+    snippet: "",
+  },
+  lookup: {
+    requestedId: failedRun.id,
+    threadId: failedRun.threadId,
+    runId: failedRun.id,
+  },
+  messages: [],
+  debug: null,
+  debugRuns: [],
+  queuedMessages: [],
+  threadData: {},
+  rawThreadData: "{}",
+  runs: [],
+  traces: { summaries: [], spans: [] },
+  feedback: [],
+  satisfaction: [],
+  evals: [],
+  checkpoints: [],
+};
+
+vi.mock("@agent-native/core/client/hooks", () => ({
+  useActionQuery: (
+    name: string,
+    params: Record<string, unknown>,
+    options?: { enabled?: boolean },
+  ) => {
+    const enabled = options?.enabled !== false;
+    queryState.calls.push({ name, params, enabled });
+    const base = {
+      isLoading: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    };
+    if (name === "list-agent-thread-sources") {
+      return {
+        ...base,
+        data: {
+          access: {
+            viewerEmail: "ops@example.com",
+            orgId: "org-1",
+            role: "admin",
+            envAdmin: false,
+            canInspectAll: true,
+            memberCount: 1,
+          },
+          sources: [
+            {
+              id: "current",
+              label: "Current Dispatch DB",
+              kind: "current",
+              current: true,
+              connected: true,
+              databaseUrlEnv: null,
+              databaseAuthTokenEnv: null,
+              canInspectAll: true,
+            },
+            {
+              id: "mail",
+              label: "Mail",
+              kind: "configured",
+              current: false,
+              connected: true,
+              databaseUrlEnv: "MAIL_DATABASE_URL",
+              databaseAuthTokenEnv: null,
+              canInspectAll: true,
+            },
+          ],
+        },
+      };
+    }
+    if (name === "list-agent-run-failures") {
+      return {
+        ...base,
+        data: enabled
+          ? {
+              failures: [failedRun],
+              count: 1,
+              partial: true,
+              access: {
+                viewerEmail: "ops@example.com",
+                scope: "current organization",
+                canInspectAll: true,
+              },
+              sources: [
+                {
+                  source: failedRun.source,
+                  status: "ok",
+                  failureCount: 1,
+                },
+                {
+                  source: { id: "clips", label: "Clips" },
+                  status: "unavailable",
+                  failureCount: 0,
+                },
+              ],
+            }
+          : undefined,
+      };
+    }
+    if (name === "get-agent-thread-debug") {
+      return { ...base, data: enabled ? detail : undefined };
+    }
+    return { ...base, data: undefined };
+  },
+}));
+
+vi.mock("@agent-native/core/client/i18n", () => ({
+  useT: () => (key: string, values?: { defaultValue?: string }) =>
+    values?.defaultValue ?? key,
+}));
+
+vi.mock("../../components/dispatch-shell", () => ({
+  DispatchShell: ({
+    title,
+    description,
+    children,
+  }: {
+    title: ReactNode;
+    description: ReactNode;
+    children: ReactNode;
+  }) => (
+    <main>
+      <h1>{title}</h1>
+      <p>{description}</p>
+      {children}
+    </main>
+  ),
+}));
+
+describe("ThreadDebugRoute", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    queryState.calls = [];
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  it("uses 24-hour defaults, preserves partial health, and inspects a cross-source failure", async () => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={["/thread-debug"]}>
+          <ThreadDebugRoute />
+        </MemoryRouter>,
+      );
+    });
+
+    expect(
+      queryState.calls.find(
+        (call) => call.name === "list-agent-run-failures" && call.enabled,
+      )?.params,
+    ).toMatchObject({
+      sourceId: "all",
+      status: "all",
+      lookbackHours: 24,
+    });
+    expect(container.textContent).toContain("Partial results");
+    expect(container.textContent).toContain("Clips (unavailable)");
+
+    const failureButton = [...container.querySelectorAll("button")].find(
+      (button) => button.textContent?.includes("Inspect failed run"),
+    );
+    expect(failureButton).toBeTruthy();
+    await act(async () => {
+      failureButton?.click();
+    });
+
+    expect(
+      queryState.calls.find(
+        (call) =>
+          call.name === "get-agent-thread-debug" &&
+          call.enabled &&
+          call.params.runId === failedRun.id,
+      )?.params,
+    ).toMatchObject({
+      sourceId: "mail",
+      runId: failedRun.id,
+    });
+  });
+
+  it("passes valid URL-backed failure filters to the action", async () => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter
+          initialEntries={[
+            "/thread-debug?source=mail&owner=ops%40example.com&status=errored&range=7d",
+          ]}
+        >
+          <ThreadDebugRoute />
+        </MemoryRouter>,
+      );
+    });
+
+    expect(
+      queryState.calls.find(
+        (call) => call.name === "list-agent-run-failures" && call.enabled,
+      )?.params,
+    ).toMatchObject({
+      sourceId: "mail",
+      ownerEmail: "ops@example.com",
+      status: "errored",
+      lookbackHours: 168,
+    });
+  });
+});