mcp-copilot-worker 1.0.1

package/src/mcp/task-markdown.ts

@@ -0,0 +1,81 @@
+import { TaskStatus, type TaskRecord } from '../types/task.js';
+
+function renderLogInstructions(task: TaskRecord): string[] {
+  if (!task.outputFilePath) {
+    return [];
+  }
+
+  return [
+    '## Read Logs',
+    '',
+    '```bash',
+    `cat -n ${task.outputFilePath}`,
+    '```',
+    '',
+    'Use `cat -n` to read with line numbers, then on subsequent reads use `tail -n +<N>` to skip already-read lines.',
+    '',
+  ];
+}
+
+export function renderTaskMarkdown(task: TaskRecord): string {
+  const lines: string[] = [
+    `# Task: ${task.id}`,
+    '',
+    '| Field | Value |',
+    '|---|---|',
+    `| **Status** | \`${task.status}\` |`,
+    `| **Model** | \`${task.model}\` |`,
+    `| **Agent Type** | \`${task.agentType}\` |`,
+    `| **Started** | ${task.startTime} |`,
+    '',
+    ...renderLogInstructions(task),
+  ];
+
+  if (
+    task.status === TaskStatus.RUNNING ||
+    task.status === TaskStatus.PENDING ||
+    task.status === TaskStatus.WAITING
+  ) {
+    lines.push('## What to do next', '');
+    lines.push('The agent is still working. If you need to wait, run `sleep 30` and then read this resource again.');
+    if (task.outputFilePath) {
+      lines.push(`For a quick progress check without reading the full resource, run \`wc -l ${task.outputFilePath}\` — a growing line count means the agent is still working.`);
+    }
+    lines.push('If the agent is still running after your first check, wait longer before checking again: `sleep 60`, then `sleep 90`, `sleep 120`, `sleep 150`, up to `sleep 180` max.');
+    lines.push('');
+  }
+
+  if (task.pendingQuestion) {
+    lines.push('## ACTION REQUIRED', '');
+    lines.push(`**Question:** ${task.pendingQuestion.question}`);
+    lines.push('');
+  }
+
+  if (task.output.length > 0) {
+    lines.push('## Recent Output', '', '```');
+    lines.push(...task.output.slice(-50));
+    lines.push('```');
+  }
+
+  return lines.join('\n');
+}
+
+export function renderTaskListMarkdown(tasks: TaskRecord[]): string {
+  const lines = [
+    `# Tasks (${tasks.length} total)`,
+    '',
+    '| ID | Status | Prompt |',
+    '|---|---|---|',
+    ...tasks.map((task) => `| ${task.id} | ${task.status} | ${task.prompt.slice(0, 40)} |`),
+  ];
+
+  const pending = tasks.filter((task) => task.status === TaskStatus.WAITING_ANSWER);
+  if (pending.length > 0) {
+    lines.push('', `## Pending Questions (${pending.length})`, '');
+    for (const task of pending) {
+      lines.push(`### ${task.id}`, '', `**Q:** ${task.pendingQuestion?.question ?? 'Pending answer required'}`, '');
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/mcp/tool-banners.ts

@@ -0,0 +1,32 @@
+import type { QuestionRegistry } from '../services/question-registry.js';
+import type { TaskManager } from '../services/task-manager.js';
+import { TaskStatus } from '../types/task.js';
+
+export function buildMessageBanner(taskManager: TaskManager): string {
+  const tasks = taskManager.getAllTasks();
+  if (tasks.length === 0) {
+    return '';
+  }
+
+  const running = tasks.filter((task) => task.status === TaskStatus.RUNNING).length;
+  const waitingAnswer = tasks.filter((task) => task.status === TaskStatus.WAITING_ANSWER).length;
+  const recent = tasks.slice(-3).map((task) => `- ${task.id} [${task.status}]`).join('\n');
+
+  return ['---', `AGENT STATUS: ${running} running | ${waitingAnswer} needs answer`, recent, 'Read task:///all for full details.']
+    .filter(Boolean)
+    .join('\n');
+}
+
+export function buildAnswerBanner(questionRegistry: QuestionRegistry): string {
+  const pending = questionRegistry.getAllPendingQuestions();
+  if (pending.size === 0) {
+    return '';
+  }
+
+  return [
+    '---',
+    `ACTION REQUIRED — ${pending.size} task${pending.size > 1 ? 's' : ''} waiting for your answer:`,
+    ...[...pending.entries()].map(([taskId, question]) => `- ${taskId}: "${question.question}"`),
+    'Use answer-agent { "task_id": "<id>", "answer": "<choice>" }',
+  ].join('\n');
+}

package/src/mcp/tool-definitions.ts

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+
+const contextFileSchema = z.object({
+  path: z.string().min(1),
+  description: z.string().optional(),
+});
+
+const spawnAgentSchema = z.object({
+  prompt: z.string().min(1).max(100_000),
+  agent_type: z.enum(['coder', 'planner', 'researcher', 'tester', 'general']),
+  context_files: z.array(contextFileSchema).max(20).optional(),
+  model: z.string().optional(),
+  cwd: z.string().optional(),
+  timeout: z.number().int().positive().max(3_600_000).optional(),
+  depends_on: z.array(z.string().min(1)).max(50).optional(),
+  labels: z.array(z.string().min(1).max(50)).max(10).optional(),
+  isolation_mode: z.enum(['shared', 'isolated']).optional(),
+});
+
+const messageAgentSchema = z.object({
+  task_id: z.string().min(1),
+  message: z.string().optional(),
+  timeout: z.number().int().positive().max(3_600_000).optional(),
+  cwd: z.string().optional(),
+});
+
+const cancelAgentSchema = z.object({
+  task_id: z.union([z.string().min(1), z.array(z.string().min(1)).min(1).max(50)]),
+  clear: z.boolean().optional(),
+  confirm: z.boolean().optional(),
+});
+
+const answerAgentSchema = z.object({
+  task_id: z.string().min(1),
+  answer: z.string().min(1).optional(),
+  answers: z.record(z.string(), z.string().min(1)).optional(),
+});
+
+export type SpawnAgentInput = z.infer<typeof spawnAgentSchema>;
+export type MessageAgentInput = z.infer<typeof messageAgentSchema>;
+export type CancelAgentInput = z.infer<typeof cancelAgentSchema>;
+export type AnswerAgentInput = z.infer<typeof answerAgentSchema>;
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  validate: (input: unknown) => unknown;
+}
+
+export interface CreateToolDefinitionsInput {
+  messageBanner: string;
+  answerBanner: string;
+  modelSuggestions?: string[] | undefined;
+  modelDescription?: string | undefined;
+}
+
+export function createToolDefinitions(input: CreateToolDefinitionsInput): ToolDefinition[] {
+  const modelProperty = {
+    type: 'string',
+    ...(input.modelSuggestions && input.modelSuggestions.length > 0
+      ? { enum: input.modelSuggestions }
+      : {}),
+    ...(input.modelDescription
+      ? { description: input.modelDescription }
+      : {}),
+  };
+
+  return [
+    {
+      name: 'spawn-agent',
+      description: [
+        'Launch a Copilot-backed task in the background.',
+        'Use `task:///all` to monitor status and `task:///{id}` for live detail.',
+      ].join(' '),
+      inputSchema: {
+        type: 'object',
+        properties: {
+          prompt: { type: 'string', minLength: 1, maxLength: 100000 },
+          agent_type: { type: 'string', enum: ['coder', 'planner', 'researcher', 'tester', 'general'] },
+          context_files: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                path: { type: 'string', minLength: 1 },
+                description: { type: 'string' },
+              },
+              required: ['path'],
+            },
+            maxItems: 20,
+          },
+          model: modelProperty,
+          cwd: { type: 'string' },
+          timeout: { type: 'integer', minimum: 1, maximum: 3600000 },
+          depends_on: { type: 'array', items: { type: 'string', minLength: 1 }, maxItems: 50 },
+          labels: { type: 'array', items: { type: 'string', minLength: 1, maxLength: 50 }, maxItems: 10 },
+          isolation_mode: { type: 'string', enum: ['shared', 'isolated'] },
+        },
+        required: ['prompt', 'agent_type'],
+      },
+      validate: (payload) => spawnAgentSchema.parse(payload),
+    },
+    {
+      name: 'message-agent',
+      description: [
+        'Resume a terminal task with a follow-up message.',
+        input.messageBanner,
+      ].filter(Boolean).join('\n\n'),
+      inputSchema: {
+        type: 'object',
+        properties: {
+          task_id: { type: 'string', minLength: 1 },
+          message: { type: 'string' },
+          timeout: { type: 'integer', minimum: 1, maximum: 3600000 },
+          cwd: { type: 'string' },
+        },
+        required: ['task_id'],
+      },
+      validate: (payload) => messageAgentSchema.parse(payload),
+    },
+    {
+      name: 'cancel-agent',
+      description: 'Cancel one task, many tasks, or clear all tracked tasks.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          task_id: {
+            type: ['string', 'array'],
+            items: { type: 'string', minLength: 1 },
+            minItems: 1,
+            maxItems: 50,
+          },
+          clear: { type: 'boolean' },
+          confirm: { type: 'boolean' },
+        },
+        required: ['task_id'],
+      },
+      validate: (payload) => cancelAgentSchema.parse(payload),
+    },
+    {
+      name: 'answer-agent',
+      description: [
+        'Answer a pending agent question and resume execution.',
+        input.answerBanner,
+      ].filter(Boolean).join('\n\n'),
+      inputSchema: {
+        type: 'object',
+        properties: {
+          task_id: { type: 'string', minLength: 1 },
+          answer: { type: 'string', minLength: 1 },
+          answers: { type: 'object', additionalProperties: { type: 'string', minLength: 1 } },
+        },
+        required: ['task_id'],
+      },
+      validate: (payload) => answerAgentSchema.parse(payload),
+    },
+  ];
+}

package/src/services/copilot-runtime.ts

@@ -0,0 +1,305 @@
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+
+import {
+  CopilotClient,
+  approveAll,
+  type CopilotClientOptions,
+  type ModelInfo,
+  type CopilotSession,
+} from '@github/copilot-sdk';
+
+import { DEFAULT_MODEL, DEFAULT_TIMEOUT_MS } from '../config/defaults.js';
+import { buildAgentPrompt } from '../templates/agent-prompt.js';
+import type { TaskRecord } from '../types/task.js';
+import { TaskStatus } from '../types/task.js';
+import { startFleetModeIfEnabled } from './fleet-mode.js';
+import {
+  buildModelCatalog,
+  describeAllowedModels,
+  resolveModelAlias,
+  type ModelCatalogInput,
+} from './model-catalog.js';
+import type { CopilotProfile } from './profile-manager.js';
+import type { ProfileManager } from './profile-manager.js';
+import type { QuestionRegistry } from './question-registry.js';
+import type { TaskManager } from './task-manager.js';
+
+export interface BuildCopilotClientOptionsInput {
+  cwd: string;
+  profile: CopilotProfile;
+  cliPath?: string | undefined;
+}
+
+function canExecute(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveCopilotCliPath(explicitPath?: string): string {
+  if (explicitPath && canExecute(explicitPath)) {
+    return explicitPath;
+  }
+
+  const configuredPath = process.env.COPILOT_CLI_PATH;
+  if (configuredPath && canExecute(configuredPath)) {
+    return configuredPath;
+  }
+
+  for (const segment of (process.env.PATH ?? '').split(delimiter)) {
+    if (!segment) {
+      continue;
+    }
+
+    const candidate = join(segment, 'copilot');
+    if (canExecute(candidate)) {
+      return candidate;
+    }
+  }
+
+  return explicitPath ?? configuredPath ?? 'copilot';
+}
+
+export function buildCopilotClientOptions(
+  input: BuildCopilotClientOptionsInput,
+): CopilotClientOptions {
+  return {
+    cliPath: resolveCopilotCliPath(input.cliPath),
+    cliArgs: ['--config-dir', input.profile.configDir],
+    cwd: input.cwd,
+    useLoggedInUser: true,
+    useStdio: false,
+    autoStart: true,
+    autoRestart: false,
+    logLevel: 'error',
+  };
+}
+
+function isRateLimitError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes('rate limit') ||
+    normalized.includes('too many requests') ||
+    normalized.includes('429') ||
+    normalized.includes('quota')
+  );
+}
+
+export class CopilotRuntime {
+  private readonly clients = new Map<string, CopilotClient>();
+  private readonly taskManager: TaskManager;
+  private readonly profileManager: ProfileManager;
+  private readonly questionRegistry: QuestionRegistry;
+
+  constructor(input: {
+    taskManager: TaskManager;
+    profileManager: ProfileManager;
+    questionRegistry: QuestionRegistry;
+  }) {
+    this.taskManager = input.taskManager;
+    this.profileManager = input.profileManager;
+    this.questionRegistry = input.questionRegistry;
+  }
+
+  async runTask(task: TaskRecord): Promise<void> {
+    try {
+      const profile = this.resolveProfile(task);
+      const client = await this.getClient(task.baseCwd ?? task.cwd, profile);
+      const prompt = await buildAgentPrompt({
+        agentType: task.agentType,
+        prompt: task.prompt,
+        contextFiles: task.contextFiles,
+      });
+
+      const session = task.sessionId
+        ? await client.resumeSession(task.sessionId, {
+            onPermissionRequest: approveAll,
+            onUserInputRequest: (request, invocation) =>
+              this.questionRegistry.register({
+                taskId: task.id,
+                sessionId: invocation.sessionId,
+                question: request.question,
+                choices: request.choices,
+                allowFreeform: request.allowFreeform,
+              }),
+            streaming: true,
+          })
+        : await client.createSession({
+            model: task.model,
+            onPermissionRequest: approveAll,
+            onUserInputRequest: (request, invocation) =>
+              this.questionRegistry.register({
+                taskId: task.id,
+                sessionId: invocation.sessionId,
+                question: request.question,
+                choices: request.choices,
+                allowFreeform: request.allowFreeform,
+              }),
+            streaming: true,
+          });
+
+      await this.taskManager.registerExecution(task.id, {
+        abort: async () => {
+          await session.abort().catch(() => {});
+        },
+        cleanup: async () => {
+          await session.disconnect().catch(() => {});
+        },
+      });
+
+      await this.taskManager.updateTask(task.id, {
+        status: TaskStatus.RUNNING,
+        sessionId: session.sessionId,
+        profileId: profile.id,
+        profileConfigDir: profile.configDir,
+      });
+
+      this.bindSessionEvents(task.id, session);
+
+      await this.taskManager.appendOutput(task.id, `[session] profile: ${profile.id} (${profile.configDir})`);
+      const fleetStarted = await startFleetModeIfEnabled(session, task.prompt);
+      if (fleetStarted) {
+        await this.taskManager.appendOutput(task.id, '[fleet] started');
+      }
+      await session.sendAndWait(
+        { prompt },
+        task.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      );
+      await this.taskManager.updateTask(task.id, {
+        status: TaskStatus.COMPLETED,
+        endTime: new Date().toISOString(),
+      });
+    } catch (error) {
+      if (isRateLimitError(error)) {
+        this.profileManager.markFailure('rate_limit');
+        await this.taskManager.updateTask(task.id, {
+          status: TaskStatus.RATE_LIMITED,
+          error: error instanceof Error ? error.message : String(error),
+          endTime: new Date().toISOString(),
+        });
+      } else {
+        await this.taskManager.updateTask(task.id, {
+          status: TaskStatus.FAILED,
+          error: error instanceof Error ? error.message : String(error),
+          endTime: new Date().toISOString(),
+        });
+      }
+    } finally {
+      await this.taskManager.clearExecution(task.id);
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    await Promise.all(
+      [...this.clients.values()].map(async (client) => {
+        await client.stop().catch(async () => {
+          await client.forceStop().catch(() => {});
+        });
+      }),
+    );
+    this.clients.clear();
+  }
+
+  async resolveRequestedModel(cwd: string, requestedModel?: string): Promise<string> {
+    const profile = this.profileManager.getCurrentProfile();
+    const catalog = await this.loadModelCatalog(cwd, profile);
+    const rawModel = requestedModel ?? DEFAULT_MODEL;
+    const resolved = resolveModelAlias(rawModel, catalog);
+    if (!resolved) {
+      throw new Error(
+        `Unsupported model "${rawModel}" for profile ${profile.id} (${profile.configDir}). ${describeAllowedModels(catalog)}`,
+      );
+    }
+
+    return resolved;
+  }
+
+  async describeCurrentProfileModels(cwd: string): Promise<{
+    latestModelIds?: string[] | undefined;
+    description?: string | undefined;
+  }> {
+    try {
+      const profile = this.profileManager.getCurrentProfile();
+      const catalog = await this.loadModelCatalog(cwd, profile);
+      return {
+        latestModelIds: catalog.latestModelIds.length > 0 ? catalog.latestModelIds : undefined,
+        description: describeAllowedModels(catalog),
+      };
+    } catch (error) {
+      return {
+        description: `Copilot model id. Model inventory unavailable: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  private bindSessionEvents(taskId: string, session: CopilotSession): void {
+    session.on('assistant.message', (event) => {
+      void this.taskManager.appendOutput(taskId, event.data.content);
+    });
+    session.on('tool.execution_start', (event) => {
+      void this.taskManager.appendOutput(taskId, `[tool] start: ${event.data.toolName}`);
+    });
+    session.on('tool.execution_complete', (event) => {
+      const label = 'toolName' in event.data ? event.data.toolName : event.data.toolCallId;
+      void this.taskManager.appendOutput(taskId, `[tool] complete: ${label} success=${String(event.data.success)}`);
+    });
+    session.on('session.error', (event) => {
+      void this.taskManager.appendOutput(taskId, `[error] ${event.data.message}`);
+    });
+  }
+
+  private async getClient(cwd: string, profile: CopilotProfile): Promise<CopilotClient> {
+    const key = `${cwd}:${profile.configDir}`;
+    const existing = this.clients.get(key);
+    if (existing) {
+      return existing;
+    }
+
+    const client = new CopilotClient(buildCopilotClientOptions({ cwd, profile }));
+    await client.start();
+    const auth = await client.getAuthStatus();
+    if (!auth.isAuthenticated) {
+      throw new Error(
+        `Copilot profile "${profile.configDir}" is not authenticated. Run \`copilot login --config-dir ${profile.configDir}\`.`,
+      );
+    }
+
+    this.clients.set(key, client);
+    return client;
+  }
+
+  private resolveProfile(task: TaskRecord): CopilotProfile {
+    if (task.profileConfigDir && task.profileId) {
+      const match = this.profileManager.getProfiles().find((profile) => profile.id === task.profileId);
+      if (match) {
+        return match;
+      }
+      return {
+        id: task.profileId,
+        configDir: task.profileConfigDir,
+        failureCount: 0,
+      };
+    }
+
+    return this.profileManager.getCurrentProfile();
+  }
+
+  private async loadModelCatalog(cwd: string, profile: CopilotProfile) {
+    const client = await this.getClient(cwd, profile);
+    const models = await client.listModels();
+    return buildModelCatalog(models.map((model) => this.toModelCatalogInput(model)));
+  }
+
+  private toModelCatalogInput(model: ModelInfo): ModelCatalogInput {
+    return {
+      id: model.id,
+      name: model.name,
+      policyState: model.policy?.state,
+    };
+  }
+}

package/src/services/fleet-mode.ts

@@ -0,0 +1,39 @@
+export const COPILOT_ENABLE_FLEET_ENV = 'COPILOT_ENABLE_FLEET';
+
+const TRUTHY_VALUES = new Set(['1', 'true', 'yes', 'on']);
+
+export interface FleetRpcSession {
+  rpc: {
+    fleet: {
+      start: (input: { prompt?: string }) => Promise<{ started: boolean }>;
+    };
+  };
+}
+
+export function isFleetModeEnabled(value = process.env[COPILOT_ENABLE_FLEET_ENV]): boolean {
+  return value !== undefined && TRUTHY_VALUES.has(value.trim().toLowerCase());
+}
+
+export function buildFleetPrompt(taskPrompt: string): string {
+  return [
+    'You are one worker in a Copilot fleet assisting the primary agent.',
+    'Work in parallel, focus on independently useful evidence, and surface concrete edits or commands the primary agent can apply immediately.',
+    'Do not take ownership of the final deliverable unless the primary agent explicitly assigns a bounded subtask that requires it.',
+    'Do not write the user-facing final answer or directly create the requested final artifact by default. Prefer scouting, verification, and support work that unblocks the primary agent.',
+    'Do not ask the user questions. Do not restate the entire task. Stay concise and execution-focused.',
+    'Primary task:',
+    taskPrompt.trim(),
+  ].join('\n\n');
+}
+
+export async function startFleetModeIfEnabled(session: FleetRpcSession, taskPrompt: string): Promise<boolean> {
+  if (!isFleetModeEnabled()) {
+    return false;
+  }
+
+  const result = await session.rpc.fleet.start({
+    prompt: buildFleetPrompt(taskPrompt),
+  });
+
+  return result.started;
+}