@borgee/agents-host 0.2.33 → 0.2.35

package/README.md

@@ -89,7 +89,7 @@ The current shipped internal compatibility surface resolves gates in this order:
 2. add any explicit entries from `AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES`
 3. subtract any explicit entries from `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES`
 
-The shipped default set now also includes `connections-state-layer`, `context-injection`, `skill-runtime`, `localhost-gateway`, `token-binding`, `collaboration-outcome-model`, `task-thread-collaboration-contract`, and `collaboration-capabilities-diagnostics`. `attention-follow-semantics`, `collaboration-skill-first`, and hosted `praestoclaw-provider` still remain opt-in.
+The shipped default set now also includes `connections-state-layer`, `context-injection`, `skill-runtime`, `localhost-gateway`, `token-binding`, `collaboration-outcome-model`, `task-thread-collaboration-contract`, `collaboration-capabilities-diagnostics`, and `provider-idle-shutdown`. `attention-follow-semantics`, `collaboration-skill-first`, and hosted `praestoclaw-provider` still remain opt-in.
 
 Managed-runtime settings still preserve the managed rollback rule for `connections-state-layer` plus `token-binding`: when `managed-runtime-convergence` remains enabled, the managed surface forces that pair on; explicitly disabling `managed-runtime-convergence` removes that pair from the managed surface again unless you also explicitly re-enable them.
 
@@ -101,6 +101,7 @@ Rollback and hardening controls stay explicit:
 - `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=<comma-list>` disables shipped gates for rollback
 - `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
+- `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=provider-idle-shutdown` keeps every provider's shared ACP adapter process resident again; `PROVIDER_IDLE_SHUTDOWN_MINUTES=0` does the same without touching gates
 
 Or with the CLI:
 
@@ -240,6 +241,9 @@ Notes:
 | `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                                                    |
+| `PROVIDER_IDLE_SHUTDOWN_MINUTES`   | `--provider-idle-shutdown-minutes`     | no       | `10`                                          | Idle window before the agent's shared ACP adapter **process** is shut down and re-spawned on the next turn. Applies to Claude, Codex, and Copilot. `0` keeps the process resident. Must be non-negative and no larger than the Node.js timer limit (~35791.39 minutes); anything else is rejected at startup. |
+
+`COPILOT_SESSION_TTL_MINUTES` and `PROVIDER_IDLE_SHUTDOWN_MINUTES` are two different layers and do not replace each other. The first evicts an individual idle Copilot ACP *session* inside a running adapter process. The second shuts the shared adapter *process* itself down once every channel it hosts is idle, for all three providers, and takes every live session in that process with it. See [Conversation memory](#conversation-memory) for what happens to those sessions afterwards.
 
 ## Local-config mode
 
@@ -325,7 +329,8 @@ The spec shape is:
       "codexArgs": [],
       "copilotCommand": "copilot",
       "copilotArgs": ["-s", "--no-color", "--allow-all-tools", "--output-format", "text"],
-      "copilotSessionTtlMinutes": 2880
+      "copilotSessionTtlMinutes": 2880,
+      "providerIdleShutdownMinutes": 10
     }
   },
   "agents": [
@@ -398,6 +403,7 @@ defaults:
     - --output-format
     - text
   copilotSessionTtlMinutes: 2880
+  providerIdleShutdownMinutes: 10
 ```
 
 Host config fields:
@@ -411,6 +417,7 @@ Host config fields:
 - `defaults.copilotCommand`
 - `defaults.copilotArgs`
 - `defaults.copilotSessionTtlMinutes`
+- `defaults.providerIdleShutdownMinutes`
 
 Absent host defaults fall back to the same code-level defaults used by the
 standalone env flow, foreground `start`, and `start-managed`.
@@ -434,8 +441,8 @@ Agent config fields:
 - `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`
+  `codexArgs`, `copilotCommand`, `copilotArgs`,
+  `copilotSessionTtlMinutes`, and `providerIdleShutdownMinutes`
 
 Array overrides are **replacement**, not concatenation. For example, an agent
 `claudeArgs` value replaces the host default `claudeArgs` entirely.
@@ -504,9 +511,23 @@ 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.
-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.
+
+We keep no transcript or history store of our own — only the native session id each provider should try to reopen next time. The transcripts themselves live in each CLI's own on-disk session store: `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for Claude, `~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-<timestamp>-<threadId>.jsonl` for Codex, and `~/.copilot/session-state/<guid>/` for Copilot. Because those stores are on disk rather than in the adapter process, a session can be reopened later by a *different* process on the same machine — which is what makes conversation memory survive both a host restart and the idle recycle below. Continuity is same-machine and same-`$HOME` only: another machine, or a different home directory, has no session to reopen.
+
+### Idle adapter shutdown
+
+Each of those subprocesses is shut down once every channel it hosts has been idle for `PROVIDER_IDLE_SHUTDOWN_MINUTES` (default `10`), and a fresh one is spawned lazily on the next turn. "Idle" means the host has no active turn, no queued turn, no ACP session start in flight, and nothing still being processed for any channel of that agent; a turn that arrives mid-shutdown waits for the teardown and then starts the replacement rather than failing. Only the provider subprocess is recycled — the agent stays connected to Borgee, the loopback gateway keeps running, and the agents-host process itself is untouched.
+
+Conversation memory normally survives the recycle. Before the process goes away the host closes each live ACP session, and on the next turn it reopens the persisted session id against the CLI's on-disk store — Claude and Codex through ACP `session/resume`, Copilot through `session/load` (a sequential resume rather than a live re-sync; the replayed history is discarded locally instead of being re-posted to the channel). This is the same restore path a host restart takes, and its ordinary outcome is that the model still remembers the conversation.
+
+When a restore does fail, the run does not break: the stale session id is dropped, a fresh `session/new` starts, and the turn still answers coherently because the host re-materializes the per-channel `context.json` and re-injects the same bootstrap context on **every** turn regardless. What is lost in that case is only the CLI-native transcript. The situations that actually cause it:
+
+- **A different machine or a different `$HOME`.** The session store is local, so continuity never crosses hosts.
+- **A stale Copilot session lock.** The Copilot CLI does not reliably unlink its `inuse.<pid>.lock` on an unclean exit ([github/copilot-cli#3255](https://github.com/github/copilot-cli/issues/3255), still open), so a force-killed process can leave a lock that makes the next restore believe the session is still in use. The idle teardown mitigates this: it gives the CLI a 5-second SIGTERM grace before any SIGKILL — twenty times the grace a fatal teardown uses — precisely so the CLI has time to unlink that lock. This is an internal default, not a knob.
+- **A very large Copilot transcript.** Long-running channels can hit upstream resume bugs: slow or memory-hungry resume ([#4251](https://github.com/github/copilot-cli/issues/4251)), a session that becomes unloadable once `events.jsonl` outgrows the V8 maximum string length ([#4325](https://github.com/github/copilot-cli/issues/4325)), and a resume-triggered compaction hang ([#4138](https://github.com/github/copilot-cli/issues/4138)). A Copilot resume may also reset the model back to the default ([#4397](https://github.com/github/copilot-cli/issues/4397)).
+- **Our own mapping rules, which are stricter than the CLI's.** We only reuse a persisted session id when the session's working directory *and* the set of directories exposed to it still match. So an ordinary channel turn and an eligible `task_assignment` turn — which runs in its own task workspace — deliberately do not share a session, and the switch between them starts a fresh one even though the CLI could still load the old session.
+
+If you would rather keep the adapter process resident than take any of that, set `PROVIDER_IDLE_SHUTDOWN_MINUTES=0`, raise the window, or roll the behavior back entirely with `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=provider-idle-shutdown`.
 
 ## Staying up to date
 

package/dist/agents-host.d.ts

@@ -21,6 +21,11 @@ export declare class AgentsHost {
     private readonly activeTurns;
     private readonly awaitingUserByChannel;
     private readonly collaborationOutcomeByChannel;
+    /**
+     * The session id last recorded per task, so a multi-turn task writes the
+     * property once rather than on every turn that reuses the same session.
+     */
+    private readonly recordedAgentSessionByTask;
     private readonly attentionSnapshotByChannel;
     private readonly missedCollaborationDiagnosticByChannel;
     private readonly progressChannelQueues;
@@ -93,6 +98,18 @@ export declare class AgentsHost {
     private confirmProtocolMessage;
     private resolveAttentionStatePath;
     private buildDefaultAttentionSnapshot;
+    /**
+     * Record which provider session worked this task, as agent.session_id.
+     *
+     * agents-host writes it rather than the agent: the session id is runtime
+     * state the agent has no reliable view of, so asking it to report its own
+     * would make the association depend on the agent remembering to.
+     *
+     * Best-effort and off the turn's critical path — a task whose session id
+     * failed to record is still a task that ran, so a failure here must neither
+     * fail the turn nor delay it.
+     */
+    private recordAgentSessionOnTask;
     private buildTurnTaskThreadContext;
     private ensureAttentionSnapshotLoaded;
     private revalidateAttentionSnapshotForTurn;

package/dist/agents-host.js

@@ -135,6 +135,7 @@ class DefaultHostRuntime {
                     copilotCommand: config.copilotCommand,
                     copilotArgs: config.copilotArgs,
                     copilotSessionTtlMinutes: config.copilotSessionTtlMinutes,
+                    providerIdleShutdownMinutes: config.providerIdleShutdownMinutes,
                 }, deps.logger, {
                     compatibilityGates,
                     authorizationAuditSink: this.authorizationAuditSink,
@@ -361,6 +362,11 @@ class DraftMessageController {
         return this.writeChain;
     }
 }
+/**
+ * The registered task property agents-host writes to record which provider
+ * session worked a task. It matches the server's registry key.
+ */
+const AGENT_SESSION_TASK_PROPERTY_KEY = 'agent.session_id';
 const BLOCKED_AUTHOR_REFRESH_BACKOFF_MS = 1_000;
 const MAX_QUEUED_MESSAGES_PER_CHANNEL = 8;
 const COLLABORATION_SENDS_PER_TURN = 1;
@@ -383,6 +389,11 @@ export class AgentsHost {
     activeTurns = new Set();
     awaitingUserByChannel = new Map();
     collaborationOutcomeByChannel = new Map();
+    /**
+     * The session id last recorded per task, so a multi-turn task writes the
+     * property once rather than on every turn that reuses the same session.
+     */
+    recordedAgentSessionByTask = new Map();
     attentionSnapshotByChannel = new Map();
     missedCollaborationDiagnosticByChannel = new Map();
     progressChannelQueues = new Map();
@@ -504,6 +515,7 @@ export class AgentsHost {
         this.collaborationOutcomeByChannel.clear();
         this.attentionSnapshotByChannel.clear();
         this.missedCollaborationDiagnosticByChannel.clear();
+        this.recordedAgentSessionByTask.clear();
         this.controlPlaneClosed = true;
         await this.runtime.stop();
         await Promise.allSettled([...this.activeTurns]);
@@ -1730,6 +1742,41 @@ export class AgentsHost {
             turnExecutionId: options?.turnExecutionId,
         });
     }
+    /**
+     * Record which provider session worked this task, as agent.session_id.
+     *
+     * agents-host writes it rather than the agent: the session id is runtime
+     * state the agent has no reliable view of, so asking it to report its own
+     * would make the association depend on the agent remembering to.
+     *
+     * Best-effort and off the turn's critical path — a task whose session id
+     * failed to record is still a task that ran, so a failure here must neither
+     * fail the turn nor delay it.
+     */
+    async recordAgentSessionOnTask(channelId, taskThreadContext, sessionId) {
+        const taskId = taskThreadContext?.state === 'active' ? taskThreadContext.currentTaskId : undefined;
+        if (!taskId || !sessionId) {
+            return;
+        }
+        if (this.recordedAgentSessionByTask.get(taskId) === sessionId) {
+            return;
+        }
+        try {
+            await this.borgee.setTaskProperty({
+                taskId,
+                key: AGENT_SESSION_TASK_PROPERTY_KEY,
+                value: sessionId,
+            });
+            this.recordedAgentSessionByTask.set(taskId, sessionId);
+        }
+        catch (error) {
+            this.logger.debugError('best-effort agent session property write failed', {
+                channelId,
+                taskId,
+                error,
+            });
+        }
+    }
     async buildTurnTaskThreadContext(msg, channelId) {
         if (msg.message_type === 'task_assignment') {
             const currentTaskId = extractTaskIdFromTaskAssignmentContent(String(msg.content ?? msg.body ?? ''));
@@ -2126,6 +2173,11 @@ export class AgentsHost {
                 : undefined);
             publicReplyText = resolvePublicReplyText(reply);
             visibleReplyBody = this.resolveVisibleTurnBody(activeTurn, reply, publicReplyText);
+            // NOT awaited: nothing downstream reads the result, and awaiting it here
+            // widens the window before the staleness check below, where a slow write
+            // can get an already-finished reply discarded. The method swallows its own
+            // errors, so there is nothing for a caller to handle.
+            void this.recordAgentSessionOnTask(channelId, taskThreadContext, reply.sessionId);
             const appliedAttentionSnapshot = this.applyAttentionUpdate(channelId, attentionSnapshot, reply.controlMalformed
                 ? undefined
                 : (reply.control && 'attentionUpdate' in reply.control

package/dist/chat/chat-control-plane.d.ts

@@ -18,4 +18,13 @@ export interface ChatControlPlane {
         taskId: string;
     }): Promise<Task>;
     updateTask(input: UpdateTaskInput): Promise<Task>;
+    setTaskProperty(input: {
+        taskId: string;
+        key: string;
+        value: string;
+    }): Promise<Task>;
+    deleteTaskProperty(input: {
+        taskId: string;
+        key: string;
+    }): Promise<Task>;
 }

package/dist/chat/sdk-chat-control-plane.d.ts

@@ -1,7 +1,7 @@
 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'>;
+type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'readHistory' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
 type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'cursorStore' | 'pluginId'>;
 /**
@@ -34,6 +34,15 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
         taskId: string;
     }): Promise<Task>;
     updateTask(input: UpdateTaskInput): Promise<Task>;
+    setTaskProperty(input: {
+        taskId: string;
+        key: string;
+        value: string;
+    }): Promise<Task>;
+    deleteTaskProperty(input: {
+        taskId: string;
+        key: string;
+    }): Promise<Task>;
 }
 export declare function mapInboundToChannelMessage(event: InboundMessageEvent): ChannelMessageEvent;
 export {};

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

@@ -123,6 +123,12 @@ export class SdkChatControlPlane {
     async updateTask(input) {
         return this.client.updateTask(input);
     }
+    async setTaskProperty(input) {
+        return this.client.setTaskProperty(input);
+    }
+    async deleteTaskProperty(input) {
+        return this.client.deleteTaskProperty(input);
+    }
 }
 export function mapInboundToChannelMessage(event) {
     return {

package/dist/cli-args.d.ts

@@ -85,4 +85,4 @@ export declare function parseCleanupManagedArgs(argv: string[]): ParsedCleanupMa
 export declare function parseApplyManagedArgs(argv: string[]): ParsedApplyManagedArgs;
 /** `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";
+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  --provider-idle-shutdown-minutes <minutes>\n                                   Shut the shared ACP adapter process down after this much idle\n                                   time and re-spawn it on the next turn; 0 keeps it resident\n                                   (default: 10)\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

@@ -15,6 +15,7 @@ export const CLI_FLAG_TO_ENV = {
     'copilot-command': 'COPILOT_COMMAND',
     'copilot-args': 'COPILOT_ARGS',
     'copilot-session-ttl-minutes': 'COPILOT_SESSION_TTL_MINUTES',
+    'provider-idle-shutdown-minutes': 'PROVIDER_IDLE_SHUTDOWN_MINUTES',
 };
 const SINGLE_AGENT_FLAG_NAMES = new Set(Object.keys(CLI_FLAG_TO_ENV));
 const FLAGS_ALLOWING_DASH_PREFIX_VALUE = new Set(['claude-args', 'codex-args', 'copilot-args']);
@@ -512,6 +513,10 @@ Single-agent agent options:
   --copilot-args <args>           Ignored by the Copilot ACP prototype
   --copilot-session-ttl-minutes <minutes>
                                    Idle session TTL for Copilot ACP sessions (default: 2880)
+  --provider-idle-shutdown-minutes <minutes>
+                                   Shut the shared ACP adapter process down after this much idle
+                                   time and re-spawn it on the next turn; 0 keeps it resident
+                                   (default: 10)
 
 Command summary:
   start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)

package/dist/compatibility-gates.d.ts

@@ -13,6 +13,7 @@ export declare const COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE =
 export declare const TOKEN_BINDING_COMPATIBILITY_GATE = "token-binding";
 export declare const POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE = "policy-audit-enforcement";
 export declare const MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE = "managed-runtime-convergence";
+export declare const PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE = "provider-idle-shutdown";
 export declare const COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES";
 export declare const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES";
 export declare const INTERNAL_POLICY_MODE_ENV = "AGENTS_HOST_INTERNAL_POLICY_MODE";

package/dist/compatibility-gates.js

@@ -14,6 +14,7 @@ export const COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE = 'collab
 export const TOKEN_BINDING_COMPATIBILITY_GATE = 'token-binding';
 export const POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE = 'policy-audit-enforcement';
 export const MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE = 'managed-runtime-convergence';
+export const PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE = 'provider-idle-shutdown';
 export const COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES';
 export const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES';
 export const INTERNAL_POLICY_MODE_ENV = 'AGENTS_HOST_INTERNAL_POLICY_MODE';
@@ -30,6 +31,7 @@ export const DEFAULT_INTERNAL_COMPATIBILITY_GATES = Object.freeze([
     LOCALHOST_GATEWAY_COMPATIBILITY_GATE,
     MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE,
     POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE,
+    PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE,
     SKILL_RUNTIME_COMPATIBILITY_GATE,
     TASK_THREAD_COLLABORATION_CONTRACT_COMPATIBILITY_GATE,
     TOKEN_BINDING_COMPATIBILITY_GATE,

package/dist/config.d.ts

@@ -1,6 +1,8 @@
 import type { AgentsHostConfig, ProviderCommandConfig, ProviderKind } from './types.js';
-export declare const MAX_COPILOT_SESSION_TTL_MINUTES: number;
+export declare const MAX_TIMER_DELAY_MINUTES: number;
 export declare const DEFAULT_COPILOT_SESSION_TTL_MINUTES: number;
+export declare const PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES = 0;
+export declare const DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES = 10;
 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"];
@@ -10,6 +12,7 @@ export declare function optionalNonEmptyString(value: unknown, fieldName: string
 export declare function parseArgs(value: string): string[];
 export declare function optionalStringArray(value: unknown, fieldName: string, sourceLabel: string): string[] | undefined;
 export declare function parseCopilotSessionTtlMinutesValue(value: unknown, sourceLabel: string): number;
+export declare function parseProviderIdleShutdownMinutesValue(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;

package/dist/config.js

@@ -2,8 +2,10 @@ 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 MAX_TIMER_DELAY_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
 export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
+export const PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES = 0;
+export const DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES = 10;
 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'];
@@ -15,6 +17,7 @@ export const DEFAULT_PROVIDER_COMMAND_CONFIG = {
     copilotCommand: 'copilot',
     copilotArgs: ['-s', '--no-color', '--allow-all-tools', '--output-format', 'text'],
     copilotSessionTtlMinutes: DEFAULT_COPILOT_SESSION_TTL_MINUTES,
+    providerIdleShutdownMinutes: DEFAULT_PROVIDER_IDLE_SHUTDOWN_MINUTES,
 };
 function requireEnv(name, env) {
     return requireNonEmptyString(env[name], `Missing required environment variable: ${name}`);
@@ -57,8 +60,18 @@ export function parseCopilotSessionTtlMinutesValue(value, sourceLabel) {
     if (!Number.isFinite(parsed) || parsed <= 0) {
         throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: expected a positive number`);
     }
-    if (parsed > MAX_COPILOT_SESSION_TTL_MINUTES) {
-        throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: must be <= ${MAX_COPILOT_SESSION_TTL_MINUTES.toFixed(2)} minutes to fit within the Node.js timer limit`);
+    if (parsed > MAX_TIMER_DELAY_MINUTES) {
+        throw new Error(`Invalid COPILOT_SESSION_TTL_MINUTES in ${sourceLabel}: must be <= ${MAX_TIMER_DELAY_MINUTES.toFixed(2)} minutes to fit within the Node.js timer limit`);
+    }
+    return parsed;
+}
+export function parseProviderIdleShutdownMinutesValue(value, sourceLabel) {
+    const parsed = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isFinite(parsed) || parsed < PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES) {
+        throw new Error(`Invalid PROVIDER_IDLE_SHUTDOWN_MINUTES in ${sourceLabel}: expected a non-negative number, where ${PROVIDER_IDLE_SHUTDOWN_DISABLED_MINUTES} keeps the shared adapter process resident`);
+    }
+    if (parsed > MAX_TIMER_DELAY_MINUTES) {
+        throw new Error(`Invalid PROVIDER_IDLE_SHUTDOWN_MINUTES in ${sourceLabel}: must be <= ${MAX_TIMER_DELAY_MINUTES.toFixed(2)} minutes to fit within the Node.js timer limit`);
     }
     return parsed;
 }
@@ -119,6 +132,8 @@ export function resolveProviderCommandConfig(overrides = {}) {
         copilotCommand: overrides.copilotCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand,
         copilotArgs: [...(overrides.copilotArgs ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs)],
         copilotSessionTtlMinutes: overrides.copilotSessionTtlMinutes ?? DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
+        providerIdleShutdownMinutes: overrides.providerIdleShutdownMinutes
+            ?? DEFAULT_PROVIDER_COMMAND_CONFIG.providerIdleShutdownMinutes,
     };
 }
 export function loadConfigFromEnv(env = process.env) {
@@ -135,6 +150,9 @@ export function loadConfigFromEnv(env = process.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,
+        providerIdleShutdownMinutes: env.PROVIDER_IDLE_SHUTDOWN_MINUTES && env.PROVIDER_IDLE_SHUTDOWN_MINUTES.trim().length > 0
+            ? parseProviderIdleShutdownMinutesValue(env.PROVIDER_IDLE_SHUTDOWN_MINUTES, 'environment variable PROVIDER_IDLE_SHUTDOWN_MINUTES')
+            : DEFAULT_PROVIDER_COMMAND_CONFIG.providerIdleShutdownMinutes,
     });
     assertProviderCommandCompatibility(provider, providerConfig, 'environment variables');
     return {

package/dist/context/main-session-delegation.d.ts

@@ -0,0 +1 @@
+export declare const MAIN_SESSION_DELEGATION_LINES: readonly string[];

package/dist/context/main-session-delegation.js

@@ -0,0 +1,6 @@
+export const MAIN_SESSION_DELEGATION_LINES = [
+    'This session is your coordination surface: read the channel, answer the human, break work down, and keep task state current here.',
+    'Delegate the actual work to subagents — research, code edits, long builds and test runs, and broad repository sweeps belong in a delegated worker instead of running inline here.',
+    'Delegation changes who executes, not who owns: the work still belongs to this thread, and you still report the result here yourself.',
+    'Stay responsive while delegated work runs, so a new incoming message never waits behind a long local operation.',
+];

package/dist/context/prompt.js

@@ -2,6 +2,7 @@ import { AWAITING_USER_CONTROL_PREFIX } from '../providers/awaiting-user.js';
 import { buildAttentionSummaryLines } from './attention.js';
 import { buildCollaborationCapabilityDeclarationSummaryLines, buildMissedCollaborationDiagnosticSummaryLines, } from './collaboration-capabilities-diagnostics.js';
 import { buildCollaborationOutcomeSummaryLines } from './collaboration-outcome.js';
+import { MAIN_SESSION_DELEGATION_LINES } from './main-session-delegation.js';
 import { buildTaskThreadCollaborationSummaryLines } from './task-thread-collaboration.js';
 function providerLabel(provider) {
     if (provider === 'copilot') {
@@ -45,10 +46,10 @@ function buildLocalhostGatewayPromptLines(context) {
     }
     lines.push('The read-only gateway commands listed in this prompt are already authorized for this turn and may be executed directly.', 'Do not ask the user for permission before using the read-only gateway commands listed below.', 'If the user asks about channel history, visible participants, or your current agent identity, run the relevant read command first and answer from its result instead of speculating about authorization.', `Node gateway checks: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --health`, `Node channel bootstrap: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-bootstrap`, `Node agent identity: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-me`, `Node channel history: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-history --limit 20`, `Python gateway checks: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --health`, `Python channel bootstrap: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-bootstrap`, `Python agent identity: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-me`, `Python channel history: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-history --limit 20`);
     if (isTaskAssignmentThread) {
-        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>"]`);
+        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>"]`, `Node set current thread task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>"`, `Node delete current thread task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>"`, `Python set current thread task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>"`, `Python delete current thread task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>"`, 'Task property keys are a closed set: link.pr (the PR implementing the task) and link.issue (the originating issue). agent.session_id is written by agents-host — do not set it. One key per call; pass <key>=<value> as one argument.');
     }
     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 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>"]`);
+        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>"]`, `Node set task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>" --task-id "<task-id>"`, `Node delete task property: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>" --task-id "<task-id>"`, `Python set task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --set-property "<key>=<value>" --task-id "<task-id>"`, `Python delete task property: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --delete-property "<key>" --task-id "<task-id>"`, 'Task property keys are a closed set: link.pr (the PR implementing the task) and link.issue (the originating issue). agent.session_id is written by agents-host — do not set it. One key per call; pass <key>=<value> as one argument.');
     }
     if (context.localhostGateway.collaboration?.enabled &&
         (context.collaborationTurnMode ?? 'ordinary') === 'ordinary') {
@@ -221,6 +222,7 @@ export function buildPrompt(params) {
         'Be concise, helpful, and honest about uncertainty.',
         'Do not claim to have performed actions you did not actually perform.',
         'Keep the visible reply text concise.',
+        ...MAIN_SESSION_DELEGATION_LINES,
         ...buildTurnControlPromptLines(params.promptContext),
         `If the user asks who you are, what powers you, or which backend/provider you use, mention that you are currently running on ${providerLabel(params.provider)}.`,
         `Channel: ${params.channelId}`,

package/dist/gateway/localhost-gateway.js

@@ -505,6 +505,23 @@ class LoopbackLocalhostGatewayController {
                     this.recordAudit('authorized', 200, decision.path, request.method ?? 'GET', decision.binding);
                     return;
                 }
+                case 'current-task-property': {
+                    const task = await this.loadCurrentThreadTask(binding);
+                    const updatedTask = await this.applyTaskPropertyChange(request, task.id, decision.route.key);
+                    this.sendTaskPropertyResult(response, decision, binding.channelId, updatedTask, request.method);
+                    return;
+                }
+                case 'task-property': {
+                    // Load first: the write must be refused for a task outside the bound
+                    // channel BEFORE it lands, not reported as not-found afterwards.
+                    const task = await this.loadAuthorizedTask(binding.channelId, {
+                        taskId: decision.route.taskId,
+                        resource: 'task',
+                    });
+                    const updatedTask = await this.applyTaskPropertyChange(request, task.id, decision.route.key);
+                    this.sendTaskPropertyResult(response, decision, binding.channelId, updatedTask, request.method);
+                    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
@@ -612,6 +629,31 @@ class LoopbackLocalhostGatewayController {
         }
         return task;
     }
+    /**
+     * PUT writes the key, DELETE removes it. The method has already been
+     * narrowed to those two by the route's allowed-method table.
+     */
+    async applyTaskPropertyChange(request, taskId, key) {
+        try {
+            if (request.method === 'DELETE') {
+                return await this.controlPlane.deleteTaskProperty({ taskId, key });
+            }
+            const body = await readGatewayJsonBody(request);
+            return await this.controlPlane.setTaskProperty({ taskId, key, value: parseTaskPropertyValue(body) });
+        }
+        catch (error) {
+            throw mapGatewayControlPlaneError(error, 'authorized');
+        }
+    }
+    sendTaskPropertyResult(response, decision, boundChannelId, task, method) {
+        if (!isTaskInAuthorizedScope(boundChannelId, task)) {
+            this.sendJson(response, 404, { error: 'not_found' });
+            this.recordAudit('not-found', 404, decision.path, method ?? 'PUT', decision.binding);
+            return;
+        }
+        this.sendJson(response, 200, task);
+        this.recordAudit('authorized', 200, decision.path, method ?? 'PUT', decision.binding);
+    }
     async loadCurrentThreadTask(binding) {
         let task;
         const preferredTaskId = binding.payload?.taskAssignmentContext?.currentTaskId;
@@ -816,6 +858,17 @@ function parseUpdateTaskInput(taskId, body) {
     }
     return input;
 }
+/**
+ * The value is required and must be a string. An absent or non-string value is
+ * a caller bug, not an instruction to store the empty string — storing that
+ * would silently blank a key the caller meant to set.
+ */
+function parseTaskPropertyValue(body) {
+    if (!isRecord(body) || typeof body.value !== 'string') {
+        throw new GatewayHttpError(400, { error: 'invalid_property_value' }, 'bad-request');
+    }
+    return body.value;
+}
 function isTaskInAuthorizedScope(boundChannelId, task) {
     return task.channelId === boundChannelId || task.threadId === boundChannelId;
 }
@@ -846,6 +899,19 @@ function mapGatewayControlPlaneError(error, fallbackReason) {
             case 'bpp.channel_id_required':
             case 'bpp.task_id_required':
                 return new GatewayHttpError(400, { error: 'bad_request' }, 'bad-request');
+            // An unregistered key or an oversized value is the caller's own mistake.
+            // Falling through to 502 would tell the agent the server is broken, and it
+            // would retry the same bad call instead of correcting it.
+            case 'bpp.task_property_key_unknown':
+                return new GatewayHttpError(400, { error: 'unknown_property_key' }, 'bad-request');
+            case 'bpp.task_property_value_too_long':
+                return new GatewayHttpError(400, { error: 'property_value_too_long' }, 'bad-request');
+            // A distinct body, not the bare `not_found` the other routes use: the CLI
+            // reads that one on a current-task request as "the thread's task could not
+            // be resolved" and tells the agent to pass --task-id, which is the wrong
+            // correction for a key that simply was not set.
+            case 'bpp.task_property_not_found':
+                return new GatewayHttpError(404, { error: 'property_not_found' }, 'not-found');
             default:
                 return new GatewayHttpError(502, { error: 'upstream_error' }, fallbackReason);
         }

package/dist/local-config.js

@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { parseDocument, stringify } from 'yaml';
-import { assertProviderCompatibility, assertProviderCommandCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
+import { assertProviderCompatibility, assertProviderCommandCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, parseProviderIdleShutdownMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
 import { resolveLocalConfigAgentStateRoot } from './state-paths.js';
 const SUPPORTED_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
 export const DEFAULT_LOCAL_HOST_CONFIG_FILENAME = 'agents-host.yaml';
@@ -124,6 +124,9 @@ function parseProviderCommandOverrides(value, sourceLabel) {
     if (value.copilotSessionTtlMinutes !== undefined && value.copilotSessionTtlMinutes !== null) {
         overrides.copilotSessionTtlMinutes = parseCopilotSessionTtlMinutesValue(value.copilotSessionTtlMinutes, sourceLabel);
     }
+    if (value.providerIdleShutdownMinutes !== undefined && value.providerIdleShutdownMinutes !== null) {
+        overrides.providerIdleShutdownMinutes = parseProviderIdleShutdownMinutesValue(value.providerIdleShutdownMinutes, sourceLabel);
+    }
     return overrides;
 }
 function toAgentsDir(hostConfigPath, rawAgentsDir) {
@@ -593,6 +596,9 @@ function renderAgentConfigYaml(agent) {
     if (agent.copilotSessionTtlMinutes !== undefined) {
         config.copilotSessionTtlMinutes = agent.copilotSessionTtlMinutes;
     }
+    if (agent.providerIdleShutdownMinutes !== undefined) {
+        config.providerIdleShutdownMinutes = agent.providerIdleShutdownMinutes;
+    }
     return stringify(config);
 }
 function buildManagedAgentSnapshot(host, stateRootBaseDir, sourcePath, agent) {
@@ -629,6 +635,9 @@ function resolveAgentProviderCommandConfig(hostDefaults, agent) {
         ...(agent.copilotSessionTtlMinutes !== undefined
             ? { copilotSessionTtlMinutes: agent.copilotSessionTtlMinutes }
             : {}),
+        ...(agent.providerIdleShutdownMinutes !== undefined
+            ? { providerIdleShutdownMinutes: agent.providerIdleShutdownMinutes }
+            : {}),
     });
 }
 export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {