@borgee/agents-host 0.2.26 → 0.2.29

package/dist/agents-host.js

@@ -4,12 +4,14 @@ import { dirname, join, resolve } from 'node:path';
 import { SdkChatControlPlane } from './chat/sdk-chat-control-plane.js';
 import { HostLogger, summarizeError } from './debug.js';
 import { createDurableCursorStore } from './durable-cursor-store.js';
-import { COLLABORATION_SKILL_FIRST_COMPATIBILITY_GATE, CONTEXT_INJECTION_COMPATIBILITY_GATE, LOCALHOST_GATEWAY_COMPATIBILITY_GATE, POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE, resolveInternalPolicyMode, resolveInternalCompatibilityGates, SKILL_RUNTIME_COMPATIBILITY_GATE, TOKEN_BINDING_COMPATIBILITY_GATE, } from './compatibility-gates.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 { projectTaskThreadCollaborationContract } from './context/task-thread-collaboration.js';
 import { createLocalhostGatewayController, LOCALHOST_GATEWAY_COLLABORATION_TARGET_COOLDOWN_MS, } from './gateway/localhost-gateway.js';
-import { extractTaskIdFromTaskAssignmentContent } from './context/injection.js';
+import { extractTaskIdFromTaskAssignmentContent, resolveChannelContextPayloadPath, } from './context/injection.js';
 import { AuthorizationAuditSink, } from './policy/authorization-audit.js';
 import { createProvider } from './providers/create-provider.js';
-import { resolveSharedProtocolKickoffDecisionPath, resolveSharedProtocolStatusPath, } from './state-paths.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';
 const PRIVATE_STATE_ROOT_MODE = 0o700;
@@ -20,6 +22,7 @@ const PROTOCOL_KICKOFF_DECISION_TIMEOUT_MS = PROTOCOL_PROVIDER_TURN_TIMEOUT_MS;
 const PROTOCOL_KICKOFF_DECISION_POLL_INTERVAL_MS = 50;
 const PROTOCOL_KICKOFF_ROUND_LIMIT = 20;
 const COLLABORATION_LATE_SEND_GRACE_MS = 5_000;
+const ORDINARY_HUMAN_EVENT_KINDS = new Set(['', 'message']);
 async function ensurePrivateStateRoot(path) {
     await mkdir(path, { recursive: true, mode: PRIVATE_STATE_ROOT_MODE });
     await chmod(path, PRIVATE_STATE_ROOT_MODE);
@@ -371,9 +374,17 @@ export class AgentsHost {
     provider;
     borgee;
     logger;
+    contextInjectionEnabled;
     collaborationEnabled;
+    collaborationOutcomeModelEnabled;
+    attentionFollowSemanticsEnabled;
+    taskThreadCollaborationContractEnabled;
+    collaborationCapabilitiesDiagnosticsEnabled;
     activeTurns = new Set();
     awaitingUserByChannel = new Map();
+    collaborationOutcomeByChannel = new Map();
+    attentionSnapshotByChannel = new Map();
+    missedCollaborationDiagnosticByChannel = new Map();
     progressChannelQueues = new Map();
     progressDrafts = new Map();
     collaborationDrafts = new Map();
@@ -393,6 +404,7 @@ export class AgentsHost {
         this.logger = new HostLogger(deps?.runtimeOptions);
         const compatibilityGates = resolveInternalCompatibilityGates();
         const contextInjectionGateEnabled = compatibilityGates.has(CONTEXT_INJECTION_COMPATIBILITY_GATE);
+        this.contextInjectionEnabled = contextInjectionGateEnabled;
         const skillRuntimeGateEnabled = compatibilityGates.has(SKILL_RUNTIME_COMPATIBILITY_GATE);
         const localhostGatewayGateEnabled = contextInjectionGateEnabled &&
             skillRuntimeGateEnabled &&
@@ -403,6 +415,14 @@ export class AgentsHost {
                 compatibilityGates.has(COLLABORATION_SKILL_FIRST_COMPATIBILITY_GATE) &&
                 policyAuditGateEnabled &&
                 resolveInternalPolicyMode(policyAuditGateEnabled) === 'enforce';
+        this.collaborationOutcomeModelEnabled = compatibilityGates.has(COLLABORATION_OUTCOME_MODEL_COMPATIBILITY_GATE);
+        this.attentionFollowSemanticsEnabled = compatibilityGates.has(ATTENTION_FOLLOW_SEMANTICS_COMPATIBILITY_GATE);
+        this.taskThreadCollaborationContractEnabled =
+            contextInjectionGateEnabled
+                && compatibilityGates.has(TASK_THREAD_COLLABORATION_CONTRACT_COMPATIBILITY_GATE);
+        this.collaborationCapabilitiesDiagnosticsEnabled =
+            contextInjectionGateEnabled
+                && compatibilityGates.has(COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE);
         this.runtime = createDefaultHostRuntime(config, {
             logger: this.logger,
             provider: deps?.provider,
@@ -481,6 +501,9 @@ export class AgentsHost {
             this.clearCollaborationDraft(channelId);
         }
         this.awaitingUserByChannel.clear();
+        this.collaborationOutcomeByChannel.clear();
+        this.attentionSnapshotByChannel.clear();
+        this.missedCollaborationDiagnosticByChannel.clear();
         this.controlPlaneClosed = true;
         await this.runtime.stop();
         await Promise.allSettled([...this.activeTurns]);
@@ -504,10 +527,25 @@ export class AgentsHost {
         if (!normalized) {
             return;
         }
+        let taskThreadContext = { state: 'inactive' };
+        let attentionSnapshot;
+        if (this.attentionFollowSemanticsEnabled
+            || this.taskThreadCollaborationContractEnabled) {
+            taskThreadContext = await this.buildTurnTaskThreadContext(msg, msg.channel_id);
+            if (this.attentionFollowSemanticsEnabled) {
+                const channelState = this.ensureCollaborationChannelState(msg.channel_id);
+                const authorKind = await this.classifyAuthor(normalized.authorId, false);
+                await this.ensureAttentionSnapshotLoaded(msg.channel_id, channelState);
+                attentionSnapshot = this.getAttentionSnapshotForTurn(msg.channel_id, taskThreadContext);
+                if (this.isHumanWakeFiltered(msg, authorKind, attentionSnapshot)) {
+                    return;
+                }
+            }
+        }
         if (msg.message_type === 'task_assignment') {
             await this.markAssignedTaskInProgress(msg.channel_id, normalized.content);
         }
-        await this.runUngatedTurn(msg, normalized.authorId, normalized.content);
+        await this.runUngatedTurn(msg, normalized.authorId, normalized.content, taskThreadContext, attentionSnapshot);
     }
     async handleCollaborationMessage(msg) {
         const normalized = await this.normalizeMessage(msg);
@@ -519,8 +557,11 @@ export class AgentsHost {
         }
         const channelState = this.ensureCollaborationChannelState(msg.channel_id);
         await this.ensureProtocolStateLoaded(msg.channel_id, channelState);
+        await this.ensureAttentionSnapshotLoaded(msg.channel_id, channelState);
         const selfAgentId = await this.ensureSelfAgentId();
         const authorKind = await this.classifyAuthor(normalized.authorId, false);
+        const taskThreadContext = await this.buildTurnTaskThreadContext(msg, msg.channel_id);
+        const attentionSnapshot = this.getAttentionSnapshotForTurn(msg.channel_id, taskThreadContext);
         if (channelState.protocol?.active) {
             if (msg.message_id && authorKind === 'agent') {
                 await this.handleActiveProtocolParticipantMessage(msg, normalized, channelState, channelState.protocol, selfAgentId);
@@ -542,6 +583,7 @@ export class AgentsHost {
             const blockedAuthorKind = await this.classifyBlockedWakeAuthor(normalized.authorId, channelState.blocked);
             if (blockedAuthorKind === 'agent') {
                 channelState.blocked.suppressedAgentMessages += 1;
+                this.recordBlockedSuppressionOutcome(msg.channel_id, channelState);
                 return;
             }
             if (blockedAuthorKind === 'unknown') {
@@ -550,6 +592,8 @@ export class AgentsHost {
                     authorId: normalized.authorId,
                     authorKind: 'unknown',
                     content: normalized.content,
+                    attentionSnapshot,
+                    taskThreadContext,
                 });
                 const resumed = await this.tryResumeBlockedFromQueue(msg.channel_id, channelState);
                 if (resumed) {
@@ -566,6 +610,8 @@ export class AgentsHost {
                     authorId: normalized.authorId,
                     authorKind: 'human',
                     content: normalized.content,
+                    attentionSnapshot,
+                    taskThreadContext,
                     wakeBlockedState,
                 },
             ];
@@ -582,6 +628,9 @@ export class AgentsHost {
                 }
             }
         }
+        if (this.isHumanWakeFiltered(msg, authorKind, attentionSnapshot)) {
+            return;
+        }
         if (authorKind !== 'agent' && channelState.activeTurn) {
             this.supersedeActiveTurn(msg.channel_id, channelState.activeTurn);
         }
@@ -593,6 +642,8 @@ export class AgentsHost {
             authorId: normalized.authorId,
             authorKind,
             content: normalized.content,
+            attentionSnapshot,
+            taskThreadContext,
         });
         await this.ensureCollaborationProcessor(msg.channel_id, channelState);
     }
@@ -681,6 +732,7 @@ export class AgentsHost {
         };
     }
     async evaluateIssuerProtocolKickoff(msg, normalized, protocolCandidate, pendingDecision) {
+        const priorMissedCollaborationDiagnostic = this.resolveMissedCollaborationDiagnosticForTurn(msg.channel_id);
         const executed = await this.executeTurn(msg, normalized.authorId, normalized.content, {
             kickoff: protocolCandidate,
             silent: true,
@@ -688,6 +740,11 @@ export class AgentsHost {
         if (executed.stale) {
             return null;
         }
+        this.recordCollaborationOutcome(msg.channel_id, {
+            responseState: executed.completed ? 'responded' : 'failed',
+            deliveryState: executed.deliveryState ?? 'not-delivered',
+        });
+        this.updateMissedCollaborationDiagnostic(msg.channel_id, priorMissedCollaborationDiagnostic);
         const reply = executed.reply;
         const rounds = reply?.control?.kind === 'start-protocol'
             ? this.validateProtocolKickoffRounds(reply.control.rounds)
@@ -958,6 +1015,7 @@ export class AgentsHost {
                 queue: [],
                 running: false,
                 protocolLoaded: false,
+                attentionLoaded: false,
             };
             this.collaborationChannels.set(channelId, state);
         }
@@ -1010,6 +1068,7 @@ export class AgentsHost {
                 : await this.classifyQueuedBlockedWakeCandidate(queued, blocked);
             if (classified === 'agent') {
                 blocked.suppressedAgentMessages += 1;
+                this.recordBlockedSuppressionOutcome(channelId, channelState);
                 continue;
             }
             if (classified === 'unknown') {
@@ -1037,6 +1096,12 @@ export class AgentsHost {
             await this.runProtocolManagedTurn(channelId, channelState, message);
             return;
         }
+        const taskThreadContext = await this.buildTurnTaskThreadContext(message.raw, channelId);
+        const attentionSnapshot = this.getAttentionSnapshotForTurn(channelId, taskThreadContext);
+        if (!message.wakeBlockedState
+            && this.isHumanWakeFiltered(message.raw, message.authorKind, attentionSnapshot)) {
+            return;
+        }
         channelState.generation += 1;
         const activeTurn = {
             generation: channelState.generation,
@@ -1051,24 +1116,66 @@ export class AgentsHost {
         const executed = await this.executeTurn(message.raw, message.authorId, this.buildIncomingContent(message), {
             activeTurn,
             incomingAuthorKind: message.authorKind,
+            attentionSnapshot,
+            taskThreadContext,
         });
         channelState.activeTurn = undefined;
         if (executed.stale) {
             return;
         }
         if (executed.completed) {
+            await this.commitAttentionSnapshot(channelId, executed.appliedAttentionSnapshot ?? attentionSnapshot);
             this.rememberRecentTurn(channelState, activeTurn);
         }
-        if (executed.reply?.awaitingUser) {
+        if (executed.completed && executed.reply?.awaitingUser) {
             channelState.blocked = {
                 awaitingUser: executed.reply.awaitingUser,
                 suppressedAgentMessages: 0,
             };
             this.awaitingUserByChannel.set(channelId, executed.reply.awaitingUser);
+            this.recordCollaborationOutcome(channelId, {
+                responseState: 'blocked',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                wakeState: 'waiting',
+                blockedDetails: {
+                    question: executed.reply.awaitingUser.question,
+                    ...(executed.reply.awaitingUser.reason
+                        ? { reason: executed.reply.awaitingUser.reason }
+                        : {}),
+                },
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
+            return;
+        }
+        if (!executed.completed && message.wakeBlockedState) {
+            const existing = this.collaborationOutcomeByChannel.get(channelId);
+            channelState.blocked = {
+                awaitingUser: message.wakeBlockedState,
+                suppressedAgentMessages: 0,
+            };
+            this.awaitingUserByChannel.set(channelId, message.wakeBlockedState);
+            this.recordCollaborationOutcome(channelId, {
+                responseState: 'blocked',
+                deliveryState: existing?.responseState === 'blocked' ? existing.deliveryState : 'not-delivered',
+                wakeState: 'waiting',
+                blockedDetails: {
+                    question: message.wakeBlockedState.question,
+                    ...(message.wakeBlockedState.reason
+                        ? { reason: message.wakeBlockedState.reason }
+                        : {}),
+                },
+                ...(existing?.turnExecutionId ? { turnExecutionId: existing.turnExecutionId } : {}),
+            });
             return;
         }
         channelState.blocked = undefined;
         this.awaitingUserByChannel.delete(channelId);
+        this.recordCollaborationOutcome(channelId, {
+            responseState: executed.completed ? 'responded' : 'failed',
+            deliveryState: executed.deliveryState ?? 'not-delivered',
+            ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+            turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+        });
     }
     async runProtocolManagedTurn(channelId, channelState, message) {
         const protocolState = channelState.protocol;
@@ -1083,6 +1190,10 @@ export class AgentsHost {
         const currentTurnIndex = protocolState.currentTurnIndex + 1;
         const peerId = this.otherProtocolParticipant(protocolState, selfAgentId);
         const isFinalTurn = currentTurnIndex >= protocolState.maxTurnCount;
+        const taskThreadContext = message.taskThreadContext
+            ?? await this.buildTurnTaskThreadContext(message.raw, channelId);
+        const attentionSnapshot = message.attentionSnapshot
+            ?? this.getAttentionSnapshotForTurn(channelId, taskThreadContext);
         const activeTurn = {
             generation: channelState.generation,
             turnExecutionId: randomUUID(),
@@ -1108,25 +1219,40 @@ export class AgentsHost {
         const executed = await this.executeTurn(message.raw, message.authorId, this.buildIncomingContent(message), {
             activeTurn,
             incomingAuthorKind: message.authorKind,
+            attentionSnapshot,
+            taskThreadContext,
         });
         channelState.activeTurn = undefined;
         if (executed.stale || !protocolState.active) {
             return;
         }
         if (executed.completed) {
+            await this.commitAttentionSnapshot(channelId, executed.appliedAttentionSnapshot ?? attentionSnapshot);
             this.rememberRecentTurn(channelState, activeTurn);
         }
         const deliveredMessageId = executed.deliveredMessageId ?? null;
         const visibleMessageId = deliveredMessageId ?? protocolState.lastProtocolMessageId;
         if (executed.reply?.controlMalformed) {
+            this.recordCollaborationOutcome(channelId, {
+                responseState: executed.completed ? 'responded' : 'failed',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
             this.finishProtocolState(channelId, channelState, protocolState, visibleMessageId);
             return;
         }
         if (!executed.reply?.control) {
+            this.recordCollaborationOutcome(channelId, {
+                responseState: executed.completed ? 'responded' : 'failed',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
             this.finishProtocolState(channelId, channelState, protocolState, visibleMessageId);
             return;
         }
-        if (executed.reply.control.kind === 'awaiting-user') {
+        if (executed.completed && executed.reply.control.kind === 'awaiting-user') {
             channelState.blocked = {
                 awaitingUser: executed.reply.awaitingUser ?? {
                     question: executed.reply.control.question,
@@ -1135,10 +1261,40 @@ export class AgentsHost {
                 suppressedAgentMessages: 0,
             };
             this.awaitingUserByChannel.set(channelId, channelState.blocked.awaitingUser);
+            this.recordCollaborationOutcome(channelId, {
+                responseState: 'blocked',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                wakeState: 'waiting',
+                blockedDetails: {
+                    question: channelState.blocked.awaitingUser.question,
+                    ...(channelState.blocked.awaitingUser.reason
+                        ? { reason: channelState.blocked.awaitingUser.reason }
+                        : {}),
+                },
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
             this.finishProtocolState(channelId, channelState, protocolState, visibleMessageId);
             return;
         }
         if (executed.reply.control.kind === 'start-protocol') {
+            this.recordCollaborationOutcome(channelId, {
+                responseState: executed.completed ? 'responded' : 'failed',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
+            this.updateMissedCollaborationDiagnostic(channelId, undefined);
+            this.finishProtocolState(channelId, channelState, protocolState, visibleMessageId);
+            return;
+        }
+        if (executed.reply.control.kind === 'attention-only') {
+            this.recordCollaborationOutcome(channelId, {
+                responseState: executed.completed ? 'responded' : 'failed',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
+            this.updateMissedCollaborationDiagnostic(channelId, undefined);
             this.finishProtocolState(channelId, channelState, protocolState, visibleMessageId);
             return;
         }
@@ -1146,6 +1302,12 @@ export class AgentsHost {
             this.finishProtocolState(channelId, channelState, protocolState);
             this.awaitingUserByChannel.delete(channelId);
             channelState.blocked = undefined;
+            this.recordCollaborationOutcome(channelId, {
+                responseState: 'failed',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
             return;
         }
         protocolState.currentTurnIndex = currentTurnIndex;
@@ -1156,12 +1318,24 @@ export class AgentsHost {
             this.finishProtocolState(channelId, channelState, protocolState, visibleMessageId);
             this.awaitingUserByChannel.delete(channelId);
             channelState.blocked = undefined;
+            this.recordCollaborationOutcome(channelId, {
+                responseState: 'responded',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
             return;
         }
         if (currentTurnIndex >= protocolState.maxTurnCount) {
             this.finishProtocolState(channelId, channelState, protocolState, visibleMessageId);
             this.awaitingUserByChannel.delete(channelId);
             channelState.blocked = undefined;
+            this.recordCollaborationOutcome(channelId, {
+                responseState: 'responded',
+                deliveryState: executed.deliveryState ?? 'not-delivered',
+                ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+                turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+            });
             return;
         }
         protocolState.expectedNextSpeakerId = peerId;
@@ -1172,6 +1346,12 @@ export class AgentsHost {
         }
         channelState.blocked = undefined;
         this.awaitingUserByChannel.delete(channelId);
+        this.recordCollaborationOutcome(channelId, {
+            responseState: 'responded',
+            deliveryState: executed.deliveryState ?? 'not-delivered',
+            ...(message.wakeBlockedState ? { wakeState: 'resumed-human' } : {}),
+            turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+        });
     }
     buildIncomingContent(message) {
         if (!message.wakeBlockedState) {
@@ -1495,7 +1675,9 @@ export class AgentsHost {
             type: 'message',
         };
         this.cancelProtocolState(channelId, channelState);
-        await this.runUngatedTurn(fallbackMessage, protocolState.anchorAuthorId, protocolState.anchorContent);
+        const taskThreadContext = await this.buildTurnTaskThreadContext(fallbackMessage, channelId);
+        const attentionSnapshot = this.getAttentionSnapshotForTurn(channelId, taskThreadContext);
+        await this.runUngatedTurn(fallbackMessage, protocolState.anchorAuthorId, protocolState.anchorContent, taskThreadContext, attentionSnapshot);
     }
     finishProtocolState(channelId, channelState, protocolState, lastMessageId) {
         protocolState.active = false;
@@ -1535,15 +1717,328 @@ export class AgentsHost {
         }
         return matched;
     }
-    async runUngatedTurn(msg, authorId, content) {
-        const executed = await this.executeTurn(msg, authorId, content);
-        if (executed.reply) {
+    resolveAttentionStatePath(channelId) {
+        return resolveAttentionStatePath(this.config.stateRootDir, channelId);
+    }
+    buildDefaultAttentionSnapshot(options) {
+        return buildNormalizedAttentionSnapshot({
+            observedAt: options?.observedAt,
+            turnExecutionId: options?.turnExecutionId,
+        });
+    }
+    async buildTurnTaskThreadContext(msg, channelId) {
+        if (msg.message_type === 'task_assignment') {
+            const currentTaskId = extractTaskIdFromTaskAssignmentContent(String(msg.content ?? msg.body ?? ''));
+            return currentTaskId ? { state: 'active', currentTaskId } : { state: 'active' };
+        }
+        if (!this.contextInjectionEnabled) {
+            return { state: 'inactive' };
+        }
+        try {
+            const content = await readFile(resolveChannelContextPayloadPath(this.config.stateRootDir, channelId), 'utf8');
+            const payload = JSON.parse(content);
+            if (payload.taskAssignmentContext?.active !== true) {
+                return { state: 'inactive' };
+            }
+            const currentTaskId = typeof payload.taskAssignmentContext.currentTaskId === 'string'
+                ? payload.taskAssignmentContext.currentTaskId.trim()
+                : '';
+            return currentTaskId ? { state: 'active', currentTaskId } : { state: 'active' };
+        }
+        catch {
+            return { state: 'unavailable' };
+        }
+    }
+    async ensureAttentionSnapshotLoaded(channelId, channelState) {
+        if (!this.attentionFollowSemanticsEnabled) {
+            return;
+        }
+        if (channelState?.attentionLoaded) {
+            return;
+        }
+        if (channelState) {
+            channelState.attentionLoaded = true;
+        }
+        try {
+            const content = await readFile(this.resolveAttentionStatePath(channelId), 'utf8');
+            this.attentionSnapshotByChannel.set(channelId, parsePersistedAttentionSnapshot(JSON.parse(content)));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT') {
+                this.logger.error('failed to load attention state', {
+                    channelId,
+                    error: summarizeError(error),
+                });
+            }
+            this.attentionSnapshotByChannel.set(channelId, this.buildDefaultAttentionSnapshot());
+        }
+    }
+    revalidateAttentionSnapshotForTurn(channelId, taskThreadContext, options) {
+        const current = this.attentionSnapshotByChannel.get(channelId)
+            ?? this.buildDefaultAttentionSnapshot();
+        if (current.claimContext?.scope !== 'task-thread') {
+            return current;
+        }
+        if (!this.contextInjectionEnabled) {
+            const next = this.buildDefaultAttentionSnapshot({
+                observedAt: options?.observedAt ?? Date.now(),
+                turnExecutionId: options?.turnExecutionId,
+            });
+            this.attentionSnapshotByChannel.set(channelId, next);
+            return next;
+        }
+        if (taskThreadContext.state === 'active' &&
+            taskThreadContext.currentTaskId &&
+            taskThreadContext.currentTaskId === current.claimContext.taskId) {
+            const next = buildNormalizedAttentionSnapshot({
+                ...current,
+                deliveryMode: 'follow',
+                claimState: 'claimed',
+                claimActivation: 'active',
+                observedAt: options?.observedAt ?? Date.now(),
+                turnExecutionId: options?.turnExecutionId,
+                claimContext: current.claimContext,
+            });
+            this.attentionSnapshotByChannel.set(channelId, next);
+            return next;
+        }
+        if (taskThreadContext.state === 'unavailable') {
+            const next = buildNormalizedAttentionSnapshot({
+                ...current,
+                deliveryMode: 'default',
+                claimState: 'claimed',
+                claimActivation: 'dormant',
+                observedAt: options?.observedAt ?? Date.now(),
+                turnExecutionId: options?.turnExecutionId,
+                claimContext: current.claimContext,
+            });
+            this.attentionSnapshotByChannel.set(channelId, next);
+            return next;
+        }
+        const next = this.buildDefaultAttentionSnapshot({
+            observedAt: options?.observedAt ?? Date.now(),
+            turnExecutionId: options?.turnExecutionId,
+        });
+        this.attentionSnapshotByChannel.set(channelId, next);
+        return next;
+    }
+    getAttentionSnapshotForTurn(channelId, taskThreadContext, options) {
+        if (!this.attentionFollowSemanticsEnabled) {
+            return undefined;
+        }
+        return this.revalidateAttentionSnapshotForTurn(channelId, taskThreadContext, options);
+    }
+    isHumanWakeFiltered(msg, authorKind, attentionSnapshot) {
+        if (!this.attentionFollowSemanticsEnabled || authorKind === 'agent') {
+            return false;
+        }
+        if (msg.message_type === 'task_assignment') {
+            return false;
+        }
+        if (this.awaitingUserByChannel.has(msg.channel_id)) {
+            return false;
+        }
+        if (msg.type?.trim() === 'mention') {
+            return false;
+        }
+        const eventKind = msg.type?.trim() ?? '';
+        if (!ORDINARY_HUMAN_EVENT_KINDS.has(eventKind)) {
+            return false;
+        }
+        if (attentionSnapshot?.wakeMode === 'follow-visible-human') {
+            return false;
+        }
+        this.noteWakeSuppressedAttentionPolicy(msg, authorKind);
+        return true;
+    }
+    applyAttentionUpdate(channelId, baseSnapshot, attentionUpdate, taskThreadContext, options) {
+        if (!this.attentionFollowSemanticsEnabled) {
+            return undefined;
+        }
+        if (!attentionUpdate) {
+            return baseSnapshot ?? this.attentionSnapshotByChannel.get(channelId);
+        }
+        const observedAt = options?.observedAt ?? Date.now();
+        const turnExecutionId = options?.turnExecutionId;
+        const current = baseSnapshot
+            ?? this.attentionSnapshotByChannel.get(channelId)
+            ?? this.buildDefaultAttentionSnapshot();
+        const clearClaim = (deliveryMode) => buildNormalizedAttentionSnapshot({
+            deliveryMode,
+            claimState: 'unclaimed',
+            claimActivation: 'inactive',
+            observedAt,
+            turnExecutionId,
+        });
+        switch (attentionUpdate) {
+            case 'follow-channel':
+                return clearClaim('follow');
+            case 'unfollow-channel':
+                return clearClaim('default');
+            case 'mute-channel':
+                return clearClaim('muted');
+            case 'claim-channel':
+                return buildNormalizedAttentionSnapshot({
+                    deliveryMode: 'follow',
+                    claimState: 'claimed',
+                    claimActivation: 'active',
+                    observedAt,
+                    turnExecutionId,
+                });
+            case 'claim-task-thread':
+                if (!this.contextInjectionEnabled
+                    || taskThreadContext.state !== 'active'
+                    || !taskThreadContext.currentTaskId) {
+                    return current;
+                }
+                return buildNormalizedAttentionSnapshot({
+                    deliveryMode: 'follow',
+                    claimState: 'claimed',
+                    claimActivation: 'active',
+                    observedAt,
+                    turnExecutionId,
+                    claimContext: {
+                        scope: 'task-thread',
+                        taskId: taskThreadContext.currentTaskId,
+                    },
+                });
+            case 'unclaim-channel':
+                return buildNormalizedAttentionSnapshot({
+                    deliveryMode: current.deliveryMode,
+                    claimState: 'unclaimed',
+                    claimActivation: 'inactive',
+                    observedAt,
+                    turnExecutionId,
+                });
+            case 'unclaim-task-thread':
+                if (!this.contextInjectionEnabled
+                    || current.claimContext?.scope !== 'task-thread'
+                    || taskThreadContext.state !== 'active'
+                    || !taskThreadContext.currentTaskId
+                    || taskThreadContext.currentTaskId !== current.claimContext.taskId) {
+                    return current;
+                }
+                return buildNormalizedAttentionSnapshot({
+                    deliveryMode: current.deliveryMode,
+                    claimState: 'unclaimed',
+                    claimActivation: 'inactive',
+                    observedAt,
+                    turnExecutionId,
+                });
+            default:
+                return current;
+        }
+    }
+    async commitAttentionSnapshot(channelId, snapshot) {
+        if (!this.attentionFollowSemanticsEnabled || !snapshot) {
+            return;
+        }
+        this.attentionSnapshotByChannel.set(channelId, snapshot);
+        await writePrivateJsonFile(this.resolveAttentionStatePath(channelId), snapshot);
+    }
+    resolveTaskThreadCollaborationContractForTurn(msg, taskThreadContext) {
+        if (!this.taskThreadCollaborationContractEnabled) {
+            return undefined;
+        }
+        return projectTaskThreadCollaborationContract({
+            incomingMessageType: msg.message_type,
+            taskThreadContextActive: taskThreadContext.state === 'active',
+        });
+    }
+    resolveCollaborationCapabilityDeclarationForTurn() {
+        if (!this.collaborationCapabilitiesDiagnosticsEnabled) {
+            return undefined;
+        }
+        return {
+            ...(this.collaborationOutcomeModelEnabled ? { collaborationOutcome: true } : {}),
+            ...(this.attentionFollowSemanticsEnabled ? { attentionSnapshot: true } : {}),
+            ...(this.taskThreadCollaborationContractEnabled
+                ? { taskThreadCollaborationContract: true }
+                : {}),
+            missedCollaborationDiagnostic: true,
+            recoveryExplanation: 'runtime-local-only',
+        };
+    }
+    resolveMissedCollaborationDiagnosticForTurn(channelId) {
+        if (!this.collaborationCapabilitiesDiagnosticsEnabled) {
+            return undefined;
+        }
+        return this.missedCollaborationDiagnosticByChannel.get(channelId);
+    }
+    updateMissedCollaborationDiagnostic(channelId, diagnostic) {
+        if (!this.collaborationCapabilitiesDiagnosticsEnabled || !diagnostic) {
+            this.missedCollaborationDiagnosticByChannel.delete(channelId);
+            return;
+        }
+        this.missedCollaborationDiagnosticByChannel.set(channelId, diagnostic);
+    }
+    noteWakeSuppressedAttentionPolicy(msg, authorKind) {
+        if (authorKind === 'agent' || msg.message_type === 'task_assignment') {
+            return;
+        }
+        const eventKind = msg.type?.trim() ?? '';
+        if (msg.type?.trim() === 'mention' || !ORDINARY_HUMAN_EVENT_KINDS.has(eventKind)) {
+            return;
+        }
+        this.updateMissedCollaborationDiagnostic(msg.channel_id, {
+            stage: 'wake',
+            reason: 'wake-suppressed-attention-policy',
+        });
+    }
+    async runUngatedTurn(msg, authorId, content, taskThreadContext, attentionSnapshot) {
+        const executed = await this.executeTurn(msg, authorId, content, {
+            attentionSnapshot,
+            taskThreadContext,
+        });
+        if (executed.completed && executed.reply) {
             this.updateAwaitingUserState(msg.channel_id, executed.reply.awaitingUser);
         }
+        if (executed.completed) {
+            await this.commitAttentionSnapshot(msg.channel_id, executed.appliedAttentionSnapshot ?? attentionSnapshot);
+        }
+        if (!executed.completed) {
+            const awaitingUser = this.awaitingUserByChannel.get(msg.channel_id);
+            if (awaitingUser) {
+                const existing = this.collaborationOutcomeByChannel.get(msg.channel_id);
+                this.recordCollaborationOutcome(msg.channel_id, {
+                    responseState: 'blocked',
+                    deliveryState: existing?.responseState === 'blocked' ? existing.deliveryState : 'not-delivered',
+                    wakeState: 'waiting',
+                    blockedDetails: {
+                        question: awaitingUser.question,
+                        ...(awaitingUser.reason ? { reason: awaitingUser.reason } : {}),
+                    },
+                    ...(existing?.turnExecutionId ? { turnExecutionId: existing.turnExecutionId } : {}),
+                });
+                return;
+            }
+        }
+        this.recordCollaborationOutcome(msg.channel_id, {
+            responseState: executed.completed && executed.reply?.awaitingUser
+                ? 'blocked'
+                : executed.completed
+                    ? 'responded'
+                    : 'failed',
+            deliveryState: executed.deliveryState ?? 'not-delivered',
+            ...(executed.completed && executed.reply?.awaitingUser
+                ? {
+                    wakeState: 'waiting',
+                    blockedDetails: {
+                        question: executed.reply.awaitingUser.question,
+                        ...(executed.reply.awaitingUser.reason
+                            ? { reason: executed.reply.awaitingUser.reason }
+                            : {}),
+                    },
+                }
+                : {}),
+        });
     }
     async executeTurn(msg, authorId, content, options) {
         const channelId = msg.channel_id;
         const activeTurn = options?.activeTurn;
+        const attentionSnapshot = options?.attentionSnapshot;
+        const taskThreadContext = options?.taskThreadContext ?? { state: 'inactive' };
         const silentTurn = options?.silent === true;
         const deferDelivery = options?.deferDelivery === true;
         const collaborationTurnMode = activeTurn?.protocol
@@ -1578,8 +2073,17 @@ export class AgentsHost {
         };
         const turnStartedAt = Date.now();
         this.logger.debug('starting turn', turnContext);
+        let reply;
+        let publicReplyText;
+        let visibleReplyBody;
+        const taskThreadCollaborationContract = this.resolveTaskThreadCollaborationContractForTurn(msg, taskThreadContext);
+        const collaborationOutcome = this.collaborationOutcomeModelEnabled
+            ? this.collaborationOutcomeByChannel.get(channelId)
+            : undefined;
+        const missedCollaborationDiagnostic = this.resolveMissedCollaborationDiagnosticForTurn(channelId);
+        const collaborationCapabilities = this.resolveCollaborationCapabilityDeclarationForTurn();
         try {
-            const reply = await this.provider.generateReply({
+            reply = await this.provider.generateReply({
                 agentName: this.config.agent.agentName,
                 provider: this.config.agent.provider,
                 channelId,
@@ -1597,6 +2101,11 @@ export class AgentsHost {
                         ...(collaborationGrounding ? { grounding: collaborationGrounding } : {}),
                     }
                     : undefined,
+                collaborationOutcome,
+                attentionSnapshot,
+                ...(taskThreadCollaborationContract ? { taskThreadCollaborationContract } : {}),
+                ...(collaborationCapabilities ? { collaborationCapabilities } : {}),
+                ...(missedCollaborationDiagnostic ? { missedCollaborationDiagnostic } : {}),
             }, usePublicDraftProgress || usePrivateCollaborationDraftProgress
                 ? {
                     onProgress: (update) => {
@@ -1611,8 +2120,16 @@ export class AgentsHost {
                     },
                 }
                 : undefined);
-            const publicReplyText = resolvePublicReplyText(reply);
-            const visibleReplyBody = this.resolveVisibleTurnBody(activeTurn, reply, publicReplyText);
+            publicReplyText = resolvePublicReplyText(reply);
+            visibleReplyBody = this.resolveVisibleTurnBody(activeTurn, reply, publicReplyText);
+            const appliedAttentionSnapshot = this.applyAttentionUpdate(channelId, attentionSnapshot, reply.controlMalformed
+                ? undefined
+                : (reply.control && 'attentionUpdate' in reply.control
+                    ? reply.control.attentionUpdate
+                    : undefined), taskThreadContext, {
+                observedAt: Date.now(),
+                turnExecutionId: activeTurn?.turnExecutionId ?? undefined,
+            });
             if (!(await this.canAcceptCompletedTurnOutput(channelId, activeTurn))) {
                 await this.discardDraft(channelId);
                 if (activeTurn?.turnExecutionId) {
@@ -1637,6 +2154,8 @@ export class AgentsHost {
                     deliveredMessageId: null,
                     publicReplyText,
                     visibleReplyBody,
+                    deliveryState: 'not-delivered',
+                    appliedAttentionSnapshot,
                     stale: false,
                     completed: true,
                 };
@@ -1655,6 +2174,8 @@ export class AgentsHost {
                     deliveredMessageId: null,
                     publicReplyText,
                     visibleReplyBody,
+                    deliveryState: 'not-delivered',
+                    appliedAttentionSnapshot,
                     stale: false,
                     completed: true,
                 };
@@ -1681,6 +2202,8 @@ export class AgentsHost {
                     deliveredMessageId,
                     publicReplyText,
                     visibleReplyBody,
+                    deliveryState: deliveredMessageId ? 'draft-finalized' : 'not-delivered',
+                    appliedAttentionSnapshot,
                     stale: false,
                     completed: true,
                 };
@@ -1707,6 +2230,8 @@ export class AgentsHost {
                     deliveredMessageId: posted.messageId,
                     publicReplyText,
                     visibleReplyBody,
+                    deliveryState: 'posted',
+                    appliedAttentionSnapshot,
                     stale: false,
                     completed: true,
                 };
@@ -1728,6 +2253,8 @@ export class AgentsHost {
                 deliveredMessageId: null,
                 publicReplyText,
                 visibleReplyBody,
+                deliveryState: 'not-delivered',
+                appliedAttentionSnapshot,
                 stale: false,
                 completed: true,
             };
@@ -1748,7 +2275,14 @@ export class AgentsHost {
                 ...turnContext,
                 error: summarizeError(error),
             });
-            return { stale: activeTurn?.superseded === true, completed: false };
+            return {
+                reply,
+                publicReplyText,
+                visibleReplyBody,
+                deliveryState: reply ? 'delivery-failed' : 'not-delivered',
+                stale: activeTurn?.superseded === true,
+                completed: false,
+            };
         }
         finally {
             stopTyping();
@@ -1917,6 +2451,11 @@ export class AgentsHost {
         if (activeTurn.superseded) {
             return;
         }
+        this.recordCollaborationOutcome(channelId, {
+            responseState: 'superseded',
+            deliveryState: 'not-delivered',
+            turnExecutionId: activeTurn.turnExecutionId ?? undefined,
+        });
         if (activeTurn.turnExecutionId) {
             this.clearCollaborationDraft(channelId, {
                 generation: activeTurn.generation,
@@ -1975,6 +2514,80 @@ export class AgentsHost {
         }
         this.awaitingUserByChannel.delete(channelId);
     }
+    recordBlockedSuppressionOutcome(channelId, channelState) {
+        const blocked = channelState.blocked;
+        if (!blocked) {
+            return;
+        }
+        const existing = this.collaborationOutcomeByChannel.get(channelId);
+        this.recordCollaborationOutcome(channelId, {
+            responseState: 'blocked',
+            deliveryState: existing?.deliveryState ?? 'not-delivered',
+            wakeState: 'suppressed-agent',
+            blockedDetails: {
+                question: blocked.awaitingUser.question,
+                ...(blocked.awaitingUser.reason ? { reason: blocked.awaitingUser.reason } : {}),
+            },
+            turnExecutionId: channelState.activeTurn?.turnExecutionId
+                ?? channelState.recentTurn?.turnExecutionId
+                ?? existing?.turnExecutionId,
+        });
+    }
+    recordCollaborationOutcome(channelId, outcome) {
+        this.collaborationOutcomeByChannel.set(channelId, {
+            source: 'host-observed',
+            responseState: outcome.responseState,
+            deliveryState: outcome.deliveryState,
+            ...(outcome.wakeState ? { wakeState: outcome.wakeState } : {}),
+            ...(outcome.blockedDetails ? { blockedDetails: outcome.blockedDetails } : {}),
+            observedAt: outcome.observedAt ?? Date.now(),
+            ...(outcome.turnExecutionId ? { turnExecutionId: outcome.turnExecutionId } : {}),
+        });
+        this.syncMissedCollaborationDiagnosticFromOutcome(channelId);
+    }
+    syncMissedCollaborationDiagnosticFromOutcome(channelId) {
+        if (!this.collaborationCapabilitiesDiagnosticsEnabled) {
+            this.missedCollaborationDiagnosticByChannel.delete(channelId);
+            return;
+        }
+        const outcome = this.collaborationOutcomeByChannel.get(channelId);
+        if (!outcome) {
+            this.missedCollaborationDiagnosticByChannel.delete(channelId);
+            return;
+        }
+        if (outcome.responseState === 'blocked'
+            && outcome.wakeState === 'waiting'
+            && outcome.blockedDetails) {
+            this.updateMissedCollaborationDiagnostic(channelId, {
+                stage: 'response',
+                reason: 'blocked-awaiting-user',
+            });
+            return;
+        }
+        if (outcome.responseState === 'superseded') {
+            this.updateMissedCollaborationDiagnostic(channelId, undefined);
+            return;
+        }
+        if (!this.collaborationOutcomeModelEnabled) {
+            this.updateMissedCollaborationDiagnostic(channelId, undefined);
+            return;
+        }
+        if (outcome.deliveryState === 'delivery-failed') {
+            this.updateMissedCollaborationDiagnostic(channelId, {
+                stage: 'delivery',
+                reason: 'delivery-failed',
+            });
+            return;
+        }
+        if (outcome.deliveryState === 'not-delivered' && outcome.responseState !== 'failed') {
+            this.updateMissedCollaborationDiagnostic(channelId, {
+                stage: 'delivery',
+                reason: 'not-delivered',
+            });
+            return;
+        }
+        this.updateMissedCollaborationDiagnostic(channelId, undefined);
+    }
     resolveVisibleTurnBody(activeTurn, reply, publicReplyText) {
         if (!activeTurn?.protocol || !this.shouldRelayProtocolReply(activeTurn, reply)) {
             return publicReplyText;