copilot-hub 0.1.0

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

@@ -0,0 +1,225 @@
+// @ts-nocheck
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+import { createWorkspaceBoundaryPolicy, assertWorkspaceAllowed, parseWorkspaceAllowedRoots, } from "@copilot-hub/core/workspace-policy";
+import { getDefaultExternalWorkspaceBasePath, getKernelRootPath, } from "@copilot-hub/core/workspace-paths";
+dotenv.config();
+const kernelRootPath = getKernelRootPath();
+const configuredDefaultWorkspaceRoot = String(process.env.DEFAULT_WORKSPACE_ROOT ?? "").trim();
+const defaultWorkspaceRoot = resolveWorkspaceRoot(configuredDefaultWorkspaceRoot || getDefaultExternalWorkspaceBasePath(kernelRootPath));
+const configuredProjectsBaseDir = String(process.env.PROJECTS_BASE_DIR ?? "").trim();
+const projectsBaseDir = path.resolve(configuredProjectsBaseDir || defaultWorkspaceRoot);
+const workspaceStrictMode = parseBoolean(process.env.WORKSPACE_STRICT_MODE ?? "true");
+const workspaceAllowedRoots = parseWorkspaceAllowedRoots(process.env.WORKSPACE_ALLOWED_ROOTS ?? "", {
+    cwd: process.cwd(),
+});
+const workspacePolicy = createWorkspaceBoundaryPolicy({
+    kernelRootPath,
+    defaultWorkspaceRoot,
+    projectsBaseDir,
+    strictMode: workspaceStrictMode,
+    additionalAllowedRoots: workspaceAllowedRoots,
+});
+assertWorkspaceAllowed({
+    workspaceRoot: defaultWorkspaceRoot,
+    policy: workspacePolicy,
+    label: "DEFAULT_WORKSPACE_ROOT",
+});
+const dataDir = path.resolve(process.env.BOT_DATA_DIR ?? path.join(process.cwd(), "data"));
+const botRegistryFilePath = path.resolve(process.env.BOT_REGISTRY_FILE ?? path.join(dataDir, "bot-registry.json"));
+const secretStoreFilePath = path.resolve(process.env.SECRET_STORE_FILE ?? path.join(dataDir, "secrets.json"));
+const instanceLockEnabled = parseBoolean(process.env.INSTANCE_LOCK_ENABLED ?? "true");
+const instanceLockFilePath = path.resolve(process.env.INSTANCE_LOCK_FILE ?? path.join(dataDir, "runtime.lock"));
+const bootstrapTelegramToken = String(process.env.TELEGRAM_BOT_TOKEN ?? "").trim();
+const defaultProviderKind = normalizeProviderKind(process.env.DEFAULT_PROVIDER_KIND ?? "codex");
+const codexBin = resolveCodexBin(process.env.CODEX_BIN);
+const codexHomeDir = resolveOptionalPath(process.env.CODEX_HOME_DIR);
+const codexSandbox = normalizeCodexSandbox(process.env.CODEX_SANDBOX ?? "danger-full-access");
+const codexApprovalPolicy = normalizeApprovalPolicy(process.env.CODEX_APPROVAL_POLICY ?? "never");
+const turnActivityTimeoutMs = Number.parseInt(process.env.TURN_ACTIVITY_TIMEOUT_MS ?? "3600000", 10);
+if (!Number.isFinite(turnActivityTimeoutMs) || turnActivityTimeoutMs < 10000) {
+    throw new Error("TURN_ACTIVITY_TIMEOUT_MS must be an integer >= 10000.");
+}
+const maxMessages = Number.parseInt(process.env.MAX_THREAD_MESSAGES ?? "200", 10);
+if (!Number.isFinite(maxMessages) || maxMessages < 20) {
+    throw new Error("MAX_THREAD_MESSAGES must be an integer >= 20.");
+}
+const webHost = (process.env.WEB_HOST ?? "127.0.0.1").trim() || "127.0.0.1";
+const webPort = Number.parseInt(process.env.WEB_PORT ?? "8787", 10);
+if (!Number.isFinite(webPort) || webPort < 1 || webPort > 65535) {
+    throw new Error("WEB_PORT must be an integer in range 1..65535.");
+}
+const webPublicBaseUrl = (process.env.WEB_PUBLIC_BASE_URL ?? `http://localhost:${webPort}`).trim();
+const webPublicBaseUrlExplicit = Boolean((process.env.WEB_PUBLIC_BASE_URL ?? "").trim());
+const webPortAutoIncrement = parseBoolean(process.env.WEB_PORT_AUTO_INCREMENT ?? "true");
+const webPortSearchMax = Number.parseInt(process.env.WEB_PORT_SEARCH_MAX ?? "30", 10);
+if (!Number.isFinite(webPortSearchMax) || webPortSearchMax < 1 || webPortSearchMax > 1000) {
+    throw new Error("WEB_PORT_SEARCH_MAX must be an integer in range 1..1000.");
+}
+const agentHeartbeatEnabled = parseBoolean(process.env.AGENT_HEARTBEAT_ENABLED ?? "true");
+const agentHeartbeatIntervalMs = Number.parseInt(process.env.AGENT_HEARTBEAT_INTERVAL_MS ?? "5000", 10);
+if (!Number.isFinite(agentHeartbeatIntervalMs) ||
+    agentHeartbeatIntervalMs < 1000 ||
+    agentHeartbeatIntervalMs > 600000) {
+    throw new Error("AGENT_HEARTBEAT_INTERVAL_MS must be an integer in range 1000..600000.");
+}
+const agentHeartbeatTimeoutMs = Number.parseInt(process.env.AGENT_HEARTBEAT_TIMEOUT_MS ?? "4000", 10);
+if (!Number.isFinite(agentHeartbeatTimeoutMs) ||
+    agentHeartbeatTimeoutMs < 500 ||
+    agentHeartbeatTimeoutMs > 60000) {
+    throw new Error("AGENT_HEARTBEAT_TIMEOUT_MS must be an integer in range 500..60000.");
+}
+const defaultThreadMode = normalizeThreadMode(process.env.THREAD_MODE);
+const defaultSharedThreadId = String(process.env.SHARED_THREAD_ID ?? "shared-main").trim();
+if (!/^[A-Za-z0-9:_-]{1,120}$/.test(defaultSharedThreadId)) {
+    throw new Error("SHARED_THREAD_ID has invalid format.");
+}
+const defaultAllowedChatIds = new Set((process.env.TELEGRAM_ALLOWED_CHAT_IDS ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean));
+fs.mkdirSync(dataDir, { recursive: true });
+export const config = {
+    defaultProviderKind,
+    providerDefaults: {
+        defaultKind: defaultProviderKind,
+        codexBin,
+        codexHomeDir,
+        codexSandbox,
+        codexApprovalPolicy,
+    },
+    codexBin,
+    codexHomeDir,
+    codexSandbox,
+    codexApprovalPolicy,
+    kernelRootPath,
+    workspaceStrictMode,
+    workspaceAllowedRoots,
+    workspacePolicy,
+    defaultWorkspaceRoot,
+    projectsBaseDir,
+    dataDir,
+    botRegistryFilePath,
+    secretStoreFilePath,
+    instanceLockEnabled,
+    instanceLockFilePath,
+    bootstrapTelegramToken,
+    turnActivityTimeoutMs,
+    maxMessages,
+    webHost,
+    webPort,
+    webPublicBaseUrl,
+    webPublicBaseUrlExplicit,
+    webPortAutoIncrement,
+    webPortSearchMax,
+    agentHeartbeatEnabled,
+    agentHeartbeatIntervalMs,
+    agentHeartbeatTimeoutMs,
+    defaultThreadMode,
+    defaultSharedThreadId,
+    defaultAllowedChatIds,
+};
+function resolveCodexBin(rawValue) {
+    const value = (rawValue ?? "").trim();
+    const normalized = value.toLowerCase();
+    if (value && normalized !== "codex") {
+        return value;
+    }
+    if (process.platform === "win32") {
+        const vscodeCodex = findVscodeCodexExe();
+        if (vscodeCodex) {
+            return vscodeCodex;
+        }
+    }
+    return value || "codex";
+}
+function findVscodeCodexExe() {
+    const userProfile = process.env.USERPROFILE;
+    if (!userProfile) {
+        return null;
+    }
+    const extensionsDir = path.join(userProfile, ".vscode", "extensions");
+    if (!fs.existsSync(extensionsDir)) {
+        return null;
+    }
+    const candidates = fs
+        .readdirSync(extensionsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => name.startsWith("openai.chatgpt-"))
+        .sort()
+        .reverse();
+    for (const folder of candidates) {
+        const exePath = path.join(extensionsDir, folder, "bin", "windows-x86_64", "codex.exe");
+        if (fs.existsSync(exePath)) {
+            return exePath;
+        }
+    }
+    return null;
+}
+function normalizeThreadMode(value) {
+    const mode = String(value ?? "single")
+        .trim()
+        .toLowerCase();
+    if (mode === "single" || mode === "per_chat") {
+        return mode;
+    }
+    throw new Error("THREAD_MODE must be either 'single' or 'per_chat'.");
+}
+function parseBoolean(value) {
+    const normalized = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+        return true;
+    }
+    if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+        return false;
+    }
+    throw new Error("Invalid boolean value in environment.");
+}
+function resolveOptionalPath(value) {
+    const raw = String(value ?? "").trim();
+    if (!raw) {
+        return null;
+    }
+    return path.resolve(raw);
+}
+function normalizeCodexSandbox(value) {
+    const mode = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (mode === "read-only" || mode === "workspace-write" || mode === "danger-full-access") {
+        return mode;
+    }
+    throw new Error("CODEX_SANDBOX must be one of: read-only, workspace-write, danger-full-access.");
+}
+function normalizeApprovalPolicy(value) {
+    const mode = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (mode === "untrusted" || mode === "on-failure" || mode === "on-request" || mode === "never") {
+        return mode;
+    }
+    throw new Error("CODEX_APPROVAL_POLICY must be one of: untrusted, on-failure, on-request, never.");
+}
+function normalizeProviderKind(value) {
+    const kind = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (!kind) {
+        return "codex";
+    }
+    if (kind === "codex") {
+        return kind;
+    }
+    throw new Error("DEFAULT_PROVIDER_KIND must currently be 'codex'.");
+}
+function resolveWorkspaceRoot(value) {
+    const raw = String(value ?? "").trim();
+    if (!raw) {
+        throw new Error("DEFAULT_WORKSPACE_ROOT must not be empty.");
+    }
+    return path.resolve(raw);
+}

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

@@ -0,0 +1,352 @@
+// @ts-nocheck
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import { BotManager } from "@copilot-hub/core/bot-manager";
+import { loadBotRegistry } from "@copilot-hub/core/bot-registry";
+import { config } from "./config.js";
+import { InstanceLock } from "@copilot-hub/core/instance-lock";
+import { KernelControlPlane } from "@copilot-hub/core/kernel-control-plane";
+import { CONTROL_ACTIONS } from "@copilot-hub/core/control-plane-actions";
+import { KernelSecretStore } from "@copilot-hub/core/secret-store";
+let activeWebPort = config.webPort;
+let runtimeWebPublicBaseUrl = config.webPublicBaseUrl;
+let shuttingDown = false;
+let server = null;
+let botManager = null;
+let instanceLock = null;
+let controlPlane = null;
+let secretStore = null;
+const workerScriptPath = fileURLToPath(new URL("./agent-worker.js", import.meta.url));
+await bootstrap();
+async function bootstrap() {
+    try {
+        if (config.instanceLockEnabled) {
+            instanceLock = new InstanceLock(config.instanceLockFilePath);
+            await instanceLock.acquire();
+        }
+        secretStore = new KernelSecretStore(config.secretStoreFilePath);
+        await secretStore.init();
+        const registry = await loadBotRegistry({
+            filePath: config.botRegistryFilePath,
+            dataDir: config.dataDir,
+            defaultWorkspaceRoot: config.defaultWorkspaceRoot,
+            defaultThreadMode: config.defaultThreadMode,
+            defaultSharedThreadId: config.defaultSharedThreadId,
+            defaultAllowedChatIds: config.defaultAllowedChatIds,
+            bootstrapTelegramToken: config.bootstrapTelegramToken,
+            defaultProviderKind: config.defaultProviderKind,
+            workspacePolicy: config.workspacePolicy,
+            resolveSecret: (name) => secretStore.getSecret(name),
+        });
+        const runtimeBots = registry.bots.filter((bot) => bot.enabled !== false);
+        botManager = new BotManager({
+            botDefinitions: runtimeBots,
+            providerDefaults: config.providerDefaults,
+            turnActivityTimeoutMs: config.turnActivityTimeoutMs,
+            maxMessages: config.maxMessages,
+            webPublicBaseUrl: runtimeWebPublicBaseUrl,
+            projectsBaseDir: config.projectsBaseDir,
+            workerScriptPath,
+            botDataRootDir: path.join(config.dataDir, "bots"),
+            heartbeatEnabled: config.agentHeartbeatEnabled,
+            heartbeatIntervalMs: config.agentHeartbeatIntervalMs,
+            heartbeatTimeoutMs: config.agentHeartbeatTimeoutMs,
+        });
+        controlPlane = new KernelControlPlane({
+            botManager,
+            registryFilePath: registry.filePath,
+            secretStore,
+            registryLoadOptions: {
+                dataDir: config.dataDir,
+                defaultWorkspaceRoot: config.defaultWorkspaceRoot,
+                defaultThreadMode: config.defaultThreadMode,
+                defaultSharedThreadId: config.defaultSharedThreadId,
+                defaultAllowedChatIds: config.defaultAllowedChatIds,
+                bootstrapTelegramToken: config.bootstrapTelegramToken,
+                defaultProviderKind: config.defaultProviderKind,
+                workspacePolicy: config.workspacePolicy,
+                resolveSecret: (name) => secretStore.getSecret(name),
+            },
+        });
+        botManager.setKernelActionHandler((request) => controlPlane.handleAgentAction(request));
+        const app = buildApiApp({
+            botManager,
+            controlPlane,
+            registryFilePath: registry.filePath,
+        });
+        const started = await startWebServer({
+            app,
+            host: config.webHost,
+            basePort: config.webPort,
+            autoIncrement: config.webPortAutoIncrement,
+            maxAttempts: config.webPortSearchMax,
+        });
+        server = started.server;
+        activeWebPort = started.port;
+        runtimeWebPublicBaseUrl = resolveRuntimeWebPublicBaseUrl({
+            explicit: config.webPublicBaseUrlExplicit,
+            configuredBaseUrl: config.webPublicBaseUrl,
+            host: config.webHost,
+            port: activeWebPort,
+        });
+        botManager.setWebPublicBaseUrl(runtimeWebPublicBaseUrl);
+        await botManager.startAutoBots();
+        registerSignals();
+        console.log(`HTTP API listening on http://${config.webHost}:${activeWebPort}`);
+        console.log(`Bot registry loaded: ${registry.filePath}`);
+        if (instanceLock) {
+            console.log(`Instance lock acquired: ${config.instanceLockFilePath}`);
+        }
+    }
+    catch (error) {
+        const message = sanitizeError(error);
+        console.error(message);
+        await cleanupBeforeExit();
+        process.exit(1);
+    }
+}
+function buildApiApp({ botManager, controlPlane, registryFilePath }) {
+    const app = express();
+    app.use(express.json({ limit: "1mb" }));
+    app.use((req, res, next) => {
+        res.setHeader("Cache-Control", "no-store");
+        next();
+    });
+    app.get("/api/health", (req, res) => {
+        res.json({
+            ok: true,
+            service: "runtime_kernel",
+            providerDefault: config.defaultProviderKind,
+            webPort: activeWebPort,
+            webPublicBaseUrl: runtimeWebPublicBaseUrl,
+            botCount: botManager.getBotCount(),
+            turnActivityTimeoutMs: config.turnActivityTimeoutMs,
+            heartbeatEnabled: config.agentHeartbeatEnabled,
+            heartbeatIntervalMs: config.agentHeartbeatIntervalMs,
+            heartbeatTimeoutMs: config.agentHeartbeatTimeoutMs,
+            registryFile: registryFilePath,
+            secretStoreFile: config.secretStoreFilePath,
+        });
+    });
+    app.get("/api/extensions/contract", wrapAsync(async (req, res) => {
+        const contract = await controlPlane.runSystemAction(CONTROL_ACTIONS.EXTENSIONS_CONTRACT_GET, {});
+        res.json(contract);
+    }));
+    app.get("/api/bots", wrapAsync(async (req, res) => {
+        const bots = await botManager.listBotsLive();
+        res.json({ bots });
+    }));
+    app.post("/api/bots/create", wrapAsync(async (req, res) => {
+        const result = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_CREATE, {
+            agent: req.body?.agent,
+            startIfEnabled: req.body?.startIfEnabled !== false,
+        });
+        res.json(result);
+    }));
+    app.post("/api/bots/:botId/delete", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const deleteMode = parseDeleteModeFromRequest(req.body);
+        const deleted = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_DELETE, {
+            botId,
+            deleteMode,
+        });
+        res.json(deleted);
+    }));
+    app.post("/api/bots/:botId/project", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const projectName = String(req.body?.projectName ?? "").trim();
+        if (!projectName) {
+            res.status(400).json({ error: "Field 'projectName' is required." });
+            return;
+        }
+        const result = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_SET_PROJECT, {
+            botId,
+            projectName,
+        });
+        res.json(result);
+    }));
+    app.post("/api/bots/:botId/policy", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const sandboxMode = String(req.body?.sandboxMode ?? "")
+            .trim()
+            .toLowerCase();
+        const approvalPolicy = String(req.body?.approvalPolicy ?? "")
+            .trim()
+            .toLowerCase();
+        if (!sandboxMode) {
+            res.status(400).json({ error: "Field 'sandboxMode' is required." });
+            return;
+        }
+        if (!approvalPolicy) {
+            res.status(400).json({ error: "Field 'approvalPolicy' is required." });
+            return;
+        }
+        const result = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_SET_POLICY, {
+            botId,
+            sandboxMode,
+            approvalPolicy,
+        });
+        res.json(result);
+    }));
+    app.get("/api/projects", wrapAsync(async (req, res) => {
+        const projects = await controlPlane.runSystemAction(CONTROL_ACTIONS.PROJECTS_LIST, {});
+        res.json(projects);
+    }));
+    app.post("/api/projects/create", wrapAsync(async (req, res) => {
+        const name = String(req.body?.name ?? "").trim();
+        if (!name) {
+            res.status(400).json({ error: "Field 'name' is required." });
+            return;
+        }
+        const created = await controlPlane.runSystemAction(CONTROL_ACTIONS.PROJECTS_CREATE, { name });
+        res.json(created);
+    }));
+    app.post("/api/bots/:botId/reset", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        await botManager.resetWebThread(botId);
+        const bot = await botManager.getBotStatus(botId);
+        res.json({
+            bot,
+            reset: true,
+        });
+    }));
+    app.get("/api/bots/:botId/approvals", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const threadId = String(req.query.threadId ?? "").trim() || undefined;
+        const approvals = await botManager.listBotApprovals(botId, threadId);
+        res.json({ approvals });
+    }));
+    app.post("/api/bots/:botId/approvals/:approvalId", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const approvalId = String(req.params.approvalId ?? "").trim();
+        const threadId = String(req.body?.threadId ?? "").trim();
+        const decision = String(req.body?.decision ?? "").trim();
+        if (!threadId) {
+            res.status(400).json({ error: "Field 'threadId' is required." });
+            return;
+        }
+        if (!decision) {
+            res.status(400).json({ error: "Field 'decision' is required." });
+            return;
+        }
+        const resolved = await botManager.resolveBotApproval(botId, {
+            threadId,
+            approvalId,
+            decision,
+        });
+        res.json({ approval: resolved });
+    }));
+    app.get("/api/bots/:botId/capabilities", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const result = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_CAPABILITIES_LIST, {
+            botId,
+        });
+        res.json(result);
+    }));
+    app.post("/api/bots/:botId/capabilities/reload", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const result = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_CAPABILITIES_RELOAD, {
+            botId,
+        });
+        res.json(result);
+    }));
+    app.post("/api/bots/:botId/capabilities/scaffold", wrapAsync(async (req, res) => {
+        const botId = String(req.params.botId ?? "").trim();
+        const capabilityId = String(req.body?.capabilityId ?? "").trim();
+        const capabilityName = String(req.body?.capabilityName ?? "").trim();
+        if (!capabilityId) {
+            res.status(400).json({ error: "Field 'capabilityId' is required." });
+            return;
+        }
+        const result = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_CAPABILITIES_SCAFFOLD, {
+            botId,
+            capabilityId,
+            capabilityName: capabilityName || undefined,
+        });
+        res.json(result);
+    }));
+    app.use((error, req, res, _next) => {
+        const message = sanitizeError(error);
+        res.status(400).json({ error: message });
+    });
+    return app;
+}
+function registerSignals() {
+    process.on("SIGINT", () => {
+        void shutdown(0);
+    });
+    process.on("SIGTERM", () => {
+        void shutdown(0);
+    });
+}
+function wrapAsync(handler) {
+    return (req, res, next) => {
+        Promise.resolve(handler(req, res, next)).catch(next);
+    };
+}
+function resolveRuntimeWebPublicBaseUrl({ explicit, configuredBaseUrl, host, port }) {
+    if (explicit) {
+        return configuredBaseUrl;
+    }
+    const exposedHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+    return `http://${exposedHost}:${port}`;
+}
+async function startWebServer({ app, host, basePort, autoIncrement, maxAttempts }) {
+    let port = basePort;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+            const startedServer = await listenOnce({ app, host, port });
+            return { server: startedServer, port };
+        }
+        catch (error) {
+            const occupied = error && typeof error === "object" && error.code === "EADDRINUSE";
+            if (!occupied || !autoIncrement || port >= 65535) {
+                throw error;
+            }
+            port += 1;
+        }
+    }
+    throw new Error(`Could not find a free web port after ${maxAttempts} attempts starting from ${basePort}.`);
+}
+function listenOnce({ app, host, port }) {
+    return new Promise((resolve, reject) => {
+        const candidate = app.listen(port, host);
+        candidate.once("listening", () => resolve(candidate));
+        candidate.once("error", (error) => reject(error));
+    });
+}
+async function shutdown(exitCode) {
+    if (shuttingDown) {
+        return;
+    }
+    shuttingDown = true;
+    await cleanupBeforeExit();
+    process.exit(exitCode);
+}
+async function cleanupBeforeExit() {
+    if (botManager) {
+        await botManager.shutdownAll();
+    }
+    if (server) {
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+        });
+    }
+    if (instanceLock) {
+        await instanceLock.release();
+    }
+}
+function sanitizeError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.split(/\r?\n/).slice(0, 12).join("\n");
+}
+function parseDeleteModeFromRequest(body) {
+    const value = String(body?.deleteMode ?? "")
+        .trim()
+        .toLowerCase();
+    if (value === "soft" || value === "purge_data" || value === "purge_all") {
+        return value;
+    }
+    return "soft";
+}

package/apps/agent-engine/dist/test/project-fingerprint.test.js

@@ -0,0 +1,40 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createProjectFingerprint } from "@copilot-hub/core/project-fingerprint";
+test("createProjectFingerprint is stable and order-independent for channels", () => {
+    const a = createProjectFingerprint({
+        runtimeId: "agent-a",
+        workspaceRoot: "./workspace-a",
+        providerKind: "CODEX",
+        channels: [
+            { kind: "telegram", id: "123" },
+            { kind: "whatsapp", id: "abc" },
+        ],
+    });
+    const b = createProjectFingerprint({
+        runtimeId: "agent-a",
+        workspaceRoot: "./workspace-a",
+        providerKind: "codex",
+        channels: [
+            { kind: "whatsapp", id: "abc" },
+            { kind: "telegram", id: "123" },
+        ],
+    });
+    assert.equal(a, b);
+    assert.match(a, /^[a-f0-9]{24}$/);
+});
+test("createProjectFingerprint changes when stable inputs differ", () => {
+    const base = createProjectFingerprint({
+        runtimeId: "agent-a",
+        workspaceRoot: "./workspace-a",
+        providerKind: "codex",
+        channels: [{ kind: "telegram", id: "123" }],
+    });
+    const changedProvider = createProjectFingerprint({
+        runtimeId: "agent-a",
+        workspaceRoot: "./workspace-a",
+        providerKind: "other",
+        channels: [{ kind: "telegram", id: "123" }],
+    });
+    assert.notEqual(base, changedProvider);
+});

package/apps/agent-engine/dist/test/thread-id.test.js

@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { normalizeThreadId } from "@copilot-hub/core/thread-id";
+test("normalizeThreadId trims and accepts valid thread ids", () => {
+    assert.equal(normalizeThreadId("  shared-main  "), "shared-main");
+    assert.equal(normalizeThreadId("chat:123_ABC-1"), "chat:123_ABC-1");
+});
+test("normalizeThreadId rejects empty and invalid values", () => {
+    assert.throws(() => normalizeThreadId(""), /threadId is required/);
+    assert.throws(() => normalizeThreadId("thread id with spaces"), /Invalid threadId/);
+    assert.throws(() => normalizeThreadId("chat/123"), /Invalid threadId/);
+});

package/apps/agent-engine/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@copilot-hub/agent-engine",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Copilot Hub execution plane (agent engine)",
+  "type": "module",
+  "scripts": {
+    "setup": "node scripts/setup-runtime.mjs",
+    "build": "tsc -p tsconfig.json",
+    "build:test": "tsc -p tsconfig.test.json",
+    "prestart": "node ../../scripts/ensure-shared-build.mjs && npm run build",
+    "start": "node dist/index.js",
+    "predev": "node ../../scripts/ensure-shared-build.mjs && npm run build",
+    "dev": "node --watch dist/index.js",
+    "pretest": "node ../../scripts/ensure-shared-build.mjs && npm run build && npm run build:test",
+    "test": "node ../../scripts/run-node-tests.mjs dist/test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@copilot-hub/contracts": "0.1.0",
+    "@copilot-hub/core": "0.1.0",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "grammy": "^1.38.3"
+  }
+}

package/apps/control-plane/.env.example

@@ -0,0 +1,25 @@
+HUB_TELEGRAM_TOKEN_ENV=HUB_TELEGRAM_TOKEN
+HUB_TELEGRAM_TOKEN=123456:replace_me
+HUB_ID=copilot_hub
+HUB_NAME=Copilot Hub
+# Optional. If empty, defaults to Desktop/copilot_workspaces (Windows/macOS/Linux)
+HUB_WORKSPACE_ROOT=
+HUB_IMMUTABLE_CORE=true
+HUB_DATA_DIR=./data/copilot_hub
+HUB_THREAD_MODE=per_chat
+HUB_SHARED_THREAD_ID=shared-copilot-hub
+HUB_ALLOWED_CHAT_IDS=
+HUB_ENGINE_BASE_URL=http://127.0.0.1:8787
+HUB_CODEX_SANDBOX=workspace-write
+HUB_CODEX_APPROVAL_POLICY=on-failure
+
+DEFAULT_WORKSPACE_ROOT=
+PROJECTS_BASE_DIR=
+WORKSPACE_STRICT_MODE=true
+WORKSPACE_ALLOWED_ROOTS=
+DEFAULT_PROVIDER_KIND=codex
+CODEX_SANDBOX=danger-full-access
+CODEX_APPROVAL_POLICY=never
+TURN_ACTIVITY_TIMEOUT_MS=3600000
+MAX_THREAD_MESSAGES=200
+