copilot-hub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openminedev
+
+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,215 @@
+# Copilot Hub
+
+Copilot Hub is a 2-plane monorepo for building and operating Telegram AI agents.
+
+## Planes
+
+- `apps/control-plane`: single Telegram hub chat for operations commands and LLM development tasks.
+- `apps/agent-engine`: execution plane (workers, channels, sessions, capabilities).
+
+Shared packages:
+
+- `packages/contracts`
+- `packages/core`
+- `packages/capabilities`
+
+## Hub chat model
+
+The same Telegram chat handles both operations and development:
+
+- commands: `/help`, `/health`, `/bots`, `/create_agent`, `/cancel`
+- normal message: handled by the LLM assistant
+
+## Workspace isolation
+
+Each runtime agent has its own dedicated `workspaceRoot`.
+
+```mermaid
+flowchart LR
+    CA["Chat A"] --> A["Agent A"] --> WA["~/Desktop/copilot_workspaces/Agent_A"]
+    CB["Chat B"] --> B["Agent B"] --> WB["~/Desktop/copilot_workspaces/Agent_B"]
+    CC["Chat C"] --> C["Agent C"] --> WC["~/Desktop/copilot_workspaces/Agent_C"]
+```
+
+Why this matters:
+
+- multiple chats can run at the same time without mixing files
+- multiple projects can run in parallel on the same machine
+- one agent change stays inside that agent workspace
+
+## Control-plane role
+
+- `control chat` is a simple maintenance chat: fix issues and add new capabilities.
+- `runtime chats` are user-facing chats: execute tasks and deliver results.
+- users stay in runtime chats for normal work and use control chat only when an agent needs a fix or upgrade.
+
+## Example flow
+
+Scenario: user asks a runtime chat (Agent A) to create a website from an image.
+
+```mermaid
+flowchart TD
+    U1["User -> Runtime chat (Agent A): Create a website from this image"] --> C{"Can Agent A read images?"}
+    C -- Yes --> O1["Agent A builds the website"]
+    C -- No --> M["Agent A says: I cannot read images yet"]
+
+    M --> U3["User -> Control chat (control-plane): Fix this for Agent A"]
+    U3 --> I["Control chat adds image_reader to Agent A workspace"]
+    I --> T{"Works correctly?"}
+    T -- No --> U3
+    T -- Yes --> R["Agent A reloads capabilities"]
+
+    R --> U4["User -> Runtime chat (Agent A): Continue the website task"]
+    U4 --> O1
+```
+
+## Install from npm
+
+```bash
+npm install -g copilot-hub@latest
+```
+
+Then run:
+
+```bash
+copilot-hub configure
+copilot-hub start
+```
+
+## Quick start from source
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Configure the required hub token:
+
+```bash
+npm run configure
+```
+
+3. Start services:
+
+```bash
+npm run start
+```
+
+`start` checks required tokens and prompts only if values are missing.
+
+## Telegram setup
+
+### 1) Create the control-plane (hub) bot token
+
+1. Open Telegram and search for `@BotFather`.
+2. Send `/start`.
+3. Send `/newbot`.
+4. Enter the bot display name you want.
+5. Enter a unique username ending with `bot` (example: `my_copilot_hub_bot`).
+6. BotFather returns a token like `123456789:AA...`.
+
+Now run:
+
+```bash
+npm run configure
+```
+
+When prompted, paste this token.
+
+### 2) Start Copilot Hub
+
+```bash
+npm run start
+```
+
+Then open your hub bot in Telegram and send `/start`.
+
+Hub commands:
+
+- `/help`
+- `/health`
+- `/bots`
+- `/create_agent`
+- `/cancel`
+
+### 3) Create runtime agent bot(s)
+
+You need one Telegram bot token per runtime agent.
+
+1. Go back to `@BotFather`.
+2. Run `/newbot` again.
+3. Create a new bot for the runtime agent.
+4. Copy the new token.
+5. In the hub chat, run `/create_agent` and follow the wizard:
+   - Step 1: send the runtime agent token
+   - Step 2: send agent id (or `default`)
+   - Step 3: reply `YES`
+
+After creation, use `/bots` in the hub chat to manage policy, reset context, or delete an agent.
+A streamlined default profile is applied, and actions start from that agent workspace folder.
+
+### 4) Token safety
+
+- Never commit real bot tokens.
+- If a token is leaked, regenerate it in `@BotFather` using `/revoke`.
+- Keep local runtime files (`data/`, `logs/`) private.
+
+## Startup troubleshooting
+
+- If `npm run start` fails, first read the error and follow the suggested action.
+- `npm run start` now auto-detects Codex from VS Code (Windows) and can install Codex CLI automatically if missing.
+- For Codex login issues, run `codex login` (or the configured `CODEX_BIN`) and retry `npm run start`.
+- If auto-install is skipped or unavailable, install Codex CLI with `npm install -g @openai/codex` or set `CODEX_BIN` in `.env`.
+- If you are still stuck, ask your favorite LLM with the exact error output.
+
+## Commands
+
+```bash
+npm run start
+npm run stop
+npm run restart
+npm run status
+npm run logs
+npm run configure
+npm run test
+npm run lint
+npm run format:check
+npm run check:apps
+```
+
+## npm release (CI)
+
+Publishing is automated from GitHub Actions on tags (`v*`).
+
+Release flow:
+
+```bash
+npm version patch
+git push origin main --follow-tags
+```
+
+The release workflow validates build/test/lint/format, checks that the tag version matches `package.json`, then publishes to npm.
+
+Authentication options:
+
+- Recommended: npm Trusted Publishing (OIDC/provenance)
+- Fallback: set `NPM_TOKEN` in GitHub repository secrets
+
+## Workspace policy
+
+- Default workspace root: `~/Desktop/copilot_workspaces` when not explicitly set.
+- `WORKSPACE_STRICT_MODE=true` enforces allowed roots.
+- `WORKSPACE_ALLOWED_ROOTS` adds extra allowed roots.
+- Workspaces inside kernel directories are rejected.
+
+## Runtime files
+
+- PIDs: `.copilot-hub/pids/`
+- Logs: `logs/`
+
+## Security
+
+- Never commit real tokens.
+- Keep `.env` and runtime data local.
+- Rotate leaked tokens immediately.

package/apps/agent-engine/.env.example

@@ -0,0 +1,41 @@
+# Runtime state files
+BOT_DATA_DIR=./data
+BOT_REGISTRY_FILE=./data/bot-registry.json
+SECRET_STORE_FILE=./data/secrets.json
+
+
+# Worker defaults
+# If empty, runtime uses Desktop/copilot_workspaces by default
+# (Windows: %USERPROFILE%/Desktop/copilot_workspaces)
+DEFAULT_WORKSPACE_ROOT=
+PROJECTS_BASE_DIR=
+WORKSPACE_STRICT_MODE=true
+WORKSPACE_ALLOWED_ROOTS=
+DEFAULT_PROVIDER_KIND=codex
+CODEX_HOME_DIR=
+CODEX_SANDBOX=danger-full-access
+CODEX_APPROVAL_POLICY=never
+TURN_ACTIVITY_TIMEOUT_MS=3600000
+MAX_THREAD_MESSAGES=200
+
+AGENT_HEARTBEAT_ENABLED=true
+AGENT_HEARTBEAT_INTERVAL_MS=5000
+AGENT_HEARTBEAT_TIMEOUT_MS=4000
+
+THREAD_MODE=single
+SHARED_THREAD_ID=shared-main
+TELEGRAM_ALLOWED_CHAT_IDS=
+
+INSTANCE_LOCK_ENABLED=true
+INSTANCE_LOCK_FILE=./data/runtime.lock
+
+WEB_HOST=127.0.0.1
+WEB_PORT=8787
+WEB_PUBLIC_BASE_URL=http://localhost:8787
+WEB_PORT_AUTO_INCREMENT=true
+WEB_PORT_SEARCH_MAX=30
+
+# Optional worker token environment variables used in bot-registry.json
+TELEGRAM_TOKEN_AGENT_1=
+
+

package/apps/agent-engine/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amine
+
+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/apps/agent-engine/README.md

@@ -0,0 +1,57 @@
+# Agent Engine
+
+`agent-engine` is the execution plane for worker agents, Telegram channels, capabilities, projects, and runtime policy.
+
+In Copilot Hub:
+- `apps/control-plane`: single Telegram hub chat (operations + LLM development)
+- `apps/agent-engine`: runtime execution plane
+
+## Quick start
+
+```bash
+npm install
+# Windows
+copy .env.example .env
+# macOS/Linux
+cp .env.example .env
+npm run setup
+npm run start
+```
+
+## Operator entry point
+
+Use `apps/control-plane` as the main operator chat.
+
+## Workspace policy
+
+- If `DEFAULT_WORKSPACE_ROOT` is empty, default root is `~/Desktop/copilot_workspaces`.
+- `WORKSPACE_STRICT_MODE=true` enforces allowed roots.
+- `WORKSPACE_ALLOWED_ROOTS` lets you append extra allowed roots.
+- Agent workspaces must stay outside the kernel directory.
+
+## Runtime API
+
+Core:
+- `GET /api/health`
+- `GET /api/bots`
+- `POST /api/bots/create`
+- `POST /api/bots/:botId/delete`
+- `POST /api/bots/:botId/policy`
+- `POST /api/bots/:botId/reset`
+
+Projects:
+- `GET /api/projects`
+- `POST /api/projects/create`
+- `POST /api/bots/:botId/project`
+
+Capabilities and approvals:
+- `GET /api/bots/:botId/capabilities`
+- `POST /api/bots/:botId/capabilities/reload`
+- `POST /api/bots/:botId/capabilities/scaffold`
+- `GET /api/bots/:botId/approvals`
+- `POST /api/bots/:botId/approvals/:approvalId`
+
+## Security
+
+- Never commit `.env` or `data/`.
+- Rotate exposed tokens.

package/apps/agent-engine/bot-registry.example.json

@@ -0,0 +1,28 @@
+{
+  "version": 3,
+  "agents": [
+    {
+      "id": "Agent_1",
+      "name": "Agent 1",
+      "enabled": true,
+      "autoStart": true,
+      "threadMode": "single",
+      "sharedThreadId": "shared-Agent_1",
+      "provider": {
+        "kind": "codex",
+        "options": {
+          "sandboxMode": "danger-full-access",
+          "approvalPolicy": "never"
+        }
+      },
+      "channels": [
+        {
+          "kind": "telegram",
+          "id": "telegram_Agent_1",
+          "tokenEnv": "TELEGRAM_TOKEN_AGENT_1"
+        }
+      ],
+      "capabilities": []
+    }
+  ]
+}

package/apps/agent-engine/capabilities/example/index.js

@@ -0,0 +1,3 @@
+import { createExampleCapability } from "@copilot-hub/core/example-capability";
+
+export const createCapability = createExampleCapability;

package/apps/agent-engine/capabilities/example/manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "example-capability",
+  "name": "Example Capability",
+  "version": "1.0.0",
+  "entry": "./index.js",
+  "minKernelVersion": "1.0.0",
+  "timeoutMs": 3000,
+  "hooks": [
+    "onRuntimeStart",
+    "onTurnStart",
+    "onTurnResult"
+  ],
+  "permissions": []
+}

package/apps/agent-engine/dist/agent-worker.js

@@ -0,0 +1,241 @@
+// @ts-nocheck
+import { BotRuntime } from "@copilot-hub/core/bot-runtime";
+const rawBotConfig = String(process.env.AGENT_BOT_CONFIG_JSON ?? "").trim();
+const rawProviderDefaults = String(process.env.AGENT_PROVIDER_DEFAULTS_JSON ?? "").trim();
+const turnActivityTimeoutMs = Number.parseInt(String(process.env.AGENT_TURN_ACTIVITY_TIMEOUT_MS ?? "3600000"), 10);
+const maxMessages = Number.parseInt(String(process.env.AGENT_MAX_MESSAGES ?? "200"), 10);
+const initialWebPublicBaseUrl = String(process.env.AGENT_WEB_PUBLIC_BASE_URL ?? "http://127.0.0.1:8787").trim();
+const kernelRequestTimeoutMs = Number.parseInt(String(process.env.AGENT_KERNEL_REQUEST_TIMEOUT_MS ?? "20000"), 10);
+if (!rawBotConfig) {
+    throw new Error("AGENT_BOT_CONFIG_JSON is required.");
+}
+const botConfig = JSON.parse(rawBotConfig);
+const providerDefaults = rawProviderDefaults ? JSON.parse(rawProviderDefaults) : {};
+let nextKernelRequestId = 1;
+const pendingKernelRequests = new Map();
+const runtime = new BotRuntime({
+    botConfig,
+    providerDefaults,
+    turnActivityTimeoutMs,
+    maxMessages,
+    kernelControl: {
+        request: (payload) => requestKernelAction(payload),
+    },
+});
+runtime.setWebPublicBaseUrl(initialWebPublicBaseUrl);
+process.on("message", (message) => {
+    void handleInboundMessage(message);
+});
+process.on("disconnect", () => {
+    void gracefulShutdown(0);
+});
+process.on("SIGINT", () => {
+    void gracefulShutdown(0);
+});
+process.on("SIGTERM", () => {
+    void gracefulShutdown(0);
+});
+process.on("uncaughtException", (error) => {
+    console.error(`Worker uncaught exception: ${sanitizeError(error)}`);
+    void gracefulShutdown(1);
+});
+process.on("unhandledRejection", (reason) => {
+    console.error(`Worker unhandled rejection: ${sanitizeError(reason)}`);
+    void gracefulShutdown(1);
+});
+sendEvent("workerReady", {
+    runtimeId: runtime.id,
+    name: runtime.name,
+});
+async function handleInboundMessage(message) {
+    const type = String(message?.type ?? "request").trim();
+    if (type === "kernelResponse") {
+        handleKernelResponse(message);
+        return;
+    }
+    if (type !== "request") {
+        return;
+    }
+    try {
+        await handleWorkerRequest(message);
+    }
+    catch (error) {
+        const requestId = message?.requestId ?? null;
+        if (requestId !== null && requestId !== undefined) {
+            sendResponse({
+                requestId,
+                ok: false,
+                error: sanitizeError(error),
+            });
+            return;
+        }
+        console.error(`Worker inbound message failed: ${sanitizeError(error)}`);
+    }
+}
+async function handleWorkerRequest(message) {
+    const requestId = message?.requestId;
+    const action = String(message?.action ?? "").trim();
+    const payload = message?.payload ?? {};
+    if (!requestId) {
+        throw new Error("requestId is required.");
+    }
+    if (!action) {
+        throw new Error("action is required.");
+    }
+    let result;
+    switch (action) {
+        case "getStatus": {
+            result = runtime.getStatus();
+            break;
+        }
+        case "startChannels": {
+            result = await runtime.startChannels();
+            break;
+        }
+        case "stopChannels": {
+            result = await runtime.stopChannels();
+            break;
+        }
+        case "resetWebThread": {
+            result = await runtime.resetWebThread();
+            break;
+        }
+        case "listPendingApprovals": {
+            const threadId = payload?.threadId ? String(payload.threadId) : undefined;
+            result = await runtime.listPendingApprovals(threadId);
+            break;
+        }
+        case "resolvePendingApproval": {
+            result = await runtime.resolvePendingApproval({
+                threadId: String(payload?.threadId ?? ""),
+                approvalId: String(payload?.approvalId ?? ""),
+                decision: String(payload?.decision ?? ""),
+            });
+            break;
+        }
+        case "reloadCapabilities": {
+            const capabilityDefinitions = Array.isArray(payload?.capabilityDefinitions)
+                ? payload.capabilityDefinitions
+                : null;
+            result = await runtime.reloadCapabilities(capabilityDefinitions);
+            break;
+        }
+        case "setProjectRoot": {
+            const projectRoot = String(payload?.projectRoot ?? "").trim();
+            if (!projectRoot) {
+                throw new Error("projectRoot is required.");
+            }
+            await runtime.setProjectRoot(projectRoot);
+            result = runtime.getStatus();
+            break;
+        }
+        case "setWebPublicBaseUrl": {
+            const value = String(payload?.webPublicBaseUrl ?? "").trim();
+            if (!value) {
+                throw new Error("webPublicBaseUrl is required.");
+            }
+            runtime.setWebPublicBaseUrl(value);
+            result = runtime.getStatus();
+            break;
+        }
+        case "shutdown": {
+            await runtime.shutdown();
+            result = { ok: true };
+            sendResponse({ requestId, ok: true, result });
+            process.exit(0);
+            return;
+        }
+        default: {
+            throw new Error(`Unsupported worker action '${action}'.`);
+        }
+    }
+    sendResponse({ requestId, ok: true, result });
+}
+async function gracefulShutdown(exitCode) {
+    try {
+        await runtime.shutdown();
+    }
+    catch {
+        // Ignore shutdown errors during process termination.
+    }
+    for (const pending of pendingKernelRequests.values()) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error("Worker process is shutting down."));
+    }
+    pendingKernelRequests.clear();
+    process.exit(exitCode);
+}
+function sendResponse(value) {
+    if (!process.send) {
+        return;
+    }
+    process.send({
+        type: "response",
+        ...value,
+    });
+}
+function sendEvent(event, payload) {
+    if (!process.send) {
+        return;
+    }
+    process.send({
+        type: "event",
+        event,
+        payload,
+    });
+}
+function requestKernelAction({ action, payload, context }) {
+    if (!process.send) {
+        return Promise.reject(new Error("Kernel IPC is unavailable."));
+    }
+    const requestId = `kreq_${Date.now()}_${nextKernelRequestId++}`;
+    const timeoutMs = Number.isFinite(kernelRequestTimeoutMs) && kernelRequestTimeoutMs >= 1000
+        ? kernelRequestTimeoutMs
+        : 20000;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pendingKernelRequests.delete(requestId);
+            reject(new Error(`Kernel request '${String(action ?? "")}' timed out after ${timeoutMs}ms.`));
+        }, timeoutMs);
+        pendingKernelRequests.set(requestId, {
+            resolve,
+            reject,
+            timer,
+        });
+        try {
+            process.send({
+                type: "kernelRequest",
+                requestId,
+                action,
+                payload,
+                context,
+            });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            pendingKernelRequests.delete(requestId);
+            reject(error);
+        }
+    });
+}
+function handleKernelResponse(message) {
+    const requestId = String(message?.requestId ?? "").trim();
+    if (!requestId) {
+        return;
+    }
+    const pending = pendingKernelRequests.get(requestId);
+    if (!pending) {
+        return;
+    }
+    pendingKernelRequests.delete(requestId);
+    clearTimeout(pending.timer);
+    if (message?.ok) {
+        pending.resolve(message.result);
+        return;
+    }
+    pending.reject(new Error(String(message?.error ?? "Unknown kernel response error.")));
+}
+function sanitizeError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.split(/\r?\n/).slice(0, 12).join("\n");
+}