@borgee/agents-host 0.2.74 → 0.2.94

package/README.md

@@ -101,7 +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
+- `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=provider-idle-shutdown` keeps every provider runtime process resident again; `PROVIDER_IDLE_SHUTDOWN_MINUTES=0` does the same without touching gates
 
 Or with the CLI:
 
@@ -239,11 +239,11 @@ Notes:
 | `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. |
 | `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_COMMAND` / `COPILOT_ARGS` | `--copilot-command` / `--copilot-args` | no       | `copilot` / parsed but ignored                 | Local Copilot CLI command. The host resolves it to an executable and starts the SDK headless JSON-RPC runtime; legacy `COPILOT_ARGS` remain ignored. |
+| `COPILOT_SESSION_TTL_MINUTES`      | `--copilot-session-ttl-minutes`        | no       | `2880`                                        | Idle TTL for per-channel Copilot SDK sessions                                                    |
+| `PROVIDER_IDLE_SHUTDOWN_MINUTES`   | `--provider-idle-shutdown-minutes`     | no       | `10`                                          | Idle window before the agent's shared provider runtime **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.
+`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 SDK *session* inside a running runtime process. The second shuts the shared provider *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
 
@@ -479,14 +479,14 @@ successfully applied snapshot running.
 Each Borgee channel is mapped 1:1 to a provider-native session while it stays
 active:
 
-- **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. The real ACP session cwd now comes from the resolved channel workspace `~/.borgee/channels/<encoded-channel-id>/workspace`. Task threads only switch execution onto an explicit existing `execution.local_directory`; otherwise they stay discussion-only on `~/.borgee/channels/<encoded-thread-id>/scratch/workspace`, and ACP permission requests are denied so filesystem and shell tools stay unavailable. 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`.
+- **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. The real ACP session cwd now comes from the resolved channel working folder `~/.borgee/channels/<encoded-channel-id>/workspace`. Task threads only switch execution onto an explicit existing `execution.local_directory`; otherwise they stay discussion-only on `~/.borgee/channels/<encoded-thread-id>/scratch/workspace`, and ACP permission requests are denied so filesystem and shell tools stay unavailable. 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`. The bundled adapter advertises a versioned targeted task-stop extension backed by the Agent SDK's `Query.stopTask(taskId)`: accepting that request moves only the selected background run to `stopping`, while its provider lifecycle event decides the terminal state and the parent turn plus sibling workers continue unchanged. Custom ACP commands do not receive this capability and remain fail-closed.
 - **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
   same-directory `AGENTS.md` project document inside a provider-visible
   per-channel projection directory and exposes that directory to Codex through
   ACP `additionalDirectories`. The real ACP session cwd now comes from the
-  resolved channel workspace `~/.borgee/channels/<encoded-channel-id>/workspace`.
+  resolved channel working folder `~/.borgee/channels/<encoded-channel-id>/workspace`.
   Task threads only switch execution onto an explicit existing
   `execution.local_directory`; otherwise they stay discussion-only on
   `~/.borgee/channels/<encoded-thread-id>/scratch/workspace`, and ACP
@@ -494,35 +494,22 @@ active:
   unavailable. The host persists the
   channel→ACP-session map in its state root and attempts ACP `session/resume`
   first when the adapter advertises it, otherwise `session/load`.
-- **Copilot**: one persistent `copilot --acp` subprocess is shared by a single
-  `AgentsHost`, with one ACP session per Borgee channel. Same-channel turns are
-  serialized; different channels keep isolated ACP sessions. The real ACP
-  session cwd now comes from the resolved channel workspace
-  `~/.borgee/channels/<encoded-channel-id>/workspace` by default. Task threads
-  only switch execution onto an explicit existing `execution.local_directory`;
-  otherwise they stay discussion-only on
-  `~/.borgee/channels/<encoded-thread-id>/scratch/workspace`, and ACP
-  permission requests are denied so filesystem and shell tools stay
-  unavailable. The
-  host persists the channel→ACP-session map in its 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.
+- **Copilot**: one persistent SDK-managed headless Copilot subprocess is shared by a single `AgentsHost`, with one SDK session per Borgee channel. Same-channel turns are serialized; different channels keep isolated sessions. The real session cwd comes from the resolved channel working folder `~/.borgee/channels/<encoded-channel-id>/workspace` by default. Task threads only switch execution onto an explicit existing `execution.local_directory`; otherwise they stay discussion-only on `~/.borgee/channels/<encoded-thread-id>/scratch/workspace`, and SDK permission requests are denied so filesystem and shell tools stay unavailable. The host persists the channel→session map in its state root and restores same-host continuity through SDK session resume. A replacement human prompt uses the SDK's foreground-only interrupt and keeps background work alive; explicit stop interrupts the foreground, cancels background agents, and cancels active background shell tasks in that session.
 
 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.
+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 provider 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.
+Conversation memory normally survives the recycle. Before the process goes away the host closes each live provider 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 SDK session resume. 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 if the resolved channel workspace path changes, or if the injected provider-visible directory set changes, the host deliberately drops the old mapping and starts a fresh session even though the CLI could still load it.
+- **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 if the resolved channel working folder path changes, or if the injected provider-visible directory set changes, the host deliberately drops the old mapping and starts a fresh session even though the CLI could still load it.
 
 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`.
 

package/dist/agents-host.d.ts

@@ -11,6 +11,7 @@ export declare class AgentsHost {
     private readonly runtime;
     private readonly provider;
     private readonly borgee;
+    private readonly backgroundRuns;
     private readonly logger;
     private readonly contextInjectionEnabled;
     private readonly collaborationEnabled;
@@ -33,6 +34,7 @@ export declare class AgentsHost {
     private readonly compactionSnapshotWriteQueueByChannel;
     private readonly missedCollaborationDiagnosticByChannel;
     private readonly channelTurnQueues;
+    private readonly autonomousReplyKeys;
     private readonly collaborationDrafts;
     private readonly collaborationChannels;
     private readonly participantDirectoryByUserId;
@@ -54,6 +56,7 @@ export declare class AgentsHost {
     stop(): Promise<void>;
     private trackActiveTurn;
     private dispatchMessage;
+    private dispatchAutonomousReply;
     private handleLegacyMessage;
     private handleCollaborationMessage;
     private detectProtocolKickoffCandidate;
@@ -144,10 +147,9 @@ export declare class AgentsHost {
      * exists — including its ending, which a window opened before it was replaced
      * would otherwise carry out on its behalf.
      *
-     * Every turn reports, including the silent and deferred ones that deliver
-     * nothing to the channel. The rail writes nothing anywhere, and the question
-     * it answers — whether anything is happening in this channel — is worth the
-     * same answer for a turn that keeps its reply to itself.
+     * Silent internal turns do not open a reporter. Deferred turns still report
+     * because they represent user-visible work even when final delivery happens
+     * elsewhere.
      */
     private beginTurnActivity;
     private canAcceptTurnOutput;

package/dist/agents-host.js

@@ -4,6 +4,7 @@ import { dirname, join, resolve } from 'node:path';
 import { SdkChatControlPlane } from './chat/sdk-chat-control-plane.js';
 import { HostLogger, summarizeError } from './debug.js';
 import { toReportedActivity } from './progress-to-activity.js';
+import { BackgroundRunTracker } from './background-runs.js';
 import { ATTENTION_FOLLOW_SEMANTICS_COMPATIBILITY_GATE, COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE, COLLABORATION_OUTCOME_MODEL_COMPATIBILITY_GATE, COLLABORATION_SKILL_FIRST_COMPATIBILITY_GATE, CONTEXT_INJECTION_COMPATIBILITY_GATE, LOCALHOST_GATEWAY_COMPATIBILITY_GATE, POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE, resolveInternalPolicyMode, resolveInternalCompatibilityGates, SKILL_RUNTIME_COMPATIBILITY_GATE, TASK_THREAD_COLLABORATION_CONTRACT_COMPATIBILITY_GATE, TOKEN_BINDING_COMPATIBILITY_GATE, } from './compatibility-gates.js';
 import { buildNormalizedAttentionSnapshot, parsePersistedAttentionSnapshot, } from './context/attention.js';
 import { mergeCompactionSnapshot, parsePersistedCompactionSnapshot, } from './context/compaction.js';
@@ -149,15 +150,19 @@ class DefaultHostRuntime {
                 });
         this.ensureStateRoot = deps.ensureStateRoot ?? ensurePrivateStateRoot;
     }
-    async start(onMessage, onStopTurn) {
+    async start(onMessage, onStopTurn, onStopBackgroundRun, onActivityTransportReady) {
         await this.ensureStateRoot(this.config.stateRootDir);
         await this.gateway.start();
         try {
             this.controlPlane.onStopTurn?.(onStopTurn);
+            this.controlPlane.onStopBackgroundRun?.(onStopBackgroundRun);
+            this.controlPlane.onActivityTransportReady?.(onActivityTransportReady);
             await this.controlPlane.connect(onMessage);
         }
         catch (error) {
             this.controlPlane.onStopTurn?.(undefined);
+            this.controlPlane.onStopBackgroundRun?.(undefined);
+            this.controlPlane.onActivityTransportReady?.(undefined);
             await this.gateway.stop().catch(() => { });
             throw error;
         }
@@ -166,6 +171,8 @@ class DefaultHostRuntime {
         let thrown;
         try {
             this.controlPlane.onStopTurn?.(undefined);
+            this.controlPlane.onStopBackgroundRun?.(undefined);
+            this.controlPlane.onActivityTransportReady?.(undefined);
             await this.controlPlane.close();
         }
         catch (error) {
@@ -272,6 +279,7 @@ 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;
+const MAX_AUTONOMOUS_REPLY_DEDUPLICATION_KEYS = 256;
 /**
  * Minimal single-agent agents host: connects one local Claude/Copilot CLI
  * to exactly one Borgee agent over `@borgee/plugin-sdk` (BPP / `/ws/plugin`).
@@ -281,6 +289,7 @@ export class AgentsHost {
     runtime;
     provider;
     borgee;
+    backgroundRuns;
     logger;
     contextInjectionEnabled;
     collaborationEnabled;
@@ -303,6 +312,7 @@ export class AgentsHost {
     compactionSnapshotWriteQueueByChannel = new Map();
     missedCollaborationDiagnosticByChannel = new Map();
     channelTurnQueues = new Map();
+    autonomousReplyKeys = new Map();
     collaborationDrafts = new Map();
     collaborationChannels = new Map();
     participantDirectoryByUserId = new Map();
@@ -349,6 +359,16 @@ export class AgentsHost {
         });
         this.provider = this.runtime.provider;
         this.borgee = this.runtime.controlPlane;
+        const backgroundRunCapabilities = this.provider.capabilities?.backgroundRuns;
+        this.backgroundRuns = new BackgroundRunTracker((channelId, activity) => {
+            this.borgee.reportActivity?.({ channelId, activity });
+        }, {
+            lifecycleSupported: backgroundRunCapabilities?.lifecycle === 'supported',
+            targetedCancellationSupported: backgroundRunCapabilities?.targetedCancellation === 'supported',
+            cancel: this.provider.cancelBackgroundRun
+                ? (channelId, providerRunId) => (this.provider.cancelBackgroundRun(channelId, providerRunId))
+                : undefined,
+        });
     }
     async start() {
         if (this.started)
@@ -364,6 +384,7 @@ export class AgentsHost {
         const bufferedMessages = [];
         let bufferingMessages = true;
         try {
+            this.provider.onAutonomousReply?.((reply) => this.dispatchAutonomousReply(reply));
             await this.runtime.start((message) => {
                 if (!this.started) {
                     return;
@@ -373,7 +394,7 @@ export class AgentsHost {
                     return;
                 }
                 this.dispatchMessage(message);
-            }, async (channelId) => this.stopTurn(channelId));
+            }, async (channelId) => this.stopTurn(channelId), async (channelId, runId) => this.backgroundRuns.stop(channelId, runId), () => this.backgroundRuns.replay());
             const agentId = await this.ensureSelfAgentId();
             bufferingMessages = false;
             while (bufferedMessages.length > 0) {
@@ -393,6 +414,7 @@ export class AgentsHost {
             bufferedMessages.length = 0;
             this.started = false;
             this.controlPlaneClosed = true;
+            this.provider.onAutonomousReply?.(undefined);
             await this.runtime.stop().catch(() => { });
             throw error;
         }
@@ -401,6 +423,7 @@ export class AgentsHost {
         if (!this.started)
             return;
         this.started = false;
+        this.provider.onAutonomousReply?.(undefined);
         this.logger.debug('stopping host', {
             activeTurnCount: this.activeTurns.size,
             provider: this.config.agent.provider,
@@ -420,6 +443,7 @@ export class AgentsHost {
         this.activeCompactionByChannel.clear();
         this.compactionSnapshotLoadedChannels.clear();
         this.missedCollaborationDiagnosticByChannel.clear();
+        this.autonomousReplyKeys.clear();
         this.recordedAgentSessionByTask.clear();
         this.controlPlaneClosed = true;
         const pendingCompactionSnapshotWrites = [...this.compactionSnapshotWriteQueueByChannel.values()];
@@ -449,6 +473,57 @@ export class AgentsHost {
             : this.enqueueChannelTurn(message.channel_id, () => this.handleLegacyMessage(message));
         this.trackActiveTurn(task);
     }
+    dispatchAutonomousReply(reply) {
+        if (!this.started
+            || this.controlPlaneClosed
+            || !reply.channelId.trim()
+            || !reply.eventId.trim()
+            || !hasVisibleText(reply.text)) {
+            return;
+        }
+        const key = `${reply.channelId}\0${reply.eventId}`;
+        if (this.autonomousReplyKeys.has(key)) {
+            return;
+        }
+        this.autonomousReplyKeys.set(key, true);
+        while (this.autonomousReplyKeys.size > MAX_AUTONOMOUS_REPLY_DEDUPLICATION_KEYS) {
+            const oldest = this.autonomousReplyKeys.keys().next().value;
+            if (typeof oldest !== 'string') {
+                break;
+            }
+            this.autonomousReplyKeys.delete(oldest);
+        }
+        const task = this.enqueueChannelTurn(reply.channelId, async () => {
+            if (!this.started || this.controlPlaneClosed) {
+                this.autonomousReplyKeys.delete(key);
+                return;
+            }
+            try {
+                await this.borgee.postMessage({
+                    channelId: reply.channelId,
+                    body: reply.text,
+                });
+                this.logger.debug('posted provider autonomous reply', {
+                    channelId: reply.channelId,
+                    provider: this.config.agent.provider,
+                });
+            }
+            catch (error) {
+                this.autonomousReplyKeys.delete(key);
+                this.logger.debugError('failed to post provider autonomous reply', {
+                    channelId: reply.channelId,
+                    provider: this.config.agent.provider,
+                    error,
+                });
+                this.logger.error('failed to post provider autonomous reply', {
+                    channelId: reply.channelId,
+                    provider: this.config.agent.provider,
+                    error: summarizeError(error),
+                });
+            }
+        });
+        this.trackActiveTurn(task);
+    }
     async handleLegacyMessage(msg) {
         const normalized = await this.normalizeMessage(msg);
         if (!normalized) {
@@ -570,8 +645,20 @@ export class AgentsHost {
         if (this.isHumanWakeFiltered(msg, authorKind, attentionSnapshot)) {
             return;
         }
+        let foregroundTransition;
         if (authorKind !== 'agent' && channelState.activeTurn) {
             this.supersedeActiveTurn(msg.channel_id, channelState.activeTurn);
+            foregroundTransition = (async () => {
+                try {
+                    await this.provider.interruptTurn?.(msg.channel_id);
+                }
+                catch (error) {
+                    this.logger.error('failed to interrupt superseded provider turn; replacement remains queued', {
+                        channelId: msg.channel_id,
+                        error: summarizeError(error),
+                    });
+                }
+            })();
         }
         if (authorKind !== 'agent') {
             channelState.recentTurn = undefined;
@@ -585,6 +672,7 @@ export class AgentsHost {
             attentionSnapshot,
             taskThreadContext,
         });
+        await foregroundTransition;
         await this.ensureCollaborationProcessor(msg.channel_id, channelState);
     }
     detectProtocolKickoffCandidate(anchorMessageId, content, selfAgentId) {
@@ -969,6 +1057,9 @@ export class AgentsHost {
     async ensureCollaborationProcessor(channelId, channelState) {
         if (channelState.processor) {
             await channelState.processor;
+            if (channelState.queue.length > 0 && !channelState.processor) {
+                await this.ensureCollaborationProcessor(channelId, channelState);
+            }
             return;
         }
         const processor = this.processCollaborationQueue(channelId, channelState).finally(() => {
@@ -2230,7 +2321,10 @@ export class AgentsHost {
             this.collaborationEnabled &&
             turnExecutionId != null &&
             activeTurn?.protocol === undefined;
-        const observeProviderProgress = publishesCollaborationDraft || this.config.agent.provider === 'claude';
+        const supportsProviderProgress = this.provider.capabilities?.progressUpdates?.support === 'supported';
+        const supportsBackgroundRunLifecycle = this.provider.capabilities?.backgroundRuns?.lifecycle === 'supported';
+        const reportsProviderActivity = !silentTurn && supportsProviderProgress;
+        const observeProviderProgress = supportsProviderProgress || supportsBackgroundRunLifecycle;
         const turnContext = {
             eventType: msg.type,
             channelId,
@@ -2257,7 +2351,9 @@ export class AgentsHost {
                 text: String(msg.content ?? msg.body ?? content),
                 attachments: msg.attachments,
             });
-        const activityReporter = this.beginTurnActivity(channelId, activeTurn?.generation);
+        const activityReporter = silentTurn
+            ? undefined
+            : this.beginTurnActivity(channelId, activeTurn?.generation);
         await this.ensureCompactionSnapshotLoaded(channelId);
         const compactionSnapshot = this.compactionSnapshotByChannel.get(channelId);
         try {
@@ -2304,20 +2400,32 @@ export class AgentsHost {
             }, observeProviderProgress
                 ? {
                     onProgress: (update) => {
+                        if (supportsBackgroundRunLifecycle) {
+                            this.backgroundRuns.observe(channelId, update);
+                            if (update.type === 'activity' && update.activity.background === true) {
+                                this.borgee.reportActivity?.({
+                                    channelId,
+                                    activity: { shape: 'activity', ...update.activity },
+                                });
+                                return;
+                            }
+                        }
                         if (!this.canAcceptTurnOutput(channelId, activeTurn?.generation)) {
                             return;
                         }
-                        if (update.type === 'compaction') {
+                        if (supportsProviderProgress && update.type === 'compaction') {
                             this.noteCompactionProgress(channelId, update.compaction, {
                                 turnExecutionId: activeTurn?.turnExecutionId ?? undefined,
                             });
                             return;
                         }
                         const reportedActivity = toReportedActivity(update);
-                        if (reportedActivity) {
-                            activityReporter.progress(reportedActivity);
+                        if (reportsProviderActivity && reportedActivity) {
+                            activityReporter?.progress(reportedActivity);
                         }
-                        if (update.type !== 'text' || update.stream !== 'answer') {
+                        if (!supportsProviderProgress
+                            || update.type !== 'text'
+                            || update.stream !== 'answer') {
                             return;
                         }
                         if (!publishesCollaborationDraft) {
@@ -2527,7 +2635,7 @@ export class AgentsHost {
         }
         finally {
             stopTyping();
-            activityReporter.end();
+            activityReporter?.end();
         }
     }
     /**
@@ -2539,10 +2647,9 @@ export class AgentsHost {
      * exists — including its ending, which a window opened before it was replaced
      * would otherwise carry out on its behalf.
      *
-     * Every turn reports, including the silent and deferred ones that deliver
-     * nothing to the channel. The rail writes nothing anywhere, and the question
-     * it answers — whether anything is happening in this channel — is worth the
-     * same answer for a turn that keeps its reply to itself.
+     * Silent internal turns do not open a reporter. Deferred turns still report
+     * because they represent user-visible work even when final delivery happens
+     * elsewhere.
      */
     beginTurnActivity(channelId, generation) {
         const reporter = this.borgee.reportTurnActivity({
@@ -2710,8 +2817,11 @@ export class AgentsHost {
                 turnExecutionId: activeTurn.turnExecutionId,
             });
         }
+        // Output acceptance checks `superseded`, so a stale foreground turn still
+        // cannot stream, draft, or post a visible reply after the interrupt. The
+        // id stays on the running turn until it unwinds so background children that
+        // inherited it can finish their own gateway work cleanly.
         activeTurn.superseded = true;
-        activeTurn.turnExecutionId = null;
     }
     invalidateChannelTurn(channelId) {
         const activeTurn = this.collaborationChannels.get(channelId)?.activeTurn;
@@ -2721,7 +2831,9 @@ export class AgentsHost {
     }
     async stopTurn(channelId) {
         const activeTurn = this.collaborationChannels.get(channelId)?.activeTurn;
-        const aborted = await this.provider.cancelTurn?.(channelId) ?? false;
+        const aborted = await (this.provider.cancelSession?.(channelId)
+            ?? this.provider.cancelTurn?.(channelId)
+            ?? false);
         if (!aborted) {
             return { aborted: false };
         }
@@ -2759,7 +2871,6 @@ export class AgentsHost {
     resolveAuthorizedCollaborationTurn(channelState, turnExecutionId) {
         const activeTurn = channelState?.activeTurn;
         if (activeTurn &&
-            !activeTurn.superseded &&
             activeTurn.turnExecutionId != null &&
             activeTurn.turnExecutionId === turnExecutionId) {
             return activeTurn;

package/dist/background-runs.d.ts

@@ -0,0 +1,24 @@
+import type { AgentActivity } from './plugin-sdk.js';
+import type { ProviderProgressUpdate } from './types.js';
+interface BackgroundRunTrackerOptions {
+    lifecycleSupported: boolean;
+    targetedCancellationSupported: boolean;
+    cancel?: (channelId: string, providerRunId: string) => Promise<boolean>;
+}
+export declare class BackgroundRunTracker {
+    private readonly report;
+    private readonly options;
+    private readonly now;
+    private readonly mintRunId;
+    private readonly runs;
+    private readonly runsById;
+    constructor(report: (channelId: string, activity: AgentActivity) => void, options: BackgroundRunTrackerOptions, now?: () => number, mintRunId?: (channelId: string, providerRunId: string, startedAt: number, executionId?: string) => string);
+    observe(channelId: string, update: ProviderProgressUpdate): void;
+    replay(): void;
+    stop(channelId: string, runId: string): Promise<{
+        outcome: 'stopped' | 'not_found' | 'unsupported';
+        reason?: string;
+    }>;
+    private publish;
+}
+export {};