zyflow 0.6.4

package/mcp-server/agent-tools.ts

@@ -0,0 +1,375 @@
+/**
+ * MCP Tools for ZyFlow Agent execution
+ *
+ * These tools allow Claude Code (or other MCP clients) to:
+ * - Execute OpenSpec changes using the Python agent server
+ * - Monitor agent execution status
+ * - Control running agents (stop, resume)
+ */
+
+const AGENT_SERVER_URL = process.env.ZYFLOW_AGENT_SERVER || 'http://localhost:3002'
+
+// Types
+interface ExecuteChangeArgs {
+  changeId: string
+  projectPath?: string
+  model?: 'claude-sonnet' | 'claude-haiku' | 'claude-opus'
+}
+
+interface GetAgentStatusArgs {
+  sessionId: string
+}
+
+interface StopAgentArgs {
+  sessionId: string
+}
+
+interface ResumeAgentArgs {
+  sessionId: string
+}
+
+// ListAgentSessionsArgs intentionally empty - lists all sessions without filters
+
+interface AgentSession {
+  session_id: string
+  change_id: string
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped'
+  created_at: string
+  updated_at: string
+  project_path: string
+  current_task: string | null
+  completed_tasks: number
+  total_tasks: number
+  error: string | null
+}
+
+interface ExecuteResponse {
+  session_id: string
+  status: string
+  message: string
+}
+
+interface AgentLogs {
+  session_id: string
+  results: Array<{
+    task_id: string
+    task_title: string
+    status: string
+    output: string
+    error: string | null
+    started_at: string | null
+    completed_at: string | null
+  }>
+  total_tasks: number
+  completed_tasks: number
+  status: string
+}
+
+// Tool definitions
+export const agentToolDefinitions = [
+  {
+    name: 'zyflow_execute_change',
+    description:
+      'OpenSpec 변경을 에이전트로 실행합니다. 백그라운드에서 태스크를 순차적으로 실행하며, 세션 ID를 반환합니다. 진행 상황은 zyflow_get_agent_status로 확인하세요.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        changeId: {
+          type: 'string',
+          description: '실행할 OpenSpec 변경 ID (예: add-payment-method)',
+        },
+        projectPath: {
+          type: 'string',
+          description: '프로젝트 경로 (선택, 기본값: 현재 디렉토리)',
+        },
+        model: {
+          type: 'string',
+          enum: ['claude-sonnet', 'claude-haiku', 'claude-opus'],
+          description: '사용할 모델 (기본값: claude-sonnet)',
+        },
+      },
+      required: ['changeId'],
+    },
+  },
+  {
+    name: 'zyflow_get_agent_status',
+    description:
+      '실행 중인 에이전트 세션의 상태를 조회합니다. 진행률, 현재 태스크, 에러 등을 확인할 수 있습니다.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: '에이전트 세션 ID',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'zyflow_stop_agent',
+    description:
+      '실행 중인 에이전트 세션을 중단합니다. 현재 태스크가 완료된 후 중단됩니다.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: '중단할 에이전트 세션 ID',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'zyflow_resume_agent',
+    description:
+      '중단된 에이전트 세션을 재개합니다. 중단 지점에서 다음 태스크부터 실행합니다.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: '재개할 에이전트 세션 ID',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'zyflow_list_agent_sessions',
+    description: '모든 에이전트 세션 목록을 조회합니다. 상태별 필터링이 가능합니다.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        status: {
+          type: 'string',
+          enum: ['pending', 'running', 'completed', 'failed', 'stopped'],
+          description: '상태로 필터링 (선택)',
+        },
+      },
+    },
+  },
+  {
+    name: 'zyflow_get_agent_logs',
+    description:
+      '에이전트 세션의 실행 로그를 조회합니다. 각 태스크의 실행 결과와 출력을 확인할 수 있습니다.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: '에이전트 세션 ID',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'zyflow_delete_agent_session',
+    description:
+      '에이전트 세션을 삭제합니다. 실행 중인 세션은 삭제할 수 없습니다.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: '삭제할 에이전트 세션 ID',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+]
+
+// Helper function for fetch with error handling
+async function agentFetch<T>(
+  path: string,
+  options?: RequestInit
+): Promise<{ success: boolean; data?: T; error?: string }> {
+  try {
+    const response = await fetch(`${AGENT_SERVER_URL}${path}`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        ...options?.headers,
+      },
+    })
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ detail: response.statusText })) as { detail?: string }
+      return {
+        success: false,
+        error: errorData.detail || `HTTP ${response.status}: ${response.statusText}`,
+      }
+    }
+
+    const data = await response.json() as T
+    return { success: true, data }
+  } catch (error) {
+    // Check if server is running
+    if (error instanceof TypeError && error.message.includes('fetch')) {
+      return {
+        success: false,
+        error:
+          'Agent 서버에 연결할 수 없습니다. "npm run py:server" 또는 "npm run dev:full"로 서버를 시작하세요.',
+      }
+    }
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+// Handler functions
+export async function handleExecuteChange(
+  args: ExecuteChangeArgs,
+  projectPath: string
+): Promise<{ success: boolean; data?: ExecuteResponse; error?: string; message?: string }> {
+  const result = await agentFetch<ExecuteResponse>('/api/agents/execute', {
+    method: 'POST',
+    body: JSON.stringify({
+      change_id: args.changeId,
+      project_path: args.projectPath || projectPath,
+      model: args.model || 'claude-sonnet',
+    }),
+  })
+
+  if (result.success && result.data) {
+    return {
+      success: true,
+      data: result.data,
+      message: `에이전트 세션이 시작되었습니다. 세션 ID: ${result.data.session_id}\n진행 상황은 zyflow_get_agent_status로 확인하세요.`,
+    }
+  }
+
+  return result
+}
+
+export async function handleGetAgentStatus(
+  args: GetAgentStatusArgs
+): Promise<{ success: boolean; data?: AgentSession; error?: string; message?: string }> {
+  const result = await agentFetch<AgentSession>(`/api/agents/sessions/${args.sessionId}`)
+
+  if (result.success && result.data) {
+    const session = result.data
+    const progress = session.total_tasks > 0
+      ? Math.round((session.completed_tasks / session.total_tasks) * 100)
+      : 0
+
+    let statusMessage = `상태: ${session.status}\n`
+    statusMessage += `진행률: ${session.completed_tasks}/${session.total_tasks} (${progress}%)\n`
+
+    if (session.current_task) {
+      statusMessage += `현재 태스크: ${session.current_task}\n`
+    }
+
+    if (session.error) {
+      statusMessage += `에러: ${session.error}\n`
+    }
+
+    return {
+      success: true,
+      data: session,
+      message: statusMessage,
+    }
+  }
+
+  return result
+}
+
+export async function handleStopAgent(
+  args: StopAgentArgs
+): Promise<{ success: boolean; data?: { message: string; session_id: string }; error?: string }> {
+  const result = await agentFetch<{ message: string; session_id: string }>(
+    `/api/agents/sessions/${args.sessionId}/stop`,
+    { method: 'POST' }
+  )
+
+  return result
+}
+
+export async function handleResumeAgent(
+  args: ResumeAgentArgs
+): Promise<{ success: boolean; data?: { message: string; session_id: string }; error?: string }> {
+  const result = await agentFetch<{ message: string; session_id: string }>(
+    `/api/agents/sessions/${args.sessionId}/resume`,
+    { method: 'POST' }
+  )
+
+  return result
+}
+
+export async function handleListAgentSessions(
+  args?: { status?: string }
+): Promise<{ success: boolean; data?: AgentSession[]; error?: string; message?: string }> {
+  const result = await agentFetch<AgentSession[]>('/api/agents/sessions')
+
+  if (result.success && result.data) {
+    let sessions = result.data
+
+    // Filter by status if provided
+    if (args?.status) {
+      sessions = sessions.filter(s => s.status === args.status)
+    }
+
+    if (sessions.length === 0) {
+      return {
+        success: true,
+        data: sessions,
+        message: '실행 중인 에이전트 세션이 없습니다.',
+      }
+    }
+
+    const summary = sessions.map(s => {
+      const progress = s.total_tasks > 0
+        ? Math.round((s.completed_tasks / s.total_tasks) * 100)
+        : 0
+      return `- ${s.session_id.substring(0, 8)}... | ${s.change_id} | ${s.status} | ${progress}%`
+    }).join('\n')
+
+    return {
+      success: true,
+      data: sessions,
+      message: `${sessions.length}개의 세션:\n${summary}`,
+    }
+  }
+
+  return result
+}
+
+export async function handleGetAgentLogs(
+  args: GetAgentStatusArgs
+): Promise<{ success: boolean; data?: AgentLogs; error?: string; message?: string }> {
+  const result = await agentFetch<AgentLogs>(`/api/agents/sessions/${args.sessionId}/logs`)
+
+  if (result.success && result.data) {
+    const logs = result.data
+    const taskResults = logs.results
+      .map(r => {
+        const status = r.status === 'completed' ? '✅' : r.status === 'failed' ? '❌' : '⏳'
+        return `${status} ${r.task_title}${r.error ? ` (에러: ${r.error})` : ''}`
+      })
+      .join('\n')
+
+    return {
+      success: true,
+      data: logs,
+      message: `실행 로그 (${logs.completed_tasks}/${logs.total_tasks} 완료):\n${taskResults || '아직 완료된 태스크가 없습니다.'}`,
+    }
+  }
+
+  return result
+}
+
+export async function handleDeleteAgentSession(
+  args: StopAgentArgs
+): Promise<{ success: boolean; data?: { message: string; session_id: string }; error?: string }> {
+  const result = await agentFetch<{ message: string; session_id: string }>(
+    `/api/agents/sessions/${args.sessionId}`,
+    { method: 'DELETE' }
+  )
+
+  return result
+}

package/mcp-server/cli-models.ts

@@ -0,0 +1,193 @@
+/**
+ * CLI Model Mappings
+ *
+ * 각 CLI별 모델 매핑 및 작업별 기본 모델 설정
+ */
+
+import type { CLIType, ModelTier, TaskType } from './post-task-types.js';
+import { TASK_DEFAULT_MODEL_TIER } from './post-task-types.js';
+
+// ============================================================================
+// CLI별 모델 매핑
+// ============================================================================
+
+/**
+ * CLI별 모델 티어 매핑
+ */
+export const CLI_MODELS: Record<CLIType, Record<ModelTier, string>> = {
+  claude: {
+    fast: 'claude-haiku',
+    balanced: 'claude-sonnet',
+    powerful: 'claude-opus',
+  },
+  gemini: {
+    fast: 'gemini-2.0-flash',
+    balanced: 'gemini-2.0-flash',
+    powerful: 'gemini-2.5-pro',
+  },
+  qwen: {
+    fast: 'qwen-turbo',
+    balanced: 'qwen-plus',
+    powerful: 'qwen-max',
+  },
+  openai: {
+    fast: 'gpt-4o-mini',
+    balanced: 'gpt-4o',
+    powerful: 'o1',
+  },
+};
+
+/**
+ * CLI별 실행 명령어 템플릿
+ */
+export const CLI_COMMANDS: Record<CLIType, string> = {
+  claude: 'claude',
+  gemini: 'gemini',
+  qwen: 'qwen',
+  openai: 'openai',
+};
+
+/**
+ * CLI별 모델 플래그
+ */
+export const CLI_MODEL_FLAGS: Record<CLIType, string> = {
+  claude: '--model',
+  gemini: '--model',
+  qwen: '--model',
+  openai: '--model',
+};
+
+// ============================================================================
+// Model Selection Functions
+// ============================================================================
+
+/**
+ * 작업에 대한 기본 모델 가져오기
+ */
+export function getDefaultModelForTask(task: TaskType): ModelTier {
+  return TASK_DEFAULT_MODEL_TIER[task] || 'balanced';
+}
+
+/**
+ * CLI와 모델 티어로 실제 모델 이름 가져오기
+ */
+export function getModelName(cli: CLIType, tier: ModelTier): string {
+  return CLI_MODELS[cli]?.[tier] || CLI_MODELS.claude[tier];
+}
+
+/**
+ * 작업에 대한 최적 모델 결정
+ */
+export function selectModelForTask(
+  task: TaskType,
+  options?: { cli?: CLIType; modelOverride?: ModelTier }
+): { cli: CLIType; model: string; tier: ModelTier } {
+  const cli = options?.cli || 'claude';
+  const tier = options?.modelOverride || getDefaultModelForTask(task);
+  const model = getModelName(cli, tier);
+
+  return { cli, model, tier };
+}
+
+/**
+ * CLI 명령어 생성
+ */
+export function buildCLICommand(
+  cli: CLIType,
+  model: string,
+  prompt: string,
+  additionalArgs?: string[]
+): string {
+  const baseCmd = CLI_COMMANDS[cli];
+  const modelFlag = CLI_MODEL_FLAGS[cli];
+  const args = additionalArgs?.join(' ') || '';
+
+  // 프롬프트는 stdin으로 전달하거나 파일로 전달
+  return `${baseCmd} ${modelFlag} ${model} ${args}`.trim();
+}
+
+// ============================================================================
+// CLI Availability Check
+// ============================================================================
+
+/**
+ * CLI 사용 가능 여부 확인을 위한 명령어
+ */
+export const CLI_VERSION_COMMANDS: Record<CLIType, string> = {
+  claude: 'claude --version',
+  gemini: 'gemini --version',
+  qwen: 'qwen --version',
+  openai: 'openai --version',
+};
+
+/**
+ * 기본 CLI 순서 (fallback용)
+ */
+export const CLI_PRIORITY: CLIType[] = ['claude', 'gemini', 'qwen', 'openai'];
+
+// ============================================================================
+// Model Cost Estimation (상대적 비용)
+// ============================================================================
+
+/**
+ * 모델 티어별 상대적 비용 (1~10 스케일)
+ */
+export const MODEL_TIER_COST: Record<ModelTier, number> = {
+  fast: 1,
+  balanced: 5,
+  powerful: 10,
+};
+
+/**
+ * 예상 비용 계산 (작업 목록 기준)
+ */
+export function estimateCost(tasks: TaskType[], modelOverride?: ModelTier): number {
+  return tasks.reduce((total, task) => {
+    const tier = modelOverride || getDefaultModelForTask(task);
+    return total + MODEL_TIER_COST[tier];
+  }, 0);
+}
+
+// ============================================================================
+// Model Descriptions (UI/문서용)
+// ============================================================================
+
+/**
+ * 모델 티어 설명
+ */
+export const MODEL_TIER_DESCRIPTIONS: Record<ModelTier, { name: string; description: string }> = {
+  fast: {
+    name: 'Fast',
+    description: '빠른 처리, 낮은 비용. 단순 패턴 수정에 적합',
+  },
+  balanced: {
+    name: 'Balanced',
+    description: '균형 잡힌 성능. 대부분의 작업에 적합',
+  },
+  powerful: {
+    name: 'Powerful',
+    description: '최고 성능. 복잡한 분석 및 보안 관련 작업에 적합',
+  },
+};
+
+/**
+ * CLI 설명
+ */
+export const CLI_DESCRIPTIONS: Record<CLIType, { name: string; description: string }> = {
+  claude: {
+    name: 'Claude (Anthropic)',
+    description: 'Anthropic의 Claude 모델. 기본 CLI',
+  },
+  gemini: {
+    name: 'Gemini (Google)',
+    description: 'Google의 Gemini 모델',
+  },
+  qwen: {
+    name: 'Qwen (Alibaba)',
+    description: 'Alibaba의 Qwen 모델',
+  },
+  openai: {
+    name: 'OpenAI',
+    description: 'OpenAI의 GPT 모델',
+  },
+};

package/mcp-server/context.ts

@@ -0,0 +1,110 @@
+import { readFile, readdir } from 'fs/promises'
+import { join } from 'path'
+import type { Task, TaskContext, TasksFile } from './types.js'
+
+/**
+ * Read proposal.md content for a change
+ */
+export async function readProposal(projectPath: string, changeId: string): Promise<string> {
+  const proposalPath = join(projectPath, 'openspec', 'changes', changeId, 'proposal.md')
+  try {
+    return await readFile(proposalPath, 'utf-8')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Find and read related spec files for a change
+ */
+export async function readRelatedSpecs(projectPath: string, changeId: string): Promise<string> {
+  const specsDir = join(projectPath, 'openspec', 'changes', changeId, 'specs')
+
+  try {
+    const specs: string[] = []
+    const entries = await readdir(specsDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const specPath = join(specsDir, entry.name, 'spec.md')
+        try {
+          const content = await readFile(specPath, 'utf-8')
+          specs.push(`## ${entry.name}\n\n${content}`)
+        } catch {
+          // Spec file doesn't exist
+        }
+      }
+    }
+
+    return specs.join('\n\n---\n\n')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Extract suggested files from proposal.md
+ * Looks for file paths mentioned in the proposal
+ */
+export function extractSuggestedFiles(proposal: string): string[] {
+  const files: string[] = []
+
+  // Match common file path patterns
+  const patterns = [
+    /`([^`]+\.(ts|tsx|js|jsx|md|json|sql))`/g,
+    /\b(src\/[a-zA-Z0-9_\-/]+\.(ts|tsx|js|jsx))\b/g,
+    /\b(server\/[a-zA-Z0-9_\-/]+\.(ts|js))\b/g,
+  ]
+
+  for (const pattern of patterns) {
+    let match
+    while ((match = pattern.exec(proposal)) !== null) {
+      const file = match[1]
+      if (!files.includes(file)) {
+        files.push(file)
+      }
+    }
+  }
+
+  return files.slice(0, 10) // Limit to 10 suggestions
+}
+
+/**
+ * Build task context for a specific task
+ */
+export async function buildTaskContext(
+  projectPath: string,
+  changeId: string,
+  tasksFile: TasksFile,
+  _task: Task
+): Promise<TaskContext> {
+  const proposal = await readProposal(projectPath, changeId)
+  const relatedSpec = await readRelatedSpecs(projectPath, changeId)
+  const suggestedFiles = extractSuggestedFiles(proposal)
+
+  // Calculate completed tasks
+  const allTasks = tasksFile.groups.flatMap(g => g.tasks)
+  const completedTasks = allTasks.filter(t => t.completed).map(t => t.id)
+  const remainingTasks = allTasks.filter(t => !t.completed).length
+
+  return {
+    changeId,
+    proposal,
+    relatedSpec: relatedSpec || undefined,
+    suggestedFiles,
+    completedTasks,
+    remainingTasks,
+  }
+}
+
+/**
+ * Get design.md content if exists
+ */
+export async function readDesign(projectPath: string, changeId: string): Promise<string | null> {
+  const designPath = join(projectPath, 'openspec', 'changes', changeId, 'design.md')
+  try {
+    return await readFile(designPath, 'utf-8')
+  } catch {
+    return null
+  }
+}