@borgee/agents-host 0.2.33 → 0.2.44

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;
@@ -88,11 +93,25 @@ export declare class AgentsHost {
     private armProtocolFallback;
     private runProtocolFallback;
     private handleProtocolFallbackFailure;
+    private ensureProtocolAnchorIncomingParts;
     private finishProtocolState;
     private cancelProtocolState;
     private confirmProtocolMessage;
+    private findChannelHistoryMessageById;
     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

@@ -14,6 +14,7 @@ import { createProvider } from './providers/create-provider.js';
 import { resolveAttentionStatePath, resolveSharedProtocolKickoffDecisionPath, resolveSharedProtocolStatusPath, } from './state-paths.js';
 import { appendVisibleMention as appendVisibleBodyMention, extractVisibleMentionIds as extractCanonicalMentionIds, } from './visible-mentions.js';
 import { waitForTaskForThread } from './task-thread-resolution.js';
+import { buildHostedIncomingContentText, buildHostedTurnContentParts, extractHostedMessageAttachments, normalizeHostedMessageAttachment, } from './hosted-turn-content.js';
 const PRIVATE_STATE_ROOT_MODE = 0o700;
 const STREAM_PROGRESS_EDIT_THROTTLE_MS = 150;
 const PROTOCOL_STATE_DIRNAME = 'protocol-state';
@@ -126,7 +127,9 @@ class DefaultHostRuntime {
             deps.provider ??
                 createProvider({
                     provider: config.agent.provider,
+                    borgeeBaseUrl: config.borgeeBaseUrl,
                     stateRootDir: config.stateRootDir,
+                    agentApiKey: config.agent.agentApiKey,
                     resolveStableAgentId: deps.resolveStableAgentId,
                     claudeCommand: config.claudeCommand,
                     claudeArgs: config.claudeArgs,
@@ -135,6 +138,7 @@ class DefaultHostRuntime {
                     copilotCommand: config.copilotCommand,
                     copilotArgs: config.copilotArgs,
                     copilotSessionTtlMinutes: config.copilotSessionTtlMinutes,
+                    providerIdleShutdownMinutes: config.providerIdleShutdownMinutes,
                 }, deps.logger, {
                     compatibilityGates,
                     authorizationAuditSink: this.authorizationAuditSink,
@@ -361,6 +365,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 +392,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 +518,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]);
@@ -547,7 +562,7 @@ export class AgentsHost {
                 }
             }
         }
-        await this.runUngatedTurn(msg, normalized.authorId, normalized.content, taskThreadContext, attentionSnapshot);
+        await this.runUngatedTurn(msg, normalized.authorId, normalized.content, taskThreadContext, attentionSnapshot, normalized.incomingParts);
     }
     async handleCollaborationMessage(msg) {
         const normalized = await this.normalizeMessage(msg);
@@ -596,6 +611,7 @@ export class AgentsHost {
                     authorId: normalized.authorId,
                     authorKind: 'unknown',
                     content: normalized.content,
+                    incomingParts: normalized.incomingParts,
                     attentionSnapshot,
                     taskThreadContext,
                 });
@@ -614,6 +630,7 @@ export class AgentsHost {
                     authorId: normalized.authorId,
                     authorKind: 'human',
                     content: normalized.content,
+                    incomingParts: normalized.incomingParts,
                     attentionSnapshot,
                     taskThreadContext,
                     wakeBlockedState,
@@ -646,6 +663,7 @@ export class AgentsHost {
             authorId: normalized.authorId,
             authorKind,
             content: normalized.content,
+            incomingParts: normalized.incomingParts,
             attentionSnapshot,
             taskThreadContext,
         });
@@ -740,6 +758,7 @@ export class AgentsHost {
         const executed = await this.executeTurn(msg, normalized.authorId, normalized.content, {
             kickoff: protocolCandidate,
             silent: true,
+            incomingParts: normalized.incomingParts,
         });
         if (executed.stale) {
             return null;
@@ -900,6 +919,7 @@ export class AgentsHost {
                 authorId: normalized.authorId,
                 authorKind: 'human',
                 content: normalized.content,
+                incomingParts: normalized.incomingParts,
             });
             await this.ensureCollaborationProcessor(msg.channel_id, channelState);
             return;
@@ -912,6 +932,7 @@ export class AgentsHost {
             ownerAgentId: selfAgentId,
             anchorAuthorId: normalized.authorId,
             anchorContent: normalized.content,
+            anchorIncomingParts: normalized.incomingParts,
             anchorMessageId: msg.message_id ?? randomUUID(),
             participantIds: protocolRequest.participantIds,
             issuerId: protocolRequest.issuerId,
@@ -934,6 +955,7 @@ export class AgentsHost {
                 authorId: normalized.authorId,
                 authorKind: 'human',
                 content: normalized.content,
+                incomingParts: normalized.incomingParts,
             });
             await this.ensureCollaborationProcessor(msg.channel_id, channelState);
             return;
@@ -1002,6 +1024,7 @@ export class AgentsHost {
             authorId: normalized.authorId,
             authorKind: 'agent',
             content: normalized.content,
+            incomingParts: normalized.incomingParts,
         });
         await this.ensureCollaborationProcessor(msg.channel_id, channelState);
     }
@@ -1119,6 +1142,7 @@ export class AgentsHost {
         channelState.activeTurn = activeTurn;
         const executed = await this.executeTurn(message.raw, message.authorId, this.buildIncomingContent(message), {
             activeTurn,
+            incomingParts: message.incomingParts,
             incomingAuthorKind: message.authorKind,
             attentionSnapshot,
             taskThreadContext,
@@ -1222,6 +1246,7 @@ export class AgentsHost {
         channelState.activeTurn = activeTurn;
         const executed = await this.executeTurn(message.raw, message.authorId, this.buildIncomingContent(message), {
             activeTurn,
+            incomingParts: message.incomingParts,
             incomingAuthorKind: message.authorKind,
             attentionSnapshot,
             taskThreadContext,
@@ -1529,59 +1554,52 @@ export class AgentsHost {
     }
     async buildResumedProtocolMessage(channelId, protocolState) {
         if (protocolState.currentTurnIndex === 0) {
+            const anchorIncomingParts = await this.ensureProtocolAnchorIncomingParts(channelId, protocolState);
+            const anchorIncomingContent = buildHostedIncomingContentText(anchorIncomingParts);
             return {
                 kind: 'protocol-turn',
                 raw: {
                     channel_id: channelId,
                     message_id: protocolState.anchorMessageId,
                     user_id: protocolState.anchorAuthorId,
-                    content: protocolState.anchorContent,
-                    body: protocolState.anchorContent,
+                    content: anchorIncomingContent,
+                    body: anchorIncomingContent,
+                    attachments: extractHostedMessageAttachments(anchorIncomingParts),
                     type: 'message',
                 },
                 authorId: protocolState.anchorAuthorId,
                 authorKind: 'human',
-                content: protocolState.anchorContent,
+                content: anchorIncomingContent,
+                incomingParts: anchorIncomingParts,
             };
         }
         if (!protocolState.lastProtocolMessageId) {
             return null;
         }
-        let before;
-        for (;;) {
-            const history = await this.borgee.readChannelHistory({
-                channelId,
-                before,
-                limit: 200,
+        const priorMessage = await this.findChannelHistoryMessageById(channelId, protocolState.lastProtocolMessageId);
+        if (priorMessage) {
+            const incomingParts = buildHostedTurnContentParts({
+                text: priorMessage.body,
+                attachments: priorMessage.attachments,
             });
-            const priorMessage = history.find((entry) => entry.id === protocolState.lastProtocolMessageId);
-            if (priorMessage) {
-                return {
-                    kind: 'protocol-turn',
-                    raw: {
-                        channel_id: channelId,
-                        message_id: priorMessage.id,
-                        user_id: priorMessage.authorId,
-                        content: priorMessage.body,
-                        body: priorMessage.body,
-                        type: 'message',
-                        created_at: priorMessage.createdAt,
-                    },
-                    authorId: priorMessage.authorId,
-                    authorKind: 'agent',
-                    content: priorMessage.body,
-                };
-            }
-            if (history.length < 200) {
-                break;
-            }
-            const oldestCreatedAt = history.reduce((oldest, entry) => {
-                return oldest == null || entry.createdAt < oldest ? entry.createdAt : oldest;
-            }, null);
-            if (oldestCreatedAt == null || (before != null && oldestCreatedAt >= before)) {
-                break;
-            }
-            before = oldestCreatedAt;
+            const incomingContent = buildHostedIncomingContentText(incomingParts);
+            return {
+                kind: 'protocol-turn',
+                raw: {
+                    channel_id: channelId,
+                    message_id: priorMessage.id,
+                    user_id: priorMessage.authorId,
+                    content: incomingContent,
+                    body: incomingContent,
+                    attachments: priorMessage.attachments,
+                    type: 'message',
+                    created_at: priorMessage.createdAt,
+                },
+                authorId: priorMessage.authorId,
+                authorKind: 'agent',
+                content: incomingContent,
+                incomingParts,
+            };
         }
         return null;
     }
@@ -1592,6 +1610,7 @@ export class AgentsHost {
             ownerAgentId,
             anchorAuthorId: protocolState.anchorAuthorId,
             anchorContent: protocolState.anchorContent,
+            anchorIncomingParts: protocolState.anchorIncomingParts,
             anchorMessageId: protocolState.anchorMessageId,
             participantIds: protocolState.participantIds,
             issuerId: protocolState.issuerId,
@@ -1670,18 +1689,36 @@ export class AgentsHost {
             await this.persistProtocolState(channelId, protocolState);
             return;
         }
+        const anchorIncomingParts = await this.ensureProtocolAnchorIncomingParts(channelId, protocolState);
+        const anchorIncomingContent = buildHostedIncomingContentText(anchorIncomingParts);
         const fallbackMessage = {
             channel_id: channelId,
             message_id: protocolState.anchorMessageId,
             user_id: protocolState.anchorAuthorId,
-            content: protocolState.anchorContent,
-            body: protocolState.anchorContent,
+            content: anchorIncomingContent,
+            body: anchorIncomingContent,
+            attachments: extractHostedMessageAttachments(anchorIncomingParts),
             type: 'message',
         };
         this.cancelProtocolState(channelId, channelState);
         const taskThreadContext = await this.buildTurnTaskThreadContext(fallbackMessage, channelId);
         const attentionSnapshot = this.getAttentionSnapshotForTurn(channelId, taskThreadContext);
-        await this.runUngatedTurn(fallbackMessage, protocolState.anchorAuthorId, protocolState.anchorContent, taskThreadContext, attentionSnapshot);
+        await this.runUngatedTurn(fallbackMessage, protocolState.anchorAuthorId, anchorIncomingContent, taskThreadContext, attentionSnapshot, anchorIncomingParts);
+    }
+    async ensureProtocolAnchorIncomingParts(channelId, protocolState) {
+        if (protocolState.anchorIncomingParts) {
+            return protocolState.anchorIncomingParts;
+        }
+        const anchorMessage = await this.findChannelHistoryMessageById(channelId, protocolState.anchorMessageId);
+        if (!anchorMessage) {
+            return buildHostedTurnContentParts({ text: protocolState.anchorContent });
+        }
+        const anchorIncomingParts = buildHostedTurnContentParts({
+            text: protocolState.anchorContent,
+            attachments: anchorMessage.attachments,
+        });
+        protocolState.anchorIncomingParts = anchorIncomingParts;
+        return anchorIncomingParts;
     }
     finishProtocolState(channelId, channelState, protocolState, lastMessageId) {
         protocolState.active = false;
@@ -1721,6 +1758,36 @@ export class AgentsHost {
         }
         return matched;
     }
+    async findChannelHistoryMessageById(channelId, messageId) {
+        let before;
+        for (;;) {
+            const history = await this.borgee.readChannelHistory({
+                channelId,
+                before,
+                limit: 200,
+            });
+            const matched = history.find((entry) => entry.id === messageId);
+            if (matched) {
+                return {
+                    ...matched,
+                    ...(matched.attachments
+                        ? { attachments: matched.attachments.map(normalizeHostedMessageAttachment) }
+                        : {}),
+                };
+            }
+            if (history.length < 200) {
+                break;
+            }
+            const oldestCreatedAt = history.reduce((oldest, entry) => {
+                return oldest == null || entry.createdAt < oldest ? entry.createdAt : oldest;
+            }, null);
+            if (oldestCreatedAt == null || (before != null && oldestCreatedAt >= before)) {
+                break;
+            }
+            before = oldestCreatedAt;
+        }
+        return null;
+    }
     resolveAttentionStatePath(channelId) {
         return resolveAttentionStatePath(this.config.stateRootDir, channelId);
     }
@@ -1730,6 +1797,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 ?? ''));
@@ -1990,10 +2092,11 @@ export class AgentsHost {
             reason: 'wake-suppressed-attention-policy',
         });
     }
-    async runUngatedTurn(msg, authorId, content, taskThreadContext, attentionSnapshot) {
+    async runUngatedTurn(msg, authorId, content, taskThreadContext, attentionSnapshot, incomingParts) {
         const executed = await this.executeTurn(msg, authorId, content, {
             attentionSnapshot,
             taskThreadContext,
+            incomingParts,
         });
         if (executed.completed && executed.reply) {
             this.updateAwaitingUserState(msg.channel_id, executed.reply.awaitingUser);
@@ -2086,6 +2189,11 @@ export class AgentsHost {
             : undefined;
         const missedCollaborationDiagnostic = this.resolveMissedCollaborationDiagnosticForTurn(channelId);
         const collaborationCapabilities = this.resolveCollaborationCapabilityDeclarationForTurn();
+        const incomingParts = options?.incomingParts
+            ?? buildHostedTurnContentParts({
+                text: String(msg.content ?? msg.body ?? content),
+                attachments: msg.attachments,
+            });
         try {
             reply = await this.provider.generateReply({
                 agentName: this.config.agent.agentName,
@@ -2093,6 +2201,7 @@ export class AgentsHost {
                 channelId,
                 incomingAuthorId: authorId,
                 incomingContent: content,
+                incomingParts,
                 incomingEventKind: msg.type,
                 incomingMessageType: msg.message_type,
                 collaboration: turnExecutionId || options?.kickoff
@@ -2126,6 +2235,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
@@ -2631,17 +2745,22 @@ export class AgentsHost {
             });
             return null;
         }
-        const content = String(msg.content ?? msg.body ?? '').trim();
-        if (!content) {
+        const incomingParts = buildHostedTurnContentParts({
+            text: String(msg.content ?? msg.body ?? ''),
+            attachments: msg.attachments,
+        });
+        if (incomingParts.length === 0) {
             this.logger.debug('ignored empty message', {
                 channelId: msg.channel_id,
                 messageId: msg.message_id,
             });
             return null;
         }
+        const content = buildHostedIncomingContentText(incomingParts);
         return {
             authorId,
             content,
+            incomingParts,
         };
     }
     // Only a task assigned to this agent drives a task-assignment turn: it keeps the message a

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

@@ -1,4 +1,5 @@
 import { createBorgeePlugin, } from '../plugin-sdk.js';
+import { normalizeHostedMessageAttachment } from '../hosted-turn-content.js';
 /**
  * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
  * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface
@@ -97,6 +98,7 @@ export class SdkChatControlPlane {
             authorId: message.authorId,
             body: message.body,
             contentType: message.contentType,
+            attachments: message.attachments?.map(normalizeHostedMessageAttachment),
             type: message.type,
             replyToId: message.replyToId,
             createdAt: message.createdAt,
@@ -123,6 +125,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 {
@@ -136,6 +144,7 @@ export function mapInboundToChannelMessage(event) {
         content: event.message?.body,
         body: event.message?.body,
         content_type: event.message?.contentType,
+        attachments: event.message?.attachments?.map(normalizeHostedMessageAttachment),
         created_at: event.createdAt,
     };
 }