@borgee/agents-host 0.2.31 → 0.2.33

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
@@ -232,6 +233,7 @@ 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-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. |
@@ -506,6 +508,68 @@ 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/chat/sdk-chat-control-plane.d.ts

@@ -1,4 +1,4 @@
-import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent } from '@borgee/plugin-sdk';
+import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent } from '../plugin-sdk.js';
 import type { ChannelSummary, ChannelHistoryEntry, ChannelMessageEvent, CreateTaskInput, DirectoryUser, MeResponseUser, PostMessageInput, PostedMessage, ReadChannelHistoryInput, Task, UpdateTaskInput } from '../types.js';
 import type { ChatControlPlane } from './chat-control-plane.js';
 type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'readHistory' | 'sendMessage' | 'startTyping' | 'updateTask'>;

package/dist/chat/sdk-chat-control-plane.js

@@ -1,4 +1,4 @@
-import { createBorgeePlugin, } from '@borgee/plugin-sdk';
+import { createBorgeePlugin, } from '../plugin-sdk.js';
 /**
  * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
  * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface

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 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\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)
@@ -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/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') {

package/dist/durable-cursor-store.d.ts

@@ -1,4 +1,4 @@
-import { type CursorStore } from '@borgee/plugin-sdk';
+import { type CursorStore } from './plugin-sdk.js';
 export interface DurableCursorStoreOptions {
     stateRootDir: string;
 }

package/dist/durable-cursor-store.js

@@ -1,4 +1,4 @@
-import { FileCursorStore } from '@borgee/plugin-sdk';
+import { FileCursorStore } from './plugin-sdk.js';
 import { resolveAgentCursorPath } from './state-paths.js';
 export function createDurableCursorStore(options) {
     return new FileCursorStore({

package/dist/gateway/localhost-gateway.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { BorgeeError, PermissionDeniedError } from '@borgee/plugin-sdk';
+import { BorgeeError, PermissionDeniedError } from '../plugin-sdk.js';
 import { SqliteConnectionsStateStore } from '../connections-state-store.js';
 import { evaluateGatewayAuthorization, } from '../policy/gateway-authorization.js';
 import { resolveConnectionsStatePath } from '../state-paths.js';
@@ -505,6 +505,33 @@ class LoopbackLocalhostGatewayController {
                     this.recordAudit('authorized', 200, decision.path, request.method ?? 'GET', decision.binding);
                     return;
                 }
+                case 'task-history': {
+                    // The thread this reads is the one the server recorded on the task: thread_id is
+                    // written once by task creation and is not part of the task update whitelist, so no
+                    // client can repoint an in-scope task at another channel's messages after the check.
+                    const task = await this.loadAuthorizedTask(binding.channelId, decision.route);
+                    if (!task.threadId) {
+                        this.sendJson(response, 404, { error: 'not_found' });
+                        this.recordAudit('not-found', 404, decision.path, request.method ?? 'GET', decision.binding);
+                        return;
+                    }
+                    const url = new URL(request.url ?? '/', baseUrl);
+                    const limit = clampHistoryLimit(url.searchParams.get('limit'));
+                    const before = parseOptionalInteger(url.searchParams.get('before'));
+                    const after = parseOptionalInteger(url.searchParams.get('after'));
+                    const messages = await this.controlPlane.readChannelHistory({
+                        channelId: task.threadId,
+                        before,
+                        after,
+                        limit,
+                    });
+                    this.sendJson(response, 200, { messages });
+                    // Presence of `readChannelId` is the cross-channel disclosure signal, so it is
+                    // stamped only when the thread really is another channel; a task read from inside
+                    // its own thread would otherwise imply a disclosure that never happened.
+                    this.recordAudit('authorized', 200, decision.path, request.method ?? 'GET', decision.binding, task.threadId === binding.channelId ? undefined : { readChannelId: task.threadId });
+                    return;
+                }
                 case 'users': {
                     if (!binding.payload?.localhostGateway?.collaboration?.enabled) {
                         this.sendJson(response, 404, { error: 'not_found' });
@@ -604,7 +631,7 @@ class LoopbackLocalhostGatewayController {
         response.setHeader('content-type', 'application/json; charset=utf-8');
         response.end(`${JSON.stringify(payload)}\n`);
     }
-    recordAudit(reason, status, path, method, binding) {
+    recordAudit(reason, status, path, method, binding, readTarget) {
         if (!this.policyAuditGateEnabled) {
             return;
         }
@@ -616,6 +643,7 @@ class LoopbackLocalhostGatewayController {
             reason,
             agentId: binding?.agentId,
             channelId: binding?.channelId,
+            ...readTarget,
             method,
             path,
             status,

package/dist/index.js

@@ -1,11 +1,14 @@
 import { resolveAgentsHostDebugMode } from './debug.js';
 import { runMain } from './run.js';
+import { emitUpdateNotice } from './update/update-notice.js';
 // Plain env-var entry point (`pnpm dev` / `pnpm start`) for the standalone
 // single-agent process. For the CLI entry point that accepts foreground
 // `agents-host start <serverUrl> <apiKey> ...` and opt-in
 // `agents-host start-managed <serverUrl>` / `agents-host start-managed <serverUrl> <apiKey> ...`,
 // see cli.ts.
-runMain({ debug: resolveAgentsHostDebugMode(false, process.env) }).catch((error) => {
+emitUpdateNotice({ env: process.env })
+    .then(() => runMain({ debug: resolveAgentsHostDebugMode(false, process.env) }))
+    .catch((error) => {
     console.error('[agents-host] fatal error:', error);
     process.exitCode = 1;
 });