@borgee/agents-host 0.1.6 → 0.1.7

package/dist/agents-host-supervisor.js

@@ -0,0 +1,313 @@
+import { watch } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { AgentsHost } from './agents-host.js';
+import { loadLocalConfigSnapshot, MANAGED_WRITE_LOCK_DIRNAME } from './local-config.js';
+const RELOAD_DEBOUNCE_MS = 300;
+function sameAgentConfig(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export class AgentsHostSupervisor {
+    hostConfigPath;
+    createHost;
+    loadSnapshot;
+    watchPath;
+    logger;
+    activeHosts = new Map();
+    watchers = new Map();
+    currentSnapshot = null;
+    reloadTimer = null;
+    reloadInFlight = false;
+    pendingReload = false;
+    runningReloadPromise = null;
+    shuttingDown = false;
+    started = false;
+    constructor(hostConfigPath, deps = {}) {
+        this.hostConfigPath = resolve(hostConfigPath);
+        this.createHost = deps.createHost ?? ((config) => new AgentsHost(config));
+        this.loadSnapshot = deps.loadSnapshot ?? ((configPath) => loadLocalConfigSnapshot(configPath));
+        this.watchPath =
+            deps.watchPath ??
+                ((path, onEvent) => watch(path, (eventType, filename) => {
+                    onEvent({
+                        eventType,
+                        filename: filename == null ? undefined : String(filename),
+                    });
+                }));
+        this.logger = deps.logger ?? console;
+    }
+    async start() {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        this.shuttingDown = false;
+        try {
+            this.installStableWatcher();
+            await this.runReloadLoop(true);
+            if (this.shuttingDown) {
+                await this.cleanUpFailedStart();
+                return;
+            }
+            const snapshot = this.currentSnapshot;
+            if (!snapshot) {
+                throw new Error('Local-config startup completed without an applied snapshot');
+            }
+            this.logger.log('[agents-host] local-config supervisor started', {
+                configPath: this.hostConfigPath,
+                agentsDir: snapshot.agentsDir,
+                agentCount: snapshot.agents.length,
+            });
+        }
+        catch (error) {
+            await this.cleanUpFailedStart();
+            throw error;
+        }
+    }
+    async stop() {
+        if (!this.started) {
+            return;
+        }
+        this.started = false;
+        this.shuttingDown = true;
+        this.clearReloadTimer();
+        this.closeAllWatchers();
+        await this.runningReloadPromise;
+        const activeKeys = [...this.activeHosts.keys()].sort((left, right) => left.localeCompare(right));
+        for (const key of activeKeys) {
+            const activeHost = this.activeHosts.get(key);
+            if (!activeHost) {
+                continue;
+            }
+            await this.stopActiveHost(key, activeHost);
+        }
+    }
+    scheduleReload() {
+        if (this.shuttingDown) {
+            return;
+        }
+        this.clearReloadTimer();
+        this.reloadTimer = setTimeout(() => {
+            this.reloadTimer = null;
+            void this.runReloadLoop();
+        }, RELOAD_DEBOUNCE_MS);
+    }
+    clearReloadTimer() {
+        if (this.reloadTimer) {
+            clearTimeout(this.reloadTimer);
+            this.reloadTimer = null;
+        }
+    }
+    async runReloadLoop(failOnStartError = false) {
+        if (this.reloadInFlight) {
+            this.pendingReload = true;
+            return;
+        }
+        this.reloadInFlight = true;
+        this.runningReloadPromise = (async () => {
+            try {
+                do {
+                    this.pendingReload = false;
+                    await this.reloadOnce(failOnStartError);
+                } while (this.pendingReload && !this.shuttingDown);
+            }
+            finally {
+                this.reloadInFlight = false;
+                this.runningReloadPromise = null;
+            }
+        })();
+        await this.runningReloadPromise;
+    }
+    async reloadOnce(failOnStartError = false) {
+        if (this.shuttingDown) {
+            return;
+        }
+        try {
+            const snapshot = await this.loadSnapshot(this.hostConfigPath);
+            if (this.shuttingDown) {
+                return;
+            }
+            await this.applySnapshot(snapshot, failOnStartError);
+            if (this.shuttingDown) {
+                return;
+            }
+            this.refreshWatchers(snapshot);
+            this.currentSnapshot = snapshot;
+            this.logger.log('[agents-host] applied local-config reload', {
+                configPath: this.hostConfigPath,
+                agentsDir: snapshot.agentsDir,
+                agentCount: snapshot.agents.length,
+            });
+        }
+        catch (error) {
+            this.logger.error('[agents-host] local-config reload failed; keeping last applied snapshot', {
+                configPath: this.hostConfigPath,
+                error,
+            });
+            if (failOnStartError) {
+                throw error;
+            }
+        }
+    }
+    refreshWatchers(snapshot) {
+        const watchPaths = this.getWatchPaths(snapshot);
+        const nextWatchers = new Map();
+        try {
+            for (const path of watchPaths) {
+                const existing = this.watchers.get(path);
+                if (existing) {
+                    nextWatchers.set(path, existing);
+                    continue;
+                }
+                nextWatchers.set(path, this.watchPath(path, (event) => this.handleWatchEvent(path, event)));
+            }
+        }
+        catch (error) {
+            for (const [path, handle] of nextWatchers) {
+                if (!this.watchers.has(path)) {
+                    handle.close();
+                }
+            }
+            throw error;
+        }
+        for (const [path, handle] of this.watchers) {
+            if (!nextWatchers.has(path)) {
+                handle.close();
+            }
+        }
+        this.watchers.clear();
+        for (const [path, handle] of nextWatchers) {
+            this.watchers.set(path, handle);
+        }
+    }
+    getWatchPaths(snapshot) {
+        const paths = snapshot.managedRootPath
+            ? [snapshot.managedRootPath, snapshot.resolvedAgentsDir]
+            : [dirname(this.hostConfigPath), snapshot.resolvedHostConfigDir, snapshot.resolvedAgentsDir];
+        return [...new Set(paths)].sort((a, b) => a.localeCompare(b));
+    }
+    handleWatchEvent(path, event) {
+        if (event?.filename === MANAGED_WRITE_LOCK_DIRNAME && path === dirname(this.hostConfigPath)) {
+            return;
+        }
+        this.scheduleReload();
+    }
+    installStableWatcher() {
+        const stablePath = dirname(this.hostConfigPath);
+        if (!this.watchers.has(stablePath)) {
+            this.watchers.set(stablePath, this.watchPath(stablePath, (event) => this.handleWatchEvent(stablePath, event)));
+        }
+    }
+    closeAllWatchers() {
+        const watchers = [...this.watchers.entries()];
+        this.watchers.clear();
+        for (const [path, handle] of watchers) {
+            try {
+                handle.close();
+            }
+            catch (error) {
+                this.logger.error('[agents-host] failed to close config watcher', { path, error });
+            }
+        }
+    }
+    async cleanUpFailedStart() {
+        this.shuttingDown = true;
+        this.clearReloadTimer();
+        this.closeAllWatchers();
+        const activeKeys = [...this.activeHosts.keys()].sort((left, right) => left.localeCompare(right));
+        for (const key of activeKeys) {
+            const activeHost = this.activeHosts.get(key);
+            if (activeHost) {
+                await this.stopActiveHost(key, activeHost);
+            }
+        }
+        this.currentSnapshot = null;
+        this.started = false;
+    }
+    async applySnapshot(snapshot, failOnStartError = false) {
+        const desiredAgents = new Map(snapshot.agents.map((agent) => [agent.key, agent]));
+        const activeKeys = [...this.activeHosts.keys()].sort((left, right) => left.localeCompare(right));
+        for (const key of activeKeys) {
+            if (!desiredAgents.has(key)) {
+                const activeHost = this.activeHosts.get(key);
+                if (activeHost) {
+                    await this.stopActiveHost(key, activeHost);
+                }
+            }
+        }
+        const desiredKeys = [...desiredAgents.keys()].sort((left, right) => left.localeCompare(right));
+        for (const key of desiredKeys) {
+            const desiredAgent = desiredAgents.get(key);
+            if (!desiredAgent) {
+                continue;
+            }
+            const activeHost = this.activeHosts.get(key);
+            if (!activeHost) {
+                await this.startDesiredAgent(desiredAgent, failOnStartError);
+                continue;
+            }
+            if (sameAgentConfig(activeHost.config, desiredAgent.config)) {
+                continue;
+            }
+            await this.stopActiveHost(key, activeHost);
+            await this.startDesiredAgent(desiredAgent, failOnStartError);
+        }
+    }
+    async startDesiredAgent(agent, failOnStartError = false) {
+        if (this.shuttingDown) {
+            return;
+        }
+        const runner = this.createHost(agent.config);
+        try {
+            await runner.start();
+            this.activeHosts.set(agent.key, {
+                config: agent.config,
+                runner,
+            });
+            this.logger.log('[agents-host] started managed agent', {
+                key: agent.key,
+                sourcePath: agent.sourcePath,
+                agentName: agent.config.agent.agentName,
+                provider: agent.config.agent.provider,
+            });
+        }
+        catch (error) {
+            try {
+                await runner.stop();
+            }
+            catch (stopError) {
+                this.logger.error('[agents-host] failed to clean up agent after start error', {
+                    key: agent.key,
+                    sourcePath: agent.sourcePath,
+                    error: stopError,
+                });
+            }
+            this.logger.error('[agents-host] failed to start managed agent; leaving it absent until the next reload', {
+                key: agent.key,
+                sourcePath: agent.sourcePath,
+                error,
+            });
+            if (failOnStartError) {
+                throw error;
+            }
+        }
+    }
+    async stopActiveHost(key, activeHost) {
+        this.activeHosts.delete(key);
+        try {
+            await activeHost.runner.stop();
+            this.logger.log('[agents-host] stopped managed agent', {
+                key,
+                agentName: activeHost.config.agent.agentName,
+                provider: activeHost.config.agent.provider,
+            });
+        }
+        catch (error) {
+            this.logger.error('[agents-host] failed to stop managed agent', {
+                key,
+                agentName: activeHost.config.agent.agentName,
+                provider: activeHost.config.agent.provider,
+                error,
+            });
+        }
+    }
+}

package/dist/agents-host.d.ts

@@ -10,10 +10,10 @@ import type { AgentsHostConfig } from './types.js';
  * the cli-client.ts file under each provider's folder. This class does not
  * keep any message history itself.
  *
- * Out of scope by design (see README): execution/remote-command dispatch,
- * node provisioning, multi-agent discovery, systemd install, and scheduled
- * (periodic) prompts. Running several agents means running several
- * processes, each with its own `BORGEE_AGENT_API_KEY`.
+ * Out of scope for this single-agent runner (see README): execution/remote-command
+ * dispatch, node provisioning, systemd install, and scheduled (periodic)
+ * prompts. Multi-agent local hosting is handled one level up by the local-config
+ * supervisor, which creates one isolated `AgentsHost` per effective agent key.
  *
  * Message gating (mention-only / DM rules) is NOT done here: the server
  * enforces per-agent + per-channel `require_mention` at BPP fan-out, so this

package/dist/agents-host.js

@@ -9,10 +9,10 @@ import { createProvider } from './providers/create-provider.js';
  * the cli-client.ts file under each provider's folder. This class does not
  * keep any message history itself.
  *
- * Out of scope by design (see README): execution/remote-command dispatch,
- * node provisioning, multi-agent discovery, systemd install, and scheduled
- * (periodic) prompts. Running several agents means running several
- * processes, each with its own `BORGEE_AGENT_API_KEY`.
+ * Out of scope for this single-agent runner (see README): execution/remote-command
+ * dispatch, node provisioning, systemd install, and scheduled (periodic)
+ * prompts. Multi-agent local hosting is handled one level up by the local-config
+ * supervisor, which creates one isolated `AgentsHost` per effective agent key.
  *
  * Message gating (mention-only / DM rules) is NOT done here: the server
  * enforces per-agent + per-channel `require_mention` at BPP fan-out, so this
@@ -32,6 +32,7 @@ export class AgentsHost {
             claudeArgs: config.claudeArgs,
             copilotCommand: config.copilotCommand,
             copilotArgs: config.copilotArgs,
+            copilotSessionTtlMinutes: config.copilotSessionTtlMinutes,
         });
         this.borgee = deps?.borgee ?? new SdkChatControlPlane(config.borgeeBaseUrl, config.agent.agentApiKey, undefined, 
         // Lets the server know which runtime/provider actually connected

package/dist/cli-args.d.ts

@@ -1,22 +1,45 @@
 /**
- * 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 declare const CLI_FLAG_TO_ENV: Record<string, string>;
-export interface ParsedStartArgs {
+export type ParsedStartArgs = ParsedSingleAgentStartArgs | ParsedLocalConfigStartArgs;
+export interface ParsedSingleAgentStartArgs {
+    mode: 'single-agent';
     serverUrl: string;
     apiKey: string;
     env: Record<string, string>;
 }
+export interface ParsedLocalConfigStartArgs {
+    mode: 'local-config';
+    configPath: string;
+}
+export interface ParsedValidateArgs {
+    configPath: string;
+}
+export interface ParsedDescribeArgs {
+    configPath: string;
+}
+export interface ParsedPrintLayoutArgs {
+    rootPath: string;
+}
+export interface ParsedGenerateConfigFromArgvArgs {
+    rootPath: string;
+    input: 'argv';
+    specJson: string;
+}
+export interface ParsedGenerateConfigFromStdinArgs {
+    rootPath: string;
+    input: 'stdin';
+}
+export type ParsedGenerateConfigArgs = ParsedGenerateConfigFromArgvArgs | ParsedGenerateConfigFromStdinArgs;
 export declare 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 declare function parseStartArgs(argv: string[]): ParsedStartArgs;
-export declare const USAGE = "Usage: agents-host start <serverUrl> <apiKey> [options]\n\nOptions:\n  --name <name>                 Display name (default: Assistant)\n  --provider <claude|copilot>   Runtime provider (default: claude)\n  --claude-command <cmd>        Local Claude CLI command (default: claude)\n  --claude-args <args>          Local Claude CLI args (default: --print)\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n\nExample:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot\n";
+export declare function parseValidateArgs(argv: string[]): ParsedValidateArgs;
+export declare function parseDescribeArgs(argv: string[]): ParsedDescribeArgs;
+export declare function parsePrintLayoutArgs(argv: string[]): ParsedPrintLayoutArgs;
+export declare function parseGenerateConfigArgs(argv: string[]): ParsedGenerateConfigArgs;
+export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start --config <path-to-host-config>\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n\nSingle-agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|copilot>     Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude CLI command (default: claude)\n  --claude-args <args>            Local Claude CLI args (default: --print)\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n\nLocal-config mode:\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host start --config ./agents-host.yaml\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  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\n";