feat(cursor): detect inline model errors, surface, notify, and bridge (#878)

android/app/src/main/kotlin/app/hapi/companion/fcm/NotificationChannels.kt

@@ -13,6 +13,9 @@ import app.hapi.data.push.PushPayload
  *
  *  - `permission_requests` — HIGH: an agent is blocked on the operator; the
  *    heads-up + sound interruption is the point.
+ *  - `model_errors` — HIGH: the agent hit a model-side failure (rate limit,
+ *    quota, crash); same urgency as a blocked permission, event-tagged so
+ *    distinct errors do not overwrite each other.
  *  - `ready` — DEFAULT: the agent finished and is waiting for input.
  *  - `task_notifications` — DEFAULT: task completed/failed; also the bucket
  *    for unknown types / contract versions (never heads-up for those).
@@ -34,6 +37,13 @@ object NotificationChannels {
                 ).apply {
                     description = context.getString(R.string.channel_permission_requests_desc)
                 },
+                NotificationChannel(
+                    PushPayload.CHANNEL_MODEL_ERROR,
+                    context.getString(R.string.channel_model_errors),
+                    NotificationManager.IMPORTANCE_HIGH,
+                ).apply {
+                    description = context.getString(R.string.channel_model_errors_desc)
+                },
                 NotificationChannel(
                     PushPayload.CHANNEL_READY,
                     context.getString(R.string.channel_ready),

android/app/src/main/kotlin/app/hapi/companion/fcm/PushNotifications.kt

@@ -64,7 +64,7 @@ object PushNotifications {
             when (payload.type) {
                 PushType.PERMISSION_REQUEST -> addPermissionActions(context, builder, payload)
                 PushType.READY, PushType.TASK_NOTIFICATION -> addReplyActions(context, builder, payload)
-                null -> Unit
+                PushType.MODEL_ERROR, null -> Unit
             }
         }
 

android/app/src/main/res/values-zh-rCN/strings.xml

@@ -172,6 +172,8 @@
     <!-- Push notifications (B-M4a) -->
     <string name="channel_permission_requests">权限请求</string>
     <string name="channel_permission_requests_desc">智能体正在等待您允许或拒绝一次工具调用</string>
+    <string name="channel_model_errors">模型错误</string>
+    <string name="channel_model_errors_desc">智能体遇到需要处理的模型侧失败</string>
     <string name="channel_ready">代理就绪</string>
     <string name="channel_ready_desc">智能体已完成并正在等待输入</string>
     <string name="channel_task_notifications">任务通知</string>

android/app/src/main/res/values/strings.xml

@@ -165,6 +165,8 @@
     <!-- Push notifications (B-M4a) -->
     <string name="channel_permission_requests">Permission requests</string>
     <string name="channel_permission_requests_desc">An agent is waiting for you to allow or deny a tool call</string>
+    <string name="channel_model_errors">Model errors</string>
+    <string name="channel_model_errors_desc">An agent hit a model-side failure that needs attention</string>
     <string name="channel_ready">Agent ready</string>
     <string name="channel_ready_desc">An agent finished and is waiting for input</string>
     <string name="channel_task_notifications">Task notifications</string>

android/core/data/src/main/kotlin/app/hapi/data/push/PushPayload.kt

@@ -12,7 +12,8 @@ import kotlinx.serialization.Serializable
 enum class PushType(val wire: String) {
     READY("ready"),
     PERMISSION_REQUEST("permission-request"),
-    TASK_NOTIFICATION("task-notification");
+    TASK_NOTIFICATION("task-notification"),
+    MODEL_ERROR("model-error");
 
     companion object {
         fun fromWire(value: String): PushType? = entries.firstOrNull { it.wire == value }
@@ -75,6 +76,8 @@ data class PushPayload(
     val severity: PushSeverity?,
     val contractVersion: String?,
     val notifySummary: PushNotifySummary?,
+    /** Hub coalescing tag (`FcmSendPayload.tag`), when present on the data map. */
+    val tag: String?,
 ) {
 
     /**
@@ -95,30 +98,31 @@ data class PushPayload(
         get() = isKnownContractVersion && when (type) {
             PushType.PERMISSION_REQUEST -> requestId != null
             PushType.READY, PushType.TASK_NOTIFICATION -> true
-            null -> false
+            PushType.MODEL_ERROR, null -> false
         }
 
     /**
      * Notification channel routing: `permission_requests` (HIGH) /
-     * `ready` (DEFAULT) / `task_notifications` (DEFAULT). Unknown types and
-     * unknown contract versions land in the default-importance
-     * `task_notifications` bucket — never in the heads-up channel.
+     * `model_errors` (HIGH) / `ready` (DEFAULT) / `task_notifications`
+     * (DEFAULT). Unknown types and unknown contract versions land in the
+     * default-importance `task_notifications` bucket — never heads-up.
      */
     val channelId: String
         get() = when {
             !isKnownContractVersion -> CHANNEL_TASK_NOTIFICATIONS
             type == PushType.PERMISSION_REQUEST -> CHANNEL_PERMISSION_REQUESTS
+            type == PushType.MODEL_ERROR -> CHANNEL_MODEL_ERROR
             type == PushType.READY -> CHANNEL_READY
             else -> CHANNEL_TASK_NOTIFICATIONS
         }
 
     /**
-     * Coalescing tag `type-<sessionId>`: a newer push of the same type for
-     * the same session replaces the previous notification instead of
-     * stacking (mirrors the hub-side `tag` scheme it uses for Web Push).
+     * Coalescing tag: prefer the hub-supplied `data.tag` (event-specific
+     * for `model-error`) before falling back to `type-<sessionId>`.
      */
     val notificationTag: String
-        get() = "${rawType.ifBlank { "unknown" }}-$sessionId"
+        get() = tag?.takeIf { it.isNotBlank() }
+            ?: "${rawType.ifBlank { "unknown" }}-$sessionId"
 
     /** Title to render; falls back to the session name, then a constant. */
     val displayTitle: String
@@ -152,6 +156,7 @@ data class PushPayload(
         const val CHANNEL_PERMISSION_REQUESTS = "permission_requests"
         const val CHANNEL_READY = "ready"
         const val CHANNEL_TASK_NOTIFICATIONS = "task_notifications"
+        const val CHANNEL_MODEL_ERROR = "model_errors"
 
         private const val DEFAULT_TITLE = "HAPI"
 
@@ -175,6 +180,7 @@ data class PushPayload(
                 severity = PushSeverity.fromWire(data["severity"]),
                 contractVersion = data["contractVersion"]?.takeIf { it.isNotBlank() },
                 notifySummary = data["notifySummary"]?.let(::parseNotifySummary),
+                tag = data["tag"]?.takeIf { it.isNotBlank() },
             )
         }
 

android/core/data/src/test/kotlin/app/hapi/data/push/PushPayloadTest.kt

@@ -82,6 +82,16 @@ class PushPayloadTest {
             PushPayload.CHANNEL_TASK_NOTIFICATIONS,
             PushPayload.parse(permissionData("type" to "task-notification"))!!.channelId,
         )
+        assertEquals(
+            PushPayload.CHANNEL_MODEL_ERROR,
+            PushPayload.parse(
+                permissionData(
+                    "type" to "model-error",
+                    "severity" to "error",
+                    "tag" to "model-error-11111111-2222-3333-4444-555555555555-evt-1",
+                )
+            )!!.channelId,
+        )
     }
 
     @Test
@@ -127,6 +137,51 @@ class PushPayloadTest {
         )
     }
 
+    @Test
+    fun `model-error is a known type and prefers the hub event tag`() {
+        val eventTag = "model-error-11111111-2222-3333-4444-555555555555-evt-1710000000000"
+        val payload = PushPayload.parse(
+            permissionData(
+                "type" to "model-error",
+                "severity" to "error",
+                "title" to "Rate limited",
+                "body" to "status 429",
+                "tag" to eventTag,
+            ).minus("requestId"),
+        )!!
+
+        assertEquals(PushType.MODEL_ERROR, payload.type)
+        assertEquals("model-error", payload.rawType)
+        assertEquals(PushPayload.CHANNEL_MODEL_ERROR, payload.channelId)
+        assertEquals(eventTag, payload.notificationTag)
+        assertEquals(PushSeverity.ERROR, payload.severity)
+        assertFalse(payload.supportsActions)
+    }
+
+    @Test
+    fun `model-error without a hub tag falls back to type-sessionId`() {
+        val payload = PushPayload.parse(
+            permissionData("type" to "model-error").minus("requestId"),
+        )!!
+        assertEquals(
+            "model-error-11111111-2222-3333-4444-555555555555",
+            payload.notificationTag,
+        )
+    }
+
+    @Test
+    fun `distinct model-error tags do not collapse`() {
+        val session = "11111111-2222-3333-4444-555555555555"
+        val first = PushPayload.parse(
+            permissionData("type" to "model-error", "tag" to "model-error-$session-evt-1"),
+        )!!.notificationTag
+        val second = PushPayload.parse(
+            permissionData("type" to "model-error", "tag" to "model-error-$session-evt-2"),
+        )!!.notificationTag
+        assertEquals("model-error-$session-evt-1", first)
+        assertEquals("model-error-$session-evt-2", second)
+    }
+
     // ---------------------------------------------------------- ready bodies --
 
     @Test

cli/src/agent/backends/acp/AcpSdkBackend.test.ts

@@ -735,6 +735,39 @@ describe('AcpSdkBackend', () => {
         expect(turnCompleteIdx).toBeGreaterThan(lateIdx);
     });
 
+    it('skips session/prompt when shouldSend is false after pre-prompt drain', async () => {
+        backendStatics.PRE_PROMPT_UPDATE_QUIET_PERIOD_MS = 1;
+        backendStatics.PRE_PROMPT_UPDATE_DRAIN_TIMEOUT_MS = 50;
+        backendStatics.UPDATE_QUIET_PERIOD_MS = 1;
+        backendStatics.UPDATE_DRAIN_TIMEOUT_MS = 50;
+        backendStatics.LATE_FLUSH_WINDOW_MS = 1;
+
+        const backend = new AcpSdkBackend({ command: 'opencode' });
+        const backendInternal = backend as unknown as {
+            transport: {
+                sendRequest: (...args: unknown[]) => Promise<unknown>;
+                close: () => Promise<void>;
+            } | null;
+        };
+        let sendCalls = 0;
+        backendInternal.transport = {
+            sendRequest: async () => {
+                sendCalls += 1;
+                return { stopReason: 'end_turn' };
+            },
+            close: async () => {}
+        };
+
+        const sent = await backend.prompt(
+            'session-1',
+            [{ type: 'text', text: 'hi' }],
+            () => {},
+            { shouldSend: () => false }
+        );
+        expect(sent).toBe(false);
+        expect(sendCalls).toBe(0);
+    });
+
     it('attributes pre-prompt straggler chunks to the previous turn\'s onUpdate', async () => {
         backendStatics.UPDATE_QUIET_PERIOD_MS = 25;
         backendStatics.UPDATE_DRAIN_TIMEOUT_MS = 200;

cli/src/agent/backends/acp/AcpSdkBackend.ts

@@ -542,8 +542,9 @@ export class AcpSdkBackend implements AgentBackend {
     async prompt(
         sessionId: string,
         content: PromptContent[],
-        onUpdate: (msg: AgentMessage) => void
-    ): Promise<void> {
+        onUpdate: (msg: AgentMessage) => void,
+        options?: { shouldSend?: () => boolean }
+    ): Promise<boolean> {
         if (!this.transport) {
             throw new Error('ACP transport not initialized');
         }
@@ -561,6 +562,9 @@ export class AcpSdkBackend implements AgentBackend {
         );
         await this.sessionUpdateQueue;
         this.messageHandler?.drainBuffers();
+        if (options?.shouldSend && !options.shouldSend()) {
+            return false;
+        }
         this.messageHandler = new AcpMessageHandler(onUpdate, {
             textChunkMode: this.options.textChunkMode,
             flavor: this.options.flavor,
@@ -655,6 +659,7 @@ export class AcpSdkBackend implements AgentBackend {
                 }
             }
         }
+        return true;
     }
 
     async cancelPrompt(sessionId: string): Promise<void> {

cli/src/agent/types.ts

@@ -105,7 +105,12 @@ export interface AgentBackend {
     setConfigOption?(sessionId: string, configId: string, value: string): Promise<void>;
     getSessionModelsMetadata?(sessionId: string): AgentSessionModelsMetadata | undefined;
     getThoughtLevelConfigOption?(sessionId: string): AgentSessionConfigOptionDescriptor | undefined;
-    prompt(sessionId: string, content: PromptContent[], onUpdate: (msg: AgentMessage) => void): Promise<void>;
+    prompt(
+        sessionId: string,
+        content: PromptContent[],
+        onUpdate: (msg: AgentMessage) => void,
+        options?: { shouldSend?: () => boolean }
+    ): Promise<void | boolean>;
     cancelPrompt(sessionId: string): Promise<void>;
     respondToPermission(sessionId: string, request: PermissionRequest, response: PermissionResponse): Promise<void>;
     onPermissionRequest(handler: (request: PermissionRequest) => void): void;

cli/src/api/api.ts

@@ -1,6 +1,7 @@
 import axios from 'axios'
 import type { AgentState, ClearOpencodeSessionCallbackRequest, ClearOpencodeSessionResponse, CreateMachineResponse, CreateSessionResponse, RunnerState, Machine, MachineMetadata, Metadata, Session } from '@/api/types'
 import { applyHubSessionSummaryContract } from '@/modules/common/sessionSummaryInstruction'
+import { setAutoBridgeTransientModelErrors } from '@/cursor/cursorModelErrorBridgePrefs'
 import type { LocalResumeTarget, ResumableSession } from '@hapi/protocol'
 import {
     AgentStateSchema,
@@ -88,6 +89,9 @@ export class ApiClient {
         if (typeof parsed.data.sessionSummaryContract === 'boolean') {
             applyHubSessionSummaryContract(parsed.data.sessionSummaryContract)
         }
+        if (typeof parsed.data.autoBridgeTransientModelErrors === 'boolean') {
+            setAutoBridgeTransientModelErrors(parsed.data.autoBridgeTransientModelErrors)
+        }
 
         const raw = parsed.data.session
 
@@ -144,6 +148,9 @@ export class ApiClient {
         if (typeof parsed.data.sessionSummaryContract === 'boolean') {
             applyHubSessionSummaryContract(parsed.data.sessionSummaryContract)
         }
+        if (typeof parsed.data.autoBridgeTransientModelErrors === 'boolean') {
+            setAutoBridgeTransientModelErrors(parsed.data.autoBridgeTransientModelErrors)
+        }
 
         const raw = parsed.data.session
         const metadata = (() => {

cli/src/api/apiSession.ts

@@ -1088,6 +1088,17 @@ export class ApiSessionClient extends EventEmitter {
         summary: string
         tokensBefore?: number
         estimatedTokensAfter?: number
+    } | {
+        type: 'modelError'
+        kind: string
+        transient: boolean
+        rawSnippet: string
+        priorAssistantClaimsDone: boolean
+    } | {
+        type: 'modelErrorBridged'
+        kind: string
+        auto: boolean
+        eventId: string
     }, id?: string): void {
         const content = {
             role: 'agent',