agent-pool-mcp 1.0.0

package/src/tool-definitions.js

@@ -0,0 +1,176 @@
+/**
+ * MCP tool definitions — schema for all available tools.
+ * Separated from server.js for clarity.
+ *
+ * @module agent-pool/tool-definitions
+ */
+
+export const TOOL_DEFINITIONS = [
+  {
+    name: 'delegate_task',
+    description: [
+      'Delegate a coding task to a Gemini CLI agent running in headless mode.',
+      'The agent is sandboxed to `cwd` directory only. Use `include_dirs` to grant access to additional directories.',
+      'Use this for parallel work: code review, testing, refactoring, analysis, or any dev task.',
+      '',
+      'Returns a task_id immediately (non-blocking). Use get_task_result to check status and retrieve the result.',
+      '',
+      'IMPORTANT: Gemini CLI cold start takes ~15-20s before the agent begins working. Set timeout to at least 60s for simple tasks, 300s+ for complex analysis.',
+      'WORKSPACE: The agent can only use file tools within `cwd` and `include_dirs`. For other paths it can use shell commands (cat, find, ls).',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'The task description for the Gemini agent. Be specific and detailed.' },
+        cwd: { type: 'string', description: 'Working directory for the agent. Defaults to current working directory.' },
+        model: { type: 'string', description: 'Model to use. Options: gemini-3.1-pro-preview, gemini-3-flash-preview. Leave empty for Auto mode.' },
+        approval_mode: {
+          type: 'string',
+          enum: ['yolo', 'auto_edit', 'plan'],
+          description: 'Approval mode: yolo (auto-approve all), auto_edit (auto-approve edits only), plan (read-only). Default: yolo.',
+        },
+        timeout: { type: 'number', description: 'Timeout in seconds. Default: 600 (10 minutes).' },
+        session_id: { type: 'string', description: 'Resume an existing Gemini CLI session by its UUID. Use list_sessions to see available sessions.' },
+        skill: { type: 'string', description: 'Activate a Gemini CLI skill by name before executing the task. Use list_skills to see available skills.' },
+        runner: { type: 'string', description: 'Runner ID from agent-pool.config.json. Default: "local". Use SSH runners for remote execution.' },
+        policy: { type: 'string', description: 'Policy file for tool restrictions. Use built-in template name (e.g. "read-only", "safe-edit") or absolute path to .yaml policy file.' },
+        on_wait_hint: { type: 'string', description: 'Custom coaching message shown when polling for results. Guides the calling agent on what to do while waiting.' },
+        include_dirs: { type: 'array', items: { type: 'string' }, description: 'Additional directories to include in the agent workspace scope. By default the agent only has access to cwd. Use this to grant access to other project dirs, config dirs, etc.' },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'delegate_task_readonly',
+    description: [
+      'Delegate a read-only analysis task to Gemini CLI agent.',
+      'The agent is sandboxed to `cwd` directory only. Use `include_dirs` to grant access to additional directories.',
+      'It is semantically identical to delegate_task but signals that the task is primarily for analysis.',
+      'Use this for code review, architecture analysis, finding bugs, writing reports, etc.',
+      '',
+      'Returns a task_id immediately (non-blocking). Use get_task_result to check status and retrieve the result.',
+      '',
+      'IMPORTANT: Gemini CLI cold start takes ~15-20s before the agent begins working. Set timeout to at least 60s for simple tasks, 300s+ for complex analysis.',
+      'WORKSPACE: The agent can only use file tools within `cwd` and `include_dirs`. For other paths it can use shell commands (cat, find, ls).',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'The analysis task for the Gemini agent.' },
+        cwd: { type: 'string', description: 'Working directory. Defaults to current working directory.' },
+        model: { type: 'string', description: 'Model to use. Leave empty for Auto.' },
+        timeout: { type: 'number', description: 'Timeout in seconds. Default: 600 (10 minutes).' },
+        session_id: { type: 'string', description: 'Resume an existing Gemini CLI session by its UUID. Use list_sessions to see available sessions.' },
+        runner: { type: 'string', description: 'Runner ID from agent-pool.config.json. Default: "local". Use SSH runners for remote execution.' },
+        on_wait_hint: { type: 'string', description: 'Custom coaching message shown when polling for results.' },
+        include_dirs: { type: 'array', items: { type: 'string' }, description: 'Additional directories to include in the agent workspace scope. By default the agent only has access to cwd.' },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'consult_peer',
+    description: [
+      'Consult a Gemini peer agent for architectural/technical consensus.',
+      'Use during PLANNING phase to validate proposals before implementation.',
+      'Supports iterative rounds: send proposal, get feedback, revise, resend until AGREE.',
+      'The peer responds with a structured verdict: AGREE, SUGGEST_CHANGES, or DISAGREE.',
+      '',
+      'Returns a task_id immediately (non-blocking). Use get_task_result to check the verdict.',
+      'The peer runs without a timeout — it will work until done. Progress is visible via get_task_result.',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        context: { type: 'string', description: 'Project context: what are we working on, constraints, requirements.' },
+        proposal: { type: 'string', description: 'Your technical proposal or architectural decision to review.' },
+        previous_rounds: { type: 'string', description: 'Summary of previous discussion rounds (if iterating toward consensus).' },
+        cwd: { type: 'string', description: 'Working directory for file access. Defaults to current working directory.' },
+        model: { type: 'string', description: 'Model to use. Default: Auto.' },
+      },
+      required: ['context', 'proposal'],
+    },
+  },
+  {
+    name: 'get_task_result',
+    description: 'Check the status and result of a background task started with delegate_task, delegate_task_readonly, or consult_peer. Returns status: running, done, or error.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task ID returned by delegate_task, delegate_task_readonly, or consult_peer.' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'cancel_task',
+    description: 'Cancel a running task and kill its process. Use when a task is stuck or no longer needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task ID to cancel.' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'list_sessions',
+    description: 'List available Gemini CLI sessions for a project directory. Returns session IDs, previews, and age. Use session_id with delegate_task to resume.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: 'Project directory to list sessions for. Defaults to current working directory.' },
+      },
+    },
+  },
+  {
+    name: 'list_skills',
+    description: 'List available Gemini CLI skills from all tiers: project (.gemini/skills/), user-global (~/.gemini/skills/), and built-in (shipped with agent-pool). Shows tier label for each skill.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+    },
+  },
+  {
+    name: 'create_skill',
+    description: 'Create or update a Gemini CLI skill. Writes a .md file with YAML frontmatter. Use scope to control where: "project" (default) or "global" (~/.gemini/skills/).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        skill_name: { type: 'string', description: 'Skill name (used as filename, e.g. "code-reviewer").' },
+        description: { type: 'string', description: 'Short description of what the skill does.' },
+        instructions: { type: 'string', description: 'Full markdown instructions for the skill. Define the agent role, rules, and output format.' },
+        scope: { type: 'string', enum: ['project', 'global'], description: 'Where to save: "project" (default, .gemini/skills/) or "global" (~/.gemini/skills/).' },
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+      required: ['skill_name', 'description', 'instructions'],
+    },
+  },
+  {
+    name: 'delete_skill',
+    description: 'Delete a Gemini CLI skill by name. Specify scope to target project or global tier.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        skill_name: { type: 'string', description: 'Skill name to delete.' },
+        scope: { type: 'string', enum: ['project', 'global'], description: 'Tier to delete from: "project" (default) or "global".' },
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+      required: ['skill_name'],
+    },
+  },
+  {
+    name: 'install_skill',
+    description: 'Install a global or built-in skill into the current project. Copies the skill file for local customization. Use list_skills to see available skills from all tiers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        skill_name: { type: 'string', description: 'Skill name to install (e.g. "code-reviewer").' },
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+      required: ['skill_name'],
+    },
+  },
+];

package/src/tools/consult.js

@@ -0,0 +1,99 @@
+/**
+ * Peer consultation — consult_peer tool for architectural consensus.
+ * Non-blocking: returns task_id, result is polled via get_task_result.
+ *
+ * @module agent-pool/tools/consult
+ */
+
+import { randomUUID } from 'node:crypto';
+import { runGeminiStreaming } from '../runner/gemini-runner.js';
+import { createTask, completeTask, failTask } from './results.js';
+
+const PEER_REVIEW_SYSTEM_PROMPT = [
+  'You are a senior software architect participating in a peer review session.',
+  'Another AI agent (Antigravity/Claude) is proposing a technical approach.',
+  'Your role is to critically evaluate the proposal and work toward consensus.',
+  '',
+  'RESPONSE FORMAT (strict):',
+  '## Verdict: [AGREE | SUGGEST_CHANGES | DISAGREE]',
+  '',
+  '## Reasoning',
+  '[Your detailed technical analysis]',
+  '',
+  '## Concerns (if any)',
+  '[List specific technical concerns]',
+  '',
+  '## Suggested Changes (if verdict is not AGREE)',
+  '[Specific actionable modifications]',
+  '',
+  '## Final Assessment',
+  '[1-2 sentence summary of your position]',
+  '',
+  'RULES:',
+  '- Be concise but thorough',
+  '- Focus on architecture, performance, maintainability, and correctness',
+  '- If the proposal is solid, AGREE and explain why',
+  '- If you suggest changes, be specific about what and why',
+  '- Consider the project conventions: Node.js, ESM, JSDoc, no TypeScript, modular structure',
+  '- Respond in the same language as the proposal (Russian or English)',
+].join('\n');
+
+/**
+ * Consult a Gemini peer agent for architectural review (non-blocking).
+ * Spawns a streaming task and returns task_id immediately.
+ *
+ * @param {object} args
+ * @param {string} args.context - Project context
+ * @param {string} args.proposal - Technical proposal
+ * @param {string} [args.previous_rounds] - Previous discussion
+ * @param {string} [args.cwd] - Working directory
+ * @param {string} [args.model] - Model ID
+ * @param {string} defaultCwd - Default working directory
+ * @returns {{content: Array<{type: string, text: string}>}}
+ */
+export function consultPeer(args, defaultCwd) {
+  const taskId = randomUUID();
+
+  const parts = [
+    PEER_REVIEW_SYSTEM_PROMPT,
+    '',
+    '--- CONTEXT ---',
+    args.context,
+    '',
+    '--- PROPOSAL ---',
+    args.proposal,
+  ];
+
+  if (args.previous_rounds) {
+    parts.push(
+      '',
+      '--- PREVIOUS DISCUSSION ---',
+      args.previous_rounds,
+      '',
+      'Based on the previous rounds, evaluate the UPDATED proposal above.',
+      'If your concerns have been addressed, respond with AGREE.',
+    );
+  }
+
+  const prompt = parts.join('\n');
+
+  createTask(taskId, `[peer-review] ${args.proposal.substring(0, 100)}`, 'Peer is reviewing your proposal. Continue with other work while waiting.', 'plan');
+
+  runGeminiStreaming({
+    prompt,
+    cwd: args.cwd ?? defaultCwd,
+    model: args.model,
+    approvalMode: 'plan',
+    timeout: 0, // no timeout — runs until completion
+    taskId,
+  })
+    .then((result) => completeTask(taskId, result))
+    .catch((err) => failTask(taskId, err.message));
+
+  return {
+    content: [{
+      type: 'text',
+      text: `🤝 Peer consultation started.\n\n- **Task ID**: \`${taskId}\`\n- **Proposal**: ${args.proposal.substring(0, 120)}...\n\nUse \`get_task_result\` with this task_id to check the verdict.`,
+    }],
+  };
+}

package/src/tools/results.js

@@ -0,0 +1,416 @@
+/**
+ * Task result store — tracks task status, PID, and retrieves results.
+ * Supports soft timeout (task continues after timeout), cancel, and post-timeout updates.
+ *
+ * @module agent-pool/tools/results
+ */
+
+import { killGroup, getSystemLoad } from '../runner/process-manager.js';
+
+/** @type {Map<string, {status: string, prompt: string, approvalMode: string, result: object|null, error: string|null, startedAt: number, completedAt: number|null, pollCount: number, waitHint: string|null, pid: number|null}>} */
+const taskStore = new Map();
+
+/** Max number of live events to keep per task (ring buffer) */
+const MAX_LIVE_EVENTS = 200;
+
+/** TTL for completed tasks in ms (10 minutes) */
+const TASK_TTL_MS = 10 * 60 * 1000;
+
+// ─── Error classification for retry hints ───────────────────
+
+/**
+ * Classify error text and return a retry hint for the calling agent.
+ * @param {string} errorText
+ * @returns {string} Retry instruction
+ */
+function classifyError(errorText) {
+  const lower = errorText.toLowerCase();
+
+  if (lower.includes('429') || lower.includes('rate limit') || lower.includes('quota') || lower.includes('resource_exhausted')) {
+    return '🔄 **Rate limited.** Wait 30-60 seconds, then retry the same task with `delegate_task`.';
+  }
+  if (lower.includes('network') || lower.includes('econnrefused') || lower.includes('econnreset') || lower.includes('etimedout') || lower.includes('fetch failed') || lower.includes('socket hang up')) {
+    return '🔄 **Network error.** Check connectivity and retry the task. This is usually transient.';
+  }
+  if (lower.includes('401') || lower.includes('403') || lower.includes('unauthenticated') || lower.includes('permission denied') || lower.includes('not authenticated')) {
+    return '🔑 **Authentication error.** Run `gemini` in terminal to re-authenticate, then retry.';
+  }
+  if (lower.includes('enomem') || lower.includes('out of memory') || lower.includes('heap')) {
+    return '💾 **Out of memory.** Too many parallel workers. Cancel some tasks with `cancel_task`, then retry.';
+  }
+  if (lower.includes('spawn') || lower.includes('enoent')) {
+    return '⚙️ **Gemini CLI not found.** Install: `npm install -g @google/gemini-cli`';
+  }
+  return '🔄 **Unexpected error.** You can retry the task with `delegate_task`. If the error persists, try a simpler prompt or check `npx agent-pool-mcp --check`.';
+}
+
+// Coaching hints — nudge the agent to think about delegation
+const COACHING_HINTS = [
+  'Think: what else can you do in parallel while this task runs? Delegate another task or work on something independent.',
+  'This worker is busy — don\'t wait idle. Check your plan: is there another step you can start now?',
+  'Pro tip: batch your delegation. Send 2-3 tasks at once, then collect results when all are done.',
+  'Instead of polling, make progress on your main task. Come back to check results after a few steps.',
+  'While the worker handles this, consider: is there a subtask you can delegate to another worker?',
+  'Your time is valuable. Use consult_peer to validate your next architectural decision while this runs.',
+  'Polling too often wastes tokens. Do meaningful work first, then check results.',
+  'Is there a code review, analysis, or research task you can delegate right now?',
+];
+
+/**
+ * Create a new task entry in the store.
+ *
+ * @param {string} taskId - Task UUID
+ * @param {string} prompt - Task prompt
+ * @param {string} [waitHint] - Custom coaching hint for polling
+ * @param {string} [approvalMode] - Approval mode (yolo, auto_edit, plan)
+ */
+export function createTask(taskId, prompt, waitHint, approvalMode) {
+  taskStore.set(taskId, {
+    status: 'running',
+    prompt,
+    approvalMode: approvalMode ?? 'unknown',
+    result: null,
+    error: null,
+    startedAt: Date.now(),
+    completedAt: null,
+    pollCount: 0,
+    waitHint: waitHint ?? null,
+    pid: null,
+    liveEvents: [],
+  });
+}
+
+/**
+ * Push a live event to a running task (for progress tracking).
+ *
+ * @param {string} taskId
+ * @param {object} event - Parsed stream-json event
+ */
+export function pushTaskEvent(taskId, event) {
+  const entry = taskStore.get(taskId);
+  if (entry && entry.status === 'running') {
+    entry.liveEvents.push(event);
+    // Ring buffer: keep only the last MAX_LIVE_EVENTS
+    if (entry.liveEvents.length > MAX_LIVE_EVENTS) {
+      entry.liveEvents = entry.liveEvents.slice(-MAX_LIVE_EVENTS);
+    }
+  }
+}
+
+/**
+ * Associate a PID with a task (called after spawn).
+ *
+ * @param {string} taskId
+ * @param {number} pid
+ */
+export function setTaskPid(taskId, pid) {
+  const entry = taskStore.get(taskId);
+  if (entry) entry.pid = pid;
+}
+
+/**
+ * Mark a task as completed with result.
+ *
+ * @param {string} taskId
+ * @param {object} result
+ */
+export function completeTask(taskId, result) {
+  const entry = taskStore.get(taskId);
+  if (entry) {
+    entry.status = 'done';
+    entry.result = result;
+    entry.completedAt = Date.now();
+    entry.pid = null;
+  }
+}
+
+/**
+ * Update a task that already resolved via soft timeout with final complete data.
+ * Only updates if the task is already 'done' with softTimeout flag.
+ *
+ * @param {string} taskId
+ * @param {object} result - Full result from process completion
+ */
+export function updateTaskResult(taskId, result) {
+  const entry = taskStore.get(taskId);
+  if (entry && entry.status === 'done' && entry.result?.softTimeout) {
+    entry.result = result;
+    entry.pid = null;
+  }
+}
+
+/**
+ * Mark a task as failed with error.
+ *
+ * @param {string} taskId
+ * @param {string} errorMessage
+ */
+export function failTask(taskId, errorMessage) {
+  const entry = taskStore.get(taskId);
+  if (entry) {
+    entry.status = 'error';
+    entry.error = errorMessage;
+    entry.completedAt = Date.now();
+    entry.pid = null;
+  }
+}
+
+/**
+ * Cancel a running task — kill its process and mark as cancelled.
+ *
+ * @param {string} taskId
+ * @returns {{content: Array<{type: string, text: string}>, isError?: boolean}}
+ */
+export function cancelTask(taskId) {
+  const entry = taskStore.get(taskId);
+  if (!entry) {
+    return {
+      content: [{ type: 'text', text: `❌ Task not found: \`${taskId}\`` }],
+      isError: true,
+    };
+  }
+
+  if (entry.status !== 'running') {
+    return {
+      content: [{ type: 'text', text: `⚠️ Task \`${taskId.substring(0, 8)}\` is already ${entry.status}, cannot cancel.` }],
+    };
+  }
+
+  const elapsed = ((Date.now() - entry.startedAt) / 1000).toFixed(0);
+  let killed = false;
+  if (entry.pid) {
+    killed = killGroup(entry.pid);
+  }
+  entry.status = 'cancelled';
+  entry.completedAt = Date.now();
+  entry.pid = null;
+
+  return {
+    content: [{
+      type: 'text',
+      text: `🛑 Task \`${taskId.substring(0, 8)}\` cancelled after ${elapsed}s.${killed ? ' Process killed.' : ''}`,
+    }],
+  };
+}
+
+/**
+ * Get task entry from store.
+ *
+ * @param {string} taskId
+ * @returns {object|undefined}
+ */
+export function getTask(taskId) {
+  return taskStore.get(taskId);
+}
+
+/**
+ * Remove task from store.
+ *
+ * @param {string} taskId
+ */
+export function removeTask(taskId) {
+  taskStore.delete(taskId);
+}
+
+/**
+ * Get summary of all active tasks for inclusion in tool responses.
+ *
+ * @returns {string|null} Formatted active tasks string, or null if none
+ */
+export function getActiveTasks() {
+  const active = [...taskStore.entries()]
+    .filter(([, entry]) => entry.status === 'running')
+    .map(([id, entry]) => {
+      const elapsed = ((Date.now() - entry.startedAt) / 1000).toFixed(0);
+      const pidInfo = entry.pid ? ` pid:${entry.pid}` : '';
+      return `- \`${id.substring(0, 8)}\` (${elapsed}s${pidInfo}) ${entry.prompt.substring(0, 60)}...`;
+    });
+  if (active.length === 0) return null;
+  return `\n\n---\n📋 **Active tasks (${active.length})**:\n${active.join('\n')}`;
+}
+
+/**
+ * Format task result for MCP response.
+ * When task is running, returns coaching hints to encourage parallel work.
+ *
+ * @param {string} taskId
+ * @returns {{content: Array<{type: string, text: string}>, isError?: boolean}}
+ */
+export function formatTaskResult(taskId) {
+  const entry = taskStore.get(taskId);
+  if (!entry) {
+    return {
+      content: [{ type: 'text', text: `❌ Task not found: \`${taskId}\`` }],
+      isError: true,
+    };
+  }
+
+  if (entry.status === 'running') {
+    const elapsed = ((Date.now() - entry.startedAt) / 1000).toFixed(0);
+    entry.pollCount++;
+
+    // Use custom hint if set, otherwise rotate through coaching hints
+    const hint = entry.waitHint
+      ? entry.waitHint
+      : COACHING_HINTS[(entry.pollCount - 1) % COACHING_HINTS.length];
+
+    // Build progress from live events
+    let progress = '';
+    if (entry.liveEvents.length > 0) {
+      const tools = entry.liveEvents.filter((e) => e.type === 'tool_use');
+      const toolResults = entry.liveEvents.filter((e) => e.type === 'tool_result');
+      const messages = entry.liveEvents.filter((e) => e.type === 'message' && e.role === 'assistant');
+      const parts = [];
+
+      // Show last 3 tool calls with args and results
+      if (tools.length > 0) {
+        const toolLines = tools.slice(-3).map((t) => {
+          const name = t.tool_name ?? t.name ?? '?';
+          const args = t.parameters ?? t.arguments ?? {};
+          // Extract the most meaningful arg — Gemini uses file_path, path, query, etc.
+          const detail = args.file_path ?? args.path ?? args.file ?? args.query ?? args.symbol ?? args.command ?? '';
+          let shortDetail = '';
+          if (typeof detail === 'string' && detail.length > 0) {
+            // Absolute paths: always trim from start — the tail (project/file) matters most
+            const display = detail.startsWith('/') && detail.length > 30
+              ? '…' + detail.slice(-30)
+              : detail.length > 60 ? '…' + detail.slice(-55) : detail;
+            shortDetail = ` → ${display}`;
+          }
+
+          // Find matching tool_result by tool_id
+          let resultInfo = '';
+          if (t.tool_id) {
+            const result = toolResults.find((r) => r.tool_id === t.tool_id);
+            if (result) {
+              // Calculate duration from timestamps
+              if (t.timestamp && result.timestamp) {
+                const duration = ((new Date(result.timestamp) - new Date(t.timestamp)) / 1000).toFixed(1);
+                resultInfo += ` (${duration}s)`;
+              }
+              // Show brief result output
+              const output = result.output ?? '';
+              if (output && typeof output === 'string' && output.length > 0) {
+                resultInfo += ` ${result.status === 'success' ? '✓' : '✗'} ${output.substring(0, 60)}`;
+              }
+            } else {
+              resultInfo = ' ⏳ running...';
+            }
+          }
+          return `  \`${name}\`${shortDetail}${resultInfo}`;
+        });
+        parts.push(`🔧 Tools (${tools.length}):\n${toolLines.join('\n')}`);
+      }
+
+      // Show last assistant message (agent's thinking/conclusion)
+      if (messages.length > 0) {
+        const lastMsg = messages[messages.length - 1];
+        const text = (lastMsg.content ?? lastMsg.text ?? '').substring(0, 150);
+        if (text) parts.push(`💬 ${text}`);
+      }
+
+      if (parts.length > 0) {
+        progress = `\n\n**Progress:**\n${parts.join('\n')}`;
+      }
+    } else if (parseInt(elapsed) > 10) {
+      progress = '\n\n⏳ *Cold start — Gemini CLI initialization takes ~15-20s*';
+    }
+
+    // System load awareness during polling
+    const load = getSystemLoad();
+    const loadInfo = load.warning ? `\n\n${load.warning}` : '';
+
+    const modeLabel = entry.approvalMode === 'plan' ? '🔒 read-only' : entry.approvalMode === 'yolo' ? '✏️ full-access' : `⚙️ ${entry.approvalMode}`;
+
+    return {
+      content: [{
+        type: 'text',
+        text: `⏳ Task is still running (${elapsed}s elapsed, ${entry.liveEvents.length} events).\n\n- **Prompt**: ${entry.prompt.substring(0, 100)}...\n- **Mode**: ${modeLabel}${progress}\n\n💡 **${hint}**${loadInfo}\n\nCheck again later with \`get_task_result\`.`,
+      }],
+    };
+  }
+
+  if (entry.status === 'cancelled') {
+    removeTask(taskId);
+    return {
+      content: [{ type: 'text', text: `🛑 Task was cancelled.` }],
+    };
+  }
+
+  if (entry.status === 'error') {
+    const errorText = entry.error ?? 'Unknown error';
+    const retryHint = classifyError(errorText);
+    removeTask(taskId);
+    return {
+      content: [{ type: 'text', text: `❌ Task failed: ${errorText}\n\n${retryHint}` }],
+      isError: true,
+    };
+  }
+
+  // Done — format result
+  const result = entry.result;
+  // Don't remove soft-timeout tasks — process is still running, updateTaskResult will update later
+  if (!result.softTimeout) {
+    removeTask(taskId);
+  }
+
+  const sections = [];
+
+  // Soft timeout indicator
+  if (result.softTimeout) {
+    sections.push(`> ⏳ **Soft timeout** reached after ${result.timeoutSeconds}s. Process may still be running — partial result below.`);
+  }
+
+  // Agent failed with non-zero exit and no response — show diagnostic info
+  if (result.exitCode && result.exitCode !== 0 && !result.response) {
+    sections.push(`## ⚠️ Agent Failed (exit code ${result.exitCode})\n\nThe agent process terminated without producing a response.`);
+    if (result.toolCalls?.length > 0) {
+      const lastTools = result.toolCalls.slice(-5).map((t) => `- \`${t.name}\``).join('\n');
+      sections.push(`### Last Tool Calls\n\n${lastTools}`);
+    }
+    if (result.errors?.length > 0) {
+      sections.push(`### Errors\n\n${result.errors.join('\n')}`);
+    }
+    const errorSignal = (result.errors ?? []).join(' ');
+    sections.push(`### Recovery\n\n${classifyError(errorSignal || `exit code ${result.exitCode}`)}`);
+  }
+
+  if (result.response) {
+    sections.push(`## Agent Response\n\n${result.response}`);
+  }
+  if (result.toolCalls?.length > 0 && result.response) {
+    const toolSummary = result.toolCalls.map((t) => `- **${t.name}**`).join('\n');
+    sections.push(`## Tools Used (${result.toolCalls.length})\n\n${toolSummary}`);
+  }
+  if (result.errors?.length > 0 && result.response) {
+    sections.push(`## Errors\n\n${result.errors.join('\n')}`);
+  }
+  const statParts = [];
+  if (entry.approvalMode) statParts.push(`- Mode: ${entry.approvalMode}`);
+  if (result.sessionId) statParts.push(`- Session ID: \`${result.sessionId}\``);
+  if (result.stats) {
+    const s = result.stats;
+    const models = Object.keys(s.models ?? {});
+    if (models.length > 0) statParts.push(`- Models: ${models.join(', ')}`);
+    if (s.total_tokens) statParts.push(`- Tokens: ${s.total_tokens} total`);
+    if (s.duration_ms) statParts.push(`- Duration: ${(s.duration_ms / 1000).toFixed(1)}s`);
+  }
+  if (result.exitCode !== null && result.exitCode !== undefined) {
+    statParts.push(`- Exit code: ${result.exitCode}`);
+  }
+  sections.push(`## Stats\n\n${statParts.join('\n')}`);
+
+  return {
+    content: [{ type: 'text', text: sections.join('\n\n---\n\n') }],
+  };
+}
+
+// TTL auto-cleanup: purge completed tasks that were never polled
+setInterval(() => {
+  const now = Date.now();
+  for (const [taskId, entry] of taskStore) {
+    if (entry.status !== 'running' && entry.completedAt && (now - entry.completedAt) > TASK_TTL_MS) {
+      taskStore.delete(taskId);
+    }
+  }
+}, 60_000).unref();