heyio 1.13.0 → 3.0.1

package/src/squad/manager.ts

@@ -0,0 +1,337 @@
+import { AUTONOMY_TIERS, type AutonomyConfig, type Squad, type SquadMember } from '@io/shared';
+import type { AutonomyTier } from '@io/shared';
+import { createChildLogger } from '../logging/logger.js';
+import { getDatabase } from '../store/db.js';
+import { Agent, type AgentConfig } from './agent.js';
+import { getEventBus } from './event-bus.js';
+import { type SkillDefinition, parseSkillContent, parseSkillFile } from './skill-parser.js';
+
+const logger = () => createChildLogger('squad-manager');
+
+// Active squads keyed by squad ID
+const activeSquads = new Map<string, SquadRuntime>();
+
+export interface SquadRuntime {
+	squad: Squad;
+	members: Map<string, Agent>; // keyed by role
+	skills: Map<string, SkillDefinition>; // keyed by role
+}
+
+/** Create a new squad in the database and return it */
+export async function createSquad(params: {
+	name: string;
+	projectPath: string;
+	repoUrl?: string;
+	universe?: string;
+	autonomyTier?: AutonomyTier;
+}): Promise<Squad> {
+	const db = getDatabase();
+	const id = crypto.randomUUID();
+	const tier = params.autonomyTier ?? 'medium';
+	const autonomyConfig = AUTONOMY_TIERS[tier];
+
+	await db.execute({
+		sql: `INSERT INTO squads (id, name, project_path, repo_url, universe, autonomy_tier, autonomy_config, status)
+		      VALUES (?, ?, ?, ?, ?, ?, ?, 'active')`,
+		args: [
+			id,
+			params.name,
+			params.projectPath,
+			params.repoUrl ?? null,
+			params.universe ?? null,
+			tier,
+			JSON.stringify(autonomyConfig),
+		],
+	});
+
+	const squad: Squad = {
+		id,
+		name: params.name,
+		projectPath: params.projectPath,
+		repoUrl: params.repoUrl,
+		universe: params.universe,
+		autonomyTier: tier,
+		autonomyConfig,
+		status: 'active',
+		createdAt: new Date(),
+	};
+
+	await getEventBus().emit({
+		id: crypto.randomUUID(),
+		timestamp: new Date(),
+		type: 'squad:created',
+		squadId: id,
+		squadName: params.name,
+		data: { projectPath: params.projectPath, tier },
+	});
+
+	logger().info({ squadId: id, name: params.name }, 'Squad created');
+	return squad;
+}
+
+/** Add a member to a squad */
+export async function addMember(params: {
+	squadId: string;
+	skill: SkillDefinition;
+	displayName: string;
+	persona?: string;
+	isVetoMember?: boolean;
+}): Promise<SquadMember> {
+	const db = getDatabase();
+	const id = crypto.randomUUID();
+
+	await db.execute({
+		sql: `INSERT INTO squad_members (id, squad_id, display_name, role_name, persona, skill_file_path, tools_allowed, is_veto_member, status)
+		      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active')`,
+		args: [
+			id,
+			params.squadId,
+			params.displayName,
+			params.skill.role,
+			params.persona ?? null,
+			params.skill.filePath,
+			JSON.stringify(params.skill.tools),
+			params.isVetoMember ? 1 : 0,
+		],
+	});
+
+	const member: SquadMember = {
+		id,
+		squadId: params.squadId,
+		displayName: params.displayName,
+		roleName: params.skill.role,
+		persona: params.persona,
+		skillFilePath: params.skill.filePath,
+		toolsAllowed: params.skill.tools,
+		isVetoMember: params.isVetoMember ?? false,
+		status: 'active',
+		createdAt: new Date(),
+	};
+
+	return member;
+}
+
+/** List all squads */
+export async function listSquads(): Promise<Squad[]> {
+	const db = getDatabase();
+	const result = await db.execute("SELECT * FROM squads WHERE status = 'active'");
+
+	return result.rows.map((row) => ({
+		id: row.id as string,
+		name: row.name as string,
+		projectPath: row.project_path as string,
+		repoUrl: (row.repo_url as string) || undefined,
+		universe: (row.universe as string) || undefined,
+		autonomyTier: row.autonomy_tier as AutonomyTier,
+		autonomyConfig: JSON.parse((row.autonomy_config as string) || '{}') as AutonomyConfig,
+		status: row.status as Squad['status'],
+		createdAt: new Date(row.created_at as string),
+	}));
+}
+
+/** Get a squad by name */
+export async function getSquadByName(name: string): Promise<Squad | null> {
+	const db = getDatabase();
+	const result = await db.execute({
+		sql: "SELECT * FROM squads WHERE name = ? AND status = 'active'",
+		args: [name],
+	});
+
+	if (result.rows.length === 0) return null;
+	const row = result.rows[0];
+
+	return {
+		id: row.id as string,
+		name: row.name as string,
+		projectPath: row.project_path as string,
+		repoUrl: (row.repo_url as string) || undefined,
+		universe: (row.universe as string) || undefined,
+		autonomyTier: row.autonomy_tier as AutonomyTier,
+		autonomyConfig: JSON.parse((row.autonomy_config as string) || '{}') as AutonomyConfig,
+		status: row.status as Squad['status'],
+		createdAt: new Date(row.created_at as string),
+	};
+}
+
+/** Get squad members */
+export async function getSquadMembers(squadId: string): Promise<SquadMember[]> {
+	const db = getDatabase();
+	const result = await db.execute({
+		sql: "SELECT * FROM squad_members WHERE squad_id = ? AND status = 'active'",
+		args: [squadId],
+	});
+
+	return result.rows.map((row) => ({
+		id: row.id as string,
+		squadId: row.squad_id as string,
+		displayName: (row.display_name as string) || (row.role_name as string),
+		roleName: row.role_name as string,
+		persona: (row.persona as string) || undefined,
+		skillFilePath: (row.skill_file_path as string) || undefined,
+		toolsAllowed: JSON.parse((row.tools_allowed as string) || '[]') as string[],
+		isVetoMember: Boolean(row.is_veto_member),
+		status: row.status as SquadMember['status'],
+		createdAt: new Date(row.created_at as string),
+	}));
+}
+
+/** Disband a squad */
+export async function disbandSquad(squadId: string): Promise<void> {
+	const db = getDatabase();
+	await db.execute({
+		sql: "UPDATE squads SET status = 'disbanded' WHERE id = ?",
+		args: [squadId],
+	});
+	await db.execute({
+		sql: "UPDATE squad_members SET status = 'retired' WHERE squad_id = ?",
+		args: [squadId],
+	});
+
+	// Destroy any running agents
+	const runtime = activeSquads.get(squadId);
+	if (runtime) {
+		for (const agent of runtime.members.values()) {
+			await agent.destroy().catch(() => {});
+		}
+		activeSquads.delete(squadId);
+	}
+
+	await getEventBus().emit({
+		id: crypto.randomUUID(),
+		timestamp: new Date(),
+		type: 'squad:disbanded',
+		squadId,
+		squadName: '',
+	});
+
+	logger().info({ squadId }, 'Squad disbanded');
+}
+
+/** Retheme a squad with a new universe — updates display names and personas */
+export async function rethemeSquad(
+	squadId: string,
+	newUniverse: string,
+	assignments: { role: string; displayName: string; persona: string }[],
+): Promise<void> {
+	const db = getDatabase();
+
+	// Update squad universe
+	await db.execute({
+		sql: 'UPDATE squads SET universe = ? WHERE id = ?',
+		args: [newUniverse, squadId],
+	});
+
+	// Update each member
+	for (const assignment of assignments) {
+		await db.execute({
+			sql: 'UPDATE squad_members SET display_name = ?, persona = ? WHERE squad_id = ? AND role_name = ?',
+			args: [assignment.displayName, assignment.persona, squadId, assignment.role],
+		});
+	}
+
+	// If squad is running, destroy and reboot agents
+	const runtime = activeSquads.get(squadId);
+	if (runtime) {
+		for (const agent of runtime.members.values()) {
+			await agent.destroy().catch(() => {});
+		}
+		activeSquads.delete(squadId);
+
+		// Reload squad data and reboot
+		const squad = await getSquadById(squadId);
+		if (squad) {
+			await bootSquad(squad);
+		}
+	}
+
+	logger().info({ squadId, universe: newUniverse }, 'Squad rethemed');
+}
+
+/** Get squad by ID */
+export async function getSquadById(squadId: string): Promise<Squad | null> {
+	const db = getDatabase();
+	const result = await db.execute({
+		sql: 'SELECT * FROM squads WHERE id = ?',
+		args: [squadId],
+	});
+
+	if (result.rows.length === 0) return null;
+	const row = result.rows[0];
+
+	return {
+		id: row.id as string,
+		name: row.name as string,
+		projectPath: row.project_path as string,
+		repoUrl: (row.repo_url as string) || undefined,
+		universe: (row.universe as string) || undefined,
+		autonomyTier: row.autonomy_tier as AutonomyTier,
+		autonomyConfig: JSON.parse((row.autonomy_config as string) || '{}') as AutonomyConfig,
+		status: row.status as Squad['status'],
+		createdAt: new Date(row.created_at as string),
+	};
+}
+
+/** Boot a squad's agents (creates sessions for each member) */
+export async function bootSquad(squad: Squad): Promise<SquadRuntime> {
+	const members = await getSquadMembers(squad.id);
+	const runtime: SquadRuntime = {
+		squad,
+		members: new Map(),
+		skills: new Map(),
+	};
+
+	const squadContext = `Project: ${squad.name}\nPath: ${squad.projectPath}${squad.repoUrl ? `\nRepo: ${squad.repoUrl}` : ''}`;
+
+	for (const member of members) {
+		let skill: SkillDefinition;
+		if (member.skillFilePath) {
+			skill = parseSkillFile(member.skillFilePath);
+		} else {
+			// Fallback: generate a minimal skill
+			skill = parseSkillContent(
+				`---\nrole: ${member.roleName}\ntools: []\nveto: false\n---\nYou are the ${member.roleName}.`,
+			);
+		}
+
+		runtime.skills.set(member.roleName, skill);
+
+		const agent = new Agent({
+			skill,
+			squadId: squad.id,
+			squadName: squad.name,
+			model: 'claude-opus-4.6',
+			identity: {
+				displayName: member.displayName,
+				persona: member.persona,
+				universe: squad.universe,
+			},
+		});
+
+		await agent.init(squadContext);
+		runtime.members.set(member.roleName, agent);
+	}
+
+	activeSquads.set(squad.id, runtime);
+	logger().info({ squadId: squad.id, memberCount: members.length }, 'Squad booted');
+	return runtime;
+}
+
+/** Get a running squad's runtime */
+export function getSquadRuntime(squadId: string): SquadRuntime | undefined {
+	return activeSquads.get(squadId);
+}
+
+/** Delegate a message to a squad's team lead */
+export async function delegateToSquad(squadId: string, message: string): Promise<string> {
+	const runtime = activeSquads.get(squadId);
+	if (!runtime) {
+		throw new Error(`Squad ${squadId} is not running`);
+	}
+
+	const teamLead = runtime.members.get('team-lead');
+	if (!teamLead) {
+		throw new Error(`Squad ${squadId} has no team lead`);
+	}
+
+	return teamLead.send(message);
+}

package/src/squad/name-generator.ts

@@ -0,0 +1,135 @@
+import { getClient } from '../copilot/client.js';
+import { createChildLogger } from '../logging/logger.js';
+
+const logger = () => createChildLogger('name-generator');
+
+export interface NameAssignment {
+	role: string;
+	displayName: string;
+	persona: string;
+}
+
+export interface GeneratedNames {
+	universe: string;
+	assignments: NameAssignment[];
+}
+
+const NAME_GENERATION_PROMPT = `You are a creative naming assistant. Your job is to assign pop-culture character names to a team of AI agents based on their technical roles.
+
+Rules:
+- Each character name must be UNIQUE within the team
+- Match character personalities to the technical role's nature (e.g. a methodical character for QA, a creative character for frontend)
+- The persona should be 1-2 sentences describing how this character communicates — their tone, quirks, and style
+- Keep personas fun but professional — they should enhance communication, not distract from technical work
+- Return ONLY valid JSON, no markdown fencing
+
+Respond with this exact JSON structure:
+{
+  "universe": "<the universe name>",
+  "assignments": [
+    { "role": "<technical role>", "displayName": "<character name>", "persona": "<1-2 sentence persona description>" }
+  ]
+}`;
+
+/**
+ * Generate character names and persona blurbs for squad members using the LLM.
+ * If a universe is provided, names come from that universe.
+ * If not, the LLM picks a fun universe on its own.
+ */
+export async function generateSquadNames(
+	roles: string[],
+	universe?: string,
+): Promise<GeneratedNames> {
+	const log = logger();
+
+	const userPrompt = universe
+		? `Assign character names from the "${universe}" universe to these team roles: ${roles.join(', ')}`
+		: `Pick a fun pop-culture universe of your choice and assign character names to these team roles: ${roles.join(', ')}`;
+
+	try {
+		const client = await getClient();
+		const session = await client.createSession({
+			systemMessage: { mode: 'replace' as const, content: NAME_GENERATION_PROMPT },
+		});
+
+		let accumulated = '';
+		const unsubDelta = session.on('assistant.message_delta', (event) => {
+			accumulated += event.data.deltaContent;
+		});
+
+		try {
+			await session.sendAndWait({ prompt: userPrompt }, 60_000);
+		} finally {
+			unsubDelta();
+		}
+
+		// Parse the JSON response
+		const parsed = extractJson(accumulated);
+		if (!parsed || !parsed.universe || !Array.isArray(parsed.assignments)) {
+			throw new Error('Invalid response structure from LLM');
+		}
+
+		// Validate all roles are covered
+		const result: GeneratedNames = {
+			universe: parsed.universe as string,
+			assignments: [],
+		};
+
+		for (const role of roles) {
+			const match = (parsed.assignments as Record<string, string>[]).find(
+				(a) => a.role?.toLowerCase() === role.toLowerCase(),
+			);
+			if (match) {
+				result.assignments.push({
+					role,
+					displayName: match.displayName || match.display_name || role,
+					persona: match.persona || '',
+				});
+			} else {
+				// Role wasn't in LLM response — use role name as fallback
+				result.assignments.push({ role, displayName: role, persona: '' });
+			}
+		}
+
+		log.info({ universe: result.universe, count: result.assignments.length }, 'Names generated');
+		return result;
+	} catch (err) {
+		log.error({ err, roles, universe }, 'Failed to generate names, falling back to role names');
+		return fallback(roles);
+	}
+}
+
+/** Fallback: use role names as display names with no persona */
+function fallback(roles: string[]): GeneratedNames {
+	return {
+		universe: 'none',
+		assignments: roles.map((role) => ({ role, displayName: role, persona: '' })),
+	};
+}
+
+/** Extract JSON from LLM response (handles possible markdown fencing) */
+function extractJson(text: string): Record<string, unknown> | null {
+	try {
+		return JSON.parse(text.trim());
+	} catch {
+		// Try extracting from markdown code fence
+		const match = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+		if (match) {
+			try {
+				return JSON.parse(match[1].trim());
+			} catch {
+				return null;
+			}
+		}
+		// Try finding JSON object in text
+		const braceMatch = text.match(/\{[\s\S]*\}/);
+		if (braceMatch) {
+			try {
+				return JSON.parse(braceMatch[0]);
+			} catch {
+				return null;
+			}
+		}
+		return null;
+	}
+}

package/src/squad/roles/templates.ts

@@ -0,0 +1,104 @@
+/** Built-in SKILL.md templates for core squad roles */
+
+export const TEAM_LEAD_SKILL = `---
+role: team-lead
+tools:
+  - read_file
+  - search_code
+veto: true
+---
+
+# Team Lead
+
+## Identity
+You are the Team Lead — a senior engineering manager and project coordinator.
+
+## Responsibilities
+- Analyze incoming tasks and break them into actionable work items
+- Assign tasks to the appropriate specialist agents
+- Coordinate round-table meetings for complex decisions
+- Review completed work before it becomes a PR
+- Maintain project direction and consistency
+- Report progress and blockers back to the orchestrator
+
+## Boundaries
+- You do NOT write or edit code directly
+- You do NOT run commands
+- You delegate all implementation work to specialists
+- You focus on planning, coordination, and quality assurance
+
+## Communication Style
+- Be concise and structured in task descriptions
+- Include acceptance criteria for every task
+- Reference relevant files and code patterns when assigning work
+`;
+
+export const SCRIBE_SKILL = `---
+role: scribe
+tools:
+  - read_file
+  - edit_file
+veto: false
+---
+
+# Scribe
+
+## Identity
+You are the Scribe — responsible for recording decisions, meeting notes, and project documentation.
+
+## Responsibilities
+- Record all key decisions made during meetings with rationale
+- Maintain a decisions log that all team members can reference
+- Document architectural choices and trade-offs
+- Write clear commit messages and PR descriptions
+- Update project README and docs when changes warrant it
+
+## Boundaries
+- You do NOT make technical decisions — you record them
+- You do NOT modify source code — only documentation files
+- You ask clarifying questions when decisions are ambiguous
+- You ensure decisions are searchable and well-categorized
+
+## Output Format
+Decisions should follow this format:
+- **Decision**: What was decided
+- **Context**: Why this was needed
+- **Rationale**: Why this option was chosen over alternatives
+- **Consequences**: What this means going forward
+`;
+
+export const QA_TESTER_SKILL = `---
+role: qa-tester
+tools:
+  - read_file
+  - edit_file
+  - run_command
+  - search_code
+veto: true
+---
+
+# QA / Test Engineer
+
+## Identity
+You are the QA/Test Engineer — the quality gate for all code changes.
+
+## Responsibilities
+- Write comprehensive tests for new features (unit, integration)
+- Run existing test suites and report failures
+- Review code for edge cases, error handling, and security issues
+- Verify changes don't break existing functionality
+- Block merges that don't meet quality standards
+
+## Boundaries
+- You focus on test code, not feature implementation
+- You veto changes that reduce test coverage or break tests
+- You report issues clearly with reproduction steps
+- You suggest fixes but don't implement production features
+
+## Quality Standards
+- All new code must have corresponding tests
+- No PR should reduce overall test coverage
+- All tests must pass before approval
+- Edge cases (empty inputs, null values, errors) must be covered
+- Async code must have timeout and error handling tests
+`;

package/src/squad/skill-parser.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync } from 'node:fs';
+import matter from 'gray-matter';
+import { getActiveSkillsContent } from '../skills/index.js';
+import { getPageListing, getSquadScopes } from '../wiki/index.js';
+
+export interface SkillDefinition {
+	role: string;
+	tools: string[];
+	veto: boolean;
+	systemPrompt: string;
+	rawMarkdown: string;
+	filePath: string;
+}
+
+interface SkillFrontmatter {
+	role: string;
+	tools?: string[];
+	veto?: boolean;
+}
+
+/**
+ * Parse a SKILL.md file into a structured SkillDefinition.
+ * Format:
+ * ---
+ * role: react-developer
+ * tools:
+ *   - edit_file
+ *   - read_file
+ * veto: false
+ * ---
+ * # Role Name
+ * System prompt markdown content...
+ */
+export function parseSkillFile(filePath: string): SkillDefinition {
+	if (!existsSync(filePath)) {
+		throw new Error(`SKILL.md not found: ${filePath}`);
+	}
+
+	const raw = readFileSync(filePath, 'utf-8');
+	return parseSkillContent(raw, filePath);
+}
+
+/**
+ * Parse SKILL.md content string into a SkillDefinition.
+ */
+export function parseSkillContent(content: string, filePath = '<inline>'): SkillDefinition {
+	const { data, content: body } = matter(content);
+	const frontmatter = data as SkillFrontmatter;
+
+	if (!frontmatter.role) {
+		throw new Error(`SKILL.md missing required 'role' in frontmatter: ${filePath}`);
+	}
+
+	return {
+		role: frontmatter.role,
+		tools: frontmatter.tools ?? [],
+		veto: frontmatter.veto ?? false,
+		systemPrompt: body.trim(),
+		rawMarkdown: content,
+		filePath,
+	};
+}
+
+/**
+ * Compile a SkillDefinition into a full system message string for the LLM.
+ * Injects role identity, boundaries, and tool context.
+ */
+export async function compileSystemPrompt(
+	skill: SkillDefinition,
+	squadContext?: string,
+	squadName?: string,
+	squadId?: string,
+	identity?: { displayName: string; persona?: string; universe?: string },
+): Promise<string> {
+	const parts: string[] = [];
+
+	if (identity?.displayName && identity.displayName !== skill.role) {
+		const intro = `You are ${identity.displayName}${identity.universe ? ` from ${identity.universe}` : ''}, the ${skill.role} agent in an IO squad.`;
+		parts.push(intro);
+		if (identity.persona) {
+			parts.push(identity.persona);
+		}
+	} else {
+		parts.push(`You are the ${skill.role} agent in an IO squad.`);
+	}
+
+	if (squadContext) {
+		parts.push(`\n## Squad Context\n${squadContext}`);
+	}
+
+	parts.push(`\n## Your Role\n${skill.systemPrompt}`);
+
+	if (skill.tools.length > 0) {
+		parts.push(`\n## Allowed Tools\nYou may ONLY use: ${skill.tools.join(', ')}`);
+	}
+
+	if (skill.veto) {
+		parts.push(
+			'\n## Veto Power\nYou have veto power in meetings. Use it when you identify critical issues.',
+		);
+	}
+
+	// Inject wiki page listing so agents know what knowledge is available
+	if (squadName) {
+		const wikiListing = getPageListing(getSquadScopes(squadName));
+		parts.push(
+			`\n## Wiki Knowledge\n${wikiListing}\n\nUse read_wiki to access page content. Use write_wiki to record important project knowledge.`,
+		);
+	}
+
+	// Inject active skills for this squad
+	if (squadId) {
+		const skillsContent = await getActiveSkillsContent('squad', squadId);
+		if (skillsContent) {
+			parts.push(skillsContent);
+		}
+	}
+
+	return parts.join('\n');
+}