mcp-copilot-cli 1.0.0

package/src/services/output-log.ts

@@ -0,0 +1,68 @@
+import { mkdir, open, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const OUTPUT_DIR_NAME = '.super-agents';
+
+function sanitizeTaskId(taskId: string): string {
+  return taskId.replace(/[\/\\:\x00]/g, '_');
+}
+
+export function getOutputDir(cwd: string): string {
+  return join(cwd, OUTPUT_DIR_NAME);
+}
+
+export function getOutputPath(cwd: string, taskId: string): string {
+  return join(getOutputDir(cwd), `${sanitizeTaskId(taskId)}.output`);
+}
+
+function timestamp(): string {
+  return new Date().toISOString();
+}
+
+export class OutputLogService {
+  async create(cwd: string, taskId: string): Promise<string> {
+    await mkdir(getOutputDir(cwd), { recursive: true });
+
+    const outputPath = getOutputPath(cwd, taskId);
+    const handle = await open(outputPath, 'a+');
+    try {
+      const existing = await readFile(outputPath, 'utf8').catch(() => '');
+      if (!existing) {
+        await handle.writeFile(
+          `# Task: ${taskId}\n# Started: ${timestamp()}\n# Working directory: ${cwd}\n${'─'.repeat(60)}\n`,
+          'utf8',
+        );
+      }
+    } finally {
+      await handle.close();
+    }
+
+    return outputPath;
+  }
+
+  async append(cwd: string, taskId: string, line: string): Promise<void> {
+    const outputPath = await this.create(cwd, taskId);
+    const handle = await open(outputPath, 'a');
+    try {
+      await handle.writeFile(`[${timestamp()}] ${line}\n`, 'utf8');
+    } finally {
+      await handle.close();
+    }
+  }
+
+  async finalize(cwd: string, taskId: string, status: string, error?: string): Promise<void> {
+    const outputPath = await this.create(cwd, taskId);
+    const handle = await open(outputPath, 'a');
+    try {
+      const footer = [
+        `${'─'.repeat(60)}`,
+        `# Completed: ${timestamp()}`,
+        `# Status: ${status}`,
+        error ? `# Error: ${error}` : null,
+      ].filter(Boolean).join('\n');
+      await handle.writeFile(`${footer}\n`, 'utf8');
+    } finally {
+      await handle.close();
+    }
+  }
+}

package/src/services/profile-manager.ts

@@ -0,0 +1,165 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import type { PersistedProfileState } from '../types/task.js';
+
+export interface CopilotProfile {
+  id: string;
+  configDir: string;
+  cooldownUntil?: number | undefined;
+  failureCount: number;
+  lastFailureReason?: string | undefined;
+}
+
+export interface ProfileManagerOptions {
+  profileDirs?: string[] | undefined;
+  cooldownMs?: number | undefined;
+  now?: (() => number) | undefined;
+  persistedProfiles?: PersistedProfileState[] | undefined;
+}
+
+export interface ProfileRotationResult {
+  success: boolean;
+  allExhausted?: boolean | undefined;
+  currentProfile?: CopilotProfile | undefined;
+}
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+
+function defaultProfileDir(): string {
+  return join(homedir(), '.copilot');
+}
+
+function dedupeProfileDirs(profileDirs: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const dir of profileDirs) {
+    const normalized = dir.trim();
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    result.push(normalized);
+  }
+
+  return result.length > 0 ? result : [defaultProfileDir()];
+}
+
+export class ProfileManager {
+  private readonly cooldownMs: number;
+  private readonly now: () => number;
+  private readonly profiles: CopilotProfile[];
+  private currentIndex = 0;
+
+  constructor(options: ProfileManagerOptions = {}) {
+    this.cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    this.now = options.now ?? Date.now;
+
+    const configuredDirs = dedupeProfileDirs(options.profileDirs ?? [defaultProfileDir()]);
+    const persistedByDir = new Map(
+      (options.persistedProfiles ?? []).map((profile) => [profile.configDir, profile]),
+    );
+
+    this.profiles = configuredDirs.map((configDir, index) => {
+      const persisted = persistedByDir.get(configDir);
+      return {
+        id: persisted?.id ?? `profile-${index + 1}`,
+        configDir,
+        cooldownUntil: persisted?.cooldownUntil,
+        failureCount: persisted?.failureCount ?? 0,
+        lastFailureReason: persisted?.lastFailureReason,
+      };
+    });
+
+    this.currentIndex = this.findFirstAvailableIndex();
+  }
+
+  static fromEnvironment(now?: () => number): ProfileManager {
+    const raw = process.env.COPILOT_CONFIG_DIRS;
+    const dirs = raw
+      ? raw.split(',').map((entry) => entry.trim()).filter(Boolean)
+      : [defaultProfileDir()];
+
+    return new ProfileManager({ profileDirs: dirs, now });
+  }
+
+  hydrate(persistedProfiles: PersistedProfileState[]): void {
+    const persistedByDir = new Map(
+      persistedProfiles.map((profile) => [profile.configDir, profile]),
+    );
+
+    for (const profile of this.profiles) {
+      const persisted = persistedByDir.get(profile.configDir);
+      if (!persisted) {
+        continue;
+      }
+
+      profile.failureCount = persisted.failureCount;
+      profile.cooldownUntil = persisted.cooldownUntil;
+      profile.lastFailureReason = persisted.lastFailureReason;
+    }
+
+    this.resetExpiredCooldowns();
+  }
+
+  getProfiles(): CopilotProfile[] {
+    return this.profiles.map((profile) => ({ ...profile }));
+  }
+
+  getCurrentProfile(): CopilotProfile {
+    this.resetExpiredCooldowns();
+    return { ...this.profiles[this.currentIndex]! };
+  }
+
+  markFailure(reason: string): ProfileRotationResult {
+    const current = this.profiles[this.currentIndex];
+    if (!current) {
+      return { success: false, allExhausted: true };
+    }
+
+    current.failureCount += 1;
+    current.lastFailureReason = reason;
+    current.cooldownUntil = this.now() + this.cooldownMs;
+
+    const nextIndex = this.findFirstAvailableIndex();
+    if (nextIndex === -1) {
+      return { success: false, allExhausted: true };
+    }
+
+    this.currentIndex = nextIndex;
+    return {
+      success: true,
+      currentProfile: this.getCurrentProfile(),
+    };
+  }
+
+  resetExpiredCooldowns(): void {
+    const now = this.now();
+    for (const profile of this.profiles) {
+      if (profile.cooldownUntil !== undefined && profile.cooldownUntil <= now) {
+        profile.cooldownUntil = undefined;
+      }
+    }
+
+    const nextIndex = this.findFirstAvailableIndex();
+    if (nextIndex !== -1) {
+      this.currentIndex = nextIndex;
+    }
+  }
+
+  toPersistedState(): PersistedProfileState[] {
+    return this.profiles.map((profile) => ({
+      id: profile.id,
+      configDir: profile.configDir,
+      cooldownUntil: profile.cooldownUntil,
+      failureCount: profile.failureCount,
+      lastFailureReason: profile.lastFailureReason,
+    }));
+  }
+
+  private findFirstAvailableIndex(): number {
+    const now = this.now();
+    return this.profiles.findIndex((profile) => profile.cooldownUntil === undefined || profile.cooldownUntil <= now);
+  }
+}

package/src/services/question-registry.ts

@@ -0,0 +1,169 @@
+import type { PendingQuestion } from '../types/task.js';
+import { TaskStatus } from '../types/task.js';
+import type { TaskManager } from './task-manager.js';
+
+interface RegisterQuestionInput {
+  taskId: string;
+  sessionId: string;
+  question: string;
+  choices?: string[] | undefined;
+  allowFreeform?: boolean | undefined;
+}
+
+interface PendingBinding {
+  question: PendingQuestion;
+  resolve: (value: { answer: string; wasFreeform: boolean }) => void;
+  reject: (reason?: unknown) => void;
+  timeout: NodeJS.Timeout;
+}
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+export class QuestionRegistry {
+  private readonly taskManager: TaskManager;
+  private readonly timeoutMs: number;
+  private readonly pending = new Map<string, PendingBinding>();
+
+  constructor(taskManager: TaskManager, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    this.taskManager = taskManager;
+    this.timeoutMs = timeoutMs;
+  }
+
+  register(input: RegisterQuestionInput): Promise<{ answer: string; wasFreeform: boolean }> {
+    this.clear(input.taskId, 'replaced by newer question');
+
+    return new Promise((resolve, reject) => {
+      const question: PendingQuestion = {
+        question: input.question,
+        choices: input.choices,
+        allowFreeform: input.allowFreeform ?? true,
+        askedAt: new Date().toISOString(),
+        sessionId: input.sessionId,
+      };
+
+      const timeout = setTimeout(() => {
+        void this.taskManager.updateTask(input.taskId, {
+          status: TaskStatus.FAILED,
+          error: 'Task failed: user question timed out after 30 minutes',
+          pendingQuestion: undefined,
+          endTime: new Date().toISOString(),
+        });
+        reject(new Error('Question timed out'));
+        this.pending.delete(input.taskId);
+      }, this.timeoutMs);
+      timeout.unref();
+
+      this.pending.set(input.taskId, { question, resolve, reject, timeout });
+      void this.taskManager.updateTask(input.taskId, {
+        status: TaskStatus.WAITING_ANSWER,
+        pendingQuestion: question,
+      });
+      void this.taskManager.appendOutput(
+        input.taskId,
+        `[question] ${input.question}`,
+      );
+    });
+  }
+
+  submitAnswer(
+    taskId: string,
+    rawAnswer: string,
+  ): { success: boolean; resolvedAnswer?: string | undefined; error?: string | undefined } {
+    const binding = this.pending.get(taskId);
+    if (!binding) {
+      return { success: false, error: 'No pending question for this task' };
+    }
+
+    const parsed = this.parseAnswer(rawAnswer, binding.question);
+    if (!parsed.success) {
+      return parsed;
+    }
+
+    clearTimeout(binding.timeout);
+    binding.resolve({ answer: parsed.resolvedAnswer!, wasFreeform: parsed.wasFreeform! });
+    this.pending.delete(taskId);
+    void this.taskManager.updateTask(taskId, {
+      status: TaskStatus.RUNNING,
+      pendingQuestion: undefined,
+    });
+    void this.taskManager.appendOutput(taskId, `[question] Answer submitted: ${parsed.resolvedAnswer}`);
+
+    return parsed;
+  }
+
+  hasPendingQuestion(taskId: string): boolean {
+    return this.pending.has(taskId);
+  }
+
+  getAllPendingQuestions(): Map<string, PendingQuestion> {
+    return new Map(
+      [...this.pending.entries()].map(([taskId, binding]) => [taskId, binding.question]),
+    );
+  }
+
+  clear(taskId: string, reason: string): void {
+    const binding = this.pending.get(taskId);
+    if (!binding) {
+      return;
+    }
+
+    clearTimeout(binding.timeout);
+    binding.reject(new Error(reason));
+    this.pending.delete(taskId);
+    void this.taskManager.updateTask(taskId, { pendingQuestion: undefined });
+  }
+
+  private parseAnswer(
+    rawAnswer: string,
+    question: PendingQuestion,
+  ): {
+    success: boolean;
+    resolvedAnswer?: string | undefined;
+    wasFreeform?: boolean | undefined;
+    error?: string | undefined;
+  } {
+    const answer = rawAnswer.trim();
+    if (!answer) {
+      return { success: false, error: 'Answer cannot be empty' };
+    }
+
+    if (question.choices && /^\d+$/.test(answer)) {
+      const index = Number.parseInt(answer, 10) - 1;
+      if (index < 0 || index >= question.choices.length) {
+        return { success: false, error: `Invalid choice. Please enter 1-${question.choices.length}.` };
+      }
+
+      return {
+        success: true,
+        resolvedAnswer: question.choices[index]!,
+        wasFreeform: false,
+      };
+    }
+
+    if (answer.toUpperCase().startsWith('OTHER:') && question.allowFreeform) {
+      return {
+        success: true,
+        resolvedAnswer: answer.slice('OTHER:'.length).trim(),
+        wasFreeform: true,
+      };
+    }
+
+    if (question.choices?.includes(answer)) {
+      return {
+        success: true,
+        resolvedAnswer: answer,
+        wasFreeform: false,
+      };
+    }
+
+    if (question.allowFreeform) {
+      return {
+        success: true,
+        resolvedAnswer: answer,
+        wasFreeform: true,
+      };
+    }
+
+    return { success: false, error: 'Invalid answer' };
+  }
+}

package/src/services/spawn-validation.ts

@@ -0,0 +1,75 @@
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import type { ContextFile } from '../types/task.js';
+import type { SpawnAgentInput } from '../mcp/tool-definitions.js';
+
+const MAX_CONTEXT_FILES = 20;
+const MAX_CONTEXT_FILE_BYTES = 200 * 1024;
+const MAX_TOTAL_CONTEXT_BYTES = 500 * 1024;
+
+const MIN_PROMPT_LENGTH: Record<SpawnAgentInput['agent_type'], number> = {
+  coder: 1000,
+  planner: 300,
+  researcher: 200,
+  tester: 300,
+  general: 200,
+};
+
+export interface ValidateSpawnAgentInputArgs {
+  input: SpawnAgentInput;
+  baseCwd: string;
+}
+
+export async function validateSpawnAgentInput(
+  args: ValidateSpawnAgentInputArgs,
+): Promise<{ contextFiles: ContextFile[] | undefined }> {
+  const minimum = MIN_PROMPT_LENGTH[args.input.agent_type];
+  if (args.input.prompt.trim().length < minimum) {
+    throw new Error(
+      `${args.input.agent_type} tasks require a prompt of at least ${minimum} characters`,
+    );
+  }
+
+  const inputFiles = args.input.context_files;
+  if (args.input.agent_type === 'coder' && (inputFiles?.length ?? 0) < 1) {
+    throw new Error('coder tasks require at least one context_files entry');
+  }
+
+  if (!inputFiles || inputFiles.length === 0) {
+    return { contextFiles: undefined };
+  }
+
+  if (inputFiles.length > MAX_CONTEXT_FILES) {
+    throw new Error(`context_files may contain at most ${MAX_CONTEXT_FILES} files`);
+  }
+
+  const normalized: ContextFile[] = [];
+  let totalBytes = 0;
+
+  for (const file of inputFiles) {
+    const absolutePath = resolve(args.baseCwd, file.path);
+    const info = await stat(absolutePath).catch(() => null);
+    if (!info) {
+      throw new Error(`Context file not found: ${file.path}`);
+    }
+    if (!info.isFile()) {
+      throw new Error(`Context file is not a regular file: ${file.path}`);
+    }
+    if (info.size > MAX_CONTEXT_FILE_BYTES) {
+      throw new Error(`Context file exceeds 200KB: ${file.path}`);
+    }
+
+    totalBytes += info.size;
+    if (totalBytes > MAX_TOTAL_CONTEXT_BYTES) {
+      throw new Error('Combined context_files size exceeds 500KB');
+    }
+
+    normalized.push({
+      path: absolutePath,
+      description: file.description,
+    });
+  }
+
+  return { contextFiles: normalized };
+}

package/src/services/task-manager.ts

@@ -0,0 +1,144 @@
+import type { PersistedProfileState } from '../types/task.js';
+import type { OutputLogService } from './output-log.js';
+import { TaskStore } from './task-store.js';
+import {
+  loadWorkspaceState,
+  saveWorkspaceState,
+  type LoadedWorkspaceState,
+} from './task-persistence.js';
+import type { CreateTaskInput, TaskRecord } from '../types/task.js';
+import { TaskStatus, isTerminalStatus } from '../types/task.js';
+
+export interface TaskManagerOptions {
+  storageRoot?: string | undefined;
+  outputLog: OutputLogService;
+  getProfiles?: (() => PersistedProfileState[]) | undefined;
+}
+
+type ExecutionBinding = {
+  abort?: () => Promise<void>;
+  cleanup?: () => Promise<void>;
+};
+
+export class TaskManager {
+  private readonly store = new TaskStore();
+  private readonly storageRoot: string | undefined;
+  private readonly outputLog: OutputLogService;
+  private readonly getProfiles: (() => PersistedProfileState[]) | undefined;
+  private readonly executionBindings = new Map<string, ExecutionBinding>();
+
+  constructor(options: TaskManagerOptions) {
+    this.storageRoot = options.storageRoot;
+    this.outputLog = options.outputLog;
+    this.getProfiles = options.getProfiles;
+  }
+
+  async load(cwd: string): Promise<LoadedWorkspaceState> {
+    const restored = await loadWorkspaceState({ cwd, storageRoot: this.storageRoot });
+    for (const task of restored.tasks) {
+      this.store.importTask(task);
+    }
+    return restored;
+  }
+
+  getTask(taskId: string): TaskRecord | undefined {
+    return this.store.getTask(taskId);
+  }
+
+  getAllTasks(): TaskRecord[] {
+    return this.store.getAllTasks();
+  }
+
+  async createTask(input: CreateTaskInput): Promise<TaskRecord> {
+    const task = this.store.createTask(input);
+    task.outputFilePath = await this.outputLog.create(task.cwd, task.id);
+    await this.persist(task.cwd);
+    return task;
+  }
+
+  async updateTask(taskId: string, updates: Partial<TaskRecord>): Promise<TaskRecord | undefined> {
+    const task = this.store.updateTask(taskId, updates);
+    if (!task) {
+      return undefined;
+    }
+
+    if (task.outputFilePath && updates.status && isTerminalStatus(updates.status)) {
+      await this.outputLog.finalize(task.cwd, task.id, task.status, task.error);
+    }
+
+    await this.persist(task.cwd);
+    return task;
+  }
+
+  async appendOutput(taskId: string, line: string): Promise<void> {
+    const task = this.store.getTask(taskId);
+    if (!task) {
+      return;
+    }
+
+    task.output.push(line);
+    task.updatedAt = new Date().toISOString();
+    await this.outputLog.append(task.cwd, task.id, line);
+    await this.persist(task.cwd);
+  }
+
+  async releaseReadyTasks(): Promise<TaskRecord[]> {
+    const tasks = this.store.releaseReadyTasks();
+    if (tasks.length > 0) {
+      await this.persist(tasks[0]!.cwd);
+    }
+    return tasks;
+  }
+
+  async registerExecution(taskId: string, binding: ExecutionBinding): Promise<void> {
+    this.executionBindings.set(taskId, binding);
+  }
+
+  async clearExecution(taskId: string): Promise<void> {
+    const binding = this.executionBindings.get(taskId);
+    if (!binding) {
+      return;
+    }
+
+    await binding.cleanup?.();
+    this.executionBindings.delete(taskId);
+  }
+
+  async cancelTask(taskId: string): Promise<boolean> {
+    const task = this.store.getTask(taskId);
+    if (!task || isTerminalStatus(task.status)) {
+      return false;
+    }
+
+    const binding = this.executionBindings.get(taskId);
+    await binding?.abort?.();
+    await this.clearExecution(taskId);
+    await this.updateTask(taskId, {
+      status: TaskStatus.CANCELLED,
+      endTime: new Date().toISOString(),
+    });
+
+    return true;
+  }
+
+  async clearAllTasks(): Promise<number> {
+    const tasks = this.store.getAllTasks();
+    for (const task of tasks) {
+      await this.cancelTask(task.id).catch(() => {});
+    }
+    this.store.clear();
+    if (tasks[0]) {
+      await this.persist(tasks[0].cwd);
+    }
+    return tasks.length;
+  }
+
+  private async persist(cwd: string): Promise<void> {
+    await saveWorkspaceState({
+      cwd,
+      storageRoot: this.storageRoot,
+      tasks: this.store.getAllTasks(),
+      profiles: this.getProfiles?.() ?? [],
+    });
+  }
+}