copilot-hub 0.1.28 → 0.1.29

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

@@ -1,12 +1,16 @@
 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 { loadCopilotHubEnvironment } from "@copilot-hub/core";
+import { resolveOptionalPathFromBase, resolvePathFromBase } from "@copilot-hub/core/config-paths";
 import { getDefaultExternalWorkspaceBasePath, getKernelRootPath, } from "@copilot-hub/core/workspace-paths";
-const envBaseDir = loadEnvironment();
+const loadedEnvironment = loadEnvironment();
+const envBaseDir = loadedEnvironment.baseDir;
+const envFilePath = loadedEnvironment.envPath;
+const envFileValues = loadedEnvironment.fileValues;
+const envOverrideKeys = loadedEnvironment.overriddenKeys;
 const kernelRootPath = getKernelRootPath();
 const configuredDefaultWorkspaceRoot = String(process.env.DEFAULT_WORKSPACE_ROOT ?? "").trim();
 const defaultWorkspaceRoot = resolveWorkspaceRoot(configuredDefaultWorkspaceRoot || getDefaultExternalWorkspaceBasePath(kernelRootPath));
@@ -85,6 +89,9 @@ const defaultAllowedChatIds = new Set((process.env.TELEGRAM_ALLOWED_CHAT_IDS ??
 fs.mkdirSync(dataDir, { recursive: true });
 export const config = {
     envBaseDir,
+    envFilePath,
+    envFileValues,
+    envOverrideKeys,
     defaultProviderKind,
     providerDefaults: {
         defaultKind: defaultProviderKind,
@@ -125,22 +132,9 @@ export const config = {
     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,
+    return loadCopilotHubEnvironment({
         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();

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

@@ -1,5 +1,5 @@
-HUB_TELEGRAM_TOKEN_ENV=HUB_TELEGRAM_TOKEN
-HUB_TELEGRAM_TOKEN=123456:replace_me
+HUB_TELEGRAM_TOKEN_ENV=HUB_TELEGRAM_TOKEN_FILE
+HUB_TELEGRAM_TOKEN_FILE=123456:replace_me
 HUB_ID=copilot_hub
 HUB_NAME=Copilot Hub
 # Optional. If empty, defaults to Desktop/copilot_workspaces (Windows/macOS/Linux)
@@ -21,4 +21,3 @@ CODEX_SANDBOX=danger-full-access
 CODEX_APPROVAL_POLICY=never
 TURN_ACTIVITY_TIMEOUT_MS=0
 MAX_THREAD_MESSAGES=200
-

package/apps/control-plane/dist/config.js

@@ -1,13 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import dotenv from "dotenv";
+import { loadCopilotHubEnvironment } from "@copilot-hub/core";
 import { parseTurnActivityTimeoutSetting } from "@copilot-hub/core/codex-app-utils";
-import { resolveConfigBaseDir, resolveOptionalPathFromBase, resolvePathFromBase, } from "@copilot-hub/core/config-paths";
+import { resolveOptionalPathFromBase, resolvePathFromBase } from "@copilot-hub/core/config-paths";
 import { createWorkspaceBoundaryPolicy, assertWorkspaceAllowed, parseWorkspaceAllowedRoots, } from "@copilot-hub/core/workspace-policy";
 import { normalizeAdminBotId, normalizeAdminTokenEnv } from "./kernel/admin-contract.js";
 import { getDefaultExternalWorkspaceBasePath, getKernelRootPath, } from "@copilot-hub/core/workspace-paths";
-const envBaseDir = loadEnvironment();
+const loadedEnvironment = loadEnvironment();
+const envBaseDir = loadedEnvironment.baseDir;
+const envFilePath = loadedEnvironment.envPath;
+const envFileValues = loadedEnvironment.fileValues;
+const envOverrideKeys = loadedEnvironment.overriddenKeys;
 const kernelRootPath = getKernelRootPath();
 const configuredDefaultWorkspaceRoot = String(process.env.DEFAULT_WORKSPACE_ROOT ?? "").trim();
 const defaultWorkspaceRoot = resolveWorkspaceRoot(configuredDefaultWorkspaceRoot || getDefaultExternalWorkspaceBasePath(kernelRootPath));
@@ -89,6 +93,9 @@ const defaultAllowedChatIds = new Set((process.env.TELEGRAM_ALLOWED_CHAT_IDS ??
 fs.mkdirSync(dataDir, { recursive: true });
 export const config = {
     envBaseDir,
+    envFilePath,
+    envFileValues,
+    envOverrideKeys,
     defaultProviderKind,
     providerDefaults: {
         defaultKind: defaultProviderKind,
@@ -132,22 +139,9 @@ export const config = {
     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,
+    return loadCopilotHubEnvironment({
         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();

package/apps/control-plane/dist/copilot-hub.js

@@ -3,16 +3,20 @@ import { BotRuntime } from "@copilot-hub/core/bot-runtime";
 import { config } from "./config.js";
 import { assertWorkspaceAllowed } from "@copilot-hub/core/workspace-policy";
 import { createChannelAdapter } from "./channels/channel-factory.js";
-const TELEGRAM_TOKEN_PATTERN = /^\d{5,}:[A-Za-z0-9_-]{20,}$/;
-const tokenEnvName = String(process.env.HUB_TELEGRAM_TOKEN_ENV ?? "HUB_TELEGRAM_TOKEN").trim() || "HUB_TELEGRAM_TOKEN";
-const hubToken = String(process.env[tokenEnvName] ?? "").trim();
+import { isUsableTelegramToken, resolveHubTelegramToken } from "./hub-token-config.js";
+const tokenResolution = resolveHubTelegramToken({
+    env: process.env,
+    envFileValues: config.envFileValues,
+});
+const tokenEnvName = tokenResolution.tokenEnvName;
+const hubToken = tokenResolution.token;
 if (!hubToken) {
     throw new Error([
         `Hub Telegram token is missing (${tokenEnvName}).`,
         "Set this token to start copilot-hub.",
     ].join("\n"));
 }
-if (!TELEGRAM_TOKEN_PATTERN.test(hubToken) || hubToken.toLowerCase().includes("replace_me")) {
+if (!isUsableTelegramToken(hubToken)) {
     throw new Error([
         `Hub Telegram token in ${tokenEnvName} is invalid.`,
         "Run 'copilot-hub configure' and paste a real BotFather token.",
@@ -73,6 +77,14 @@ const runtime = new BotRuntime({
 let shuttingDown = false;
 await bootstrap();
 async function bootstrap() {
+    for (const warning of tokenResolution.warnings) {
+        console.warn(`[copilot_hub] ${warning}`);
+    }
+    if (config.envOverrideKeys.includes("HUB_TELEGRAM_TOKEN_ENV") ||
+        config.envOverrideKeys.includes(tokenEnvName)) {
+        console.warn(`[copilot_hub] Config file '${config.envFilePath ?? ".env"}' overrode a pre-existing process environment value for the hub token settings.`);
+    }
+    console.log(`[copilot_hub] using hub Telegram token variable '${tokenEnvName}' from ${tokenResolution.source === "env_file" ? "config file" : "process environment"}.`);
     await runtime.startChannels();
     console.log(`[copilot_hub] online as '${hubId}' on workspace '${hubWorkspaceRoot}'.`);
     registerSignals();

package/apps/control-plane/dist/hub-token-config.js

@@ -0,0 +1,37 @@
+const DEFAULT_HUB_TELEGRAM_TOKEN_ENV = "HUB_TELEGRAM_TOKEN_FILE";
+const LEGACY_HUB_TELEGRAM_TOKEN_ENV = "HUB_TELEGRAM_TOKEN";
+const TELEGRAM_TOKEN_PATTERN = /^\d{5,}:[A-Za-z0-9_-]{20,}$/;
+export function resolveHubTelegramToken({ env = process.env, envFileValues = {}, } = {}) {
+    const fileTokenEnvName = String(envFileValues.HUB_TELEGRAM_TOKEN_ENV ?? "").trim();
+    const processTokenEnvName = String(env.HUB_TELEGRAM_TOKEN_ENV ?? "").trim();
+    const tokenEnvName = fileTokenEnvName || processTokenEnvName || DEFAULT_HUB_TELEGRAM_TOKEN_ENV;
+    const fileToken = String(envFileValues[tokenEnvName] ?? "").trim();
+    const processToken = String(env[tokenEnvName] ?? "").trim();
+    const token = fileToken || processToken;
+    const warnings = [];
+    if (fileTokenEnvName && processTokenEnvName && fileTokenEnvName !== processTokenEnvName) {
+        warnings.push(`Config file selects hub token variable '${fileTokenEnvName}', overriding pre-existing process env selector '${processTokenEnvName}'.`);
+    }
+    if (tokenEnvName === LEGACY_HUB_TELEGRAM_TOKEN_ENV) {
+        warnings.push(`Hub token variable '${LEGACY_HUB_TELEGRAM_TOKEN_ENV}' is deprecated. Run 'copilot-hub configure' to migrate to '${DEFAULT_HUB_TELEGRAM_TOKEN_ENV}'.`);
+    }
+    if (fileToken && processToken && fileToken !== processToken) {
+        const detail = isUsableTelegramToken(fileToken)
+            ? `Using the token saved in the config file for '${tokenEnvName}' instead of the conflicting process environment value.`
+            : `Config file value for '${tokenEnvName}' overrides the conflicting process environment value.`;
+        warnings.push(detail);
+    }
+    return {
+        tokenEnvName,
+        token,
+        source: fileToken ? "env_file" : "process_env",
+        warnings,
+    };
+}
+export function isUsableTelegramToken(value) {
+    const token = String(value ?? "").trim();
+    if (!token || token.toLowerCase().includes("replace_me")) {
+        return false;
+    }
+    return TELEGRAM_TOKEN_PATTERN.test(token);
+}

package/apps/control-plane/dist/test/hub-token-config.test.js

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+let configPromise = null;
+async function loadConfig() {
+    if (!configPromise) {
+        const specifier = ["..", "hub-token-config.js"].join("/");
+        configPromise = import(specifier);
+    }
+    return configPromise;
+}
+test("resolveHubTelegramToken prefers the config file token over a conflicting process env token", async () => {
+    const { resolveHubTelegramToken } = await loadConfig();
+    const result = resolveHubTelegramToken({
+        env: {
+            HUB_TELEGRAM_TOKEN_ENV: "HUB_TELEGRAM_TOKEN",
+            HUB_TELEGRAM_TOKEN: "123456:invalid_process_value_ABCDEFGHIJKLM",
+        },
+        envFileValues: {
+            HUB_TELEGRAM_TOKEN_ENV: "HUB_TELEGRAM_TOKEN",
+            HUB_TELEGRAM_TOKEN: "123456:valid_file_value_ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+        },
+    });
+    assert.equal(result.tokenEnvName, "HUB_TELEGRAM_TOKEN");
+    assert.equal(result.source, "env_file");
+    assert.equal(result.token, "123456:valid_file_value_ABCDEFGHIJKLMNOPQRSTUVWXYZ");
+    assert.match(result.warnings.join("\n"), /deprecated/i);
+});
+test("resolveHubTelegramToken uses the dedicated file token variable by default", async () => {
+    const { resolveHubTelegramToken } = await loadConfig();
+    const result = resolveHubTelegramToken({
+        env: {},
+        envFileValues: {
+            HUB_TELEGRAM_TOKEN_ENV: "HUB_TELEGRAM_TOKEN_FILE",
+            HUB_TELEGRAM_TOKEN_FILE: "123456:valid_file_value_ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+        },
+    });
+    assert.equal(result.tokenEnvName, "HUB_TELEGRAM_TOKEN_FILE");
+    assert.equal(result.source, "env_file");
+    assert.equal(result.warnings.length, 0);
+});
+test("isUsableTelegramToken recognizes valid telegram token formats", async () => {
+    const { isUsableTelegramToken } = await loadConfig();
+    assert.equal(isUsableTelegramToken("123456:valid_file_value_ABCDEFGHIJKLMNOPQRSTUVWXYZ"), true);
+    assert.equal(isUsableTelegramToken("123456:replace_me"), false);
+    assert.equal(isUsableTelegramToken(""), false);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-hub",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "Copilot Hub CLI and runtime bundle",
   "license": "MIT",
   "repository": {

package/packages/core/dist/env-config.d.ts

@@ -0,0 +1,10 @@
+export interface LoadedCopilotHubEnvironment {
+    baseDir: string;
+    envPath: string | null;
+    fileValues: Record<string, string>;
+    overriddenKeys: string[];
+}
+export declare function loadCopilotHubEnvironment({ env, cwd, }?: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}): LoadedCopilotHubEnvironment;

package/packages/core/dist/env-config.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import dotenv from "dotenv";
+import { resolveConfigBaseDir } from "./config-paths.js";
+export function loadCopilotHubEnvironment({ env = process.env, cwd = process.cwd(), } = {}) {
+    const configuredEnvPath = String(env.COPILOT_HUB_ENV_PATH ?? "").trim();
+    const resolvedEnvPath = configuredEnvPath ? path.resolve(configuredEnvPath) : "";
+    const discoveredEnvPath = resolvedEnvPath || resolveDefaultEnvPath(cwd);
+    const baseDir = resolveConfigBaseDir({
+        configuredBaseDir: env.COPILOT_HUB_ENV_BASE_DIR,
+        configuredEnvPath: discoveredEnvPath,
+        cwd,
+    });
+    const fileValues = loadEnvFileValues(discoveredEnvPath);
+    const overriddenKeys = applyEnvFileValues(env, fileValues);
+    if (resolvedEnvPath) {
+        env.COPILOT_HUB_ENV_PATH = resolvedEnvPath;
+    }
+    env.COPILOT_HUB_ENV_BASE_DIR = baseDir;
+    return {
+        baseDir,
+        envPath: discoveredEnvPath || null,
+        fileValues,
+        overriddenKeys,
+    };
+}
+function resolveDefaultEnvPath(cwd) {
+    const candidate = path.resolve(String(cwd ?? process.cwd()), ".env");
+    return fs.existsSync(candidate) ? candidate : "";
+}
+function loadEnvFileValues(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        return normalizeEnvMap(dotenv.parse(raw));
+    }
+    catch {
+        return {};
+    }
+}
+function applyEnvFileValues(env, fileValues) {
+    const overriddenKeys = [];
+    for (const [key, value] of Object.entries(fileValues)) {
+        const previousValue = String(env[key] ?? "");
+        if (previousValue && previousValue !== value) {
+            overriddenKeys.push(key);
+        }
+        env[key] = value;
+    }
+    return overriddenKeys.sort();
+}
+function normalizeEnvMap(value) {
+    const output = {};
+    for (const [key, entry] of Object.entries(value ?? {})) {
+        const normalizedKey = String(key ?? "").trim();
+        if (!normalizedKey) {
+            continue;
+        }
+        output[normalizedKey] = String(entry ?? "").trim();
+    }
+    return output;
+}
+//# sourceMappingURL=env-config.js.map

package/packages/core/dist/env-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-config.js","sourceRoot":"","sources":["../src/env-config.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { createWorkspaceBoundaryPolicy, assertWorkspaceAllowed, isPathInside, normalizeAbsolutePath, parseWorkspaceAllowedRoots, } from "./workspace-policy.js";
 export { normalizeThreadId } from "./thread-id.js";
 export { createProjectFingerprint } from "./project-fingerprint.js";
-export { DEFAULT_EXTERNAL_WORKSPACES_DIRNAME, getKernelRootPath, getDefaultExternalWorkspaceBasePath, resolveDefaultWorkspaceForBot, isPathInside as isWorkspacePathInside, } from "./workspace-paths.js";
+export { DEFAULT_EXTERNAL_WORKSPACES_DIRNAME, getKernelRootPath, resolveKernelRootPath, getDefaultExternalWorkspaceBasePath, resolveExternalWorkspaceBasePath, resolveDefaultWorkspaceForBot, isPathInside as isWorkspacePathInside, } from "./workspace-paths.js";
 export { resolveConfigBaseDir, resolveProcessConfigBaseDir, resolvePathFromBase, resolveOptionalPathFromBase, } from "./config-paths.js";
+export { loadCopilotHubEnvironment } from "./env-config.js";
 export { InstanceLock } from "./instance-lock.js";
 export { JsonStateStore } from "./state-store.js";
 export { assertControlPermission } from "./control-permission.js";

package/packages/core/dist/index.js

@@ -1,8 +1,9 @@
 export { createWorkspaceBoundaryPolicy, assertWorkspaceAllowed, isPathInside, normalizeAbsolutePath, parseWorkspaceAllowedRoots, } from "./workspace-policy.js";
 export { normalizeThreadId } from "./thread-id.js";
 export { createProjectFingerprint } from "./project-fingerprint.js";
-export { DEFAULT_EXTERNAL_WORKSPACES_DIRNAME, getKernelRootPath, getDefaultExternalWorkspaceBasePath, resolveDefaultWorkspaceForBot, isPathInside as isWorkspacePathInside, } from "./workspace-paths.js";
+export { DEFAULT_EXTERNAL_WORKSPACES_DIRNAME, getKernelRootPath, resolveKernelRootPath, getDefaultExternalWorkspaceBasePath, resolveExternalWorkspaceBasePath, resolveDefaultWorkspaceForBot, isPathInside as isWorkspacePathInside, } from "./workspace-paths.js";
 export { resolveConfigBaseDir, resolveProcessConfigBaseDir, resolvePathFromBase, resolveOptionalPathFromBase, } from "./config-paths.js";
+export { loadCopilotHubEnvironment } from "./env-config.js";
 export { InstanceLock } from "./instance-lock.js";
 export { JsonStateStore } from "./state-store.js";
 export { assertControlPermission } from "./control-permission.js";

package/packages/core/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,YAAY,EACZ,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EACL,mCAAmC,EACnC,iBAAiB,EACjB,mCAAmC,EACnC,6BAA6B,EAC7B,YAAY,IAAI,qBAAqB,GACtC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,YAAY,EACZ,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EACL,mCAAmC,EACnC,iBAAiB,EACjB,qBAAqB,EACrB,mCAAmC,EACnC,gCAAgC,EAChC,6BAA6B,EAC7B,YAAY,IAAI,qBAAqB,GACtC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/packages/core/dist/workspace-paths.d.ts

@@ -1,5 +1,16 @@
 export declare const DEFAULT_EXTERNAL_WORKSPACES_DIRNAME = "copilot_workspaces";
 export declare function getKernelRootPath(): string;
-export declare function getDefaultExternalWorkspaceBasePath(_kernelRoot?: string): string;
+export declare function resolveKernelRootPath({ env, moduleUrl, cwd, }?: {
+    env?: NodeJS.ProcessEnv;
+    moduleUrl?: string;
+    cwd?: string;
+}): string;
+export declare function getDefaultExternalWorkspaceBasePath(kernelRoot?: string): string;
+export declare function resolveExternalWorkspaceBasePath({ kernelRootPath, desktopCandidates, homeDir, tempDir, }: {
+    kernelRootPath: string;
+    desktopCandidates?: readonly string[];
+    homeDir?: string;
+    tempDir?: string;
+}): string;
 export declare function resolveDefaultWorkspaceForBot(botId: unknown, kernelRoot?: string): string;
 export declare function isPathInside(parentPath: unknown, candidatePath: unknown): boolean;

package/packages/core/dist/workspace-paths.js

@@ -1,18 +1,42 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
 export const DEFAULT_EXTERNAL_WORKSPACES_DIRNAME = "copilot_workspaces";
 const DESKTOP_DIRNAME = "Desktop";
 export function getKernelRootPath() {
-    return path.resolve(process.cwd());
+    return resolveKernelRootPath();
 }
-export function getDefaultExternalWorkspaceBasePath(_kernelRoot = getKernelRootPath()) {
-    const desktopCandidates = getDesktopCandidates();
-    const fallbackDesktop = path.resolve(process.cwd(), DESKTOP_DIRNAME);
+export function resolveKernelRootPath({ env = process.env, moduleUrl = import.meta.url, cwd = process.cwd(), } = {}) {
+    const configuredRoot = String(env.COPILOT_HUB_KERNEL_ROOT ?? "").trim();
+    if (configuredRoot) {
+        return path.resolve(configuredRoot);
+    }
+    const moduleFilePath = String(moduleUrl ?? "").trim();
+    if (moduleFilePath) {
+        return path.resolve(path.dirname(fileURLToPath(moduleFilePath)), "..", "..", "..");
+    }
+    return path.resolve(String(cwd ?? process.cwd()));
+}
+export function getDefaultExternalWorkspaceBasePath(kernelRoot = getKernelRootPath()) {
+    return resolveExternalWorkspaceBasePath({
+        kernelRootPath: kernelRoot,
+    });
+}
+export function resolveExternalWorkspaceBasePath({ kernelRootPath, desktopCandidates = getDesktopCandidates(), homeDir = os.homedir(), tempDir = os.tmpdir(), }) {
     const desktopRoot = desktopCandidates.find((candidate) => directoryExists(candidate)) ??
         desktopCandidates[0] ??
-        fallbackDesktop;
-    return path.resolve(desktopRoot, DEFAULT_EXTERNAL_WORKSPACES_DIRNAME);
+        path.resolve(String(homeDir ?? "").trim() || process.cwd(), DESKTOP_DIRNAME);
+    const preferredRoot = path.resolve(desktopRoot, DEFAULT_EXTERNAL_WORKSPACES_DIRNAME);
+    if (!isPathInside(kernelRootPath, preferredRoot)) {
+        return preferredRoot;
+    }
+    const homeFallbackRoot = path.resolve(String(homeDir ?? "").trim() || process.cwd(), DEFAULT_EXTERNAL_WORKSPACES_DIRNAME);
+    if (!isPathInside(kernelRootPath, homeFallbackRoot)) {
+        return homeFallbackRoot;
+    }
+    return path.resolve(String(tempDir ?? "").trim() || process.cwd(), DEFAULT_EXTERNAL_WORKSPACES_DIRNAME);
 }
 export function resolveDefaultWorkspaceForBot(botId, kernelRoot = getKernelRootPath()) {
     const id = String(botId ?? "").trim();

package/packages/core/dist/workspace-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-paths.js","sourceRoot":"","sources":["../src/workspace-paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspace-paths.js","sourceRoot":"","sources":["../src/workspace-paths.ts"],"names":[],"mappings":"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"}

package/packages/core/package.json

@@ -34,6 +34,10 @@
       "types": "./dist/config-paths.d.ts",
       "import": "./dist/config-paths.js"
     },
+    "./env-config": {
+      "types": "./dist/env-config.d.ts",
+      "import": "./dist/env-config.js"
+    },
     "./instance-lock": {
       "types": "./dist/instance-lock.d.ts",
       "import": "./dist/instance-lock.js"

package/scripts/dist/configure.mjs

@@ -15,7 +15,8 @@ const engineExamplePath = path.join(repoRoot, "apps", "agent-engine", ".env.exam
 const controlPlaneEnvPath = layout.controlPlaneEnvPath;
 const controlPlaneExamplePath = path.join(repoRoot, "apps", "control-plane", ".env.example");
 const TELEGRAM_TOKEN_PATTERN = /^\d{5,}:[A-Za-z0-9_-]{20,}$/;
-const DEFAULT_CONTROL_PLANE_TOKEN_ENV = "HUB_TELEGRAM_TOKEN";
+const DEFAULT_CONTROL_PLANE_TOKEN_ENV = "HUB_TELEGRAM_TOKEN_FILE";
+const LEGACY_CONTROL_PLANE_TOKEN_ENV = "HUB_TELEGRAM_TOKEN";
 const args = new Set(process.argv.slice(2));
 const requiredOnly = args.has("--required-only");
 await main();
@@ -44,9 +45,7 @@ async function main() {
     writeLines(controlPlaneEnvPath, controlPlaneLines);
 }
 async function configureRequiredTokens({ rl, controlPlaneLines }) {
-    const controlPlaneMap = parseEnvMap(controlPlaneLines);
-    const controlPlaneTokenEnvName = nonEmpty(controlPlaneMap.HUB_TELEGRAM_TOKEN_ENV, DEFAULT_CONTROL_PLANE_TOKEN_ENV);
-    setEnvValue(controlPlaneLines, "HUB_TELEGRAM_TOKEN_ENV", controlPlaneTokenEnvName);
+    const controlPlaneTokenEnvName = migrateControlPlaneTokenEnv(controlPlaneLines);
     const postControlPlaneMap = parseEnvMap(controlPlaneLines);
     const currentToken = String(postControlPlaneMap[controlPlaneTokenEnvName] ?? "").trim();
     if (isUsableTelegramToken(currentToken)) {
@@ -62,10 +61,8 @@ async function configureRequiredTokens({ rl, controlPlaneLines }) {
     console.log("Required token saved.");
 }
 async function configureAll({ rl, controlPlaneLines }) {
-    const controlPlaneMap = parseEnvMap(controlPlaneLines);
     console.log("\nCopilot Hub control-plane configuration\n");
-    const controlPlaneTokenEnvDefault = nonEmpty(controlPlaneMap.HUB_TELEGRAM_TOKEN_ENV, DEFAULT_CONTROL_PLANE_TOKEN_ENV);
-    setEnvValue(controlPlaneLines, "HUB_TELEGRAM_TOKEN_ENV", controlPlaneTokenEnvDefault);
+    const controlPlaneTokenEnvDefault = migrateControlPlaneTokenEnv(controlPlaneLines);
     const currentControlPlaneToken = String(parseEnvMap(controlPlaneLines)[controlPlaneTokenEnvDefault] ?? "").trim();
     const newControlPlaneToken = currentControlPlaneToken
         ? await askTelegramToken(rl, "Control-plane Telegram token (press Enter to keep current)", true)
@@ -77,6 +74,23 @@ async function configureAll({ rl, controlPlaneLines }) {
         console.log("- Control-plane token left unchanged.");
     }
 }
+function migrateControlPlaneTokenEnv(lines) {
+    const controlPlaneMap = parseEnvMap(lines);
+    const configuredTokenEnvName = nonEmpty(controlPlaneMap.HUB_TELEGRAM_TOKEN_ENV, DEFAULT_CONTROL_PLANE_TOKEN_ENV);
+    const shouldMigrateLegacyName = configuredTokenEnvName === LEGACY_CONTROL_PLANE_TOKEN_ENV;
+    const nextTokenEnvName = shouldMigrateLegacyName
+        ? DEFAULT_CONTROL_PLANE_TOKEN_ENV
+        : configuredTokenEnvName;
+    setEnvValue(lines, "HUB_TELEGRAM_TOKEN_ENV", nextTokenEnvName);
+    if (shouldMigrateLegacyName) {
+        const legacyToken = String(controlPlaneMap[LEGACY_CONTROL_PLANE_TOKEN_ENV] ?? "").trim();
+        const dedicatedToken = String(controlPlaneMap[DEFAULT_CONTROL_PLANE_TOKEN_ENV] ?? "").trim();
+        if (legacyToken && !dedicatedToken) {
+            setEnvValue(lines, DEFAULT_CONTROL_PLANE_TOKEN_ENV, legacyToken);
+        }
+    }
+    return nextTokenEnvName;
+}
 function ensureEnvFile(envPath, examplePath) {
     fs.mkdirSync(path.dirname(envPath), { recursive: true });
     if (fs.existsSync(envPath)) {

package/scripts/dist/daemon.mjs

@@ -508,6 +508,23 @@ function detectFatalStartupError(ensureResult) {
             detectedAt: new Date().toISOString(),
         };
     }
+    const invalidHubTokenLine = findLineContaining(evidenceChunks, (line) => line.includes("hub telegram token in") && line.includes("is invalid"));
+    if (invalidHubTokenLine) {
+        return {
+            reason: invalidHubTokenLine,
+            action: "Run 'copilot-hub configure' to save a valid hub token in the control-plane config, then retry service.",
+            detectedAt: new Date().toISOString(),
+        };
+    }
+    const workspaceRootLine = findLineContaining(evidenceChunks, (line) => line.includes("default_workspace_root must be outside kernel directory") ||
+        line.includes("hub_workspace_root must be outside kernel directory"));
+    if (workspaceRootLine) {
+        return {
+            reason: workspaceRootLine,
+            action: "Set DEFAULT_WORKSPACE_ROOT to a folder outside the copilot-hub installation, then retry service.",
+            detectedAt: new Date().toISOString(),
+        };
+    }
     return null;
 }
 function readLogTail(filePath, maxLines = 120) {

package/scripts/src/configure.mts

@@ -18,7 +18,8 @@ const engineExamplePath = path.join(repoRoot, "apps", "agent-engine", ".env.exam
 const controlPlaneEnvPath = layout.controlPlaneEnvPath;
 const controlPlaneExamplePath = path.join(repoRoot, "apps", "control-plane", ".env.example");
 const TELEGRAM_TOKEN_PATTERN = /^\d{5,}:[A-Za-z0-9_-]{20,}$/;
-const DEFAULT_CONTROL_PLANE_TOKEN_ENV = "HUB_TELEGRAM_TOKEN";
+const DEFAULT_CONTROL_PLANE_TOKEN_ENV = "HUB_TELEGRAM_TOKEN_FILE";
+const LEGACY_CONTROL_PLANE_TOKEN_ENV = "HUB_TELEGRAM_TOKEN";
 
 const args = new Set(process.argv.slice(2));
 const requiredOnly = args.has("--required-only");
@@ -53,13 +54,7 @@ async function main() {
 }
 
 async function configureRequiredTokens({ rl, controlPlaneLines }) {
-  const controlPlaneMap = parseEnvMap(controlPlaneLines);
-
-  const controlPlaneTokenEnvName = nonEmpty(
-    controlPlaneMap.HUB_TELEGRAM_TOKEN_ENV,
-    DEFAULT_CONTROL_PLANE_TOKEN_ENV,
-  );
-  setEnvValue(controlPlaneLines, "HUB_TELEGRAM_TOKEN_ENV", controlPlaneTokenEnvName);
+  const controlPlaneTokenEnvName = migrateControlPlaneTokenEnv(controlPlaneLines);
 
   const postControlPlaneMap = parseEnvMap(controlPlaneLines);
   const currentToken = String(postControlPlaneMap[controlPlaneTokenEnvName] ?? "").trim();
@@ -82,15 +77,9 @@ async function configureRequiredTokens({ rl, controlPlaneLines }) {
 }
 
 async function configureAll({ rl, controlPlaneLines }) {
-  const controlPlaneMap = parseEnvMap(controlPlaneLines);
-
   console.log("\nCopilot Hub control-plane configuration\n");
 
-  const controlPlaneTokenEnvDefault = nonEmpty(
-    controlPlaneMap.HUB_TELEGRAM_TOKEN_ENV,
-    DEFAULT_CONTROL_PLANE_TOKEN_ENV,
-  );
-  setEnvValue(controlPlaneLines, "HUB_TELEGRAM_TOKEN_ENV", controlPlaneTokenEnvDefault);
+  const controlPlaneTokenEnvDefault = migrateControlPlaneTokenEnv(controlPlaneLines);
   const currentControlPlaneToken = String(
     parseEnvMap(controlPlaneLines)[controlPlaneTokenEnvDefault] ?? "",
   ).trim();
@@ -106,6 +95,29 @@ async function configureAll({ rl, controlPlaneLines }) {
   }
 }
 
+function migrateControlPlaneTokenEnv(lines) {
+  const controlPlaneMap = parseEnvMap(lines);
+  const configuredTokenEnvName = nonEmpty(
+    controlPlaneMap.HUB_TELEGRAM_TOKEN_ENV,
+    DEFAULT_CONTROL_PLANE_TOKEN_ENV,
+  );
+  const shouldMigrateLegacyName = configuredTokenEnvName === LEGACY_CONTROL_PLANE_TOKEN_ENV;
+  const nextTokenEnvName = shouldMigrateLegacyName
+    ? DEFAULT_CONTROL_PLANE_TOKEN_ENV
+    : configuredTokenEnvName;
+  setEnvValue(lines, "HUB_TELEGRAM_TOKEN_ENV", nextTokenEnvName);
+
+  if (shouldMigrateLegacyName) {
+    const legacyToken = String(controlPlaneMap[LEGACY_CONTROL_PLANE_TOKEN_ENV] ?? "").trim();
+    const dedicatedToken = String(controlPlaneMap[DEFAULT_CONTROL_PLANE_TOKEN_ENV] ?? "").trim();
+    if (legacyToken && !dedicatedToken) {
+      setEnvValue(lines, DEFAULT_CONTROL_PLANE_TOKEN_ENV, legacyToken);
+    }
+  }
+
+  return nextTokenEnvName;
+}
+
 function ensureEnvFile(envPath, examplePath) {
   fs.mkdirSync(path.dirname(envPath), { recursive: true });
   if (fs.existsSync(envPath)) {

package/scripts/src/daemon.mts

@@ -600,6 +600,34 @@ function detectFatalStartupError(ensureResult) {
     };
   }
 
+  const invalidHubTokenLine = findLineContaining(
+    evidenceChunks,
+    (line) => line.includes("hub telegram token in") && line.includes("is invalid"),
+  );
+  if (invalidHubTokenLine) {
+    return {
+      reason: invalidHubTokenLine,
+      action:
+        "Run 'copilot-hub configure' to save a valid hub token in the control-plane config, then retry service.",
+      detectedAt: new Date().toISOString(),
+    };
+  }
+
+  const workspaceRootLine = findLineContaining(
+    evidenceChunks,
+    (line) =>
+      line.includes("default_workspace_root must be outside kernel directory") ||
+      line.includes("hub_workspace_root must be outside kernel directory"),
+  );
+  if (workspaceRootLine) {
+    return {
+      reason: workspaceRootLine,
+      action:
+        "Set DEFAULT_WORKSPACE_ROOT to a folder outside the copilot-hub installation, then retry service.",
+      detectedAt: new Date().toISOString(),
+    };
+  }
+
   return null;
 }