@borgee/agents-host 0.2.29 → 0.2.32

package/README.md

@@ -63,6 +63,7 @@ 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>
+agents-host update
 ```
 
 ## Standalone env mode
@@ -84,7 +85,7 @@ Codex now ships on the same default hosted-provider surface as Claude and Copilo
 
 The current shipped internal compatibility surface resolves gates in this order:
 
-1. start from the shipped defaults: `claude-provider-v2`, `copilot-provider-v2`, `codex-provider`, `managed-runtime-convergence`, and `policy-audit-enforcement`
+1. start from the shipped defaults: `copilot-provider-v2`, `codex-provider`, `managed-runtime-convergence`, and `policy-audit-enforcement`
 2. add any explicit entries from `AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES`
 3. subtract any explicit entries from `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES`
 
@@ -98,7 +99,7 @@ Legacy managed roots created before `managed-runtime-settings.json` existed need
 Rollback and hardening controls stay explicit:
 
 - `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=<comma-list>` disables shipped gates for rollback
-- `AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS=claude:v1,copilot:v1` forces Claude and/or Copilot back to the v1 adapters while their v2 gates stay enabled
+- `AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS=copilot:v1` forces Copilot back to the v1 adapter while its v2 gate stays enabled; stale `claude:v1|v2` entries are tolerated as no-ops for compatibility
 - `AGENTS_HOST_INTERNAL_POLICY_MODE=enforce` hardens the shipped `policy-audit-enforcement` gate beyond its default `audit-only` mode
 
 Or with the CLI:
@@ -232,9 +233,10 @@ Notes:
 | `BORGEE_BASE_URL`                  | positional `<serverUrl>`               | yes      | —                                             | Borgee server base URL                                                                           |
 | `BORGEE_AGENT_API_KEY`             | positional `<apiKey>`                  | yes      | —                                             | Agent API key from the web UI                                                                    |
 | `AGENTS_HOST_DEBUG`                | `--debug`                              | no       | off                                           | Extra host/provider lifecycle logs. Set `AGENTS_HOST_DEBUG=1` to enable without the CLI flag.   |
+| `AGENTS_HOST_DISABLE_UPDATE_CHECK` | —                                      | no       | off                                           | Set to `1` to skip the advisory startup update check.                                            |
 | `BORGEE_AGENT_NAME`                | `--name`                               | no       | `Assistant`                                   | Display name used in prompts                                                                     |
 | `RUNTIME_PROVIDER`                 | `--provider`                           | no       | `claude`                                      | `claude`, `copilot`, or `codex`                                                                  |
-| `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude` / `--print --permission-mode bypassPermissions` | Local Claude CLI command + args                                                                  |
+| `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude-agent-acp` / empty                    | Local Claude ACP adapter command + args. The shipped bundled `claude-agent-acp` path requires empty `CLAUDE_ARGS`; non-empty args are only valid when `CLAUDE_COMMAND` points at a custom ACP adapter command. Legacy `claude --print --permission-mode bypassPermissions` is tolerated as a compatibility alias. |
 | `CODEX_COMMAND` / `CODEX_ARGS`     | `--codex-command` / `--codex-args`     | no       | `codex-acp` / empty                           | Local Codex ACP adapter command + args. The default launch resolves the bundled `@agentclientprotocol/codex-acp` entrypoint. |
 | `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                                                    |
@@ -317,8 +319,8 @@ The spec shape is:
   "host": {
     "borgeeBaseUrl": "https://borgee.example.com",
     "defaults": {
-      "claudeCommand": "claude",
-      "claudeArgs": ["--print", "--permission-mode", "bypassPermissions"],
+      "claudeCommand": "claude-agent-acp",
+      "claudeArgs": [],
       "codexCommand": "codex-acp",
       "codexArgs": [],
       "copilotCommand": "copilot",
@@ -384,11 +386,8 @@ paths are also allowed.
 borgeeBaseUrl: https://borgee.example.com
 agentsDir: ./agents
 defaults:
-  claudeCommand: claude
-  claudeArgs:
-    - --print
-    - --permission-mode
-    - bypassPermissions
+  claudeCommand: claude-agent-acp
+  claudeArgs: []
   codexCommand: codex-acp
   codexArgs: []
   copilotCommand: copilot
@@ -424,12 +423,6 @@ name: Support Bot
 apiKey: bgr_support_xxxxxxxx
 provider: claude
 enabled: true
-claudeArgs:
-  - --print
-  - --permission-mode
-  - bypassPermissions
-  - --model
-  - sonnet
 ```
 
 Agent config fields:
@@ -439,6 +432,7 @@ Agent config fields:
 - `apiKey` (**required**)
 - `provider` (**required**): `claude`, `copilot`, or `codex` (roll back Codex only with `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=codex-provider`)
 - `enabled` (optional, default `true`)
+- `claudeCommand` / `claudeArgs` (optional): leave unset to use the shipped bundled `claude-agent-acp` path. On that bundled path `claudeArgs` must stay empty. Non-empty `claudeArgs` are only supported when `claudeCommand` points at a custom ACP adapter command.
 - optional overrides for `claudeCommand`, `claudeArgs`, `codexCommand`,
   `codexArgs`, `copilotCommand`, `copilotArgs`, and
   `copilotSessionTtlMinutes`
@@ -478,10 +472,16 @@ successfully applied snapshot running.
 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>`. The host persists the channel→session map in
-  its state root, serializes cross-channel map rewrites, and retries once with a
-  fresh session immediately if Claude reports a stale `--resume` target.
+- **Claude**: one persistent `@agentclientprotocol/claude-agent-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. Ordinary threads keep the shared runtime workspace cwd, while
+  eligible `task_assignment` threads switch the real ACP session cwd to that
+  same hidden local task-scoped workspace. The host persists the
+  channel→ACP-session map in its state root, restores same-host continuity with
+  ACP `session/resume` when available, retries stale restores with a fresh
+  session immediately, and injects the per-channel local context paths through
+  Claude ACP `_meta.systemPrompt.append`.
 - **Codex**: one persistent `@agentclientprotocol/codex-acp` subprocess is
   shared by a single `AgentsHost`, with one ACP session per Borgee channel. When
   the current turn has a materialized channel context payload, Codex refreshes a
@@ -504,17 +504,72 @@ active:
   state root and restores same-host continuity with ACP `session/resume` when
   available, otherwise `session/load` plus local replay cleanup on runtimes
   that advertise only load support.
-- **Claude**: Claude still keeps one provider-native session mapping per Borgee
-  channel, but unlike the ACP-backed adapters it spawns a fresh CLI process for
-  each turn. Ordinary threads inherit the host runtime cwd; eligible
-  `task_assignment` threads run the CLI process with the hidden local
-  task-scoped workspace as the process cwd, again without implying that the
-  target repository is already checked out there.
-
 There is no separate transcript/history store on our side. Claude, Codex, and
 Copilot only persist the native session ids they should try to resume later;
 cross-host continuity still does not exist in this runtime.
 
+## Staying up to date
+
+`agents-host update` reinstalls the published package:
+
+```bash
+agents-host update
+```
+
+It takes no options. The latest published release is resolved with `npm view`,
+and the package is reinstalled with the manager that owns the current global
+install (`npm install -g`, `pnpm add -g`, `yarn global add`, or `bun add -g`).
+When the installed version is already at or ahead of the latest release it says
+so and does nothing.
+
+The command only acts on a **global** install. It refuses a source checkout
+(update that with git) and a project-local dependency (update it through the
+consuming project's manifest); rewriting either behind their owner's back is not
+this command's call. Which of the three it is comes from asking each installed
+manager where it puts global installs — `npm root -g`, `pnpm root -g`,
+`yarn global dir`, `bun pm bin -g` — and seeing which answer contains this
+package, so relocated roots (`YARN_GLOBAL_FOLDER`, `BUN_INSTALL`, Windows
+`%LOCALAPPDATA%\Yarn\Data`) and pnpm's virtual store all classify correctly.
+
+`npm` has to be on `PATH` for the version lookup even when another manager owns
+the install; it ships with Node, and all four managers read the same registry.
+Going through npm rather than querying the registry directly is what makes
+`.npmrc` discovery, scoped auth tokens, proxies, custom CAs, and retries work,
+so private and mirrored registries need no extra configuration here.
+
+### Startup update check
+
+Every user-facing startup path — the env-var entrypoint, `start`, `start --config`,
+and both `start-managed` forms — checks for a newer published release first and
+prints an advisory notice on stderr:
+
+```text
+[agents-host] update available: 0.2.31 -> 0.3.0
+[agents-host] run `agents-host update` to install it
+```
+
+The check cannot hold startup back:
+
+- source checkouts are skipped from the package path alone, so `pnpm dev` never
+  nags and never spawns a package manager
+- the answer is cached for six hours in `~/.borgee/agents-host/update-check.json`
+  (mode `0600`), so repeated `start-managed` upserts do not re-query the registry
+- a failed lookup is cached the same way, so an unreachable registry costs the
+  deadline once per six hours rather than on every start
+- the lookup owns a five-second deadline and **kills** the `npm` child when it
+  passes, which bounds the wait even when the hang is inside DNS resolution
+- which manager owns the install is only asked once there is a notice to word,
+  so a start with nothing to report never pays for it
+- every failure — offline machine, unreachable registry, unreadable cache — is
+  silent; `AGENTS_HOST_DEBUG=1` prints the reason
+- `AGENTS_HOST_DISABLE_UPDATE_CHECK=1` turns the check off
+- machine-oriented commands (`describe-managed`, `apply-managed`, `describe`,
+  `print-layout`, `generate-config`, `log`) never run it
+
+A cached start still runs one local `npm config get registry`, measured at about
+100ms, because the cached answer is only valid for the registry it came from and
+npm is the only thing that knows which registry `.npmrc` resolves to.
+
 ## Testing
 
 ```bash

package/dist/agents-host.d.ts

@@ -128,7 +128,7 @@ export declare class AgentsHost {
     private resolveVisibleTurnBody;
     private shouldRelayProtocolReply;
     private normalizeMessage;
-    private markAssignedTaskInProgress;
+    private resolveTaskAssignmentDelivery;
     private ensureSelfAgentId;
     private classifyAuthor;
     private refreshParticipantDirectory;

package/dist/agents-host.js

@@ -527,6 +527,11 @@ export class AgentsHost {
         if (!normalized) {
             return;
         }
+        const effective = await this.resolveTaskAssignmentDelivery(msg, normalized);
+        if (!effective) {
+            return;
+        }
+        msg = effective;
         let taskThreadContext = { state: 'inactive' };
         let attentionSnapshot;
         if (this.attentionFollowSemanticsEnabled
@@ -542,9 +547,6 @@ export class AgentsHost {
                 }
             }
         }
-        if (msg.message_type === 'task_assignment') {
-            await this.markAssignedTaskInProgress(msg.channel_id, normalized.content);
-        }
         await this.runUngatedTurn(msg, normalized.authorId, normalized.content, taskThreadContext, attentionSnapshot);
     }
     async handleCollaborationMessage(msg) {
@@ -552,9 +554,11 @@ export class AgentsHost {
         if (!normalized) {
             return;
         }
-        if (msg.message_type === 'task_assignment') {
-            await this.markAssignedTaskInProgress(msg.channel_id, normalized.content);
+        const effective = await this.resolveTaskAssignmentDelivery(msg, normalized);
+        if (!effective) {
+            return;
         }
+        msg = effective;
         const channelState = this.ensureCollaborationChannelState(msg.channel_id);
         await this.ensureProtocolStateLoaded(msg.channel_id, channelState);
         await this.ensureAttentionSnapshotLoaded(msg.channel_id, channelState);
@@ -2640,28 +2644,51 @@ export class AgentsHost {
             content,
         };
     }
-    async markAssignedTaskInProgress(threadId, content) {
+    // Only a task assigned to this agent drives a task-assignment turn: it keeps the message a
+    // task_assignment (and best-effort flips an open task to in_progress). An unassigned or
+    // other-assigned task_assignment degrades to an ordinary message, and this agent's own echo of
+    // it drops, so the creator never auto-starts work it was not assigned.
+    async resolveTaskAssignmentDelivery(msg, normalized) {
+        if (msg.message_type !== 'task_assignment') {
+            return msg;
+        }
+        const selfAgentId = await this.ensureSelfAgentId();
+        let task;
         try {
-            const selfAgentId = await this.ensureSelfAgentId();
-            const task = await waitForTaskForThread(this.borgee, threadId, {
-                preferredTaskId: extractTaskIdFromTaskAssignmentContent(content),
+            task = await waitForTaskForThread(this.borgee, msg.channel_id, {
+                preferredTaskId: extractTaskIdFromTaskAssignmentContent(normalized.content),
                 attempts: 10,
                 delayMs: 250,
             });
-            if (!task || task.status !== 'open' || task.assigneeId !== selfAgentId) {
-                return;
-            }
-            await this.borgee.updateTask({
-                taskId: task.id,
-                status: 'in_progress',
-            });
         }
         catch (error) {
-            this.logger.debugError('best-effort task auto-start failed', {
-                channelId: threadId,
+            this.logger.debugError('task-assignment resolution failed', {
+                channelId: msg.channel_id,
                 error,
             });
+            task = null;
+        }
+        if (task && task.assigneeId === selfAgentId) {
+            if (task.status === 'open') {
+                try {
+                    await this.borgee.updateTask({
+                        taskId: task.id,
+                        status: 'in_progress',
+                    });
+                }
+                catch (error) {
+                    this.logger.debugError('best-effort task auto-start failed', {
+                        channelId: msg.channel_id,
+                        error,
+                    });
+                }
+            }
+            return msg;
+        }
+        if (normalized.authorId === selfAgentId) {
+            return null;
         }
+        return { ...msg, message_type: 'default' };
     }
     async ensureSelfAgentId() {
         if (this.selfAgentId) {

package/dist/cli-args.d.ts

@@ -83,4 +83,6 @@ export declare function parseLogArgs(argv: string[]): ParsedLogArgs;
 export declare function parseDescribeManagedArgs(argv: string[]): ParsedDescribeManagedArgs;
 export declare function parseCleanupManagedArgs(argv: string[]): ParsedCleanupManagedArgs;
 export declare function parseApplyManagedArgs(argv: string[]): ParsedApplyManagedArgs;
-export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\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\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude CLI command (default: claude)\n  --claude-args <args>            Local Claude CLI args (default: --print --permission-mode bypassPermissions)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\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\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\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 --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\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";
+/** `update` always installs the latest published release; it takes no options. */
+export declare function assertNoUpdateArgs(argv: string[]): void;
+export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\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  agents-host update\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)\n  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\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\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\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  update                          Update the globally installed @borgee/agents-host to the latest release\n\nStartup update check:\n  Startup commands print an advisory notice on stderr when a newer release is published.\n  Set AGENTS_HOST_DISABLE_UPDATE_CHECK=1 to turn that check off.\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\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  agents-host update\n";

package/dist/cli-args.js

@@ -470,6 +470,15 @@ export function parseApplyManagedArgs(argv) {
     }
     return { serverUrl, input: 'argv', specJson };
 }
+/** `update` always installs the latest published release; it takes no options. */
+export function assertNoUpdateArgs(argv) {
+    const [unexpected] = argv;
+    if (unexpected !== undefined) {
+        throw new CliUsageError(unexpected.startsWith('--')
+            ? `Unknown option: ${unexpected}`
+            : `Unexpected argument: ${unexpected}`);
+    }
+}
 export const USAGE = `Usage:
   agents-host start <serverUrl> <apiKey> [options]
   agents-host start-managed <serverUrl>
@@ -486,6 +495,7 @@ export const USAGE = `Usage:
   agents-host print-layout --root <dir>
   agents-host generate-config --root <dir> --stdin
   agents-host generate-config --root <dir> --spec-json <json>
+  agents-host update
 
 Foreground start options:
   --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)
@@ -494,8 +504,8 @@ Single-agent agent options:
   --name <name>                   Display name (default: Assistant)
   --provider <claude|codex|copilot>
                                    Runtime provider (default: claude)
-  --claude-command <cmd>          Local Claude CLI command (default: claude)
-  --claude-args <args>            Local Claude CLI args (default: --print --permission-mode bypassPermissions)
+  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)
+  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)
   --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)
   --codex-args <args>             Local Codex ACP adapter args
   --copilot-command <cmd>         Local Copilot CLI command (default: copilot)
@@ -519,6 +529,11 @@ Command summary:
   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
+  update                          Update the globally installed @borgee/agents-host to the latest release
+
+Startup update check:
+  Startup commands print an advisory notice on stderr when a newer release is published.
+  Set AGENTS_HOST_DISABLE_UPDATE_CHECK=1 to turn that check off.
 
 Examples:
   agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug
@@ -534,4 +549,5 @@ Examples:
   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
+  agents-host update
 `;

package/dist/cli.d.ts

@@ -2,6 +2,8 @@
 import { applyManagedSpec, bootstrapManagedDaemonStart, cleanupManagedRuntime, describeManagedSpec } from './managed-daemon.js';
 import { runManagedDaemonLogCommand } from './managed-daemon-log.js';
 import { describeLocalConfig, generateLocalConfig, printLocalConfigLayout, runMain, validateLocalConfig } from './run.js';
+import { runUpdateCommand } from './update/update-command.js';
+import { emitUpdateNotice } from './update/update-notice.js';
 export interface CliDeps {
     env?: NodeJS.ProcessEnv;
     logger?: Pick<Console, 'error'>;
@@ -17,6 +19,8 @@ export interface CliDeps {
     describeManagedSpec?: typeof describeManagedSpec;
     cleanupManagedRuntime?: typeof cleanupManagedRuntime;
     applyManagedSpec?: typeof applyManagedSpec;
+    runUpdateCommand?: typeof runUpdateCommand;
+    emitUpdateNotice?: typeof emitUpdateNotice;
     stdout?: Pick<Console, 'log'>;
 }
 interface CliEntrypointDeps {

package/dist/cli.js

@@ -2,11 +2,13 @@
 import { realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CliUsageError, parseApplyManagedArgs, parseDaemonArgs, parseDescribeArgs, parseDescribeManagedArgs, parseCleanupManagedArgs, parseGenerateConfigArgs, parseLogArgs, parseManagedStartArgs, parsePrintLayoutArgs, parseStartArgs, parseValidateArgs, USAGE, } from './cli-args.js';
+import { assertNoUpdateArgs, CliUsageError, parseApplyManagedArgs, parseDaemonArgs, parseDescribeArgs, parseDescribeManagedArgs, parseCleanupManagedArgs, parseGenerateConfigArgs, parseLogArgs, parseManagedStartArgs, parsePrintLayoutArgs, parseStartArgs, parseValidateArgs, USAGE, } from './cli-args.js';
 import { resolveAgentsHostDebugMode } from './debug.js';
 import { applyManagedSpec, bootstrapManagedDaemonStart, cleanupManagedRuntime, describeManagedSpec, ManagedAgentsHostDaemon, } from './managed-daemon.js';
 import { runManagedDaemonLogCommand } from './managed-daemon-log.js';
 import { describeLocalConfig, generateLocalConfig, printLocalConfigLayout, runMain, validateLocalConfig, } from './run.js';
+import { runUpdateCommand } from './update/update-command.js';
+import { emitUpdateNotice } from './update/update-notice.js';
 function formatErrorMessage(error) {
     if (error instanceof Error) {
         return error.message;
@@ -46,9 +48,12 @@ export async function dispatchCli(argv, deps = {}) {
         });
     const readStdin = deps.readStdin ?? readAllStdin;
     const stdout = deps.stdout ?? console;
+    const runUpdateCommandImpl = deps.runUpdateCommand ?? runUpdateCommand;
+    const emitUpdateNoticeImpl = deps.emitUpdateNotice ?? emitUpdateNotice;
     if (command === 'start') {
         const parsed = parseStartArgs(rest);
         const debug = resolveAgentsHostDebugMode(parsed.debug, env);
+        await emitUpdateNoticeImpl({ env });
         if (parsed.mode === 'single-agent') {
             env.BORGEE_BASE_URL = parsed.serverUrl;
             env.BORGEE_AGENT_API_KEY = parsed.apiKey;
@@ -67,6 +72,7 @@ export async function dispatchCli(argv, deps = {}) {
         if (resolveAgentsHostDebugMode(false, env)) {
             throw new CliUsageError('start-managed does not support debug mode; use foreground start or start --config --debug instead');
         }
+        await emitUpdateNoticeImpl({ env });
         if (parsed.apiKey === undefined) {
             await bootstrapManagedDaemonStartImpl({
                 serverUrl: parsed.serverUrl,
@@ -165,6 +171,11 @@ export async function dispatchCli(argv, deps = {}) {
         await startManagedDaemonImpl(parsed.rootPath, parsed.debug);
         return;
     }
+    if (command === 'update') {
+        assertNoUpdateArgs(rest);
+        await runUpdateCommandImpl();
+        return;
+    }
     throw new CliUsageError(`Unknown command: ${command}`);
 }
 async function readAllStdin() {

package/dist/compatibility-gates.js

@@ -21,7 +21,6 @@ export const INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV = 'AGENTS_HOST_INTERNAL_PROVI
 export const MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION = 1;
 const VALID_PROVIDER_IMPLEMENTATION_ENTRIES = '"claude:v1", "claude:v2", "copilot:v1", or "copilot:v2"';
 export const DEFAULT_INTERNAL_COMPATIBILITY_GATES = Object.freeze([
-    CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE,
     COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE,
     COLLABORATION_OUTCOME_MODEL_COMPATIBILITY_GATE,
     CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE,
@@ -118,11 +117,15 @@ export function resolveManagedRuntimeProviderImplementationOverrides(env = proce
     const enabledGates = new Set(compatibilityGates);
     return normalizeInternalProviderImplementationOverrides(env[INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV]).filter((assignment) => {
         const [provider] = assignment.split(':');
+        if (provider === 'claude') {
+            return false;
+        }
         return enabledGates.has(PROVIDER_IMPLEMENTATION_COMPATIBILITY_GATES[provider]);
     });
 }
 export function resolveManagedRuntimeCompatibilityGates(env = process.env) {
     const compatibilityGates = new Set(resolveInternalCompatibilityGates(env));
+    compatibilityGates.delete(CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE);
     const explicitlyEnabledGates = parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV]);
     if (compatibilityGates.has(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE)) {
         compatibilityGates.add(CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE);

package/dist/config.d.ts

@@ -1,6 +1,9 @@
 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_CLAUDE_COMMAND = "claude-agent-acp";
+export declare const LEGACY_CLAUDE_COMMAND = "claude";
+export declare const LEGACY_CLAUDE_ONE_SHOT_ARGS: readonly ["--print", "--permission-mode", "bypassPermissions"];
 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;
@@ -9,5 +12,10 @@ export declare function optionalStringArray(value: unknown, fieldName: string, s
 export declare function parseCopilotSessionTtlMinutesValue(value: unknown, sourceLabel: string): number;
 export declare function resolveProvider(rawValue: string, sourceLabel: string): ProviderKind;
 export declare function assertProviderCompatibility(provider: ProviderKind, sourceLabel: string, env?: NodeJS.ProcessEnv): void;
+export declare function isLegacyClaudeCompatibilityAlias(command: string, args: string[]): boolean;
+export declare function isLegacyClaudeBinaryCommand(command: string): boolean;
+export declare function hasLegacyClaudeOneShotArgs(args: string[]): boolean;
+export declare function assertClaudeCommandCompatibility(command: string, args: string[], sourceLabel: string): void;
+export declare function assertProviderCommandCompatibility(provider: ProviderKind, config: Pick<ProviderCommandConfig, 'claudeCommand' | 'claudeArgs'>, sourceLabel: string): void;
 export declare function resolveProviderCommandConfig(overrides?: Partial<ProviderCommandConfig>): ProviderCommandConfig;
 export declare function loadConfigFromEnv(env?: NodeJS.ProcessEnv): AgentsHostConfig;

package/dist/config.js

@@ -1,11 +1,15 @@
+import { basename } from 'node:path';
 import { resolveSingleAgentStateRoot } from './state-paths.js';
 import { CODEX_PROVIDER_COMPATIBILITY_GATE, resolveInternalCompatibilityGates, } from './compatibility-gates.js';
 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_CLAUDE_COMMAND = 'claude-agent-acp';
+export const LEGACY_CLAUDE_COMMAND = 'claude';
+export const LEGACY_CLAUDE_ONE_SHOT_ARGS = ['--print', '--permission-mode', 'bypassPermissions'];
 export const DEFAULT_PROVIDER_COMMAND_CONFIG = {
-    claudeCommand: 'claude',
-    claudeArgs: ['--print', '--permission-mode', 'bypassPermissions'],
+    claudeCommand: DEFAULT_CLAUDE_COMMAND,
+    claudeArgs: [],
     codexCommand: 'codex-acp',
     codexArgs: [],
     copilotCommand: 'copilot',
@@ -74,6 +78,38 @@ export function assertProviderCompatibility(provider, sourceLabel, env = process
         throw new Error(`${sourceLabel}: provider "codex" requires the shipped ${CODEX_PROVIDER_COMPATIBILITY_GATE} path to remain enabled`);
     }
 }
+export function isLegacyClaudeCompatibilityAlias(command, args) {
+    if (command !== LEGACY_CLAUDE_COMMAND || args.length !== LEGACY_CLAUDE_ONE_SHOT_ARGS.length) {
+        return false;
+    }
+    return args.every((arg, index) => arg === LEGACY_CLAUDE_ONE_SHOT_ARGS[index]);
+}
+export function isLegacyClaudeBinaryCommand(command) {
+    return basename(command) === LEGACY_CLAUDE_COMMAND;
+}
+export function hasLegacyClaudeOneShotArgs(args) {
+    return (args.length === LEGACY_CLAUDE_ONE_SHOT_ARGS.length
+        && args.every((arg, index) => arg === LEGACY_CLAUDE_ONE_SHOT_ARGS[index]));
+}
+export function assertClaudeCommandCompatibility(command, args, sourceLabel) {
+    if (command === DEFAULT_CLAUDE_COMMAND) {
+        if (args.length > 0) {
+            throw new Error(`Invalid Claude config in ${sourceLabel}: the shipped ${DEFAULT_CLAUDE_COMMAND} path does not accept CLAUDE_ARGS/claudeArgs. Leave them empty or point claudeCommand/CLAUDE_COMMAND at a custom ACP adapter command instead.`);
+        }
+        return;
+    }
+    if (isLegacyClaudeBinaryCommand(command)) {
+        if (isLegacyClaudeCompatibilityAlias(command, args)) {
+            return;
+        }
+        throw new Error(`Invalid Claude config in ${sourceLabel}: raw "${LEGACY_CLAUDE_COMMAND}" commands no longer speak ACP directly. Use the shipped ${DEFAULT_CLAUDE_COMMAND} default, keep only the exact legacy compatibility alias "${LEGACY_CLAUDE_COMMAND} ${LEGACY_CLAUDE_ONE_SHOT_ARGS.join(' ')}", or point claudeCommand/CLAUDE_COMMAND at a real ACP adapter command.`);
+    }
+}
+export function assertProviderCommandCompatibility(provider, config, sourceLabel) {
+    if (provider === 'claude') {
+        assertClaudeCommandCompatibility(config.claudeCommand, config.claudeArgs, sourceLabel);
+    }
+}
 export function resolveProviderCommandConfig(overrides = {}) {
     return {
         claudeCommand: overrides.claudeCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand,
@@ -89,20 +125,22 @@ export function loadConfigFromEnv(env = process.env) {
     const provider = resolveProvider(envOr('RUNTIME_PROVIDER', 'claude', env), 'Unsupported RUNTIME_PROVIDER');
     assertProviderCompatibility(provider, 'Unsupported RUNTIME_PROVIDER', env);
     const agentApiKey = requireEnv('BORGEE_AGENT_API_KEY', env);
+    const providerConfig = resolveProviderCommandConfig({
+        claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
+        claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),
+        codexCommand: envOr('CODEX_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.codexCommand, env),
+        codexArgs: parseArgs(envOr('CODEX_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.codexArgs.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,
+    });
+    assertProviderCommandCompatibility(provider, providerConfig, 'environment variables');
     return {
         borgeeBaseUrl: requireEnv('BORGEE_BASE_URL', env),
         stateRootDir: resolveSingleAgentStateRoot(env, undefined, agentApiKey),
-        ...resolveProviderCommandConfig({
-            claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
-            claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),
-            codexCommand: envOr('CODEX_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.codexCommand, env),
-            codexArgs: parseArgs(envOr('CODEX_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.codexArgs.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,
-        }),
+        ...providerConfig,
         agent: {
             agentApiKey,
             agentName: envOr('BORGEE_AGENT_NAME', 'Assistant', env),

package/dist/context/prompt.js

@@ -48,7 +48,7 @@ function buildLocalhostGatewayPromptLines(context) {
         lines.push('Task-collection commands remain disabled inside this task thread; use the parent channel for create/list task operations.', `Node get current thread task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task`, `Node update current thread task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`, `Python get current thread task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task`, `Python update current thread task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`);
     }
     else {
-        lines.push(`Node create task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Node list tasks: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Node get task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Node update task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`, `Python create task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Python list tasks: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Python get task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Python update task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`);
+        lines.push(`Node create task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Node list tasks: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Node get task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Node read task thread history: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-task-history --task-id "<task-id>" --limit 20`, `Node update task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`, `Python create task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Python list tasks: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Python get task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Python read task thread history: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-task-history --task-id "<task-id>" --limit 20`, `Python update task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`);
     }
     if (context.localhostGateway.collaboration?.enabled &&
         (context.collaborationTurnMode ?? 'ordinary') === 'ordinary') {