heyio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Jolley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# 🤖 IO
+
+A personal AI assistant daemon built on the GitHub Copilot SDK. IO runs 24/7 on your machine, reachable via Telegram and a terminal TUI.
+
+[![CI](https://github.com/michaeljolley/io/actions/workflows/ci.yml/badge.svg)](https://github.com/michaeljolley/io/actions/workflows/ci.yml)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
+
+## ✨ Features
+
+- **Copilot SDK Integration** — powered by GitHub's Copilot SDK for LLM conversations with tool calling
+- **Multi-Interface** — Telegram bot + terminal TUI + HTTP API (future web UI)
+- **Persistent Memory** — wiki-based knowledge base stored at `~/.io/wiki/`
+- **Squad System** — persistent project teams that remember decisions, context, and history
+- **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
+- **Self-Updating** — checks for updates and can apply them automatically
+
+## 📋 Prerequisites
+
+- **Node.js** >= 18
+- **GitHub Copilot subscription** — IO uses the Copilot SDK, which requires an active Copilot license
+- **GitHub CLI** (`gh`) — authenticated via `gh auth login`
+
+## 🚀 Quick Start
+
+### Install
+
+```bash
+npm install -g heyio
+```
+
+### Setup
+
+Run the setup wizard to configure your Telegram bot token and user ID:
+
+```bash
+io setup
+```
+
+This creates a config file at `~/.io/config.json`.
+
+### Run
+
+```bash
+# Interactive TUI mode
+io
+
+# Background daemon (Telegram + HTTP API)
+io --daemon
+
+# Allow IO to modify its own source code
+io --self-edit
+```
+
+## 💬 CLI Usage
+
+| Command | Description |
+| --- | --- |
+| `io` | Start interactive TUI mode |
+| `io --daemon` | Run as background daemon (Telegram + API) |
+| `io --self-edit` | Allow IO to modify its own source |
+| `io setup` | Configure Telegram bot token and user ID |
+| `io skill list` | List installed skills |
+| `io skill add <repo-url>` | Install a skill from a git repository |
+| `io skill remove <slug>` | Remove an installed skill |
+| `io skill search <query>` | Search the skills.sh registry |
+
+## ⚙️ Configuration
+
+IO stores its configuration at `~/.io/config.json`. The setup wizard (`io setup`) handles initial configuration, but you can also edit the file directly.
+
+```jsonc
+{
+  // Telegram bot token from @BotFather
+  "telegramBotToken": "123456:ABC-DEF...",
+
+  // Your Telegram user ID (for authentication)
+  "telegramUserId": 123456789,
+
+  // Enable self-edit mode by default
+  "selfEdit": false
+}
+```
+
+All persistent data is stored under `~/.io/`:
+
+| Path | Purpose |
+| --- | --- |
+| `~/.io/config.json` | User configuration |
+| `~/.io/wiki/` | Knowledge base (markdown files) |
+| `~/.io/io.db` | SQLite database (squads, tasks) |
+| `~/.io/skills/` | Installed skills |
+
+## 🧩 Skills System
+
+Skills are modular extensions that add new tools and capabilities to IO. Each skill is a directory containing a `SKILL.md` manifest and tool definitions.
+
+### Managing Skills
+
+```bash
+# Search the skills.sh registry
+io skill search "github"
+
+# Install from a git repo
+io skill add https://github.com/user/my-skill.git
+
+# List installed skills
+io skill list
+
+# Remove a skill
+io skill remove my-skill
+```
+
+### Creating a Skill
+
+A skill is a directory with a `SKILL.md` file that describes the skill and its tools. See the [Contributing Guide](CONTRIBUTING.md) for details on the skill format.
+
+## 👥 Squad System
+
+Squads are persistent project teams that IO manages. Each squad:
+
+- Is associated with a specific project or domain
+- Remembers decisions, context, and conversation history
+- Can have multiple specialized agents working together
+- Persists across sessions in the SQLite database
+
+IO's orchestrator automatically creates and manages squads based on your conversations.
+
+## 🏗️ Architecture
+
+```
+User → [TUI / Telegram / HTTP API]
+                ↓
+         Orchestrator (Copilot SDK)
+          ↕           ↕
+     Squad Manager   Wiki/Memory
+          ↓
+     Worker Agents
+```
+
+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.
+
+The **Squad System** provides persistent project context, while the **Wiki** serves as a long-term knowledge base that spans all conversations.
+
+## 🏗️ Project Structure
+
+```
+src/
+├── index.ts              # CLI entry (commander)
+├── daemon.ts             # Daemon startup/shutdown
+├── config.ts             # Config loading
+├── paths.ts              # Path constants
+├── update.ts             # Self-update checker
+├── copilot/
+│   ├── client.ts         # CopilotClient singleton
+│   ├── orchestrator.ts   # Main session management
+│   ├── agents.ts         # Worker agent sessions
+│   ├── tools.ts          # Tool definitions
+│   ├── skills.ts         # Skills loader
+│   └── system-message.ts # System prompt builder
+├── store/
+│   ├── db.ts             # SQLite database
+│   ├── squads.ts         # Squad CRUD
+│   └── tasks.ts          # Agent task tracking
+├── wiki/
+│   ├── fs.ts             # Wiki filesystem
+│   └── search.ts         # Wiki search
+├── telegram/
+│   ├── bot.ts            # Grammy Telegram bot
+│   └── handlers.ts       # Command handlers
+├── tui/
+│   └── index.ts          # Terminal UI
+└── api/
+    └── server.ts         # Express HTTP + SSE
+```
+
+## 🛠️ Development
+
+```bash
+# Clone the repository
+git clone https://github.com/michaeljolley/io.git
+cd io
+
+# Install dependencies
+npm install
+
+# Run in development mode (watch)
+npm run dev
+
+# Build for production
+npm run build
+
+# Run the TUI directly
+npm run tui
+
+# Run the daemon directly
+npm run daemon
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before submitting a pull request.

package/dist/api/server.js

@@ -0,0 +1,70 @@
+import express from "express";
+import { config } from "../config.js";
+let messageHandler;
+const sseConnections = new Set();
+export function setMessageHandler(handler) {
+    messageHandler = handler;
+}
+export function broadcastToSSE(text) {
+    const payload = JSON.stringify({ type: "delta", text });
+    for (const res of sseConnections) {
+        res.write(`data: ${payload}\n\n`);
+    }
+}
+export async function startApiServer() {
+    const app = express();
+    app.use(express.json());
+    app.use((_req, res, next) => {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+        next();
+    });
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok" });
+    });
+    app.get("/status", (_req, res) => {
+        res.json({ version: "1.0.0", uptime: process.uptime() });
+    });
+    app.post("/message", async (req, res) => {
+        const { text } = req.body;
+        if (!text) {
+            res.status(400).json({ error: "Missing 'text' in request body" });
+            return;
+        }
+        if (!messageHandler) {
+            res.status(503).json({ error: "No message handler registered" });
+            return;
+        }
+        const connectionId = crypto.randomUUID();
+        let fullResponse = "";
+        await messageHandler(text, connectionId, (chunk, done) => {
+            fullResponse += chunk;
+            const ssePayload = JSON.stringify({
+                type: done ? "done" : "delta",
+                text: chunk,
+            });
+            for (const conn of sseConnections) {
+                conn.write(`data: ${ssePayload}\n\n`);
+            }
+        });
+        res.json({ response: fullResponse });
+    });
+    app.get("/events", (req, res) => {
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("Connection", "keep-alive");
+        res.flushHeaders();
+        sseConnections.add(res);
+        req.on("close", () => {
+            sseConnections.delete(res);
+        });
+    });
+    return new Promise((resolve) => {
+        app.listen(config.apiPort, () => {
+            console.log(`[io] API server listening on port ${config.apiPort}`);
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/config.js

@@ -0,0 +1,28 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { CONFIG_PATH, IO_HOME } from "./paths.js";
+const DEFAULT_CONFIG = {
+    telegramEnabled: false,
+    selfEditEnabled: false,
+    apiPort: 3170,
+};
+function loadConfig() {
+    mkdirSync(IO_HOME, { recursive: true });
+    if (!existsSync(CONFIG_PATH)) {
+        writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2));
+        return { ...DEFAULT_CONFIG };
+    }
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        return { ...DEFAULT_CONFIG, ...parsed };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+export const config = loadConfig();
+export function saveConfig(updates) {
+    Object.assign(config, updates);
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+//# sourceMappingURL=config.js.map

package/dist/copilot/agents.js

@@ -0,0 +1,267 @@
+import { randomUUID } from "crypto";
+import { execSync } from "child_process";
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync, } from "fs";
+import { join, dirname, resolve } from "path";
+import { defineTool, approveAll } from "@github/copilot-sdk";
+import { z } from "zod";
+import { getClient } from "./client.js";
+import { getSquad, updateSquadSession, updateSquadStatus, getDecisionsSummary, logDecision, } from "../store/squads.js";
+import { createTask, completeTask, failTask, getActiveTasks, } from "../store/tasks.js";
+import { SESSIONS_DIR } from "../paths.js";
+const agentSessions = new Map();
+export function getAgentInfo() {
+    const activeTasks = getActiveTasks();
+    const tasksByAgent = new Map();
+    for (const task of activeTasks) {
+        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";
+        }
+        if (squad?.status === "error") {
+            status = "error";
+        }
+        agents.push({
+            slug,
+            name: squad?.name ?? slug,
+            status,
+            currentTask,
+        });
+    }
+    return agents;
+}
+export async function delegateToAgent(squadSlug, task, onComplete) {
+    const squad = getSquad(squadSlug);
+    if (!squad) {
+        throw new Error(`Squad not found: ${squadSlug}`);
+    }
+    const session = await getOrCreateSession(squadSlug);
+    const taskId = randomUUID();
+    createTask(taskId, squadSlug, task);
+    updateSquadStatus(squadSlug, "working");
+    // Run the task in the background — return taskId immediately
+    void (async () => {
+        try {
+            const response = await session.sendAndWait({ prompt: task });
+            const result = response?.data?.content ?? "Task completed (no output)";
+            completeTask(taskId, result);
+            updateSquadStatus(squadSlug, "idle");
+            onComplete(taskId, result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            failTask(taskId, message);
+            updateSquadStatus(squadSlug, "error");
+        }
+    })();
+    return taskId;
+}
+export async function shutdownAgents() {
+    for (const [slug, session] of agentSessions) {
+        try {
+            await session.destroy();
+        }
+        catch {
+            // best-effort cleanup
+        }
+        agentSessions.delete(slug);
+    }
+}
+export function getActiveAgentTasks() {
+    return getActiveTasks().map((t) => ({
+        taskId: t.task_id,
+        agentSlug: t.agent_slug,
+        description: t.description,
+        status: t.status,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function getOrCreateSession(squadSlug) {
+    const existing = agentSessions.get(squadSlug);
+    if (existing)
+        return existing;
+    const squad = getSquad(squadSlug);
+    const client = await getClient();
+    const decisions = getDecisionsSummary(squadSlug);
+    const agentTools = buildAgentTools(squadSlug);
+    const commonConfig = {
+        model: "gpt-4.1",
+        configDir: SESSIONS_DIR,
+        streaming: false,
+        systemMessage: {
+            content: `You are a specialist agent working on the "${squad.name}" project at ${squad.project_path}.
+
+## Past Decisions
+${decisions}
+
+## Your Role
+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.`,
+        },
+        tools: agentTools,
+        onPermissionRequest: approveAll,
+        infiniteSessions: {
+            enabled: true,
+            backgroundCompactionThreshold: 0.8,
+            bufferExhaustionThreshold: 0.95,
+        },
+    };
+    let session;
+    // Try to resume an existing session if we have a saved session ID
+    if (squad.copilot_session_id) {
+        try {
+            session = await client.resumeSession(squad.copilot_session_id, commonConfig);
+        }
+        catch {
+            session = await client.createSession(commonConfig);
+        }
+    }
+    else {
+        session = await client.createSession(commonConfig);
+    }
+    updateSquadSession(squadSlug, session.sessionId);
+    agentSessions.set(squadSlug, session);
+    return session;
+}
+function buildAgentTools(squadSlug) {
+    const shell = defineTool("shell", {
+        description: "Run a shell command. Use for git, build tools, file operations, etc.",
+        parameters: z.object({
+            command: z.string().describe("The command to run"),
+            timeout_secs: z
+                .number()
+                .optional()
+                .describe("Timeout in seconds (default: 60)"),
+            working_dir: z
+                .string()
+                .optional()
+                .describe("Working directory for the command"),
+        }),
+        handler: async ({ command, timeout_secs, working_dir }) => {
+            try {
+                const result = execSync(command, {
+                    encoding: "utf-8",
+                    timeout: (timeout_secs ?? 60) * 1000,
+                    maxBuffer: 1024 * 1024,
+                    cwd: working_dir,
+                });
+                const output = result.trim();
+                if (output.length > 8000) {
+                    return output.slice(0, 8000) + "\n\n[…truncated]";
+                }
+                return output || "(no output)";
+            }
+            catch (err) {
+                const execErr = err;
+                const stderr = execErr.stderr?.trim() ?? "";
+                const stdout = execErr.stdout?.trim() ?? "";
+                const msg = stderr || stdout || execErr.message || "Command failed";
+                if (msg.length > 4000) {
+                    return `Error:\n${msg.slice(0, 4000)}\n[…truncated]`;
+                }
+                return `Error:\n${msg}`;
+            }
+        },
+    });
+    const fileOps = defineTool("file_ops", {
+        description: "Read, write, or list files on the local filesystem.",
+        parameters: z.object({
+            operation: z
+                .enum(["read", "write", "list"])
+                .describe("Operation to perform"),
+            path: z.string().describe("File or directory path"),
+            content: z
+                .string()
+                .optional()
+                .describe("Content to write (for write operation)"),
+            recursive: z
+                .boolean()
+                .optional()
+                .describe("Recurse into subdirectories (for list)"),
+        }),
+        handler: async ({ operation, path: filePath, content, recursive }) => {
+            try {
+                const resolved = resolve(filePath);
+                if (operation === "read") {
+                    if (!existsSync(resolved))
+                        return `File not found: ${filePath}`;
+                    const text = readFileSync(resolved, "utf-8");
+                    if (text.length > 8000) {
+                        return text.slice(0, 8000) + "\n\n[…truncated]";
+                    }
+                    return text;
+                }
+                if (operation === "write") {
+                    if (!content)
+                        return "Error: content is required for write operation";
+                    mkdirSync(dirname(resolved), { recursive: true });
+                    writeFileSync(resolved, content, "utf-8");
+                    return `Written: ${filePath}`;
+                }
+                if (operation === "list") {
+                    if (!existsSync(resolved))
+                        return `Directory not found: ${filePath}`;
+                    if (recursive) {
+                        const files = walkDirectory(resolved);
+                        return files.join("\n") || "(empty directory)";
+                    }
+                    const entries = readdirSync(resolved);
+                    return (entries
+                        .map((e) => {
+                        const full = join(resolved, e);
+                        const isDir = statSync(full).isDirectory();
+                        return isDir ? `${e}/` : e;
+                    })
+                        .join("\n") || "(empty directory)");
+                }
+                return `Unknown operation: ${operation}`;
+            }
+            catch (err) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    });
+    const squadLogDecision = defineTool("squad_log_decision", {
+        description: "Log an important decision for this squad so it persists across sessions.",
+        parameters: z.object({
+            decision: z.string().describe("The decision made"),
+            context: z.string().optional().describe("Context or reasoning"),
+        }),
+        handler: async ({ decision, context }) => {
+            try {
+                logDecision(squadSlug, decision, context);
+                return `Decision logged for squad ${squadSlug}`;
+            }
+            catch (err) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    });
+    return [shell, fileOps, squadLogDecision];
+}
+function walkDirectory(dir, maxDepth = 3, depth = 0) {
+    if (depth >= maxDepth)
+        return [];
+    const results = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith("."))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(`${entry.name}/`);
+            results.push(...walkDirectory(full, maxDepth, depth + 1).map((f) => `  ${entry.name}/${f}`));
+        }
+        else {
+            results.push(entry.name);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=agents.js.map

package/dist/copilot/client.js

@@ -0,0 +1,29 @@
+import { CopilotClient } from "@github/copilot-sdk";
+let client;
+export async function getClient() {
+    if (!client) {
+        client = new CopilotClient({
+            autoStart: true,
+            autoRestart: true,
+        });
+        await client.start();
+    }
+    return client;
+}
+export async function resetClient() {
+    if (client) {
+        try {
+            await client.stop();
+        }
+        catch { /* best-effort */ }
+        client = undefined;
+    }
+    return getClient();
+}
+export async function stopClient() {
+    if (client) {
+        await client.stop();
+        client = undefined;
+    }
+}
+//# sourceMappingURL=client.js.map