@borgee/agents-host 0.1.6 → 0.1.8

package/dist/cli-args.js

@@ -1,8 +1,8 @@
 /**
- * Maps `agents-host start` CLI flags to the env vars `config.ts` reads.
- * Keeping this as a plain lookup table (rather than duplicating
- * `loadConfigFromEnv`'s parsing logic) means the CLI and the plain
- * env-var entry point (`index.ts`) always agree on defaults/validation.
+ * Maps single-agent `agents-host start` CLI flags to the env vars `config.ts`
+ * reads. Keeping this as a plain lookup table (rather than duplicating
+ * `loadConfigFromEnv`'s parsing logic) means the CLI and the env-var entry
+ * point (`index.ts`) always agree on defaults/validation.
  */
 export const CLI_FLAG_TO_ENV = {
     name: 'BORGEE_AGENT_NAME',
@@ -11,56 +11,246 @@ export const CLI_FLAG_TO_ENV = {
     'claude-args': 'CLAUDE_ARGS',
     'copilot-command': 'COPILOT_COMMAND',
     'copilot-args': 'COPILOT_ARGS',
+    'copilot-session-ttl-minutes': 'COPILOT_SESSION_TTL_MINUTES',
 };
+const SINGLE_AGENT_FLAG_NAMES = new Set(Object.keys(CLI_FLAG_TO_ENV));
 export class CliUsageError extends Error {
 }
-/**
- * Parses `start <serverUrl> <apiKey> [--flag value ...]` (the argv slice
- * after the `start` command word). Throws `CliUsageError` with a
- * human-readable message on any usage problem instead of exiting the
- * process, so callers (and tests) can decide how to report it.
- */
 export function parseStartArgs(argv) {
     const positionals = [];
     const env = {};
+    const seenSingleAgentFlags = new Set();
+    let configPath;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        if (arg.startsWith('--')) {
-            const flag = arg.slice(2);
-            const value = argv[i + 1];
-            if (value === undefined || value.startsWith('--')) {
-                throw new CliUsageError(`Missing value for --${flag}`);
-            }
-            const envKey = CLI_FLAG_TO_ENV[flag];
-            if (!envKey) {
-                throw new CliUsageError(`Unknown option: --${flag}`);
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('--')) {
+            throw new CliUsageError(`Missing value for --${flag}`);
+        }
+        if (flag === 'config') {
+            if (configPath !== undefined) {
+                throw new CliUsageError('--config may only be specified once');
             }
-            env[envKey] = value;
+            configPath = value;
             i++;
+            continue;
         }
-        else {
-            positionals.push(arg);
+        const envKey = CLI_FLAG_TO_ENV[flag];
+        if (!envKey) {
+            throw new CliUsageError(`Unknown option: --${flag}`);
         }
+        env[envKey] = value;
+        seenSingleAgentFlags.add(flag);
+        i++;
+    }
+    if (configPath !== undefined) {
+        if (positionals.length > 0) {
+            throw new CliUsageError('Cannot combine --config with <serverUrl> <apiKey>');
+        }
+        if (seenSingleAgentFlags.size > 0) {
+            throw new CliUsageError(`Cannot combine --config with single-agent option --${[...seenSingleAgentFlags][0]}`);
+        }
+        return {
+            mode: 'local-config',
+            configPath,
+        };
     }
     const [serverUrl, apiKey, ...extra] = positionals;
-    if (!serverUrl)
+    if (!serverUrl) {
         throw new CliUsageError('Missing <serverUrl>');
-    if (!apiKey)
+    }
+    if (!apiKey) {
         throw new CliUsageError('Missing <apiKey>');
-    if (extra.length > 0)
+    }
+    if (extra.length > 0) {
         throw new CliUsageError(`Unexpected argument: ${extra[0]}`);
-    return { serverUrl, apiKey, env };
+    }
+    return {
+        mode: 'single-agent',
+        serverUrl,
+        apiKey,
+        env,
+    };
+}
+export function parseValidateArgs(argv) {
+    const positionals = [];
+    let configPath;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'config') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new CliUsageError('Missing value for --config');
+            }
+            if (configPath !== undefined) {
+                throw new CliUsageError('--config may only be specified once');
+            }
+            configPath = value;
+            i++;
+            continue;
+        }
+        if (SINGLE_AGENT_FLAG_NAMES.has(flag)) {
+            throw new CliUsageError(`Validate accepts only --config; cannot use single-agent option --${flag}`);
+        }
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    if (positionals.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${positionals[0]}`);
+    }
+    if (!configPath) {
+        throw new CliUsageError('Missing required --config <path>');
+    }
+    return { configPath };
 }
-export const USAGE = `Usage: agents-host start <serverUrl> <apiKey> [options]
+export function parseDescribeArgs(argv) {
+    const parsed = parseValidateArgs(argv);
+    return { configPath: parsed.configPath };
+}
+export function parsePrintLayoutArgs(argv) {
+    const positionals = [];
+    let rootPath;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'root') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new CliUsageError('Missing value for --root');
+            }
+            if (rootPath !== undefined) {
+                throw new CliUsageError('--root may only be specified once');
+            }
+            rootPath = value;
+            i++;
+            continue;
+        }
+        if (flag === 'config') {
+            throw new CliUsageError('print-layout accepts only --root; cannot use --config');
+        }
+        if (SINGLE_AGENT_FLAG_NAMES.has(flag)) {
+            throw new CliUsageError(`print-layout accepts only --root; cannot use single-agent option --${flag}`);
+        }
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    if (positionals.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${positionals[0]}`);
+    }
+    if (!rootPath) {
+        throw new CliUsageError('Missing required --root <dir>');
+    }
+    return { rootPath };
+}
+export function parseGenerateConfigArgs(argv) {
+    const positionals = [];
+    let rootPath;
+    let specJson;
+    let stdin = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'stdin') {
+            if (stdin) {
+                throw new CliUsageError('--stdin may only be specified once');
+            }
+            stdin = true;
+            continue;
+        }
+        if (flag === 'root' || flag === 'spec-json') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new CliUsageError(`Missing value for --${flag}`);
+            }
+            if (flag === 'root') {
+                if (rootPath !== undefined) {
+                    throw new CliUsageError('--root may only be specified once');
+                }
+                rootPath = value;
+            }
+            else {
+                if (specJson !== undefined) {
+                    throw new CliUsageError('--spec-json may only be specified once');
+                }
+                specJson = value;
+            }
+            i++;
+            continue;
+        }
+        if (flag === 'config') {
+            throw new CliUsageError('generate-config accepts only --root and --spec-json; cannot use --config');
+        }
+        if (SINGLE_AGENT_FLAG_NAMES.has(flag)) {
+            throw new CliUsageError(`generate-config accepts only --root and --spec-json; cannot use single-agent option --${flag}`);
+        }
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    if (positionals.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${positionals[0]}`);
+    }
+    if (!rootPath) {
+        throw new CliUsageError('Missing required --root <dir>');
+    }
+    if (stdin && specJson !== undefined) {
+        throw new CliUsageError('generate-config accepts exactly one input source: --stdin or --spec-json');
+    }
+    if (stdin) {
+        return { rootPath, input: 'stdin' };
+    }
+    if (!specJson) {
+        throw new CliUsageError('Missing required input: use --stdin or --spec-json <json>');
+    }
+    return { rootPath, input: 'argv', specJson };
+}
+export const USAGE = `Usage:
+  agents-host start <serverUrl> <apiKey> [options]
+  agents-host start --config <path-to-host-config>
+  agents-host validate --config <path-to-host-config>
+  agents-host describe --config <path-to-host-config>
+  agents-host print-layout --root <dir>
+  agents-host generate-config --root <dir> --stdin
+  agents-host generate-config --root <dir> --spec-json <json>
 
-Options:
-  --name <name>                 Display name (default: Assistant)
-  --provider <claude|copilot>   Runtime provider (default: claude)
-  --claude-command <cmd>        Local Claude CLI command (default: claude)
-  --claude-args <args>          Local Claude CLI args (default: --print)
+Single-agent options:
+  --name <name>                   Display name (default: Assistant)
+  --provider <claude|copilot>     Runtime provider (default: claude)
+  --claude-command <cmd>          Local Claude CLI command (default: claude)
+  --claude-args <args>            Local Claude CLI args (default: --print)
   --copilot-command <cmd>         Local Copilot CLI command (default: copilot)
   --copilot-args <args>           Ignored by the Copilot ACP prototype
+  --copilot-session-ttl-minutes <minutes>
+                                   Idle session TTL for Copilot ACP sessions (default: 2880)
+
+Local-config mode:
+  start --config <path>           Start agents + supervisor + watchers from a host config file
+  validate --config <path>        Validate local-config files without starting agents or watchers
+  describe --config <path>        Print the current managed full-set spec as JSON
+  print-layout --root <dir>       Print the canonical default local-config layout as JSON
+  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin
+  generate-config --root <dir> --spec-json <json>
+                                   Compatibility input; JSON is exposed in process arguments
 
-Example:
+Examples:
   agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot
+  agents-host start --config ./agents-host.yaml
+  agents-host validate --config ./agents-host.yaml
+  agents-host describe --config ./agents-host.yaml
+  agents-host print-layout --root ./runtime-root
+  printf '%s' '{"host":{"borgeeBaseUrl":"https://borgee.example.com"},"agents":[{"key":"cp1","name":"Copilot","apiKey":"bgr_xxx","provider":"copilot"}]}' | agents-host generate-config --root ./runtime-root --stdin
 `;

package/dist/cli.d.ts

@@ -1,2 +1,19 @@
 #!/usr/bin/env node
+import { describeLocalConfig, generateLocalConfig, printLocalConfigLayout, runMain, validateLocalConfig } from './run.js';
+export interface CliDeps {
+    env?: NodeJS.ProcessEnv;
+    logger?: Pick<Console, 'error'>;
+    runMain?: typeof runMain;
+    validateLocalConfig?: typeof validateLocalConfig;
+    describeLocalConfig?: typeof describeLocalConfig;
+    printLocalConfigLayout?: typeof printLocalConfigLayout;
+    generateLocalConfig?: typeof generateLocalConfig;
+    readStdin?: () => Promise<string>;
+}
+interface CliEntrypointDeps {
+    realpath?: (path: string) => string;
+}
+export declare function dispatchCli(argv: string[], deps?: Omit<CliDeps, 'logger'>): Promise<void>;
+export declare function main(argv?: string[], deps?: CliDeps): Promise<number>;
+export declare function isCliEntrypoint(importMetaUrl: string, argv1?: string | undefined, deps?: CliEntrypointDeps): boolean;
 export {};

package/dist/cli.js

@@ -1,34 +1,117 @@
 #!/usr/bin/env node
-import { CliUsageError, parseStartArgs, USAGE } from './cli-args.js';
-import { runMain } from './run.js';
-function fail(message) {
-    if (message)
-        console.error(`[agents-host] ${message}`);
-    console.error(USAGE);
-    process.exit(message ? 1 : 0);
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CliUsageError, parseDescribeArgs, parseGenerateConfigArgs, parsePrintLayoutArgs, parseStartArgs, parseValidateArgs, USAGE, } from './cli-args.js';
+import { describeLocalConfig, generateLocalConfig, printLocalConfigLayout, runMain, validateLocalConfig } from './run.js';
+function formatErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+export async function dispatchCli(argv, deps = {}) {
+    const [command, ...rest] = argv;
+    const env = deps.env ?? process.env;
+    const runMainImpl = deps.runMain ?? runMain;
+    const validateLocalConfigImpl = deps.validateLocalConfig ?? validateLocalConfig;
+    const describeLocalConfigImpl = deps.describeLocalConfig ?? describeLocalConfig;
+    const printLocalConfigLayoutImpl = deps.printLocalConfigLayout ?? printLocalConfigLayout;
+    const generateLocalConfigImpl = deps.generateLocalConfig ?? generateLocalConfig;
+    const readStdin = deps.readStdin ?? readAllStdin;
+    if (command === 'start') {
+        const parsed = parseStartArgs(rest);
+        if (parsed.mode === 'single-agent') {
+            env.BORGEE_BASE_URL = parsed.serverUrl;
+            env.BORGEE_AGENT_API_KEY = parsed.apiKey;
+            for (const [key, value] of Object.entries(parsed.env)) {
+                env[key] = value;
+            }
+            await runMainImpl();
+            return;
+        }
+        await runMainImpl({ configPath: parsed.configPath });
+        return;
+    }
+    if (command === 'validate') {
+        const parsed = parseValidateArgs(rest);
+        await validateLocalConfigImpl(parsed.configPath);
+        return;
+    }
+    if (command === 'describe') {
+        const parsed = parseDescribeArgs(rest);
+        await describeLocalConfigImpl(parsed.configPath);
+        return;
+    }
+    if (command === 'print-layout') {
+        const parsed = parsePrintLayoutArgs(rest);
+        await printLocalConfigLayoutImpl(parsed.rootPath);
+        return;
+    }
+    if (command === 'generate-config') {
+        const parsed = parseGenerateConfigArgs(rest);
+        if (parsed.input === 'stdin') {
+            await generateLocalConfigImpl(parsed.rootPath, await readStdin(), '<stdin>');
+        }
+        else {
+            await generateLocalConfigImpl(parsed.rootPath, parsed.specJson);
+        }
+        return;
+    }
+    throw new CliUsageError(`Unknown command: ${command}`);
 }
-const [command, ...rest] = process.argv.slice(2);
-if (command === undefined || command === '--help' || command === '-h') {
-    fail();
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
 }
-if (command !== 'start') {
-    fail(`Unknown command: ${command}`);
+export async function main(argv = process.argv.slice(2), deps = {}) {
+    const logger = deps.logger ?? console;
+    const [command] = argv;
+    if (command === undefined || command === '--help' || command === '-h') {
+        logger.error(USAGE);
+        return 0;
+    }
+    try {
+        await dispatchCli(argv, deps);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            logger.error(`[agents-host] ${error.message}`);
+            logger.error(USAGE);
+            return 1;
+        }
+        logger.error(`[agents-host] ${formatErrorMessage(error)}`, error);
+        return 1;
+    }
 }
-try {
-    const { serverUrl, apiKey, env } = parseStartArgs(rest);
-    process.env.BORGEE_BASE_URL = serverUrl;
-    process.env.BORGEE_AGENT_API_KEY = apiKey;
-    for (const [key, value] of Object.entries(env)) {
-        process.env[key] = value;
+function safeRealpath(path, realpath) {
+    try {
+        return realpath(path);
+    }
+    catch {
+        return null;
     }
 }
-catch (error) {
-    if (error instanceof CliUsageError) {
-        fail(error.message);
+export function isCliEntrypoint(importMetaUrl, argv1 = process.argv[1], deps = {}) {
+    if (!argv1) {
+        return false;
+    }
+    const importMetaPath = fileURLToPath(importMetaUrl);
+    const argvPath = resolve(argv1);
+    if (importMetaPath === argvPath) {
+        return true;
     }
-    throw error;
+    const realpath = deps.realpath ?? realpathSync.native;
+    const importMetaRealpath = safeRealpath(importMetaPath, realpath);
+    const argvRealpath = safeRealpath(argvPath, realpath);
+    return importMetaRealpath !== null && importMetaRealpath === argvRealpath;
+}
+if (isCliEntrypoint(import.meta.url)) {
+    void main().then((exitCode) => {
+        process.exitCode = exitCode;
+    });
 }
-runMain().catch((error) => {
-    console.error('[agents-host] fatal error:', error);
-    process.exitCode = 1;
-});

package/dist/config.d.ts

@@ -1,11 +1,12 @@
-import type { AgentsHostConfig } from './types.js';
-/**
- * Loads agents-host configuration from environment variables. This process
- * hosts exactly one Borgee agent (`BORGEE_AGENT_API_KEY`) — to run more
- * agents, run more processes with different env vars.
- *
- * The Copilot ACP prototype still parses `COPILOT_ARGS` for CLI/env backward
- * compatibility, but the persistent ACP backend intentionally ignores them and
- * always launches `copilot --acp`.
- */
-export declare function loadConfigFromEnv(): AgentsHostConfig;
+import type { AgentsHostConfig, ProviderCommandConfig, ProviderKind } from './types.js';
+export declare const MAX_COPILOT_SESSION_TTL_MINUTES: number;
+export declare const DEFAULT_COPILOT_SESSION_TTL_MINUTES: number;
+export declare const DEFAULT_PROVIDER_COMMAND_CONFIG: ProviderCommandConfig;
+export declare function requireNonEmptyString(value: unknown, message: string): string;
+export declare function optionalNonEmptyString(value: unknown, fieldName: string, sourceLabel: string): string | undefined;
+export declare function parseArgs(value: string): string[];
+export declare function optionalStringArray(value: unknown, fieldName: string, sourceLabel: string): string[] | undefined;
+export declare function parseCopilotSessionTtlMinutesValue(value: unknown, sourceLabel: string): number;
+export declare function resolveProvider(rawValue: string, sourceLabel: string): ProviderKind;
+export declare function resolveProviderCommandConfig(overrides?: Partial<ProviderCommandConfig>): ProviderCommandConfig;
+export declare function loadConfigFromEnv(env?: NodeJS.ProcessEnv): AgentsHostConfig;

package/dist/config.js

@@ -1,43 +1,92 @@
-function requireEnv(name) {
-    const value = process.env[name];
-    if (!value || value.trim().length === 0) {
-        throw new Error(`Missing required environment variable: ${name}`);
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+export const MAX_COPILOT_SESSION_TTL_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
+export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
+export const DEFAULT_PROVIDER_COMMAND_CONFIG = {
+    claudeCommand: 'claude',
+    claudeArgs: ['--print'],
+    copilotCommand: 'copilot',
+    copilotArgs: ['-s', '--no-color', '--allow-all-tools', '--output-format', 'text'],
+    copilotSessionTtlMinutes: DEFAULT_COPILOT_SESSION_TTL_MINUTES,
+};
+function requireEnv(name, env) {
+    return requireNonEmptyString(env[name], `Missing required environment variable: ${name}`);
+}
+function envOr(name, fallback, env) {
+    const value = env[name];
+    return value && value.trim().length > 0 ? value.trim() : fallback;
+}
+export function requireNonEmptyString(value, message) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(message);
     }
     return value.trim();
 }
-function envOr(name, fallback) {
-    const value = process.env[name];
-    return value && value.trim().length > 0 ? value.trim() : fallback;
+export function optionalNonEmptyString(value, fieldName, sourceLabel) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return requireNonEmptyString(value, `Invalid ${fieldName} in ${sourceLabel}: expected a non-empty string`);
 }
-function parseArgs(value) {
+export function parseArgs(value) {
     return value.trim().length > 0 ? value.trim().split(/\s+/) : [];
 }
-function resolveProvider() {
-    const raw = envOr('RUNTIME_PROVIDER', 'claude').toLowerCase();
-    if (raw === 'claude' || raw === 'copilot')
+export function optionalStringArray(value, fieldName, sourceLabel) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`Invalid ${fieldName} in ${sourceLabel}: expected an array of strings`);
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim().length === 0) {
+            throw new Error(`Invalid ${fieldName}[${index}] in ${sourceLabel}: expected a non-empty string`);
+        }
+        return entry.trim();
+    });
+}
+export function parseCopilotSessionTtlMinutesValue(value, sourceLabel) {
+    const parsed = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: expected a positive number`);
+    }
+    if (parsed > MAX_COPILOT_SESSION_TTL_MINUTES) {
+        throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: must be <= ${MAX_COPILOT_SESSION_TTL_MINUTES.toFixed(2)} minutes to fit within the Node.js timer limit`);
+    }
+    return parsed;
+}
+export function resolveProvider(rawValue, sourceLabel) {
+    const raw = rawValue.trim().toLowerCase();
+    if (raw === 'claude' || raw === 'copilot') {
         return raw;
-    throw new Error(`Unsupported RUNTIME_PROVIDER: ${raw} (expected "claude" or "copilot")`);
-}
-/**
- * Loads agents-host configuration from environment variables. This process
- * hosts exactly one Borgee agent (`BORGEE_AGENT_API_KEY`) — to run more
- * agents, run more processes with different env vars.
- *
- * The Copilot ACP prototype still parses `COPILOT_ARGS` for CLI/env backward
- * compatibility, but the persistent ACP backend intentionally ignores them and
- * always launches `copilot --acp`.
- */
-export function loadConfigFromEnv() {
+    }
+    throw new Error(`${sourceLabel}: expected "claude" or "copilot", got "${rawValue}"`);
+}
+export function resolveProviderCommandConfig(overrides = {}) {
+    return {
+        claudeCommand: overrides.claudeCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand,
+        claudeArgs: [...(overrides.claudeArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs)],
+        copilotCommand: overrides.copilotCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand,
+        copilotArgs: [...(overrides.copilotArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs)],
+        copilotSessionTtlMinutes: overrides.copilotSessionTtlMinutes ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
+    };
+}
+export function loadConfigFromEnv(env = process.env) {
+    const provider = resolveProvider(envOr('RUNTIME_PROVIDER', 'claude', env), 'Unsupported RUNTIME_PROVIDER');
     return {
-        borgeeBaseUrl: requireEnv('BORGEE_BASE_URL'),
-        claudeCommand: envOr('CLAUDE_COMMAND', 'claude'),
-        claudeArgs: parseArgs(envOr('CLAUDE_ARGS', '--print')),
-        copilotCommand: envOr('COPILOT_COMMAND', 'copilot'),
-        copilotArgs: parseArgs(envOr('COPILOT_ARGS', '-s --no-color --allow-all-tools --output-format text')),
+        borgeeBaseUrl: requireEnv('BORGEE_BASE_URL', env),
+        ...resolveProviderCommandConfig({
+            claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
+            claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),
+            copilotCommand: envOr('COPILOT_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand, env),
+            copilotArgs: parseArgs(envOr('COPILOT_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs.join(' '), env)),
+            copilotSessionTtlMinutes: env.COPILOT_SESSION_TTL_MINUTES && env.COPILOT_SESSION_TTL_MINUTES.trim().length > 0
+                ? parseCopilotSessionTtlMinutesValue(env.COPILOT_SESSION_TTL_MINUTES, 'environment variable COPILOT_SESSION_TTL_MINUTES')
+                : DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
+        }),
         agent: {
-            agentApiKey: requireEnv('BORGEE_AGENT_API_KEY'),
-            agentName: envOr('BORGEE_AGENT_NAME', 'Assistant'),
-            provider: resolveProvider(),
+            agentApiKey: requireEnv('BORGEE_AGENT_API_KEY', env),
+            agentName: envOr('BORGEE_AGENT_NAME', 'Assistant', env),
+            provider,
         },
     };
 }

package/dist/local-config.d.ts

@@ -0,0 +1,51 @@
+import type { LocalConfigGenerateResult, LocalConfigGenerateSpec, LocalConfigSnapshot } from './types.js';
+export declare const DEFAULT_LOCAL_HOST_CONFIG_FILENAME = "agents-host.yaml";
+export declare const DEFAULT_LOCAL_AGENTS_DIRNAME = "agents";
+export declare const MANAGED_WRITE_LOCK_DIRNAME = ".generate-config.lock";
+export interface LocalConfigLayout {
+    root: string;
+    hostConfigPath: string;
+    agentsDir: string;
+}
+export interface LocalConfigDirEntry {
+    name: string;
+    isFile: boolean;
+}
+export interface LocalConfigFileSystem {
+    readFile(path: string): Promise<string>;
+    readDir(path: string): Promise<LocalConfigDirEntry[]>;
+    realPath?(path: string): Promise<string>;
+}
+interface ManagedPathStatus {
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    mtimeMs: number;
+}
+export interface ManagedLocalConfigFileSystem extends LocalConfigFileSystem {
+    writeFile(path: string, content: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    removeTree(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    readLink(path: string): Promise<string>;
+    lstat(path: string): Promise<ManagedPathStatus>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+export declare function resolveLocalConfigLayout(rootPath: string): LocalConfigLayout;
+export declare function parseGenerateConfigSpec(value: unknown, sourceLabel: string): LocalConfigGenerateSpec;
+export declare function loadLocalConfigSnapshot(hostConfigPath: string, deps?: {
+    fileSystem?: LocalConfigFileSystem;
+    acquireManagedGenerationLease?: boolean;
+}): Promise<LocalConfigSnapshot>;
+export declare function loadLocalConfigGenerateSpec(hostConfigPath: string, deps?: {
+    fileSystem?: LocalConfigFileSystem;
+    acquireManagedGenerationLease?: boolean;
+}): Promise<LocalConfigGenerateSpec>;
+export declare function materializeLocalConfig(rootPath: string, spec: LocalConfigGenerateSpec, deps?: {
+    fileSystem?: ManagedLocalConfigFileSystem;
+}): Promise<LocalConfigGenerateResult>;
+export {};