heyio 0.1.31 → 0.1.33

package/README.md

@@ -12,10 +12,10 @@ A personal AI assistant daemon built on the GitHub Copilot SDK. IO runs 24/7 on
 - **Multi-Interface** — Web UI + Telegram bot + terminal TUI + HTTP API
 - **Web Frontend** — Vue 3 dashboard with chat, squad management, skills, and agent activity views
 - **Persistent Memory** — wiki-based knowledge base stored at `~/.io/wiki/`
-- **Squad System** — persistent project teams that remember decisions, context, and history
+- **Squad System** — persistent project teams with **named specialist agents** themed from 80s pop culture (A-Team, Transformers, ThunderCats, GI Joe, Aliens, Ghostbusters)
 - **Skills** — modular skill system; install from git repos or the [skills.sh](https://skills.sh) registry
 - **Adaptive Sessions** — infinite sessions with automatic context compaction
-- **Worker Agents** — delegated task execution through specialized agent sessions
+- **Named Agent Personas** — each squad agent gets a character persona with personality, dynamic role title, and specialized charter
 - **GitHub Integration** — create, list, view, and comment on issues and PRs via the `github` tool
 - **Smart Model Routing** — automatically selects the best model for each task based on complexity
 - **Self-Updating** — checks for updates and can apply them automatically
@@ -179,14 +179,21 @@ A skill is a directory with a `SKILL.md` file that describes the skill and its t
 
 ## 👥 Squad System
 
-Squads are persistent project teams that IO manages. Each squad:
+Squads are persistent project teams with **named specialist agents**. Each squad:
 
-- Is associated with a specific project or domain
-- Remembers decisions, context, and conversation history
-- Can have multiple specialized agents working together
+- Has an 80s pop culture **universe theme** (A-Team, Transformers, ThunderCats, GI Joe, Aliens, Ghostbusters)
+- Contains dynamically-created **specialist agents** with roles tailored to the project (e.g., "Express API Engineer", "Vue.js Frontend Dev")
+- Each agent is assigned a **character persona** with personality traits that color their work style
+- Remembers decisions, context, and conversation history across sessions
 - Persists across sessions in the SQLite database
 
-IO's orchestrator automatically creates and manages squads based on your conversations.
+### How Squads Work
+
+1. **Create** — `squad_create` assigns a random 80s universe (or user picks one)
+2. **Analyze** — `squad_analyze` scans the project to determine languages, frameworks, and tools
+3. **Build the team** — `squad_add_agent` for each specialist the project needs; characters are drawn from the universe pool
+4. **Delegate** — `squad_delegate` sends tasks to specific agents by character name
+5. **Track** — `squad_task_status` monitors progress and retrieves results
 
 ## 🏗️ Architecture
 
@@ -197,12 +204,12 @@ User → [Web UI / TUI / Telegram / HTTP API]
           ↕           ↕
      Squad Manager   Wiki/Memory
           ↓
-     Worker Agents
+     Named Agents (80s Characters)
 ```
 
 IO is built around the **Copilot SDK** which handles all LLM interactions, including tool calling and context management. The **Orchestrator** manages the primary conversation session with automatic context compaction for infinite-length sessions.
 
-For complex tasks, the orchestrator delegates work to **Worker Agents** — short-lived agent sessions that execute specific tasks and report back.
+For complex tasks, the orchestrator delegates work to **Named Agents** — persistent agent sessions with character personas, specialized roles, and per-agent system prompts. Each agent works autonomously within their squad's project context.
 
 The **Squad System** provides persistent project context, while the **Wiki** serves as a long-term knowledge base that spans all conversations.
 
@@ -252,14 +259,15 @@ src/
 ├── copilot/
 │   ├── client.ts         # CopilotClient singleton
 │   ├── orchestrator.ts   # Main session management
-│   ├── agents.ts         # Worker agent sessions
+│   ├── agents.ts         # Named agent sessions & personas
+│   ├── universes.ts      # 80s universe character data
 │   ├── tools.ts          # Tool definitions
 │   ├── model-router.ts   # Complexity-based model selection
 │   ├── skills.ts         # Skills loader
 │   └── system-message.ts # System prompt builder
 ├── store/
 │   ├── db.ts             # SQLite database
-│   ├── squads.ts         # Squad CRUD
+│   ├── squads.ts         # Squad & agent CRUD
 │   └── tasks.ts          # Agent task tracking
 ├── wiki/
 │   ├── fs.ts             # Wiki filesystem

package/dist/api/server.js

@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
 import express from "express";
 import { config } from "../config.js";
 import { listSkills } from "../copilot/skills.js";
-import { listSquads, createSquad } from "../store/squads.js";
+import { listSquads, createSquad, listSquadAgents } from "../store/squads.js";
 import { getAgentInfo } from "../copilot/agents.js";
 import { IO_VERSION } from "../paths.js";
 import { requireAuth } from "./auth.js";
@@ -86,6 +86,17 @@ export async function startApiServer() {
             res.status(500).json({ error: "Failed to create squad" });
         }
     });
+    api.get("/squads/:slug/agents", (req, res) => {
+        try {
+            const slug = Array.isArray(req.params.slug) ? req.params.slug[0] : req.params.slug;
+            const agents = listSquadAgents(slug);
+            res.json({ agents });
+        }
+        catch (e) {
+            console.error("Error listing squad agents:", e);
+            res.status(500).json({ error: "Failed to list squad agents" });
+        }
+    });
     // Agents endpoints
     api.get("/agents", (_req, res) => {
         try {

package/dist/copilot/agents.js

@@ -6,11 +6,17 @@ import { homedir } from "os";
 import { defineTool, approveAll } from "@github/copilot-sdk";
 import { z } from "zod";
 import { getClient } from "./client.js";
-import { getModelForTask } from "./model-router.js";
-import { getSquad, updateSquadSession, updateSquadStatus, getDecisionsSummary, logDecision, } from "../store/squads.js";
+import { getModelForTask, getModelForTier, classifyComplexity } from "./model-router.js";
+import { getSquad, updateSquadSession, updateSquadStatus, getDecisionsSummary, logDecision, listSquadAgents, getSquadAgent, updateAgentSession, updateAgentStatus, } from "../store/squads.js";
 import { createTask, completeTask, failTask, getActiveTasks, } from "../store/tasks.js";
 import { SESSIONS_DIR } from "../paths.js";
+import { getUniverse } from "./universes.js";
+// Key format: "squadSlug:characterName" for per-agent sessions, "squadSlug" for legacy
 const agentSessions = new Map();
+const agentSessionModels = new Map();
+function agentSessionKey(squadSlug, characterName) {
+    return characterName ? `${squadSlug}:${characterName}` : squadSlug;
+}
 export function getAgentInfo() {
     const activeTasks = getActiveTasks();
     const tasksByAgent = new Map();
@@ -18,34 +24,71 @@ export function getAgentInfo() {
         tasksByAgent.set(task.agent_slug, task.description);
     }
     const agents = [];
-    for (const [slug, _session] of agentSessions) {
-        const squad = getSquad(slug);
-        const currentTask = tasksByAgent.get(slug);
-        let status = "idle";
-        if (currentTask) {
-            status = "working";
+    const seenSquads = new Set();
+    // Collect info from squad agents (named agents)
+    for (const [key, _session] of agentSessions) {
+        const parts = key.split(":");
+        const squadSlug = parts[0];
+        const characterName = parts[1];
+        seenSquads.add(squadSlug);
+        const squad = getSquad(squadSlug);
+        if (characterName) {
+            const agent = getSquadAgent(squadSlug, characterName);
+            const currentTask = tasksByAgent.get(key) ?? tasksByAgent.get(squadSlug);
+            agents.push({
+                slug: squadSlug,
+                name: agent ? `${agent.character_name} (${agent.role_title})` : characterName,
+                characterName,
+                roleTitle: agent?.role_title,
+                universe: squad?.universe ?? undefined,
+                status: agent?.status === "working" ? "working" : currentTask ? "working" : "idle",
+                currentTask,
+            });
         }
-        if (squad?.status === "error") {
-            status = "error";
+        else {
+            // Legacy generic agent
+            const currentTask = tasksByAgent.get(squadSlug);
+            agents.push({
+                slug: squadSlug,
+                name: squad?.name ?? squadSlug,
+                status: currentTask ? "working" : squad?.status === "error" ? "error" : "idle",
+                currentTask,
+            });
         }
-        agents.push({
-            slug,
-            name: squad?.name ?? slug,
-            status,
-            currentTask,
-        });
     }
     return agents;
 }
-export async function delegateToAgent(squadSlug, task, onComplete) {
+export async function delegateToAgent(squadSlug, task, onComplete, targetAgent) {
     const squad = getSquad(squadSlug);
     if (!squad) {
         throw new Error(`Squad not found: ${squadSlug}`);
     }
-    const session = await getOrCreateSession(squadSlug, task);
+    // Determine which agent session to use
+    let agent;
+    if (targetAgent) {
+        agent = getSquadAgent(squadSlug, targetAgent);
+        if (!agent) {
+            throw new Error(`Agent "${targetAgent}" not found in squad "${squadSlug}". Use squad_agents to list the roster.`);
+        }
+    }
+    else {
+        // If squad has named agents, pick the best match (first idle, or first one)
+        const agents = listSquadAgents(squadSlug);
+        if (agents.length > 0) {
+            agent = agents.find((a) => a.status === "idle") ?? agents[0];
+        }
+    }
+    const session = agent
+        ? await getOrCreateAgentSession(squadSlug, agent, task)
+        : await getOrCreateSession(squadSlug, task);
     const taskId = randomUUID();
-    createTask(taskId, squadSlug, task);
+    const agentKey = agent
+        ? agentSessionKey(squadSlug, agent.character_name)
+        : squadSlug;
+    createTask(taskId, agentKey, task);
     updateSquadStatus(squadSlug, "working");
+    if (agent)
+        updateAgentStatus(squadSlug, agent.character_name, "working");
     // Run the task in the background — return taskId immediately
     void (async () => {
         try {
@@ -53,25 +96,33 @@ export async function delegateToAgent(squadSlug, task, onComplete) {
             const result = response?.data?.content ?? "Task completed (no output)";
             completeTask(taskId, result);
             updateSquadStatus(squadSlug, "idle");
+            if (agent)
+                updateAgentStatus(squadSlug, agent.character_name, "idle");
             onComplete(taskId, result);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             failTask(taskId, message);
             updateSquadStatus(squadSlug, "error");
+            if (agent)
+                updateAgentStatus(squadSlug, agent.character_name, "error");
         }
     })();
+    const agentLabel = agent
+        ? `${agent.character_name} (${agent.role_title})`
+        : `squad "${squadSlug}"`;
     return taskId;
 }
 export async function shutdownAgents() {
-    for (const [slug, session] of agentSessions) {
+    for (const [key, session] of agentSessions) {
         try {
             await session.destroy();
         }
         catch {
             // best-effort cleanup
         }
-        agentSessions.delete(slug);
+        agentSessions.delete(key);
+        agentSessionModels.delete(key);
     }
 }
 export function getActiveAgentTasks() {
@@ -85,6 +136,97 @@ export function getActiveAgentTasks() {
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
+/**
+ * Create or resume a Copilot session for a specific named agent.
+ * Model is selected per-task: uses the higher of the agent's default tier
+ * and the task's classified complexity. This means an agent never gets a
+ * model worse than their baseline, but can be upgraded for complex tasks.
+ */
+async function getOrCreateAgentSession(squadSlug, agent, taskDescription) {
+    const key = agentSessionKey(squadSlug, agent.character_name);
+    // Determine model based on task complexity vs agent's default tier
+    const agentTier = agent.model_tier;
+    const taskTier = taskDescription ? classifyComplexity(taskDescription) : agentTier;
+    const tierRank = { high: 3, medium: 2, low: 1 };
+    const effectiveTier = tierRank[taskTier] >= tierRank[agentTier] ? taskTier : agentTier;
+    const model = getModelForTier(effectiveTier);
+    // If we have a cached session, check if the model matches; if not, destroy and recreate
+    const existing = agentSessions.get(key);
+    if (existing) {
+        // Sessions don't expose their model, so track it separately
+        const cachedModel = agentSessionModels.get(key);
+        if (cachedModel === model)
+            return existing;
+        // Model changed — destroy old session for the upgraded model
+        console.error(`[io] Agent ${agent.character_name}: upgrading model ${cachedModel} → ${model} for task complexity`);
+        try {
+            await existing.destroy();
+        }
+        catch { /* best-effort */ }
+        agentSessions.delete(key);
+        agentSessionModels.delete(key);
+    }
+    const squad = getSquad(squadSlug);
+    const client = await getClient();
+    const decisions = getDecisionsSummary(squadSlug);
+    console.error(`[io] Agent ${agent.character_name}: using model "${model}" (agent tier: ${agentTier}, task tier: ${taskTier}, effective: ${effectiveTier})`);
+    const universeName = squad.universe
+        ? getUniverse(squad.universe)?.name ?? squad.universe
+        : "Unknown";
+    const agentTools = buildAgentTools(squadSlug);
+    const systemMessage = `You are ${agent.character_name}, a specialist agent on the "${squad.name}" project team (${universeName} universe).
+
+## Your Identity
+- **Name**: ${agent.character_name}
+- **Role**: ${agent.role_title}
+- **Personality**: ${agent.personality ?? "Professional and focused."}
+
+## Your Charter
+${agent.charter ?? "General-purpose agent. Handle tasks as they come."}
+
+## Project
+- **Path**: ${squad.project_path}
+
+## Past Decisions
+${decisions}
+
+## Instructions
+You are a coding agent. Use the shell tool to run commands and file_ops to read/write files.
+Log important decisions with squad_log_decision so they persist.
+Stay in character — let your personality color your work style and communication, but always deliver quality results.`;
+    const commonConfig = {
+        model,
+        configDir: SESSIONS_DIR,
+        streaming: false,
+        systemMessage: { content: systemMessage },
+        tools: agentTools,
+        onPermissionRequest: approveAll,
+        infiniteSessions: {
+            enabled: true,
+            backgroundCompactionThreshold: 0.8,
+            bufferExhaustionThreshold: 0.95,
+        },
+    };
+    let session;
+    if (agent.copilot_session_id) {
+        try {
+            session = await client.resumeSession(agent.copilot_session_id, commonConfig);
+        }
+        catch {
+            session = await client.createSession(commonConfig);
+        }
+    }
+    else {
+        session = await client.createSession(commonConfig);
+    }
+    updateAgentSession(squadSlug, agent.character_name, session.sessionId);
+    agentSessions.set(key, session);
+    agentSessionModels.set(key, model);
+    return session;
+}
+/**
+ * Legacy: create a generic squad session (for squads without named agents).
+ */
 async function getOrCreateSession(squadSlug, taskDescription) {
     const existing = agentSessions.get(squadSlug);
     if (existing)

package/dist/copilot/orchestrator.js

@@ -4,7 +4,7 @@ import { config } from "../config.js";
 import { SESSIONS_DIR, IO_VERSION } from "../paths.js";
 import { getState, setState, deleteState, logConversation } from "../store/db.js";
 import { clearStaleTasks, getTask } from "../store/tasks.js";
-import { getSquad, listSquads, createSquad, deleteSquad, logDecision, getDecisionsSummary, updateSquadStatus, } from "../store/squads.js";
+import { getSquad, listSquads, createSquad, deleteSquad, logDecision, getDecisionsSummary, updateSquadStatus, addSquadAgent, listSquadAgents, removeSquadAgent, } from "../store/squads.js";
 import { readPage, writePage, assertPagePath, deletePage, listPages } from "../wiki/fs.js";
 import { resolveModelTiers } from "./model-router.js";
 import { searchWiki, getWikiSummary } from "../wiki/search.js";
@@ -37,7 +37,7 @@ let processing = false;
 // Session config helpers
 // ---------------------------------------------------------------------------
 function mapSquad(s) {
-    return { slug: s.slug, name: s.name, projectPath: s.project_path, status: s.status };
+    return { slug: s.slug, name: s.name, projectPath: s.project_path, status: s.status, universe: s.universe };
 }
 function getToolDeps() {
     return {
@@ -65,6 +65,16 @@ function getToolDeps() {
             description: t.description,
             status: t.status,
         })),
+        addSquadAgent,
+        listSquadAgents: (slug) => listSquadAgents(slug).map((a) => ({
+            character_name: a.character_name,
+            role_title: a.role_title,
+            charter: a.charter,
+            model_tier: a.model_tier,
+            personality: a.personality,
+            status: a.status,
+        })),
+        removeSquadAgent,
         listSkills,
         installSkill,
         removeSkill,

package/dist/copilot/system-message.js

@@ -56,21 +56,34 @@ You receive messages and decide how to handle them:
 ${squadBlock}
 ## Squad System
 
-Squads are persistent project teams. When a user works on a codebase:
-1. Create a squad with \`squad_create\` — this sets up a persistent team for that project.
-2. The squad remembers decisions via \`squad_log_decision\`.
-3. Recall squad context with \`squad_recall\` before doing project work.
-4. Check squad status with \`squad_status\`.
+Squads are persistent project teams with **named specialist agents**. Each squad has an 80s pop culture theme (A-Team, Transformers, Thundercats, GI Joe, Aliens, Ghostbusters).
+
+### Creating a Squad
+1. **Create**: \`squad_create\` — creates the squad and assigns a random 80s universe (or specify one).
+2. **Analyze**: \`squad_analyze\` — scan the project directory to understand languages, frameworks, tools.
+3. **Build the team**: Based on the analysis, use \`squad_add_agent\` for each specialist the project needs. Choose **dynamic role titles** based on what the project actually uses (e.g., "Express API Engineer", "Vue.js Frontend Dev", "Vitest Test Engineer"). Each agent gets the next character from the squad's universe.
+4. **Review**: \`squad_agents\` — see the full roster with character names, roles, and personalities.
+
+### Working with Squad Agents
+- The squad remembers decisions via \`squad_log_decision\`.
+- Recall context with \`squad_recall\` before doing project work.
+- Check overall status with \`squad_status\`.
 
 ### Delegating Work
-After planning tasks with the user, **use \`squad_delegate\` to send each task to the squad agent for implementation**. The workflow is:
+After planning tasks with the user, **use \`squad_delegate\` to send each task to the right agent**:
 1. Plan the work with the user (break into concrete tasks).
-2. Call \`squad_delegate\` for each task — provide detailed instructions including file paths, expected behavior, and acceptance criteria.
-3. The agent works autonomously in the background. You get a task ID immediately.
+2. Call \`squad_delegate\` with the squad slug and task. Optionally specify an \`agent\` (character name) to target a specific specialist. If omitted, the system picks the best available agent.
+3. The agent works autonomously in the background with their specialized system prompt.
 4. Use \`squad_task_status\` to check progress and retrieve results.
-5. Report results back to the user.
+5. Report results back to the user, mentioning the character name.
+
+You can delegate multiple tasks to different agents in parallel.
 
-You can delegate multiple tasks in parallel — each gets its own task ID.
+### Agent Roles Are Dynamic
+**Do NOT use generic roles** like "developer" or "tester". Analyze the project first and create roles that match its actual technology stack. Examples:
+- IO project → "Copilot SDK Specialist", "Vue.js Frontend Dev", "Express API Engineer"
+- .NET web app → "ASP.NET Core Backend", "Blazor UI Developer", "xUnit Test Engineer"
+- Rust CLI → "Rust Systems Programmer", "CLI UX Designer", "Integration Test Engineer"
 
 ### Model Selection
 Squad agents are automatically assigned a model based on task complexity:
@@ -90,13 +103,17 @@ The model is selected automatically. Tell the user which model tier was chosen w
 - \`wiki_list\`: List all pages in your knowledge base.
 
 ### Squad Management
-- \`squad_create\`: Create a project squad.
+- \`squad_create\`: Create a project squad (with optional 80s universe theme).
+- \`squad_analyze\`: **Analyze a project** to determine what specialists are needed.
+- \`squad_add_agent\`: **Add a named specialist** to a squad with a dynamic role title and charter.
+- \`squad_agents\`: List a squad's agent roster.
+- \`squad_remove_agent\`: Remove an agent from a squad.
 - \`squad_recall\`: Get a squad's context and decisions.
-- \`squad_status\`: Check squad status.
+- \`squad_status\`: Check all squads and their rosters.
 - \`squad_log_decision\`: Log a decision for a squad.
-- \`squad_delegate\`: **Delegate a task to a squad agent.** The agent works autonomously in the background. Returns a task ID.
+- \`squad_delegate\`: **Delegate a task to a specific agent** (by character name) or let the system pick.
 - \`squad_task_status\`: Check the status/result of a delegated task, or list all active tasks.
-- \`squad_delete\`: Delete a squad and all its decisions permanently.
+- \`squad_delete\`: Delete a squad and all its agents/decisions permanently.
 
 ### Skills
 - \`skill_list\`: List all installed skills.