tycono 0.1.93-beta.2 → 0.1.93-beta.3

package/package.json

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

package/src/api/src/create-server.ts

@@ -32,6 +32,7 @@ import { skillsRouter } from './routes/skills.js';
 import { questsRouter } from './routes/quests.js';
 import { coinsRouter } from './routes/coins.js';
 import { activeSessionsRouter } from './routes/active-sessions.js';
+import { supervisionRouter } from './routes/supervision.js';
 import { importKnowledge } from './services/knowledge-importer.js';
 import { AnthropicProvider, type LLMProvider } from './engine/llm-adapter.js';
 import { readConfig } from './services/company-config.js';
@@ -209,6 +210,7 @@ export function createExpressApp(): express.Application {
   app.use('/api/quests', questsRouter);
   app.use('/api/coins', coinsRouter);
   app.use('/api/active-sessions', activeSessionsRouter);
+  app.use('/api/supervision', supervisionRouter);
 
   app.get('/api/health', (_req, res) => {
     res.json({ status: 'ok', companyRoot: COMPANY_ROOT });

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

@@ -37,6 +37,10 @@ export interface AgentConfig {
   onTurnComplete?: (turn: number) => void;
   /** Trace: emitted when system prompt is assembled */
   onPromptAssembled?: (systemPrompt: string, userTask: string) => void;
+  /** Supervision: abort a running session */
+  onAbortSession?: (sessionId: string) => boolean;
+  /** Supervision: amend a running session with new instructions */
+  onAmendSession?: (sessionId: string, instruction: string) => boolean;
 }
 
 export interface AgentResult {
@@ -51,19 +55,48 @@ export interface AgentResult {
 
 /**
  * Compress older messages to reduce token usage.
- * Strategy: Keep first 2 messages (initial task) and last 4 messages (recent context).
- * Middle messages: truncate long tool_result content, collapse text blocks.
+ *
+ * SV-9 Enhancement: Zone-based compression for supervision sessions.
+ * - Zone A (pinned): first 2 messages (system prompt + original task + plan) — never compress
+ * - Zone B (rolling): middle messages — heartbeat ticks get aggressive compression
+ * - Zone C (recent): last 4 messages — preserve for LLM context
+ *
+ * Heartbeat-specific: consecutive quiet ticks are merged into a single line.
  */
 function compressMessages(messages: LLMMessage[]): void {
   if (messages.length <= 6) return;
 
-  // Keep first 2 (task setup) and last 4 (recent context)
+  // Zone A: first 2, Zone C: last 4
   const keepHead = 2;
   const keepTail = 4;
   const compressRange = messages.slice(keepHead, messages.length - keepTail);
 
-  for (const msg of compressRange) {
+  // Track consecutive quiet heartbeat ticks for merging
+  let quietTickStart = -1;
+  let quietTickCount = 0;
+
+  for (let idx = 0; idx < compressRange.length; idx++) {
+    const msg = compressRange[idx];
+
     if (typeof msg.content === 'string') {
+      // Check if this is a heartbeat quiet tick result
+      const isQuietTick = msg.content.includes('sessions progressing normally') && msg.content.includes('No anomalies');
+
+      if (isQuietTick) {
+        quietTickCount++;
+        if (quietTickStart === -1) quietTickStart = idx;
+
+        // Merge consecutive quiet ticks
+        if (quietTickCount > 1) {
+          msg.content = `[Quiet ticks merged: ${quietTickCount} ticks, no anomalies]`;
+        }
+        continue;
+      }
+
+      // Reset quiet tick counter on non-quiet content
+      quietTickStart = -1;
+      quietTickCount = 0;
+
       // Truncate long text content
       if (msg.content.length > 500) {
         msg.content = msg.content.slice(0, 300) + '\n\n[... compressed ...]';
@@ -73,8 +106,13 @@ function compressMessages(messages: LLMMessage[]): void {
         const block = msg.content[i] as Record<string, unknown>;
         if (block.type === 'tool_result') {
           const content = typeof block.content === 'string' ? block.content : '';
-          if (content.length > 300) {
-            block.content = content.slice(0, 200) + '\n[... compressed, was ' + content.length + ' chars]';
+
+          // Heartbeat digest results: compress more aggressively
+          const isDigest = content.includes('Supervision Digest') || content.includes('sessions progressing normally');
+          const maxLen = isDigest ? 150 : 300;
+
+          if (content.length > maxLen) {
+            block.content = content.slice(0, maxLen - 50) + '\n[... compressed, was ' + content.length + ' chars]';
           }
         } else if (block.type === 'text' && typeof block.text === 'string' && block.text.length > 500) {
           block.text = (block.text as string).slice(0, 300) + '\n[... compressed ...]';
@@ -132,7 +170,9 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
   // 2. Determine tools
   const subordinates = getSubordinates(orgTree, roleId);
   const hasBash = !readOnly && !!config.codeRoot;
-  const tools = getToolsForRole(subordinates.length > 0, readOnly, hasBash);
+  const node = orgTree.nodes.get(roleId);
+  const heartbeatEnabled = node?.heartbeat?.enabled === true && subordinates.length > 0;
+  const tools = getToolsForRole(subordinates.length > 0, readOnly, hasBash, heartbeatEnabled);
 
   // 3. Set up tool executor
   const toolExecOptions: ToolExecutorOptions = {
@@ -140,7 +180,10 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
     roleId,
     orgTree,
     codeRoot: config.codeRoot,
+    sessionId: config.sessionId,
     onToolExec,
+    onAbortSession: config.onAbortSession,
+    onAmendSession: config.onAmendSession,
     onDispatch: async (targetRoleId: string, subTask: string) => {
       // Recursive dispatch — validate, then run sub-agent
       const authResult = validateDispatch(orgTree, roleId, targetRoleId);
@@ -318,9 +361,9 @@ export async function runAgentLoop(config: AgentConfig): Promise<AgentResult> {
     );
 
     // EG-004: Parallel tool execution for independent tools
-    // dispatch/consult run sequentially (recursive agent calls)
+    // dispatch/consult/heartbeat run sequentially (recursive agent calls / blocking)
     // All other tools run in parallel via Promise.all()
-    const sequentialTools = new Set(['dispatch', 'consult']);
+    const sequentialTools = new Set(['dispatch', 'consult', 'heartbeat_watch']);
     const parallelCalls = toolCalls.filter(tc => !sequentialTools.has(tc.name));
     const sequentialCalls = toolCalls.filter(tc => sequentialTools.has(tc.name));
 

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

@@ -132,6 +132,12 @@ Use the code repository path for all source code work (reading, writing, buildin
     subordinates = subordinates.filter(id => options.targetRoles!.includes(id));
   }
 
+  // Supervision prompt (SV-11, SV-12: C-Level heartbeat mode)
+  const heartbeatEnabled = node.heartbeat?.enabled === true;
+  if (heartbeatEnabled && subordinates.length > 0) {
+    sections.push(buildSupervisionSection(node));
+  }
+
   // Dispatch 도구 안내 (하위 Role이 있는 경우)
   if (subordinates.length > 0) {
     sections.push(buildDispatchSection(orgTree, roleId, subordinates, options?.teamStatus));
@@ -697,6 +703,59 @@ Your final report MUST include a **Change Summary** with files changed and commi
   return section;
 }
 
+function buildSupervisionSection(node: OrgNode): string {
+  const hb = node.heartbeat ?? { enabled: true, intervalSec: 120, maxTicks: 60 };
+  return `# Supervision Mode (Heartbeat)
+
+⛔ **When you dispatch subordinates, you MUST enter supervision mode using heartbeat_watch.**
+⛔ **Do NOT use sleep+curl polling. heartbeat_watch blocks server-side at zero cost.**
+
+## Supervision Protocol
+
+1. **Dispatch** subordinates with clear task descriptions
+2. **Call heartbeat_watch** with the returned session IDs:
+   \`heartbeat_watch(sessionIds=[...], durationSec=${hb.intervalSec})\`
+3. **Analyze the digest** against your plan:
+   - On track → call heartbeat_watch again (keep watching)
+   - Off track → \`amend_session(sessionId, instruction)\` to course-correct
+   - Seriously wrong → \`abort_session(sessionId)\` + re-dispatch with different instructions
+   - Need peer input → \`consult(peer_role_id, question)\`
+   - All done → compile results and report to your superior
+4. **Repeat** heartbeat_watch until all subordinates complete
+
+## Available Supervision Tools
+
+| Tool | When to Use |
+|------|-------------|
+| \`heartbeat_watch\` | Watch subordinate sessions (blocks ${hb.intervalSec}s, $0 LLM cost) |
+| \`amend_session\` | Inject new instructions into a running session |
+| \`abort_session\` | Kill a session that's going wrong |
+| \`consult\` | Ask a peer C-Level for their perspective |
+
+## Digest Response
+
+heartbeat_watch returns a digest with:
+- **Significance score** (0-10): How much attention this tick needs
+- **Anomalies**: Errors, stalls (3min+), sessions awaiting input
+- **Per-session activity**: What each subordinate has been doing
+- **Peer activity** (if peers are also in supervision mode)
+
+Quiet ticks (score 0-1) return a single line: "All N sessions progressing normally."
+
+## Budget
+
+- Max ticks: ${hb.maxTicks} (${Math.round(hb.maxTicks * hb.intervalSec / 60)} minutes total)
+- Quiet tick cost: ~$0.001 (minimal LLM analysis)
+- Alert tick cost: ~$0.02-0.05 (intervention decision)
+
+## ⛔ Anti-Patterns
+
+- ❌ Using \`bash_execute\` with sleep/curl to poll — use heartbeat_watch instead
+- ❌ Calling \`--check\` in a loop — heartbeat_watch handles this automatically
+- ❌ Ignoring digest anomalies — always address errors and stalls
+- ❌ Not re-watching after a quiet tick — keep the loop going until all done`;
+}
+
 function buildConsultSection(orgTree: OrgTree, roleId: string): string | null {
   // Build list of roles this agent can consult
   const consultable: string[] = [];

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

@@ -21,6 +21,12 @@ export interface RoleSource {
   upstream_version?: string;
 }
 
+export interface HeartbeatConfig {
+  enabled: boolean;
+  intervalSec: number;   // default 120
+  maxTicks: number;      // default 60
+}
+
 export interface OrgNode {
   id: string;
   name: string;
@@ -34,6 +40,7 @@ export interface OrgNode {
   skills?: string[];
   model?: string;
   source?: RoleSource;
+  heartbeat?: HeartbeatConfig;
 }
 
 export interface OrgTree {
@@ -69,6 +76,11 @@ interface RawRoleYaml {
     forked_at?: string;
     upstream_version?: string;
   };
+  heartbeat?: {
+    enabled?: boolean;
+    intervalSec?: number;
+    maxTicks?: number;
+  };
 }
 
 /* ─── Build ──────────────────────────────────── */
@@ -128,6 +140,11 @@ export function buildOrgTree(companyRoot: string): OrgTree {
           forked_at: raw.source.forked_at,
           upstream_version: raw.source.upstream_version,
         } : undefined,
+        heartbeat: raw.heartbeat ? {
+          enabled: raw.heartbeat.enabled ?? false,
+          intervalSec: raw.heartbeat.intervalSec ?? 120,
+          maxTicks: raw.heartbeat.maxTicks ?? 60,
+        } : undefined,
       };
       tree.nodes.set(node.id, node);
     } catch {

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

@@ -249,6 +249,152 @@ log(f'')
 log(f'Poll every 10s until status is DONE.')
 `;
 
+/* ─── Supervision Bridge Script (Python3) — SV-14 ────── */
+
+const SUPERVISION_SCRIPT = `#!/usr/bin/env python3
+"""supervision-bridge: C-Level이 부하 세션을 감시하는 브릿지 스크립트.
+
+사용법:
+  supervision watch ses-001,ses-002 --duration 120    — Long-poll watch (blocking)
+  supervision peers --wave xxx --role cto              — Peer session discovery
+  supervision abort ses-001 --reason "Wrong direction" — Abort session
+  supervision amend ses-001 "New instructions here"    — Amend session
+
+환경변수:
+  DISPATCH_API_URL    — API 서버 URL (default: http://localhost:3001)
+"""
+import sys, os, json, urllib.request, urllib.error
+sys.stdout.reconfigure(line_buffering=True)
+
+api = os.environ.get('DISPATCH_API_URL', 'http://localhost:3001')
+
+def log(msg):
+    print(msg, flush=True)
+
+if len(sys.argv) < 2:
+    log('Usage: supervision <watch|peers|abort|amend> [args...]')
+    sys.exit(1)
+
+cmd = sys.argv[1]
+
+if cmd == 'watch':
+    sessions = sys.argv[2] if len(sys.argv) > 2 else ''
+    duration = '120'
+    alert_on = 'msg:done,msg:error'
+    i = 3
+    while i < len(sys.argv):
+        if sys.argv[i] == '--duration' and i + 1 < len(sys.argv):
+            duration = sys.argv[i + 1]
+            i += 2
+        elif sys.argv[i] == '--alert-on' and i + 1 < len(sys.argv):
+            alert_on = sys.argv[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    if not sessions:
+        log('Error: session IDs required (comma-separated)')
+        sys.exit(1)
+
+    url = f'{api}/api/supervision/watch?sessions={sessions}&duration={duration}&alertOn={alert_on}'
+    try:
+        resp = json.loads(urllib.request.urlopen(url, timeout=int(duration) + 10).read())
+        log(resp.get('text', '(no digest)'))
+        if resp.get('anomalies'):
+            log(f'\\nAnomalies: {len(resp["anomalies"])}')
+            for a in resp['anomalies']:
+                log(f'  [{a["type"]}] {a["message"]}')
+    except Exception as e:
+        log(f'ERROR: {e}')
+    sys.exit(0)
+
+elif cmd == 'peers':
+    wave_id = ''
+    role_id = ''
+    i = 2
+    while i < len(sys.argv):
+        if sys.argv[i] == '--wave' and i + 1 < len(sys.argv):
+            wave_id = sys.argv[i + 1]
+            i += 2
+        elif sys.argv[i] == '--role' and i + 1 < len(sys.argv):
+            role_id = sys.argv[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    if not wave_id or not role_id:
+        log('Usage: supervision peers --wave <waveId> --role <roleId>')
+        sys.exit(1)
+
+    try:
+        url = f'{api}/api/supervision/peers?waveId={wave_id}&roleId={role_id}'
+        resp = json.loads(urllib.request.urlopen(url, timeout=10).read())
+        peers = resp.get('peers', [])
+        if not peers:
+            log('No peer C-Level sessions found in this wave.')
+        else:
+            for p in peers:
+                log(f'[{p["roleId"]}] {p["sessionId"]} — {p["status"]} — {p["task"][:80]}')
+    except Exception as e:
+        log(f'ERROR: {e}')
+    sys.exit(0)
+
+elif cmd == 'abort':
+    session_id = sys.argv[2] if len(sys.argv) > 2 else ''
+    reason = 'Aborted by supervisor'
+    i = 3
+    while i < len(sys.argv):
+        if sys.argv[i] == '--reason' and i + 1 < len(sys.argv):
+            reason = sys.argv[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    if not session_id:
+        log('Usage: supervision abort <sessionId> [--reason "..."]')
+        sys.exit(1)
+
+    try:
+        body = json.dumps({'sessionId': session_id, 'reason': reason}).encode()
+        req = urllib.request.Request(f'{api}/api/jobs/{session_id}', method='DELETE')
+        urllib.request.urlopen(req, timeout=10)
+        log(f'Session {session_id} aborted. Reason: {reason}')
+    except Exception as e:
+        log(f'ERROR: {e}')
+    sys.exit(0)
+
+elif cmd == 'amend':
+    session_id = sys.argv[2] if len(sys.argv) > 2 else ''
+    instruction = ' '.join(sys.argv[3:]) if len(sys.argv) > 3 else ''
+
+    if not session_id or not instruction:
+        log('Usage: supervision amend <sessionId> "<instruction>"')
+        sys.exit(1)
+
+    # Amend uses continue-session with amended context
+    body = json.dumps({
+        'response': f'[SUPERVISION AMENDMENT] {instruction}',
+        'responderRole': os.environ.get('DISPATCH_SOURCE_ROLE', 'ceo'),
+    }).encode()
+
+    try:
+        req = urllib.request.Request(
+            f'{api}/api/exec/session/{session_id}/message',
+            body,
+            {'Content-Type': 'application/json'},
+        )
+        resp = json.loads(urllib.request.urlopen(req, timeout=10).read())
+        log(f'Session {session_id} amended with new instructions.')
+    except Exception as e:
+        log(f'ERROR: {e}')
+    sys.exit(0)
+
+else:
+    log(f'Unknown command: {cmd}')
+    log('Usage: supervision <watch|peers|abort|amend> [args...]')
+    sys.exit(1)
+`;
+
 /* ─── Claude CLI Runner ──────────────────────── */
 
 /**
@@ -303,6 +449,12 @@ export class ClaudeCliRunner implements ExecutionRunner {
     const consultScript = path.join(tmpDir, `consult-${roleId}-${Date.now()}.py`);
     fs.writeFileSync(consultScript, CONSULT_SCRIPT, { mode: 0o755 });
 
+    // Supervision Bridge — for C-Level roles with subordinates + heartbeat enabled
+    const supervisionScript = path.join(tmpDir, `supervision-${roleId}-${Date.now()}.py`);
+    if (subordinates.length > 0) {
+      fs.writeFileSync(supervisionScript, SUPERVISION_SCRIPT, { mode: 0o755 });
+    }
+
     // 5. Playwright MCP 설정 — 각 runner 인스턴스가 독립 브라우저 사용
     const runnerOutputDir = path.join(tmpDir, `playwright-${roleId}-${Date.now()}`);
     fs.mkdirSync(runnerOutputDir, { recursive: true });
@@ -361,6 +513,9 @@ export class ClaudeCliRunner implements ExecutionRunner {
     cleanEnv.DISPATCH_CMD = dispatchScript;
     cleanEnv.CONSULT_CMD = consultScript;
     cleanEnv.CONSULT_SOURCE_ROLE = roleId;
+    if (subordinates.length > 0) {
+      cleanEnv.SUPERVISION_CMD = supervisionScript;
+    }
 
     const modelName = config.model ?? 'claude-sonnet-4-5';
     // Use codeRoot as cwd — auto-creates ../{name}-code/ if not configured
@@ -499,6 +654,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.unlinkSync(supervisionScript); } catch { /* ignore */ }
         try { fs.rmSync(runnerOutputDir, { recursive: true, force: true }); } catch { /* ignore */ }
 
         // 비정상 종료 시에도 결과 반환 (output이 있을 수 있으므로)
@@ -517,6 +673,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.unlinkSync(supervisionScript); } catch { /* ignore */ }
         try { fs.rmSync(runnerOutputDir, { recursive: true, force: true }); } catch { /* ignore */ }
         reject(err);
       });

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

@@ -48,6 +48,8 @@ export class DirectApiRunner implements ExecutionRunner {
       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,

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

@@ -45,6 +45,10 @@ export interface RunnerConfig {
   codeRoot?: string;
   /** PSM-004: Environment variables to inject (e.g., port assignments) */
   env?: Record<string, 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 ───────────────────────────────── */

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

@@ -106,6 +106,54 @@ export const BASH_TOOL: ToolDefinition = {
   },
 };
 
+/**
+ * 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)',
+        default: ['msg:done', 'msg:error'],
+      },
+    },
+    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에게 제공 (동료/상관/부하에게 질문)
  */
@@ -124,8 +172,9 @@ export const CONSULT_TOOL: ToolDefinition = {
 
 /**
  * Role에 따른 도구 목록 반환
+ * @param heartbeatEnabled - C-Level supervision mode enabled (provides heartbeat_watch, amend_session, abort_session)
  */
-export function getToolsForRole(hasSubordinates: boolean, readOnly: boolean, hasBash = false): ToolDefinition[] {
+export function getToolsForRole(hasSubordinates: boolean, readOnly: boolean, hasBash = false, heartbeatEnabled = false): ToolDefinition[] {
   if (readOnly) {
     return [...READ_TOOLS];
   }
@@ -138,6 +187,11 @@ export function getToolsForRole(hasSubordinates: boolean, readOnly: boolean, has
 
   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;