tycono 0.1.56 → 0.1.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tycono",
-  "version": "0.1.56",
+  "version": "0.1.57",
   "description": "Build an AI company. Watch them work.",
   "type": "module",
   "bin": {

package/src/api/src/engine/agent-loop.ts

@@ -1,7 +1,7 @@
 import { AnthropicProvider, type LLMProvider, type LLMMessage, type ToolResult, type MessageContent } from './llm-adapter.js';
 import { type OrgTree, getSubordinates } from './org-tree.js';
 import { assembleContext, type TeamStatus } from './context-assembler.js';
-import { validateDispatch } from './authority-validator.js';
+import { validateDispatch, validateConsult } from './authority-validator.js';
 import { getToolsForRole } from './tools/definitions.js';
 import { executeTool, type ToolExecutorOptions } from './tools/executor.js';
 import { type TokenLedger } from '../services/token-ledger.js';
@@ -30,6 +30,7 @@ export interface AgentConfig {
   onText?: (text: string) => void;
   onToolExec?: (name: string, input: Record<string, unknown>) => void;
   onDispatch?: (roleId: string, task: string) => void;
+  onConsult?: (roleId: string, question: string) => void;
   onTurnComplete?: (turn: number) => void;
 }
 
@@ -56,6 +57,7 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
     onText,
     onToolExec,
     onDispatch: onDispatchCallback,
+    onConsult: onConsultCallback,
     onTurnComplete,
   } = config;
 
@@ -130,6 +132,47 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
       totalInput += subResult.totalTokens.input;
       totalOutput += subResult.totalTokens.output;
 
+      return subResult.output;
+    },
+    onConsult: async (targetRoleId: string, question: string) => {
+      // Authority check
+      const authResult = validateConsult(orgTree, roleId, targetRoleId);
+      if (!authResult.allowed) {
+        return `Consult rejected: ${authResult.reason}`;
+      }
+
+      // Circular consult detection
+      if (visitedRoles.has(targetRoleId)) {
+        return `[CONSULT BLOCKED] Circular consult detected: ${roleId} → ${targetRoleId}. Chain: ${[...visitedRoles].join(' → ')}`;
+      }
+
+      onConsultCallback?.(targetRoleId, question);
+
+      // Run sub-agent in read-only mode for the consulted role
+      const consultTask = `[Consultation from ${roleId}] ${question}\n\nAnswer this question based on your role's expertise and knowledge. Be concise and specific.`;
+      const subResult = await runAgentLoop({
+        companyRoot,
+        roleId: targetRoleId,
+        task: consultTask,
+        sourceRole: roleId,
+        orgTree,
+        readOnly: true, // Consult is always read-only
+        maxTurns: Math.min(maxTurns, 10), // Limit consult turns
+        llm,
+        depth: depth + 1,
+        visitedRoles: new Set(visitedRoles),
+        abortSignal,
+        jobId: config.jobId,
+        model: config.model,
+        tokenLedger: config.tokenLedger,
+        onText: (text) => onText?.(`[consult:${targetRoleId}] ${text}`),
+        onToolExec,
+      });
+
+      // Aggregate sub-agent tokens
+      totalInput += subResult.totalTokens.input;
+      totalOutput += subResult.totalTokens.output;
+
       return subResult.output;
     },
   };

package/src/api/src/engine/authority-validator.ts

@@ -1,4 +1,4 @@
-import { type OrgTree, canDispatchTo, getChainOfCommand } from './org-tree.js';
+import { type OrgTree, canDispatchTo, canConsult, getChainOfCommand } from './org-tree.js';
 
 /* ─── Types ──────────────────────────────────── */
 
@@ -47,6 +47,37 @@ export function validateDispatch(
   return { allowed: true, reason: 'Dispatch authorized' };
 }
 
+/**
+ * Validate whether a source role can consult (ask a question to) a target role.
+ * Allowed: peers (same parent), direct manager, or subordinates.
+ */
+export function validateConsult(
+  orgTree: OrgTree,
+  sourceRole: string,
+  targetRole: string,
+): AuthResult {
+  if (sourceRole === targetRole) {
+    return { allowed: false, reason: `Cannot consult self (${sourceRole})` };
+  }
+
+  if (!orgTree.nodes.has(sourceRole) && sourceRole !== 'ceo') {
+    return { allowed: false, reason: `Source role not found: ${sourceRole}` };
+  }
+
+  if (!orgTree.nodes.has(targetRole)) {
+    return { allowed: false, reason: `Target role not found: ${targetRole}` };
+  }
+
+  if (!canConsult(orgTree, sourceRole, targetRole)) {
+    return {
+      allowed: false,
+      reason: `${sourceRole} cannot consult ${targetRole}. Only peers (same manager), direct manager, or subordinates are allowed.`,
+    };
+  }
+
+  return { allowed: true, reason: 'Consult authorized' };
+}
+
 /**
  * Validate whether a role can perform a write operation to a given path.
  * Checks the knowledge.writes scope from role.yaml.

package/src/api/src/engine/context-assembler.ts

@@ -8,6 +8,7 @@ import {
   getSubordinates,
   getChainOfCommand,
   formatOrgChart,
+  canConsult,
 } from './org-tree.js';
 
 /* ─── Types ──────────────────────────────────── */
@@ -113,6 +114,12 @@ export function assembleContext(
     sections.push(buildDispatchSection(orgTree, roleId, subordinates, options?.teamStatus));
   }
 
+  // Consult 도구 안내 (상담 가능한 Role이 있는 경우)
+  const consultSection = buildConsultSection(orgTree, roleId);
+  if (consultSection) {
+    sections.push(consultSection);
+  }
+
   // Language preference
   const prefs = readPreferences(companyRoot);
   const lang = prefs.language ?? 'auto';
@@ -514,3 +521,48 @@ Every dispatch MUST include:
 
   return section;
 }
+
+function buildConsultSection(orgTree: OrgTree, roleId: string): string | null {
+  // Build list of roles this agent can consult
+  const consultable: string[] = [];
+  for (const [id] of orgTree.nodes) {
+    if (id !== roleId && canConsult(orgTree, roleId, id)) {
+      consultable.push(id);
+    }
+  }
+
+  if (consultable.length === 0) return null;
+
+  const roleList = consultable.map((id) => {
+    const n = orgTree.nodes.get(id);
+    if (!n) return `- \`${id}\``;
+    const firstLine = n.persona.split('\n')[0] || n.name;
+    return `- **${n.name}** (\`${id}\`): ${firstLine}`;
+  }).join('\n');
+
+  return `# Consult (Ask Colleagues)
+
+You can ask questions to other roles using the \`consult\` tool:
+
+${roleList}
+
+## How to Consult
+
+Use the \`consult\` tool:
+\`\`\`json
+{ "roleId": "designer", "question": "What color scheme are you using for the dashboard?" }
+\`\`\`
+
+The consulted role will answer your question in read-only mode and return the response to you.
+
+## When to Use
+- Need technical decisions or clarifications from your manager
+- Need design/implementation details from a peer
+- Need domain expertise from another team member
+- Unsure about architecture or conventions — ask before guessing
+
+## Rules
+- The consulted role answers in **read-only mode** (no file modifications)
+- Keep questions specific and concise for better answers
+- Don't consult for tasks that should be dispatched (use dispatch for work assignments)`;
+}

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

@@ -1,11 +1,11 @@
 // Context Engine — public API
-export { buildOrgTree, canDispatchTo, getSubordinates, getDescendants, getChainOfCommand, formatOrgChart, refreshOrgTree } from './org-tree.js';
+export { buildOrgTree, canDispatchTo, canConsult, getSubordinates, getDescendants, getChainOfCommand, formatOrgChart, refreshOrgTree } from './org-tree.js';
 export type { OrgTree, OrgNode, Authority, KnowledgeAccess } from './org-tree.js';
 
 export { assembleContext } from './context-assembler.js';
 export type { AssembledContext } from './context-assembler.js';
 
-export { validateDispatch, validateWrite, validateRead } from './authority-validator.js';
+export { validateDispatch, validateConsult, validateWrite, validateRead } from './authority-validator.js';
 export type { AuthResult } from './authority-validator.js';
 
 export { RoleLifecycleManager } from './role-lifecycle.js';

package/src/api/src/engine/org-tree.ts

@@ -195,6 +195,24 @@ export function canDispatchTo(tree: OrgTree, source: string, target: string): bo
   return descendants.includes(target);
 }
 
+/** Can source consult (ask a question to) target? Peers, direct manager, or subordinates. */
+export function canConsult(tree: OrgTree, source: string, target: string): boolean {
+  if (source === target) return false;
+  const sourceNode = tree.nodes.get(source);
+  const targetNode = tree.nodes.get(target);
+  if (!sourceNode || !targetNode) return false;
+
+  // 1. Peers — same parent
+  if (sourceNode.reportsTo === targetNode.reportsTo) return true;
+
+  // 2. Direct manager
+  if (sourceNode.reportsTo === target) return true;
+
+  // 3. Subordinates (same as dispatch scope)
+  const descendants = getDescendants(tree, source);
+  return descendants.includes(target);
+}
+
 /** Refresh tree (re-read all role.yaml files) */
 export function refreshOrgTree(companyRoot: string): OrgTree {
   return buildOrgTree(companyRoot);

package/src/api/src/engine/runners/claude-cli.ts

@@ -116,6 +116,113 @@ else:
     log(f'Check result later: python3 "$DISPATCH_CMD" --check {job_id}')
 `;
 
+/* ─── Consult Bridge Script (Python3) ────── */
+
+const CONSULT_SCRIPT = `#!/usr/bin/env python3
+"""consult-bridge: CLI runner가 다른 Role에게 질문하는 브릿지 스크립트.
+
+사용법:
+  consult <roleId> "<question>"          — Job 시작 (readOnly) + 결과 대기
+  consult --check <jobId>                — 완료된 Job 결과 조회
+
+환경변수:
+  CONSULT_API_URL    — API 서버 URL (default: http://localhost:3001)
+  CONSULT_PARENT_JOB — 부모 Job ID (자동 설정)
+  CONSULT_SOURCE_ROLE — 현재 Role ID (자동 설정)
+"""
+import sys, os, json, time, urllib.request, urllib.error
+sys.stdout.reconfigure(line_buffering=True)
+
+api = os.environ.get('CONSULT_API_URL', os.environ.get('DISPATCH_API_URL', 'http://localhost:3001'))
+
+def log(msg):
+    print(msg, flush=True)
+
+def get_result(job_id):
+    try:
+        history = json.loads(urllib.request.urlopen(f'{api}/api/jobs/{job_id}/history', timeout=10).read())
+        events = history.get('events', [])
+        text_parts = []
+        for e in events:
+            if e['type'] == 'text':
+                text_parts.append(e['data'].get('text', ''))
+            elif e['type'] == 'job:error':
+                text_parts.append('\\nERROR: ' + e['data'].get('message', ''))
+        return ''.join(text_parts) or '(No text output)'
+    except Exception as e:
+        return f'ERROR: Failed to get result: {e}'
+
+# Mode: --check <jobId>
+if len(sys.argv) >= 3 and sys.argv[1] == '--check':
+    job_id = sys.argv[2]
+    try:
+        info = json.loads(urllib.request.urlopen(f'{api}/api/jobs/{job_id}', timeout=10).read())
+        status = info.get('status', 'unknown')
+        if status == 'running':
+            log(f'Job {job_id} is still running. Try again later.')
+        else:
+            log(f'=== Job {job_id}: {status} ===')
+            log(get_result(job_id))
+    except Exception as e:
+        log(f'ERROR: {e}')
+    sys.exit(0)
+
+# Mode: consult <roleId> "<question>"
+if len(sys.argv) < 3:
+    log('Usage: consult <roleId> "<question>"')
+    log('       consult --check <jobId>')
+    sys.exit(1)
+
+role_id = sys.argv[1]
+question = ' '.join(sys.argv[2:])
+parent_job = os.environ.get('CONSULT_PARENT_JOB', os.environ.get('DISPATCH_PARENT_JOB', ''))
+source_role = os.environ.get('CONSULT_SOURCE_ROLE', os.environ.get('DISPATCH_SOURCE_ROLE', 'ceo'))
+
+# Start job (readOnly + consult type)
+task = f'[Consultation from {source_role}] {question}\\n\\nAnswer this question based on your role\\'s expertise and knowledge. Be concise and specific.'
+body = json.dumps({
+    'type': 'consult',
+    'roleId': role_id,
+    'task': task,
+    'sourceRole': source_role,
+    'readOnly': True,
+    'parentJobId': parent_job if parent_job else None,
+}).encode()
+
+try:
+    req = urllib.request.Request(f'{api}/api/jobs', body, {'Content-Type': 'application/json'})
+    resp = json.loads(urllib.request.urlopen(req, timeout=10).read())
+    job_id = resp['jobId']
+except Exception as e:
+    log(f'ERROR: Failed to start consult job: {e}')
+    sys.exit(1)
+
+log(f'=== Consulting {role_id.upper()} ===')
+log(f'Question: {question[:120]}')
+log(f'Job ID: {job_id}')
+
+# Wait for completion (max ~100s)
+status = 'running'
+waited = 0
+while waited < 100:
+    try:
+        info = json.loads(urllib.request.urlopen(f'{api}/api/jobs/{job_id}', timeout=5).read())
+        status = info.get('status', 'unknown')
+        if status in ('done', 'error'):
+            break
+    except Exception:
+        pass
+    time.sleep(3)
+    waited += 3
+
+if status in ('done', 'error'):
+    log(f'\\n=== {role_id.upper()} Answer ({status}) ===')
+    log(get_result(job_id))
+else:
+    log(f'\\n{role_id.upper()} is still thinking (waited {waited}s).')
+    log(f'Check result later: python3 "$CONSULT_CMD" --check {job_id}')
+`;
+
 /* ─── Claude CLI Runner ──────────────────────── */
 
 /**
@@ -163,6 +270,10 @@ export class ClaudeCliRunner implements ExecutionRunner {
       fs.writeFileSync(dispatchScript, DISPATCH_SCRIPT, { mode: 0o755 });
     }
 
+    // Consult Bridge — available to ALL roles (not just managers)
+    const consultScript = path.join(tmpDir, `consult-${roleId}-${Date.now()}.py`);
+    fs.writeFileSync(consultScript, CONSULT_SCRIPT, { mode: 0o755 });
+
     // 5. Playwright MCP 설정 — 각 runner 인스턴스가 독립 브라우저 사용
     const runnerOutputDir = path.join(tmpDir, `playwright-${roleId}-${Date.now()}`);
     fs.mkdirSync(runnerOutputDir, { recursive: true });
@@ -207,6 +318,8 @@ export class ClaudeCliRunner implements ExecutionRunner {
     }
     // dispatch 명령어 경로를 PATH에 추가하지 않고 절대 경로로 사용
     cleanEnv.DISPATCH_CMD = dispatchScript;
+    cleanEnv.CONSULT_CMD = consultScript;
+    cleanEnv.CONSULT_SOURCE_ROLE = roleId;
 
     const modelName = config.model ?? 'claude-sonnet-4-5';
     // Use codeRoot as cwd if configured, otherwise fall back to companyRoot
@@ -245,6 +358,7 @@ export class ClaudeCliRunner implements ExecutionRunner {
             resolved = true;
             try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
             try { fs.unlinkSync(dispatchScript); } catch { /* ignore */ }
+            try { fs.unlinkSync(consultScript); } catch { /* ignore */ }
             try { fs.rmSync(runnerOutputDir, { recursive: true, force: true }); } catch { /* ignore */ }
             resolve({
               output,
@@ -339,6 +453,7 @@ export class ClaudeCliRunner implements ExecutionRunner {
         // 임시 파일 정리
         try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
         try { fs.unlinkSync(dispatchScript); } catch { /* ignore */ }
+        try { fs.unlinkSync(consultScript); } catch { /* ignore */ }
         try { fs.rmSync(runnerOutputDir, { recursive: true, force: true }); } catch { /* ignore */ }
 
         // 비정상 종료 시에도 결과 반환 (output이 있을 수 있으므로)
@@ -356,6 +471,7 @@ export class ClaudeCliRunner implements ExecutionRunner {
         resolved = true;
         try { fs.unlinkSync(promptFile); } catch { /* ignore */ }
         try { fs.unlinkSync(dispatchScript); } catch { /* ignore */ }
+        try { fs.unlinkSync(consultScript); } catch { /* ignore */ }
         try { fs.rmSync(runnerOutputDir, { recursive: true, force: true }); } catch { /* ignore */ }
         reject(err);
       });

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

@@ -44,6 +44,7 @@ export class DirectApiRunner implements ExecutionRunner {
       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),
     }).then((agentResult): RunnerResult => ({
       output: agentResult.output,

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

@@ -46,6 +46,7 @@ export interface RunnerCallbacks {
   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;
 }

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

@@ -89,6 +89,22 @@ export const DISPATCH_TOOL: ToolDefinition = {
   },
 };
 
+/**
+ * 상담 도구 — 모든 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에 따른 도구 목록 반환
  */
@@ -97,7 +113,7 @@ export function getToolsForRole(hasSubordinates: boolean, readOnly: boolean): To
     return [...READ_TOOLS];
   }
 
-  const tools = [...READ_TOOLS, ...WRITE_TOOLS];
+  const tools = [...READ_TOOLS, ...WRITE_TOOLS, CONSULT_TOOL];
 
   if (hasSubordinates) {
     tools.push(DISPATCH_TOOL);

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

@@ -12,6 +12,7 @@ export interface ToolExecutorOptions {
   roleId: string;
   orgTree: OrgTree;
   onDispatch?: (roleId: string, task: string) => Promise<string>;
+  onConsult?: (roleId: string, question: string) => Promise<string>;
   onToolExec?: (name: string, input: Record<string, unknown>) => void;
 }
 
@@ -21,7 +22,7 @@ export async function executeTool(
   toolCall: ToolCall,
   options: ToolExecutorOptions,
 ): Promise<ToolResult> {
-  const { companyRoot, roleId, orgTree, onDispatch, onToolExec } = options;
+  const { companyRoot, roleId, orgTree, onDispatch, onConsult, onToolExec } = options;
   const { id, name, input } = toolCall;
 
   onToolExec?.(name, input);
@@ -40,6 +41,8 @@ export async function executeTool(
         return editFile(id, input, companyRoot, roleId, orgTree);
       case 'dispatch':
         return await dispatchTask(id, input, onDispatch);
+      case 'consult':
+        return await consultTask(id, input, onConsult);
       default:
         return { tool_use_id: id, content: `Unknown tool: ${name}`, is_error: true };
     }
@@ -286,3 +289,23 @@ async function dispatchTask(
   const result = await onDispatch(roleId, task);
   return { tool_use_id: id, content: result };
 }
+
+async function consultTask(
+  id: string,
+  input: Record<string, unknown>,
+  onConsult?: (roleId: string, question: string) => Promise<string>,
+): Promise<ToolResult> {
+  const roleId = String(input.roleId ?? '');
+  const question = String(input.question ?? '');
+
+  if (!roleId || !question) {
+    return { tool_use_id: id, content: 'Error: roleId and question are required', is_error: true };
+  }
+
+  if (!onConsult) {
+    return { tool_use_id: id, content: 'Error: consult not available in this context', is_error: true };
+  }
+
+  const result = await onConsult(roleId, question);
+  return { tool_use_id: id, content: result };
+}

package/src/api/src/routes/execute.ts

@@ -292,7 +292,9 @@ function handleReplyToJob(jobId: string, body: Record<string, unknown>, res: Ser
     return;
   }
 
-  const newJob = jobManager.replyToJob(jobId, message);
+  const responderRole = body.responderRole as string | undefined;
+
+  const newJob = jobManager.replyToJob(jobId, message, responderRole);
   if (!newJob) {
     jsonResponse(res, 400, { error: 'Job not found or not awaiting input' });
     return;

package/src/api/src/services/company-config.ts

@@ -7,18 +7,39 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+export interface ConversationLimits {
+  /** Harness 레벨 경고 턴 수 (기본 50). 도달 시 turn:warning 이벤트 발생. */
+  softLimit: number;
+  /** Harness 레벨 강제 종료 턴 수 (기본 200). 도달 시 Runner abort. */
+  hardLimit: number;
+}
+
 export interface CompanyConfig {
   engine: 'claude-cli' | 'direct-api';
   model?: string;
   apiKey?: string;
   codeRoot?: string;  // 코드 프로젝트 경로 (AKB와 분리된 코드 repo)
+  conversationLimits?: Partial<ConversationLimits>;
 }
 
 export const TYCONO_DIR = '.tycono';
 const CONFIG_DIR = TYCONO_DIR;
 const CONFIG_FILE = 'config.json';
+const DEFAULT_CONVERSATION_LIMITS: ConversationLimits = {
+  softLimit: 50,
+  hardLimit: 200,
+};
+
 const DEFAULT_CONFIG: CompanyConfig = { engine: 'claude-cli' };
 
+/** Resolve conversation limits with defaults. */
+export function getConversationLimits(config: CompanyConfig): ConversationLimits {
+  return {
+    ...DEFAULT_CONVERSATION_LIMITS,
+    ...config.conversationLimits,
+  };
+}
+
 function configPath(companyRoot: string): string {
   return path.join(companyRoot, CONFIG_DIR, CONFIG_FILE);
 }