@borgee/agents-host 0.1.6 → 0.1.7

package/README.md

@@ -1,40 +1,63 @@
 # @borgee/agents-host
 
-Minimal local runtime host: connects a local **Claude Code CLI** (`claude`) or
-**GitHub Copilot CLI** (`copilot`) process to a single Borgee agent over
-[`@borgee/plugin-sdk`](../sdk/plugin-ts) — the same BPP (`/ws/plugin`)
-protocol the official OpenClaw plugin uses.
+Minimal local runtime host for Borgee agents.
+
+- **Single-agent mode** keeps the existing one-process / one-agent flow.
+- **Local-config mode** adds first-step multi-agent local hosting from a host
+  config file plus one config file per agent, with hot reload.
 
 ## What this is (and isn't)
 
-This package is intentionally the *smallest* slice that proves the full loop:
+This package intentionally focuses on the smallest local-hosting loop:
 
-```
+```text
 Borgee channel message
   → /ws/plugin (BPP)
   → @borgee/plugin-sdk
   → AgentsHost.handleMessage
-  → local `claude`/`copilot` CLI subprocess
+  → local claude / copilot CLI subprocess
   → BPP reply
   → Borgee channel
 ```
 
-**In scope:** one agent per process, per-channel conversation memory via each
-provider's native session mechanism (Claude CLI resume, Copilot ACP sessions),
-and dispatching to a local CLI provider.
+**In scope:**
+
+- single-agent env / CLI startup
+- local-config multi-agent startup
+- one isolated `AgentsHost` per effective agent key
+- per-channel conversation memory via each provider's native session mechanism
+- hot reload for host config and agent file add / update / remove
+
+**Out of scope:**
+
+- remote command execution / shell dispatch
+- node provisioning
+- systemd/service installation
+- scheduled / periodic prompts
 
-**Out of scope** (see the larger `feat/multi-agent-runtime-host` work for
-these): remote command execution / shell dispatch, node provisioning,
-multi-agent discovery/sync, systemd service install, and scheduled/periodic
-prompts. To run several agents, run several processes with different
-`BORGEE_AGENT_API_KEY` values.
+## Running
 
-## Setup
+```bash
+pnpm --filter @borgee/agents-host dev     # tsx, env-var single-agent mode
+pnpm --filter @borgee/agents-host build   # tsc -> dist/
+pnpm --filter @borgee/agents-host start   # node dist/index.js, env-var single-agent mode
+```
 
-1. In the Borgee web UI, create an Agent and reveal its API key.
-2. Install the Claude Code CLI (`claude`) or GitHub Copilot CLI (`copilot`)
-   locally and make sure it works standalone.
-3. Run this package with the environment variables below.
+For the published CLI entry point:
+
+```bash
+agents-host start <serverUrl> <apiKey> [options]
+agents-host start --config <path-to-host-config>
+agents-host validate --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>
+```
+
+## Single-agent mode
+
+Use the existing env-var flow when you want exactly one hosted agent per
+process.
 
 ```bash
 BORGEE_BASE_URL=https://your-borgee-server \
@@ -44,48 +67,265 @@ RUNTIME_PROVIDER=claude \
 pnpm --filter @borgee/agents-host dev
 ```
 
-## Environment variables
+Or with the CLI:
 
-| Variable | Required | Default | Description |
-| --- | --- | --- | --- |
-| `BORGEE_BASE_URL` | yes | — | Borgee server base URL (e.g. `https://borgee.example.com`) |
-| `BORGEE_AGENT_API_KEY` | yes | — | The agent's API key, revealed from the web UI |
-| `BORGEE_AGENT_NAME` | no | `Assistant` | Display name used in prompts |
-| `RUNTIME_PROVIDER` | no | `claude` | `claude` or `copilot` |
-| `CLAUDE_COMMAND` / `CLAUDE_ARGS` | no | `claude` / `--print` | Local Claude CLI command + args |
-| `COPILOT_COMMAND` / `COPILOT_ARGS` | no | `copilot` / empty | Local Copilot CLI command. `COPILOT_ARGS` is accepted for backward-compatible config/CLI parsing but ignored by the persistent Copilot ACP prototype, which always launches `copilot --acp`. |
+```bash
+agents-host start https://your-borgee-server bgr_xxxxxxxx --provider copilot
+```
 
-## Conversation memory
+### Environment variables / equivalent single-agent CLI flags
 
-Each Borgee channel is mapped 1:1 to a provider-native session for the
-process's lifetime:
+| Variable                           | CLI flag                               | Required | Default                                       | Description                                                                                      |
+| ---------------------------------- | -------------------------------------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `BORGEE_BASE_URL`                  | positional `<serverUrl>`               | yes      | —                                             | Borgee server base URL                                                                           |
+| `BORGEE_AGENT_API_KEY`             | positional `<apiKey>`                  | yes      | —                                             | Agent API key from the web UI                                                                    |
+| `BORGEE_AGENT_NAME`                | `--name`                               | no       | `Assistant`                                   | Display name used in prompts                                                                     |
+| `RUNTIME_PROVIDER`                 | `--provider`                           | no       | `claude`                                      | `claude` or `copilot`                                                                            |
+| `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude` / `--print`                          | Local Claude CLI command + args                                                                  |
+| `COPILOT_COMMAND` / `COPILOT_ARGS` | `--copilot-command` / `--copilot-args` | no       | `copilot` / parsed but ignored by ACP runtime | Local Copilot CLI command. The persistent Copilot ACP prototype always launches `copilot --acp`. |
+| `COPILOT_SESSION_TTL_MINUTES`      | `--copilot-session-ttl-minutes`        | no       | `2880`                                        | Idle TTL for per-channel Copilot ACP sessions                                                    |
 
-- **Claude**: first turn for a channel uses `--session-id <uuid>`; every
-  turn after uses `-r/--resume <uuid>` (Claude treats these as distinct
-  operations).
-- **Copilot**: one persistent `copilot --acp` subprocess is shared by the
-  host, with one ACP session per Borgee channel. Same-channel turns are
-  serialized so they cannot interleave; different channels keep isolated ACP
-  sessions.
+## Local-config mode
 
-There is no separate history/context store on our side; if the runtime host
-process restarts, each channel starts a fresh CLI session (no session-id
-persistence across restarts in this minimal version).
+Run one supervisor process from a host config file:
 
-## Running
+```bash
+agents-host start --config ./agents-host.yaml
+```
+
+Validate the same local-config files without starting agents, the supervisor,
+watchers, control-plane connections, or provider subprocesses:
 
 ```bash
-pnpm --filter @borgee/agents-host dev     # tsx, no build step
-pnpm --filter @borgee/agents-host build   # tsc -> dist/
-pnpm --filter @borgee/agents-host start   # node dist/index.js
+agents-host validate --config ./agents-host.yaml
+```
+
+`validate` supports local-config mode only and reuses the same
+`loadLocalConfigSnapshot()` validation path as `start --config`.
+
+Print the canonical default local-config layout for a root directory without
+writing files or starting any runtime processes:
+
+```bash
+agents-host print-layout --root ./runtime-root
 ```
 
-There is no systemd/service installer here — run it as a plain foreground
-process (or wrap it with your own process manager) and stop it with
-`Ctrl+C`/`SIGTERM`.
+This command prints JSON only. It describes the default bootstrap layout:
+
+- host config file: `<root>/agents-host.yaml`
+- agents directory: `<root>/agents`
+
+It does **not** read an existing host config file, so it does **not** reflect a
+custom `agentsDir` override from `agents-host.yaml`.
+
+Materialize the canonical default local-config files under that root. Pass the
+secret-bearing JSON spec on standard input so it is not exposed in process
+arguments:
+
+```bash
+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
+```
+
+`generate-config` is machine-oriented:
+
+- it accepts one JSON spec object via `--stdin`; `--spec-json` remains only as
+  a compatibility input and exposes the JSON in process arguments
+- it always writes the canonical default layout from `print-layout`
+- it publishes a complete validated generation atomically; a failed generation
+  leaves the prior active set in place
+- concurrent writers for the same managed root are serialized through a
+  root-local lock; a writer waits up to 10 seconds, then fails clearly if the
+  lock remains held
+- it retains the active and immediately previous generations and reader-leased
+  generations, then removes older generated generations (including superseded API keys)
+- if that post-publication pruning fails, the apply remains successful and its
+  JSON summary includes a `warnings` entry with code
+  `PRUNE_SUPERSEDED_GENERATIONS_FAILED`
+- it uses a dedicated managed root: `<root>/agents-host.yaml` and
+  `<root>/agents` are stable links to the active private generation
+- it replaces stale supported agent config files as part of that atomic
+  full-set publication, never by pruning the active set first
+- it creates and normalizes the managed root and generation directories to
+  mode `0700`, and generated host and agent config files to mode `0600`
+- it prints a JSON summary without echoing agent API keys
+
+Use a new empty directory as the managed root. `generate-config` refuses a
+root whose managed links or generation storage have been replaced with
+unexpected file types or targets. Existing hand-managed local-config layouts
+continue to work with `start --config` and `validate --config`; they are not
+converted in place by this command.
+
+The spec shape is:
+
+```json
+{
+  "host": {
+    "borgeeBaseUrl": "https://borgee.example.com",
+    "defaults": {
+      "claudeCommand": "claude",
+      "claudeArgs": ["--print"],
+      "copilotCommand": "copilot",
+      "copilotArgs": ["-s", "--no-color", "--allow-all-tools", "--output-format", "text"],
+      "copilotSessionTtlMinutes": 2880
+    }
+  },
+  "agents": [
+    {
+      "key": "cp1",
+      "name": "Copilot",
+      "apiKey": "bgr_xxx",
+      "provider": "copilot",
+      "enabled": true
+    }
+  ]
+}
+```
+
+`host.agentsDir` is intentionally **not** accepted here. Canonical generation
+always targets `<root>/agents`, and validation is re-run after generation using
+the same local-config loader as `start --config` / `validate --config`. Start
+the generated layout with `agents-host start --config <root>/agents-host.yaml`;
+that stable path follows the active atomically published generation.
+The loader preserves that stable path for validation output and publication
+watches, while pinning resolved host and agents-directory paths before reading.
+Managed snapshots hold a short-lived reader lease until the read finishes, so
+each snapshot uses one generation even if publication changes `current`
+concurrently.
+
+The supervisor loads:
+
+- one **host config file**
+- one **agent config file per discovered file** under the agents directory
+- one isolated `AgentsHost` per enabled agent key
+
+### Supported file types
+
+Host and agent config files may be:
+
+- `*.yaml`
+- `*.yml`
+- `*.json`
+
+Parsing uses the `yaml` package for all supported file types.
+
+### Recommended layout
+
+```text
+packages/agents-host/
+  agents-host.yaml
+  agents/
+    support.yaml
+    triage.json
+```
+
+### Host config
+
+`agentsDir` defaults to `./agents` relative to the host config file. Absolute
+paths are also allowed.
+
+```yaml
+borgeeBaseUrl: https://borgee.example.com
+agentsDir: ./agents
+defaults:
+  claudeCommand: claude
+  claudeArgs:
+    - --print
+  copilotCommand: copilot
+  copilotArgs:
+    - -s
+    - --no-color
+    - --allow-all-tools
+    - --output-format
+    - text
+  copilotSessionTtlMinutes: 2880
+```
+
+Host config fields:
+
+- `borgeeBaseUrl` (**required**)
+- `agentsDir` (optional, default `./agents` relative to the host config file)
+- `defaults.claudeCommand`
+- `defaults.claudeArgs`
+- `defaults.copilotCommand`
+- `defaults.copilotArgs`
+- `defaults.copilotSessionTtlMinutes`
+
+Absent host defaults fall back to the same code-level defaults used by the
+single-agent env / CLI flow.
+
+### Agent config
+
+```yaml
+key: support-bot
+name: Support Bot
+apiKey: bgr_support_xxxxxxxx
+provider: claude
+enabled: true
+claudeArgs:
+  - --print
+  - --model
+  - sonnet
+```
+
+Agent config fields:
+
+- `key` (**required**): stable identity used for diffing and reload decisions
+- `name` (**required**)
+- `apiKey` (**required**)
+- `provider` (**required**): `claude` or `copilot`
+- `enabled` (optional, default `true`)
+- optional overrides for `claudeCommand`, `claudeArgs`, `copilotCommand`,
+  `copilotArgs`, and `copilotSessionTtlMinutes`
+
+Array overrides are **replacement**, not concatenation. For example, an agent
+`claudeArgs` value replaces the host default `claudeArgs` entirely.
+
+## Hot reload behavior
+
+The supervisor watches:
+
+- the stable host-config parent, so an atomic `current` publication triggers a reload
+- the resolved host-config generation directory
+- the resolved configured agents directory
+
+Every `rename` / `change` event is treated as a reload trigger. Reloads are
+serialized with initial startup and debounced by at least 300ms. Each reload
+does a full rescan, validation pass, diff, and apply cycle.
+
+Diff rules:
+
+- `enabled: false` agents are excluded before diffing
+- new `key` → start a new isolated `AgentsHost`
+- removed `key` → stop that agent
+- same `key` + same effective config → no-op
+- same `key` + changed effective config → stop old runner, then start replacement
+
+Changing an agent `key` is treated as **remove old + add new**, so provider-side
+session state is not preserved across the key change.
+
+If a reload candidate is invalid (malformed host config, malformed agent config,
+or duplicate agent keys), the supervisor logs the error and keeps the last
+successfully applied snapshot running.
+
+## Conversation memory
+
+Each Borgee channel is mapped 1:1 to a provider-native session while it stays
+active:
+
+- **Claude**: first turn for a channel uses `--session-id <uuid>`; every turn
+  after uses `-r/--resume <uuid>`.
+- **Copilot**: one persistent `copilot --acp` subprocess is shared by a single
+  `AgentsHost`, with one ACP session per Borgee channel. Same-channel turns are
+  serialized; different channels keep isolated ACP sessions.
+
+There is no separate history store on our side. If a runner restarts, that
+agent's provider-side channel sessions start fresh.
 
 ## Testing
 
 ```bash
-pnpm --filter @borgee/agents-host test
+pnpm --filter @borgee/agents-host exec vitest run --testTimeout=10000
+pnpm --filter @borgee/agents-host typecheck
+pnpm --filter @borgee/agents-host build
 ```

package/dist/agents-host-supervisor.d.ts

@@ -0,0 +1,54 @@
+import type { AgentsHostConfig, LocalConfigSnapshot } from './types.js';
+export interface HostRunner {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface WatchHandle {
+    close(): void;
+}
+export interface WatchEventInfo {
+    eventType?: string;
+    filename?: string;
+}
+export interface LoggerLike {
+    log(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export interface AgentsHostSupervisorDeps {
+    createHost?: (config: AgentsHostConfig) => HostRunner;
+    loadSnapshot?: (configPath: string) => Promise<LocalConfigSnapshot>;
+    watchPath?: (path: string, onEvent: (event?: WatchEventInfo) => void) => WatchHandle;
+    logger?: LoggerLike;
+}
+export declare class AgentsHostSupervisor {
+    private readonly hostConfigPath;
+    private readonly createHost;
+    private readonly loadSnapshot;
+    private readonly watchPath;
+    private readonly logger;
+    private readonly activeHosts;
+    private readonly watchers;
+    private currentSnapshot;
+    private reloadTimer;
+    private reloadInFlight;
+    private pendingReload;
+    private runningReloadPromise;
+    private shuttingDown;
+    private started;
+    constructor(hostConfigPath: string, deps?: AgentsHostSupervisorDeps);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private scheduleReload;
+    private clearReloadTimer;
+    private runReloadLoop;
+    private reloadOnce;
+    private refreshWatchers;
+    private getWatchPaths;
+    private handleWatchEvent;
+    private installStableWatcher;
+    private closeAllWatchers;
+    private cleanUpFailedStart;
+    private applySnapshot;
+    private startDesiredAgent;
+    private stopActiveHost;
+}