larkin 0.4.18 → 0.4.20

package/dist/runtime/pi-supervised-command.mjs

@@ -0,0 +1,420 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export const DEFAULT_WAIT_SECONDS = 60;
+export const DEFAULT_LIFE_SECONDS = 600;
+export const LARKIN_SUPERVISED_COMMAND_CAPABILITY = "larkin-pi-supervised-command-v1";
+const MAX_STREAM_BYTES = 64 * 1024;
+export function supervisedWaitSeconds() {
+    const raw = Number.parseInt(process.env.LARKIN_PI_SUPERVISED_WAIT_SECONDS || "", 10);
+    if (Number.isInteger(raw) && raw > 0)
+        return Math.min(raw, DEFAULT_WAIT_SECONDS);
+    return DEFAULT_WAIT_SECONDS;
+}
+export function supervisedLifeSeconds() {
+    const raw = Number.parseInt(process.env.LARKIN_PI_SUPERVISED_LIFE_SECONDS || "", 10);
+    if (Number.isInteger(raw) && raw > 0)
+        return Math.min(raw, DEFAULT_LIFE_SECONDS);
+    return DEFAULT_LIFE_SECONDS;
+}
+export function resolveSupervisedCwd(root, requested) {
+    if (typeof root !== "string" || root.length === 0)
+        throw new Error("supervised cwd root is required");
+    if (fs.lstatSync(root).isSymbolicLink())
+        throw new Error("supervised cwd must not be a symlink");
+    const base = fs.realpathSync(root);
+    const target = requested && requested.length > 0 ? path.resolve(base, requested) : base;
+    const relative = path.relative(base, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("supervised cwd escapes the session root");
+    let current = base;
+    if (relative && relative !== ".") {
+        for (const part of relative.split(path.sep)) {
+            if (!part || part === ".")
+                continue;
+            current = path.join(current, part);
+            if (fs.lstatSync(current).isSymbolicLink())
+                throw new Error("supervised cwd must not be a symlink");
+        }
+    }
+    const real = fs.realpathSync(current);
+    const prefix = base.endsWith(path.sep) ? base : base + path.sep;
+    if (real !== base && !real.startsWith(prefix))
+        throw new Error("supervised cwd escapes the session root");
+    if (!fs.statSync(real).isDirectory())
+        throw new Error("supervised cwd is not a directory");
+    return real;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function listDescendantPids(root) {
+    if (process.platform === "win32")
+        return [];
+    const found = new Set();
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (current === undefined)
+            break;
+        const listed = spawnSync("pgrep", ["-P", String(current)], { encoding: "utf8" });
+        if (listed.status !== 0 || !listed.stdout)
+            continue;
+        for (const line of listed.stdout.split(/\s+/)) {
+            const child = Number.parseInt(line, 10);
+            if (!Number.isInteger(child) || child <= 0 || found.has(child) || child === root)
+                continue;
+            found.add(child);
+            queue.push(child);
+        }
+    }
+    return [...found];
+}
+function refreshTreePids(pid, known) {
+    known.add(pid);
+    for (const child of listDescendantPids(pid))
+        known.add(child);
+    return [...known];
+}
+async function killProcessTree(pid, known = new Set([pid])) {
+    const descendants = refreshTreePids(pid, known).filter((child) => child !== pid);
+    if (process.platform === "win32") {
+        const result = await new Promise((resolve) => {
+            const child = spawn("taskkill", ["/F", "/T", "/PID", String(pid)], { stdio: "ignore", windowsHide: true });
+            child.once("error", (error) => resolve({ status: null, error }));
+            child.once("exit", (status) => resolve({ status }));
+        });
+        if (result.error && pidAlive(pid))
+            throw result.error;
+    }
+    else {
+        for (const child of [...descendants].reverse()) {
+            try {
+                process.kill(child, "SIGKILL");
+            }
+            catch { /* already dead */ }
+        }
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { /* already dead */ }
+        }
+    }
+    const started = Date.now();
+    const pending = () => pidAlive(pid) || descendants.some((child) => pidAlive(child));
+    while (pending() && Date.now() - started < 2000) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        if (process.platform !== "win32") {
+            for (const child of descendants) {
+                try {
+                    process.kill(child, "SIGKILL");
+                }
+                catch { /* already dead */ }
+            }
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { /* already dead */ }
+        }
+    }
+    if (pending())
+        throw new Error(`supervised process tree ${pid} still alive`);
+}
+class ByteCursor {
+    chunks = [];
+    dropped = 0;
+    write(chunk) {
+        let data = chunk;
+        if (chunk.length > MAX_STREAM_BYTES) {
+            this.dropped += chunk.length - MAX_STREAM_BYTES;
+            data = chunk.subarray(chunk.length - MAX_STREAM_BYTES);
+        }
+        this.chunks.push(data);
+        let total = this.chunks.reduce((n, c) => n + c.length, 0);
+        while (total > MAX_STREAM_BYTES && this.chunks.length) {
+            const overflow = total - MAX_STREAM_BYTES;
+            const head = this.chunks[0];
+            if (head.length <= overflow) {
+                this.chunks.shift();
+                this.dropped += head.length;
+                total -= head.length;
+            }
+            else {
+                this.chunks[0] = head.subarray(overflow);
+                this.dropped += overflow;
+                total -= overflow;
+            }
+        }
+    }
+    snapshot(cursor) {
+        const joined = Buffer.concat(this.chunks);
+        let start = Math.max(0, cursor - this.dropped);
+        if (start < joined.length) {
+            while (start < joined.length && (joined[start] & 0b1100_0000) === 0b1000_0000)
+                start++;
+        }
+        let end = joined.length;
+        if (end > start) {
+            let cont = 0;
+            let i = end;
+            while (i > start && (joined[i - 1] & 0b1100_0000) === 0b1000_0000) {
+                i--;
+                cont++;
+            }
+            if (i > start) {
+                const lead = joined[i - 1];
+                const need = lead < 0x80 ? 1 : lead < 0xe0 ? 2 : lead < 0xf0 ? 3 : 4;
+                if (cont + 1 < need)
+                    end = i - 1;
+            }
+        }
+        const slice = joined.subarray(Math.min(start, end), end);
+        return {
+            text: slice.toString("utf8"),
+            cursor: this.dropped + end,
+            truncated: this.dropped > cursor || start > Math.max(0, cursor - this.dropped),
+        };
+    }
+}
+const handles = new Map();
+const terminals = new Map();
+const MAX_TERMINALS = 32;
+function rememberTerminal(id, owner, snapshot) {
+    terminals.set(id, { owner, snapshot });
+    while (terminals.size > MAX_TERMINALS) {
+        const oldest = terminals.keys().next().value;
+        if (!oldest)
+            break;
+        terminals.delete(oldest);
+    }
+}
+function notify(record) {
+    const waiters = record.exitWaiters.splice(0);
+    for (const wake of waiters)
+        wake();
+}
+function finish(record, status, exitCode) {
+    if (record.lifetimeTimer) {
+        clearTimeout(record.lifetimeTimer);
+        record.lifetimeTimer = undefined;
+    }
+    if (record.treePoll) {
+        clearInterval(record.treePoll);
+        record.treePoll = undefined;
+    }
+    if (record.status === "running") {
+        record.status = status;
+        record.exitCode = exitCode;
+    }
+    notify(record);
+}
+export function startSupervisedCommand(input) {
+    if (typeof input.executable !== "string" || input.executable.length === 0) {
+        throw new Error("executable must be a non-empty string");
+    }
+    if (!Array.isArray(input.args) || input.args.some((arg) => typeof arg !== "string")) {
+        throw new Error("args must be a string array");
+    }
+    const cwd = resolveSupervisedCwd(input.cwd);
+    const child = spawn(input.executable, input.args, {
+        cwd,
+        shell: false,
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let record;
+    child.on("error", (error) => {
+        if (!record)
+            return;
+        const current = record;
+        void current.chain.then(async () => {
+            await killProcessTree(current.pid, current.treePids);
+            finish(current, "killed", null);
+        });
+        void error;
+    });
+    if (!child.pid)
+        throw new Error("failed to spawn supervised command");
+    const id = randomBytes(16).toString("hex");
+    record = {
+        id,
+        owner: input.owner,
+        child,
+        pid: child.pid,
+        startedAt: Date.now(),
+        deadlineAt: Date.now() + supervisedLifeSeconds() * 1000,
+        stdout: new ByteCursor(),
+        stderr: new ByteCursor(),
+        stdoutCursor: 0,
+        stderrCursor: 0,
+        status: "running",
+        exitCode: null,
+        terminalConsumed: false,
+        cancelRequested: false,
+        exitWaiters: [],
+        treePids: new Set([child.pid]),
+        chain: Promise.resolve(),
+        closed: Promise.resolve(),
+    };
+    const started = record;
+    let markClosed = () => { };
+    started.closed = new Promise((resolve) => { markClosed = resolve; });
+    child.stdout?.on("data", (chunk) => started.stdout.write(Buffer.from(chunk)));
+    child.stderr?.on("data", (chunk) => started.stderr.write(Buffer.from(chunk)));
+    started.treePoll = setInterval(() => {
+        refreshTreePids(started.pid, started.treePids);
+    }, 50);
+    started.treePoll.unref?.();
+    child.once("close", (code) => {
+        markClosed();
+        void started.chain.then(async () => {
+            await killProcessTree(started.pid, started.treePids);
+            finish(started, "exited", code);
+        });
+    });
+    started.lifetimeTimer = setTimeout(() => {
+        void started.chain.then(async () => {
+            if (started.status !== "running")
+                return;
+            await killProcessTree(started.pid, started.treePids);
+            finish(started, "lifetime_exceeded", null);
+        });
+    }, supervisedLifeSeconds() * 1000);
+    started.lifetimeTimer.unref?.();
+    handles.set(id, started);
+    return { handle: id, pid: started.pid };
+}
+function snapshot(record) {
+    const out = record.stdout.snapshot(record.stdoutCursor);
+    const err = record.stderr.snapshot(record.stderrCursor);
+    record.stdoutCursor = out.cursor;
+    record.stderrCursor = err.cursor;
+    return {
+        handle: record.id,
+        pid: record.pid,
+        status: record.status,
+        exitCode: record.exitCode,
+        stdout: out.text,
+        stderr: err.text,
+        stdoutCursor: out.cursor,
+        stderrCursor: err.cursor,
+        truncated: out.truncated || err.truncated,
+    };
+}
+function requireHandle(owner, handle) {
+    const record = handles.get(handle);
+    if (!record || record.owner !== owner)
+        throw new Error("supervised handle not found");
+    return record;
+}
+function enqueue(record, work) {
+    const next = record.chain.then(work, work);
+    record.chain = next.then(() => undefined, () => undefined);
+    return next;
+}
+export async function waitSupervisedCommand(owner, handle, timeoutSeconds) {
+    const remembered = terminals.get(handle);
+    if (remembered && remembered.owner === owner && !handles.has(handle))
+        return remembered.snapshot;
+    const record = requireHandle(owner, handle);
+    return enqueue(record, async () => {
+        const cap = supervisedWaitSeconds();
+        const requested = typeof timeoutSeconds === "number" && timeoutSeconds > 0 ? timeoutSeconds : cap;
+        if (requested > cap)
+            throw new Error(`wait timeout:${requested} exceeds the ${cap}s supervised wait limit`);
+        const remainingLife = Math.max(0, record.deadlineAt - Date.now());
+        const waitMs = Math.min(requested * 1000, remainingLife, cap * 1000);
+        if (record.status === "running" && waitMs > 0) {
+            await new Promise((resolve) => {
+                let done = false;
+                const finishWait = () => {
+                    if (done)
+                        return;
+                    done = true;
+                    record.exitWaiters = record.exitWaiters.filter((item) => item !== finishWait);
+                    resolve();
+                };
+                const timer = setTimeout(finishWait, waitMs);
+                record.exitWaiters.push(() => {
+                    clearTimeout(timer);
+                    finishWait();
+                });
+            });
+        }
+        if (record.status !== "running" && record.terminalConsumed) {
+            throw new Error("supervised terminal result already consumed");
+        }
+        const result = snapshot(record);
+        if (result.status !== "running") {
+            record.terminalConsumed = true;
+            rememberTerminal(record.id, owner, result);
+            handles.delete(record.id);
+        }
+        return result;
+    });
+}
+export async function cancelSupervisedCommand(owner, handle) {
+    const remembered = terminals.get(handle);
+    if (remembered && remembered.owner === owner && !handles.has(handle))
+        return remembered.snapshot;
+    const record = requireHandle(owner, handle);
+    return enqueue(record, async () => {
+        record.cancelRequested = true;
+        notify(record);
+        if (record.status === "running") {
+            await killProcessTree(record.pid, record.treePids);
+            record.status = "killed";
+        }
+        if (record.lifetimeTimer) {
+            clearTimeout(record.lifetimeTimer);
+            record.lifetimeTimer = undefined;
+        }
+        await record.closed;
+        const result = record.terminalConsumed && remembered?.owner === owner
+            ? remembered.snapshot
+            : snapshot(record);
+        record.terminalConsumed = true;
+        rememberTerminal(record.id, owner, result);
+        handles.delete(record.id);
+        return result;
+    });
+}
+export async function reapSupervisedCommands(owner) {
+    for (const [id, remembered] of terminals) {
+        if (remembered.owner === owner)
+            terminals.delete(id);
+    }
+    const owned = [...handles.values()].filter((record) => record.owner === owner);
+    const errors = [];
+    await Promise.all(owned.map(async (record) => {
+        try {
+            await cancelSupervisedCommand(owner, record.id);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (record.lifetimeTimer)
+            clearTimeout(record.lifetimeTimer);
+        try {
+            await killProcessTree(record.pid, record.treePids);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        handles.delete(record.id);
+    }));
+    if (errors.length > 0)
+        throw errors[0];
+}

package/dist/runtime/runtime-adapters.mjs

@@ -11,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";
@@ -455,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;
@@ -557,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;
@@ -606,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") {
@@ -683,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) {
@@ -698,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();
@@ -938,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);
@@ -947,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