@fitchmultz/pi-subagents 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.52.0] - 2026-10-26
+
+### Added
+
+- Park children that stay idle for five minutes on a Pi fork with native working-session capture. The child saves its exact working state and its process exits, freeing its memory. Its Intercom identity stays listed with no departure. Passive messages, topic updates and `last` reads do not wake it; its main answers `last` from the saved history. A normal message, ask or continuation restores the exact saved state into a new process, which then receives retained messages in order. A failed final save records `park-failed.json` and restarts nothing; continuing reports it. Official Pi keeps idle children resident.
+
+### Known limitations
+
+- The remaining idle CPU, receipt-reader, child-readiness and receipt-append performance targets are tracked in [#290](https://github.com/fitchmultz/pi-subagents/issues/290). This release does not claim those targets are met.
+
 ## [0.51.0] - 2026-10-26
 
 ### Added

package/dist/agent/child-runtime.js

@@ -0,0 +1,80 @@
+import * as fs from "node:fs";
+import { shellCommand } from "./process.js";
+import { localCwdOwner } from "./cwd.js";
+function guard(pi, directory, token) {
+    pi.on("tool_call", (event) => {
+        if (event.toolName === "delegate" || event.toolName === "agent_runs") {
+            return { block: true, reason: "Only a main session may delegate or control children." };
+        }
+        const owner = pi.getAllTools().find((tool) => tool.name === "bash")?.sourceInfo;
+        if (event.toolName === "bash" &&
+            typeof event.input.command === "string" &&
+            owner &&
+            (owner.source === "builtin" || localCwdOwner(owner))) {
+            // Preserve the selected local owner's cwd/env and leave remote/custom tools alone.
+            const input = event.input;
+            input.command = shellCommand(event.input.command, directory, token);
+        }
+        return;
+    });
+}
+/** One native child session with this package's child policy and live-view hooks. */
+export function childRuntime(sdk, launch, hooks) {
+    return async ({ sessionManager }) => {
+        // Exact restore keeps settings, tool policy and accepted queues; it never replays input.
+        const restore = hooks.saved ? { workingSession: hooks.saved } : {};
+        if (!fs.existsSync(launch.sessionFile)) {
+            throw new Error("Missing saved native session; refusing to create another.");
+        }
+        const settingsManager = sdk.SettingsManager.create(launch.cwd, launch.agentDir, {
+            projectTrusted: launch.trusted,
+        });
+        const services = await sdk.createAgentSessionServices({
+            ...restore,
+            cwd: launch.cwd,
+            agentDir: launch.agentDir,
+            settingsManager,
+            resourceLoaderOptions: {
+                additionalExtensionPaths: [launch.entry],
+                extensionFactories: [
+                    {
+                        name: "codemode",
+                        builtin: true,
+                        factory: sdk.createCodemodeExtension({ mode: "on" }),
+                    },
+                    { name: "tool_search", builtin: true, factory: sdk.createToolSearchExtension() },
+                    { name: "mcp", builtin: true, factory: sdk.createMcpExtension() },
+                    (pi) => {
+                        guard(pi, hooks.directory, hooks.token);
+                        pi.on("session_start", (_event, ctx) => {
+                            hooks.started(pi, ctx);
+                        });
+                        // Sparse tool lifecycle keeps the live view's tools even while nobody watches.
+                        pi.on("tool_execution_start", hooks.tool);
+                        pi.on("tool_execution_update", hooks.tool);
+                        pi.on("tool_execution_end", hooks.tool);
+                    },
+                ],
+            },
+        });
+        const diagnostics = services.resourceLoader.getExtensions().errors;
+        if (diagnostics.length > 0) {
+            throw new Error(`Child extension load failed: ${JSON.stringify(diagnostics)}`);
+        }
+        const model = services.modelRuntime.getModel(launch.provider, launch.model);
+        if (!model) {
+            throw new Error(`Saved model ${launch.provider}/${launch.model} is unavailable; no fallback was used.`);
+        }
+        return {
+            ...(await sdk.createAgentSessionFromServices({
+                ...restore,
+                services,
+                sessionManager,
+                model,
+                thinkingLevel: launch.thinking,
+            })),
+            services,
+            diagnostics: services.diagnostics,
+        };
+    };
+}

package/dist/agent/contracts.js

@@ -89,6 +89,15 @@ export const commandSchema = Type.Object({
     createdAt: Type.Number(),
 });
 export const successorSchema = Type.Object({ id: Type.String() });
+/** Authority to restore exact working state, valid only after the named actor has exited. */
+/** Exact parked authority: one exited generation's state bytes for this session and leaf. */
+export const parkedSchema = Type.Object({
+    token: Type.String(),
+    state: Type.String(),
+    digest: Type.String(),
+    sessionId: Type.String(),
+    leafId: Type.Union([Type.String(), Type.Null()]),
+});
 export const exitSchema = Type.Object({
     pid: Type.Integer(),
     code: Type.Union([Type.Integer(), Type.Null()]),

package/dist/agent/index.js

@@ -1,11 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { actor, alive, ensureActor, ownIdentity, requestStop, signalProcess, stopChildren, } from "./process.js";
+import { actor, alive, ensureActor, ownIdentity, parkFailure, requestStop, signalProcess, stopChildren, } from "./process.js";
 import { isChild, errorText } from "./host.js";
+import { serveParked } from "./parking.js";
 import { resultSchema, attachmentSchema, admissionSchema, commandSchema, } from "./contracts.js";
 import { delegateSchema, runsSchema } from "./tool-schemas.js";
-import { enqueue, latest, launchAt, list, read, runDirectory, ownerDirectory, conversation, write, } from "./storage.js";
+import { enqueue, latest, launchAt, list, read, runDirectory, ownerDirectory, conversation, successor, write, } from "./storage.js";
 import { notifications, deliver, settle } from "./notifications.js";
 import { prepareLaunch } from "./launch.js";
 import { renderReceipt, renderInventory, renderInspection } from "./view.js";
@@ -290,23 +291,6 @@ class AgentRuntime {
             .sort((a, b) => a.createdAt - b.createdAt);
         return renderInventory(this.base, all, this.ctx, input);
     }
-    successor(launch, prompt) {
-        const id = randomUUID();
-        const next = { ...launch, id, predecessor: launch.id, prompt, createdAt: Date.now() };
-        fs.mkdirSync(runDirectory(this.base, id), { mode: 0o700 });
-        write(path.join(runDirectory(this.base, id), "launch.json"), next, true);
-        try {
-            write(path.join(runDirectory(this.base, launch.id), "successor.json"), { id }, true);
-        }
-        catch (error) {
-            fs.rmSync(runDirectory(this.base, id), { recursive: true });
-            if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) {
-                throw error;
-            }
-            return undefined;
-        }
-        return next;
-    }
     continuationResult(launch) {
         const result = read(path.join(runDirectory(this.base, launch.id), "result.json"), resultSchema);
         if (result) {
@@ -352,7 +336,8 @@ class AgentRuntime {
                 note: "Guidance queued, not actual completion or model consumption.",
             });
         }
-        const next = this.successor(launch, input.prompt);
+        parkFailure(this.base, launch);
+        const next = successor(this.base, launch, input.prompt);
         if (!next) {
             return renderReceipt(this.base, latest(this.base, launch), this.ctx, {
                 receipt: "existing-successor",
@@ -409,6 +394,7 @@ class AgentRuntime {
     }
     register() {
         registerCompactMessages(this.pi, ["agent-completion", "subagent-notify"]);
+        serveParked(this.pi, () => (this.child || !this.ctx ? undefined : { base: this.base, owner: this.owner }), this.shutdown.signal);
         this.pi.on("session_start", (_event, context) => this.start(context));
         this.pi.on("turn_end", (event, context) => {
             // The public pending flag covers user input; the preview also includes custom messages.

package/dist/agent/observation.js

@@ -117,6 +117,10 @@ export class ActorObservation {
         const { session } = this;
         return this.running || session.isStreaming || session.isCompacting || session.isRetrying;
     }
+    /** A live viewer keeps its actor resident; parking would end the native stream it reads. */
+    get watched() {
+        return this.viewers.size + this.greeting.size > 0;
+    }
     details() {
         return [...this.viewers].filter((viewer) => viewer.level === "detail").length;
     }

package/dist/agent/parking.js

@@ -0,0 +1,253 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parkedSchema } from "./contracts.js";
+import { errorText, loadSDK } from "./host.js";
+import { conversation, latest, launchAt, list, read, runDirectory, write } from "./storage.js";
+import { alive, shells, wakeActor } from "./process.js";
+import { isHistoryRequest, PARK, PARKED_HISTORY, WAKE, } from "../shared/parking.js";
+import { nativePeerId } from "../pi-intercom/session-targets.js";
+function parkable(session) {
+    return typeof Reflect.get(session, "acquireWorkingSession") === "function";
+}
+function finalizing(runtime) {
+    return typeof Reflect.get(runtime, "setFinalization") === "function";
+}
+function fence(pi, park) {
+    let fenced = Promise.resolve(false);
+    pi.events.emit(PARK, {
+        park,
+        reply: (parked) => {
+            fenced = parked;
+        },
+    });
+    return fenced;
+}
+async function cut(pi, session, { quiet, errors, signal }) {
+    try {
+        // Save handlers may legitimately append entries; only the pre-cut leaf proves idleness.
+        if ((await fence(pi, true)) && quiet() && session.isIdle) {
+            return await session.acquireWorkingSession({ boundary: "settled", signal });
+        }
+    }
+    catch (error) {
+        errors.push(errorText(error));
+    }
+    return undefined;
+}
+const PARK_AFTER_MS = 5 * 60_000;
+const digest = (file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+/** Parked authority names this session and exactly the saved generation's state bytes. */
+function exact(restore, parked, state, launch) {
+    if (parked.sessionId !== launch.sessionId ||
+        parked.state !== state ||
+        digest(state) !== parked.digest) {
+        return undefined;
+    }
+    const saved = restore(state);
+    return saved.sessionFile === launch.sessionFile &&
+        saved.header.id === launch.sessionId &&
+        saved.leafId === parked.leafId
+        ? saved
+        : undefined;
+}
+/** This child's exact parked generation, if any; mismatched authority restores nothing. */
+export function parkedState(dir, launch, restore) {
+    const parked = read(path.join(dir, "parked.json"), parkedSchema);
+    if (!parked) {
+        return undefined;
+    }
+    if (!restore) {
+        throw new Error("Parked working state needs the Pi fork that saved it; nothing was reopened.");
+    }
+    // Native working state requires a canonical parent, not a symlinked alias like macOS /var.
+    const state = path.join(fs.realpathSync(dir), `working-${parked.token}.json`);
+    const saved = exact(restore, parked, state, launch);
+    if (!saved) {
+        throw new Error("Parked working state is not this child's saved generation; nothing was reopened.");
+    }
+    return { state, saved };
+}
+/** One actor generation's idle parking and exact restore; commands stay with the runner. */
+export class Parking {
+    saved;
+    restored;
+    since = 0;
+    leaf;
+    base;
+    launch;
+    token;
+    sdk;
+    constructor(base, launch, token, sdk) {
+        this.base = base;
+        this.launch = launch;
+        this.token = token;
+        this.sdk = sdk;
+    }
+    get dir() {
+        return runDirectory(this.base, this.launch.rootId);
+    }
+    get file() {
+        return path.join(this.dir, "parked.json");
+    }
+    /** Parked authority is exact state or nothing; never a journal-only reopen. */
+    open() {
+        const { sdk, launch } = this;
+        const { openWorkingSession: restore } = sdk;
+        const parked = parkedState(this.dir, launch, restore && sdk.readWorkingSession);
+        if (!parked || !restore) {
+            return sdk.SessionManager.open(launch.sessionFile, undefined, launch.cwd);
+        }
+        this.saved = parked.saved;
+        this.restored = parked.state;
+        return restore(parked.saved);
+    }
+    /** The ready restored generation owns this state now; a later park writes a new cut. */
+    adopt() {
+        if (this.restored !== undefined) {
+            fs.rmSync(this.file);
+            fs.rmSync(this.restored, { force: true });
+        }
+    }
+    /** True once this generation has exited its runtime with or without parked authority. */
+    async park(runtime, actor) {
+        if (!actor.pi ||
+            !this.due(runtime.session, actor.busy) ||
+            shells(this.base, this.launch, this.token).some(alive)) {
+            return false;
+        }
+        const hold = await this.prepare(runtime, actor.pi, actor);
+        if (hold) {
+            await this.commit(runtime, hold, actor.errors);
+        }
+        return hold !== undefined;
+    }
+    /** Final idle: no run, turn, journal change or viewer since the period began. */
+    due(session, busy) {
+        const leaf = session.sessionManager.getLeafId();
+        if (busy || !session.isIdle || leaf !== this.leaf) {
+            this.leaf = leaf;
+            this.since = performance.now();
+            return false;
+        }
+        return performance.now() - this.since >= PARK_AFTER_MS;
+    }
+    /**
+     * Fence broker input, then hold a settled sleep-ready cut of the same quiet idle leaf. Any
+     * failure or raced command releases, unfences and keeps this actor resident.
+     */
+    async prepare(runtime, pi, { quiet, errors, signal }) {
+        const { session } = runtime;
+        this.since = performance.now();
+        if (!parkable(session) || !this.sdk.writeWorkingSession || !finalizing(runtime)) {
+            return undefined;
+        }
+        // A launcher that enqueues after this marker waits for exit, then wakes the saved state.
+        const marker = path.join(this.dir, "actor.lock", "parking.json");
+        write(marker, { at: Date.now() });
+        const hold = await cut(pi, session, {
+            quiet: () => quiet() && session.sessionManager.getLeafId() === this.leaf,
+            errors,
+            signal,
+        });
+        // Revalidate after the awaited fence and save, immediately before the irreversible commit.
+        if (hold?.sleepReady === true && quiet()) {
+            return hold;
+        }
+        await hold?.release();
+        await fence(pi, false);
+        fs.rmSync(marker, { force: true });
+        return undefined;
+    }
+    /** Commit: native strict exit, then capture; failure leaves no parked authority. */
+    async commit(runtime, hold, errors) {
+        const save = this.sdk.writeWorkingSession;
+        if (save && finalizing(runtime)) {
+            runtime.setFinalization((final) => this.capture(final, save), { strictShutdown: true });
+        }
+        // No await between release and dispose: native final exit fences new turns in this tick.
+        const released = hold.release();
+        const disposed = runtime.dispose();
+        try {
+            await Promise.all([released, disposed]);
+        }
+        catch (error) {
+            errors.push(errorText(error));
+        }
+        if (read(this.file, parkedSchema)?.token !== this.token) {
+            // Truthful boundary: retained input stays queued and nothing restarts implicitly.
+            write(path.join(this.dir, "park-failed.json"), { token: this.token, errors });
+        }
+    }
+    async capture(session, save) {
+        if (!parkable(session)) {
+            throw new Error("Native working state is unavailable.");
+        }
+        const hold = await session.acquireWorkingSession({ boundary: "settled" });
+        try {
+            if (!hold.sleepReady) {
+                throw new Error(`Final working state is not sleep-ready: ${hold.blockers.join("; ")}`);
+            }
+            const state = path.join(fs.realpathSync(this.dir), `working-${this.token}.json`);
+            save(state, hold.state);
+            hold.assertHeld();
+            write(this.file, {
+                token: this.token,
+                state,
+                digest: digest(state),
+                sessionId: this.launch.sessionId,
+                leafId: hold.state.leafId,
+            });
+        }
+        finally {
+            await hold.release();
+        }
+    }
+}
+/** The broker names a parked child by native peer ID; only this owner's conversations match. */
+function ownedRun(runs, peer) {
+    const launch = runs && typeof peer === "string"
+        ? list(runs.base)
+            .map((id) => launchAt(runs.base, id, runs.owner))
+            .find((candidate) => nativePeerId(candidate.sessionId) === peer)
+        : undefined;
+    return launch && runs && latest(runs.base, launch);
+}
+/** The captured leaf's root-to-leaf path, as a live session manager reports it. */
+function branchOf(state) {
+    const entries = new Map(state.entries.map((entry) => [entry.id, entry]));
+    const branch = [];
+    for (let entry = entries.get(state.leafId ?? ""); entry !== undefined; entry = entries.get(entry.parentId ?? "")) {
+        branch.unshift(entry);
+    }
+    return branch;
+}
+async function history(runs, peer) {
+    const launch = ownedRun(runs, peer);
+    const restore = launch && (await loadSDK(launch.sdk)).readWorkingSession;
+    const state = runs && launch && parkedState(conversation(runs.base, launch), launch, restore)?.saved;
+    return state && { getBranch: () => branchOf(state) };
+}
+/**
+ * Wakes this owner's parked children for broker input and reads their saved history.
+ * `runs` is undefined while this session owns no children.
+ */
+export function serveParked(pi, runs, signal) {
+    pi.events.on(WAKE, (peer) => {
+        // On failure, retained input stays queued at the broker until the next main registration.
+        (async () => {
+            const current = runs();
+            const launch = ownedRun(current, peer);
+            if (current && launch) {
+                await wakeActor(current.base, launch, signal);
+            }
+        })().catch((error) => {
+            console.error(`Agent wake: ${errorText(error)}`);
+        });
+    });
+    pi.events.on(PARKED_HISTORY, (request) => {
+        if (isHistoryRequest(request)) {
+            request.reply(history(runs(), request.peer));
+        }
+    });
+}

package/dist/agent/process.js

@@ -7,7 +7,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { isChildProcessReplaced, observeChildProcessReplaced, readChildProcessIdentity, readProcessClock, trySignalChildTree, } from "../shared/post-exit-stdio-guard.js";
 import { agentObservationSocketPath } from "../pi-intercom/broker/paths.js";
 import { hasErrorCode } from "../shared/unknown.js";
-import { attachmentSchema, processSchema } from "./contracts.js";
+import { attachmentSchema, parkedSchema, processSchema, } from "./contracts.js";
 import { conversation, enqueue, launchAt, list, read, write } from "./storage.js";
 import { errorText } from "./host.js";
 /** Owner records follow their process's birth; stat after read only moves the bound later. */
@@ -154,9 +154,12 @@ function spawnActor(base, launch, token) {
     });
 }
 async function awaitStopping(dir, existing, signal) {
-    if (existing && fs.existsSync(path.join(dir, `stopping-${existing.token}.json`))) {
-        const deadline = Date.now() + 5000;
-        while (alive(existing)) {
+    if (existing) {
+        const stopping = path.join(dir, `stopping-${existing.token}.json`);
+        // Parking ends in exit or a removed marker, after native shutdown persistence.
+        const parking = path.join(dir, "actor.lock", "parking.json");
+        const deadline = Date.now() + (fs.existsSync(stopping) ? 5000 : 30_000);
+        while ((fs.existsSync(stopping) || fs.existsSync(parking)) && alive(existing)) {
             signal?.throwIfAborted();
             if (Date.now() > deadline) {
                 throw new Error("Previous actor is still stopping; no replacement was launched.");
@@ -177,6 +180,7 @@ export async function ensureActor(base, launch, signal) {
     if (existing && alive(existing)) {
         return;
     }
+    parkFailure(base, launch, existing);
     if (existing) {
         if (shells(base, launch, existing.token).some(alive)) {
             throw new Error("Owned native shell work remains live; stop it before continuing.");
@@ -199,6 +203,29 @@ export async function ensureActor(base, launch, signal) {
     write(path.join(lock, "claim.json"), { ...ownIdentity(), token });
     spawnActor(base, launch, token);
 }
+/** A failed park keeps its input queued; exact state is lost, so nothing restarts it implicitly. */
+export function parkFailure(base, launch, exited) {
+    const dir = conversation(base, launch);
+    const parked = read(path.join(dir, "parked.json"), parkedSchema);
+    if (exited && parked && parked.token !== exited.token) {
+        // Only the exited claim that saved this state may hand it to the next generation.
+        throw new Error("Parked working state belongs to another actor generation; nothing was reopened.");
+    }
+    const file = path.join(dir, "park-failed.json");
+    if (fs.existsSync(file)) {
+        throw new Error(`This idle child exited without saving its exact working state (${file}). Nothing was restarted or admitted; messages for it stay queued. Inspect it, then delegate new work.`);
+    }
+}
+/** A broker wake may only restore exact parked state, never reopen the journal alone. */
+export async function wakeActor(base, launch, signal) {
+    const dir = conversation(base, launch);
+    await awaitStopping(dir, actor(base, launch), signal);
+    parkFailure(base, launch);
+    if (!fs.existsSync(path.join(dir, "parked.json"))) {
+        throw new Error("No parked working state; the child was not woken.");
+    }
+    await ensureActor(base, launch, signal);
+}
 /** A crashed generation cannot unlink its endpoint; its exact token names the leftover. */
 function removeObservationEndpoint(token) {
     try {