tycono-server 0.1.0-beta.0

package/src/shared/types.ts

@@ -0,0 +1,224 @@
+/**
+ * Shared Type Contract — Single Source of Truth (D-014 Session-Centric)
+ *
+ * 이 파일은 API와 Web이 공유하는 모든 상태/이벤트 타입을 정의합니다.
+ * 상태 관련 타입을 추가하거나 변경할 때는 반드시 이 파일을 수정하세요.
+ *
+ * 규칙:
+ * 1. 상태 타입은 여기서만 정의 — api/web에서 재정의 금지
+ * 2. UI-only 상태(waiting, connecting 등)는 별도 섹션에 명시적 분리
+ * 3. 상태 전이는 TRANSITIONS 맵으로 검증 가능
+ *
+ * D-014: Session이 모든 대화의 일급 단위. Job은 내부 런타임 핸들.
+ */
+
+/* ═══════════════════════════════════════════════
+ *  Message — 실행 단위의 핵심 상태 (D-014: 구 Job 대체)
+ * ═══════════════════════════════════════════════ */
+
+/** Message의 실행 상태 — 시스템 전체에서 유일한 정의 */
+export type MessageStatus = 'streaming' | 'done' | 'error' | 'awaiting_input' | 'interrupted';
+
+/** /api/exec/status 등에서 Role 단위로 집계할 때 사용 */
+export type RoleStatus = 'idle' | 'working' | 'awaiting_input' | 'done';
+
+/** MessageStatus → RoleStatus 변환 (유일한 매핑 규칙) */
+export function messageStatusToRoleStatus(status: MessageStatus): RoleStatus {
+  switch (status) {
+    case 'streaming': return 'working';
+    case 'awaiting_input': return 'awaiting_input';
+    case 'done': return 'done';
+    case 'error': return 'done';
+    case 'interrupted': return 'done';
+  }
+}
+
+/** Role이 "활성 상태"인지 판단 — exec/status, Org Chart 등에서 사용 */
+export function isRoleActive(status: RoleStatus): boolean {
+  return status === 'working' || status === 'awaiting_input';
+}
+
+/** Message가 "활성 상태"인지 판단 */
+export function isMessageActive(status: MessageStatus): boolean {
+  return status === 'streaming' || status === 'awaiting_input';
+}
+
+/** Message가 종료 상태인지 판단 */
+export function isMessageTerminal(status: MessageStatus): boolean {
+  return status === 'done' || status === 'error' || status === 'interrupted';
+}
+
+/** 허용된 상태 전이 (from → to[]) */
+export const MESSAGE_TRANSITIONS: Record<MessageStatus, MessageStatus[]> = {
+  streaming:      ['done', 'error', 'awaiting_input', 'interrupted'],
+  awaiting_input: ['streaming', 'done', 'error', 'interrupted'],
+  interrupted:    ['streaming', 'done'],  // re-dispatch 또는 CEO dismiss
+  done:           [],
+  error:          [],
+};
+
+/** 상태 전이 유효성 검증 */
+export function canTransition(from: MessageStatus, to: MessageStatus): boolean {
+  return MESSAGE_TRANSITIONS[from].includes(to);
+}
+
+/* ═══════════════════════════════════════════════
+ *  Activity Events — 실행 이벤트 로그
+ * ═══════════════════════════════════════════════ */
+
+/** 모든 이벤트 타입 — Message.events[]에 기록되는 유일한 어휘 */
+export type ActivityEventType =
+  // Message lifecycle (D-014: 구 job:* → msg:*)
+  | 'msg:start' | 'msg:done' | 'msg:error'
+  | 'msg:awaiting_input' | 'msg:reply'
+  | 'msg:turn-complete'
+  // Execution
+  | 'text' | 'thinking'
+  | 'tool:start' | 'tool:result'
+  // Dispatch (child session)
+  | 'dispatch:start' | 'dispatch:done'
+  // Harness (turn limits)
+  | 'turn:warning' | 'turn:limit'
+  // Knowledge import
+  | 'import:scan' | 'import:process' | 'import:created'
+  // Trace (full prompt/response capture for AI debugging)
+  | 'prompt:assembled' | 'trace:response'
+  // Supervision (C-Level heartbeat)
+  | 'heartbeat:tick' | 'heartbeat:skip'
+  // Other
+  | 'stderr';
+
+export interface ActivityEvent {
+  seq: number;
+  ts: string;
+  type: ActivityEventType;
+  roleId: string;
+  parentSessionId?: string;
+  /** Trace ID — top-level sessionId, inherited by child sessions */
+  traceId?: string;
+  data: Record<string, unknown>;
+}
+
+/* ═══════════════════════════════════════════════
+ *  Session — D-014 통합 세션
+ * ═══════════════════════════════════════════════ */
+
+export type SessionStatus = 'active' | 'closed';
+export type SessionSource = 'chat' | 'wave' | 'dispatch' | 'consult';
+
+/* ═══════════════════════════════════════════════
+ *  Wave — 조직 전파 단위
+ * ═══════════════════════════════════════════════ */
+
+/** Wave JSON에 저장되는 role별 상태 */
+export type WaveRoleStatus = MessageStatus | 'unknown';
+
+/* ═══════════════════════════════════════════════
+ *  Frontend-Only 상태 (UI 전용, 백엔드에는 없음)
+ *  명시적으로 분리하여 혼동 방지
+ * ═══════════════════════════════════════════════ */
+
+/** Wave 노드의 UI 상태 — MessageStatus + UI-only 상태 */
+export type WaveNodeStatus =
+  | MessageStatus              // 'streaming' | 'done' | 'error' | 'awaiting_input' | 'interrupted'
+  | 'waiting'                  // 아직 dispatch 안 됨 (UI 초기 상태)
+  | 'not-dispatched';          // wave 완료 후에도 dispatch 안 된 노드
+
+/** WaveNode가 "활성 상태"인지 판단 — UI-only 상태 포함 */
+export function isWaveNodeActive(status: WaveNodeStatus): boolean {
+  return status === 'streaming' || status === 'awaiting_input';
+}
+
+/** SSE 연결 상태 — 네트워크 레벨, 실행 상태와 무관 */
+export type StreamStatus = 'idle' | 'connecting' | 'streaming' | 'done' | 'error';
+
+/** ActivityEventType → MessageStatus 변환 (wave replay 등에서 사용) */
+export function eventTypeToMessageStatus(eventType: ActivityEventType): MessageStatus | 'unknown' {
+  switch (eventType) {
+    case 'msg:done': return 'done';
+    case 'msg:error': return 'error';
+    case 'msg:awaiting_input': return 'awaiting_input';
+    default: return 'unknown';
+  }
+}
+
+/** TeamStatus — Role별 현재 상태 + 작업 내용 (context-assembler, runner에서 공유) */
+export type TeamStatus = Record<string, { status: RoleStatus; task?: string }>;
+
+/* ═══════════════════════════════════════════════
+ *  Preset — Wave-scoped team configuration
+ * ═══════════════════════════════════════════════ */
+
+/** preset.yaml 스키마 */
+export interface PresetDefinition {
+  /** Spec version (e.g. "preset/v1") */
+  spec: string;
+  /** Unique identifier (directory name) */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Short tagline */
+  tagline?: string;
+  /** Version string */
+  version: string;
+  /** Full description */
+  description?: string;
+  /** Author info */
+  author?: {
+    id: string;
+    name: string;
+    verified?: boolean;
+  };
+  /** Category / classification */
+  category?: string;
+  industry?: string;
+  stage?: string;
+  use_case?: string[];
+  /** Role IDs included in this preset */
+  roles: string[];
+  /** Counts */
+  knowledge_docs?: number;
+  skills_count?: number;
+  /** Pricing */
+  pricing?: {
+    type: 'one-time' | 'subscription';
+    price: number;
+    wave_scoped_tier?: string;
+  };
+  /** Tags for search */
+  tags?: string[];
+  languages?: string[];
+  /** Stats (marketplace) */
+  stats?: {
+    installs: number;
+    rating: number;
+    reviews: number;
+    waves_used: number;
+  };
+  /** Wave-scoped recommendations */
+  wave_scoped?: {
+    recommended_tasks?: string[];
+    task_keywords?: string[];
+    avg_wave_duration?: string;
+    complexity?: string;
+  };
+}
+
+/** Loaded preset with resolved path info */
+export interface LoadedPreset {
+  definition: PresetDefinition;
+  /** Absolute path to preset directory (or null for _default) */
+  path: string | null;
+  /** Whether this is the _default preset */
+  isDefault: boolean;
+}
+
+/** Preset summary for TUI display */
+export interface PresetSummary {
+  id: string;
+  name: string;
+  description?: string;
+  rolesCount: number;
+  roles: string[];
+  isDefault: boolean;
+}

package/templates/CLAUDE.md.tmpl

@@ -0,0 +1,239 @@
+# Company Rules
+
+> Powered by [Tycono](https://tycono.ai) — AI Company Operating Platform
+
+---
+
+## Task Routing
+
+| Task | Read First | Role |
+|------|-----------|------|
+| Product planning | `projects/` | PM |
+| Technical design | `architecture/` | CTO |
+| Implementation | `projects/*/tasks.md` | Engineer |
+| UI/UX Design | `projects/*/design/` | Designer |
+| Testing/QA | `projects/*/tasks.md` | QA |
+| E2E Testing | `e2e-experiments/tui-e2e-testcases.md` | QA |
+| Operations | `marketing/` | PM |
+| Business/Revenue | `company.md` | CBO |
+| Domain knowledge | `knowledge.md` | CBO |
+
+---
+
+## AKB Core Concepts
+
+> **AKB** = A file-based knowledge system where AI uses **search (Grep/Glob)** to find and **contextual links** to navigate
+>
+> Full reference: `methodologies/agentic-knowledge-base.md`
+
+| Layer | Role | AI Usage |
+|-------|------|----------|
+| **Root** (CLAUDE.md) | Minimal routing | Auto-injected as system prompt |
+| **Hub** ({folder}.md) | TOC + tool/guide references | **Check before starting work** |
+| **Node** (*.md) | Actual information | Search directly via Grep/Glob |
+
+---
+
+## AI Work Rules
+
+### The Loop (Work Cycle)
+
+Every task follows this cycle. Implementing without completing the cycle is only half the job.
+
+| Step | Action | Why |
+|------|--------|-----|
+| ① Knowledge | Check/research related docs | Without context, direction goes wrong |
+| ② Task | Define task from docs | Without requirements, you'll rework |
+| ③ Implement | Execute the actual work | Value creation |
+| ④ Knowledge Update | Update docs with new insights | Prevents knowledge decay |
+| ⑤ Task Update | Update task status, check next work | Ensures continuity |
+
+**C-Level**: Execute The Loop autonomously — decompose tasks, analyze dependencies, dispatch independent tasks in parallel, collect results.
+**Member**: After implementation, always complete steps ④ and ⑤.
+
+### Hub-First Principle
+
+> ⛔ **Read the relevant Hub document before starting any work.**
+
+Check the Task Routing table above to find the right "Read First" path.
+Every folder has a Hub file (`{folder-name}.md`) as its entry point.
+Read the Hub's existing tools/scripts/guides before starting work.
+
+### Skill Check Principle
+
+> ⛔ **If `.claude/skills/{role-id}/SKILL.md` exists, you MUST read it.**
+
+Skill files define the tools, commands, and guides for each Role.
+Working without reading skills means missing existing tools and starting from scratch.
+
+### Custom Rules (CRITICAL)
+
+> ⛔ **Before starting work, check if `custom-rules.md` exists and read it.**
+> This file contains company-specific rules, constraints, and processes.
+> If the file doesn't exist, ignore this section.
+
+### Git Rules
+
+- Source code changes: feature branch → PR → merge
+- Direct push to main is prohibited
+
+### Knowledge Gate
+
+> **Before creating a new document, search existing docs first.**
+
+```
+1. Summarize the insight + 3-5 keywords
+2. Search existing docs with those keywords (grep 3+ terms)
+3. Decide:
+   - Overlap 70%+ -> Add to existing document
+   - Overlap 30-70% -> New doc + cross-link to existing
+   - Overlap <30% -> New document (register in Hub)
+   - Temporary info -> Journal only (no new doc)
+4. Cross-link to related docs
+5. Register in the relevant Hub
+```
+
+### Document Hygiene
+
+| Rule | Description |
+|------|-------------|
+| No orphan docs | Every document must be reachable from a Hub |
+| Hub pattern | Each folder's entry point is `{folder}.md` |
+| Prefer existing | Adding 1 doc = maintenance cost. Strengthen existing > create new |
+| Cross-link | New docs must reference at least 1 related doc |
+| Source attribution | External research must cite source and date |
+
+### Skills
+
+Roles have equipped **Skills** -- modular capability guides in `.claude/skills/`.
+
+- Role-specific skills: `.claude/skills/{role-id}/SKILL.md`
+- Shared skills: `.claude/skills/_shared/{skill-id}/SKILL.md`
+- Each Role's equipped skills are listed in `role.yaml` under `skills:`
+- **Always read SKILL.md before starting work** for that Role
+
+### Agent Dispatch Rules (CRITICAL)
+
+> **Sub-agents (Agent/Task) do NOT automatically receive CLAUDE.md.**
+> **You MUST instruct them to read CLAUDE.md in the first line of the prompt.**
+
+Without the Root (CLAUDE.md), sub-agents skip Hubs and dive straight into code,
+missing existing tools, guides, and constraints.
+
+#### Required Prompt Pattern
+
+Every sub-agent prompt **must include**:
+
+1. Instruction to read CLAUDE.md
+2. **Required skill file paths** for the Role
+
+```
+⛔ AKB Rule: Read CLAUDE.md before starting work.
+Find the relevant Hub from the "Task Routing" table and read it first.
+Check the Hub's existing tools/guides/constraints before exploring code.
+⛔ Read the required skill files below and use the tools/commands defined in them.
+```
+
+#### Role Skill Mapping
+
+| Role | Required Skills (path: `.claude/skills/{name}/SKILL.md`) |
+|------|--------------------------------------------------------|
+| Each Role | `{role-id}` + shared skills listed in `role.yaml` |
+
+> Check each Role's `role.yaml` `skills:` field for the exact list.
+
+### Self-Verification Before Escalation (CRITICAL)
+
+> **Before saying "I can't" or "user action needed", check your own tools/skills first.**
+
+#### Checklist (before reporting inability)
+
+```
+□ 1. Check CLAUDE.md routing table for relevant skills/tools
+□ 2. Glob search .claude/skills/ for related skills
+□ 3. Read the skill and determine if it can solve the problem
+□ 4. Only if all above fail → Report: "Tried X but unable due to [specific reason]"
+```
+
+### Exploration Depth
+
+> **Don't stop at Hubs. Explore detailed documents for thorough understanding.**
+
+| Question Type | Minimum | Additional |
+|--------------|---------|------------|
+| Implementation | Hub | Related Node |
+| Debugging | Hub | Related issues/logs |
+| **Strategy/Design** | Hub | **Design docs, past decisions, architecture details** |
+| **New Feature** | Hub | **Existing implementation patterns, related architecture** |
+
+### Skill Synchronization (CRITICAL)
+
+> **When changing code/processes, update related `.claude/skills/` SKILL.md files too.**
+
+| Change Type | Skill Update |
+|-------------|-------------|
+| API endpoint change | Update API reference |
+| New tool/script added | Add to tool listing |
+| Process change | Update procedure guide |
+| Feature removed | Remove related section |
+
+### AKB Management (CRITICAL)
+
+> **Every Role manages knowledge as part of their work. Don't just code and stop.**
+
+After completing any task, check:
+
+| # | Item | Description |
+|---|------|-------------|
+| 1 | **New knowledge?** | Did this task produce new insights/decisions/analysis? |
+| 2 | **Search existing docs** | Are there related docs already? (grep 3+ keywords) |
+| 3 | **Decide location** | Add to existing doc vs create new (prefer existing) |
+| 4 | **Hub connection** | Is the new/updated doc reachable from a Hub? |
+| 5 | **Cross-link** | Are there mutual references between related docs? |
+| 6 | **Task update** | Is the task status updated? Next work identified? |
+
+---
+
+## Folder Structure
+
+```
+{project}/
+├── knowledge/                ← Tycono world. AI agent's cwd. Git root.
+│   ├── CLAUDE.md             ← Only AI entry point
+│   ├── .claude/skills/       ← Role skill guides
+│   │   ├── _shared/
+│   │   └── {role-id}/SKILL.md
+│   ├── roles/
+│   │   ├── roles.md          ← Hub
+│   │   └── {role-id}/
+│   │       ├── role.yaml
+│   │       ├── profile.md
+│   │       └── journal/
+│   ├── architecture/         ← Hub (technical architecture)
+│   ├── projects/             ← Hub (project tracking)
+│   ├── decisions/            ← CEO decisions
+│   ├── methodologies/        ← Frameworks & principles
+│   ├── presets/              ← Team presets
+│   ├── marketing/            ← Hub (SNS, launch, SEO)
+│   ├── e2e-experiments/      ← Hub (E2E test records)
+│   ├── company.md            ← Company info
+│   ├── custom-rules.md       ← Company custom rules (user owned)
+│   └── knowledge.md          ← Hub (domain knowledge index)
+│
+├── .tycono/                  ← Operational data (outside git)
+│   ├── config.json           ← Engine settings, codeRoots
+│   ├── tycono.db             ← SQLite (conversation history)
+│   ├── preferences.json      ← UI settings
+│   ├── waves/                ← Wave execution logs
+│   ├── sessions/             ← Session state
+│   ├── standup/              ← Daily standups
+│   ├── cost/                 ← Token cost tracking
+│   └── activity-streams/     ← SSE event logs (runtime)
+│
+└── apps/                     ← Code (default monorepo, outside git)
+```
+
+---
+
+<!-- tycono:managed v{{VERSION}} — This file is managed by Tycono. Do not edit manually. -->
+<!-- Company-specific rules go in custom-rules.md (knowledge/ root) -->

package/templates/company.md.tmpl

@@ -0,0 +1,17 @@
+# {{COMPANY_NAME}}
+
+> {{DESCRIPTION}}
+
+## Mission
+
+Define your company's mission here.
+
+## Vision
+
+Define your company's vision here.
+
+## Values
+
+- Value 1
+- Value 2
+- Value 3

package/templates/gitignore.tmpl

@@ -0,0 +1,28 @@
+# Dependencies
+node_modules/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Engine config (contains API keys)
+.tycono/config.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
+
+# Runtime state
+operations/activity/
+operations/sessions/

package/templates/roles.md.tmpl

@@ -0,0 +1,8 @@
+# Roles
+
+> Role directory for {{COMPANY_NAME}}
+
+## Active Roles
+
+| Name | ID | Level | Reports To | Status |
+|------|----|-------|------------|--------|

package/templates/skills/_manifest.json

@@ -0,0 +1,23 @@
+{
+  "version": "1.0.0",
+  "skills": [
+    {
+      "id": "knowledge-gate",
+      "name": "Knowledge Gate",
+      "category": "core",
+      "description": "Knowledge documentation gatekeeper with dynamic domain expert analysis."
+    },
+    {
+      "id": "akb-linter",
+      "name": "AKB Document Linter",
+      "category": "core",
+      "description": "Document hygiene checker that finds AI-confusing documents."
+    },
+    {
+      "id": "agent-browser",
+      "name": "Agent Browser",
+      "category": "core",
+      "description": "Token-efficient browser automation CLI for AI agents."
+    }
+  ]
+}