@calltelemetry/openclaw-linear 0.6.1 → 0.7.1

package/src/pipeline/tier-assess.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { TIER_MODELS, assessTier, type IssueContext } from "./tier-assess.js";
+
+// ---------------------------------------------------------------------------
+// Mock runAgent
+// ---------------------------------------------------------------------------
+
+const mockRunAgent = vi.fn();
+
+vi.mock("../agent/agent.js", () => ({
+  runAgent: (...args: unknown[]) => mockRunAgent(...args),
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeApi(overrides?: { defaultAgentId?: string }) {
+  return {
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    pluginConfig: {
+      defaultAgentId: overrides?.defaultAgentId,
+    },
+  } as any;
+}
+
+function makeIssue(overrides?: Partial<IssueContext>): IssueContext {
+  return {
+    identifier: "CT-123",
+    title: "Fix login bug",
+    description: "Users cannot log in when using SSO",
+    labels: ["bug"],
+    commentCount: 2,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("TIER_MODELS", () => {
+  it("maps junior to haiku, medior to sonnet, senior to opus", () => {
+    expect(TIER_MODELS.junior).toBe("anthropic/claude-haiku-4-5");
+    expect(TIER_MODELS.medior).toBe("anthropic/claude-sonnet-4-6");
+    expect(TIER_MODELS.senior).toBe("anthropic/claude-opus-4-6");
+  });
+});
+
+describe("assessTier", () => {
+  beforeEach(() => {
+    mockRunAgent.mockReset();
+  });
+
+  it("returns parsed tier from agent response", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"senior","reasoning":"Multi-service architecture change"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("senior");
+    expect(result.model).toBe(TIER_MODELS.senior);
+    expect(result.reasoning).toBe("Multi-service architecture change");
+    expect(api.logger.info).toHaveBeenCalled();
+  });
+
+  it("falls back to medior when agent fails (success: false) with no parseable JSON", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: false,
+      output: "Agent process exited with code 1",
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("medior");
+    expect(result.model).toBe(TIER_MODELS.medior);
+    expect(result.reasoning).toBe("Assessment failed — defaulting to medior");
+    expect(api.logger.warn).toHaveBeenCalled();
+  });
+
+  it("falls back to medior when output has no JSON", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: "I think this is a medium complexity issue because it involves multiple files.",
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("medior");
+    expect(result.model).toBe(TIER_MODELS.medior);
+    expect(result.reasoning).toBe("Assessment failed — defaulting to medior");
+  });
+
+  it("falls back to medior when JSON has invalid tier", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"expert","reasoning":"Very hard problem"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("medior");
+    expect(result.model).toBe(TIER_MODELS.medior);
+  });
+
+  it("handles agent throwing an error", async () => {
+    mockRunAgent.mockRejectedValue(new Error("Connection refused"));
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("medior");
+    expect(result.model).toBe(TIER_MODELS.medior);
+    expect(result.reasoning).toBe("Assessment failed — defaulting to medior");
+    expect(api.logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("Tier assessment error for CT-123"),
+    );
+  });
+
+  it("truncates long descriptions to 1500 chars", async () => {
+    const longDescription = "A".repeat(3000);
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"junior","reasoning":"Simple copy change"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    await assessTier(api, makeIssue({ description: longDescription }));
+
+    // Verify the message sent to runAgent has the description truncated
+    const callArgs = mockRunAgent.mock.calls[0][0];
+    const message: string = callArgs.message;
+    // The description in the prompt should be at most 1500 chars of the original
+    // "Description: " prefix + 1500 chars = the truncated form
+    expect(message).toContain("Description: " + "A".repeat(1500));
+    expect(message).not.toContain("A".repeat(1501));
+  });
+
+  it("uses configured agentId when provided", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"junior","reasoning":"Typo fix"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    await assessTier(api, makeIssue(), "kaylee");
+
+    const callArgs = mockRunAgent.mock.calls[0][0];
+    expect(callArgs.agentId).toBe("kaylee");
+  });
+
+  it("parses JSON even when wrapped in markdown fences", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '```json\n{"tier":"junior","reasoning":"Config tweak"}\n```',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("junior");
+    expect(result.model).toBe(TIER_MODELS.junior);
+    expect(result.reasoning).toBe("Config tweak");
+  });
+});

package/src/pipeline/webhook.ts

@@ -6,10 +6,14 @@ import { LinearAgentApi, resolveLinearToken } from "../api/linear-api.js";
 import { spawnWorker, type HookContext } from "./pipeline.js";
 import { setActiveSession, clearActiveSession } from "./active-session.js";
 import { readDispatchState, getActiveDispatch, registerDispatch, updateDispatchStatus, completeDispatch, removeActiveDispatch } from "./dispatch-state.js";
-import { createDiscordNotifier, createNoopNotifier, type NotifyFn } from "../infra/notify.js";
+import { createNotifierFromConfig, type NotifyFn } from "../infra/notify.js";
 import { assessTier } from "./tier-assess.js";
 import { createWorktree, prepareWorkspace } from "../infra/codex-worktree.js";
 import { ensureClawDir, writeManifest } from "./artifacts.js";
+import { readPlanningState, isInPlanningMode, getPlanningSession } from "./planning-state.js";
+import { initiatePlanningSession, handlePlannerTurn } from "./planner.js";
+import { startProjectDispatch } from "./dag-dispatch.js";
+import { emitDiagnostic } from "../infra/observability.js";
 
 // ── Agent profiles (loaded from config, no hardcoded names) ───────
 interface AgentProfile {
@@ -146,6 +150,7 @@ export async function handleLinearWebhook(
   // Debug: log full payload structure for diagnosing webhook types
   const payloadKeys = Object.keys(payload).join(", ");
   api.logger.info(`Linear webhook received: type=${payload.type} action=${payload.action} keys=[${payloadKeys}]`);
+  emitDiagnostic(api, { event: "webhook_received", webhookType: payload.type, webhookAction: payload.action });
 
 
   // ── AppUserNotification — OAuth app webhook for agent mentions/assignments
@@ -663,6 +668,66 @@ export async function handleLinearWebhook(
     const commentor = comment?.user?.name ?? "Unknown";
     const issue = comment?.issue ?? payload.issue;
 
+    // ── Planning mode intercept ──────────────────────────────────
+    const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+
+    if (issue?.id) {
+      const linearApiForPlanning = createLinearApi(api);
+      if (linearApiForPlanning) {
+        try {
+          const enriched = await linearApiForPlanning.getIssueDetails(issue.id);
+          const projectId = enriched?.project?.id;
+          const planStatePath = pluginConfig?.planningStatePath as string | undefined;
+
+          if (projectId) {
+            const planState = await readPlanningState(planStatePath);
+
+            // Check if this is a plan initiation request
+            const isPlanRequest = /\b(plan|planning)\s+(this\s+)?(project|out)\b/i.test(commentBody);
+            if (isPlanRequest && !isInPlanningMode(planState, projectId)) {
+              api.logger.info(`Planning: initiation requested on ${issue.identifier ?? issue.id}`);
+              void initiatePlanningSession(
+                { api, linearApi: linearApiForPlanning, pluginConfig },
+                projectId,
+                { id: issue.id, identifier: enriched.identifier, title: enriched.title, team: enriched.team },
+              ).catch((err) => api.logger.error(`Planning initiation error: ${err}`));
+              return true;
+            }
+
+            // Route to planner if project is in planning mode
+            if (isInPlanningMode(planState, projectId)) {
+              const session = getPlanningSession(planState, projectId);
+              if (session && comment?.id && !wasRecentlyProcessed(`plan-comment:${comment.id}`)) {
+                api.logger.info(`Planning: routing comment to planner for ${session.projectName}`);
+                void handlePlannerTurn(
+                  { api, linearApi: linearApiForPlanning, pluginConfig },
+                  session,
+                  { issueId: issue.id, commentBody, commentorName: commentor },
+                  {
+                    onApproved: (approvedProjectId) => {
+                      const notify = createNotifierFromConfig(pluginConfig, api.runtime);
+                      const hookCtx: HookContext = {
+                        api,
+                        linearApi: linearApiForPlanning,
+                        notify,
+                        pluginConfig,
+                        configPath: pluginConfig?.dispatchStatePath as string | undefined,
+                      };
+                      void startProjectDispatch(hookCtx, approvedProjectId)
+                        .catch((err) => api.logger.error(`Project dispatch start error: ${err}`));
+                    },
+                  },
+                ).catch((err) => api.logger.error(`Planner turn error: ${err}`));
+              }
+              return true;
+            }
+          }
+        } catch (err) {
+          api.logger.warn(`Planning mode check failed: ${err}`);
+        }
+      }
+    }
+
     // Load agent profiles and build mention pattern dynamically.
     // Default agent (app mentions) is handled by AgentSessionEvent — never here.
     const profiles = loadAgentProfiles();
@@ -1161,6 +1226,26 @@ async function handleDispatch(
 
   api.logger.info(`@dispatch: processing ${identifier}`);
 
+  // 0. Check planning mode — prevent dispatch for issues in planning-mode projects
+  try {
+    const enrichedForPlan = await linearApi.getIssueDetails(issue.id ?? issue);
+    const planProjectId = enrichedForPlan?.project?.id;
+    if (planProjectId) {
+      const planStatePath = pluginConfig?.planningStatePath as string | undefined;
+      const planState = await readPlanningState(planStatePath);
+      if (isInPlanningMode(planState, planProjectId)) {
+        api.logger.info(`dispatch: ${identifier} is in planning-mode project — skipping`);
+        await linearApi.createComment(
+          issue.id,
+          "This project is in planning mode. Finalize the plan before dispatching implementation.",
+        );
+        return;
+      }
+    }
+  } catch (err) {
+    api.logger.warn(`dispatch: planning mode check failed for ${identifier}: ${err}`);
+  }
+
   // 1. Check for existing active dispatch — reclaim if stale
   const STALE_DISPATCH_MS = 30 * 60_000; // 30 min without a gateway holding it = stale
   const state = await readDispatchState(statePath);
@@ -1217,6 +1302,7 @@ async function handleDispatch(
   });
 
   api.logger.info(`@dispatch: ${identifier} assessed as ${assessment.tier} (${assessment.model}) — ${assessment.reasoning}`);
+  emitDiagnostic(api, { event: "dispatch_started", identifier, tier: assessment.tier, issueId: issue.id });
 
   // 5. Create persistent worktree
   let worktree;
@@ -1285,6 +1371,7 @@ async function handleDispatch(
     dispatchedAt: now,
     agentSessionId,
     attempt: 0,
+    project: enrichedIssue?.project?.id,
   }, statePath);
 
   // 8. Register active session for tool resolution
@@ -1337,22 +1424,8 @@ async function handleDispatch(
   // 11. Run v2 pipeline: worker → audit → verdict (non-blocking)
   activeRuns.add(issue.id);
 
-  // Instantiate notifier
-  const discordBotToken = (() => {
-    try {
-      const config = JSON.parse(
-        require("node:fs").readFileSync(
-          require("node:path").join(process.env.HOME ?? "/home/claw", ".openclaw", "openclaw.json"),
-          "utf8",
-        ),
-      );
-      return config?.channels?.discord?.token as string | undefined;
-    } catch { return undefined; }
-  })();
-  const flowDiscordChannel = pluginConfig?.flowDiscordChannel as string | undefined;
-  const notify: NotifyFn = (discordBotToken && flowDiscordChannel)
-    ? createDiscordNotifier(discordBotToken, flowDiscordChannel)
-    : createNoopNotifier();
+  // Instantiate notifier (Discord, Slack, or both — config-driven)
+  const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime);
 
   const hookCtx: HookContext = {
     api,

package/src/tools/dispatch-history-tool.ts

@@ -0,0 +1,201 @@
+/**
+ * dispatch-history-tool.ts — Agent tool for searching dispatch history.
+ *
+ * Searches dispatch state + memory files to provide context about
+ * past dispatches. Useful for agents to understand what work has
+ * been done on related issues.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { readDispatchState, listActiveDispatches, type ActiveDispatch, type CompletedDispatch } from "../pipeline/dispatch-state.js";
+import { resolveOrchestratorWorkspace } from "../pipeline/artifacts.js";
+
+export function createDispatchHistoryTool(
+  api: OpenClawPluginApi,
+  pluginConfig?: Record<string, unknown>,
+): AnyAgentTool {
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+
+  return {
+    name: "dispatch_history",
+    label: "Dispatch History",
+    description:
+      "Search dispatch history for past and active Linear issue dispatches. " +
+      "Returns issue identifier, tier, status, attempts, and summary excerpts.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Issue identifier (e.g. 'CT-123') or keyword to search in summaries.",
+        },
+        tier: {
+          type: "string",
+          enum: ["junior", "medior", "senior"],
+          description: "Filter by tier.",
+        },
+        status: {
+          type: "string",
+          enum: ["dispatched", "working", "auditing", "done", "failed", "stuck"],
+          description: "Filter by status.",
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return (default: 10).",
+        },
+      },
+    },
+    execute: async (_toolCallId: string, params: {
+      query?: string;
+      tier?: string;
+      status?: string;
+      limit?: number;
+    }) => {
+      const maxResults = params.limit ?? 10;
+      const results: Array<{
+        identifier: string;
+        tier: string;
+        status: string;
+        attempts: number;
+        summary?: string;
+        active: boolean;
+      }> = [];
+
+      // Search active dispatches
+      const state = await readDispatchState(statePath);
+      const active = listActiveDispatches(state);
+      for (const d of active) {
+        if (matchesFilters(d.issueIdentifier, d.tier, d.status, params)) {
+          results.push({
+            identifier: d.issueIdentifier,
+            tier: d.tier,
+            status: d.status,
+            attempts: d.attempt,
+            active: true,
+          });
+        }
+      }
+
+      // Search completed dispatches
+      for (const [id, d] of Object.entries(state.dispatches.completed)) {
+        if (matchesFilters(id, d.tier, d.status, params)) {
+          results.push({
+            identifier: id,
+            tier: d.tier,
+            status: d.status,
+            attempts: d.totalAttempts ?? 0,
+            active: false,
+          });
+        }
+      }
+
+      // Search memory files for richer context
+      try {
+        const wsDir = resolveOrchestratorWorkspace(api, pluginConfig);
+        const memDir = join(wsDir, "memory");
+        const files = readdirSync(memDir).filter(f => f.startsWith("dispatch-") && f.endsWith(".md"));
+
+        for (const file of files) {
+          const id = file.replace("dispatch-", "").replace(".md", "");
+          // Skip if already in results
+          if (results.some(r => r.identifier === id)) {
+            // Enrich with summary
+            const existing = results.find(r => r.identifier === id);
+            if (existing && !existing.summary) {
+              try {
+                const content = readFileSync(join(memDir, file), "utf-8");
+                existing.summary = extractSummaryExcerpt(content, params.query);
+              } catch {}
+            }
+            continue;
+          }
+
+          // Check if memory file matches query
+          if (params.query) {
+            try {
+              const content = readFileSync(join(memDir, file), "utf-8");
+              if (
+                id.toLowerCase().includes(params.query.toLowerCase()) ||
+                content.toLowerCase().includes(params.query.toLowerCase())
+              ) {
+                const meta = parseFrontmatter(content);
+                if (matchesFilters(id, meta.tier, meta.status, params)) {
+                  results.push({
+                    identifier: id,
+                    tier: meta.tier ?? "unknown",
+                    status: meta.status ?? "completed",
+                    attempts: meta.attempts ?? 0,
+                    summary: extractSummaryExcerpt(content, params.query),
+                    active: false,
+                  });
+                }
+              }
+            } catch {}
+          }
+        }
+      } catch {}
+
+      const limited = results.slice(0, maxResults);
+
+      if (limited.length === 0) {
+        return jsonResult({ message: "No dispatch history found matching the criteria.", results: [] });
+      }
+
+      const formatted = limited.map(r => {
+        const parts = [`**${r.identifier}** — ${r.status} (${r.tier}, ${r.attempts} attempts)${r.active ? " [ACTIVE]" : ""}`];
+        if (r.summary) parts.push(`  ${r.summary}`);
+        return parts.join("\n");
+      }).join("\n\n");
+
+      return jsonResult({
+        message: `Found ${limited.length} dispatch(es):\n\n${formatted}`,
+        results: limited,
+      });
+    },
+  } as unknown as AnyAgentTool;
+}
+
+function matchesFilters(
+  identifier: string,
+  tier: string,
+  status: string,
+  params: { query?: string; tier?: string; status?: string },
+): boolean {
+  if (params.tier && tier !== params.tier) return false;
+  if (params.status && status !== params.status) return false;
+  if (params.query && !identifier.toLowerCase().includes(params.query.toLowerCase())) return false;
+  return true;
+}
+
+function parseFrontmatter(content: string): Record<string, any> {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const result: Record<string, any> = {};
+  for (const line of match[1].split("\n")) {
+    const [key, ...rest] = line.split(": ");
+    if (key && rest.length > 0) {
+      let value: any = rest.join(": ").trim();
+      if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+      else if (!isNaN(Number(value))) value = Number(value);
+      result[key.trim()] = value;
+    }
+  }
+  return result;
+}
+
+function extractSummaryExcerpt(content: string, query?: string): string {
+  // Remove frontmatter
+  const body = content.replace(/^---[\s\S]*?---\n?/, "").trim();
+  if (!query) return body.slice(0, 200);
+
+  // Find the query in the body and return surrounding context
+  const lower = body.toLowerCase();
+  const idx = lower.indexOf(query.toLowerCase());
+  if (idx === -1) return body.slice(0, 200);
+
+  const start = Math.max(0, idx - 50);
+  const end = Math.min(body.length, idx + query.length + 150);
+  return (start > 0 ? "..." : "") + body.slice(start, end) + (end < body.length ? "..." : "");
+}

package/src/tools/orchestration-tools.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createOrchestrationTools } from "./orchestration-tools.js";
+
+// ---------------------------------------------------------------------------
+// Mock runAgent
+// ---------------------------------------------------------------------------
+
+const mockRunAgent = vi.fn();
+
+vi.mock("../agent/agent.js", () => ({
+  runAgent: (...args: unknown[]) => mockRunAgent(...args),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock jsonResult (from openclaw/plugin-sdk)
+// ---------------------------------------------------------------------------
+
+vi.mock("openclaw/plugin-sdk", () => ({
+  jsonResult: (obj: unknown) => ({ type: "json", data: obj }),
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeApi() {
+  return {
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+  } as any;
+}
+
+function makeCtx(): Record<string, unknown> {
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("createOrchestrationTools", () => {
+  beforeEach(() => {
+    mockRunAgent.mockReset();
+  });
+
+  it("returns 2 tools", () => {
+    const tools = createOrchestrationTools(makeApi(), makeCtx());
+
+    expect(tools).toHaveLength(2);
+    expect(tools[0].name).toBe("spawn_agent");
+    expect(tools[1].name).toBe("ask_agent");
+  });
+
+  it("spawn_agent tool has correct name and parameters schema", () => {
+    const tools = createOrchestrationTools(makeApi(), makeCtx());
+    const spawn = tools[0];
+
+    expect(spawn.name).toBe("spawn_agent");
+    expect(spawn.parameters).toBeDefined();
+    expect(spawn.parameters.type).toBe("object");
+    expect(spawn.parameters.properties.agentId).toBeDefined();
+    expect(spawn.parameters.properties.task).toBeDefined();
+    expect(spawn.parameters.properties.timeoutSeconds).toBeDefined();
+    expect(spawn.parameters.required).toEqual(["agentId", "task"]);
+  });
+
+  it("spawn_agent dispatches to runAgent and returns immediately", async () => {
+    // runAgent returns a promise that never resolves (to prove fire-and-forget)
+    let resolveAgent!: (value: unknown) => void;
+    const agentPromise = new Promise((resolve) => { resolveAgent = resolve; });
+    mockRunAgent.mockReturnValue(agentPromise);
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const spawn = tools[0];
+
+    const result = await spawn.execute("call-1", {
+      agentId: "kaylee",
+      task: "Investigate database performance",
+    });
+
+    // Should return immediately with a sessionId, even though runAgent hasn't resolved
+    expect(result.data.agentId).toBe("kaylee");
+    expect(result.data.sessionId).toMatch(/^spawn-kaylee-/);
+    expect(result.data.message).toContain("Dispatched task");
+    expect(mockRunAgent).toHaveBeenCalledOnce();
+
+    // Clean up: resolve the hanging promise to avoid unhandled rejection
+    resolveAgent({ success: true, output: "done" });
+  });
+
+  it("ask_agent returns response on success", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: "No, the schema change is backward-compatible and won't break tests.",
+    });
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const askAgent = tools[1];
+
+    const result = await askAgent.execute("call-2", {
+      agentId: "kaylee",
+      message: "Would this schema change break existing tests?",
+    });
+
+    expect(result.data.agentId).toBe("kaylee");
+    expect(result.data.response).toBe(
+      "No, the schema change is backward-compatible and won't break tests.",
+    );
+    expect(result.data.message).toContain("Response from agent");
+  });
+
+  it("ask_agent returns error message on failure", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: false,
+      output: "Agent timed out after 120s",
+    });
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const askAgent = tools[1];
+
+    const result = await askAgent.execute("call-3", {
+      agentId: "kaylee",
+      message: "Check if the migration works",
+    });
+
+    expect(result.data.agentId).toBe("kaylee");
+    expect(result.data.error).toBe("Agent timed out after 120s");
+    expect(result.data.message).toContain("failed to respond");
+    expect(result.data.response).toBeUndefined();
+  });
+
+  it("ask_agent uses custom timeout when provided", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: "Result from agent",
+    });
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const askAgent = tools[1];
+
+    await askAgent.execute("call-4", {
+      agentId: "mal",
+      message: "Run a long analysis",
+      timeoutSeconds: 600,
+    });
+
+    const callArgs = mockRunAgent.mock.calls[0][0];
+    // 600 seconds = 600_000 ms
+    expect(callArgs.timeoutMs).toBe(600_000);
+  });
+});