hammoc 1.8.3 → 1.9.0

package/packages/server/dist/utils/backgroundTaskPoller.js

@@ -0,0 +1,356 @@
+/**
+ * Post-turn background-task wait loop, shared by the browser chat path
+ * (websocket.ts) and the queue runner (queueService.ts).
+ *
+ * The engine returns from a turn at end_turn while background tasks may still
+ * be running. The engine process itself stays alive: when a task completes it
+ * injects a `<task-notification>` user message into the session JSONL and
+ * AUTO-RESUMES generation (a follow-up response, which can itself launch or
+ * re-engage background tasks — e.g. SendMessage re-running an idle agent).
+ * None of that reaches the closed stream, so we watch the session JSONL tail:
+ *
+ * - user `<task-notification>` messages          → resolve a pending task
+ * - user tool_result blocks                      → launch acks register a new
+ *   pending (SendMessage resume, nested launches); any other result for a
+ *   tracked id resolves it
+ * - assistant tool_use blocks with
+ *   `run_in_background: true`                    → register a new pending
+ * - assistant records                            → follow-up generation
+ *   progress; `stop_reason: "end_turn"` with no pending tasks ends the wait
+ *
+ * The wait ends when every pending task is resolved AND the auto-resume
+ * follow-up (if any) reached end_turn — or on abort/timeout.
+ */
+import { closeSync, existsSync, openSync, readSync, statSync } from 'fs';
+import { parseTaskNotification } from '../services/historyParser.js';
+import { createLogger } from './logger.js';
+const log = createLogger('backgroundTaskPoller');
+export const BG_POLL_INTERVAL_MS = 500;
+/** Hard cap. Generous: a verifier agent + follow-up repair + re-verify chain
+ *  has been observed to take 13+ minutes. The user always has the Stop button. */
+export const BG_WAIT_TIMEOUT_MS = 1_800_000; // 30 minutes
+/** How long to wait for an auto-resume follow-up to BEGIN after the last
+ *  pending task resolved. Completed notifications usually trigger generation
+ *  within ~2s; stopped/failed ones may produce none at all. */
+export const BG_FOLLOWUP_GRACE_MS = 8_000;
+/** How far back the startup reconcile scans the existing JSONL for
+ *  already-recorded notifications. Covers hours of heavy turns; a pending
+ *  task's notification is always within its own turn's bytes. */
+export const RECONCILE_SCAN_BYTES = 4 * 1024 * 1024;
+function blockText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join(' ');
+    }
+    return '';
+}
+/** Extract task-notification text from any record shape that can carry it:
+ *  queue-operation (enqueue), attachment (queued-command display), user (injected). */
+function notificationTextFrom(raw) {
+    if (raw.type === 'queue-operation' || raw.type === 'attachment') {
+        return raw.content ?? raw.attachment?.prompt ?? '';
+    }
+    if (raw.type === 'user')
+        return blockText(raw.message?.content);
+    return '';
+}
+/**
+ * Resolve pending ids whose completion notification is ALREADY in the file.
+ *
+ * A notification can be enqueued (queue-operation record) yet never injected
+ * into the conversation before the engine closes the stream — observed
+ * 2026-07-05 (TicaDice 36c5b1ea: 9 parallel agents, one notification enqueued
+ * at 09:09Z but never injected → the turn ended with a ghost pending). The
+ * tail poll only reads bytes written AFTER its snapshot, so without this pass
+ * a ghost pending waits the full timeout for bytes that already exist.
+ */
+function reconcileExistingNotifications(filePath, tracker, logPrefix) {
+    try {
+        if (!existsSync(filePath) || tracker.pending === 0)
+            return;
+        const size = statSync(filePath).size;
+        const start = Math.max(0, size - RECONCILE_SCAN_BYTES);
+        const fd = openSync(filePath, 'r');
+        const buf = Buffer.alloc(size - start);
+        readSync(fd, buf, 0, size - start, start);
+        closeSync(fd);
+        const pendingIds = [...tracker.pendingToolUseIds];
+        for (const line of buf.toString('utf8').split('\n')) {
+            if (tracker.pending === 0)
+                break;
+            // Cheap pre-filter: skip lines that reference no pending id.
+            if (!pendingIds.some((id) => line.includes(id)))
+                continue;
+            let raw;
+            try {
+                raw = JSON.parse(line);
+            }
+            catch {
+                continue; // partial first line of the bounded read, or mid-write junk
+            }
+            if (raw.isSidechain === true)
+                continue;
+            const text = notificationTextFrom(raw);
+            if (!text)
+                continue;
+            const notif = parseTaskNotification(text);
+            if (notif?.toolUseId && tracker.hasPending(notif.toolUseId)) {
+                tracker.trackTaskDone(notif.toolUseId);
+                log.info(`${logPrefix} reconcile: notification for ${notif.toolUseId.slice(-8)} already recorded (${raw.type}) — resolved without waiting, remaining=${tracker.pending}`);
+            }
+        }
+    }
+    catch {
+        /* reconcile is best-effort; the poll loop remains the authority */
+    }
+}
+/**
+ * Wait until all tracked background tasks complete and any auto-resume
+ * follow-up generation finishes.
+ *
+ * @returns true when the session reached a settled state; false on
+ *          abort/stop/timeout (caller proceeds with turn finalization anyway —
+ *          the JSONL reload picks up whatever was written).
+ */
+export async function waitForBackgroundTasksAndFollowUp(opts) {
+    const { filePath, tracker, abortSignal, keepRunning, logPrefix = '[BG-WAIT]', timeoutMs = BG_WAIT_TIMEOUT_MS, pollIntervalMs = BG_POLL_INTERVAL_MS, followUpGraceMs = BG_FOLLOWUP_GRACE_MS, callbacks, } = opts;
+    if (!tracker.isWaiting)
+        return true;
+    // A pending task's notification may ALREADY be in the file (enqueued but
+    // never injected before the stream closed) — resolve those before waiting
+    // for new bytes, otherwise they would wait out the full timeout.
+    reconcileExistingNotifications(filePath, tracker, logPrefix);
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    log.info(`${logPrefix} waiting for ${tracker.pending} background task(s): file=${filePath}, ids=[${[...tracker.pendingToolUseIds].map((id) => id.slice(-8)).join(',')}]`);
+    let lastSize = 0;
+    try {
+        lastSize = existsSync(filePath) ? statSync(filePath).size : 0;
+    }
+    catch {
+        /* file may not exist yet */
+    }
+    // Follow-up state: set when the last pending task resolves; cleared when a
+    // new pending registers (e.g. the follow-up re-engaged an agent).
+    let fullyDoneAt = tracker.isFullyDone ? Date.now() : null;
+    let followUpActive = false;
+    // stop_reason of the most recent assistant record seen in the tail.
+    let lastAssistantStop = null;
+    // Guard against re-broadcasting pre-end_turn records that were already
+    // delivered by the live delta stream. The JSONL write of the first turn's
+    // assistant record can race with polling start (SDK writes to JSONL slightly
+    // after closing the stream), so we must not emit assistant/tool blocks until
+    // we've confirmed we're past at least one task-notification (= in follow-up
+    // territory). Records before the first notification were already streamed live.
+    let seenFirstNotification = false;
+    while (Date.now() < deadline) {
+        if (abortSignal?.aborted || (keepRunning && !keepRunning())) {
+            log.info(`${logPrefix} background wait interrupted: pending=${tracker.pending}`);
+            return false;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        try {
+            // Only read when the file grew — skip expensive I/O when nothing changed.
+            const currentSize = existsSync(filePath) ? statSync(filePath).size : 0;
+            if (currentSize > lastSize) {
+                const tailSize = currentSize - lastSize;
+                const fd = openSync(filePath, 'r');
+                const buf = Buffer.alloc(tailSize);
+                readSync(fd, buf, 0, tailSize, lastSize);
+                closeSync(fd);
+                lastSize = currentSize;
+                const lines = buf.toString('utf8').split('\n').filter((l) => l.trim());
+                for (const line of lines) {
+                    let raw;
+                    try {
+                        raw = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    // Subagent sidechain records must not drive main-turn state.
+                    if (raw.isSidechain === true)
+                        continue;
+                    if (raw.type === 'assistant') {
+                        const content = raw.message?.content;
+                        if (Array.isArray(content)) {
+                            let textIdx = 0;
+                            for (const block of content) {
+                                if (block.type === 'tool_use' && block.id) {
+                                    tracker.trackToolUse(block.id, block.input, block.name);
+                                    // Only re-broadcast after the first task-notification — records
+                                    // before that were already delivered by the live delta stream.
+                                    if (seenFirstNotification) {
+                                        callbacks?.onToolUse?.({
+                                            id: block.id,
+                                            name: block.name ?? 'Tool',
+                                            input: block.input ?? {},
+                                            status: 'pending',
+                                        });
+                                    }
+                                }
+                                else if (block.type === 'text' && block.text?.trim()) {
+                                    const idx = textIdx++;
+                                    if (seenFirstNotification) {
+                                        callbacks?.onTextChunk?.({
+                                            sessionId: '',
+                                            messageId: `${raw.uuid ?? 'bg'}-t${idx}`,
+                                            content: block.text,
+                                            done: false,
+                                        });
+                                    }
+                                }
+                                else if (block.type === 'thinking' && block.thinking?.trim()) {
+                                    if (seenFirstNotification) {
+                                        callbacks?.onThinking?.(block.thinking);
+                                    }
+                                }
+                            }
+                        }
+                        lastAssistantStop = raw.message?.stop_reason ?? null;
+                        // Live check (not fullyDoneAt): the resolving notification and the
+                        // first follow-up record often land in the same read batch.
+                        // `seenFirstNotification` anchors the detection AFTER a notification
+                        // line: the SDK's transcript batcher can flush the PREVIOUS
+                        // generation's records (with their end_turn) into the tail read, and
+                        // without the anchor those late flushes masquerade as the follow-up
+                        // (observed 2026-07-12: the net declared "follow-up complete" in
+                        // 506ms while the real follow-up's first record was 95s away).
+                        // Accepted tradeoff: a reconcile-resolved pending whose REAL
+                        // follow-up lands in the tail without any notification line settles
+                        // at the grace instead of waiting for its end_turn — that shape
+                        // requires a live engine post-turn, which the dual-gate + expiry-
+                        // eviction main path no longer leaves behind.
+                        if (tracker.isFullyDone && !followUpActive && seenFirstNotification) {
+                            followUpActive = true;
+                            log.info(`${logPrefix} auto-resume follow-up generation detected`);
+                        }
+                        continue;
+                    }
+                    // Task-notification resolution: SDK writes the notification in
+                    // multiple record types — `type: "user"` (streamed input),
+                    // `type: "queue-operation"`, and `type: "attachment"` (Hammoc's
+                    // chain/queue injection). Check ALL of them for notification text.
+                    if (raw.type === 'queue-operation' || raw.type === 'attachment') {
+                        const notifText = notificationTextFrom(raw);
+                        if (notifText) {
+                            const notif = parseTaskNotification(notifText);
+                            if (notif) {
+                                seenFirstNotification = true;
+                                // A notification sighting restarts the no-follow-up grace: the
+                                // follow-up it may trigger measures from HERE, not from an
+                                // earlier reconcile-time resolution.
+                                if (tracker.isFullyDone)
+                                    fullyDoneAt = Date.now();
+                                if (notif.toolUseId) {
+                                    if (tracker.hasPending(notif.toolUseId)) {
+                                        tracker.trackTaskDone(notif.toolUseId);
+                                        log.info(`${logPrefix} task-notification (${raw.type}): toolUseId=${notif.toolUseId.slice(-8)}, remaining=${tracker.pending}`);
+                                    }
+                                    callbacks?.onTaskNotification?.({
+                                        taskId: notif.taskId,
+                                        status: notif.status,
+                                        summary: notif.summary,
+                                        toolUseId: notif.toolUseId,
+                                    });
+                                }
+                                else if (tracker.pending > 0) {
+                                    tracker.trackTaskDone();
+                                    log.info(`${logPrefix} task-notification (${raw.type}) without id, remaining=${tracker.pending}`);
+                                }
+                            }
+                        }
+                        continue;
+                    }
+                    if (raw.type !== 'user')
+                        continue;
+                    // Task-notification user messages resolve their pending task.
+                    const text = blockText(raw.message?.content);
+                    if (text) {
+                        const notif = parseTaskNotification(text);
+                        if (notif) {
+                            seenFirstNotification = true;
+                            // Same grace restart as the queue-operation/attachment branch.
+                            if (tracker.isFullyDone)
+                                fullyDoneAt = Date.now();
+                            if (notif.toolUseId) {
+                                if (tracker.hasPending(notif.toolUseId)) {
+                                    tracker.trackTaskDone(notif.toolUseId);
+                                    log.info(`${logPrefix} task-notification: toolUseId=${notif.toolUseId.slice(-8)}, remaining=${tracker.pending}`);
+                                }
+                                // Emit AFTER the poller's own resolution — the callback's
+                                // internal trackTaskDone(id) is then an idempotent no-op.
+                                // (No-id legacy notifications are NOT emitted: the callback's
+                                // no-id fallback would arbitrarily remove a second entry.)
+                                callbacks?.onTaskNotification?.({
+                                    taskId: notif.taskId,
+                                    status: notif.status,
+                                    summary: notif.summary,
+                                    toolUseId: notif.toolUseId,
+                                });
+                            }
+                            else if (tracker.pending > 0) {
+                                tracker.trackTaskDone(); // legacy: notification without tool-use-id
+                                log.info(`${logPrefix} task-notification without id, remaining=${tracker.pending}`);
+                            }
+                        }
+                    }
+                    // tool_result blocks: launch acks register (SendMessage resume,
+                    // nested launches); non-ack results for tracked ids resolve them.
+                    const content = raw.message?.content;
+                    if (Array.isArray(content)) {
+                        for (const block of content) {
+                            if (block.type === 'tool_result' && block.tool_use_id) {
+                                const before = tracker.pending;
+                                const resultText = blockText(block.content);
+                                tracker.trackToolResult(block.tool_use_id, resultText);
+                                if (tracker.pending !== before) {
+                                    log.info(`${logPrefix} tool_result ${tracker.pending > before ? 'registered' : 'resolved'}: toolUseId=${block.tool_use_id.slice(-8)}, pending=${tracker.pending}`);
+                                }
+                                const isError = block.is_error ?? false;
+                                if (seenFirstNotification) {
+                                    callbacks?.onToolResult?.(block.tool_use_id, {
+                                        success: !isError,
+                                        output: isError ? undefined : resultText,
+                                        error: isError ? resultText : undefined,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // JSONL may be mid-write; retry on next tick
+        }
+        // Maintain follow-up bookkeeping AFTER processing the batch.
+        if (tracker.isFullyDone) {
+            if (fullyDoneAt === null)
+                fullyDoneAt = Date.now();
+        }
+        else {
+            fullyDoneAt = null;
+            followUpActive = false;
+        }
+        if (tracker.isFullyDone && fullyDoneAt !== null) {
+            if (followUpActive) {
+                if (lastAssistantStop === 'end_turn') {
+                    log.info(`${logPrefix} background tasks + follow-up complete, elapsed=${Date.now() - startedAt}ms`);
+                    return true;
+                }
+            }
+            else if (Date.now() - fullyDoneAt >= followUpGraceMs) {
+                log.info(`${logPrefix} background tasks done, no follow-up generation, elapsed=${Date.now() - startedAt}ms`);
+                return true;
+            }
+        }
+    }
+    log.warn(`${logPrefix} timed out: pending=${tracker.pending}, followUpActive=${followUpActive}, elapsed=${Date.now() - startedAt}ms`);
+    return false;
+}
+//# sourceMappingURL=backgroundTaskPoller.js.map

package/packages/server/dist/utils/backgroundTaskPoller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundTaskPoller.js","sourceRoot":"","sources":["../../src/utils/backgroundTaskPoller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAIzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,GAAG,GAAG,YAAY,CAAC,sBAAsB,CAAC,CAAC;AAEjD,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC;kFACkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAC,CAAC,aAAa;AAC1D;;+DAE+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAC1C;;iEAEiE;AACjE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAqCpD,SAAS,SAAS,CAAC,OAAgB;IACjC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAQ,OAA6B;aAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;aAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;aACxB,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;uFACuF;AACvF,SAAS,oBAAoB,CAAC,GAK7B;IACC,IAAI,GAAG,CAAC,IAAI,KAAK,iBAAiB,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAChE,OAAO,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,IAAI,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChE,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,8BAA8B,CACrC,QAAgB,EAChB,OAA8B,EAC9B,SAAiB;IAEjB,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,OAAO,KAAK,CAAC;YAAE,OAAO;QAC3D,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,oBAAoB,CAAC,CAAC;QACvD,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC;QACvC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,GAAG,KAAK,EAAE,KAAK,CAAC,CAAC;QAC1C,SAAS,CAAC,EAAE,CAAC,CAAC;QAEd,MAAM,UAAU,GAAG,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAClD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACpD,IAAI,OAAO,CAAC,OAAO,KAAK,CAAC;gBAAE,MAAM;YACjC,6DAA6D;YAC7D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBAAE,SAAS;YAC1D,IAAI,GAA2E,CAAC;YAChF,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,CAAC,4DAA4D;YACxE,CAAC;YACD,IAAI,GAAG,CAAC,WAAW,KAAK,IAAI;gBAAE,SAAS;YACvC,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,KAAK,EAAE,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC5D,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBACvC,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,gCAAgC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,sBAAsB,GAAG,CAAC,IAAI,2CAA2C,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5K,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,IAA2B;IAE3B,MAAM,EACJ,QAAQ,EACR,OAAO,EACP,WAAW,EACX,WAAW,EACX,SAAS,GAAG,WAAW,EACvB,SAAS,GAAG,kBAAkB,EAC9B,cAAc,GAAG,mBAAmB,EACpC,eAAe,GAAG,oBAAoB,EACtC,SAAS,GACV,GAAG,IAAI,CAAC;IAET,IAAI,CAAC,OAAO,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAEpC,yEAAyE;IACzE,0EAA0E;IAC1E,iEAAiE;IACjE,8BAA8B,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAE7D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAEvC,GAAG,CAAC,IAAI,CACN,GAAG,SAAS,gBAAgB,OAAO,CAAC,OAAO,6BAA6B,QAAQ,UAAU,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAChK,CAAC;IAEF,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,CAAC;QACH,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,4BAA4B;IAC9B,CAAC;IAED,2EAA2E;IAC3E,kEAAkE;IAClE,IAAI,WAAW,GAAkB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACzE,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,oEAAoE;IACpE,IAAI,iBAAiB,GAAkB,IAAI,CAAC;IAC5C,uEAAuE;IACvE,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,gFAAgF;IAChF,IAAI,qBAAqB,GAAG,KAAK,CAAC;IAElC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,WAAW,EAAE,OAAO,IAAI,CAAC,WAAW,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAC5D,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,yCAAyC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACjF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;QAEpE,IAAI,CAAC;YACH,0EAA0E;YAC1E,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACvE,IAAI,WAAW,GAAG,QAAQ,EAAE,CAAC;gBAC3B,MAAM,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;gBACxC,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBACnC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACnC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBACzC,SAAS,CAAC,EAAE,CAAC,CAAC;gBACd,QAAQ,GAAG,WAAW,CAAC;gBAEvB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACvE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBACzB,IAAI,GAOH,CAAC;oBACF,IAAI,CAAC;wBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACzB,CAAC;oBAAC,MAAM,CAAC;wBACP,SAAS;oBACX,CAAC;oBACD,6DAA6D;oBAC7D,IAAI,GAAG,CAAC,WAAW,KAAK,IAAI;wBAAE,SAAS;oBAEvC,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;wBAC7B,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC;wBACrC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;4BAC3B,IAAI,OAAO,GAAG,CAAC,CAAC;4BAChB,KAAK,MAAM,KAAK,IAAI,OAA4B,EAAE,CAAC;gCACjD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;oCAC1C,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;oCACxD,gEAAgE;oCAChE,+DAA+D;oCAC/D,IAAI,qBAAqB,EAAE,CAAC;wCAC1B,SAAS,EAAE,SAAS,EAAE,CAAC;4CACrB,EAAE,EAAE,KAAK,CAAC,EAAE;4CACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,MAAM;4CAC1B,KAAK,EAAG,KAAK,CAAC,KAAiC,IAAI,EAAE;4CACrD,MAAM,EAAE,SAAS;yCAClB,CAAC,CAAC;oCACL,CAAC;gCACH,CAAC;qCAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;oCACvD,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;oCACtB,IAAI,qBAAqB,EAAE,CAAC;wCAC1B,SAAS,EAAE,WAAW,EAAE,CAAC;4CACvB,SAAS,EAAE,EAAE;4CACb,SAAS,EAAE,GAAG,GAAG,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG,EAAE;4CACxC,OAAO,EAAE,KAAK,CAAC,IAAI;4CACnB,IAAI,EAAE,KAAK;yCACZ,CAAC,CAAC;oCACL,CAAC;gCACH,CAAC;qCAAM,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;oCAC/D,IAAI,qBAAqB,EAAE,CAAC;wCAC1B,SAAS,EAAE,UAAU,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;oCAC1C,CAAC;gCACH,CAAC;4BACH,CAAC;wBACH,CAAC;wBACD,iBAAiB,GAAG,GAAG,CAAC,OAAO,EAAE,WAAW,IAAI,IAAI,CAAC;wBACrD,mEAAmE;wBACnE,4DAA4D;wBAC5D,qEAAqE;wBACrE,4DAA4D;wBAC5D,qEAAqE;wBACrE,oEAAoE;wBACpE,iEAAiE;wBACjE,+DAA+D;wBAC/D,6DAA6D;wBAC7D,oEAAoE;wBACpE,gEAAgE;wBAChE,kEAAkE;wBAClE,8CAA8C;wBAC9C,IAAI,OAAO,CAAC,WAAW,IAAI,CAAC,cAAc,IAAI,qBAAqB,EAAE,CAAC;4BACpE,cAAc,GAAG,IAAI,CAAC;4BACtB,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,4CAA4C,CAAC,CAAC;wBACrE,CAAC;wBACD,SAAS;oBACX,CAAC;oBAED,+DAA+D;oBAC/D,2DAA2D;oBAC3D,gEAAgE;oBAChE,mEAAmE;oBACnE,IAAI,GAAG,CAAC,IAAI,KAAK,iBAAiB,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;wBAChE,MAAM,SAAS,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;wBAC5C,IAAI,SAAS,EAAE,CAAC;4BACd,MAAM,KAAK,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;4BAC/C,IAAI,KAAK,EAAE,CAAC;gCACV,qBAAqB,GAAG,IAAI,CAAC;gCAC7B,+DAA+D;gCAC/D,2DAA2D;gCAC3D,qCAAqC;gCACrC,IAAI,OAAO,CAAC,WAAW;oCAAE,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gCAClD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;oCACpB,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;wCACxC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;wCACvC,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,uBAAuB,GAAG,CAAC,IAAI,gBAAgB,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;oCACjI,CAAC;oCACD,SAAS,EAAE,kBAAkB,EAAE,CAAC;wCAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;wCACpB,MAAM,EAAE,KAAK,CAAC,MAAM;wCACpB,OAAO,EAAE,KAAK,CAAC,OAAO;wCACtB,SAAS,EAAE,KAAK,CAAC,SAAS;qCAC3B,CAAC,CAAC;gCACL,CAAC;qCAAM,IAAI,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;oCAC/B,OAAO,CAAC,aAAa,EAAE,CAAC;oCACxB,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,uBAAuB,GAAG,CAAC,IAAI,2BAA2B,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gCACpG,CAAC;4BACH,CAAC;wBACH,CAAC;wBACD,SAAS;oBACX,CAAC;oBAED,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;wBAAE,SAAS;oBAElC,8DAA8D;oBAC9D,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;oBAC7C,IAAI,IAAI,EAAE,CAAC;wBACT,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;wBAC1C,IAAI,KAAK,EAAE,CAAC;4BACV,qBAAqB,GAAG,IAAI,CAAC;4BAC7B,+DAA+D;4BAC/D,IAAI,OAAO,CAAC,WAAW;gCAAE,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;4BAClD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gCACpB,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;oCACxC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;oCACvC,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,iCAAiC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gCACnH,CAAC;gCACD,0DAA0D;gCAC1D,0DAA0D;gCAC1D,8DAA8D;gCAC9D,2DAA2D;gCAC3D,SAAS,EAAE,kBAAkB,EAAE,CAAC;oCAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;oCACpB,MAAM,EAAE,KAAK,CAAC,MAAM;oCACpB,OAAO,EAAE,KAAK,CAAC,OAAO;oCACtB,SAAS,EAAE,KAAK,CAAC,SAAS;iCAC3B,CAAC,CAAC;4BACL,CAAC;iCAAM,IAAI,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;gCAC/B,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,2CAA2C;gCACpE,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,4CAA4C,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;4BACtF,CAAC;wBACH,CAAC;oBACH,CAAC;oBAED,gEAAgE;oBAChE,kEAAkE;oBAClE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC;oBACrC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;wBAC3B,KAAK,MAAM,KAAK,IAAI,OAA4B,EAAE,CAAC;4BACjD,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;gCACtD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;gCAC/B,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gCAC5C,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;gCACvD,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;oCAC/B,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,gBAAgB,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,eAAe,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gCACrK,CAAC;gCACD,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC;gCACxC,IAAI,qBAAqB,EAAE,CAAC;oCAC1B,SAAS,EAAE,YAAY,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE;wCAC3C,OAAO,EAAE,CAAC,OAAO;wCACjB,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU;wCACxC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;qCACxC,CAAC,CAAC;gCACL,CAAC;4BACH,CAAC;wBACH,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,6CAA6C;QAC/C,CAAC;QAED,6DAA6D;QAC7D,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,IAAI,WAAW,KAAK,IAAI;gBAAE,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,WAAW,GAAG,IAAI,CAAC;YACnB,cAAc,GAAG,KAAK,CAAC;QACzB,CAAC;QAED,IAAI,OAAO,CAAC,WAAW,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YAChD,IAAI,cAAc,EAAE,CAAC;gBACnB,IAAI,iBAAiB,KAAK,UAAU,EAAE,CAAC;oBACrC,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,mDAAmD,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,CAAC,CAAC;oBACpG,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;iBAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,IAAI,eAAe,EAAE,CAAC;gBACvD,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,4DAA4D,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,CAAC,CAAC;gBAC7G,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,uBAAuB,OAAO,CAAC,OAAO,oBAAoB,cAAc,aAAa,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,CAAC,CAAC;IACtI,OAAO,KAAK,CAAC;AACf,CAAC"}

package/packages/server/dist/utils/backgroundTaskTracker.d.ts

@@ -3,18 +3,66 @@ export interface BackgroundTaskState {
     waiting: boolean;
 }
 export type BackgroundTaskChangeCallback = (state: BackgroundTaskState) => void;
+/**
+ * Launch acknowledgements the engine writes into a tool_result when the call
+ * turned into a background task. The request-side `run_in_background` flag is
+ * NOT a reliable signal: the engine may decide on its own to background a
+ * subagent (feature-gated async-by-default agents, auto-background after a
+ * timeout, SendMessage resuming an idle agent). The tool RESULT is the single
+ * source of truth for "this call is now running in the background".
+ *
+ * Strings verified against the bundled CLI 0.3.191 and real session JSONL.
+ */
+export declare const BACKGROUND_LAUNCH_MARKERS: readonly string[];
+/**
+ * Tools whose results can legitimately BE a background-launch ack. Every other
+ * tool can only QUOTE the marker text — e.g. Read/Grep over this very file, or
+ * a test fixture — never produce it as a real launch confirmation. 'Task' is
+ * the pre-rename name of the 'Agent' tool (older bundled CLIs).
+ */
+export declare const BACKGROUND_CAPABLE_TOOLS: ReadonlySet<string>;
+/**
+ * A real launch ack carries its marker on the FIRST line of the result
+ * (verified against real session JSONL: agent/bash acks start with the marker;
+ * the SendMessage resume ack is single-line JSON). A file-read or grep result
+ * that merely CONTAINS the marker has it buried mid-content.
+ */
+export declare function isBackgroundLaunchAck(content: string): boolean;
 export declare class BackgroundTaskTracker {
-    private pendingCount;
+    private pendingIds;
+    /** tool_use_id → tool name, recorded for every call — consulted on the
+     *  result side to reject ack lookalikes from tools that cannot background. */
+    private toolNames;
     private _mainResponseEnded;
     private onChange?;
     constructor(onChange?: BackgroundTaskChangeCallback);
-    trackToolUse(input: unknown): void;
-    trackTaskDone(): void;
+    /** Request-side registration: the model explicitly asked for background. */
+    trackToolUse(toolUseId: string, input: unknown, toolName?: string): void;
+    /**
+     * Response-side registration/resolution — the authoritative signal.
+     *
+     * - Result carries a background-launch ack → the call IS a background task,
+     *   regardless of what the request said. Register (idempotent). Only tools
+     *   that can actually background are eligible — a Read/Grep result quoting
+     *   the marker text (source files, test fixtures, docs) must not register.
+     *   Unknown names stay eligible (fail-open): tool_use always precedes
+     *   tool_result on every feed, so a miss means a real ack, not a quote.
+     * - Result carries anything else for an id we thought was backgrounded →
+     *   the call resolved synchronously after all (launch failure, foreground
+     *   completion). Unregister so the turn does not wait for a notification
+     *   that will never come.
+     */
+    trackToolResult(toolUseId: string, content: string): void;
+    /** SDK-engine stream signal: system/task_started announces every background launch. */
+    trackTaskStarted(toolUseId?: string): void;
+    trackTaskDone(toolUseId?: string): void;
+    hasPending(toolUseId: string): boolean;
     markMainEnded(): void;
     get mainResponseEnded(): boolean;
     get isWaiting(): boolean;
     get isFullyDone(): boolean;
     get pending(): number;
+    get pendingToolUseIds(): ReadonlySet<string>;
     private notify;
 }
 //# sourceMappingURL=backgroundTaskTracker.d.ts.map

package/packages/server/dist/utils/backgroundTaskTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backgroundTaskTracker.d.ts","sourceRoot":"","sources":["../../src/utils/backgroundTaskTracker.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAEhF,qBAAa,qBAAqB;IAChC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,CAA+B;gBAEpC,QAAQ,CAAC,EAAE,4BAA4B;IAInD,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAWlC,aAAa,IAAI,IAAI;IAKrB,aAAa,IAAI,IAAI;IAKrB,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,OAAO,CAAC,MAAM;CAGf"}
+{"version":3,"file":"backgroundTaskTracker.d.ts","sourceRoot":"","sources":["../../src/utils/backgroundTaskTracker.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAatD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAMvD,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,UAAU,CAAqB;IACvC;kFAC8E;IAC9E,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,CAA+B;gBAEpC,QAAQ,CAAC,EAAE,4BAA4B;IAInD,4EAA4E;IAC5E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAcxE;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAczD,uFAAuF;IACvF,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ1C,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAWvC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAItC,aAAa,IAAI,IAAI;IAKrB,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,iBAAiB,IAAI,WAAW,CAAC,MAAM,CAAC,CAE3C;IAED,OAAO,CAAC,MAAM;CAGf"}

package/packages/server/dist/utils/backgroundTaskTracker.js

@@ -1,22 +1,127 @@
+/**
+ * Launch acknowledgements the engine writes into a tool_result when the call
+ * turned into a background task. The request-side `run_in_background` flag is
+ * NOT a reliable signal: the engine may decide on its own to background a
+ * subagent (feature-gated async-by-default agents, auto-background after a
+ * timeout, SendMessage resuming an idle agent). The tool RESULT is the single
+ * source of truth for "this call is now running in the background".
+ *
+ * Strings verified against the bundled CLI 0.3.191 and real session JSONL.
+ */
+export const BACKGROUND_LAUNCH_MARKERS = [
+    // Bash / PowerShell run_in_background launch ack
+    'Command running in background with ID:',
+    // Interactive TUI: user pressed the background keybind mid-command (CLI engine mirror)
+    'Command was manually backgrounded by user with ID:',
+    // Agent tool async launch — explicit flag, `background: true` frontmatter,
+    // or the engine's async-by-default feature gate
+    'Async agent launched successfully',
+    // Agent tool with isolation: 'remote'
+    'Cloud agent launched.',
+    // SendMessage re-engaging an idle background agent (produces a NEW
+    // task-notification bound to the SendMessage call's tool_use_id)
+    'resumed from transcript in the background with your message',
+];
+/**
+ * Tools whose results can legitimately BE a background-launch ack. Every other
+ * tool can only QUOTE the marker text — e.g. Read/Grep over this very file, or
+ * a test fixture — never produce it as a real launch confirmation. 'Task' is
+ * the pre-rename name of the 'Agent' tool (older bundled CLIs).
+ */
+export const BACKGROUND_CAPABLE_TOOLS = new Set([
+    'Bash',
+    'PowerShell',
+    'Agent',
+    'Task',
+    'SendMessage',
+]);
+/**
+ * A real launch ack carries its marker on the FIRST line of the result
+ * (verified against real session JSONL: agent/bash acks start with the marker;
+ * the SendMessage resume ack is single-line JSON). A file-read or grep result
+ * that merely CONTAINS the marker has it buried mid-content.
+ */
+export function isBackgroundLaunchAck(content) {
+    const trimmed = content.trimStart();
+    const nl = trimmed.indexOf('\n');
+    const firstLine = nl === -1 ? trimmed : trimmed.slice(0, nl);
+    return BACKGROUND_LAUNCH_MARKERS.some((m) => firstLine.includes(m));
+}
 export class BackgroundTaskTracker {
-    pendingCount = 0;
+    pendingIds = new Set();
+    /** tool_use_id → tool name, recorded for every call — consulted on the
+     *  result side to reject ack lookalikes from tools that cannot background. */
+    toolNames = new Map();
     _mainResponseEnded = false;
     onChange;
     constructor(onChange) {
         this.onChange = onChange;
     }
-    trackToolUse(input) {
+    /** Request-side registration: the model explicitly asked for background. */
+    trackToolUse(toolUseId, input, toolName) {
+        if (toolName)
+            this.toolNames.set(toolUseId, toolName);
         if (typeof input === 'object' &&
             input !== null &&
             input.run_in_background === true) {
-            this.pendingCount++;
+            if (!this.pendingIds.has(toolUseId)) {
+                this.pendingIds.add(toolUseId);
+                this.notify();
+            }
+        }
+    }
+    /**
+     * Response-side registration/resolution — the authoritative signal.
+     *
+     * - Result carries a background-launch ack → the call IS a background task,
+     *   regardless of what the request said. Register (idempotent). Only tools
+     *   that can actually background are eligible — a Read/Grep result quoting
+     *   the marker text (source files, test fixtures, docs) must not register.
+     *   Unknown names stay eligible (fail-open): tool_use always precedes
+     *   tool_result on every feed, so a miss means a real ack, not a quote.
+     * - Result carries anything else for an id we thought was backgrounded →
+     *   the call resolved synchronously after all (launch failure, foreground
+     *   completion). Unregister so the turn does not wait for a notification
+     *   that will never come.
+     */
+    trackToolResult(toolUseId, content) {
+        const name = this.toolNames.get(toolUseId);
+        const ackEligible = name === undefined || BACKGROUND_CAPABLE_TOOLS.has(name);
+        if (ackEligible && isBackgroundLaunchAck(content)) {
+            if (!this.pendingIds.has(toolUseId)) {
+                this.pendingIds.add(toolUseId);
+                this.notify();
+            }
+        }
+        else if (this.pendingIds.has(toolUseId)) {
+            this.pendingIds.delete(toolUseId);
             this.notify();
         }
     }
-    trackTaskDone() {
-        this.pendingCount = Math.max(0, this.pendingCount - 1);
+    /** SDK-engine stream signal: system/task_started announces every background launch. */
+    trackTaskStarted(toolUseId) {
+        if (!toolUseId)
+            return;
+        if (!this.pendingIds.has(toolUseId)) {
+            this.pendingIds.add(toolUseId);
+            this.notify();
+        }
+    }
+    trackTaskDone(toolUseId) {
+        if (toolUseId) {
+            this.pendingIds.delete(toolUseId);
+        }
+        else if (this.pendingIds.size > 0) {
+            // Fallback: no id provided — remove one arbitrary entry (legacy compat)
+            const first = this.pendingIds.values().next().value;
+            if (first)
+                this.pendingIds.delete(first);
+        }
         this.notify();
     }
+    hasPending(toolUseId) {
+        return this.pendingIds.has(toolUseId);
+    }
     markMainEnded() {
         this._mainResponseEnded = true;
         this.notify();
@@ -25,16 +130,19 @@ export class BackgroundTaskTracker {
         return this._mainResponseEnded;
     }
     get isWaiting() {
-        return this._mainResponseEnded && this.pendingCount > 0;
+        return this._mainResponseEnded && this.pendingIds.size > 0;
     }
     get isFullyDone() {
-        return this._mainResponseEnded && this.pendingCount === 0;
+        return this._mainResponseEnded && this.pendingIds.size === 0;
     }
     get pending() {
-        return this.pendingCount;
+        return this.pendingIds.size;
+    }
+    get pendingToolUseIds() {
+        return this.pendingIds;
     }
     notify() {
-        this.onChange?.({ pending: this.pendingCount, waiting: this.isWaiting });
+        this.onChange?.({ pending: this.pendingIds.size, waiting: this.isWaiting });
     }
 }
 //# sourceMappingURL=backgroundTaskTracker.js.map

package/packages/server/dist/utils/backgroundTaskTracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"backgroundTaskTracker.js","sourceRoot":"","sources":["../../src/utils/backgroundTaskTracker.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,qBAAqB;IACxB,YAAY,GAAG,CAAC,CAAC;IACjB,kBAAkB,GAAG,KAAK,CAAC;IAC3B,QAAQ,CAAgC;IAEhD,YAAY,QAAuC;QACjD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,YAAY,CAAC,KAAc;QACzB,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACb,KAAyC,CAAC,iBAAiB,KAAK,IAAI,EACrE,CAAC;YACD,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,aAAa;QACX,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACjC,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,YAAY,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAEO,MAAM;QACZ,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3E,CAAC;CACF"}
+{"version":3,"file":"backgroundTaskTracker.js","sourceRoot":"","sources":["../../src/utils/backgroundTaskTracker.ts"],"names":[],"mappings":"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"}

package/packages/server/dist/utils/backgroundToolGuard.d.ts

@@ -0,0 +1,26 @@
+import type { PermissionResult } from '@anthropic-ai/claude-agent-sdk';
+/**
+ * Hammoc invariant: an `end_turn` signal must mean "every piece of work this turn
+ * started is finished". A tool-level `run_in_background: true` Bash call breaks
+ * that — the shell detaches, the turn ends while the process is still running, and
+ * the eventual completion notification has no open turn to land in. The fallout is
+ * the same in every engine: queue/chain advance to the next item too early, the
+ * session shows "done" while work is still live, and "완료" notifications fire
+ * prematurely. SDK and CLI engines diverge on how (or whether) they cope, so rather
+ * than rely on per-engine grace timers we forbid the background flag outright at the
+ * shared permission gate — keeping `end_turn = done` true for both engines.
+ *
+ * Long-lived processes (dev servers, test launchers) are still possible: detach them
+ * at the OS level (`Start-Process` on Windows, `nohup … &` elsewhere) so the shell
+ * call returns immediately and is never tracked as a pending turn task, then manage
+ * them by PID. That path does NOT set the tool flag, so it falls through this guard.
+ *
+ * Returns a deny `PermissionResult` when the call must be blocked, or `null` to let
+ * the normal permission flow continue. Intentionally narrow: only the `Bash` tool's
+ * background flag is blocked — background sub-agents (Task/Agent) are out of scope.
+ *
+ * Placed at the very TOP of every `canUseTool` (before bypass auto-approve branches)
+ * so the block holds across all permission modes that route through the callback.
+ */
+export declare function denyBackgroundBash(toolName: string, input: unknown): PermissionResult | null;
+//# sourceMappingURL=backgroundToolGuard.d.ts.map