@bbigbang/core 0.1.0

package/dist/web/notificationRounds.js

@@ -0,0 +1,1061 @@
+import { randomUUID } from 'node:crypto';
+import { bumpAgentMessageCheckpoint } from './messageCheckpoints.js';
+import { findThreadRootMessageId } from './threadRoots.js';
+export const NOTIFICATION_REASON_MASK = {
+    participant_heads_up: 1 << 0,
+    explicit_agent_mention: 1 << 1,
+    human_prompt: 1 << 2,
+    task_control_notice: 1 << 3,
+};
+export const NOTIFICATION_PRIORITY = {
+    participant_heads_up: 1,
+    explicit_agent_mention: 2,
+    human_prompt: 3,
+    task_control_notice: 4,
+};
+const REDACTED_NOTIFICATION_PROMPT = '[notification delivery payload redacted]';
+export function normalizeNotificationSurfaceThreadKey(threadRootId) {
+    return threadRootId?.trim() ?? '';
+}
+export function notificationSurfaceKey(channelId, threadRootId) {
+    return `${channelId}:${normalizeNotificationSurfaceThreadKey(threadRootId)}`;
+}
+function parsePayload(payloadJson) {
+    const parsed = JSON.parse(payloadJson);
+    if (!parsed || typeof parsed.promptText !== 'string' || parsed.promptText.trim() === '') {
+        throw new Error('Notification round has an invalid delivery payload.');
+    }
+    return parsed;
+}
+export function redactNotificationDeliveryPayloadJson(payloadJson) {
+    let activationMetadata;
+    try {
+        const parsed = JSON.parse(payloadJson ?? '{}');
+        activationMetadata = redactNotificationActivationMetadata(parsed?.activationMetadata);
+    }
+    catch {
+        activationMetadata = undefined;
+    }
+    return JSON.stringify({
+        promptText: REDACTED_NOTIFICATION_PROMPT,
+        ...(activationMetadata ? { activationMetadata } : {}),
+    });
+}
+function redactNotificationActivationMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const redacted = { ...value };
+    delete redacted.promptContextSections;
+    delete redacted.slashCommand;
+    delete redacted.attachments;
+    delete redacted.attachmentIds;
+    return Object.keys(redacted).length > 0 ? redacted : undefined;
+}
+function getMutableReadyRound(db, params) {
+    return db.prepare(`SELECT round_id as roundId
+       FROM agent_notification_rounds
+      WHERE target_agent_id = ?
+        AND channel_id = ?
+        AND surface_thread_key = ?
+        AND status = 'ready'
+        AND leased_until IS NULL
+      ORDER BY created_at ASC
+      LIMIT 1`).get(params.targetAgentId, params.channelId, params.surfaceThreadKey);
+}
+export function getAgentSurfaceNotificationState(db, params) {
+    const surfaceThreadKey = normalizeNotificationSurfaceThreadKey(params.threadRootId);
+    const row = db.prepare(`SELECT covered_through_seq as coveredThroughSeq,
+            acked_through_seq as ackedThroughSeq
+       FROM agent_surface_notification_state
+      WHERE target_agent_id = ?
+        AND channel_id = ?
+        AND surface_thread_key = ?
+      LIMIT 1`).get(params.targetAgentId, params.channelId, surfaceThreadKey);
+    return row;
+}
+export function getAgentSurfaceNotificationAckedThroughSeq(db, params) {
+    return getAgentSurfaceNotificationState(db, params)?.ackedThroughSeq ?? 0;
+}
+export function advanceAgentSurfaceNotificationAck(db, params) {
+    const now = params.now ?? Date.now();
+    const ackedThroughSeq = Math.max(0, Math.floor(params.ackedThroughSeq));
+    if (ackedThroughSeq <= 0)
+        return;
+    const surfaceThreadKey = normalizeNotificationSurfaceThreadKey(params.threadRootId);
+    db.transaction(() => {
+        getOrCreateSurfaceState(db, {
+            targetAgentId: params.targetAgentId,
+            channelId: params.channelId,
+            surfaceThreadKey,
+            now,
+        });
+        db.prepare(`UPDATE agent_surface_notification_state
+          SET covered_through_seq = MAX(covered_through_seq, ?),
+              acked_through_seq = MAX(acked_through_seq, ?),
+              updated_at = ?
+        WHERE target_agent_id = ?
+          AND channel_id = ?
+          AND surface_thread_key = ?`).run(ackedThroughSeq, ackedThroughSeq, now, params.targetAgentId, params.channelId, surfaceThreadKey);
+        bumpAgentMessageCheckpoint(db, params.targetAgentId, params.channelId, ackedThroughSeq, surfaceThreadKey || null);
+        const excludeRoundClause = params.excludeRoundId ? 'AND round_id <> ?' : '';
+        const supersedeArgs = [
+            now,
+            now,
+            params.targetAgentId,
+            params.channelId,
+            surfaceThreadKey,
+            ...(params.excludeRoundId ? [params.excludeRoundId] : []),
+            ackedThroughSeq,
+        ];
+        db.prepare(`UPDATE agent_notification_rounds
+          SET status = 'superseded',
+              superseded_at = ?,
+              leased_until = NULL,
+              attempt_token = NULL,
+              delivery_id = NULL,
+              delivery_mode = NULL,
+              updated_at = ?
+        WHERE target_agent_id = ?
+          AND channel_id = ?
+          AND surface_thread_key = ?
+          ${excludeRoundClause}
+          AND status IN ('ready', 'leased', 'delivered')
+          AND acked_at IS NULL
+          AND to_seq_inclusive <= ?`).run(...supersedeArgs);
+    })();
+}
+function getOrCreateSurfaceState(db, params) {
+    const existing = db.prepare(`SELECT covered_through_seq as coveredThroughSeq,
+            acked_through_seq as ackedThroughSeq
+       FROM agent_surface_notification_state
+      WHERE target_agent_id = ?
+        AND channel_id = ?
+        AND surface_thread_key = ?
+      LIMIT 1`).get(params.targetAgentId, params.channelId, params.surfaceThreadKey);
+    if (existing)
+        return existing;
+    db.prepare(`INSERT INTO agent_surface_notification_state(
+       target_agent_id, channel_id, surface_thread_key, covered_through_seq, acked_through_seq, created_at, updated_at
+     ) VALUES(?, ?, ?, 0, 0, ?, ?)`).run(params.targetAgentId, params.channelId, params.surfaceThreadKey, params.now, params.now);
+    return { coveredThroughSeq: 0, ackedThroughSeq: 0 };
+}
+export function listAgentSurfaceRosterParticipants(db, params) {
+    const now = params.now ?? Date.now();
+    const surfaceThreadKey = normalizeNotificationSurfaceThreadKey(params.threadRootId);
+    const sanitizedLimit = Number.isInteger(params.limit) && params.limit > 0 ? params.limit : undefined;
+    const limitClause = sanitizedLimit !== undefined ? `LIMIT ${sanitizedLimit}` : '';
+    return db.prepare(`SELECT r.target_agent_id as agentId,
+            a.name as name,
+            CASE
+              WHEN MAX(CASE WHEN r.source = 'surface_owner' THEN 1 ELSE 0 END) = 1 THEN 'owner'
+              ELSE 'participant'
+            END as role,
+            MIN(r.created_at) as joinedAt,
+            MAX(r.updated_at) as lastActiveAt
+       FROM agent_surface_roster r
+       JOIN agents a ON a.agent_id = r.target_agent_id
+      WHERE r.channel_id = ?
+        AND r.surface_thread_key = ?
+        AND (? != '' OR r.source != 'surface_owner')
+        AND (r.expires_at IS NULL OR r.expires_at > ?)
+      GROUP BY r.target_agent_id, a.name
+      ORDER BY
+        CASE
+          WHEN MAX(CASE WHEN r.source = 'surface_owner' THEN 1 ELSE 0 END) = 1 THEN 0
+          ELSE 1
+        END ASC,
+        MAX(r.updated_at) DESC,
+        a.name ASC
+      ${limitClause}`).all(params.channelId, surfaceThreadKey, surfaceThreadKey, now);
+}
+export function ensureAgentSurfaceOwner(db, params) {
+    const now = params.now ?? Date.now();
+    const surfaceThreadKey = normalizeNotificationSurfaceThreadKey(params.threadRootId);
+    if (!surfaceThreadKey) {
+        return;
+    }
+    const existingOwner = db.prepare(`SELECT 1
+       FROM agent_surface_roster
+      WHERE channel_id = ?
+        AND surface_thread_key = ?
+        AND source = 'surface_owner'
+      LIMIT 1`).get(params.channelId, surfaceThreadKey);
+    if (existingOwner)
+        return;
+    upsertAgentSurfaceRoster(db, {
+        targetAgentId: params.targetAgentId,
+        channelId: params.channelId,
+        threadRootId: surfaceThreadKey,
+        source: 'surface_owner',
+        sourceKey: 'owner',
+        sourceAgentId: params.targetAgentId,
+        expiresAt: null,
+        now,
+    });
+}
+export function syncTaskBindingSurfaceRoster(db, params) {
+    db.transaction(() => _syncTaskBindingSurfaceRoster(db, params))();
+}
+function _syncTaskBindingSurfaceRoster(db, params) {
+    const now = params.now ?? Date.now();
+    const entries = new Set();
+    const ownerAgentId = params.ownerAgentId?.trim();
+    if (ownerAgentId)
+        entries.add(ownerAgentId);
+    for (const collaboratorAgentId of params.collaboratorAgentIds ?? []) {
+        const normalized = collaboratorAgentId.trim();
+        if (normalized)
+            entries.add(normalized);
+    }
+    const surfaceThreadKey = normalizeNotificationSurfaceThreadKey(params.threadRootId);
+    const entryList = [...entries];
+    if (entryList.length > 0) {
+        const placeholders = entryList.map(() => '?').join(', ');
+        db.prepare(`DELETE FROM target_participants
+        WHERE channel_id = ?
+          AND thread_root_id = ?
+          AND agent_id NOT IN (${placeholders})`).run(params.channelId, surfaceThreadKey, ...entryList);
+    }
+    else {
+        db.prepare(`DELETE FROM target_participants
+        WHERE channel_id = ?
+          AND thread_root_id = ?`).run(params.channelId, surfaceThreadKey);
+    }
+    if (params.collaboratorAgentIds !== undefined) {
+        if (entryList.length > 0) {
+            const placeholders = entryList.map(() => '?').join(', ');
+            db.prepare(`DELETE FROM agent_surface_roster
+          WHERE channel_id = ?
+            AND surface_thread_key = ?
+            AND source = 'task_binding_current'
+            AND source_key = ?
+            AND target_agent_id NOT IN (${placeholders})`).run(params.channelId, surfaceThreadKey, params.taskId, ...entryList);
+        }
+        else {
+            db.prepare(`DELETE FROM agent_surface_roster
+          WHERE channel_id = ?
+            AND surface_thread_key = ?
+            AND source = 'task_binding_current'
+            AND source_key = ?`).run(params.channelId, surfaceThreadKey, params.taskId);
+        }
+    }
+    db.prepare(`DELETE FROM agent_surface_roster
+      WHERE channel_id = ?
+        AND surface_thread_key = ?
+        AND source = 'surface_owner'`).run(params.channelId, surfaceThreadKey);
+    for (const agentId of entries) {
+        upsertAgentSurfaceRoster(db, {
+            targetAgentId: agentId,
+            channelId: params.channelId,
+            threadRootId: params.threadRootId,
+            source: 'task_binding_current',
+            sourceKey: params.taskId,
+            sourceAgentId: params.ownerAgentId ?? null,
+            expiresAt: null,
+            now,
+        });
+        if (ownerAgentId && agentId === ownerAgentId) {
+            upsertAgentSurfaceRoster(db, {
+                targetAgentId: agentId,
+                channelId: params.channelId,
+                threadRootId: params.threadRootId,
+                source: 'surface_owner',
+                sourceKey: params.taskId,
+                sourceAgentId: agentId,
+                expiresAt: null,
+                now,
+            });
+        }
+    }
+}
+function loadTaskPolicySnapshotForSurface(db, params) {
+    if (!params.surfaceThreadKey)
+        return null;
+    const rootMessageId = findThreadRootMessageId(db, params.channelId, params.surfaceThreadKey);
+    if (!rootMessageId)
+        return null;
+    const row = db.prepare(`SELECT t.task_id as taskId,
+            t.status,
+            t.updated_at as updatedAt,
+            t.claimed_by_agent_id as assigneeAgentId,
+            tp.participant_role as targetParticipantRole
+       FROM tasks t
+       LEFT JOIN task_participants tp
+         ON tp.task_id = t.task_id
+        AND tp.agent_id = ?
+      WHERE t.channel_id = ?
+        AND t.message_id = ?
+      LIMIT 1`).get(params.targetAgentId, params.channelId, rootMessageId);
+    if (!row)
+        return null;
+    return {
+        taskId: row.taskId,
+        status: row.status,
+        updatedAt: row.updatedAt,
+        assigneeAgentId: row.assigneeAgentId,
+        targetParticipantRole: row.targetParticipantRole
+            ?? (row.assigneeAgentId === params.targetAgentId ? 'owner' : null),
+    };
+}
+function parseTaskPolicySnapshot(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed
+            || typeof parsed.taskId !== 'string'
+            || typeof parsed.status !== 'string'
+            || typeof parsed.updatedAt !== 'number') {
+            return null;
+        }
+        return {
+            taskId: parsed.taskId,
+            status: parsed.status,
+            updatedAt: parsed.updatedAt,
+            assigneeAgentId: typeof parsed.assigneeAgentId === 'string' ? parsed.assigneeAgentId : null,
+            targetParticipantRole: parsed.targetParticipantRole === 'owner' || parsed.targetParticipantRole === 'collaborator'
+                ? parsed.targetParticipantRole
+                : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function upsertAgentSurfaceRoster(db, params) {
+    const now = params.now ?? Date.now();
+    const surfaceThreadKey = normalizeNotificationSurfaceThreadKey(params.threadRootId);
+    if (!surfaceThreadKey && params.source === 'surface_owner') {
+        return;
+    }
+    db.prepare(`INSERT INTO agent_surface_roster(
+       target_agent_id, channel_id, surface_thread_key, source, source_key, source_agent_id, expires_at, created_at, updated_at
+     ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(target_agent_id, channel_id, surface_thread_key, source, source_key) DO UPDATE SET
+       source_agent_id = excluded.source_agent_id,
+       expires_at = excluded.expires_at,
+       updated_at = excluded.updated_at`).run(params.targetAgentId, params.channelId, surfaceThreadKey, params.source, params.sourceKey?.trim() ?? '', params.sourceAgentId ?? null, params.expiresAt ?? null, now, now);
+}
+export function createOrMergeNotificationRound(db, params) {
+    const now = params.now ?? Date.now();
+    const surfaceThreadKey = normalizeNotificationSurfaceThreadKey(params.threadRootId);
+    const toSeqInclusive = Math.max(0, Math.floor(params.toSeqInclusive));
+    if (toSeqInclusive <= 0) {
+        return { roundId: '', created: false, skipped: true, acceptedPayload: false };
+    }
+    return db.transaction(() => {
+        const state = getOrCreateSurfaceState(db, {
+            targetAgentId: params.targetAgentId,
+            channelId: params.channelId,
+            surfaceThreadKey,
+            now,
+        });
+        if (toSeqInclusive <= state.coveredThroughSeq) {
+            const existing = getMutableReadyRound(db, {
+                targetAgentId: params.targetAgentId,
+                channelId: params.channelId,
+                surfaceThreadKey,
+            });
+            return {
+                roundId: existing?.roundId ?? '',
+                created: false,
+                skipped: !existing,
+                acceptedPayload: false,
+            };
+        }
+        const reasonMask = NOTIFICATION_REASON_MASK[params.reason];
+        const priority = NOTIFICATION_PRIORITY[params.reason];
+        const payloadJson = JSON.stringify(params.deliveryPayload);
+        const resolvedTaskPolicySnapshot = params.taskPolicySnapshot
+            ?? loadTaskPolicySnapshotForSurface(db, {
+                targetAgentId: params.targetAgentId,
+                channelId: params.channelId,
+                surfaceThreadKey,
+            });
+        const taskPolicySnapshotJson = resolvedTaskPolicySnapshot == null
+            ? null
+            : JSON.stringify(resolvedTaskPolicySnapshot);
+        const existing = getMutableReadyRound(db, {
+            targetAgentId: params.targetAgentId,
+            channelId: params.channelId,
+            surfaceThreadKey,
+        });
+        db.prepare(`UPDATE agent_surface_notification_state
+          SET covered_through_seq = MAX(covered_through_seq, ?),
+              last_human_activity_at = CASE
+                WHEN ? THEN ?
+                ELSE last_human_activity_at
+              END,
+              last_target_activity_at = CASE
+                WHEN ? THEN ?
+                ELSE last_target_activity_at
+              END,
+              updated_at = ?
+        WHERE target_agent_id = ?
+          AND channel_id = ?
+          AND surface_thread_key = ?`).run(toSeqInclusive, params.fromAgentId?.startsWith('user:') ? 1 : 0, now, params.fromAgentId === params.targetAgentId ? 1 : 0, now, now, params.targetAgentId, params.channelId, surfaceThreadKey);
+        if (existing) {
+            db.prepare(`UPDATE agent_notification_rounds
+            SET conversation_id = ?,
+                reason_mask = reason_mask | ?,
+                priority = MAX(priority, ?),
+                to_seq_inclusive = MAX(to_seq_inclusive, ?),
+                from_agent_id = COALESCE(?, from_agent_id),
+                sender_name = COALESCE(?, sender_name),
+                last_message_id = COALESCE(?, last_message_id),
+                message_count = message_count + ?,
+                delivery_payload_json = ?,
+                task_policy_snapshot_json = COALESCE(?, task_policy_snapshot_json),
+                updated_at = ?
+          WHERE round_id = ?`).run(params.conversationId, reasonMask, priority, toSeqInclusive, params.fromAgentId ?? null, params.senderName ?? null, params.lastMessageId ?? null, Math.max(1, params.messageCount ?? 1), payloadJson, taskPolicySnapshotJson, now, existing.roundId);
+            return { roundId: existing.roundId, created: false, skipped: false, acceptedPayload: true };
+        }
+        const roundId = randomUUID();
+        db.prepare(`INSERT INTO agent_notification_rounds(
+         round_id, target_agent_id, channel_id, surface_thread_key, conversation_id,
+         reason_mask, priority, from_seq_exclusive, to_seq_inclusive, status, not_before,
+         from_agent_id, sender_name, first_message_id, last_message_id, message_count,
+         delivery_payload_json, task_policy_snapshot_json, created_at, updated_at
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, 'ready', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(roundId, params.targetAgentId, params.channelId, surfaceThreadKey, params.conversationId, reasonMask, priority, state.ackedThroughSeq, toSeqInclusive, params.fromAgentId ?? null, params.senderName ?? null, params.firstMessageId ?? null, params.lastMessageId ?? null, Math.max(1, params.messageCount ?? 1), payloadJson, taskPolicySnapshotJson, now, now);
+        return { roundId, created: true, skipped: false, acceptedPayload: true };
+    })();
+}
+export function leaseReadyNotificationRound(db, params) {
+    const now = params?.now ?? Date.now();
+    const leaseMs = Math.max(1_000, params?.leaseMs ?? 30_000);
+    const ackTimeoutMs = Math.max(1_000, params?.ackTimeoutMs ?? 30_000);
+    const ackDeadline = now - ackTimeoutMs;
+    const roundIdClause = params?.roundId ? 'AND round_id = ?' : '';
+    const values = params?.roundId
+        ? [now, now, ackDeadline, params.roundId]
+        : [now, now, ackDeadline];
+    const row = db.prepare(`SELECT r.round_id as roundId,
+            r.target_agent_id as targetAgentId,
+            r.channel_id as channelId,
+            r.surface_thread_key as surfaceThreadKey,
+            r.conversation_id as conversationId,
+            r.reason_mask as reasonMask,
+            r.priority,
+            r.from_seq_exclusive as fromSeqExclusive,
+            r.to_seq_inclusive as toSeqInclusive,
+            r.status,
+            r.delivery_id as deliveryId,
+            r.delivery_payload_json as deliveryPayloadJson,
+            r.task_policy_snapshot_json as taskPolicySnapshotJson,
+            r.attempt_count as attemptCount
+       FROM agent_notification_rounds r
+      WHERE r.status IN ('ready', 'leased', 'delivered')
+        AND r.not_before <= ?
+        AND NOT EXISTS (
+          SELECT 1
+            FROM agent_surface_notification_state s
+           WHERE s.target_agent_id = r.target_agent_id
+             AND s.channel_id = r.channel_id
+             AND s.surface_thread_key = r.surface_thread_key
+             AND s.acked_through_seq >= r.to_seq_inclusive
+        )
+        AND (
+          r.status = 'ready'
+          OR (r.status = 'leased' AND COALESCE(r.leased_until, 0) <= ?)
+          OR (r.status = 'delivered' AND r.acked_at IS NULL AND COALESCE(r.delivered_at, 0) <= ?)
+        )
+        ${roundIdClause}
+      ORDER BY r.priority DESC, r.created_at ASC
+      LIMIT 1`).get(...values);
+    if (!row)
+        return null;
+    const deliveryId = randomUUID();
+    const attemptToken = randomUUID();
+    const result = db.prepare(`UPDATE agent_notification_rounds
+        SET status = 'leased',
+            leased_until = ?,
+            attempt_token = ?,
+            delivery_id = ?,
+            attempt_count = attempt_count + 1,
+            updated_at = ?
+      WHERE round_id = ?
+        AND status IN ('ready', 'leased', 'delivered')
+        AND NOT EXISTS (
+          SELECT 1
+            FROM agent_surface_notification_state s
+           WHERE s.target_agent_id = agent_notification_rounds.target_agent_id
+             AND s.channel_id = agent_notification_rounds.channel_id
+             AND s.surface_thread_key = agent_notification_rounds.surface_thread_key
+             AND s.acked_through_seq >= agent_notification_rounds.to_seq_inclusive
+        )
+        AND (
+          status = 'ready'
+          OR (status = 'leased' AND COALESCE(leased_until, 0) <= ?)
+          OR (status = 'delivered' AND acked_at IS NULL AND COALESCE(delivered_at, 0) <= ?)
+        )`).run(now + leaseMs, attemptToken, deliveryId, now, row.roundId, now, ackDeadline);
+    if (result.changes !== 1)
+        return null;
+    const delivery = {
+        deliveryId,
+        roundId: row.roundId,
+        ackedThroughSeq: row.toSeqInclusive,
+        surfaceKey: notificationSurfaceKey(row.channelId, row.surfaceThreadKey),
+    };
+    return {
+        ...row,
+        status: 'leased',
+        deliveryId,
+        delivery,
+    };
+}
+export function markNotificationRoundDelivered(db, params) {
+    const now = params.now ?? Date.now();
+    db.prepare(`UPDATE agent_notification_rounds
+        SET status = 'delivered',
+            delivery_mode = ?,
+            delivered_at = ?,
+            updated_at = ?
+      WHERE round_id = ?
+        AND delivery_id = ?
+        AND status = 'leased'`).run(params.mode, now, now, params.roundId, params.deliveryId);
+}
+export function releaseNotificationRoundForRetry(db, params) {
+    const now = params.now ?? Date.now();
+    const retryMs = Math.max(1_000, params.retryMs ?? 10_000);
+    const retryAt = now + retryMs;
+    const errorText = params.error?.slice(0, 1000) ?? null;
+    db.transaction(() => {
+        const row = db.prepare(`SELECT round_id as roundId,
+              target_agent_id as targetAgentId,
+              channel_id as channelId,
+              surface_thread_key as surfaceThreadKey,
+              reason_mask as reasonMask,
+	              priority,
+	              to_seq_inclusive as toSeqInclusive,
+	              message_count as messageCount,
+	              delivery_payload_json as deliveryPayloadJson,
+	              task_policy_snapshot_json as taskPolicySnapshotJson
+         FROM agent_notification_rounds
+        WHERE round_id = ?
+          AND delivery_id = ?
+          AND status = 'leased'
+        LIMIT 1`).get(params.roundId, params.deliveryId);
+        if (!row)
+            return;
+        const existingReady = db.prepare(`SELECT round_id as roundId
+         FROM agent_notification_rounds
+        WHERE target_agent_id = ?
+          AND channel_id = ?
+          AND surface_thread_key = ?
+          AND status = 'ready'
+          AND leased_until IS NULL
+          AND round_id != ?
+        ORDER BY created_at ASC
+        LIMIT 1`).get(row.targetAgentId, row.channelId, row.surfaceThreadKey, row.roundId);
+        if (existingReady) {
+            db.prepare(`UPDATE agent_notification_rounds
+            SET reason_mask = reason_mask | ?,
+                priority = MAX(priority, ?),
+                to_seq_inclusive = MAX(to_seq_inclusive, ?),
+                message_count = message_count + ?,
+                not_before = MAX(not_before, ?),
+                task_policy_snapshot_json = COALESCE(task_policy_snapshot_json, ?),
+                failed_at = ?,
+                last_error = COALESCE(?, last_error),
+                updated_at = ?
+          WHERE round_id = ?`).run(row.reasonMask, row.priority, row.toSeqInclusive, Math.max(1, row.messageCount), retryAt, row.taskPolicySnapshotJson, now, errorText, now, existingReady.roundId);
+            db.prepare(`UPDATE agent_notification_rounds
+            SET status = 'superseded',
+                superseded_at = ?,
+                leased_until = NULL,
+                attempt_token = NULL,
+                delivery_id = NULL,
+                delivery_mode = NULL,
+                delivery_payload_json = ?,
+                failed_at = ?,
+                last_error = COALESCE(?, last_error),
+                updated_at = ?
+          WHERE round_id = ?`).run(now, redactNotificationDeliveryPayloadJson(row.deliveryPayloadJson), now, errorText, now, row.roundId);
+            return;
+        }
+        db.prepare(`UPDATE agent_notification_rounds
+          SET status = 'ready',
+              not_before = ?,
+              leased_until = NULL,
+              attempt_token = NULL,
+              delivery_id = NULL,
+              delivery_mode = NULL,
+              failed_at = ?,
+              last_error = ?,
+              updated_at = ?
+        WHERE round_id = ?
+          AND delivery_id = ?
+          AND status = 'leased'`).run(retryAt, now, errorText, now, params.roundId, params.deliveryId);
+    })();
+}
+export function ackNotificationDelivery(db, params) {
+    const now = params.now ?? Date.now();
+    return db.transaction(() => {
+        const row = db.prepare(`SELECT round_id as roundId,
+              target_agent_id as targetAgentId,
+              channel_id as channelId,
+              surface_thread_key as surfaceThreadKey,
+	              delivery_id as deliveryId,
+	              status,
+	              to_seq_inclusive as toSeqInclusive,
+	              delivery_payload_json as deliveryPayloadJson
+         FROM agent_notification_rounds
+        WHERE round_id = ?
+        LIMIT 1`).get(params.roundId);
+        if (!row
+            || row.deliveryId !== params.deliveryId
+            || !['leased', 'delivered'].includes(row.status)
+            || Math.max(0, Math.floor(params.ackedThroughSeq)) !== row.toSeqInclusive) {
+            return false;
+        }
+        const ackedThroughSeq = row.toSeqInclusive;
+        advanceAgentSurfaceNotificationAck(db, {
+            targetAgentId: row.targetAgentId,
+            channelId: row.channelId,
+            threadRootId: row.surfaceThreadKey || null,
+            ackedThroughSeq,
+            now,
+            excludeRoundId: params.roundId,
+        });
+        db.prepare(`UPDATE agent_notification_rounds
+          SET status = 'acknowledged',
+              delivery_mode = ?,
+              acked_at = COALESCE(acked_at, ?),
+	              delivered_at = COALESCE(delivered_at, ?),
+	              delivery_payload_json = ?,
+	              leased_until = NULL,
+	              updated_at = ?
+        WHERE round_id = ?
+        AND delivery_id = ?`).run(params.mode, now, now, redactNotificationDeliveryPayloadJson(row.deliveryPayloadJson), now, params.roundId, params.deliveryId);
+        return true;
+    })();
+}
+export function deleteAgentNotificationV2State(db, agentId) {
+    db.prepare(`DELETE FROM agent_surface_notification_state WHERE target_agent_id = ?`).run(agentId);
+    db.prepare(`DELETE FROM agent_notification_rounds
+      WHERE target_agent_id = ? OR from_agent_id = ?`).run(agentId, agentId);
+    db.prepare(`DELETE FROM agent_surface_roster
+      WHERE target_agent_id = ? OR source_agent_id = ?`).run(agentId, agentId);
+}
+export function deleteNotificationV2StateForChannel(db, channelId) {
+    db.prepare(`DELETE FROM agent_surface_notification_state WHERE channel_id = ?`).run(channelId);
+    db.prepare(`DELETE FROM agent_notification_rounds WHERE channel_id = ?`).run(channelId);
+    db.prepare(`DELETE FROM agent_surface_roster WHERE channel_id = ?`).run(channelId);
+}
+export function deleteNotificationV2StateForThreadRoots(db, params) {
+    const threadRootIds = Array.from(new Set(params.threadRootIds
+        .map((threadRootId) => normalizeNotificationSurfaceThreadKey(threadRootId))
+        .filter(Boolean)));
+    if (threadRootIds.length === 0)
+        return;
+    const placeholders = threadRootIds.map(() => '?').join(', ');
+    db.prepare(`DELETE FROM agent_surface_notification_state
+      WHERE channel_id = ?
+        AND surface_thread_key IN (${placeholders})`).run(params.channelId, ...threadRootIds);
+    db.prepare(`DELETE FROM agent_notification_rounds
+      WHERE channel_id = ?
+        AND surface_thread_key IN (${placeholders})`).run(params.channelId, ...threadRootIds);
+    db.prepare(`DELETE FROM agent_surface_roster
+      WHERE channel_id = ?
+        AND surface_thread_key IN (${placeholders})`).run(params.channelId, ...threadRootIds);
+}
+export function supersedeNotificationRoundsForThreadRoots(db, params) {
+    const now = params.now ?? Date.now();
+    const threadRootIds = Array.from(new Set(params.threadRootIds
+        .map((threadRootId) => normalizeNotificationSurfaceThreadKey(threadRootId))
+        .filter(Boolean)));
+    if (threadRootIds.length === 0)
+        return 0;
+    const placeholders = threadRootIds.map(() => '?').join(', ');
+    const chatReasonClause = params.chatOnly ?? true
+        ? `AND (reason_mask & ?) != 0
+       AND (reason_mask & ?) = 0`
+        : '';
+    const rows = db.prepare(`SELECT round_id as roundId,
+            target_agent_id as targetAgentId,
+            channel_id as channelId,
+            surface_thread_key as surfaceThreadKey,
+            conversation_id as conversationId,
+            reason_mask as reasonMask,
+            priority,
+            from_seq_exclusive as fromSeqExclusive,
+            to_seq_inclusive as toSeqInclusive,
+            status,
+            delivery_id as deliveryId,
+            delivery_payload_json as deliveryPayloadJson,
+            task_policy_snapshot_json as taskPolicySnapshotJson,
+            attempt_count as attemptCount
+       FROM agent_notification_rounds
+      WHERE channel_id = ?
+        AND surface_thread_key IN (${placeholders})
+        AND status IN ('ready', 'leased', 'delivered')
+        AND acked_at IS NULL
+        ${chatReasonClause}`).all(params.channelId, ...threadRootIds, ...(params.chatOnly ?? true
+        ? [
+            NOTIFICATION_REASON_MASK.participant_heads_up | NOTIFICATION_REASON_MASK.explicit_agent_mention,
+            NOTIFICATION_REASON_MASK.human_prompt | NOTIFICATION_REASON_MASK.task_control_notice,
+        ]
+        : []));
+    let superseded = 0;
+    for (const row of rows) {
+        let payload = null;
+        try {
+            payload = parsePayload(row.deliveryPayloadJson);
+        }
+        catch {
+            payload = null;
+        }
+        const current = loadTaskPolicySnapshotForSurface(db, {
+            targetAgentId: row.targetAgentId,
+            channelId: row.channelId,
+            surfaceThreadKey: row.surfaceThreadKey,
+        });
+        if (payload && current && canDeliverClosedTaskPeerInboxRound(db, row, payload, current)) {
+            continue;
+        }
+        supersedeNotificationRound(db, {
+            roundId: row.roundId,
+            now,
+            error: params.reason,
+        });
+        superseded += 1;
+    }
+    return superseded;
+}
+function hasQueuedHumanPrompt(db, conversationId) {
+    const row = db.prepare(`SELECT 1
+       FROM conversation_prompt_queue
+	      WHERE conversation_id = ?
+	        AND record_as_user_message != 0
+	        AND COALESCE(dispatch_kind, '') != 'legacy_unknown'
+	      LIMIT 1`).get(conversationId);
+    return Boolean(row);
+}
+function getConversationRunState(db, conversationId) {
+    const row = db.prepare(`SELECT c.status,
+            r.run_id as runId
+       FROM conversations c
+       LEFT JOIN runs r
+         ON r.session_key = c.session_key
+        AND r.ended_at IS NULL
+      WHERE c.id = ?
+      ORDER BY r.started_at DESC
+      LIMIT 1`).get(conversationId);
+    return row ?? null;
+}
+function canSteerReason(row, payload) {
+    if (payload.allowActiveSteer === false)
+        return false;
+    return (row.reasonMask & NOTIFICATION_REASON_MASK.task_control_notice) !== 0
+        || (row.reasonMask & NOTIFICATION_REASON_MASK.human_prompt) !== 0
+        || (row.reasonMask & NOTIFICATION_REASON_MASK.explicit_agent_mention) !== 0
+        || (payload.allowActiveSteer === true
+            && (row.reasonMask & NOTIFICATION_REASON_MASK.participant_heads_up) !== 0);
+}
+function isChatNotificationRound(row) {
+    return (row.reasonMask & (NOTIFICATION_REASON_MASK.participant_heads_up
+        | NOTIFICATION_REASON_MASK.explicit_agent_mention)) !== 0
+        && (row.reasonMask & (NOTIFICATION_REASON_MASK.human_prompt
+            | NOTIFICATION_REASON_MASK.task_control_notice)) === 0;
+}
+export function isClosedTaskStatus(status) {
+    return status === 'in_review' || status === 'done';
+}
+function isPeerInboxAggregatePayload(payload) {
+    const aggregate = payload.activationMetadata?.peerInboxAggregate;
+    return Boolean(aggregate
+        && typeof aggregate.aggregateId === 'string'
+        && Number.isFinite(aggregate.firstSeq)
+        && Number.isFinite(aggregate.lastSeq)
+        && Number.isFinite(aggregate.messageCount));
+}
+export function getTaskCloseEventAt(db, params) {
+    if (!isClosedTaskStatus(params.status))
+        return null;
+    const row = db.prepare(`SELECT MAX(created_at) as closedAt
+       FROM task_events
+      WHERE task_id = ?
+        AND event_type = 'status_changed'
+        AND to_status = ?`).get(params.taskId, params.status);
+    return typeof row?.closedAt === 'number' ? row.closedAt : null;
+}
+export function peerInboxMessagesWereCreatedBeforeTaskClose(db, params) {
+    const closedAt = getTaskCloseEventAt(db, {
+        taskId: params.taskId,
+        status: params.taskStatus,
+    });
+    if (closedAt == null)
+        return false;
+    const firstSeq = Math.max(1, Math.floor(params.firstSeq));
+    const lastSeq = Math.max(firstSeq, Math.floor(params.lastSeq));
+    const messageWindow = db.prepare(`SELECT COUNT(*) as messageCount,
+            MAX(created_at) as maxCreatedAt
+       FROM channel_messages
+      WHERE channel_id = ?
+        AND COALESCE(thread_root_id, '') = ?
+        AND seq BETWEEN ? AND ?`).get(params.channelId, params.surfaceThreadKey, firstSeq, lastSeq);
+    return Boolean(messageWindow
+        && messageWindow.messageCount > 0
+        && typeof messageWindow.maxCreatedAt === 'number'
+        && messageWindow.maxCreatedAt <= closedAt);
+}
+function canDeliverClosedTaskPeerInboxRound(db, row, payload, current) {
+    const aggregate = payload.activationMetadata?.peerInboxAggregate;
+    return isClosedTaskStatus(current.status)
+        && isChatNotificationRound(row)
+        && isPeerInboxAggregatePayload(payload)
+        && ((row.reasonMask & NOTIFICATION_REASON_MASK.participant_heads_up) === 0
+            || Boolean(current.targetParticipantRole))
+        && Boolean(aggregate)
+        && peerInboxMessagesWereCreatedBeforeTaskClose(db, {
+            channelId: row.channelId,
+            surfaceThreadKey: row.surfaceThreadKey,
+            firstSeq: aggregate?.firstSeq ?? 0,
+            lastSeq: aggregate?.lastSeq ?? 0,
+            taskId: current.taskId,
+            taskStatus: current.status,
+        });
+}
+function supersedeNotificationRound(db, params) {
+    const now = params.now ?? Date.now();
+    const deliveryClause = params.deliveryId ? 'AND delivery_id = ?' : '';
+    const row = db.prepare(`SELECT delivery_payload_json as deliveryPayloadJson
+     FROM agent_notification_rounds
+     WHERE round_id = ?
+       ${deliveryClause}
+       AND status IN ('ready', 'leased', 'delivered')
+     LIMIT 1`).get(...(params.deliveryId ? [params.roundId, params.deliveryId] : [params.roundId]));
+    if (!row)
+        return;
+    const args = params.deliveryId
+        ? [now, redactNotificationDeliveryPayloadJson(row.deliveryPayloadJson), params.error?.slice(0, 1000) ?? null, now, params.roundId, params.deliveryId]
+        : [now, redactNotificationDeliveryPayloadJson(row.deliveryPayloadJson), params.error?.slice(0, 1000) ?? null, now, params.roundId];
+    db.prepare(`UPDATE agent_notification_rounds
+        SET status = 'superseded',
+            superseded_at = ?,
+            leased_until = NULL,
+            attempt_token = NULL,
+            delivery_id = NULL,
+            delivery_mode = NULL,
+            delivery_payload_json = ?,
+            last_error = COALESCE(?, last_error),
+            updated_at = ?
+      WHERE round_id = ?
+        ${deliveryClause}
+        AND status IN ('ready', 'leased', 'delivered')`).run(...args);
+}
+function validateNotificationRoundTaskPolicy(db, row, payload) {
+    const current = loadTaskPolicySnapshotForSurface(db, {
+        targetAgentId: row.targetAgentId,
+        channelId: row.channelId,
+        surfaceThreadKey: row.surfaceThreadKey,
+    });
+    const snapshot = parseTaskPolicySnapshot(row.taskPolicySnapshotJson);
+    if (!current && !snapshot)
+        return { ok: true };
+    if (!current)
+        return { ok: false, reason: 'Task binding no longer exists' };
+    if (!snapshot) {
+        if ((row.reasonMask & NOTIFICATION_REASON_MASK.participant_heads_up) !== 0
+            && !current.targetParticipantRole) {
+            return { ok: false, reason: 'Target is no longer a current task participant' };
+        }
+        if (isClosedTaskStatus(current.status) && isChatNotificationRound(row)) {
+            return canDeliverClosedTaskPeerInboxRound(db, row, payload, current)
+                ? { ok: true }
+                : { ok: false, reason: `Task thread is ${current.status}` };
+        }
+        return { ok: true };
+    }
+    if ((row.reasonMask & NOTIFICATION_REASON_MASK.participant_heads_up) !== 0
+        && !current.targetParticipantRole) {
+        return { ok: false, reason: 'Target is no longer a current task participant' };
+    }
+    if (current.taskId !== snapshot.taskId) {
+        return { ok: false, reason: 'Task binding changed' };
+    }
+    if (isClosedTaskStatus(current.status) && isChatNotificationRound(row)) {
+        if (canDeliverClosedTaskPeerInboxRound(db, row, payload, current)) {
+            return { ok: true };
+        }
+        return current.updatedAt !== snapshot.updatedAt
+            ? { ok: false, reason: 'Task policy snapshot is stale' }
+            : { ok: false, reason: `Task thread is ${current.status}` };
+    }
+    if (current.updatedAt !== snapshot.updatedAt) {
+        return { ok: false, reason: 'Task policy snapshot is stale' };
+    }
+    return { ok: true };
+}
+export async function processReadyNotificationRounds(params) {
+    const now = params.now ?? Date.now();
+    const limit = Math.max(1, params.limit ?? 10);
+    let delivered = 0;
+    let deferred = 0;
+    for (let index = 0; index < limit; index += 1) {
+        const round = leaseReadyNotificationRound(params.db, {
+            now,
+            roundId: params.roundId,
+        });
+        if (!round)
+            break;
+        let payload;
+        try {
+            payload = parsePayload(round.deliveryPayloadJson);
+        }
+        catch (error) {
+            releaseNotificationRoundForRetry(params.db, {
+                roundId: round.roundId,
+                deliveryId: round.deliveryId,
+                error: String(error?.message ?? error),
+                now,
+            });
+            deferred += 1;
+            continue;
+        }
+        const runState = getConversationRunState(params.db, round.conversationId);
+        if (!runState) {
+            releaseNotificationRoundForRetry(params.db, {
+                roundId: round.roundId,
+                deliveryId: round.deliveryId,
+                error: 'Conversation not found',
+                now,
+                retryMs: 60_000,
+            });
+            deferred += 1;
+            continue;
+        }
+        const taskPolicy = validateNotificationRoundTaskPolicy(params.db, round, payload);
+        if (!taskPolicy.ok) {
+            supersedeNotificationRound(params.db, {
+                roundId: round.roundId,
+                deliveryId: round.deliveryId,
+                error: taskPolicy.reason,
+                now,
+            });
+            deferred += 1;
+            continue;
+        }
+        const queuedHumanPromptBlocksRound = hasQueuedHumanPrompt(params.db, round.conversationId)
+            && (round.reasonMask & NOTIFICATION_REASON_MASK.human_prompt) === 0;
+        if (queuedHumanPromptBlocksRound) {
+            releaseNotificationRoundForRetry(params.db, {
+                roundId: round.roundId,
+                deliveryId: round.deliveryId,
+                error: 'Blocked by queued human prompt',
+                now,
+            });
+            deferred += 1;
+            continue;
+        }
+        const steerAllowed = canSteerReason(round, payload);
+        if (runState.runId
+            && !steerAllowed) {
+            releaseNotificationRoundForRetry(params.db, {
+                roundId: round.roundId,
+                deliveryId: round.deliveryId,
+                error: 'Active run is not steerable for this notification reason',
+                now,
+            });
+            deferred += 1;
+            continue;
+        }
+        try {
+            const result = await params.conversationManager.submitPrompt(round.conversationId, payload.promptText, {
+                recordAsUserMessage: false,
+                activationContextText: payload.activationContextText,
+                activationContextSections: payload.activationContextSections,
+                activationContextMode: payload.activationContextMode ?? 'resume_only',
+                resumeContextText: payload.resumeContextText,
+                resumeContextSections: payload.resumeContextSections,
+                replayOverlapRecentMessages: payload.replayOverlapRecentMessages,
+                activationMetadata: payload.activationMetadata,
+                attachments: payload.attachments,
+                attachmentIds: payload.attachmentIds,
+                notificationDelivery: round.delivery,
+                allowActiveSteer: steerAllowed,
+                allowQueue: false,
+                ...(payload.suppressReplyContract === true ? { suppressReplyContract: true } : {}),
+            });
+            if (result.queued && !result.runId) {
+                releaseNotificationRoundForRetry(params.db, {
+                    roundId: round.roundId,
+                    deliveryId: round.deliveryId,
+                    error: 'Notification delivery was deferred',
+                    now,
+                });
+                deferred += 1;
+                continue;
+            }
+            markNotificationRoundDelivered(params.db, {
+                roundId: round.roundId,
+                deliveryId: round.deliveryId,
+                mode: result.steered ? 'steer' : 'dispatch',
+                now,
+            });
+            delivered += 1;
+        }
+        catch (error) {
+            releaseNotificationRoundForRetry(params.db, {
+                roundId: round.roundId,
+                deliveryId: round.deliveryId,
+                error: String(error?.message ?? error),
+                now,
+            });
+            deferred += 1;
+        }
+    }
+    return { delivered, deferred };
+}
+export async function enqueueAndDeliverNotificationRound(params) {
+    const round = createOrMergeNotificationRound(params.db, params);
+    if (round.skipped || !round.roundId || !round.acceptedPayload) {
+        return { roundId: round.roundId, delivered: 0, deferred: 0, skipped: true, acceptedPayload: round.acceptedPayload };
+    }
+    const result = await processReadyNotificationRounds({
+        db: params.db,
+        conversationManager: params.conversationManager,
+        roundId: round.roundId,
+        now: params.now,
+        limit: 1,
+    });
+    return {
+        roundId: round.roundId,
+        delivered: result.delivered,
+        deferred: result.deferred,
+        skipped: false,
+        acceptedPayload: round.acceptedPayload,
+    };
+}
+export function startNotificationDeliveryService(params) {
+    const intervalMs = Math.max(1_000, params.intervalMs ?? 1_000);
+    let timer = null;
+    let running = false;
+    const tick = async () => {
+        if (running)
+            return;
+        running = true;
+        try {
+            await processReadyNotificationRounds({
+                db: params.db,
+                conversationManager: params.conversationManager,
+            });
+        }
+        finally {
+            running = false;
+        }
+    };
+    timer = setInterval(() => {
+        void tick();
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        tick,
+        stop: () => {
+            if (!timer)
+                return;
+            clearInterval(timer);
+            timer = null;
+        },
+    };
+}