mcp-codex-worker 0.1.11 → 0.1.13

package/src/execution/copilot-adapter.ts

@@ -0,0 +1,40 @@
+// ---------------------------------------------------------------------------
+// CopilotAdapter — Phase 2 stub
+// Spec reference: §3.4
+// ---------------------------------------------------------------------------
+
+import type { Provider } from '../task/task-state.js';
+import type { TaskHandle } from '../task/task-handle.js';
+import type { ProviderCapabilities } from './provider-capabilities.js';
+import { COPILOT_CAPABILITIES } from './provider-capabilities.js';
+import {
+  BaseProviderAdapter,
+  type ProviderSpawnOptions,
+  type AvailabilityResult,
+} from './base-adapter.js';
+
+export class CopilotAdapter extends BaseProviderAdapter {
+  readonly id: Provider = 'copilot';
+  readonly displayName = 'Copilot';
+
+  checkAvailability(): AvailabilityResult {
+    return { available: false, reason: 'Phase 2 — not yet implemented' };
+  }
+
+  getCapabilities(): ProviderCapabilities {
+    return COPILOT_CAPABILITIES;
+  }
+
+  getStats(): Record<string, unknown> {
+    return {};
+  }
+
+  protected async executeSession(
+    _handle: TaskHandle,
+    _prompt: string,
+    _signal: AbortSignal,
+    _options: ProviderSpawnOptions,
+  ): Promise<void> {
+    throw new Error('Not implemented — Phase 2');
+  }
+}

package/src/execution/provider-capabilities.ts

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// CapabilityMatrix — runtime-enforced provider contract
+// Spec reference: §3.4
+// ---------------------------------------------------------------------------
+
+import type { PendingQuestionType } from '../task/task-state.js';
+
+/**
+ * Declares what a provider adapter can do at runtime.
+ * TaskManager reads these at startup and uses them to route behavior.
+ */
+export interface ProviderCapabilities {
+  /** Session survives server restart (e.g. Codex rollout files). */
+  sessionPersistence: boolean;
+  /** Distinct approve/decline protocol (e.g. Codex 4 approval types). */
+  structuredApproval: boolean;
+  /** Can stream tokens/chunks. */
+  streamingOutput: boolean;
+  /** Has explicit cancel primitive (e.g. turn/interrupt). */
+  abortPrimitive: boolean;
+  /** Supports thread/read-style probe for crash recovery. */
+  crashRecovery: boolean;
+  /** How the provider selects a model. */
+  modelRouting: 'config' | 'api-param' | 'none';
+  /** Emits structured rate-limit error. */
+  rateLimitSignal: boolean;
+  /** Subset of the 5 PendingQuestion types this provider supports. */
+  pauseTypes: readonly PendingQuestionType[];
+}
+
+// ---------------------------------------------------------------------------
+// Concrete capability declarations — Phase 1 matrix
+// ---------------------------------------------------------------------------
+
+const ALL_PAUSE_TYPES: readonly PendingQuestionType[] = [
+  'user_input',
+  'command_approval',
+  'file_approval',
+  'elicitation',
+  'dynamic_tool',
+] as const;
+
+export const CODEX_CAPABILITIES: Readonly<ProviderCapabilities> = {
+  sessionPersistence: true,
+  structuredApproval: true,
+  streamingOutput: true,
+  abortPrimitive: true,
+  crashRecovery: true,
+  modelRouting: 'config',
+  rateLimitSignal: true,
+  pauseTypes: ALL_PAUSE_TYPES,
+};
+
+export const COPILOT_CAPABILITIES: Readonly<ProviderCapabilities> = {
+  sessionPersistence: false,
+  structuredApproval: false,
+  streamingOutput: true,
+  abortPrimitive: true,
+  crashRecovery: false,
+  modelRouting: 'api-param',
+  rateLimitSignal: true,
+  pauseTypes: ['user_input'] as const,
+};
+
+export const CLAUDE_CAPABILITIES: Readonly<ProviderCapabilities> = {
+  sessionPersistence: false,
+  structuredApproval: false,
+  streamingOutput: true,
+  abortPrimitive: true,
+  crashRecovery: false,
+  modelRouting: 'api-param',
+  rateLimitSignal: true,
+  pauseTypes: ['user_input'] as const,
+};
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+  ok: boolean;
+  reason?: string;
+}
+
+/**
+ * Validates that a pause type is supported by the provider's capabilities.
+ * Returns `{ ok: false, reason }` if the provider does not support the given type.
+ */
+export function validateResponseAgainstCapabilities(
+  caps: ProviderCapabilities,
+  pauseType: PendingQuestionType,
+): ValidationResult {
+  if (caps.pauseTypes.includes(pauseType)) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    reason: `this provider does not support ${pauseType} responses`,
+  };
+}

package/src/execution/provider-registry.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// ProviderRegistry — routes task types to provider adapters
+// Spec reference: §3.4
+// ---------------------------------------------------------------------------
+
+import type { Provider, TaskTypeName } from '../task/task-state.js';
+import type { BaseProviderAdapter } from './base-adapter.js';
+
+/**
+ * Central registry for provider adapters.
+ *
+ * Supports:
+ * - Registration by provider ID
+ * - Default fallback provider
+ * - Per-task-type routing overrides
+ * - Bulk shutdown
+ */
+export class ProviderRegistry {
+  private readonly adapters = new Map<Provider, BaseProviderAdapter>();
+  private defaultProvider: Provider | undefined;
+  private readonly taskTypeRoutes = new Map<TaskTypeName, Provider>();
+
+  /** Register an adapter. Keyed by its `id` property. */
+  register(adapter: BaseProviderAdapter): void {
+    this.adapters.set(adapter.id, adapter);
+  }
+
+  /** Set the fallback provider used when no task-type route matches. */
+  setDefault(provider: Provider): void {
+    this.defaultProvider = provider;
+  }
+
+  /** Override routing for a specific task type. */
+  setTaskTypeRoute(taskType: TaskTypeName, provider: Provider): void {
+    this.taskTypeRoutes.set(taskType, provider);
+  }
+
+  /** Look up an adapter by provider ID. */
+  getAdapter(provider: Provider): BaseProviderAdapter | undefined {
+    return this.adapters.get(provider);
+  }
+
+  /**
+   * Select the best adapter for a given task type.
+   *
+   * Resolution order:
+   * 1. Explicit task-type route
+   * 2. Default provider
+   * 3. First registered adapter (arbitrary but deterministic)
+   */
+  selectForTaskType(taskType: TaskTypeName): BaseProviderAdapter | undefined {
+    // 1. Check explicit route
+    const routed = this.taskTypeRoutes.get(taskType);
+    if (routed !== undefined) {
+      const adapter = this.adapters.get(routed);
+      if (adapter) return adapter;
+    }
+
+    // 2. Check default
+    if (this.defaultProvider !== undefined) {
+      const adapter = this.adapters.get(this.defaultProvider);
+      if (adapter) return adapter;
+    }
+
+    // 3. Fall back to first registered
+    const all = Array.from(this.adapters.values());
+    return all.length > 0 ? all[0] : undefined;
+  }
+
+  /** Return all registered adapters. */
+  getAllAdapters(): BaseProviderAdapter[] {
+    return Array.from(this.adapters.values());
+  }
+
+  /** Shut down all registered adapters in parallel. */
+  async shutdownAll(): Promise<void> {
+    await Promise.all(
+      Array.from(this.adapters.values()).map((a) => a.shutdown()),
+    );
+  }
+}

package/src/mcp/resource-renderers.ts

@@ -0,0 +1,224 @@
+import { TaskStatus, TERMINAL_STATUSES } from '../task/task-state.js';
+import type { TaskState, PendingQuestion } from '../task/task-state.js';
+import { mapToDisplay } from '../task/wire-state-mapper.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const PROMPT_MAX_LEN = 50;
+const SUMMARY_LOG_LINES = 20;
+const DETAIL_OUTPUT_LINES = 10;
+
+// ---------------------------------------------------------------------------
+// Sorting helpers
+// ---------------------------------------------------------------------------
+
+/** Active statuses that should appear first on the scoreboard. */
+const ACTIVE_STATUSES: ReadonlySet<TaskStatus> = new Set([
+  TaskStatus.RUNNING,
+  TaskStatus.WAITING_ANSWER,
+  TaskStatus.RATE_LIMITED,
+]);
+
+/** Pending statuses that appear between active and terminal. */
+const PENDING_STATUSES: ReadonlySet<TaskStatus> = new Set([
+  TaskStatus.WAITING,
+  TaskStatus.PENDING,
+]);
+
+function sortPriority(status: TaskStatus): number {
+  if (ACTIVE_STATUSES.has(status)) return 0;
+  if (PENDING_STATUSES.has(status)) return 1;
+  return 2; // terminal
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+function truncatePrompt(prompt: string, maxLen: number = PROMPT_MAX_LEN): string {
+  if (prompt.length <= maxLen) return prompt;
+  return prompt.slice(0, maxLen - 3) + '...';
+}
+
+function formatElapsed(createdAt: string, updatedAt: string): string {
+  const start = new Date(createdAt).getTime();
+  const end = new Date(updatedAt).getTime();
+  const diffMs = Math.max(0, end - start);
+
+  const totalSec = Math.floor(diffMs / 1000);
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+
+  if (min > 0) {
+    return `${min}m ${sec}s`;
+  }
+  return `${sec}s`;
+}
+
+/**
+ * Build a status-count summary string like "3 done, 1 busy, 1 wait".
+ * Uses the display badge labels (without brackets) as category names.
+ */
+function statusSummary(tasks: TaskState[]): string {
+  const counts = new Map<string, number>();
+  for (const t of tasks) {
+    const badge = mapToDisplay(t.status);
+    // Strip brackets: "[busy]" → "busy"
+    const label = badge.slice(1, -1);
+    counts.set(label, (counts.get(label) ?? 0) + 1);
+  }
+  return Array.from(counts.entries())
+    .map(([label, count]) => `${count} ${label}`)
+    .join(', ');
+}
+
+// ---------------------------------------------------------------------------
+// renderScoreboard
+// ---------------------------------------------------------------------------
+
+/**
+ * Compact all-tasks view.
+ *
+ * Resource URI: `task:///all`
+ */
+export function renderScoreboard(tasks: TaskState[]): string {
+  const sorted = [...tasks].sort((a, b) => sortPriority(a.status) - sortPriority(b.status));
+
+  const summary = tasks.length > 0 ? ` (${statusSummary(tasks)})` : '';
+  const header = `tasks -- ${tasks.length} total${summary}`;
+
+  const lines: string[] = [header, ''];
+
+  for (const task of sorted) {
+    const badge = mapToDisplay(task.status);
+    const prompt = truncatePrompt(task.prompt);
+    const elapsed = formatElapsed(task.createdAt, task.updatedAt);
+    lines.push(`${badge} ${task.id} -- "${prompt}" (${elapsed})`);
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// renderTaskDetail
+// ---------------------------------------------------------------------------
+
+/**
+ * Full task detail view as markdown.
+ *
+ * Resource URI: `task:///{id}`
+ */
+export function renderTaskDetail(task: TaskState): string {
+  const badge = mapToDisplay(task.status);
+
+  const lines: string[] = [
+    `# Task: ${task.id} -- ${truncatePrompt(task.prompt)}`,
+    '',
+    '| Field | Value |',
+    '|---|---|',
+    `| **Status** | ${badge} \`${task.status}\` |`,
+    `| **Provider** | ${task.provider} |`,
+  ];
+
+  if (task.sessionId) {
+    lines.push(`| **Session ID** | \`${task.sessionId}\` |`);
+  }
+
+  if (task.model) {
+    lines.push(`| **Model** | \`${task.model}\` |`);
+  }
+
+  lines.push(`| **Task type** | ${task.taskType} |`);
+  lines.push(`| **CWD** | \`${task.cwd}\` |`);
+  lines.push(`| **Created** | ${task.createdAt} |`);
+
+  if (task.startedAt) {
+    lines.push(`| **Started** | ${task.startedAt} |`);
+  }
+  if (task.completedAt) {
+    lines.push(`| **Completed** | ${task.completedAt} |`);
+  }
+
+  lines.push(`| **Updated** | ${task.updatedAt} |`);
+  lines.push('');
+
+  // Pending questions
+  if (task.pendingQuestions.length > 0) {
+    lines.push('## Pending Question', '');
+    for (const q of task.pendingQuestions) {
+      lines.push(formatPendingQuestion(q));
+    }
+    lines.push('');
+  }
+
+  // Error
+  if (task.error) {
+    lines.push('## Error', '', `\`\`\`\n${task.error}\n\`\`\``, '');
+  }
+
+  // Last N output lines
+  if (task.output.length > 0) {
+    const tail = task.output.slice(-DETAIL_OUTPUT_LINES);
+    lines.push('## Recent Output', '');
+    for (const line of tail) {
+      lines.push(line);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatPendingQuestion(q: PendingQuestion): string {
+  switch (q.type) {
+    case 'user_input':
+      return q.questions.map((iq) => `- **${iq.text}**${iq.options ? ` (options: ${iq.options.join(', ')})` : ''}`).join('\n');
+    case 'command_approval':
+      return `- **Command approval**: \`${q.command}\``;
+    case 'file_approval':
+      return `- **File approval**: ${q.fileChanges.map((f) => f.path).join(', ')}`;
+    case 'elicitation':
+      return `- **Elicitation**: ${q.message}`;
+    case 'dynamic_tool':
+      return `- **Dynamic tool**: \`${q.toolName}\``;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// renderSummaryLog
+// ---------------------------------------------------------------------------
+
+/**
+ * Last 20 lines from task.output.
+ *
+ * Resource URI: `task:///{id}/log`
+ */
+export function renderSummaryLog(task: TaskState): string {
+  if (task.output.length === 0) {
+    return `# Log: ${task.id}\n\nNo output yet.`;
+  }
+
+  const tail = task.output.slice(-SUMMARY_LOG_LINES);
+  const header = `# Log: ${task.id} (last ${tail.length} of ${task.output.length} lines)`;
+  return [header, '', ...tail].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// renderVerboseLog
+// ---------------------------------------------------------------------------
+
+/**
+ * All lines from task.output (no truncation).
+ *
+ * Resource URI: `task:///{id}/log.verbose`
+ */
+export function renderVerboseLog(task: TaskState): string {
+  if (task.output.length === 0) {
+    return `# Verbose Log: ${task.id}\n\nNo output yet.`;
+  }
+
+  const header = `# Verbose Log: ${task.id} (${task.output.length} lines)`;
+  return [header, '', ...task.output].join('\n');
+}

package/src/mcp/sep1686-handlers.ts

@@ -0,0 +1,149 @@
+import type { TaskState, PendingQuestion } from '../task/task-state.js';
+import { TaskStatus } from '../task/task-state.js';
+import type { WireState } from '../task/wire-state-mapper.js';
+import { mapToWireState } from '../task/wire-state-mapper.js';
+
+// ---------------------------------------------------------------------------
+// Response interfaces — SEP-1686 wire-compatible shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * Response shape for `tasks/get` — a single task's status snapshot.
+ */
+export interface TasksGetResponse {
+  taskId: string;
+  status: WireState;
+  pollFrequency: number;
+  keepAlive?: number;
+  metadata?: { pendingQuestion?: PendingQuestion };
+  error?: string;
+}
+
+/**
+ * List item shape for `tasks/list` — lightweight summary per task.
+ */
+export interface TasksListItem {
+  taskId: string;
+  status: WireState;
+  pollFrequency: number;
+  createdAt: string;
+  lastUpdatedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Poll frequency computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the recommended poll interval in milliseconds based on task status.
+ *
+ * - WAITING_ANSWER → 2 000 ms  (client should check frequently for input-required)
+ * - PENDING, RUNNING → 5 000 ms
+ * - All others (WAITING, RATE_LIMITED, terminal) → 30 000 ms
+ */
+export function computePollFrequency(task: TaskState): number {
+  switch (task.status) {
+    case TaskStatus.WAITING_ANSWER:
+      return 2000;
+    case TaskStatus.PENDING:
+    case TaskStatus.RUNNING:
+      return 5000;
+    default:
+      return 30000;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// tasks/get response builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a SEP-1686 `tasks/get` response from internal TaskState.
+ *
+ * - Maps internal status to wire state via `mapToWireState`
+ * - Computes poll frequency via `computePollFrequency`
+ * - Includes `keepAlive` from task if present
+ * - Includes first pending question in metadata when status is
+ *   WAITING_ANSWER and the queue is non-empty
+ * - Includes error string if present
+ */
+export function buildTasksGetResponse(task: TaskState): TasksGetResponse {
+  const status = mapToWireState(task.status);
+  const pollFrequency = computePollFrequency(task);
+
+  const hasPendingQuestion =
+    task.status === TaskStatus.WAITING_ANSWER &&
+    task.pendingQuestions.length > 0;
+
+  const response: TasksGetResponse = {
+    taskId: task.id,
+    status,
+    pollFrequency,
+  };
+
+  if (task.keepAlive !== undefined) {
+    response.keepAlive = task.keepAlive;
+  }
+
+  if (hasPendingQuestion) {
+    const firstQuestion = task.pendingQuestions[0];
+    if (firstQuestion !== undefined) {
+      response.metadata = { pendingQuestion: firstQuestion };
+    }
+  }
+
+  if (task.error !== undefined) {
+    response.error = task.error;
+  }
+
+  return response;
+}
+
+// ---------------------------------------------------------------------------
+// tasks/list response builder
+// ---------------------------------------------------------------------------
+
+const PAGE_SIZE = 50;
+
+/**
+ * Builds a SEP-1686 `tasks/list` response.
+ *
+ * - Filters by wire status if `statusFilter` is provided
+ * - Sorts by `createdAt` descending (newest first)
+ * - Paginates with page size 50; cursor is a string-encoded start index
+ * - Returns `nextCursor` if more pages exist
+ */
+export function buildTasksListResponse(
+  tasks: TaskState[],
+  cursor?: string,
+  statusFilter?: WireState,
+): { tasks: TasksListItem[]; nextCursor?: string } {
+  // 1. Filter by wire status if requested
+  const filtered = statusFilter
+    ? tasks.filter(t => mapToWireState(t.status) === statusFilter)
+    : [...tasks];
+
+  // 2. Sort by createdAt descending
+  filtered.sort(
+    (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+  );
+
+  // 3. Paginate
+  const start = cursor ? parseInt(cursor, 10) : 0;
+  const page = filtered.slice(start, start + PAGE_SIZE);
+  const nextStart = start + PAGE_SIZE;
+  // 4. Map to list items
+  const items: TasksListItem[] = page.map(t => ({
+    taskId: t.id,
+    status: mapToWireState(t.status),
+    pollFrequency: computePollFrequency(t),
+    createdAt: t.createdAt,
+    lastUpdatedAt: t.updatedAt,
+  }));
+
+  const result: { tasks: TasksListItem[]; nextCursor?: string } = { tasks: items };
+  if (nextStart < filtered.length) {
+    result.nextCursor = String(nextStart);
+  }
+  return result;
+}