tycono-server 0.1.0-beta.0

package/src/api/src/engine/runners/direct-api.ts

@@ -0,0 +1,66 @@
+import { runAgentLoop } from '../agent-loop.js';
+import { AnthropicProvider, type LLMProvider } from '../llm-adapter.js';
+import { getTokenLedger } from '../../services/token-ledger.js';
+import type { ExecutionRunner, RunnerConfig, RunnerCallbacks, RunnerHandle, RunnerResult } from './types.js';
+
+/* ─── Direct API Runner ──────────────────────── */
+
+/**
+ * Anthropic API를 직접 호출하는 실행 엔진.
+ *
+ * - @anthropic-ai/sdk로 Claude API 직접 호출
+ * - Agent Loop가 도구 실행, dispatch를 내부 처리
+ * - 토큰 사용량 정확히 추적 가능
+ * - ANTHROPIC_API_KEY 환경변수 필수
+ *
+ * 활성화: EXECUTION_ENGINE=direct-api
+ */
+export class DirectApiRunner implements ExecutionRunner {
+  private llm: LLMProvider;
+
+  constructor(llm?: LLMProvider) {
+    this.llm = llm ?? new AnthropicProvider();
+  }
+
+  execute(config: RunnerConfig, callbacks: RunnerCallbacks): RunnerHandle {
+    const abortController = new AbortController();
+
+    const tokenLedger = getTokenLedger(config.companyRoot);
+
+    const promise = runAgentLoop({
+      companyRoot: config.companyRoot,
+      roleId: config.roleId,
+      task: config.task,
+      sourceRole: config.sourceRole,
+      orgTree: config.orgTree,
+      readOnly: config.readOnly,
+      maxTurns: config.maxTurns,
+      codeRoot: config.codeRoot,
+      llm: this.llm,
+      abortSignal: abortController.signal,
+      sessionId: config.sessionId,
+      model: config.model,
+      tokenLedger,
+      attachments: config.attachments,
+      onText: (text) => callbacks.onText?.(text),
+      onToolExec: (name, input) => callbacks.onToolUse?.(name, input),
+      onDispatch: (roleId, task) => callbacks.onDispatch?.(roleId, task),
+      onConsult: (roleId, question) => callbacks.onConsult?.(roleId, question),
+      onTurnComplete: (turn) => callbacks.onTurnComplete?.(turn),
+      onPromptAssembled: (systemPrompt, userTask) => callbacks.onPromptAssembled?.(systemPrompt, userTask),
+      onAbortSession: config.onAbortSession,
+      onAmendSession: config.onAmendSession,
+    }).then((agentResult): RunnerResult => ({
+      output: agentResult.output,
+      turns: agentResult.turns,
+      totalTokens: agentResult.totalTokens,
+      toolCalls: agentResult.toolCalls,
+      dispatches: agentResult.dispatches,
+    }));
+
+    return {
+      promise,
+      abort: () => abortController.abort(),
+    };
+  }
+}

package/src/api/src/engine/runners/index.ts

@@ -0,0 +1,30 @@
+export type { ExecutionRunner, RunnerConfig, RunnerCallbacks, RunnerHandle, RunnerResult } from './types.js';
+export { ClaudeCliRunner } from './claude-cli.js';
+export { DirectApiRunner } from './direct-api.js';
+
+import { ClaudeCliRunner } from './claude-cli.js';
+import { DirectApiRunner } from './direct-api.js';
+import type { ExecutionRunner } from './types.js';
+import type { LLMProvider } from '../llm-adapter.js';
+
+/* ─── Runner Factory ─────────────────────────── */
+
+/**
+ * 환경변수 EXECUTION_ENGINE에 따라 적절한 Runner 생성.
+ *
+ *   - claude-cli (기본): Claude Code CLI 사용 — 구독 기반, 비용 없음
+ *   - direct-api: Anthropic API 직접 호출 — ANTHROPIC_API_KEY 필요
+ *
+ * @param llm - LLMProvider를 전달하면 direct-api 모드에서 해당 provider 사용
+ */
+export function createRunner(llm?: LLMProvider): ExecutionRunner {
+  const engine = process.env.EXECUTION_ENGINE || 'claude-cli';
+
+  switch (engine) {
+    case 'direct-api':
+      return new DirectApiRunner(llm);
+    case 'claude-cli':
+    default:
+      return new ClaudeCliRunner();
+  }
+}

package/src/api/src/engine/runners/types.ts

@@ -0,0 +1,95 @@
+import type { OrgTree } from '../org-tree.js';
+
+/* ─── Runner Interface ──────────────────────── */
+
+/**
+ * Execution Runner 추상화.
+ *
+ * 현재 구현:
+ *   - claude-cli: Claude Code CLI (`claude -p`) 기반 — 구독으로 비용 부담 없음
+ *   - direct-api: Anthropic API 직접 호출 — 향후 전환용
+ *
+ * EXECUTION_ENGINE 환경변수로 전환 (기본값: claude-cli)
+ */
+
+/* ─── Attachment Types ────────────────────────── */
+
+export interface ImageAttachment {
+  type: 'image';
+  data: string;      // base64 encoded
+  name: string;
+  mediaType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+}
+
+/* ─── Config ──────────────────────────────────── */
+
+export type { TeamStatus } from '../../../../shared/types.js';
+import type { TeamStatus } from '../../../../shared/types.js';
+
+export interface RunnerConfig {
+  companyRoot: string;
+  roleId: string;
+  task: string;
+  sourceRole: string;
+  orgTree: OrgTree;
+  readOnly?: boolean;
+  maxTurns?: number;
+  model?: string;
+  /** D-014: Session ID for tracking (required — primary identifier for token ledger). */
+  sessionId: string;
+  teamStatus?: TeamStatus;
+  attachments?: ImageAttachment[];
+  /** Selective dispatch scope — only these roles can be dispatched to */
+  targetRoles?: string[];
+  /** EG-001: Code project root for bash_execute tool */
+  codeRoot?: string;
+  /** PSM-004: Environment variables to inject (e.g., port assignments) */
+  env?: Record<string, string>;
+  /** Wave-scoped preset ID for knowledge injection */
+  presetId?: string;
+  /** CLI session ID for --resume (context continuity across turn limits) */
+  cliSessionId?: string;
+  /** SV-7: Supervision — abort a running session */
+  onAbortSession?: (sessionId: string) => boolean;
+  /** SV-6: Supervision — amend a running session */
+  onAmendSession?: (sessionId: string, instruction: string) => boolean;
+}
+
+/* ─── Callbacks ───────────────────────────────── */
+
+export interface RunnerCallbacks {
+  onText?: (text: string) => void;
+  onThinking?: (text: string) => void;
+  onToolUse?: (tool: string, input?: Record<string, unknown>) => void;
+  onDispatch?: (roleId: string, task: string) => void;
+  onConsult?: (roleId: string, question: string) => void;
+  onTurnComplete?: (turn: number) => void;
+  onError?: (error: string) => void;
+  /** Trace: emitted when system prompt is assembled, for full prompt capture */
+  onPromptAssembled?: (systemPrompt: string, userTask: string) => void;
+}
+
+/* ─── Result ──────────────────────────────────── */
+
+export interface RunnerResult {
+  output: string;
+  turns: number;
+  totalTokens: { input: number; output: number };
+  toolCalls: Array<{ name: string; input?: Record<string, unknown> }>;
+  dispatches: Array<{ roleId: string; task: string; result?: string }>;
+  /** CLI session ID captured from stream-json result event (for --resume) */
+  cliSessionId?: string;
+}
+
+/* ─── Handle (for abort support) ──────────────── */
+
+export interface RunnerHandle {
+  promise: Promise<RunnerResult>;
+  abort: () => void;
+}
+
+/* ─── Runner Interface ────────────────────────── */
+
+export interface ExecutionRunner {
+  execute(config: RunnerConfig, callbacks: RunnerCallbacks): RunnerHandle;
+}

package/src/api/src/engine/skill-template.ts

@@ -0,0 +1,134 @@
+import type { OrgNode } from './org-tree.js';
+
+/**
+ * Level 1: 템플릿 기반 SKILL.md 자동 생성
+ *
+ * role.yaml 데이터를 기반으로 SKILL.md 골격을 생성한다.
+ * Level 2 (AI 보강)는 Agent Runtime 완성 후 추가.
+ */
+export function generateSkillMd(node: OrgNode): string {
+  const approvalTarget = node.reportsTo || 'CEO';
+
+  const autonomousRows = node.authority.autonomous
+    .map((a) => `| ${a} | ✅ | |`)
+    .join('\n');
+
+  const approvalRows = node.authority.needsApproval
+    .map((a) => `| ${a} | | ⚠️ ${approvalTarget} 승인 |`)
+    .join('\n');
+
+  const readPaths = node.knowledge.reads
+    .map((p) => `| 읽기 | \`${p}\` |`)
+    .join('\n');
+
+  const writePaths = node.knowledge.writes
+    .map((p) => `| 쓰기 | \`${p}\` |`)
+    .join('\n');
+
+  const coreMaxim = extractMaxim(node.persona);
+
+  return `# ${node.name} Skill
+
+---
+name: ${node.id}
+description: |
+  ${node.persona.trim().split('\n')[0]}
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
+> "${coreMaxim}"
+
+## 핵심 책임
+
+| 영역 | 자율 | 승인 필요 |
+|------|------|-----------|
+${autonomousRows}
+${approvalRows}
+
+---
+
+## 작업 프로세스
+
+### 작업 수신 시
+
+\`\`\`
+1. 관련 Hub 문서 읽기
+2. 기존 문서/코드 확인 (grep 키워드 3개+)
+3. 작업 수행
+4. 결과 기록 (저널 + AKB)
+5. ${approvalTarget} 승인 필요 사항은 [APPROVAL_NEEDED] 태그
+\`\`\`
+
+---
+
+## 핵심 파일 경로
+
+| 용도 | 경로 |
+|------|------|
+${readPaths}
+${writePaths}
+| 저널 | \`roles/${node.id}/journal/\` |
+
+---
+
+## 저널 작성
+
+작업 완료 후 \`roles/${node.id}/journal/YYYY-MM-DD.md\`:
+
+\`\`\`markdown
+# ${node.name} Journal — YYYY-MM-DD
+
+### {작업 제목}
+
+#### 완료 사항
+1. ...
+
+#### [APPROVAL_NEEDED] (있는 경우)
+- ...
+
+#### 생성/수정 파일
+| 파일 | 작업 |
+|------|------|
+\`\`\`
+
+---
+
+## 보고 규칙
+
+- **일일**: ${node.reports.daily || '완료 사항 + 진행 중 + 블로커'}
+- **주간**: ${node.reports.weekly || '주간 성과 + 다음 주 목표'}
+
+---
+
+## Equipped Skills
+
+${node.skills?.length ? node.skills.map((s) => `- \`${s}\` — see \`.claude/skills/_shared/${s}/SKILL.md\``).join('\n') : '- (none)'}
+
+---
+
+## AKB 규칙
+
+- 작업 결과는 반드시 AKB에 기록
+- 일일 업무는 \`roles/${node.id}/journal/\`에 기록
+- ${approvalTarget} 승인 필요 시 [APPROVAL_NEEDED] 태그 사용
+- 새 문서 생성 시 관련 Hub에 등록 필수
+
+---
+
+## 핵심 원칙
+
+> "작업 전에 Hub 문서를 먼저 읽어라. 이미 있는 것을 다시 만들지 마라."
+
+> "모든 작업에는 기록이 남아야 한다. 기록 없는 작업은 없었던 것이다."
+`;
+}
+
+function extractMaxim(persona: string): string {
+  // Try to find a quoted phrase in persona
+  const quoted = persona.match(/"([^"]+)"/);
+  if (quoted) return quoted[1];
+
+  // Otherwise use the first sentence
+  const firstSentence = persona.trim().split(/[.。]/)[0];
+  return firstSentence.trim();
+}

package/src/api/src/engine/tools/definitions.ts

@@ -0,0 +1,201 @@
+import type { ToolDefinition } from '../llm-adapter.js';
+
+/**
+ * 읽기 전용 도구 — Ask 엔드포인트에서도 사용
+ */
+export const READ_TOOLS: ToolDefinition[] = [
+  {
+    name: 'read_file',
+    description: 'Read the contents of a file. Returns the file content as text.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path relative to company root (e.g., "knowledge/roles/cto/role.yaml")' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'list_files',
+    description: 'List files in a directory matching a glob pattern.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        directory: { type: 'string', description: 'Directory path relative to company root' },
+        pattern: { type: 'string', description: 'Glob pattern (default: "*.md")', default: '*.md' },
+      },
+      required: ['directory'],
+    },
+  },
+  {
+    name: 'search_files',
+    description: 'Search for text content across files using a pattern.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Search pattern (regex supported)' },
+        directory: { type: 'string', description: 'Directory to search in (relative to company root)', default: '.' },
+        file_pattern: { type: 'string', description: 'File glob to filter (e.g., "*.md")', default: '*' },
+      },
+      required: ['pattern'],
+    },
+  },
+];
+
+/**
+ * 쓰기 도구 — Assign 엔드포인트에서만 사용
+ */
+export const WRITE_TOOLS: ToolDefinition[] = [
+  {
+    name: 'write_file',
+    description: 'Create or overwrite a file with the given content.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path relative to company root' },
+        content: { type: 'string', description: 'File content to write' },
+      },
+      required: ['path', 'content'],
+    },
+  },
+  {
+    name: 'edit_file',
+    description: 'Edit a file by replacing a specific string with another string.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path relative to company root' },
+        old_string: { type: 'string', description: 'Exact string to find and replace' },
+        new_string: { type: 'string', description: 'Replacement string' },
+      },
+      required: ['path', 'old_string', 'new_string'],
+    },
+  },
+];
+
+/**
+ * 디스패치 도구 — 매니저 Role에게만 제공
+ */
+export const DISPATCH_TOOL: ToolDefinition = {
+  name: 'dispatch',
+  description: 'Assign a task to a subordinate role. The subordinate will execute the task independently and return the result. Only available for roles with direct reports.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      roleId: { type: 'string', description: 'Target role ID (e.g., "engineer", "pm")' },
+      task: { type: 'string', description: 'Task description for the subordinate' },
+    },
+    required: ['roleId', 'task'],
+  },
+};
+
+/**
+ * Bash 실행 도구 — 코드 프로젝트에서 시스템 명령 실행 (EG-001)
+ */
+export const BASH_TOOL: ToolDefinition = {
+  name: 'bash_execute',
+  description: 'Execute a shell command in the code project directory. Use for git, npm, tsc, node, test runners, and build tools. Commands run in the codeRoot directory (not company knowledge base). Dangerous commands (rm -rf, sudo, etc.) are blocked.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'Shell command to execute' },
+      timeout: { type: 'number', description: 'Timeout in milliseconds (default: 30000, max: 120000)' },
+      cwd: { type: 'string', description: 'Working directory relative to codeRoot (default: ".")' },
+    },
+    required: ['command'],
+  },
+};
+
+/**
+ * Supervision 도구 — C-Level에게만 제공 (부하/동료 세션 감시)
+ */
+export const HEARTBEAT_WATCH_TOOL: ToolDefinition = {
+  name: 'heartbeat_watch',
+  description: 'Block and watch activity streams of subordinates (or peers). Returns a digest of events after the specified duration or when an alert event occurs. Use this to supervise running dispatches at zero LLM cost during the wait period.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      sessionIds: { type: 'array', items: { type: 'string' }, description: 'Session IDs to watch (subordinates or peers)' },
+      durationSec: { type: 'number', description: 'Watch duration in seconds (default 120, max 300)', default: 120 },
+      alertOn: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Event types that trigger early return (default: msg:done, msg:error, msg:awaiting_input)',
+        default: ['msg:done', 'msg:error', 'msg:awaiting_input'],
+      },
+    },
+    required: ['sessionIds'],
+  },
+};
+
+export const AMEND_SESSION_TOOL: ToolDefinition = {
+  name: 'amend_session',
+  description: 'Send additional instructions to a running subordinate session. The instructions will be injected at the next turn boundary. Use when a subordinate is going in the wrong direction and needs course correction.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      sessionId: { type: 'string', description: 'Target session ID to amend' },
+      instruction: { type: 'string', description: 'Additional instruction to inject into the session' },
+    },
+    required: ['sessionId', 'instruction'],
+  },
+};
+
+export const ABORT_SESSION_TOOL: ToolDefinition = {
+  name: 'abort_session',
+  description: 'Abort a running subordinate session immediately. Use when the subordinate is clearly doing the wrong thing and needs to be stopped. You can re-dispatch with different instructions afterwards.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      sessionId: { type: 'string', description: 'Target session ID to abort' },
+      reason: { type: 'string', description: 'Reason for aborting (logged in activity stream)' },
+    },
+    required: ['sessionId'],
+  },
+};
+
+/**
+ * 상담 도구 — 모든 Role에게 제공 (동료/상관/부하에게 질문)
+ */
+export const CONSULT_TOOL: ToolDefinition = {
+  name: 'consult',
+  description: 'Ask a question to another role (peer, manager, or subordinate) and wait for their answer. The consulted role will respond in read-only mode. Use when you need information, expertise, or a decision from a colleague.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      roleId: { type: 'string', description: 'Target role ID to consult (e.g., "designer", "cto")' },
+      question: { type: 'string', description: 'The question to ask' },
+    },
+    required: ['roleId', 'question'],
+  },
+};
+
+/**
+ * Role에 따른 도구 목록 반환
+ * @param heartbeatEnabled - C-Level supervision mode enabled (provides heartbeat_watch, amend_session, abort_session)
+ */
+export function getToolsForRole(hasSubordinates: boolean, readOnly: boolean, hasBash = false, heartbeatEnabled = false, hasPeers = false): ToolDefinition[] {
+  if (readOnly) {
+    return [...READ_TOOLS];
+  }
+
+  const tools = [...READ_TOOLS, ...WRITE_TOOLS];
+  if (hasPeers) {
+    tools.push(CONSULT_TOOL);
+  }
+
+  if (hasBash) {
+    tools.push(BASH_TOOL);
+  }
+
+  if (hasSubordinates) {
+    tools.push(DISPATCH_TOOL);
+
+    // Supervision tools — only for roles with subordinates AND heartbeat enabled
+    if (heartbeatEnabled) {
+      tools.push(HEARTBEAT_WATCH_TOOL, AMEND_SESSION_TOOL, ABORT_SESSION_TOOL);
+    }
+  }
+
+  return tools;
+}