super-subagents 1.0.1

package/src/tools/resume-task.ts

@@ -0,0 +1,51 @@
+import { ResumeTaskSchema } from '../utils/sanitize.js';
+import { spawnCopilotProcess } from '../services/process-spawner.js';
+import { mcpText, formatError, join } from '../utils/format.js';
+
+export const resumeTaskTool = {
+  name: 'resume_task',
+  description: `Resume an interrupted Copilot session. Get session_id from get_status response.`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      session_id: {
+        type: 'string',
+        description: 'Session ID from previous task.'
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory. Auto-detected if omitted.'
+      },
+      timeout: {
+        type: 'number',
+        description: 'Max execution time in ms. Default: 600000 (configurable via MCP_TASK_TIMEOUT_MS).'
+      },
+    },
+    required: ['session_id'],
+  },
+};
+
+export async function handleResumeTask(args: unknown): Promise<{ content: Array<{ type: string; text: string }> }> {
+  try {
+    const input = args as any;
+    const parsed = ResumeTaskSchema.parse({ sessionId: input?.session_id || input?.sessionId, ...input });
+
+    const taskId = await spawnCopilotProcess({
+      prompt: '',
+      timeout: parsed.timeout,
+      cwd: parsed.cwd,
+      autonomous: parsed.autonomous,
+      resumeSessionId: parsed.sessionId,
+    });
+
+    return mcpText(join(
+      `Session \`${parsed.sessionId}\` resumed as task **${taskId}**.`,
+      'Check status with `get_status`.'
+    ));
+  } catch (error) {
+    return mcpText(formatError(
+      error instanceof Error ? error.message : 'Unknown',
+      'Get `session_id` from a completed or failed task using `get_status` before resuming.'
+    ));
+  }
+}

package/src/tools/retry-task.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { taskManager } from '../services/task-manager.js';
+import { TaskStatus } from '../types.js';
+import { mcpText, formatError, join, displayStatus } from '../utils/format.js';
+
+const RetryTaskSchema = z.object({
+  task_id: z.string().min(1).describe('Task ID to retry'),
+});
+
+export const retryTaskTool = {
+  name: 'retry_task',
+  description: `Immediately retry a rate-limited task. Creates new task with same prompt.`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      task_id: {
+        type: 'string',
+        description: 'Rate-limited task ID to retry.',
+      },
+    },
+    required: ['task_id'],
+  },
+};
+
+export async function handleRetryTask(args: unknown): Promise<{ content: Array<{ type: string; text: string }> }> {
+  try {
+    const parsed = RetryTaskSchema.parse(args || {});
+    const taskId = parsed.task_id.toLowerCase().trim();
+
+    const task = taskManager.getTask(taskId);
+
+    if (!task) {
+      return mcpText(formatError('Task not found', 'Use `list_tasks` to find valid task IDs.'));
+    }
+
+    if (task.status !== TaskStatus.RATE_LIMITED) {
+      const hint = task.status === TaskStatus.FAILED
+        ? 'Task has already failed. Use `spawn_task` to create a new task with the same prompt.'
+        : 'Only `rate_limited` tasks can be retried with this tool.';
+      return mcpText(formatError(
+        `Task is not rate-limited (status: ${displayStatus(task.status)})`,
+        hint
+      ));
+    }
+
+    // Check if max retries exceeded
+    if (task.retryInfo && task.retryInfo.retryCount >= task.retryInfo.maxRetries) {
+      return mcpText(formatError(
+        `Max retries exceeded (${task.retryInfo.retryCount}/${task.retryInfo.maxRetries})`,
+        'Use `spawn_task` to create a new task with the same prompt.'
+      ));
+    }
+
+    // Trigger the retry via TaskManager
+    const result = await taskManager.triggerManualRetry(taskId);
+
+    if (!result.success) {
+      return mcpText(formatError(result.error || 'Retry failed'));
+    }
+
+    const attempt = (task.retryInfo?.retryCount ?? 0) + 1;
+    return mcpText(join(
+      `Retried **${task.id}** as **${result.newTaskId}** (attempt ${attempt}).`,
+      'Check status with `get_status`.'
+    ));
+  } catch (error) {
+    return mcpText(formatError(
+      error instanceof Error ? error.message : 'Unknown error',
+      'Ensure `task_id` is provided.'
+    ));
+  }
+}

package/src/tools/simulate-rate-limit.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { taskManager } from '../services/task-manager.js';
+import { TaskStatus } from '../types.js';
+import { createRetryInfo } from '../services/retry-queue.js';
+import { mcpText, formatError, join } from '../utils/format.js';
+
+const SimulateRateLimitSchema = z.object({
+  prompt: z.string().min(1).max(50000).optional().default('Test task for rate limit simulation'),
+  skip_fallback: z.boolean().optional().default(false),
+});
+
+export const simulateRateLimitTool = {
+  name: 'simulate_rate_limit',
+  description: `[DEBUG] Simulate a rate-limited task to test Claude CLI fallback behavior. Creates a task, marks it as rate-limited, and optionally triggers the fallback flow via manual retry.`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Task prompt to use for the simulated task. Default: test prompt.',
+      },
+      skip_fallback: {
+        type: 'boolean',
+        description: 'If true, skip triggering retry/fallback and leave task in RATE_LIMITED state for inspection. Default: false.',
+      },
+    },
+    required: [],
+  },
+};
+
+export async function handleSimulateRateLimit(args: unknown): Promise<{ content: Array<{ type: string; text: string }> }> {
+  try {
+    const parsed = SimulateRateLimitSchema.parse(args || {});
+
+    // Create a task marked as coming from copilot
+    const task = taskManager.createTask(parsed.prompt, undefined, undefined, {
+      provider: 'copilot',
+      fallbackAttempted: parsed.skip_fallback,
+    });
+
+    // Simulate some output
+    taskManager.appendOutput(task.id, 'Starting task...');
+    taskManager.appendOutput(task.id, '[simulated] Error: too many requests, rate limit exceeded');
+
+    // Mark as rate-limited
+    const retryInfo = createRetryInfo(task, 'Simulated rate limit');
+    taskManager.updateTask(task.id, {
+      status: TaskStatus.RATE_LIMITED,
+      exitCode: 1,
+      endTime: new Date().toISOString(),
+      error: 'Simulated: too many requests, rate limit exceeded',
+      retryInfo,
+    });
+
+    // If not skipping fallback, trigger manual retry which will exercise the fallback path
+    let fallbackResult: { success: boolean; newTaskId?: string; error?: string } | undefined;
+    if (!parsed.skip_fallback) {
+      fallbackResult = await taskManager.triggerManualRetry(task.id);
+    }
+
+    let message: string;
+    if (fallbackResult?.success) {
+      message = join(
+        `[Debug] Rate limit simulated for **${task.id}**.`,
+        `Fallback retry triggered as **${fallbackResult.newTaskId}**.`,
+        'Check status with `get_status`.'
+      );
+    } else if (parsed.skip_fallback) {
+      message = join(
+        `[Debug] Rate limit simulated for **${task.id}**.`,
+        'Task left in `rate_limited` state for inspection.'
+      );
+    } else {
+      message = join(
+        `[Debug] Rate limit simulated for **${task.id}**.`,
+        `Fallback trigger failed: ${fallbackResult?.error || 'unknown error'}`
+      );
+    }
+
+    return mcpText(message);
+  } catch (error) {
+    return mcpText(formatError(error instanceof Error ? error.message : 'Unknown error'));
+  }
+}

package/src/tools/spawn-task.ts

@@ -0,0 +1,135 @@
+import { SpawnTaskSchema } from '../utils/sanitize.js';
+import { spawnCopilotProcess } from '../services/process-spawner.js';
+import { taskManager } from '../services/task-manager.js';
+import { MODEL_IDS, MODELS, DEFAULT_MODEL } from '../models.js';
+import { TASK_TYPE_IDS, TASK_TYPES, applyTemplate, isValidTaskType, type TaskType } from '../templates/index.js';
+import { mcpText, formatError, join, formatLabels } from '../utils/format.js';
+
+export const spawnTaskTool = {
+  name: 'spawn_task',
+  description: `Spawn an autonomous agent task. Each task runs as a completely isolated agent with NO shared memory or conversation history -- the prompt you provide is the ONLY context the agent receives.
+
+IMPORTANT: Prefer spawning tasks one at a time with spawn_task. Only use batch_spawn when you have multiple small tasks with explicit cross-dependencies that must be set up atomically. For most work, individual spawn_task calls give you better control and let you write more detailed, context-rich prompts for each task.
+
+Task types: super-coder (implementation), super-planner (architecture), super-researcher (investigation), super-tester (QA).
+Models: ${MODEL_IDS.join(', ')}. Default: ${DEFAULT_MODEL}.`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      prompt: {
+        type: 'string',
+        description: `The complete, self-contained instructions for the spawned agent. This is the ONLY context the agent will have -- it cannot see your conversation history, previous tool calls, or any other context.
+
+Your prompt MUST include:
+- WHAT to do: Clear, specific objective (not vague like "fix the bug" -- say exactly which bug, which file, what the expected behavior is)
+- WHERE to do it: All relevant file paths as absolute paths (e.g. /Users/dev/project/src/auth.ts, not just "auth.ts")
+- HOW to verify: What does "done" look like? What tests to run? What to check?
+- CONTEXT: Any background the agent needs -- error messages, stack traces, related code snippets, architectural decisions
+
+BAD prompt: "Fix the login bug"
+GOOD prompt: "In /Users/dev/myapp/src/services/auth.ts, the login() function on line 45 throws 'TypeError: Cannot read property email of undefined' when the user object is null. Fix the null check, ensure the function returns a proper error response for missing users, and verify by running: npm test -- --grep login"
+
+The more detailed your prompt, the better the agent performs. Treat it as a complete brief for a developer who has never seen the codebase before.`,
+      },
+      task_type: {
+        type: 'string',
+        enum: TASK_TYPE_IDS,
+        description: `Agent template that prepends specialized system instructions to your prompt.
+- super-coder: For implementation tasks -- writing, editing, refactoring code
+- super-planner: For architecture and design -- planning implementations, evaluating tradeoffs
+- super-researcher: For investigation -- answering questions, finding code patterns, analyzing behavior
+- super-tester: For QA -- writing tests, running test suites, verifying behavior`,
+      },
+      model: {
+        type: 'string',
+        enum: MODEL_IDS,
+        description: `Model to use. Default: ${DEFAULT_MODEL}.
+- claude-sonnet-4.5: Best balance of speed and capability (default, recommended for most tasks)
+- claude-haiku-4.5: Fastest -- use for simple, well-defined tasks like running a single command or small edits
+- claude-opus-4.5: Most capable -- use for complex reasoning, large refactors, or tasks requiring deep analysis`,
+      },
+      cwd: {
+        type: 'string',
+        description: `The absolute path to the working directory where the agent will execute. You should detect your current working directory and pass it here as a full absolute path. This is especially important when working in git worktrees -- pass the actual worktree path (e.g. /Users/dev/project/worktrees/feature-branch), NOT the main repository root. Do not create a new worktree just for this -- simply pass the directory you are currently working in.`,
+      },
+      timeout: {
+        type: 'number',
+        description: 'Max execution time in ms. Default: 600000 (10 min, configurable via MCP_TASK_TIMEOUT_MS). Max: 3600000 (configurable via MCP_TASK_TIMEOUT_MAX_MS). Increase for large tasks.',
+      },
+      autonomous: {
+        type: 'boolean',
+        description: 'Run without interactive prompts. Default: true. Almost always leave this as true.',
+      },
+      depends_on: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Task IDs that must complete before this task starts. The task will wait in "waiting" status until all dependencies finish.',
+      },
+      labels: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Labels for grouping and filtering tasks (max 10). Useful when managing multiple related tasks -- e.g. "auth-migration", "phase-1".',
+      },
+    },
+    required: ['prompt'],
+  },
+};
+
+export async function handleSpawnTask(args: unknown): Promise<{ content: Array<{ type: string; text: string }> }> {
+  try {
+    const parsed = SpawnTaskSchema.parse(args);
+
+    // Validate dependencies if provided
+    const dependsOn = parsed.depends_on?.filter((d: string) => d.trim()) || [];
+    if (dependsOn.length > 0) {
+      const validationError = taskManager.validateDependencies(dependsOn);
+      if (validationError) {
+        return mcpText(formatError(
+          validationError,
+          'Ensure all dependency task IDs exist.\nUse `list_tasks` to find valid task IDs.'
+        ));
+      }
+    }
+
+    let finalPrompt = parsed.prompt;
+    if (parsed.task_type && isValidTaskType(parsed.task_type)) {
+      finalPrompt = applyTemplate(parsed.task_type as TaskType, parsed.prompt);
+    }
+
+    const labels = parsed.labels?.filter((l: string) => l.trim()) || [];
+
+    const taskId = await spawnCopilotProcess({
+      prompt: finalPrompt,
+      timeout: parsed.timeout,
+      cwd: parsed.cwd,
+      model: parsed.model,
+      autonomous: parsed.autonomous,
+      dependsOn: dependsOn.length > 0 ? dependsOn : undefined,
+      labels: labels.length > 0 ? labels : undefined,
+    });
+
+    const task = taskManager.getTask(taskId);
+    const isWaiting = task?.status === 'waiting';
+
+    if (isWaiting) {
+      const depsList = dependsOn.map(d => `\`${d}\``).join(', ');
+      return mcpText(join(
+        `Task **${taskId}** spawned (waiting).`,
+        `Depends on: ${depsList}`,
+        '',
+        'Dependencies must complete before this task runs.',
+        'Check status with `get_status`.'
+      ));
+    }
+
+    return mcpText(join(
+      `Task **${taskId}** spawned (${task?.status || 'pending'}).`,
+      'Check status with `get_status`.'
+    ));
+  } catch (error) {
+    return mcpText(formatError(
+      error instanceof Error ? error.message : 'Unknown error',
+      'Check that the `prompt` parameter is provided and valid.'
+    ));
+  }
+}

package/src/tools/stream-output.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { taskManager } from '../services/task-manager.js';
+import { TaskStatus } from '../types.js';
+import { mcpText, formatError, displayStatus, formatDuration, join } from '../utils/format.js';
+import { TASK_STALL_WARN_MS } from '../config/timeouts.js';
+
+const StreamOutputSchema = z.object({
+  task_id: z.string().min(1),
+  offset: z.number().int().min(0).optional().default(0),
+  limit: z.number().int().min(1).max(500).optional().default(100),
+});
+
+export const streamOutputTool = {
+  name: 'stream_output',
+  description: `Get incremental output from a task. Use offset to get new lines since last call. This is the preferred way to monitor task output -- unlike get_status, this tool is not throttled and returns only the new output lines you haven't seen yet.`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      task_id: {
+        type: 'string',
+        description: 'Task ID to stream output from.',
+      },
+      offset: {
+        type: 'number',
+        description: 'Line offset to start from. Default: 0. Use next_offset from response.',
+      },
+      limit: {
+        type: 'number',
+        description: 'Max lines to return. Default: 100. Max: 500.',
+      },
+    },
+    required: ['task_id'],
+  },
+};
+
+export async function handleStreamOutput(args: unknown): Promise<{ content: Array<{ type: string; text: string }> }> {
+  try {
+    const parsed = StreamOutputSchema.parse(args || {});
+    const taskId = parsed.task_id.toLowerCase().trim();
+
+    const task = taskManager.getTask(taskId);
+
+    if (!task) {
+      return mcpText(formatError('Task not found', 'Use `list_tasks` to find valid task IDs.'));
+    }
+
+    const totalLines = task.output.length;
+    const offset = Math.min(parsed.offset, totalLines);
+    const outputLines = task.output.slice(offset, offset + parsed.limit);
+    const nextOffset = offset + outputLines.length;
+    const hasMore = nextOffset < totalLines;
+    const now = Date.now();
+    const lastOutputAgeMs = task.lastOutputAt ? now - new Date(task.lastOutputAt).getTime() : undefined;
+
+    const isTerminal = [
+      TaskStatus.COMPLETED,
+      TaskStatus.FAILED,
+      TaskStatus.CANCELLED,
+      TaskStatus.TIMED_OUT,
+    ].includes(task.status);
+
+    // Build headline
+    const statusStr = displayStatus(task.status);
+    let rangeStr: string;
+    if (outputLines.length > 0) {
+      rangeStr = `lines ${offset}-${nextOffset - 1} of ${totalLines}`;
+    } else {
+      rangeStr = `${totalLines} lines`;
+    }
+    const exitInfo = isTerminal && task.exitCode !== undefined ? `, exit code: ${task.exitCode}` : '';
+    const headline = `**${task.id}** -- ${statusStr} (${rangeStr}${exitInfo})`;
+
+    // Build body
+    let body: string;
+    if (outputLines.length > 0) {
+      body = outputLines.map(l => `> ${l}`).join('\n');
+    } else {
+      body = 'No output yet.';
+    }
+
+    // Build footer
+    let footer: string;
+    if (hasMore) {
+      const remaining = totalLines - nextOffset;
+      footer = `${remaining} more lines available. Use offset \`${nextOffset}\` to continue.`;
+    } else if (isTerminal) {
+      footer = 'All output retrieved.';
+    } else if (lastOutputAgeMs !== undefined && lastOutputAgeMs >= TASK_STALL_WARN_MS) {
+      footer = `No output for ${formatDuration(lastOutputAgeMs)}. Task may be stalled.`;
+    } else {
+      footer = 'Waiting for more output...';
+    }
+
+    // Add error if terminal and has error
+    const errorLine = task.error && isTerminal ? `**Error:** ${task.error}` : undefined;
+
+    return mcpText(join(headline, '', body, '', errorLine, footer));
+  } catch (error) {
+    return mcpText(formatError(error instanceof Error ? error.message : 'Unknown error'));
+  }
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+import type { ResultPromise } from 'execa';
+
+export type Provider = 'copilot' | 'claude-cli';
+
+export enum TaskStatus {
+  PENDING = 'pending',
+  WAITING = 'waiting',
+  RUNNING = 'running',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  RATE_LIMITED = 'rate_limited',
+  TIMED_OUT = 'timed_out',
+}
+
+export type TimeoutReason =
+  | 'hard_timeout'
+  | 'stall'
+  | 'process_dead'
+  | 'server_restart'
+  | 'unknown';
+
+export interface TimeoutContext {
+  timeoutMs?: number;
+  timeoutAt?: string;
+  elapsedMs?: number;
+  lastOutputAt?: string;
+  lastOutputAgeMs?: number;
+  lastHeartbeatAt?: string;
+  pidAlive?: boolean;
+  detectedBy?: 'execa' | 'health_check' | 'startup_recovery' | 'manual';
+}
+
+export interface RetryInfo {
+  reason: string;
+  retryCount: number;
+  nextRetryTime: string;
+  maxRetries: number;
+  originalTaskId?: string;
+}
+
+export interface TaskState {
+  id: string;
+  status: TaskStatus;
+  prompt: string;
+  output: string[];
+  pid?: number;
+  sessionId?: string;
+  startTime: string;
+  lastOutputAt?: string;
+  lastHeartbeatAt?: string;
+  endTime?: string;
+  exitCode?: number;
+  error?: string;
+  cwd?: string;
+  model?: string;
+  autonomous?: boolean;
+  isResume?: boolean;
+  process?: ResultPromise;
+  retryInfo?: RetryInfo;
+  dependsOn?: string[];
+  timeout?: number;
+  timeoutAt?: string;
+  timeoutReason?: TimeoutReason;
+  timeoutContext?: TimeoutContext;
+  labels?: string[];
+  provider?: Provider;
+  fallbackAttempted?: boolean;
+  switchAttempted?: boolean;
+  recoveryAttempted?: boolean;
+}
+
+export interface SpawnOptions {
+  prompt: string;
+  timeout?: number;
+  cwd?: string;
+  model?: string;
+  autonomous?: boolean;
+  resumeSessionId?: string;
+  retryInfo?: RetryInfo;
+  dependsOn?: string[];
+  labels?: string[];
+  provider?: Provider;
+  fallbackAttempted?: boolean;
+  switchAttempted?: boolean;
+}

package/src/utils/format.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared formatting helpers for converting MCP tool responses to markdown.
+ */
+
+/** Wraps a markdown string in the MCP response shape. */
+export function mcpText(markdown: string): { content: Array<{ type: string; text: string }> } {
+  return { content: [{ type: 'text', text: markdown }] };
+}
+
+/** Display status in human-readable form: "rate_limited" -> "rate limited" */
+export function displayStatus(status: string): string {
+  return status.replace(/_/g, ' ');
+}
+
+/** Format labels as inline code: "`label-a`, `label-b`". Returns empty string if none. */
+export function formatLabels(labels?: string[]): string {
+  if (!labels || labels.length === 0) return '';
+  return labels.map(l => `\`${l}\``).join(', ');
+}
+
+/** "Labels: `a`, `b`" or empty string. */
+export function formatLabelsLine(labels?: string[]): string {
+  const f = formatLabels(labels);
+  return f ? `Labels: ${f}` : '';
+}
+
+/** Milliseconds to human duration: 541364 -> "~9m" */
+export function formatDuration(ms: number): string {
+  if (ms <= 0) return '0s';
+  const totalSec = Math.round(ms / 1000);
+  if (totalSec < 60) return `~${totalSec}s`;
+  const min = Math.round(totalSec / 60);
+  if (min < 60) return `~${min}m`;
+  const h = Math.floor(min / 60);
+  const rm = min % 60;
+  return rm === 0 ? `~${h}h` : `~${h}h ${rm}m`;
+}
+
+/** Format output as a blockquote with optional truncation. Returns empty string for empty output. */
+export function formatOutputBlock(output: string, label = 'Output', maxLen = 2000): string {
+  if (!output || !output.trim()) return '';
+  let text = output;
+  let truncated = false;
+  if (text.length > maxLen) {
+    text = text.slice(-maxLen);
+    truncated = true;
+  }
+  const quoted = text.split('\n').map(line => `> ${line}`).join('\n');
+  const parts = [`**${label}:**`, quoted];
+  if (truncated) parts.push('*(truncated -- use `stream_output` for full output)*');
+  return parts.join('\n');
+}
+
+/** Standard error block with optional actionable hint. */
+export function formatError(error: string, hint?: string): string {
+  const parts = [`**Error:** ${error}`];
+  if (hint) parts.push('', hint);
+  return parts.join('\n');
+}
+
+/** "Run `sleep 120` then check again." or empty string. */
+export function formatRetryHint(retryCommand?: string): string {
+  if (!retryCommand) return '';
+  return `Run \`${retryCommand}\` then check again.`;
+}
+
+/** Escape pipe characters in table cell content. */
+function escapeCell(value: string): string {
+  return value.replace(/\|/g, '\\|');
+}
+
+/** Render a markdown table from headers and rows. */
+export function formatTable(headers: string[], rows: string[][]): string {
+  const headerRow = `| ${headers.map(escapeCell).join(' | ')} |`;
+  const separator = `|${headers.map(() => '------').join('|')}|`;
+  const dataRows = rows.map(r => `| ${r.map(escapeCell).join(' | ')} |`);
+  return [headerRow, separator, ...dataRows].join('\n');
+}
+
+/** Join non-empty strings with newlines, filtering out falsy/empty values. */
+export function join(...parts: (string | undefined | false | null)[]): string {
+  return parts.filter(p => typeof p === 'string' && p.length > 0).join('\n');
+}

package/src/utils/sanitize.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { MODEL_IDS } from '../models.js';
+import { TASK_TYPE_IDS } from '../templates/index.js';
+import {
+  TASK_TIMEOUT_DEFAULT_MS,
+  TASK_TIMEOUT_MAX_MS,
+  TASK_TIMEOUT_MIN_MS,
+} from '../config/timeouts.js';
+
+export const SpawnTaskSchema = z.object({
+  prompt: z.string().min(1).max(50000),
+  timeout: z.number().int().min(TASK_TIMEOUT_MIN_MS).max(TASK_TIMEOUT_MAX_MS).optional().default(TASK_TIMEOUT_DEFAULT_MS), // 10 minutes default
+  cwd: z.string().optional(),
+  model: z.enum(MODEL_IDS as [string, ...string[]]).optional(),
+  task_type: z.enum(TASK_TYPE_IDS as [string, ...string[]]).optional(),
+  autonomous: z.boolean().optional().default(true),
+  depends_on: z.array(z.string().min(1)).optional(),
+  labels: z.array(z.string().min(1).max(50)).max(10).optional(),
+});
+
+export const ResumeTaskSchema = z.object({
+  sessionId: z.string().min(1),
+  timeout: z.number().int().min(TASK_TIMEOUT_MIN_MS).max(TASK_TIMEOUT_MAX_MS).optional().default(TASK_TIMEOUT_DEFAULT_MS), // 10 minutes default
+  cwd: z.string().optional(),
+  autonomous: z.boolean().optional().default(true),
+});
+
+export const GetTaskStatusSchema = z.object({
+  taskId: z.union([z.string().min(1), z.array(z.string().min(1))]),
+});
+
+export const ListTasksSchema = z.object({
+  status: z.enum(['pending', 'waiting', 'running', 'completed', 'failed', 'cancelled', 'rate_limited', 'timed_out']).optional(),
+  label: z.string().min(1).optional(),
+});

package/src/utils/task-id-generator.ts

@@ -0,0 +1,25 @@
+import { uniqueNamesGenerator, adjectives, colors, animals, names } from 'unique-names-generator';
+
+/**
+ * Generates human-readable task IDs like "brave-tiger-42" or "cosmic-falcon-17"
+ * Much easier to remember and communicate than UUIDs or random strings
+ */
+export function generateTaskId(): string {
+  const randomNumber = Math.floor(Math.random() * 100);
+  
+  const name = uniqueNamesGenerator({
+    dictionaries: [adjectives, animals],
+    separator: '-',
+    length: 2,
+    style: 'lowerCase',
+  });
+  
+  return `${name}-${randomNumber}`;
+}
+
+/**
+ * Normalizes task ID for case-insensitive lookups
+ */
+export function normalizeTaskId(taskId: string): string {
+  return taskId.toLowerCase().trim();
+}