larkin 0.4.18 → 0.4.19

package/dist/runtime/runtime-host.mjs

@@ -10,6 +10,7 @@ import { classifyRuntimePrerequisite, providerAuthenticationFailureReadiness, Ru
 import { resolveOfficialLarkCli } from "../app/official-lark-cli.mjs";
 import { assertAgentWorkspaceBound, managedLarkCliEnv } from "../app/agent-lark-cli-workspace.mjs";
 import { isPiNativeCompactionRequired, PiCompactionBreaker, PiCompactionRecoveryMachine, } from "./pi-compaction-recovery.mjs";
+import { getDispatchedSubagent as lookupDispatchedSubagent, ledgerFilePath, noteDispatchedSubagent, noteDispatchedSubagentTerminal, noteDispatchedSubagentWakeAcknowledged, probePiSubagentRecord, readDispatchedSubagentLedger, reconcileDispatchedSubagents, taskIdsFromCompletionKey, undeliveredTerminalWakeKeys, PI_SUBAGENT_SESSION_OWNER_ENV, retirePiSubagentRecord, effectivePiStateDir, writeDispatchedSubagentLedger, writeDispatchedSubagentRecordFile, } from "./pi-subagent-ledger.mjs";
 export class RuntimeSessionResetError extends Error {
     code;
     pendingCount;
@@ -32,6 +33,7 @@ export class RuntimeSessionRecoveryError extends Error {
 }
 const MAX_DELIVERIES = 2048;
 const BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT = 5;
+const DEFAULT_SUBAGENT_RECONCILE_INTERVAL_MS = 15_000;
 const now = () => new Date().toISOString();
 const isActiveDelivery = (status) => ["pending", "submitting", "accepted"].includes(status);
 const REPLAY_FAILURE_CODES = new Set([
@@ -141,6 +143,10 @@ export function createRuntimeHost(options) {
         maxAttempts: options.retryPolicy?.maxAttempts ?? 6,
         stableWindowMs: options.retryPolicy?.stableWindowMs ?? 30_000,
     };
+    const subagentReconcileIntervalMs = options.subagentReconcileIntervalMs ?? DEFAULT_SUBAGENT_RECONCILE_INTERVAL_MS;
+    if (!Number.isFinite(subagentReconcileIntervalMs) || subagentReconcileIntervalMs < 0) {
+        throw new Error("subagentReconcileIntervalMs must be >= 0");
+    }
     const emit = (event) => {
         if (event.type === "delivery")
             telemetry?.delivery(event.agentId, event.messageId, event.status);
@@ -150,10 +156,14 @@ export function createRuntimeHost(options) {
     const runtimeEnv = (config, generation) => {
         const base = {
             LARKIN_AGENT_ID: config.agentId,
-            ...(generation ? { LARKIN_RUNTIME_OBSERVATION_GENERATION: generation } : {}),
+            ...(generation ? {
+                LARKIN_RUNTIME_OBSERVATION_GENERATION: generation,
+                [PI_SUBAGENT_SESSION_OWNER_ENV]: generation,
+            } : {}),
             LARKIN_CONFIG_DIR: process.env.LARKIN_CONFIG_DIR,
             LARKIN_HOME: process.env.LARKIN_HOME,
             ...(config.piDistribution ? { LARKIN_PI_DISTRIBUTION: config.piDistribution } : {}),
+            LARKIN_STATE_DIR: effectivePiStateDir(config),
             ...(process.env.HOME ? { HOME: process.env.HOME } : {}),
             ...(process.env.SHELL ? { SHELL: process.env.SHELL } : {}),
             ...(process.env.ZDOTDIR ? { ZDOTDIR: process.env.ZDOTDIR } : {}),
@@ -639,6 +649,7 @@ export function createRuntimeHost(options) {
         }
         agent.backgroundCompletionRejectStreak = 0;
         clearBackgroundCompletionRetryTimer(agent);
+        // Leave the durable wake pending so a later restart can requeue it.
     };
     const scheduleBackgroundCompletionRetry = (agent) => {
         const streak = agent.backgroundCompletionRejectStreak;
@@ -705,6 +716,7 @@ export function createRuntimeHost(options) {
         agent.backgroundCompletionWakeInputId = null;
         agent.backgroundCompletionRejectStreak = 0;
         clearBackgroundCompletionRetryTimer(agent);
+        acknowledgeSubagentWake(agent, completionKey);
     };
     const wakeOnBackgroundCompletion = async (agent) => {
         // Caller already reserved submitting/busy so a concurrent idle drain cannot
@@ -713,7 +725,15 @@ export function createRuntimeHost(options) {
             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 headKey = agent.backgroundCompletionQueue[0];
+            const tasks = taskIdsFromCompletionKey(headKey ?? "")
+                .map((taskId) => lookupDispatchedSubagent(agent.subagentLedger, taskId))
+                .filter((task) => Boolean(task));
+            const details = tasks.map((task) => `task ${task.taskId} status=${task.status}`).join("; ");
+            const wakeReason = details
+                ? `background subagent completed; ${details}`
+                : "background subagent completed";
+            const input = options.promptBuilder.buildRuntimeInput("wake", crypto.randomUUID(), { wakeReason });
             const result = await session.prompt(input);
             if (agent.session !== session || agent.stopped)
                 return { status: "dropped" };
@@ -791,10 +811,62 @@ export function createRuntimeHost(options) {
             agent.submitting = false;
         }
     };
+    const persistSubagentLedger = (agent) => {
+        writeDispatchedSubagentLedger(ledgerFilePath(effectivePiStateDir(agent.config)), agent.subagentLedger);
+    };
+    const dropQueuedBackgroundCompletionFallback = (agent, completionKey) => {
+        const keys = new Set([completionKey, ...taskIdsFromCompletionKey(completionKey)]);
+        for (let index = agent.backgroundCompletionQueue.length - 1; index >= 0; index -= 1) {
+            const queued = agent.backgroundCompletionQueue[index];
+            if (queued && keys.has(queued))
+                agent.backgroundCompletionQueue.splice(index, 1);
+        }
+        for (const key of keys)
+            agent.backgroundCompletionKeys.add(key);
+    };
+    const acknowledgeSubagentWake = (agent, completionKey) => {
+        const next = noteDispatchedSubagentWakeAcknowledged(agent.subagentLedger, { completionKey });
+        if (next === agent.subagentLedger)
+            return;
+        agent.subagentLedger = next;
+        persistSubagentLedger(agent);
+        for (const taskId of taskIdsFromCompletionKey(completionKey)) {
+            retirePiSubagentRecord(lookupDispatchedSubagent(agent.subagentLedger, taskId)?.recordFile);
+        }
+    };
+    const enqueueUndeliveredTerminalWakes = (agent) => {
+        for (const key of undeliveredTerminalWakeKeys(agent.subagentLedger)) {
+            agent.backgroundCompletionKeys.delete(key);
+            for (const taskId of taskIdsFromCompletionKey(key))
+                agent.backgroundCompletionKeys.delete(taskId);
+            noteBackgroundCompletion(agent, key);
+        }
+    };
+    const reconcileAfterSessionSwap = (agent) => {
+        reconcileSubagentLedger(agent, { forceMissing: true, missingReason: "pi session gone" });
+        enqueueUndeliveredTerminalWakes(agent);
+        if (agent.backgroundCompletionQueue.length > 0)
+            scheduleBackgroundCompletionDrain(agent);
+    };
+    const loadSubagentLedger = (config) => {
+        return readDispatchedSubagentLedger(ledgerFilePath(effectivePiStateDir(config)));
+    };
+    const clearSubagentReconcileTimer = (agent) => {
+        if (!agent.subagentReconcileTimer)
+            return;
+        clearInterval(agent.subagentReconcileTimer);
+        agent.subagentReconcileTimer = null;
+    };
+    const hasActiveDispatchedSubagent = (agent) => agent.subagentLedger.tasks.some((task) => task.status === "dispatched");
     const noteBackgroundCompletion = (agent, completionKey) => {
+        const taskIds = taskIdsFromCompletionKey(completionKey);
         if (agent.backgroundCompletionKeys.has(completionKey))
             return;
+        if (taskIds.length > 0 && taskIds.every((taskId) => agent.backgroundCompletionKeys.has(taskId)))
+            return;
         agent.backgroundCompletionKeys.add(completionKey);
+        for (const taskId of taskIds)
+            agent.backgroundCompletionKeys.add(taskId);
         if (!agent.backgroundCompletionQueue.includes(completionKey)) {
             agent.backgroundCompletionQueue.push(completionKey);
         }
@@ -802,6 +874,62 @@ export function createRuntimeHost(options) {
             scheduleBackgroundCompletionDrain(agent);
         }
     };
+    const recordDispatchedSubagent = (agent, taskId, outputFile) => {
+        const recordFile = writeDispatchedSubagentRecordFile(effectivePiStateDir(agent.config), taskId, agent.piSessionOwner);
+        agent.subagentLedger = noteDispatchedSubagent(agent.subagentLedger, { taskId, outputFile, recordFile });
+        persistSubagentLedger(agent);
+        armSubagentReconcileTimer(agent);
+    };
+    const recordTerminalSubagentNotification = (agent, completionKey, statuses) => {
+        let next = agent.subagentLedger;
+        for (const taskId of taskIdsFromCompletionKey(completionKey)) {
+            const status = statuses?.[taskId];
+            next = noteDispatchedSubagentTerminal(next, {
+                taskId,
+                status: status && status !== "dispatched" && status !== "orphaned" ? status : "completed",
+                wakeKey: completionKey,
+            });
+        }
+        agent.subagentLedger = next;
+        persistSubagentLedger(agent);
+        if (!hasActiveDispatchedSubagent(agent))
+            clearSubagentReconcileTimer(agent);
+    };
+    const reconcileSubagentLedger = (agent, input = {}) => {
+        if (agent.stopped)
+            return;
+        const result = reconcileDispatchedSubagents(agent.subagentLedger, {
+            probe: options.subagentRecordProbe ?? probePiSubagentRecord,
+            forceMissing: input.forceMissing === true,
+            missingReason: input.missingReason,
+        });
+        const previousLedger = agent.subagentLedger;
+        agent.subagentLedger = result.ledger;
+        if (result.orphaned.length > 0 || result.terminals.length > 0 || result.ledger !== previousLedger) {
+            persistSubagentLedger(agent);
+        }
+        for (const record of [...result.orphaned, ...result.terminals]) {
+            noteBackgroundCompletion(agent, record.wakeKey ?? record.taskId);
+        }
+        if (!hasActiveDispatchedSubagent(agent))
+            clearSubagentReconcileTimer(agent);
+        else
+            armSubagentReconcileTimer(agent);
+    };
+    const armSubagentReconcileTimer = (agent) => {
+        if (agent.stopped || agent.subagentReconcileTimer || subagentReconcileIntervalMs === 0)
+            return;
+        if (!hasActiveDispatchedSubagent(agent))
+            return;
+        agent.subagentReconcileTimer = setInterval(() => {
+            if (agent.stopped) {
+                clearSubagentReconcileTimer(agent);
+                return;
+            }
+            reconcileSubagentLedger(agent);
+        }, subagentReconcileIntervalMs);
+        agent.subagentReconcileTimer.unref?.();
+    };
     const scheduleRecreate = (agent, reason) => {
         if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
             return;
@@ -823,6 +951,8 @@ export function createRuntimeHost(options) {
                 const proactive = session ? proactivelyCompactPiAtIdle(agent, session) : null;
                 if (proactive && await proactive === "failed")
                     return;
+                reconcileSubagentLedger(agent, { forceMissing: true, missingReason: "pi session gone" });
+                enqueueUndeliveredTerminalWakes(agent);
                 await retryPending(agent);
                 if (agent.backgroundCompletionQueue.length > 0)
                     scheduleBackgroundCompletionDrain(agent);
@@ -853,13 +983,21 @@ export function createRuntimeHost(options) {
         if (agent.stabilityTimer)
             clearTimeout(agent.stabilityTimer);
         agent.stabilityTimer = null;
-        void session.close(`replace after ${reason}`).catch((error) => log("runtime close after replacement failed", String(error)));
         for (const record of agent.records.values())
             if (isActiveDelivery(record.status))
                 record.status = "pending";
         emitConsumed(agent, persist(agent));
         emit({ type: "agent-status", agentId: agent.config.agentId, status: "error", error: reason });
-        scheduleRecreate(agent, reason);
+        // Close first so the shutdown sweep can bridge consumed or terminal state
+        // before force-missing reconcile treats a plain sidecar as orphaned.
+        void session.close(`replace after ${reason}`)
+            .catch((error) => log("runtime close after replacement failed", String(error)))
+            .finally(() => {
+            if (agent.stopped)
+                return;
+            reconcileAfterSessionSwap(agent);
+            scheduleRecreate(agent, reason);
+        });
     };
     const recoverConfiguration = (agent, session, message) => {
         if (agent.session !== session || agent.stopped)
@@ -884,6 +1022,8 @@ export function createRuntimeHost(options) {
         const recovery = (async () => {
             try {
                 await session.close("runtime configuration error");
+                if (!agent.stopped)
+                    reconcileAfterSessionSwap(agent);
                 const result = agent.adapter.recoverConfigurationError
                     ? await agent.adapter.recoverConfigurationError(message)
                     : { recovered: false, reason: "runtime adapter does not support automatic configuration recovery" };
@@ -1171,6 +1311,7 @@ export function createRuntimeHost(options) {
             if (agent.backgroundCompletionQueue.length > 0 && !agent.backgroundCompletionRetryTimer) {
                 scheduleBackgroundCompletionDrain(agent);
             }
+            reconcileSubagentLedger(agent);
             telemetry?.runtimeEvent(agent.config.agentId, event);
             if (recoveredAuthentication) {
                 agent.authFailureActive = false;
@@ -1191,8 +1332,18 @@ 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);
+            if (event.phase === "background_dispatched" && typeof event.taskId === "string" && event.taskId) {
+                recordDispatchedSubagent(agent, event.taskId, typeof event.outputFile === "string" ? event.outputFile : undefined);
+            }
+            else if (event.phase === "completed" && typeof event.completionKey === "string") {
+                recordTerminalSubagentNotification(agent, event.completionKey, event.completionStatuses);
+                if (event.handledInTurn === true) {
+                    acknowledgeSubagentWake(agent, event.completionKey);
+                    dropQueuedBackgroundCompletionFallback(agent, event.completionKey);
+                }
+                else {
+                    noteBackgroundCompletion(agent, event.completionKey);
+                }
             }
         }
         else if (event.type === "activity") {
@@ -1310,11 +1461,12 @@ export function createRuntimeHost(options) {
         });
         const generation = ++agent.generation;
         let completedSession = null;
+        const sessionEnv = runtimeEnv(agent.config, `${agent.launchId}:${generation}`);
         agent.starting = agent.adapter.createSession({
             agentId: agent.config.agentId, model: agent.config.model, reasoningEffort: agent.config.effort || null,
             workspaceDir: agent.config.workspaceDir, stateDir: agent.config.stateDir,
             resumeSessionId: agent.config.sessionId || null, standingPrompt,
-            env: runtimeEnv(agent.config, `${agent.launchId}:${generation}`),
+            env: sessionEnv,
         }).then((session) => {
             completedSession = session;
             if (agent.stopped || generation !== agent.generation) {
@@ -1322,6 +1474,7 @@ export function createRuntimeHost(options) {
                 throw new Error("stale runtime session creation");
             }
             agent.session = session;
+            agent.piSessionOwner = sessionEnv[PI_SUBAGENT_SESSION_OWNER_ENV];
             session.subscribe((event) => observe(agent, session, event));
             if (agent.session !== session)
                 return session;
@@ -1461,7 +1614,9 @@ export function createRuntimeHost(options) {
                 ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}) });
         }
         emit({ type: "agent-status", agentId, status: "active", readiness });
+        agent.piSessionOwner = probeEnv[PI_SUBAGENT_SESSION_OWNER_ENV];
         await oldSession.close("Pi context fallback committed").catch((error) => log("previous Pi session close after fallback failed", String(error)));
+        reconcileAfterSessionSwap(agent);
         const proactive = proactivelyCompactPiAtIdle(agent, fresh);
         void (proactive ?? Promise.resolve("noop")).then((outcome) => {
             if (outcome !== "failed")
@@ -1536,11 +1691,13 @@ export function createRuntimeHost(options) {
                         clearTimeout(previous.stabilityTimer);
                     if (previous.backgroundCompletionRetryTimer)
                         clearTimeout(previous.backgroundCompletionRetryTimer);
+                    if (previous.subagentReconcileTimer)
+                        clearInterval(previous.subagentReconcileTimer);
                     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,
+                        backgroundCompletionRetryTimer: null, subagentReconcileTimer: null,
                         disabledReason: null, configurationRecovery: null,
                         readiness: previous.authFailureActive ? previous.readiness : readiness,
                     };
@@ -1557,13 +1714,14 @@ 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);
-                    }
+                    candidate.piSessionOwner = stageEnv[PI_SUBAGENT_SESSION_OWNER_ENV];
+                    // Close first so the old session's shutdown sweep can bridge consumed
+                    // terminals before force-missing reconcile. Commit also clears any
+                    // inherited backoff timer; reschedule so a queued completion still
+                    // drains on the new session.
                     await previous.session?.close("runtime candidate committed")
                         .catch((error) => log("previous runtime close after candidate commit failed", String(error)));
+                    reconcileAfterSessionSwap(candidate);
                 },
                 rollback,
             };
@@ -1656,8 +1814,10 @@ export function createRuntimeHost(options) {
                     ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}) });
             }
             emit({ type: "agent-status", agentId, status: "active", readiness });
+            agent.piSessionOwner = probeEnv[PI_SUBAGENT_SESSION_OWNER_ENV];
             await oldSession.close("fresh session reset committed")
                 .catch((error) => log("previous runtime close after fresh reset failed", String(error)));
+            reconcileAfterSessionSwap(agent);
             return { generationChanged: true, sessionChanged: oldSessionId !== fresh.sessionId, turns: 0,
                 runtimeReady: true, pendingCount: 0, sessionId: fresh.sessionId };
         },
@@ -1806,8 +1966,10 @@ export function createRuntimeHost(options) {
                 }
                 emit({ type: "agent-status", agentId, status: "active", readiness });
                 durableRollback = null;
+                agent.piSessionOwner = probeEnv[PI_SUBAGENT_SESSION_OWNER_ENV];
                 await oldSession.close("context-window recovery committed")
                     .catch((error) => log("previous runtime close after context-window recovery failed", String(error)));
+                reconcileAfterSessionSwap(agent);
                 const proactive = proactivelyCompactPiAtIdle(agent, fresh);
                 void (proactive ?? Promise.resolve("noop")).then((outcome) => {
                     if (outcome !== "failed")
@@ -1897,7 +2059,8 @@ export function createRuntimeHost(options) {
                     promotedInboxUpdateIds: new Set(),
                     backgroundCompletionQueue: [], backgroundCompletionKeys: new Set(),
                     backgroundCompletionInFlight: null, backgroundCompletionWakeInputId: null,
-                    backgroundCompletionRejectStreak: 0, backgroundCompletionRetryTimer: null };
+                    backgroundCompletionRejectStreak: 0, backgroundCompletionRetryTimer: null,
+                    subagentLedger: loadSubagentLedger(config), subagentReconcileTimer: null };
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {
@@ -1928,6 +2091,8 @@ export function createRuntimeHost(options) {
                 emitConsumed(agent, [...startupConsumed, ...persist(agent)]);
                 try {
                     await ensureSession(agent);
+                    reconcileSubagentLedger(agent, { forceMissing: true, missingReason: "runtime restarted" });
+                    enqueueUndeliveredTerminalWakes(agent);
                     await recoverStalePiCompaction(agent);
                     const startupSession = agent.session;
                     const proactive = startupSession ? proactivelyCompactPiAtIdle(agent, startupSession) : null;
@@ -1940,6 +2105,8 @@ export function createRuntimeHost(options) {
                     const reason = error instanceof Error ? error.message : String(error);
                     const transient = error instanceof RuntimePrerequisiteError && error.readiness.state === "unavailable";
                     agent.disabledReason = transient ? null : reason;
+                    reconcileSubagentLedger(agent, { forceMissing: true, missingReason: "runtime restarted" });
+                    enqueueUndeliveredTerminalWakes(agent);
                     if (transient) {
                         recoveringCount += 1;
                         scheduleRecreate(agent, reason);
@@ -2050,6 +2217,8 @@ export function createRuntimeHost(options) {
                 clearTimeout(agent.stabilityTimer);
             if (agent.backgroundCompletionRetryTimer)
                 clearTimeout(agent.backgroundCompletionRetryTimer);
+            if (agent.subagentReconcileTimer)
+                clearInterval(agent.subagentReconcileTimer);
             if (agent.busy)
                 await agent.session?.cancel(reason);
             await agent.session?.close(reason);
@@ -2058,5 +2227,9 @@ export function createRuntimeHost(options) {
         },
         async shutdown(reason) { await Promise.allSettled([...managed.keys()].map((id) => this.stop(id, reason))); },
         subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        getDispatchedSubagent(agentId, taskId) {
+            const agent = managed.get(agentId);
+            return agent ? lookupDispatchedSubagent(agent.subagentLedger, taskId) : null;
+        },
     };
 }

package/package.json

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