copilot-hub 0.1.20 → 0.1.23

package/README.md

@@ -82,6 +82,7 @@ copilot-hub start
 
 `start` runs guided setup automatically if required values are missing.
 On interactive terminals, `start` can also offer OS-native service installation when it is not yet configured.
+`start` also verifies the supported Codex CLI range and can install the validated version automatically when needed.
 
 ## Quick start from source
 
@@ -160,16 +161,29 @@ Default values are already applied, and actions start from that agent workspace
 
 - Never commit real bot tokens.
 - If a token is leaked, regenerate it in `@BotFather` using `/revoke`.
-- Keep local runtime files (`data/`, `logs/`) private.
+- Keep local runtime files 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.
+- `npm run start` now checks that Codex CLI is inside the supported range and can install the validated version automatically if missing or outside that range.
 - 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 auto-install is skipped or unavailable, install Codex CLI with `npm install -g @openai/codex@0.113.0` or set `CODEX_BIN` in your Copilot Hub config to a binary in the supported `0.113.x` range.
 - If you are still stuck, ask your favorite LLM with the exact error output.
 
+## Upgrades
+
+Use the standard npm flow:
+
+```bash
+npm install -g copilot-hub@latest
+copilot-hub restart
+```
+
+If Copilot Hub is not already running, use `copilot-hub start` after the install instead of `copilot-hub restart`.
+
+Tokens, registry data, logs and runtime state are now stored in a persistent per-user Copilot Hub directory, so they survive package upgrades. The runtime also no longer keeps the installed package directory as its working directory, so `npm install -g copilot-hub@latest` can replace the package cleanly on Windows while the service is running.
+
 ## Commands
 
 ```bash
@@ -179,19 +193,12 @@ npm run restart
 npm run status
 npm run logs
 npm run configure
-npm run update
 npm run test
 npm run lint
 npm run format:check
 npm run check:apps
 ```
 
-Global update command:
-
-```bash
-copilot-hub update
-```
-
 Service mode (optional, OS-native):
 
 ```bash
@@ -237,11 +244,13 @@ Authentication options:
 
 ## Runtime files
 
-- PIDs: `.copilot-hub/pids/`
-- Logs: `logs/`
+- Config, tokens, registry, logs and runtime state live in the per-user Copilot Hub home directory.
+- Windows default: `%APPDATA%\\copilot-hub`
+- macOS default: `~/Library/Application Support/copilot-hub`
+- Linux default: `${XDG_CONFIG_HOME:-~/.config}/copilot-hub`
 
 ## Security
 
 - Never commit real tokens.
-- Keep `.env` and runtime data local.
+- Keep your Copilot Hub home directory private.
 - Rotate leaked tokens immediately.

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

@@ -1,18 +1,20 @@
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import dotenv from "dotenv";
 import { createWorkspaceBoundaryPolicy, assertWorkspaceAllowed, parseWorkspaceAllowedRoots, } from "@copilot-hub/core/workspace-policy";
 import { parseTurnActivityTimeoutSetting } from "@copilot-hub/core/codex-app-utils";
+import { resolveConfigBaseDir, resolveOptionalPathFromBase, resolvePathFromBase, } from "@copilot-hub/core/config-paths";
 import { getDefaultExternalWorkspaceBasePath, getKernelRootPath, } from "@copilot-hub/core/workspace-paths";
-dotenv.config();
+const envBaseDir = loadEnvironment();
 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 projectsBaseDir = resolvePathFromBase(configuredProjectsBaseDir || defaultWorkspaceRoot, envBaseDir);
 const workspaceStrictMode = parseBoolean(process.env.WORKSPACE_STRICT_MODE ?? "true");
 const workspaceAllowedRoots = parseWorkspaceAllowedRoots(process.env.WORKSPACE_ALLOWED_ROOTS ?? "", {
-    cwd: process.cwd(),
+    cwd: envBaseDir,
 });
 const workspacePolicy = createWorkspaceBoundaryPolicy({
     kernelRootPath,
@@ -26,15 +28,19 @@ assertWorkspaceAllowed({
     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 dataDir = resolvePathFromBase(process.env.BOT_DATA_DIR ?? path.join(envBaseDir, "data"), envBaseDir);
+const botRegistryFilePath = resolvePathFromBase(process.env.BOT_REGISTRY_FILE ?? path.join(dataDir, "bot-registry.json"), envBaseDir);
+const secretStoreFilePath = resolvePathFromBase(process.env.SECRET_STORE_FILE ?? path.join(dataDir, "secrets.json"), envBaseDir);
 const instanceLockEnabled = parseBoolean(process.env.INSTANCE_LOCK_ENABLED ?? "true");
-const instanceLockFilePath = path.resolve(process.env.INSTANCE_LOCK_FILE ?? path.join(dataDir, "runtime.lock"));
+const instanceLockFilePath = resolvePathFromBase(process.env.INSTANCE_LOCK_FILE ?? path.join(dataDir, "runtime.lock"), envBaseDir);
 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 codexHomeDir = resolveOptionalPathFromBase(process.env.CODEX_HOME_DIR, envBaseDir);
+if (codexHomeDir) {
+    process.env.CODEX_HOME_DIR = codexHomeDir;
+    process.env.CODEX_HOME = codexHomeDir;
+}
 const codexSandbox = normalizeCodexSandbox(process.env.CODEX_SANDBOX ?? "danger-full-access");
 const codexApprovalPolicy = normalizeApprovalPolicy(process.env.CODEX_APPROVAL_POLICY ?? "never");
 const turnActivityTimeoutMs = parseTurnActivityTimeoutSetting(process.env.TURN_ACTIVITY_TIMEOUT_MS ?? "0", 0);
@@ -78,6 +84,7 @@ const defaultAllowedChatIds = new Set((process.env.TELEGRAM_ALLOWED_CHAT_IDS ??
     .filter(Boolean));
 fs.mkdirSync(dataDir, { recursive: true });
 export const config = {
+    envBaseDir,
     defaultProviderKind,
     providerDefaults: {
         defaultKind: defaultProviderKind,
@@ -117,6 +124,24 @@ export const config = {
     defaultSharedThreadId,
     defaultAllowedChatIds,
 };
+function loadEnvironment() {
+    const configuredEnvPath = String(process.env.COPILOT_HUB_ENV_PATH ?? "").trim();
+    const resolvedEnvPath = configuredEnvPath ? path.resolve(configuredEnvPath) : "";
+    const baseDir = resolveConfigBaseDir({
+        configuredBaseDir: process.env.COPILOT_HUB_ENV_BASE_DIR,
+        configuredEnvPath: resolvedEnvPath,
+        cwd: process.cwd(),
+    });
+    if (configuredEnvPath) {
+        process.env.COPILOT_HUB_ENV_PATH = resolvedEnvPath;
+        dotenv.config({ path: resolvedEnvPath });
+    }
+    else {
+        dotenv.config();
+    }
+    process.env.COPILOT_HUB_ENV_BASE_DIR = baseDir;
+    return baseDir;
+}
 function resolveCodexBin(rawValue) {
     const value = String(rawValue ?? "").trim();
     const normalized = value.toLowerCase();
@@ -124,6 +149,10 @@ function resolveCodexBin(rawValue) {
         return value;
     }
     if (process.platform === "win32") {
+        const npmGlobalCodex = findWindowsNpmGlobalCodexBin();
+        if (npmGlobalCodex) {
+            return npmGlobalCodex;
+        }
         const vscodeCodex = findVscodeCodexExe();
         if (vscodeCodex) {
             return vscodeCodex;
@@ -155,6 +184,59 @@ function findVscodeCodexExe() {
     }
     return null;
 }
+function findWindowsNpmGlobalCodexBin() {
+    if (process.platform !== "win32") {
+        return null;
+    }
+    const candidates = [];
+    const appData = String(process.env.APPDATA ?? "").trim();
+    if (appData) {
+        candidates.push(path.join(appData, "npm", "codex.cmd"));
+        candidates.push(path.join(appData, "npm", "codex.exe"));
+        candidates.push(path.join(appData, "npm", "codex"));
+    }
+    const npmPrefix = readNpmPrefix();
+    if (npmPrefix) {
+        candidates.push(path.join(npmPrefix, "codex.cmd"));
+        candidates.push(path.join(npmPrefix, "codex.exe"));
+        candidates.push(path.join(npmPrefix, "codex"));
+    }
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function readNpmPrefix() {
+    const result = spawnNpm(["config", "get", "prefix"]);
+    if (result.error || result.status !== 0) {
+        return "";
+    }
+    const value = String(result.stdout ?? "").trim();
+    if (!value || value.toLowerCase() === "undefined") {
+        return "";
+    }
+    return value;
+}
+function spawnNpm(args) {
+    if (process.platform === "win32") {
+        const comspec = process.env.ComSpec || "cmd.exe";
+        const commandLine = ["npm", ...args].join(" ");
+        return spawnSync(comspec, ["/d", "/s", "/c", commandLine], {
+            cwd: envBaseDir,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: false,
+            encoding: "utf8",
+        });
+    }
+    return spawnSync("npm", args, {
+        cwd: envBaseDir,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false,
+        encoding: "utf8",
+    });
+}
 function normalizeThreadMode(value) {
     const mode = String(value ?? "single")
         .trim()
@@ -176,13 +258,6 @@ function parseBoolean(value) {
     }
     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()
@@ -218,5 +293,5 @@ function resolveWorkspaceRoot(value) {
     if (!raw) {
         throw new Error("DEFAULT_WORKSPACE_ROOT must not be empty.");
     }
-    return path.resolve(raw);
+    return resolvePathFromBase(raw, envBaseDir);
 }

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

@@ -5,7 +5,9 @@ import { fileURLToPath } from "node:url";
 import express from "express";
 import { BotManager } from "@copilot-hub/core/bot-manager";
 import { CodexAppClient } from "@copilot-hub/core/codex-app-client";
+import { buildShellWrappedCommandLine, requiresShellWrappedSpawn, } from "@copilot-hub/core/codex-app-utils";
 import { loadBotRegistry } from "@copilot-hub/core/bot-registry";
+import { invalidateCodexQuotaUsageCache } from "@copilot-hub/core/telegram-channel";
 import { config } from "./config.js";
 import { InstanceLock } from "@copilot-hub/core/instance-lock";
 import { KernelControlPlane } from "@copilot-hub/core/kernel-control-plane";
@@ -215,6 +217,7 @@ function buildApiApp({ botManager, controlPlane, registryFilePath, }) {
         const refreshed = await refreshRunningBotProviders({
             botManager: requireBotManager(),
         });
+        invalidateCodexQuotaUsageCache();
         res.json({
             ok: true,
             switched: true,
@@ -273,8 +276,18 @@ function buildApiApp({ botManager, controlPlane, registryFilePath, }) {
             .trim()
             .toLowerCase();
         const hasModel = Object.prototype.hasOwnProperty.call(req.body ?? {}, "model");
+        const hasReasoningEffort = Object.prototype.hasOwnProperty.call(req.body ?? {}, "reasoningEffort");
+        const hasServiceTier = Object.prototype.hasOwnProperty.call(req.body ?? {}, "serviceTier");
         const rawModel = req.body?.model;
+        const rawReasoningEffort = req.body?.reasoningEffort;
+        const rawServiceTier = req.body?.serviceTier;
         const model = rawModel === null || rawModel === undefined ? null : String(rawModel).trim();
+        const reasoningEffort = rawReasoningEffort === null || rawReasoningEffort === undefined
+            ? null
+            : String(rawReasoningEffort).trim().toLowerCase();
+        const serviceTier = rawServiceTier === null || rawServiceTier === undefined
+            ? null
+            : String(rawServiceTier).trim().toLowerCase();
         if (!sandboxMode) {
             res.status(400).json({ error: "Field 'sandboxMode' is required." });
             return;
@@ -291,6 +304,12 @@ function buildApiApp({ botManager, controlPlane, registryFilePath, }) {
         if (hasModel) {
             payload.model = model;
         }
+        if (hasReasoningEffort) {
+            payload.reasoningEffort = reasoningEffort;
+        }
+        if (hasServiceTier) {
+            payload.serviceTier = serviceTier;
+        }
         const result = await controlPlane.runSystemAction(CONTROL_ACTIONS.BOTS_SET_POLICY, payload);
         res.json(result);
     }));
@@ -476,13 +495,21 @@ function startCodexDeviceAuthSession() {
         refreshedBots: [],
         refreshFailures: [],
     };
-    const child = spawn(codexBin, ["login", "--device-auth"], {
-        cwd: config.kernelRootPath,
-        shell: false,
-        stdio: ["ignore", "pipe", "pipe"],
-        windowsHide: true,
-        env: process.env,
-    });
+    const child = requiresShellWrappedSpawn(codexBin)
+        ? spawn(buildShellWrappedCommandLine(codexBin, ["login", "--device-auth"]), {
+            cwd: config.kernelRootPath,
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            env: process.env,
+        })
+        : spawn(codexBin, ["login", "--device-auth"], {
+            cwd: config.kernelRootPath,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            env: process.env,
+        });
     session.child = child;
     codexDeviceAuthSession = session;
     child.stdout.on("data", (chunk) => {
@@ -507,6 +534,7 @@ function startCodexDeviceAuthSession() {
                 botManager: requireBotManager(),
             })
                 .then((refreshed) => {
+                invalidateCodexQuotaUsageCache();
                 session.refreshedBots = refreshed.refreshedBotIds;
                 session.refreshFailures = refreshed.failures;
                 session.status = "succeeded";
@@ -706,6 +734,8 @@ function normalizeModelCatalog(rawModels) {
             displayName: String(entry?.displayName ?? model).trim() || model,
             description: String(entry?.description ?? "").trim(),
             isDefault: entry?.isDefault === true,
+            supportedReasoningEfforts: normalizeReasoningCatalog(entry?.supportedReasoningEfforts),
+            defaultReasoningEffort: normalizeReasoningEffortValue(entry?.defaultReasoningEffort),
         });
     }
     return normalized.sort((a, b) => {
@@ -725,17 +755,58 @@ function looksLikeCodexApiKey(value) {
     }
     return key.startsWith("sk-");
 }
+function normalizeReasoningCatalog(value) {
+    const options = [];
+    const seen = new Set();
+    for (const entry of Array.isArray(value) ? value : []) {
+        const option = isRecord(entry) ? entry : {};
+        const reasoningEffort = normalizeReasoningEffortValue(option.reasoningEffort ?? option.effort ?? option.id);
+        if (!reasoningEffort || seen.has(reasoningEffort)) {
+            continue;
+        }
+        seen.add(reasoningEffort);
+        options.push({
+            reasoningEffort,
+            description: String(option.description ?? "").trim(),
+        });
+    }
+    return options;
+}
+function normalizeReasoningEffortValue(value) {
+    const normalized = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (normalized === "none" ||
+        normalized === "minimal" ||
+        normalized === "low" ||
+        normalized === "medium" ||
+        normalized === "high" ||
+        normalized === "xhigh") {
+        return normalized;
+    }
+    return null;
+}
 function runCodexCommand(args, { inputText = "" } = {}) {
     const codexBin = String(config.codexBin ?? "codex").trim() || "codex";
-    const result = spawnSync(codexBin, args, {
-        cwd: config.kernelRootPath,
-        shell: false,
-        stdio: ["pipe", "pipe", "pipe"],
-        windowsHide: true,
-        encoding: "utf8",
-        input: inputText,
-        env: process.env,
-    });
+    const result = requiresShellWrappedSpawn(codexBin)
+        ? spawnSync(buildShellWrappedCommandLine(codexBin, args), {
+            cwd: config.kernelRootPath,
+            shell: true,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            encoding: "utf8",
+            input: inputText,
+            env: process.env,
+        })
+        : spawnSync(codexBin, args, {
+            cwd: config.kernelRootPath,
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            encoding: "utf8",
+            input: inputText,
+            env: process.env,
+        });
     if (result.error) {
         return {
             ok: false,
@@ -764,6 +835,9 @@ function formatCodexSpawnError(codexBin, error) {
     if (code === "EPERM") {
         return `Codex binary '${codexBin}' cannot be executed (EPERM).`;
     }
+    if (code === "EINVAL" && requiresShellWrappedSpawn(codexBin)) {
+        return `Codex binary '${codexBin}' must be launched through the Windows shell.`;
+    }
     const message = error instanceof Error ? error.message : String(error);
     return `Failed to execute '${codexBin}': ${firstNonEmptyLine(message)}`;
 }

package/apps/control-plane/dist/channels/codex-quota-cache.js

@@ -0,0 +1,16 @@
+let cachedCodexUsage = null;
+export function readCachedCodexQuotaSnapshot(now) {
+    if (cachedCodexUsage && now < cachedCodexUsage.expiresAt) {
+        return cachedCodexUsage.snapshot;
+    }
+    return null;
+}
+export function writeCachedCodexQuotaSnapshot(snapshot, expiresAt) {
+    cachedCodexUsage = {
+        expiresAt,
+        snapshot,
+    };
+}
+export function invalidateCodexQuotaUsageCache() {
+    cachedCodexUsage = null;
+}