larkin 0.4.17 → 0.4.19

package/dist/runtime/pi-subagent-record-watchdog.bundle.js

@@ -0,0 +1,183 @@
+// @bun
+// src/runtime/pi-subagent-ledger.ts
+import fs from "fs";
+import path from "path";
+var PI_SUBAGENT_RECORD_DIRNAME = "pi-subagent-records";
+var PI_SUBAGENT_SESSION_OWNER_ENV = "LARKIN_PI_SESSION_OWNER";
+var TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "timed_out",
+  "orphaned"
+]);
+function isTerminalPiSubagentRecord(record) {
+  if (!record || typeof record !== "object")
+    return false;
+  const status = record.status;
+  return typeof status === "string" && status.length > 0 && status !== "running" && status !== "queued";
+}
+function isConsumedTerminalPiSubagentRecord(record) {
+  if (!isTerminalPiSubagentRecord(record))
+    return false;
+  return record.resultConsumed === true;
+}
+function ledgerStatusFromPiSubagentRecord(record) {
+  const status = typeof record === "object" && record && "status" in record ? String(record.status || "").trim().toLowerCase() : "";
+  if (status === "error")
+    return "failed";
+  if (status === "aborted")
+    return "timed_out";
+  if (status === "stopped")
+    return "cancelled";
+  if (status === "steered")
+    return "timed_out";
+  return "completed";
+}
+function readPersistedPiSubagentTerminal(file) {
+  return readPiSubagentTerminalFile(file, false);
+}
+function writePersistedPiSubagentTerminal(file, input, options) {
+  writePiSubagentTerminalFile(file, input, options?.resultConsumed === true);
+}
+function dispatchedSubagentRecordDir(stateDir) {
+  return path.join(stateDir, PI_SUBAGENT_RECORD_DIRNAME);
+}
+function sweepAbsentPiSubagentRecordFiles(recordDir, getRecord, options) {
+  let names;
+  try {
+    names = fs.readdirSync(recordDir);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return [];
+    throw error;
+  }
+  const removed = [];
+  for (const name of names) {
+    if (!name || name.startsWith("."))
+      continue;
+    const file = path.join(recordDir, name);
+    try {
+      const stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink() || !stat.isFile())
+        continue;
+    } catch {
+      continue;
+    }
+    const owner = typeof options?.owner === "string" && options.owner.trim() ? options.owner.trim() : undefined;
+    if (owner && readPiSubagentRecordOwner(file) !== owner)
+      continue;
+    const record = getRecord(name);
+    if (isTerminalPiSubagentRecord(record)) {
+      try {
+        writePersistedPiSubagentTerminal(file, {
+          taskId: name,
+          status: ledgerStatusFromPiSubagentRecord(record)
+        }, { resultConsumed: isConsumedTerminalPiSubagentRecord(record) });
+      } catch {}
+      continue;
+    }
+    if (record != null)
+      continue;
+    if (readPersistedPiSubagentTerminal(file))
+      continue;
+    try {
+      fs.unlinkSync(file);
+      removed.push(name);
+    } catch {}
+  }
+  return removed;
+}
+function readPiSubagentTerminalFile(file, requireConsumed) {
+  if (!file)
+    return null;
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+      return null;
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object")
+      return null;
+    if (requireConsumed && parsed.resultConsumed !== true && parsed.consumed !== true)
+      return null;
+    if (typeof parsed.taskId !== "string" || parsed.taskId.length === 0)
+      return null;
+    if (parsed.status !== "completed" && parsed.status !== "failed" && parsed.status !== "cancelled" && parsed.status !== "timed_out") {
+      return null;
+    }
+    return { taskId: parsed.taskId, status: parsed.status };
+  } catch {
+    return null;
+  }
+}
+function writePiSubagentTerminalFile(file, input, resultConsumed) {
+  const existing = (() => {
+    try {
+      return fs.lstatSync(file);
+    } catch {
+      return null;
+    }
+  })();
+  if (existing?.isSymbolicLink())
+    throw new Error("subagent record file must not be a symlink");
+  const owner = readPiSubagentRecordOwner(file);
+  const payload = `${JSON.stringify({
+    taskId: input.taskId,
+    ...resultConsumed ? { resultConsumed: true } : {},
+    status: input.status,
+    ...owner ? { owner } : {}
+  })}
+`;
+  if (existing?.isFile()) {
+    try {
+      if (fs.readFileSync(file, "utf8") === payload)
+        return;
+    } catch {}
+  }
+  fs.writeFileSync(file, payload, { mode: 384 });
+  fs.chmodSync(file, 384);
+}
+function readPiSubagentRecordOwner(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return typeof parsed?.owner === "string" && parsed.owner.trim() ? parsed.owner.trim() : undefined;
+  } catch {
+    return;
+  }
+}
+
+// src/runtime/pi-subagent-record-watchdog.ts
+var PI_SUBAGENTS_MANAGER = Symbol.for("pi-subagents:manager");
+var DEFAULT_SWEEP_INTERVAL_MS = 15000;
+function piSubagentRecordWatchdog(pi) {
+  const stateDir = process.env.LARKIN_STATE_DIR;
+  const owner = process.env[PI_SUBAGENT_SESSION_OWNER_ENV];
+  if (!stateDir || !owner)
+    return;
+  const recordDir = dispatchedSubagentRecordDir(stateDir);
+  const intervalMs = sweepIntervalMs();
+  const tick = () => {
+    try {
+      const manager = globalThis[PI_SUBAGENTS_MANAGER];
+      if (typeof manager?.getRecord !== "function")
+        return;
+      sweepAbsentPiSubagentRecordFiles(recordDir, (taskId) => manager.getRecord(taskId), { owner });
+    } catch {}
+  };
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  const stop = () => {
+    clearInterval(timer);
+    tick();
+  };
+  pi.on("session_shutdown", stop);
+}
+function sweepIntervalMs() {
+  const raw = Number.parseInt(process.env.LARKIN_PI_SUBAGENT_RECORD_SWEEP_MS || "", 10);
+  if (Number.isInteger(raw) && raw > 0)
+    return raw;
+  return DEFAULT_SWEEP_INTERVAL_MS;
+}
+export {
+  piSubagentRecordWatchdog as default
+};

package/dist/runtime/pi-subagent-record-watchdog.mjs

@@ -0,0 +1,46 @@
+import { dispatchedSubagentRecordDir, PI_SUBAGENT_SESSION_OWNER_ENV, sweepAbsentPiSubagentRecordFiles, } from "./pi-subagent-ledger.mjs";
+const PI_SUBAGENTS_MANAGER = Symbol.for("pi-subagents:manager");
+const DEFAULT_SWEEP_INTERVAL_MS = 15_000;
+/**
+ * Pi-process watchdog: delete Larkin record sidecars once AgentManager no longer
+ * has the in-memory task. Persist any terminal AgentRecord — including an
+ * unconsumed completion Pi may evict after ten minutes — before treating a
+ * missing getRecord as a genuine orphan. A get_subagent_result consume also
+ * suppresses the canonical notification; bridge that consumed marker before
+ * cleanup can delete the sidecar. Leftover transcripts are intentionally
+ * ignored. Sidecars are owner-tagged so a staged Pi sharing LARKIN_STATE_DIR
+ * cannot sweep another session's records. This extension registers
+ * session_shutdown first so the final sweep still sees getRecord.
+ */
+export default function piSubagentRecordWatchdog(pi) {
+    const stateDir = process.env.LARKIN_STATE_DIR;
+    const owner = process.env[PI_SUBAGENT_SESSION_OWNER_ENV];
+    if (!stateDir || !owner)
+        return;
+    const recordDir = dispatchedSubagentRecordDir(stateDir);
+    const intervalMs = sweepIntervalMs();
+    const tick = () => {
+        try {
+            const manager = globalThis[PI_SUBAGENTS_MANAGER];
+            if (typeof manager?.getRecord !== "function")
+                return;
+            sweepAbsentPiSubagentRecordFiles(recordDir, (taskId) => manager.getRecord(taskId), { owner });
+        }
+        catch {
+            // Best-effort: a transient EACCES/EMFILE must not crash the Pi timer.
+        }
+    };
+    const timer = setInterval(tick, intervalMs);
+    timer.unref?.();
+    const stop = () => {
+        clearInterval(timer);
+        tick();
+    };
+    pi.on("session_shutdown", stop);
+}
+function sweepIntervalMs() {
+    const raw = Number.parseInt(process.env.LARKIN_PI_SUBAGENT_RECORD_SWEEP_MS || "", 10);
+    if (Number.isInteger(raw) && raw > 0)
+        return raw;
+    return DEFAULT_SWEEP_INTERVAL_MS;
+}

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

@@ -20,6 +20,20 @@ const TERMINAL_STATUS_TOKENS = new Set([
     "turn-limit",
     "turn_limit",
 ]);
+export function ledgerStatusFromPiNotificationStatus(status) {
+    const normalized = status.trim().toLowerCase();
+    if (normalized.startsWith("error") || normalized === "error")
+        return "failed";
+    if (normalized.startsWith("stopped"))
+        return "cancelled";
+    if (normalized.startsWith("aborted")
+        || normalized.includes("turn limit")
+        || normalized.includes("turn-limit")
+        || normalized.includes("turn_limit")
+        || normalized.includes("steered"))
+        return "timed_out";
+    return "completed";
+}
 export function isCanonicalTerminalPiSubagentStatus(status) {
     const normalized = status.trim().toLowerCase();
     if (!normalized)

package/dist/runtime/runtime-adapters.mjs

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { createInterface } from "node:readline";
+import { applyPiPackageDirForChild, piChildDistributionFromOverrides } from "./builtin-pi-assets.mjs";
 import { isPiThinkingLevel } from "./pi-model-catalog.mjs";
 import { PiRpcClient } from "./pi-rpc-client.mjs";
 import { internalCommandSpec } from "../app/internal-command.mjs";
@@ -10,7 +11,9 @@ 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 { extractCanonicalPiSubagentNotification, ledgerStatusFromPiNotificationStatus, } from "./pi-subagents-notification.mjs";
+import { resolvePiSubagentRecordWatchdogExtensionArg } from "./pi-subagent-record-watchdog-injection.mjs";
+import { effectivePiStateDir, extractBackgroundPiSubagentDispatch } from "./pi-subagent-ledger.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";
@@ -454,6 +457,7 @@ class PiSession extends EventSession {
     observedCompletedEpochs = new Set();
     observedBackgroundCompletionKeys = new Set();
     pendingUnownedCompletionKeys = new Set();
+    pendingUnownedCompletionStatuses = new Map();
     observedAgentEndEpochs = new Set();
     firstOutputObserved = false;
     toolCallOpen = false;
@@ -556,6 +560,7 @@ class PiSession extends EventSession {
             this.observedCompletedEpochs.clear();
             this.observedBackgroundCompletionKeys.clear();
             this.pendingUnownedCompletionKeys.clear();
+            this.pendingUnownedCompletionStatuses.clear();
             this.observedAgentEndEpochs.clear();
             this.activeEpoch = null;
             this.settleArmedEpoch = null;
@@ -605,13 +610,34 @@ 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);
+            const completionNotification = extractCanonicalPiSubagentNotification(event.messages);
+            if (completionNotification && !this.observedBackgroundCompletionKeys.has(completionNotification.key)) {
+                const completionStatuses = Object.fromEntries(completionNotification.notifications.map((notification) => [
+                    notification.taskId,
+                    ledgerStatusFromPiNotificationStatus(notification.status),
+                ]));
+                const owningTurnFailed = event.willRetry === true
+                    || this.finalAssistantStopReason === "error"
+                    || this.finalAssistantStopReason === "aborted";
+                if (this.activeEpoch === null || owningTurnFailed) {
+                    // Unowned agent_end still has an active Pi session, so prompting
+                    // before settle is rejected as "Agent is already processing".
+                    // A failed or retrying owned turn also did not process the
+                    // notification; do not emit handledInTurn so RuntimeHost can still
+                    // wake after input-error, retry, or restart.
+                    this.pendingUnownedCompletionKeys.add(completionNotification.key);
+                    this.pendingUnownedCompletionStatuses.set(completionNotification.key, completionStatuses);
+                }
+                else {
+                    // Already visible in the owned turn. Persist as acknowledged; do not
+                    // schedule another wake after the parent turn settles.
+                    this.observedBackgroundCompletionKeys.add(completionNotification.key);
+                    this.emitObservation("completed", {
+                        completionKey: completionNotification.key,
+                        completionStatuses,
+                        handledInTurn: true,
+                    });
+                }
             }
         }
         else if (event?.type === "agent_settled") {
@@ -682,6 +708,13 @@ class PiSession extends EventSession {
                 this.toolCallOpen = false;
                 this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "tool_result" });
             }
+            const dispatched = extractBackgroundPiSubagentDispatch(event);
+            if (dispatched) {
+                this.emitObservation("background_dispatched", {
+                    taskId: dispatched.taskId,
+                    ...(dispatched.outputFile ? { outputFile: dispatched.outputFile } : {}),
+                });
+            }
         }
         else if (event?.type === "message_update" && event.assistantMessageEvent?.delta) {
             if (!this.firstOutputObserved) {
@@ -697,9 +730,14 @@ class PiSession extends EventSession {
             if (this.observedBackgroundCompletionKeys.has(completionKey))
                 continue;
             this.observedBackgroundCompletionKeys.add(completionKey);
-            this.emitObservation("completed", { completionKey });
+            const completionStatuses = this.pendingUnownedCompletionStatuses.get(completionKey);
+            this.emitObservation("completed", {
+                completionKey,
+                ...(completionStatuses ? { completionStatuses } : {}),
+            });
         }
         this.pendingUnownedCompletionKeys.clear();
+        this.pendingUnownedCompletionStatuses.clear();
     }
     emitObservation(phase, fields = {}) {
         const inputId = this.oldestOwnedInput();
@@ -937,6 +975,11 @@ export function resolvePiProcessExtensionArgs(input, resolvers = {}) {
         return [];
     const resolverInput = { distribution: "external", piCommand: input.piCommand, env: input.env };
     const args = [];
+    // Watchdog must load before the subagent extension so session_shutdown still
+    // sees AgentManager.getRecord and can bridge consumed or terminal state.
+    const recordWatchdog = (resolvers.recordWatchdog ?? resolvePiSubagentRecordWatchdogExtensionArg)(resolverInput);
+    if (recordWatchdog)
+        args.push("-e", recordWatchdog);
     const subagents = (resolvers.subagents ?? resolvePiSubagentExtensionArg)(resolverInput);
     if (subagents)
         args.push("-e", subagents);
@@ -946,7 +989,7 @@ export function resolvePiProcessExtensionArgs(input, resolvers = {}) {
     return args;
 }
 async function createPiRpcBackend(input, dependencies, spawn, productionSpawn = true) {
-    const stateRoot = input.stateDir ?? path.join(input.workspaceDir, ".larkin");
+    const stateRoot = effectivePiStateDir(input);
     const mergedEnv = { ...globalThis.process.env, ...dependencies.env, ...input.env, NO_COLOR: "1" };
     assertNoProjectPiCompactionOverride(input.workspaceDir);
     const ownedPiDirectory = mergedEnv.LARKIN_CONFIG_DIR
@@ -967,23 +1010,29 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         ...(session.sessionFile ? ["--session", session.sessionFile] : []),
         ...(requestedModel ? ["--model", requestedModel] : []),
         ...(requestedEffort ? ["--thinking", requestedEffort] : [])];
-    const builtin = mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin";
+    const builtin = piChildDistributionFromOverrides(dependencies.env, input.env) === "builtin";
+    if (!builtin && mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin")
+        delete mergedEnv.LARKIN_PI_DISTRIBUTION;
     const builtinSpec = builtin ? internalCommandSpec("pi-rpc", [], mergedEnv) : null;
     const command = builtinSpec?.command ?? dependencies.piCommand ?? dependencies.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
     const commandPrefix = builtinSpec?.args ?? dependencies.piCommandArgs ?? [];
     const commandArgs = [...commandPrefix, ...args];
+    mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
+    if (builtin)
+        mergedEnv.PI_TELEMETRY = "0";
+    const childEnv = applyPiPackageDirForChild(mergedEnv, {
+        distribution: builtin ? "builtin" : "external",
+        explicitPackageDir: input.env?.PI_PACKAGE_DIR ?? dependencies.env?.PI_PACKAGE_DIR,
+    });
     const reportedVersion = productionSpawn && !builtin
         ? parsePiExecutableVersion(String(spawnSync(command, [...commandPrefix, "--version"], {
-            cwd: input.workspaceDir, env: mergedEnv, encoding: "utf8", timeout: 5_000,
+            cwd: input.workspaceDir, env: childEnv, encoding: "utf8", timeout: 5_000,
         }).stdout || ""))
         : BUNDLED_PI_VERSION;
-    mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
-    if (builtin)
-        mergedEnv.PI_TELEMETRY = "0";
     const extensionArgs = (dependencies.resolvePiProcessExtensionArgs ?? resolvePiProcessExtensionArgs)({
         distribution: builtin ? "builtin" : "external",
         piCommand: command,
-        env: mergedEnv,
+        env: childEnv,
         platform: process.platform,
     });
     commandArgs.push(...extensionArgs);
@@ -993,14 +1042,14 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         // requested model first, then write the matching 15% reserve before the
         // real session starts; no prompt, provider request, package, or extension
         // is loaded by the probe.
-        probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, mergedEnv, spawn, dependencies.piRpcClientOptions);
+        probedModel = await discoverEffectivePiContextWindow(input, command, commandPrefix, requestedModel, childEnv, spawn, dependencies.piRpcClientOptions);
         writeOwnedPiSettings(ownedPiDirectory, calculatePiCompactionSettings(probedModel.contextWindow));
     }
     const artifactEntriesBeforeSpawn = new Set(fs.readdirSync(ownedPiDirectory));
     const artifactSpawnBoundary = Date.now();
     const child = spawn(command, commandArgs, {
         cwd: input.workspaceDir,
-        env: mergedEnv,
+        env: childEnv,
         stdio: ["pipe", "pipe", "pipe"],
     });
     traceProcessBoundary(mergedEnv, "pi-rpc:child-spawned", { configDir: mergedEnv.LARKIN_CONFIG_DIR, agentId: input.agentId, targetDir: ownedPiDirectory, childPid: child.pid ?? null });
@@ -1164,8 +1213,7 @@ export function createNativeRuntimeAdapter(id, dependencies = {}) {
                     throw new RuntimePrerequisiteError(readiness);
             }
             if (id === "pi") {
-                const distribution = ({ ...globalThis.process.env, ...dependencies.env, ...input.env }).LARKIN_PI_DISTRIBUTION === "builtin"
-                    ? "builtin" : "external";
+                const distribution = piChildDistributionFromOverrides(dependencies.env, input.env);
                 return new PiSession(await (dependencies.createPiSession
                     ? dependencies.createPiSession(input)
                     : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn, productionSpawn)), distribution);