larkin 0.4.18 → 0.4.19

package/dist/runtime/runtime-host.cjs

@@ -17,6 +17,7 @@ const runtime_readiness_js_1 = require("./runtime-readiness.cjs");
 const official_lark_cli_js_1 = require("../app/official-lark-cli.cjs");
 const agent_lark_cli_workspace_js_1 = require("../app/agent-lark-cli-workspace.cjs");
 const pi_compaction_recovery_js_1 = require("./pi-compaction-recovery.cjs");
+const pi_subagent_ledger_js_1 = require("./pi-subagent-ledger.cjs");
 class RuntimeSessionResetError extends Error {
     code;
     pendingCount;
@@ -41,6 +42,7 @@ class RuntimeSessionRecoveryError extends Error {
 exports.RuntimeSessionRecoveryError = RuntimeSessionRecoveryError;
 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([
@@ -150,6 +152,10 @@ 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);
@@ -159,10 +165,14 @@ 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_ledger_js_1.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: (0, pi_subagent_ledger_js_1.effectivePiStateDir)(config),
             ...(process.env.HOME ? { HOME: process.env.HOME } : {}),
             ...(process.env.SHELL ? { SHELL: process.env.SHELL } : {}),
             ...(process.env.ZDOTDIR ? { ZDOTDIR: process.env.ZDOTDIR } : {}),
@@ -648,6 +658,7 @@ 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;
@@ -714,6 +725,7 @@ 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
@@ -722,7 +734,15 @@ function createRuntimeHost(options) {
             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 headKey = agent.backgroundCompletionQueue[0];
+            const tasks = (0, pi_subagent_ledger_js_1.taskIdsFromCompletionKey)(headKey ?? "")
+                .map((taskId) => (0, pi_subagent_ledger_js_1.getDispatchedSubagent)(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", node_crypto_1.default.randomUUID(), { wakeReason });
             const result = await session.prompt(input);
             if (agent.session !== session || agent.stopped)
                 return { status: "dropped" };
@@ -800,10 +820,62 @@ function createRuntimeHost(options) {
             agent.submitting = false;
         }
     };
+    const persistSubagentLedger = (agent) => {
+        (0, pi_subagent_ledger_js_1.writeDispatchedSubagentLedger)((0, pi_subagent_ledger_js_1.ledgerFilePath)((0, pi_subagent_ledger_js_1.effectivePiStateDir)(agent.config)), agent.subagentLedger);
+    };
+    const dropQueuedBackgroundCompletionFallback = (agent, completionKey) => {
+        const keys = new Set([completionKey, ...(0, pi_subagent_ledger_js_1.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 = (0, pi_subagent_ledger_js_1.noteDispatchedSubagentWakeAcknowledged)(agent.subagentLedger, { completionKey });
+        if (next === agent.subagentLedger)
+            return;
+        agent.subagentLedger = next;
+        persistSubagentLedger(agent);
+        for (const taskId of (0, pi_subagent_ledger_js_1.taskIdsFromCompletionKey)(completionKey)) {
+            (0, pi_subagent_ledger_js_1.retirePiSubagentRecord)((0, pi_subagent_ledger_js_1.getDispatchedSubagent)(agent.subagentLedger, taskId)?.recordFile);
+        }
+    };
+    const enqueueUndeliveredTerminalWakes = (agent) => {
+        for (const key of (0, pi_subagent_ledger_js_1.undeliveredTerminalWakeKeys)(agent.subagentLedger)) {
+            agent.backgroundCompletionKeys.delete(key);
+            for (const taskId of (0, pi_subagent_ledger_js_1.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 (0, pi_subagent_ledger_js_1.readDispatchedSubagentLedger)((0, pi_subagent_ledger_js_1.ledgerFilePath)((0, pi_subagent_ledger_js_1.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 = (0, pi_subagent_ledger_js_1.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);
         }
@@ -811,6 +883,62 @@ function createRuntimeHost(options) {
             scheduleBackgroundCompletionDrain(agent);
         }
     };
+    const recordDispatchedSubagent = (agent, taskId, outputFile) => {
+        const recordFile = (0, pi_subagent_ledger_js_1.writeDispatchedSubagentRecordFile)((0, pi_subagent_ledger_js_1.effectivePiStateDir)(agent.config), taskId, agent.piSessionOwner);
+        agent.subagentLedger = (0, pi_subagent_ledger_js_1.noteDispatchedSubagent)(agent.subagentLedger, { taskId, outputFile, recordFile });
+        persistSubagentLedger(agent);
+        armSubagentReconcileTimer(agent);
+    };
+    const recordTerminalSubagentNotification = (agent, completionKey, statuses) => {
+        let next = agent.subagentLedger;
+        for (const taskId of (0, pi_subagent_ledger_js_1.taskIdsFromCompletionKey)(completionKey)) {
+            const status = statuses?.[taskId];
+            next = (0, pi_subagent_ledger_js_1.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 = (0, pi_subagent_ledger_js_1.reconcileDispatchedSubagents)(agent.subagentLedger, {
+            probe: options.subagentRecordProbe ?? pi_subagent_ledger_js_1.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;
@@ -832,6 +960,8 @@ 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);
@@ -862,13 +992,21 @@ 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)
@@ -893,6 +1031,8 @@ 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" };
@@ -1180,6 +1320,7 @@ 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;
@@ -1200,8 +1341,18 @@ 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") {
@@ -1319,11 +1470,12 @@ 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) {
@@ -1331,6 +1483,7 @@ function createRuntimeHost(options) {
                 throw new Error("stale runtime session creation");
             }
             agent.session = session;
+            agent.piSessionOwner = sessionEnv[pi_subagent_ledger_js_1.PI_SUBAGENT_SESSION_OWNER_ENV];
             session.subscribe((event) => observe(agent, session, event));
             if (agent.session !== session)
                 return session;
@@ -1470,7 +1623,9 @@ function createRuntimeHost(options) {
                 ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}) });
         }
         emit({ type: "agent-status", agentId, status: "active", readiness });
+        agent.piSessionOwner = probeEnv[pi_subagent_ledger_js_1.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")
@@ -1545,11 +1700,13 @@ 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: 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,
+                        backgroundCompletionRetryTimer: null, subagentReconcileTimer: null,
                         disabledReason: null, configurationRecovery: null,
                         readiness: previous.authFailureActive ? previous.readiness : readiness,
                     };
@@ -1566,13 +1723,14 @@ 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_ledger_js_1.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,
             };
@@ -1665,8 +1823,10 @@ function createRuntimeHost(options) {
                     ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}) });
             }
             emit({ type: "agent-status", agentId, status: "active", readiness });
+            agent.piSessionOwner = probeEnv[pi_subagent_ledger_js_1.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 };
         },
@@ -1815,8 +1975,10 @@ function createRuntimeHost(options) {
                 }
                 emit({ type: "agent-status", agentId, status: "active", readiness });
                 durableRollback = null;
+                agent.piSessionOwner = probeEnv[pi_subagent_ledger_js_1.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")
@@ -1906,7 +2068,8 @@ 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()) {
@@ -1937,6 +2100,8 @@ 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;
@@ -1949,6 +2114,8 @@ function createRuntimeHost(options) {
                     const reason = error instanceof Error ? error.message : String(error);
                     const transient = error instanceof runtime_readiness_js_1.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);
@@ -2059,6 +2226,8 @@ 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);
@@ -2067,5 +2236,9 @@ 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 ? (0, pi_subagent_ledger_js_1.getDispatchedSubagent)(agent.subagentLedger, taskId) : null;
+        },
     };
 }