@borgee/agents-host 0.2.26 → 0.2.29

package/dist/managed-daemon.js

@@ -5,7 +5,7 @@ import { createConnection, createServer } from 'node:net';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AgentsHostSupervisor } from './agents-host-supervisor.js';
-import { COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
+import { COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, resolveManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
 import { loadConfigFromEnv } from './config.js';
 import { loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
 import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonLogPath, resolveManagedDaemonSocketPath, resolveManagedRuntimeRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
@@ -222,15 +222,45 @@ function buildManagedRuntimeSettingsEnv(baseEnv, snapshot) {
     return {
         ...baseEnv,
         [COMPATIBILITY_GATES_ENV]: snapshot.compatibilityGates.join(','),
+        [INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV]: resolveDisabledDefaultCompatibilityGates(snapshot.compatibilityGates).join(','),
         [INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV]: snapshot.providerImplementationOverrides.join(','),
         [INTERNAL_POLICY_MODE_ENV]: snapshot.internalPolicyMode,
     };
 }
-function getManagedRuntimeFingerprintMismatch(status, desiredSettings) {
-    if (!desiredSettings.convergenceEnabled) {
-        return status.managedRuntimeFingerprint != null;
+function buildDesiredManagedRuntimeSettingsFromSnapshot(snapshot) {
+    return {
+        snapshot,
+        fingerprint: createManagedRuntimeSettingsFingerprint(snapshot),
+        convergenceEnabled: snapshot.compatibilityGates.includes(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE),
+    };
+}
+async function getManagedRuntimeFingerprintMismatch(rootPath, status, desiredSettings) {
+    if (status.managedRuntimeFingerprint != null) {
+        return status.managedRuntimeFingerprint !== desiredSettings.fingerprint;
+    }
+    if (desiredSettings.convergenceEnabled) {
+        return true;
+    }
+    const persistedSettingsSnapshot = await loadManagedRuntimeSettingsSnapshot(rootPath);
+    if (!persistedSettingsSnapshot) {
+        return true;
+    }
+    return createManagedRuntimeSettingsFingerprint(persistedSettingsSnapshot) !== desiredSettings.fingerprint;
+}
+async function resolveAuthoritativeManagedRuntimeSettings(rootPath, effectiveProcessEnv) {
+    const persistedSettingsSnapshot = await loadManagedRuntimeSettingsSnapshot(rootPath);
+    if (!persistedSettingsSnapshot) {
+        return {
+            desiredSettings: resolveDesiredManagedRuntimeSettings(effectiveProcessEnv),
+            processEnv: effectiveProcessEnv,
+            persistedSettingsSnapshot: null,
+        };
     }
-    return status.managedRuntimeFingerprint !== desiredSettings.fingerprint;
+    return {
+        desiredSettings: buildDesiredManagedRuntimeSettingsFromSnapshot(persistedSettingsSnapshot),
+        processEnv: buildManagedRuntimeSettingsEnv(effectiveProcessEnv, persistedSettingsSnapshot),
+        persistedSettingsSnapshot,
+    };
 }
 function cloneLocalAgentConfig(agent) {
     return {
@@ -311,6 +341,57 @@ export function buildManagedLocalAgentConfig(options) {
         },
     };
 }
+function mergeManagedLocalAgentConfig(existingAgent, generatedAgent, envOverrides) {
+    const overrides = envOverrides ?? {};
+    const hasOverride = (key) => Object.prototype.hasOwnProperty.call(overrides, key);
+    return {
+        ...cloneLocalAgentConfig(existingAgent),
+        key: generatedAgent.key,
+        apiKey: generatedAgent.apiKey,
+        enabled: true,
+        name: hasOverride('BORGEE_AGENT_NAME') ? generatedAgent.name : existingAgent.name,
+        provider: hasOverride('RUNTIME_PROVIDER') ? generatedAgent.provider : existingAgent.provider,
+        claudeCommand: hasOverride('CLAUDE_COMMAND') ? generatedAgent.claudeCommand : existingAgent.claudeCommand,
+        claudeArgs: hasOverride('CLAUDE_ARGS')
+            ? [...(generatedAgent.claudeArgs ?? [])]
+            : [...(existingAgent.claudeArgs ?? [])],
+        codexCommand: hasOverride('CODEX_COMMAND') ? generatedAgent.codexCommand : existingAgent.codexCommand,
+        codexArgs: hasOverride('CODEX_ARGS')
+            ? [...(generatedAgent.codexArgs ?? [])]
+            : [...(existingAgent.codexArgs ?? [])],
+        copilotCommand: hasOverride('COPILOT_COMMAND')
+            ? generatedAgent.copilotCommand
+            : existingAgent.copilotCommand,
+        copilotArgs: hasOverride('COPILOT_ARGS')
+            ? [...(generatedAgent.copilotArgs ?? [])]
+            : [...(existingAgent.copilotArgs ?? [])],
+        copilotSessionTtlMinutes: hasOverride('COPILOT_SESSION_TTL_MINUTES')
+            ? generatedAgent.copilotSessionTtlMinutes
+            : existingAgent.copilotSessionTtlMinutes,
+    };
+}
+function collectExplicitManagedAgentEnvOverrides(processEnv, optionEnv) {
+    const explicitOverrides = {};
+    for (const key of [
+        'BORGEE_AGENT_NAME',
+        'RUNTIME_PROVIDER',
+        'CLAUDE_COMMAND',
+        'CLAUDE_ARGS',
+        'CODEX_COMMAND',
+        'CODEX_ARGS',
+        'COPILOT_COMMAND',
+        'COPILOT_ARGS',
+        'COPILOT_SESSION_TTL_MINUTES',
+    ]) {
+        if (processEnv[key] !== undefined) {
+            explicitOverrides[key] = processEnv[key];
+        }
+        if (optionEnv && Object.prototype.hasOwnProperty.call(optionEnv, key)) {
+            explicitOverrides[key] = optionEnv[key];
+        }
+    }
+    return explicitOverrides;
+}
 function resolveManagedRuntimeLayoutForServerUrl(serverUrl, processEnv = process.env) {
     const rootPath = resolveManagedRuntimeRoot(serverUrl, processEnv);
     return {
@@ -884,8 +965,6 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         ...(options.processEnv ?? process.env),
         ...options.env,
     };
-    const loadSpec = deps.loadSpec
-        ?? ((hostConfigPath) => loadLocalConfigGenerateSpec(hostConfigPath, { env: effectiveProcessEnv }));
     const materialize = deps.materialize ?? materializeLocalConfig;
     const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
     const spawnDaemonProcess = deps.spawnDaemon ?? spawnManagedDaemonProcess;
@@ -895,19 +974,51 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         ?? (async (rootPath) => {
             await waitForManagedDaemonShutdown(rootPath, canConnectToSocket);
         });
-    const desiredSettings = resolveDesiredManagedRuntimeSettings(effectiveProcessEnv);
-    const resolvedManagedAgent = options.apiKey === undefined ? null : buildManagedLocalAgentConfig(options);
-    const resolved = resolvedManagedAgent ??
-        resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
+    const requestedSettings = resolveDesiredManagedRuntimeSettings(effectiveProcessEnv);
+    const resolved = resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
     const releaseBootstrapLock = await acquireLock(resolved.rootPath);
     try {
+        const currentRuntimeSettings = await resolveAuthoritativeManagedRuntimeSettings(resolved.rootPath, effectiveProcessEnv);
+        const loadManagedSpecWithCurrentRuntimeEnv = (hostConfigPath) => deps.loadSpec
+            ? deps.loadSpec(hostConfigPath)
+            : loadLocalConfigGenerateSpec(hostConfigPath, {
+                env: currentRuntimeSettings.processEnv,
+            });
+        if (options.apiKey !== undefined
+            && currentRuntimeSettings.persistedSettingsSnapshot == null
+            && await fs.access(resolved.hostConfigPath).then(() => true).catch(() => false)) {
+            throw new Error(`Managed runtime root ${resolved.rootPath} predates managed-runtime-settings.json; run \`agents-host start-managed ${options.serverUrl}\` once to migrate it before updating an individual agent`);
+        }
+        const explicitManagedAgentOverrides = collectExplicitManagedAgentEnvOverrides(options.processEnv ?? process.env, options.env);
+        const currentManagedSpec = options.apiKey === undefined
+            ? undefined
+            : await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadManagedSpecWithCurrentRuntimeEnv);
+        const resolvedManagedAgent = options.apiKey === undefined
+            ? null
+            : (() => {
+                const generatedManagedAgent = buildManagedLocalAgentConfig({
+                    ...options,
+                    processEnv: currentRuntimeSettings.processEnv,
+                    env: options.env,
+                });
+                const existingAgent = currentManagedSpec?.agents.find((agent) => agent.key === generatedManagedAgent.agent.key);
+                return existingAgent
+                    ? {
+                        ...generatedManagedAgent,
+                        agent: mergeManagedLocalAgentConfig(existingAgent, generatedManagedAgent.agent, explicitManagedAgentOverrides),
+                    }
+                    : generatedManagedAgent;
+            })();
+        const desiredBootstrapSettings = options.apiKey === undefined ? requestedSettings : currentRuntimeSettings.desiredSettings;
+        const desiredBootstrapProcessEnv = options.apiKey === undefined ? effectiveProcessEnv : currentRuntimeSettings.processEnv;
         let statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
-        if (statusResponse && getManagedRuntimeFingerprintMismatch(statusResponse, desiredSettings)) {
+        if (statusResponse
+            && await getManagedRuntimeFingerprintMismatch(resolved.rootPath, statusResponse, desiredBootstrapSettings)) {
             await recycleManagedDaemonWithDesiredSettings({
                 rootPath: resolved.rootPath,
                 debug: options.debug === true,
-                processEnv: effectiveProcessEnv,
-                desiredSettings,
+                processEnv: desiredBootstrapProcessEnv,
+                desiredSettings: desiredBootstrapSettings,
                 sendRequest,
                 waitForShutdown,
                 spawnDaemonProcess,
@@ -917,11 +1028,17 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         }
         if (!statusResponse) {
             if (options.apiKey === undefined) {
-                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, loadSpec);
+                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, (hostConfigPath) => options.apiKey === undefined
+                    ? (deps.loadSpec
+                        ? deps.loadSpec(hostConfigPath)
+                        : loadLocalConfigGenerateSpec(hostConfigPath, {
+                            env: desiredBootstrapProcessEnv,
+                        }))
+                    : loadManagedSpecWithCurrentRuntimeEnv(hostConfigPath));
             }
             else {
                 try {
-                    await loadSpec(resolved.hostConfigPath);
+                    await loadManagedSpecWithCurrentRuntimeEnv(resolved.hostConfigPath);
                 }
                 catch (error) {
                     if (isNotFoundError(error)) {
@@ -938,8 +1055,8 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
             await startManagedDaemonWithPersistedSettings({
                 rootPath: resolved.rootPath,
                 debug: options.debug === true,
-                processEnv: effectiveProcessEnv,
-                desiredSettings,
+                processEnv: desiredBootstrapProcessEnv,
+                desiredSettings: desiredBootstrapSettings,
                 spawnDaemonProcess,
                 waitForDaemon,
                 sendRequest,
@@ -948,7 +1065,11 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         }
         if (options.apiKey === undefined) {
             if (!statusResponse) {
-                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, loadSpec);
+                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, (hostConfigPath) => deps.loadSpec
+                    ? deps.loadSpec(hostConfigPath)
+                    : loadLocalConfigGenerateSpec(hostConfigPath, {
+                        env: desiredBootstrapProcessEnv,
+                    }));
             }
             else {
                 assertManagedRuntimeBinding(statusResponse.borgeeBaseUrl, options.serverUrl);
@@ -1079,10 +1200,11 @@ async function terminateChildProcessAndWait(child) {
     }
     await waitForChildExit(child, DAEMON_FORCE_KILL_WAIT_MS);
 }
-async function rollbackManagedApplyFailure(rootPath, previousSpec, materialize, clearRuntimeImpl, applyError) {
+async function rollbackManagedApplyFailure(rootPath, previousSpec, previousSettingsSnapshot, materialize, clearRuntimeImpl, applyError) {
     const original = toManagedErrorPayload(applyError, 'MANAGED_RELOAD_FAILED');
     try {
         if (previousSpec) {
+            await restoreManagedRuntimeSettingsSnapshot(rootPath, previousSettingsSnapshot);
             await materialize(rootPath, cloneLocalConfigGenerateSpec(previousSpec));
         }
         else {
@@ -1139,8 +1261,6 @@ function validateDaemonUpsertAgentInput(currentSpec, serverUrl, agent, env = pro
 }
 export async function describeManagedSpec(options, deps = {}) {
     const effectiveProcessEnv = options.processEnv ?? process.env;
-    const loadSpec = deps.loadSpec
-        ?? ((hostConfigPath) => loadLocalConfigGenerateSpec(hostConfigPath, { env: effectiveProcessEnv }));
     const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
     const resolved = resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
     try {
@@ -1167,7 +1287,12 @@ export async function describeManagedSpec(options, deps = {}) {
         }
     }
     try {
-        const persistedSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpec);
+        const currentRuntimeSettings = await resolveAuthoritativeManagedRuntimeSettings(resolved.rootPath, effectiveProcessEnv);
+        const persistedSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, (hostConfigPath) => deps.loadSpec
+            ? deps.loadSpec(hostConfigPath)
+            : loadLocalConfigGenerateSpec(hostConfigPath, {
+                env: currentRuntimeSettings.processEnv,
+            }));
         if (!persistedSpec) {
             return { ok: true, present: false };
         }
@@ -1207,27 +1332,13 @@ async function applySpecToRunningManagedDaemon(rootPath, borgeeBaseUrl, spec, se
 }
 export async function applyManagedSpec(options, deps = {}) {
     const effectiveProcessEnv = options.processEnv ?? process.env;
-    const loadSpec = deps.loadSpec
-        ?? ((hostConfigPath) => loadLocalConfigGenerateSpec(hostConfigPath, { env: effectiveProcessEnv }));
-    const materialize = deps.materialize
-        ?? ((rootPath, spec) => materializeLocalConfig(rootPath, spec, { env: effectiveProcessEnv }));
+    const desiredSettings = resolveDesiredManagedRuntimeSettings(effectiveProcessEnv);
     const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
     const spawnDaemonProcess = deps.spawnDaemon ?? spawnManagedDaemonProcess;
     const waitForDaemon = deps.waitForDaemonReady ?? waitForManagedDaemonReady;
     const acquireLock = deps.acquireBootstrapLock ?? acquireBootstrapLock;
     const clearManagedRuntimeImpl = deps.clearManagedRuntime ?? clearManagedRuntime;
     const resolved = resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
-    let spec;
-    try {
-        spec = validateApplyManagedInput(options.spec, options.serverUrl, effectiveProcessEnv);
-    }
-    catch (error) {
-        if (isManagedOperationError(error)) {
-            return toManagedErrorResponse(error);
-        }
-        return toManagedErrorResponse(managedOperationError('MANAGED_SPEC_INVALID', `Invalid managed spec: ${toErrorMessage(error)}`));
-    }
-    const desiredSettings = resolveDesiredManagedRuntimeSettings(effectiveProcessEnv);
     const waitForShutdown = deps.waitForShutdown
         ?? (async (rootPath) => {
             await waitForManagedDaemonShutdown(rootPath, canConnectToSocket);
@@ -1240,6 +1351,32 @@ export async function applyManagedSpec(options, deps = {}) {
         return toApplyManagedColdStartErrorResponse(error);
     }
     try {
+        const currentRuntimeSettings = await resolveAuthoritativeManagedRuntimeSettings(resolved.rootPath, effectiveProcessEnv);
+        const loadSpecWithCurrentRuntimeEnv = (hostConfigPath) => deps.loadSpec
+            ? deps.loadSpec(hostConfigPath)
+            : loadLocalConfigGenerateSpec(hostConfigPath, {
+                env: currentRuntimeSettings.processEnv,
+            });
+        const materializeWithDesiredEnv = (rootPath, nextSpec) => deps.materialize
+            ? deps.materialize(rootPath, nextSpec)
+            : materializeLocalConfig(rootPath, nextSpec, {
+                env: effectiveProcessEnv,
+            });
+        const materializeWithCurrentRuntimeEnv = (rootPath, nextSpec) => deps.materialize
+            ? deps.materialize(rootPath, nextSpec)
+            : materializeLocalConfig(rootPath, nextSpec, {
+                env: currentRuntimeSettings.processEnv,
+            });
+        let spec;
+        try {
+            spec = validateApplyManagedInput(options.spec, options.serverUrl, effectiveProcessEnv);
+        }
+        catch (error) {
+            if (isManagedOperationError(error)) {
+                return toManagedErrorResponse(error);
+            }
+            return toManagedErrorResponse(managedOperationError('MANAGED_SPEC_INVALID', `Invalid managed spec: ${toErrorMessage(error)}`));
+        }
         let statusResponse;
         try {
             statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
@@ -1250,7 +1387,8 @@ export async function applyManagedSpec(options, deps = {}) {
             }
             throw error;
         }
-        if (statusResponse && getManagedRuntimeFingerprintMismatch(statusResponse, desiredSettings)) {
+        if (statusResponse
+            && await getManagedRuntimeFingerprintMismatch(resolved.rootPath, statusResponse, desiredSettings)) {
             try {
                 await recycleManagedDaemonWithDesiredSettings({
                     rootPath: resolved.rootPath,
@@ -1273,7 +1411,7 @@ export async function applyManagedSpec(options, deps = {}) {
         }
         let previousSpec;
         try {
-            previousSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpec);
+            previousSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpecWithCurrentRuntimeEnv);
             if (previousSpec) {
                 assertManagedSpecBinding(previousSpec, options.serverUrl);
             }
@@ -1282,10 +1420,10 @@ export async function applyManagedSpec(options, deps = {}) {
             return toApplyManagedColdStartErrorResponse(error);
         }
         try {
-            await materialize(resolved.rootPath, cloneLocalConfigGenerateSpec(spec));
+            await materializeWithDesiredEnv(resolved.rootPath, cloneLocalConfigGenerateSpec(spec));
         }
         catch (error) {
-            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, error);
+            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, currentRuntimeSettings.persistedSettingsSnapshot ?? undefined, materializeWithCurrentRuntimeEnv, clearManagedRuntimeImpl, error);
         }
         try {
             await startManagedDaemonWithPersistedSettings({
@@ -1300,7 +1438,7 @@ export async function applyManagedSpec(options, deps = {}) {
             const status = await sendRequest(resolved.rootPath, { type: 'status' });
             if (!status.ok) {
                 const managedError = getManagedErrorPayload(status);
-                return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, managedOperationError(managedError.code, managedError.message));
+                return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, currentRuntimeSettings.persistedSettingsSnapshot ?? undefined, materializeWithCurrentRuntimeEnv, clearManagedRuntimeImpl, managedOperationError(managedError.code, managedError.message));
             }
             if (status.type !== 'status') {
                 throw new Error('Unexpected managed daemon response for status');
@@ -1314,7 +1452,7 @@ export async function applyManagedSpec(options, deps = {}) {
             };
         }
         catch (error) {
-            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, error);
+            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, currentRuntimeSettings.persistedSettingsSnapshot ?? undefined, materializeWithCurrentRuntimeEnv, clearManagedRuntimeImpl, error);
         }
     }
     finally {
@@ -1350,9 +1488,7 @@ export class ManagedAgentsHostDaemon {
         this.loadSpec = deps.loadSpec ?? loadLocalConfigGenerateSpec;
         this.materialize = deps.materialize ?? materializeLocalConfig;
         const managedRuntimeSettings = resolveDesiredManagedRuntimeSettings(process.env);
-        this.managedRuntimeFingerprint = managedRuntimeSettings.convergenceEnabled
-            ? managedRuntimeSettings.fingerprint
-            : null;
+        this.managedRuntimeFingerprint = managedRuntimeSettings.fingerprint;
         this.logger = deps.logger ?? console;
         this.logPath = deps.logPath ?? null;
         this.server = createServer((socket) => {

package/dist/providers/awaiting-user.js

@@ -1,5 +1,17 @@
 export const HOST_CONTROL_PREFIX = '[[BORGEE_CONTROL]] ';
 export const AWAITING_USER_CONTROL_PREFIX = HOST_CONTROL_PREFIX;
+const VALID_ATTENTION_UPDATES = new Set([
+    'follow-channel',
+    'unfollow-channel',
+    'mute-channel',
+    'claim-channel',
+    'claim-task-thread',
+    'unclaim-channel',
+    'unclaim-task-thread',
+]);
+function isProviderAttentionUpdate(value) {
+    return typeof value === 'string' && VALID_ATTENTION_UPDATES.has(value);
+}
 function hasVisibleText(value) {
     return value.trim().length > 0;
 }
@@ -50,13 +62,26 @@ function parseControlPayload(payload) {
     if (typeof record.kind !== 'string') {
         return null;
     }
+    const attentionUpdate = (() => {
+        if (record.attentionUpdate === undefined) {
+            return undefined;
+        }
+        return isProviderAttentionUpdate(record.attentionUpdate) ? record.attentionUpdate : null;
+    })();
+    if (attentionUpdate === null) {
+        return null;
+    }
     if (record.kind === 'continue-to-peer' || record.kind === 'conclude-locally') {
-        return Object.keys(record).length === 1
-            ? { kind: record.kind }
+        return Object.keys(record).every((key) => key === 'kind' || key === 'attentionUpdate')
+            ? {
+                kind: record.kind,
+                ...(attentionUpdate ? { attentionUpdate } : {}),
+            }
             : null;
     }
     if (record.kind === 'start-protocol') {
-        return Object.keys(record).length === 2
+        return attentionUpdate === undefined
+            && Object.keys(record).length === 2
             && typeof record.rounds === 'number'
             && Number.isInteger(record.rounds)
             && record.rounds > 0
@@ -68,7 +93,7 @@ function parseControlPayload(payload) {
     }
     if (record.kind === 'awaiting-user') {
         const keys = Object.keys(record);
-        if (keys.some((key) => key !== 'kind' && key !== 'question' && key !== 'reason')) {
+        if (keys.some((key) => key !== 'kind' && key !== 'question' && key !== 'reason' && key !== 'attentionUpdate')) {
             return null;
         }
         if (typeof record.question !== 'string' || record.question.trim().length === 0) {
@@ -82,8 +107,17 @@ function parseControlPayload(payload) {
             kind: 'awaiting-user',
             question: record.question.trim(),
             ...(typeof record.reason === 'string' ? { reason: record.reason.trim() } : {}),
+            ...(attentionUpdate ? { attentionUpdate } : {}),
         };
     }
+    if (record.kind === 'attention-only') {
+        return Object.keys(record).length === 2 && attentionUpdate
+            ? {
+                kind: 'attention-only',
+                attentionUpdate,
+            }
+            : null;
+    }
     return null;
 }
 export function parseProviderReply(text) {
@@ -98,8 +132,15 @@ export function parseProviderReply(text) {
             controlMalformed: true,
         };
     }
+    const textWithoutFooter = stripTrailingCarriageReturn(match.analyzedText.slice(0, match.removalStart));
+    if (control.kind === 'attention-only' && !hasVisibleText(textWithoutFooter)) {
+        return {
+            text: textWithoutFooter,
+            controlMalformed: true,
+        };
+    }
     return {
-        text: stripTrailingCarriageReturn(match.analyzedText.slice(0, match.removalStart)),
+        text: textWithoutFooter,
         control,
         ...(control.kind === 'awaiting-user'
             ? {

package/dist/providers/codex/project-doc.js

@@ -1,4 +1,8 @@
 import { basename } from 'node:path';
+import { buildAttentionSummaryLines } from '../../context/attention.js';
+import { buildCollaborationCapabilityDeclarationSummaryLines, buildMissedCollaborationDiagnosticSummaryLines, } from '../../context/collaboration-capabilities-diagnostics.js';
+import { buildCollaborationOutcomeSummaryLines } from '../../context/collaboration-outcome.js';
+import { buildTaskThreadCollaborationSummaryLines } from '../../context/task-thread-collaboration.js';
 const PROJECT_DOC_MAX_BYTES = 32 * 1024;
 function buildSkillRuntimeLines(context) {
     if (!context?.skillRuntime || !context.channelContextPayloadPath) {
@@ -47,6 +51,26 @@ export function buildCodexProjectDocument(context) {
                 'That writable task workspace is local to agents-host for the current task thread and does not imply that the target repository has already been checked out there.',
             ]
             : []),
+        ...(() => {
+            const collaborationOutcomeLines = buildCollaborationOutcomeSummaryLines(context?.collaborationOutcome);
+            return collaborationOutcomeLines.length > 0 ? ['', ...collaborationOutcomeLines] : [];
+        })(),
+        ...(() => {
+            const attentionLines = buildAttentionSummaryLines(context?.attentionSnapshot);
+            return attentionLines.length > 0 ? ['', ...attentionLines] : [];
+        })(),
+        ...(() => {
+            const capabilityLines = buildCollaborationCapabilityDeclarationSummaryLines(context?.collaborationCapabilities);
+            return capabilityLines.length > 0 ? ['', ...capabilityLines] : [];
+        })(),
+        ...(() => {
+            const diagnosticLines = buildMissedCollaborationDiagnosticSummaryLines(context?.missedCollaborationDiagnostic);
+            return diagnosticLines.length > 0 ? ['', ...diagnosticLines] : [];
+        })(),
+        ...(() => {
+            const taskThreadLines = buildTaskThreadCollaborationSummaryLines(context?.taskThreadCollaborationContract);
+            return taskThreadLines.length > 0 ? ['', ...taskThreadLines] : [];
+        })(),
         ...(() => {
             const skillRuntimeLines = buildSkillRuntimeLines(context);
             return skillRuntimeLines.length > 0 ? ['', ...skillRuntimeLines] : [];

package/dist/state-paths.d.ts

@@ -11,6 +11,7 @@ export declare function resolveAgentCursorPath(stateRootDir: string, agentId: st
 export declare function resolveSharedProtocolKickoffDecisionPath(stateRootDir: string, channelId: string, anchorMessageId: string): string;
 export declare function resolveSharedProtocolStatusPath(stateRootDir: string, channelId: string, anchorMessageId: string): string;
 export declare function resolveConnectionsStatePath(stateRootDir: string): string;
+export declare function resolveAttentionStatePath(stateRootDir: string, channelId: string): string;
 export declare function resolveAuthorizationAuditPath(stateRootDir: string): string;
 export declare function resolvePreviousAuthorizationAuditPath(stateRootDir: string): string;
 export declare function resolveClaudeSessionMapPath(stateRootDir: string, agentId: string): string;

package/dist/state-paths.js

@@ -110,6 +110,9 @@ export function resolveSharedProtocolStatusPath(stateRootDir, channelId, anchorM
 export function resolveConnectionsStatePath(stateRootDir) {
     return join(stateRootDir, 'connections-state.sqlite');
 }
+export function resolveAttentionStatePath(stateRootDir, channelId) {
+    return join(stateRootDir, 'attention-state', `${encodeSegment(channelId)}.json`);
+}
 export function resolveAuthorizationAuditPath(stateRootDir) {
     return join(stateRootDir, 'authorization-audit.jsonl');
 }

package/dist/types.d.ts

@@ -140,6 +140,83 @@ export interface CollaborationDraftSnapshot {
     finalMessageId?: string;
 }
 export type ProviderCollaborationTurnMode = 'ordinary' | 'silent-kickoff' | 'protocol-managed';
+export type CollaborationOutcomeResponseState = 'responded' | 'blocked' | 'superseded' | 'failed';
+export type CollaborationOutcomeDeliveryState = 'posted' | 'draft-finalized' | 'not-delivered' | 'delivery-failed';
+export type CollaborationOutcomeWakeState = 'waiting' | 'suppressed-agent' | 'resumed-human';
+export interface CollaborationOutcomeBlockedDetails {
+    question: string;
+    reason?: string;
+}
+/**
+ * Shared host-side projection only. This is the latest host-observed snapshot
+ * that adapters may surface back to providers; it is not provider-authoritative
+ * truth about collaboration state or recovery.
+ */
+export interface CollaborationOutcomeSnapshot {
+    source: 'host-observed';
+    responseState: CollaborationOutcomeResponseState;
+    deliveryState: CollaborationOutcomeDeliveryState;
+    wakeState?: CollaborationOutcomeWakeState;
+    blockedDetails?: CollaborationOutcomeBlockedDetails;
+    observedAt: number;
+    turnExecutionId?: string;
+}
+export type AttentionDeliveryMode = 'default' | 'follow' | 'muted';
+export type AttentionClaimState = 'unclaimed' | 'claimed';
+export type AttentionClaimActivation = 'inactive' | 'active' | 'dormant';
+export type AttentionWakeMode = 'current-policy' | 'follow-visible-human' | 'mute-non-mention';
+export type ProviderAttentionUpdate = 'follow-channel' | 'unfollow-channel' | 'mute-channel' | 'claim-channel' | 'claim-task-thread' | 'unclaim-channel' | 'unclaim-task-thread';
+export interface AttentionClaimContext {
+    scope: 'channel' | 'task-thread';
+    taskId: string;
+}
+/**
+ * Shared host-side projection only. This is the latest host-observed snapshot
+ * that adapters may surface back to providers; it is not server-authoritative
+ * truth about delivery policy, fanout, or ownership.
+ */
+export interface AttentionSnapshot {
+    source: 'host-observed';
+    deliveryMode: AttentionDeliveryMode;
+    claimState: AttentionClaimState;
+    claimActivation: AttentionClaimActivation;
+    wakeMode: AttentionWakeMode;
+    observedAt: number;
+    turnExecutionId?: string;
+    claimContext?: AttentionClaimContext;
+}
+export type TaskThreadCollaborationTurnRole = 'assignment' | 'continuation';
+export type TaskThreadMainResultContract = 'ordinary-final-reply-in-thread';
+export type TaskThreadAuxiliaryRouteContract = 'optional-auxiliary-send-or-escalation-only';
+export type TaskThreadCheckInContract = 'status-update-intent-only';
+export type TaskThreadBlockedWorkContract = 'in-thread-disclosure-only';
+/**
+ * Shared host-side projection only. This is a narrow adapter-facing summary of
+ * task-thread collaboration meaning; it is not runtime-authoritative truth
+ * about task ownership, task routes, heartbeat execution, or blocked state.
+ */
+export interface TaskThreadCollaborationContract {
+    source: 'host-projected';
+    turnRole: TaskThreadCollaborationTurnRole;
+    taskThreadContextActive: true;
+    mainResult: TaskThreadMainResultContract;
+    auxiliaryRoute: TaskThreadAuxiliaryRouteContract;
+    checkIn: TaskThreadCheckInContract;
+    blockedWork: TaskThreadBlockedWorkContract;
+}
+export interface CollaborationCapabilityDeclaration {
+    collaborationOutcome?: true;
+    attentionSnapshot?: true;
+    taskThreadCollaborationContract?: true;
+    missedCollaborationDiagnostic?: true;
+    recoveryExplanation?: 'runtime-local-only';
+}
+export type MissedCollaborationDiagnosticStage = 'delivery' | 'wake' | 'response';
+export type MissedCollaborationDiagnosticReason = 'delivery-failed' | 'not-delivered' | 'wake-suppressed-attention-policy' | 'blocked-awaiting-user';
+export interface MissedCollaborationDiagnostic {
+    stage: MissedCollaborationDiagnosticStage;
+    reason: MissedCollaborationDiagnosticReason;
+}
 export interface ProviderCollaborationContext {
     enabled: boolean;
     turnExecutionId?: string;
@@ -158,6 +235,11 @@ export interface ProviderInput {
     incomingEventKind?: string;
     incomingMessageType?: string;
     collaboration?: ProviderCollaborationContext;
+    collaborationOutcome?: CollaborationOutcomeSnapshot;
+    attentionSnapshot?: AttentionSnapshot;
+    taskThreadCollaborationContract?: TaskThreadCollaborationContract;
+    collaborationCapabilities?: CollaborationCapabilityDeclaration;
+    missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
 }
 export interface ProviderProtocolContext {
     anchorMessageId: string;
@@ -210,6 +292,11 @@ export interface PreparedPromptContext {
     gatewayAuthPath?: string;
     collaborationTurnExecutionId?: string;
     collaborationTurnMode?: ProviderCollaborationTurnMode;
+    collaborationOutcome?: CollaborationOutcomeSnapshot;
+    attentionSnapshot?: AttentionSnapshot;
+    taskThreadCollaborationContract?: TaskThreadCollaborationContract;
+    collaborationCapabilities?: CollaborationCapabilityDeclaration;
+    missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
     kickoff?: ProviderProtocolKickoffContext;
     protocol?: ProviderProtocolContext;
     grounding?: ProviderTurnGroundingContext;
@@ -234,16 +321,22 @@ export interface ProviderAwaitingUser {
     question: string;
     reason?: string;
 }
-export type ProviderTurnControl = {
+export interface ProviderTurnControlBase {
+    attentionUpdate?: ProviderAttentionUpdate;
+}
+export type ProviderTurnControl = ({
     kind: 'continue-to-peer';
-} | {
+} & ProviderTurnControlBase) | ({
     kind: 'conclude-locally';
-} | {
+} & ProviderTurnControlBase) | {
     kind: 'start-protocol';
     rounds: number;
 } | ({
     kind: 'awaiting-user';
-} & ProviderAwaitingUser);
+} & ProviderAwaitingUser & ProviderTurnControlBase) | ({
+    kind: 'attention-only';
+    attentionUpdate: ProviderAttentionUpdate;
+} & ProviderTurnControlBase);
 export interface ProviderReply {
     text: string;
     awaitingUser?: ProviderAwaitingUser;