larkin 0.4.9 → 0.4.10

package/dist/runtime/pi-subagents-notification.mjs

@@ -0,0 +1,161 @@
+function escapeXml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function extractTag(content, tagName) {
+    const match = new RegExp(`<${tagName}>([\\s\\S]*?)</${tagName}>`).exec(content);
+    return match ? match[1].trim() : null;
+}
+/**
+ * Pi subagents emit terminal <status> as Done or a display label
+ * (Error: ..., Aborted (...), Stopped, Wrapped up (turn limit)).
+ * Raw tokens completed/error/aborted/stopped/steered/turn-limit are also accepted.
+ */
+const TERMINAL_STATUS_TOKENS = new Set([
+    "done",
+    "completed",
+    "error",
+    "aborted",
+    "stopped",
+    "steered",
+    "turn-limit",
+    "turn_limit",
+]);
+export function isCanonicalTerminalPiSubagentStatus(status) {
+    const normalized = status.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    if (TERMINAL_STATUS_TOKENS.has(normalized))
+        return true;
+    if (normalized.startsWith("error:") || normalized.startsWith("error "))
+        return true;
+    if (normalized.startsWith("aborted"))
+        return true;
+    if (normalized.startsWith("stopped"))
+        return true;
+    if (normalized.includes("turn limit") || normalized.includes("turn-limit") || normalized.includes("turn_limit")) {
+        return true;
+    }
+    if (normalized.includes("steered"))
+        return true;
+    return false;
+}
+function parseTaskNotificationBlock(block) {
+    const taskId = extractTag(block, "task-id");
+    const status = extractTag(block, "status");
+    const summary = extractTag(block, "summary");
+    const result = extractTag(block, "result");
+    if (!taskId || !status || !summary || !result)
+        return null;
+    if (!isCanonicalTerminalPiSubagentStatus(status))
+        return null;
+    return {
+        taskId,
+        toolUseId: extractTag(block, "tool-use-id") ?? undefined,
+        outputFile: extractTag(block, "output-file") ?? undefined,
+        status,
+        summary,
+        result,
+    };
+}
+function parseCanonicalNotificationContent(content) {
+    const blocks = [...content.matchAll(/<task-notification>([\s\S]*?)<\/task-notification>/g)]
+        .map((match) => match[1]);
+    if (blocks.length === 0)
+        return null;
+    const seen = new Set();
+    const notifications = [];
+    for (const block of blocks) {
+        const parsed = parseTaskNotificationBlock(block);
+        if (!parsed || seen.has(parsed.taskId))
+            continue;
+        seen.add(parsed.taskId);
+        notifications.push(parsed);
+    }
+    if (notifications.length === 0)
+        return null;
+    const taskIds = notifications.map((notification) => notification.taskId);
+    return { taskIds, notifications, content, key: taskIds.join("|") };
+}
+function collectCandidateContents(node, found = new Set()) {
+    const candidates = [];
+    const visit = (value) => {
+        if (value === null || value === undefined)
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (typeof value !== "object")
+            return;
+        const record = value;
+        if (record.customType === "subagent-notification" && typeof record.content === "string") {
+            if (!found.has(record.content)) {
+                found.add(record.content);
+                candidates.push(record.content);
+            }
+        }
+        else if (Array.isArray(record.content)) {
+            visit(record.content);
+        }
+        if (Array.isArray(record.messages))
+            visit(record.messages);
+        if (Array.isArray(record.parts))
+            visit(record.parts);
+    };
+    visit(node);
+    return candidates;
+}
+export function buildCanonicalPiSubagentNotificationContent(options) {
+    const status = options.status ?? "Done";
+    const summary = options.summary ?? `Agent ${JSON.stringify("Fixture")} completed`;
+    const result = options.result ?? "Fixture result.";
+    const totalTokens = options.totalTokens ?? 12;
+    const toolUses = options.toolUses ?? 1;
+    const durationMs = options.durationMs ?? 34;
+    return [
+        "<task-notification>",
+        `<task-id>${escapeXml(options.taskId)}</task-id>`,
+        options.toolUseId ? `<tool-use-id>${escapeXml(options.toolUseId)}</tool-use-id>` : null,
+        options.outputFile ? `<output-file>${escapeXml(options.outputFile)}</output-file>` : null,
+        `<status>${escapeXml(status)}</status>`,
+        `<summary>${escapeXml(summary)}</summary>`,
+        `<result>${escapeXml(result)}</result>`,
+        `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${toolUses}</tool_uses><duration_ms>${durationMs}</duration_ms></usage>`,
+        "</task-notification>",
+    ].filter(Boolean).join("\n");
+}
+export function buildCanonicalPiSubagentAssistantMessage(options) {
+    return {
+        role: "assistant",
+        content: [{
+                type: "custom",
+                customType: "subagent-notification",
+                content: buildCanonicalPiSubagentNotificationContent(options),
+            }],
+    };
+}
+export function extractCanonicalPiSubagentNotification(messages) {
+    const seen = new Set();
+    const notifications = [];
+    const contents = [];
+    for (const content of collectCandidateContents(messages)) {
+        const parsed = parseCanonicalNotificationContent(content);
+        if (!parsed)
+            continue;
+        contents.push(parsed.content);
+        for (const notification of parsed.notifications) {
+            if (seen.has(notification.taskId))
+                continue;
+            seen.add(notification.taskId);
+            notifications.push(notification);
+        }
+    }
+    if (notifications.length === 0)
+        return null;
+    const taskIds = notifications.map((notification) => notification.taskId);
+    return { taskIds, notifications, content: contents.join("\n"), key: taskIds.join("|") };
+}
+export function extractCanonicalPiSubagentCompletionKeyFromMessages(messages) {
+    return extractCanonicalPiSubagentNotification(messages)?.key ?? null;
+}

package/dist/runtime/runtime-adapters.mjs

@@ -10,6 +10,7 @@ import { BUNDLED_PI_VERSION, piAgentDirectory } from "./pi-provider-config.mjs";
 import { recordPiRuntimeArtifactProvenance } from "./pi-artifact-provenance.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 import { resolvePiSubagentExtensionArg } from "./pi-subagent-injection.mjs";
+import { extractCanonicalPiSubagentCompletionKeyFromMessages } from "./pi-subagents-notification.mjs";
 import { resolvePiBashTimeoutExtensionArg } from "./pi-bash-timeout-injection.mjs";
 import { classifyRuntimePrerequisite, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
 import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, } from "./provider-error-classifier.mjs";
@@ -451,6 +452,8 @@ class PiSession extends EventSession {
     observedSubmitEpochs = new Set();
     observedAcceptedEpochs = new Set();
     observedCompletedEpochs = new Set();
+    observedBackgroundCompletionKeys = new Set();
+    pendingUnownedCompletionKeys = new Set();
     observedAgentEndEpochs = new Set();
     firstOutputObserved = false;
     toolCallOpen = false;
@@ -551,6 +554,8 @@ class PiSession extends EventSession {
             this.observedSubmitEpochs.clear();
             this.observedAcceptedEpochs.clear();
             this.observedCompletedEpochs.clear();
+            this.observedBackgroundCompletionKeys.clear();
+            this.pendingUnownedCompletionKeys.clear();
             this.observedAgentEndEpochs.clear();
             this.activeEpoch = null;
             this.settleArmedEpoch = null;
@@ -600,11 +605,25 @@ class PiSession extends EventSession {
                 this.observedCompletedEpochs.add(this.activeEpoch);
                 this.emitObservation("completed");
             }
+            const completionNotificationKey = extractCanonicalPiSubagentCompletionKeyFromMessages(event.messages);
+            if (completionNotificationKey
+                && this.activeEpoch === null
+                && !this.observedBackgroundCompletionKeys.has(completionNotificationKey)) {
+                // agent_end can still have an active Pi session. Prompting before
+                // unowned agent_settled is rejected as "Agent is already processing".
+                this.pendingUnownedCompletionKeys.add(completionNotificationKey);
+            }
         }
         else if (event?.type === "agent_settled") {
             const epoch = this.activeEpoch;
-            if (epoch === null || this.settleArmedEpoch !== epoch)
+            if (epoch === null) {
+                this.flushPendingUnownedCompletions();
+                return;
+            }
+            if (this.settleArmedEpoch !== epoch) {
+                this.flushPendingUnownedCompletions();
                 return;
+            }
             this.activeEpoch = null;
             this.settleArmedEpoch = null;
             const error = this.finalAssistantError;
@@ -645,6 +664,7 @@ class PiSession extends EventSession {
             this.observedAcceptedEpochs.delete(epoch);
             this.observedCompletedEpochs.delete(epoch);
             this.observedAgentEndEpochs.delete(epoch);
+            this.flushPendingUnownedCompletions();
         }
         else if (event?.type === "tool_execution_start") {
             if (!this.firstOutputObserved) {
@@ -672,6 +692,15 @@ class PiSession extends EventSession {
             this.emit({ type: "activity", activity: kind, text: String(event.assistantMessageEvent.delta) });
         }
     }
+    flushPendingUnownedCompletions() {
+        for (const completionKey of this.pendingUnownedCompletionKeys) {
+            if (this.observedBackgroundCompletionKeys.has(completionKey))
+                continue;
+            this.observedBackgroundCompletionKeys.add(completionKey);
+            this.emitObservation("completed", { completionKey });
+        }
+        this.pendingUnownedCompletionKeys.clear();
+    }
     emitObservation(phase, fields = {}) {
         const inputId = this.oldestOwnedInput();
         const observation = { type: "runtime-observation", runtime: "pi",
@@ -681,6 +710,8 @@ class PiSession extends EventSession {
             Object.defineProperty(observation, "sessionId", { value: this.sessionId, enumerable: false });
         if (inputId)
             Object.defineProperty(observation, "inputId", { value: inputId, enumerable: false });
+        if (fields.completionKey)
+            Object.defineProperty(observation, "completionKey", { value: fields.completionKey, enumerable: false });
         this.emit(observation);
     }
     oldestOwnedInput() {

package/dist/runtime/runtime-host.cjs

@@ -39,6 +39,7 @@ class RuntimeSessionRecoveryError extends Error {
 }
 exports.RuntimeSessionRecoveryError = RuntimeSessionRecoveryError;
 const MAX_DELIVERIES = 2048;
+const BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT = 5;
 const now = () => new Date().toISOString();
 const isActiveDelivery = (status) => ["pending", "submitting", "accepted"].includes(status);
 const REPLAY_FAILURE_CODES = new Set([
@@ -521,6 +522,12 @@ function createRuntimeHost(options) {
                 queueMicrotask(() => { void retryPending(agent); });
             }
             queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
+            // A completion queued during this submit has no turn-end if prompt
+            // rejected/threw before turn-start. Drain now that submitting is clear.
+            if (!agent.busy && !agent.turnInProgress && agent.backgroundCompletionQueue.length > 0
+                && !agent.backgroundCompletionRetryTimer) {
+                scheduleBackgroundCompletionDrain(agent);
+            }
         }
     };
     const retryPending = async (agent) => {
@@ -599,6 +606,210 @@ function createRuntimeHost(options) {
             agent.retryAfterSubmit = true;
         await retryPending(agent);
     };
+    const clearBackgroundCompletionRetryTimer = (agent) => {
+        if (!agent.backgroundCompletionRetryTimer)
+            return;
+        clearTimeout(agent.backgroundCompletionRetryTimer);
+        agent.backgroundCompletionRetryTimer = null;
+    };
+    const scheduleBackgroundCompletionDrain = (agent, delayMs = 0) => {
+        if (agent.stopped)
+            return;
+        if (delayMs > 0) {
+            if (agent.backgroundCompletionRetryTimer)
+                return;
+            agent.backgroundCompletionRetryTimer = setTimeout(() => {
+                agent.backgroundCompletionRetryTimer = null;
+                if (agent.stopped)
+                    return;
+                void drainBackgroundCompletionQueue(agent);
+            }, delayMs);
+            agent.backgroundCompletionRetryTimer.unref?.();
+            return;
+        }
+        clearBackgroundCompletionRetryTimer(agent);
+        queueMicrotask(() => { void drainBackgroundCompletionQueue(agent); });
+    };
+    const dropBackgroundCompletion = (agent, completionKey) => {
+        if (!completionKey)
+            return;
+        if (agent.backgroundCompletionQueue[0] === completionKey)
+            agent.backgroundCompletionQueue.shift();
+        else {
+            const index = agent.backgroundCompletionQueue.indexOf(completionKey);
+            if (index >= 0)
+                agent.backgroundCompletionQueue.splice(index, 1);
+        }
+        agent.backgroundCompletionKeys.add(completionKey);
+        if (agent.backgroundCompletionInFlight === completionKey) {
+            agent.backgroundCompletionInFlight = null;
+            agent.backgroundCompletionWakeInputId = null;
+        }
+        agent.backgroundCompletionRejectStreak = 0;
+        clearBackgroundCompletionRetryTimer(agent);
+    };
+    const scheduleBackgroundCompletionRetry = (agent) => {
+        const streak = agent.backgroundCompletionRejectStreak;
+        if (streak < BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT) {
+            scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        const delayedAttempt = streak - BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT;
+        if (delayedAttempt >= retryPolicy.maxAttempts) {
+            const exhausted = agent.backgroundCompletionQueue[0];
+            if (exhausted) {
+                log("background completion wake retries exhausted", exhausted);
+                dropBackgroundCompletion(agent, exhausted);
+            }
+            if (agent.backgroundCompletionQueue.length > 0)
+                scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        const delay = Math.min(retryPolicy.maxDelayMs, retryPolicy.baseDelayMs * 2 ** delayedAttempt);
+        scheduleBackgroundCompletionDrain(agent, delay);
+    };
+    const isPersistentBackgroundWakeFailure = (event) => {
+        if (!event)
+            return false;
+        const category = event.errorCategory;
+        if (category === "auth" || category === "billing" || category === "quota")
+            return true;
+        return category === "provider" && event.retryable === false;
+    };
+    const failBackgroundCompletionWake = (agent, event) => {
+        const completionKey = agent.backgroundCompletionInFlight ?? agent.backgroundCompletionQueue[0];
+        if (!completionKey)
+            return;
+        rearmBackgroundCompletion(agent, completionKey);
+        if (isPersistentBackgroundWakeFailure(event)) {
+            log("background completion wake dropped", event?.errorCategory ?? "persistent");
+            dropBackgroundCompletion(agent, completionKey);
+            if (agent.backgroundCompletionQueue.length > 0)
+                scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        agent.backgroundCompletionRejectStreak += 1;
+        scheduleBackgroundCompletionRetry(agent);
+    };
+    const rearmBackgroundCompletion = (agent, completionKey = agent.backgroundCompletionInFlight) => {
+        if (!completionKey)
+            return;
+        agent.backgroundCompletionKeys.delete(completionKey);
+        if (agent.backgroundCompletionInFlight === completionKey) {
+            agent.backgroundCompletionInFlight = null;
+            agent.backgroundCompletionWakeInputId = null;
+        }
+        if (!agent.backgroundCompletionQueue.includes(completionKey)) {
+            agent.backgroundCompletionQueue.unshift(completionKey);
+        }
+    };
+    const commitBackgroundCompletion = (agent) => {
+        const completionKey = agent.backgroundCompletionInFlight;
+        if (!completionKey)
+            return;
+        if (agent.backgroundCompletionQueue[0] === completionKey)
+            agent.backgroundCompletionQueue.shift();
+        agent.backgroundCompletionInFlight = null;
+        agent.backgroundCompletionWakeInputId = null;
+        agent.backgroundCompletionRejectStreak = 0;
+        clearBackgroundCompletionRetryTimer(agent);
+    };
+    const wakeOnBackgroundCompletion = async (agent) => {
+        // Caller already reserved submitting/busy so a concurrent idle drain cannot
+        // dequeue another head while ensureSession/prompt yields.
+        try {
+            const session = await ensureSession(agent);
+            if (agent.session !== session || agent.stopped)
+                return { status: "dropped" };
+            const input = options.promptBuilder.buildRuntimeInput("wake", node_crypto_1.default.randomUUID(), { wakeReason: "background subagent completed" });
+            const result = await session.prompt(input);
+            if (agent.session !== session || agent.stopped)
+                return { status: "dropped" };
+            if (result.status === "accepted") {
+                markSessionStable(agent, session);
+                return { status: "accepted", inputId: input.inputId };
+            }
+            agent.busy = false;
+            return { status: "retry" };
+        }
+        catch (error) {
+            agent.busy = false;
+            log("background completion wake failed", error instanceof Error ? error.message : String(error));
+            return { status: "retry" };
+        }
+    };
+    const drainBackgroundCompletionQueue = async (agent) => {
+        if (agent.stopped || agent.busy || agent.turnInProgress || agent.submitting)
+            return;
+        if (agent.backgroundCompletionInFlight || !agent.backgroundCompletionQueue.length)
+            return;
+        clearBackgroundCompletionRetryTimer(agent);
+        const proactive = agent.piProactiveCompaction
+            && agent.piProactiveCompactionGeneration === agent.generation
+            && agent.piProactiveCompactionSession === agent.session
+            ? agent.piProactiveCompaction : null;
+        if (proactive && await proactive === "failed")
+            return;
+        if (agent.adapter.id === "pi" && agent.piProactiveCompactionFailedGeneration === agent.generation)
+            return;
+        if (agent.adapter.id === "pi" && !agent.busy && !agent.turnInProgress && agent.session) {
+            const idleGate = proactivelyCompactPiAtIdle(agent, agent.session);
+            if (idleGate && await idleGate === "failed")
+                return;
+        }
+        if (agent.stopped || agent.busy || agent.turnInProgress || agent.submitting)
+            return;
+        if (agent.backgroundCompletionInFlight || !agent.backgroundCompletionQueue.length)
+            return;
+        agent.submitting = true;
+        agent.busy = true;
+        const completionKey = agent.backgroundCompletionQueue[0];
+        try {
+            const outcome = await wakeOnBackgroundCompletion(agent);
+            if (outcome.status === "accepted") {
+                agent.backgroundCompletionKeys.add(completionKey);
+                agent.backgroundCompletionInFlight = completionKey;
+                agent.backgroundCompletionWakeInputId = outcome.inputId;
+                // Keep the reject streak until the wake turn actually succeeds. An accepted
+                // prompt that later terminal-fails must not reset the bounded retry budget.
+                clearBackgroundCompletionRetryTimer(agent);
+            }
+            else if (outcome.status === "dropped") {
+                if (agent.stopped) {
+                    if (agent.backgroundCompletionQueue[0] === completionKey)
+                        agent.backgroundCompletionQueue.shift();
+                    agent.backgroundCompletionKeys.delete(completionKey);
+                    clearBackgroundCompletionRetryTimer(agent);
+                }
+                else {
+                    rearmBackgroundCompletion(agent, completionKey);
+                    agent.busy = false;
+                }
+            }
+            else {
+                agent.busy = false;
+                agent.backgroundCompletionRejectStreak += 1;
+                // Leave the item queued+deduped. Immediate microtask retries cover a
+                // brief reject; after that a bounded timer still drains because Pi will
+                // not re-emit the same completion.
+                scheduleBackgroundCompletionRetry(agent);
+            }
+        }
+        finally {
+            agent.submitting = false;
+        }
+    };
+    const noteBackgroundCompletion = (agent, completionKey) => {
+        if (agent.backgroundCompletionKeys.has(completionKey))
+            return;
+        agent.backgroundCompletionKeys.add(completionKey);
+        if (!agent.backgroundCompletionQueue.includes(completionKey)) {
+            agent.backgroundCompletionQueue.push(completionKey);
+        }
+        if (!agent.busy && !agent.turnInProgress && !agent.submitting && !agent.backgroundCompletionInFlight) {
+            scheduleBackgroundCompletionDrain(agent);
+        }
+    };
     const scheduleRecreate = (agent, reason) => {
         if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
             return;
@@ -621,6 +832,8 @@ function createRuntimeHost(options) {
                 if (proactive && await proactive === "failed")
                     return;
                 await retryPending(agent);
+                if (agent.backgroundCompletionQueue.length > 0)
+                    scheduleBackgroundCompletionDrain(agent);
             }).catch((error) => {
                 const readiness = error instanceof runtime_readiness_js_1.RuntimePrerequisiteError ? error.readiness
                     : (0, runtime_readiness_js_1.classifyRuntimePrerequisite)(agent.adapter.id, error);
@@ -643,6 +856,7 @@ function createRuntimeHost(options) {
         agent.busy = false;
         agent.submitting = false;
         agent.generation += 1;
+        rearmBackgroundCompletion(agent);
         agent.recreateReason = reason;
         if (agent.stabilityTimer)
             clearTimeout(agent.stabilityTimer);
@@ -663,6 +877,7 @@ function createRuntimeHost(options) {
         agent.busy = false;
         agent.submitting = false;
         agent.generation += 1;
+        rearmBackgroundCompletion(agent);
         if (agent.stabilityTimer)
             clearTimeout(agent.stabilityTimer);
         agent.stabilityTimer = null;
@@ -919,6 +1134,15 @@ function createRuntimeHost(options) {
             agent.busy = false;
             emit({ type: "activity", agentId: agent.config.agentId, activity: "idle", activityKind: "idle", detailKind: "turn_ended" });
             reconcileAcceptedAtTurnEnd(agent);
+            if (agent.backgroundCompletionInFlight) {
+                if (agent.turnHadFailure)
+                    failBackgroundCompletionWake(agent);
+                else
+                    commitBackgroundCompletion(agent);
+            }
+            if (agent.backgroundCompletionQueue.length > 0 && !agent.backgroundCompletionRetryTimer) {
+                scheduleBackgroundCompletionDrain(agent);
+            }
             telemetry?.runtimeEvent(agent.config.agentId, event);
             if (recoveredAuthentication) {
                 agent.authFailureActive = false;
@@ -938,12 +1162,24 @@ function createRuntimeHost(options) {
             });
             queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
         }
+        else if (event.type === "runtime-observation") {
+            if (event.phase === "completed" && typeof event.completionKey === "string") {
+                noteBackgroundCompletion(agent, event.completionKey);
+            }
+        }
         else if (event.type === "activity") {
             if (agent.turnInProgress && event.activity !== "internal")
                 agent.turnHadAuthenticatedOutput = true;
             emit({ type: "activity", agentId: agent.config.agentId, activity: event.activity, activityKind: event.activity });
         }
         else if (event.type === "input-error") {
+            if (agent.backgroundCompletionInFlight
+                && (!event.inputId || !agent.backgroundCompletionWakeInputId
+                    || event.inputId === agent.backgroundCompletionWakeInputId)
+                && event.willRetry !== true) {
+                agent.turnHadFailure = true;
+                failBackgroundCompletionWake(agent, event);
+            }
             const record = event.inputId
                 ? agent.records.get(event.inputId) ?? [...agent.records.values()].find((candidate) => candidate.input.inputId === event.inputId)
                 : undefined;
@@ -1270,10 +1506,13 @@ function createRuntimeHost(options) {
                         clearTimeout(previous.retryTimer);
                     if (previous.stabilityTimer)
                         clearTimeout(previous.stabilityTimer);
+                    if (previous.backgroundCompletionRetryTimer)
+                        clearTimeout(previous.backgroundCompletionRetryTimer);
                     const candidate = {
                         ...previous, config, adapter, session, launchId: node_crypto_1.default.randomUUID(), busy: false, submitting: false,
                         starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
                         recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
+                        backgroundCompletionRetryTimer: null,
                         disabledReason: null, configurationRecovery: null,
                         readiness: previous.authFailureActive ? previous.readiness : readiness,
                     };
@@ -1290,6 +1529,11 @@ function createRuntimeHost(options) {
                     if (!candidate.authFailureActive) {
                         emit({ type: "agent-status", agentId: config.agentId, status: "active", readiness: candidate.readiness ?? readiness });
                     }
+                    // Commit clears any inherited backoff timer; reschedule so a queued
+                    // completion still drains on the new session.
+                    if (candidate.backgroundCompletionQueue.length > 0) {
+                        scheduleBackgroundCompletionDrain(candidate);
+                    }
                     await previous.session?.close("runtime candidate committed")
                         .catch((error) => log("previous runtime close after candidate commit failed", String(error)));
                 },
@@ -1622,7 +1866,10 @@ function createRuntimeHost(options) {
                     piProactiveCompaction: null, piProactiveCompactionGeneration: null, piProactiveCompactionSession: null,
                     piProactiveCompactionFailedGeneration: null, readiness: null,
                     turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false,
-                    promotedInboxUpdateIds: new Set() };
+                    promotedInboxUpdateIds: new Set(),
+                    backgroundCompletionQueue: [], backgroundCompletionKeys: new Set(),
+                    backgroundCompletionInFlight: null, backgroundCompletionWakeInputId: null,
+                    backgroundCompletionRejectStreak: 0, backgroundCompletionRetryTimer: null };
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {
@@ -1773,6 +2020,8 @@ function createRuntimeHost(options) {
                 clearTimeout(agent.retryTimer);
             if (agent.stabilityTimer)
                 clearTimeout(agent.stabilityTimer);
+            if (agent.backgroundCompletionRetryTimer)
+                clearTimeout(agent.backgroundCompletionRetryTimer);
             if (agent.busy)
                 await agent.session?.cancel(reason);
             await agent.session?.close(reason);

package/dist/runtime/runtime-host.mjs

@@ -30,6 +30,7 @@ export class RuntimeSessionRecoveryError extends Error {
     }
 }
 const MAX_DELIVERIES = 2048;
+const BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT = 5;
 const now = () => new Date().toISOString();
 const isActiveDelivery = (status) => ["pending", "submitting", "accepted"].includes(status);
 const REPLAY_FAILURE_CODES = new Set([
@@ -512,6 +513,12 @@ export function createRuntimeHost(options) {
                 queueMicrotask(() => { void retryPending(agent); });
             }
             queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
+            // A completion queued during this submit has no turn-end if prompt
+            // rejected/threw before turn-start. Drain now that submitting is clear.
+            if (!agent.busy && !agent.turnInProgress && agent.backgroundCompletionQueue.length > 0
+                && !agent.backgroundCompletionRetryTimer) {
+                scheduleBackgroundCompletionDrain(agent);
+            }
         }
     };
     const retryPending = async (agent) => {
@@ -590,6 +597,210 @@ export function createRuntimeHost(options) {
             agent.retryAfterSubmit = true;
         await retryPending(agent);
     };
+    const clearBackgroundCompletionRetryTimer = (agent) => {
+        if (!agent.backgroundCompletionRetryTimer)
+            return;
+        clearTimeout(agent.backgroundCompletionRetryTimer);
+        agent.backgroundCompletionRetryTimer = null;
+    };
+    const scheduleBackgroundCompletionDrain = (agent, delayMs = 0) => {
+        if (agent.stopped)
+            return;
+        if (delayMs > 0) {
+            if (agent.backgroundCompletionRetryTimer)
+                return;
+            agent.backgroundCompletionRetryTimer = setTimeout(() => {
+                agent.backgroundCompletionRetryTimer = null;
+                if (agent.stopped)
+                    return;
+                void drainBackgroundCompletionQueue(agent);
+            }, delayMs);
+            agent.backgroundCompletionRetryTimer.unref?.();
+            return;
+        }
+        clearBackgroundCompletionRetryTimer(agent);
+        queueMicrotask(() => { void drainBackgroundCompletionQueue(agent); });
+    };
+    const dropBackgroundCompletion = (agent, completionKey) => {
+        if (!completionKey)
+            return;
+        if (agent.backgroundCompletionQueue[0] === completionKey)
+            agent.backgroundCompletionQueue.shift();
+        else {
+            const index = agent.backgroundCompletionQueue.indexOf(completionKey);
+            if (index >= 0)
+                agent.backgroundCompletionQueue.splice(index, 1);
+        }
+        agent.backgroundCompletionKeys.add(completionKey);
+        if (agent.backgroundCompletionInFlight === completionKey) {
+            agent.backgroundCompletionInFlight = null;
+            agent.backgroundCompletionWakeInputId = null;
+        }
+        agent.backgroundCompletionRejectStreak = 0;
+        clearBackgroundCompletionRetryTimer(agent);
+    };
+    const scheduleBackgroundCompletionRetry = (agent) => {
+        const streak = agent.backgroundCompletionRejectStreak;
+        if (streak < BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT) {
+            scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        const delayedAttempt = streak - BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT;
+        if (delayedAttempt >= retryPolicy.maxAttempts) {
+            const exhausted = agent.backgroundCompletionQueue[0];
+            if (exhausted) {
+                log("background completion wake retries exhausted", exhausted);
+                dropBackgroundCompletion(agent, exhausted);
+            }
+            if (agent.backgroundCompletionQueue.length > 0)
+                scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        const delay = Math.min(retryPolicy.maxDelayMs, retryPolicy.baseDelayMs * 2 ** delayedAttempt);
+        scheduleBackgroundCompletionDrain(agent, delay);
+    };
+    const isPersistentBackgroundWakeFailure = (event) => {
+        if (!event)
+            return false;
+        const category = event.errorCategory;
+        if (category === "auth" || category === "billing" || category === "quota")
+            return true;
+        return category === "provider" && event.retryable === false;
+    };
+    const failBackgroundCompletionWake = (agent, event) => {
+        const completionKey = agent.backgroundCompletionInFlight ?? agent.backgroundCompletionQueue[0];
+        if (!completionKey)
+            return;
+        rearmBackgroundCompletion(agent, completionKey);
+        if (isPersistentBackgroundWakeFailure(event)) {
+            log("background completion wake dropped", event?.errorCategory ?? "persistent");
+            dropBackgroundCompletion(agent, completionKey);
+            if (agent.backgroundCompletionQueue.length > 0)
+                scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        agent.backgroundCompletionRejectStreak += 1;
+        scheduleBackgroundCompletionRetry(agent);
+    };
+    const rearmBackgroundCompletion = (agent, completionKey = agent.backgroundCompletionInFlight) => {
+        if (!completionKey)
+            return;
+        agent.backgroundCompletionKeys.delete(completionKey);
+        if (agent.backgroundCompletionInFlight === completionKey) {
+            agent.backgroundCompletionInFlight = null;
+            agent.backgroundCompletionWakeInputId = null;
+        }
+        if (!agent.backgroundCompletionQueue.includes(completionKey)) {
+            agent.backgroundCompletionQueue.unshift(completionKey);
+        }
+    };
+    const commitBackgroundCompletion = (agent) => {
+        const completionKey = agent.backgroundCompletionInFlight;
+        if (!completionKey)
+            return;
+        if (agent.backgroundCompletionQueue[0] === completionKey)
+            agent.backgroundCompletionQueue.shift();
+        agent.backgroundCompletionInFlight = null;
+        agent.backgroundCompletionWakeInputId = null;
+        agent.backgroundCompletionRejectStreak = 0;
+        clearBackgroundCompletionRetryTimer(agent);
+    };
+    const wakeOnBackgroundCompletion = async (agent) => {
+        // Caller already reserved submitting/busy so a concurrent idle drain cannot
+        // dequeue another head while ensureSession/prompt yields.
+        try {
+            const session = await ensureSession(agent);
+            if (agent.session !== session || agent.stopped)
+                return { status: "dropped" };
+            const input = options.promptBuilder.buildRuntimeInput("wake", crypto.randomUUID(), { wakeReason: "background subagent completed" });
+            const result = await session.prompt(input);
+            if (agent.session !== session || agent.stopped)
+                return { status: "dropped" };
+            if (result.status === "accepted") {
+                markSessionStable(agent, session);
+                return { status: "accepted", inputId: input.inputId };
+            }
+            agent.busy = false;
+            return { status: "retry" };
+        }
+        catch (error) {
+            agent.busy = false;
+            log("background completion wake failed", error instanceof Error ? error.message : String(error));
+            return { status: "retry" };
+        }
+    };
+    const drainBackgroundCompletionQueue = async (agent) => {
+        if (agent.stopped || agent.busy || agent.turnInProgress || agent.submitting)
+            return;
+        if (agent.backgroundCompletionInFlight || !agent.backgroundCompletionQueue.length)
+            return;
+        clearBackgroundCompletionRetryTimer(agent);
+        const proactive = agent.piProactiveCompaction
+            && agent.piProactiveCompactionGeneration === agent.generation
+            && agent.piProactiveCompactionSession === agent.session
+            ? agent.piProactiveCompaction : null;
+        if (proactive && await proactive === "failed")
+            return;
+        if (agent.adapter.id === "pi" && agent.piProactiveCompactionFailedGeneration === agent.generation)
+            return;
+        if (agent.adapter.id === "pi" && !agent.busy && !agent.turnInProgress && agent.session) {
+            const idleGate = proactivelyCompactPiAtIdle(agent, agent.session);
+            if (idleGate && await idleGate === "failed")
+                return;
+        }
+        if (agent.stopped || agent.busy || agent.turnInProgress || agent.submitting)
+            return;
+        if (agent.backgroundCompletionInFlight || !agent.backgroundCompletionQueue.length)
+            return;
+        agent.submitting = true;
+        agent.busy = true;
+        const completionKey = agent.backgroundCompletionQueue[0];
+        try {
+            const outcome = await wakeOnBackgroundCompletion(agent);
+            if (outcome.status === "accepted") {
+                agent.backgroundCompletionKeys.add(completionKey);
+                agent.backgroundCompletionInFlight = completionKey;
+                agent.backgroundCompletionWakeInputId = outcome.inputId;
+                // Keep the reject streak until the wake turn actually succeeds. An accepted
+                // prompt that later terminal-fails must not reset the bounded retry budget.
+                clearBackgroundCompletionRetryTimer(agent);
+            }
+            else if (outcome.status === "dropped") {
+                if (agent.stopped) {
+                    if (agent.backgroundCompletionQueue[0] === completionKey)
+                        agent.backgroundCompletionQueue.shift();
+                    agent.backgroundCompletionKeys.delete(completionKey);
+                    clearBackgroundCompletionRetryTimer(agent);
+                }
+                else {
+                    rearmBackgroundCompletion(agent, completionKey);
+                    agent.busy = false;
+                }
+            }
+            else {
+                agent.busy = false;
+                agent.backgroundCompletionRejectStreak += 1;
+                // Leave the item queued+deduped. Immediate microtask retries cover a
+                // brief reject; after that a bounded timer still drains because Pi will
+                // not re-emit the same completion.
+                scheduleBackgroundCompletionRetry(agent);
+            }
+        }
+        finally {
+            agent.submitting = false;
+        }
+    };
+    const noteBackgroundCompletion = (agent, completionKey) => {
+        if (agent.backgroundCompletionKeys.has(completionKey))
+            return;
+        agent.backgroundCompletionKeys.add(completionKey);
+        if (!agent.backgroundCompletionQueue.includes(completionKey)) {
+            agent.backgroundCompletionQueue.push(completionKey);
+        }
+        if (!agent.busy && !agent.turnInProgress && !agent.submitting && !agent.backgroundCompletionInFlight) {
+            scheduleBackgroundCompletionDrain(agent);
+        }
+    };
     const scheduleRecreate = (agent, reason) => {
         if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
             return;
@@ -612,6 +823,8 @@ export function createRuntimeHost(options) {
                 if (proactive && await proactive === "failed")
                     return;
                 await retryPending(agent);
+                if (agent.backgroundCompletionQueue.length > 0)
+                    scheduleBackgroundCompletionDrain(agent);
             }).catch((error) => {
                 const readiness = error instanceof RuntimePrerequisiteError ? error.readiness
                     : classifyRuntimePrerequisite(agent.adapter.id, error);
@@ -634,6 +847,7 @@ export function createRuntimeHost(options) {
         agent.busy = false;
         agent.submitting = false;
         agent.generation += 1;
+        rearmBackgroundCompletion(agent);
         agent.recreateReason = reason;
         if (agent.stabilityTimer)
             clearTimeout(agent.stabilityTimer);
@@ -654,6 +868,7 @@ export function createRuntimeHost(options) {
         agent.busy = false;
         agent.submitting = false;
         agent.generation += 1;
+        rearmBackgroundCompletion(agent);
         if (agent.stabilityTimer)
             clearTimeout(agent.stabilityTimer);
         agent.stabilityTimer = null;
@@ -910,6 +1125,15 @@ export function createRuntimeHost(options) {
             agent.busy = false;
             emit({ type: "activity", agentId: agent.config.agentId, activity: "idle", activityKind: "idle", detailKind: "turn_ended" });
             reconcileAcceptedAtTurnEnd(agent);
+            if (agent.backgroundCompletionInFlight) {
+                if (agent.turnHadFailure)
+                    failBackgroundCompletionWake(agent);
+                else
+                    commitBackgroundCompletion(agent);
+            }
+            if (agent.backgroundCompletionQueue.length > 0 && !agent.backgroundCompletionRetryTimer) {
+                scheduleBackgroundCompletionDrain(agent);
+            }
             telemetry?.runtimeEvent(agent.config.agentId, event);
             if (recoveredAuthentication) {
                 agent.authFailureActive = false;
@@ -929,12 +1153,24 @@ export function createRuntimeHost(options) {
             });
             queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
         }
+        else if (event.type === "runtime-observation") {
+            if (event.phase === "completed" && typeof event.completionKey === "string") {
+                noteBackgroundCompletion(agent, event.completionKey);
+            }
+        }
         else if (event.type === "activity") {
             if (agent.turnInProgress && event.activity !== "internal")
                 agent.turnHadAuthenticatedOutput = true;
             emit({ type: "activity", agentId: agent.config.agentId, activity: event.activity, activityKind: event.activity });
         }
         else if (event.type === "input-error") {
+            if (agent.backgroundCompletionInFlight
+                && (!event.inputId || !agent.backgroundCompletionWakeInputId
+                    || event.inputId === agent.backgroundCompletionWakeInputId)
+                && event.willRetry !== true) {
+                agent.turnHadFailure = true;
+                failBackgroundCompletionWake(agent, event);
+            }
             const record = event.inputId
                 ? agent.records.get(event.inputId) ?? [...agent.records.values()].find((candidate) => candidate.input.inputId === event.inputId)
                 : undefined;
@@ -1261,10 +1497,13 @@ export function createRuntimeHost(options) {
                         clearTimeout(previous.retryTimer);
                     if (previous.stabilityTimer)
                         clearTimeout(previous.stabilityTimer);
+                    if (previous.backgroundCompletionRetryTimer)
+                        clearTimeout(previous.backgroundCompletionRetryTimer);
                     const candidate = {
                         ...previous, config, adapter, session, launchId: crypto.randomUUID(), busy: false, submitting: false,
                         starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
                         recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
+                        backgroundCompletionRetryTimer: null,
                         disabledReason: null, configurationRecovery: null,
                         readiness: previous.authFailureActive ? previous.readiness : readiness,
                     };
@@ -1281,6 +1520,11 @@ export function createRuntimeHost(options) {
                     if (!candidate.authFailureActive) {
                         emit({ type: "agent-status", agentId: config.agentId, status: "active", readiness: candidate.readiness ?? readiness });
                     }
+                    // Commit clears any inherited backoff timer; reschedule so a queued
+                    // completion still drains on the new session.
+                    if (candidate.backgroundCompletionQueue.length > 0) {
+                        scheduleBackgroundCompletionDrain(candidate);
+                    }
                     await previous.session?.close("runtime candidate committed")
                         .catch((error) => log("previous runtime close after candidate commit failed", String(error)));
                 },
@@ -1613,7 +1857,10 @@ export function createRuntimeHost(options) {
                     piProactiveCompaction: null, piProactiveCompactionGeneration: null, piProactiveCompactionSession: null,
                     piProactiveCompactionFailedGeneration: null, readiness: null,
                     turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false,
-                    promotedInboxUpdateIds: new Set() };
+                    promotedInboxUpdateIds: new Set(),
+                    backgroundCompletionQueue: [], backgroundCompletionKeys: new Set(),
+                    backgroundCompletionInFlight: null, backgroundCompletionWakeInputId: null,
+                    backgroundCompletionRejectStreak: 0, backgroundCompletionRetryTimer: null };
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {
@@ -1764,6 +2011,8 @@ export function createRuntimeHost(options) {
                 clearTimeout(agent.retryTimer);
             if (agent.stabilityTimer)
                 clearTimeout(agent.stabilityTimer);
+            if (agent.backgroundCompletionRetryTimer)
+                clearTimeout(agent.backgroundCompletionRetryTimer);
             if (agent.busy)
                 await agent.session?.cancel(reason);
             await agent.session?.close(reason);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkin",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [