@fitchmultz/pi-subagents 0.49.0 → 0.50.0

package/dist/agent/process.js

@@ -0,0 +1,173 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { readChildProcessIdentity, trySignalChildTree } from "../shared/post-exit-stdio-guard.js";
+import { processSchema } from "./contracts.js";
+import { conversation, read, write } from "./storage.js";
+export function alive(identity) {
+    try {
+        process.kill(identity.pid, 0);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false;
+        }
+        return true;
+    }
+    const actual = readChildProcessIdentity(identity.pid);
+    return identity.identity === "unverified" || actual === undefined || actual === identity.identity;
+}
+export function ownIdentity() {
+    // An ordinary main need not be a group leader. Ambiguous live PIDs fail closed.
+    return { pid: process.pid, identity: readChildProcessIdentity(process.pid) ?? "unverified" };
+}
+export function actor(base, launch) {
+    return read(path.join(conversation(base, launch), "actor.lock", "process.json"), processSchema);
+}
+function childEnvironment(launch) {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (key.startsWith("PI_SUBAGENT_") ||
+            ["PI_SESSION_FILE", "PI_SESSION_ID", "PI_INTERCOM_SESSION_NAME"].includes(key)) {
+            delete env[key];
+        }
+    }
+    return Object.assign(env, {
+        PI_PACKAGE_DIR: launch.sdk,
+        PI_CODING_AGENT_DIR: launch.agentDir,
+        PI_INTERCOM_ROOT_SESSION_ID: launch.owner,
+        PI_INTERCOM_PARENT_SESSION_ID: launch.owner,
+    });
+}
+function spawnActor(base, launch, token) {
+    const dir = conversation(base, launch);
+    const log = fs.openSync(path.join(dir, "runner.log"), "a", 0o600);
+    const runner = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./runner.ts" : "./runner.js", import.meta.url));
+    let child;
+    try {
+        child = spawn(process.execPath, [runner, base, launch.rootId, token, launch.id], {
+            cwd: launch.cwd,
+            env: childEnvironment(launch),
+            detached: true,
+            stdio: ["ignore", log, log],
+        });
+    }
+    finally {
+        fs.closeSync(log);
+    }
+    child.on("error", (error) => {
+        write(path.join(dir, "spawn-error.json"), { error: error.message });
+    });
+    child.on("exit", (code, signal) => {
+        write(path.join(dir, `exit-${token}.json`), { pid: child.pid, code, signal, at: Date.now() });
+        trySignalChildTree(child, "SIGKILL");
+    });
+    child.unref();
+    if (child.pid === undefined) {
+        throw new Error("Actor was not spawned; retained launch claim requires inspection.");
+    }
+    write(path.join(dir, "actor.lock", "process.json"), {
+        pid: child.pid,
+        identity: readChildProcessIdentity(child.pid) ?? "unverified",
+        token,
+    });
+}
+async function awaitStopping(dir, existing) {
+    if (existing && fs.existsSync(path.join(dir, `stopping-${existing.token}.json`))) {
+        const deadline = Date.now() + 5000;
+        while (alive(existing)) {
+            if (Date.now() > deadline) {
+                throw new Error("Previous actor is still stopping; no replacement was launched.");
+            }
+            // The old actor must actually exit before replacing its generation.
+            // oxlint-disable-next-line no-await-in-loop
+            await delay(25);
+        }
+    }
+}
+export async function ensureActor(base, launch) {
+    const dir = conversation(base, launch);
+    const lock = path.join(dir, "actor.lock");
+    await awaitStopping(dir, actor(base, launch));
+    // Another parallel tool may replace the claim while this invocation yields.
+    const existing = actor(base, launch);
+    if (existing && alive(existing)) {
+        return;
+    }
+    if (existing) {
+        if (shells(base, launch, existing.token).some(alive)) {
+            throw new Error("Owned native shell work remains live; stop it before continuing.");
+        }
+        fs.rmSync(lock, { recursive: true });
+    }
+    try {
+        fs.mkdirSync(lock);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+            throw new Error("Actor launch is ambiguous; retained claim prevents duplicate launch.", {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    const token = randomUUID();
+    write(path.join(lock, "claim.json"), { ...ownIdentity(), token });
+    spawnActor(base, launch, token);
+}
+function verifyLiveness(pid) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false;
+        }
+        throw new Error("Actor liveness is ambiguous; no stop was sent.", { cause: error });
+    }
+    return true;
+}
+export function verifyProcess(identity) {
+    if (!verifyLiveness(identity.pid)) {
+        return false;
+    }
+    const actual = readChildProcessIdentity(identity.pid);
+    if (identity.identity !== "unverified" && actual === undefined && !verifyLiveness(identity.pid)) {
+        // Native abort can reap a shell between the liveness probe and birth lookup.
+        return false;
+    }
+    if (identity.identity === "unverified" || actual !== identity.identity) {
+        throw new Error("Cannot verify actor process identity; no signal sent.");
+    }
+    return true;
+}
+export function signalProcess(identity, signal) {
+    if (!verifyProcess(identity)) {
+        return false;
+    }
+    return trySignalChildTree({ pid: identity.pid, kill: (s) => process.kill(identity.pid, s) }, signal);
+}
+export function shells(base, launch, token) {
+    const dir = path.join(conversation(base, launch), "shells", token);
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    return fs.readdirSync(dir).map((name) => {
+        const identity = read(path.join(dir, name), processSchema);
+        if (!identity || identity.token !== token) {
+            throw new Error("Foreign or missing native shell identity.");
+        }
+        return identity;
+    });
+}
+function quote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function shellCommand(command, directory, token) {
+    const helper = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./shell.ts" : "./shell.js", import.meta.url));
+    const register = [process.execPath, helper, directory, token].map(quote).join(" ");
+    return `if ! ${register} "$$"; then exit 125; fi\n${command}`;
+}

package/dist/agent/receipts.js

@@ -0,0 +1,75 @@
+import * as fs from "node:fs";
+import { scanJournal } from "../shared/journal-frames.js";
+import { journalStamp } from "../shared/native-journal.js";
+const detailFields = new Set([
+    "owner",
+    "id",
+    "completed",
+    "receivedResult",
+    "completion",
+    "subagentCompletion",
+    "wait",
+]);
+function detailsProjection(details) {
+    if (details[0] !== "details") {
+        return false;
+    }
+    if (details.length === 1) {
+        return true;
+    }
+    if (details.length === 2) {
+        return detailFields.has(String(details[1])) ? 4096 : false;
+    }
+    return details.length === 3 &&
+        ["completion", "subagentCompletion", "wait"].includes(String(details[1])) &&
+        ["runId", "key", "ownerSessionId", "completionId", "status", "index"].includes(String(details[2]))
+        ? 4096
+        : false;
+}
+const receiptProjection = (keys) => {
+    if (keys.length === 0) {
+        return true;
+    }
+    if (["type", "id", "customType"].includes(String(keys[0]))) {
+        return keys.length === 1 ? 4096 : false;
+    }
+    if (keys[0] !== "message") {
+        return detailsProjection(keys);
+    }
+    if (keys.length === 1) {
+        return true;
+    }
+    if (["role", "toolName", "isError"].includes(String(keys[1]))) {
+        return keys.length === 2 ? 4096 : false;
+    }
+    return detailsProjection(keys.slice(1));
+};
+/** Physical LF publication owns delivery, including when native memory is stale. */
+export function receiptId(file, owner, matches) {
+    if (file === undefined || !fs.existsSync(file)) {
+        return;
+    }
+    const fd = fs.openSync(file, "r");
+    let first = true;
+    let owned = false;
+    let found;
+    try {
+        const stamp = journalStamp(fs.fstatSync(fd, { bigint: true }));
+        scanJournal(fd, receiptProjection, ({ value }) => {
+            if (first) {
+                first = false;
+                owned = value.type === "session" && value.id === owner;
+            }
+            else if (owned && found === undefined && typeof value.id === "string" && matches(value)) {
+                found = value.id;
+            }
+        }, { policy: "live", requireNewline: true });
+        if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== stamp) {
+            throw new Error("Native receipt journal changed while reading.");
+        }
+        return found;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

package/dist/agent/runner.js

@@ -0,0 +1,372 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { attachmentSchema, commandSchema, } from "./contracts.js";
+import { launchAt, read, runDirectory, write } from "./storage.js";
+import { alive, ownIdentity, shellCommand } from "./process.js";
+import { errorText, loadSDK } from "./host.js";
+import { childUsage } from "./usage.js";
+import { initializeCwd, localCwdOwner } from "./cwd.js";
+function completionStatus(stopping, message, error) {
+    if (stopping || message?.stopReason === "aborted") {
+        return "stopped";
+    }
+    if (error !== undefined || !message || message.stopReason === "error") {
+        return "failed";
+    }
+    return "completed";
+}
+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;
+    });
+}
+class Actor {
+    active;
+    stopping = false;
+    current;
+    errors = [];
+    started = new Set();
+    session;
+    context;
+    base;
+    initial;
+    token;
+    constructor(base, initial, token) {
+        this.base = base;
+        this.initial = initial;
+        this.token = token;
+    }
+    get dir() {
+        return runDirectory(this.base, this.initial.rootId);
+    }
+    response(baseline) {
+        const session = this.session;
+        if (!session) {
+            throw new Error("Native child session is not ready.");
+        }
+        const terminal = session.sessionManager
+            .getBranch()
+            .findLast((entry) => !baseline.has(entry.id) && entry.type === "message" && entry.message.role === "assistant");
+        if (terminal?.type !== "message" || terminal.message.role !== "assistant") {
+            return;
+        }
+        return { id: terminal.id, message: terminal.message };
+    }
+    saveResult(launch, baseline, error) {
+        const terminal = this.response(baseline);
+        const message = terminal?.message;
+        const accounting = this.usage(launch, baseline, terminal?.id);
+        const output = this.output(message);
+        const result = {
+            id: launch.id,
+            owner: launch.owner,
+            status: completionStatus(this.stopping, message, error),
+            endedAt: Date.now(),
+            terminalEntryId: accounting.accountingError === undefined ? terminal?.id : undefined,
+            ...accounting,
+            error: error ??
+                message?.errorMessage ??
+                (message ? undefined : "Native run produced no terminal assistant message."),
+        };
+        fs.writeFileSync(path.join(runDirectory(this.base, launch.id), "output.txt"), output, {
+            mode: 0o600,
+        });
+        write(path.join(runDirectory(this.base, launch.id), "result.json"), result);
+    }
+    usage(launch, baseline, terminal) {
+        try {
+            return { contributions: childUsage(launch, baseline, terminal) };
+        }
+        catch (error) {
+            return {
+                accountingError: errorText(error),
+                ...(terminal !== undefined
+                    ? { accountingPending: { terminalCandidate: terminal, baseline: [...baseline] } }
+                    : {}),
+            };
+        }
+    }
+    output(message) {
+        return (message?.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("\n") ?? "");
+    }
+    createRuntime(sdk) {
+        return async ({ sessionManager }) => {
+            const launch = this.initial;
+            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({
+                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, this.dir, this.token);
+                            pi.on("session_start", (_event, ctx) => {
+                                this.context = { pi, ctx };
+                            });
+                        },
+                    ],
+                },
+            });
+            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({
+                    services,
+                    sessionManager,
+                    model,
+                    thinkingLevel: launch.thinking,
+                })),
+                services,
+                diagnostics: services.diagnostics,
+            };
+        };
+    }
+    stop = () => {
+        write(path.join(this.dir, "stop-acknowledged.json"), { at: Date.now(), id: this.current?.id });
+        this.stopping = true;
+        this.session?.abort().catch((error) => {
+            this.errors.push(errorText(error));
+        });
+    };
+    run(launch) {
+        const session = this.session;
+        if (!session) {
+            throw new Error("Native child session is not ready.");
+        }
+        this.current = launch;
+        const baseline = new Set(session.sessionManager.getEntries().map((entry) => entry.id));
+        this.active = (async () => {
+            try {
+                if (launch.provider !== this.initial.provider ||
+                    launch.model !== this.initial.model ||
+                    launch.thinking !== this.initial.thinking) {
+                    throw new Error("Continuation model snapshot changed unexpectedly.");
+                }
+                await session.prompt(launch.prompt, { expandPromptTemplates: false });
+                await session.waitForIdle();
+                this.saveResult(launch, baseline);
+            }
+            catch (error) {
+                this.saveResult(launch, baseline, errorText(error));
+            }
+            finally {
+                this.active = undefined;
+                this.current = undefined;
+            }
+        })();
+    }
+    commandLaunch(command) {
+        const receipt = path.join(this.dir, "admissions", `${command.id}.json`);
+        if (fs.existsSync(receipt) || this.started.has(command.id)) {
+            return undefined;
+        }
+        if (command.action === "run" &&
+            fs.existsSync(path.join(runDirectory(this.base, command.runId), "successor.json"))) {
+            // A durable handoff supersedes even an unadmitted predecessor; never replay it.
+            return undefined;
+        }
+        const launch = launchAt(this.base, command.runId, this.initial.owner);
+        if (launch.rootId !== this.initial.rootId || launch.sessionFile !== this.initial.sessionFile) {
+            throw new Error("Foreign conversation command.");
+        }
+        return launch;
+    }
+    accept(command) {
+        const session = this.session;
+        if (!session) {
+            throw new Error("Native child session is not ready.");
+        }
+        const receipt = path.join(this.dir, "admissions", `${command.id}.json`);
+        const launch = this.commandLaunch(command);
+        if (!launch) {
+            return;
+        }
+        if (command.action === "run" &&
+            (this.stopping || this.active !== undefined || !session.isIdle)) {
+            return;
+        }
+        this.started.add(command.id);
+        const stale = this.staleCommand(command, launch, session);
+        // This is queue admission, never a claim of native journal publication.
+        write(receipt, {
+            id: command.id,
+            runId: launch.id,
+            action: command.action,
+            state: stale ? "stale" : "accepted",
+            at: Date.now(),
+        }, true);
+        if (stale) {
+            return;
+        }
+        this.applyCommand(command, launch, session);
+    }
+    staleCommand(command, launch, session) {
+        // Unbound legacy Stops cannot safely target this generation either.
+        if (command.action === "stop") {
+            return command.actorToken !== this.token;
+        }
+        return (command.action === "steer" &&
+            (this.active === undefined || session.isIdle || this.current?.id !== launch.id));
+    }
+    applyCommand(command, launch, session) {
+        if (command.action === "stop") {
+            this.stop();
+            return;
+        }
+        if (command.action === "run") {
+            this.run(launch);
+            return;
+        }
+        if (command.prompt === undefined) {
+            throw new Error("Missing guidance.");
+        }
+        // Synchronous native queue admission cannot turn into an idle prompt after an await.
+        session.agent.steer({
+            role: "user",
+            content: [{ type: "text", text: command.prompt }],
+            timestamp: Date.now(),
+        });
+    }
+    pending() {
+        const dir = path.join(this.dir, "commands");
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        return fs
+            .readdirSync(dir)
+            .filter((file) => file.endsWith(".json"))
+            .flatMap((file) => {
+            const command = read(path.join(dir, file), commandSchema);
+            return command ? [command] : [];
+        })
+            .sort((a, b) => a.createdAt - b.createdAt);
+    }
+    shouldExit() {
+        if (this.active !== undefined) {
+            return false;
+        }
+        if (this.stopping) {
+            return true;
+        }
+        if (this.session && (!this.session.isIdle || this.session.pendingMessageCount > 0)) {
+            return false;
+        }
+        const attachment = read(path.join(this.base, "attachment.json"), attachmentSchema);
+        return attachment === undefined || !attachment.attached || !alive(attachment);
+    }
+    failure(error) {
+        const launch = this.current ?? this.initial;
+        const result = {
+            id: launch.id,
+            owner: launch.owner,
+            status: this.stopping ? "stopped" : "failed",
+            endedAt: Date.now(),
+            error: errorText(error),
+        };
+        const directory = runDirectory(this.base, launch.id);
+        if (!fs.existsSync(path.join(directory, "result.json"))) {
+            fs.writeFileSync(path.join(directory, "output.txt"), "", { mode: 0o600 });
+            write(path.join(directory, "result.json"), result);
+        }
+        process.exitCode = 1;
+    }
+    async serve() {
+        const sdk = await loadSDK(this.initial.sdk);
+        let runtime;
+        try {
+            runtime = await sdk.createAgentSessionRuntime(this.createRuntime(sdk), {
+                cwd: this.initial.cwd,
+                agentDir: this.initial.agentDir,
+                sessionManager: sdk.SessionManager.open(this.initial.sessionFile, undefined, this.initial.cwd),
+            });
+            this.session = runtime.session;
+            await this.session.bindExtensions({
+                mode: "print",
+                onError: (error) => {
+                    this.errors.push(error.error);
+                },
+            });
+            if (!this.context) {
+                throw new Error("Child extension context is unavailable.");
+            }
+            initializeCwd(this.context.pi, this.context.ctx, this.initial.cwd, this.dir);
+            if (this.initial.name !== undefined) {
+                this.session.sessionManager.appendSessionInfo(this.initial.name);
+            }
+            write(path.join(this.dir, "actor.lock", "process.json"), {
+                ...ownIdentity(),
+                token: this.token,
+            });
+            write(path.join(this.dir, "ready.json"), {
+                pid: process.pid,
+                token: this.token,
+                sessionId: this.session.sessionManager.getSessionId(),
+                at: Date.now(),
+            });
+            process.on("SIGTERM", this.stop);
+            process.on("SIGINT", this.stop);
+            do {
+                this.pending().forEach((command) => this.accept(command));
+                // Durable command readiness, not elapsed time, defines admission.
+                // oxlint-disable-next-line no-await-in-loop
+                await delay(100);
+            } while (!this.shouldExit());
+            await this.active;
+        }
+        catch (error) {
+            this.failure(error);
+        }
+        finally {
+            process.off("SIGTERM", this.stop);
+            process.off("SIGINT", this.stop);
+            await runtime?.dispose();
+            write(path.join(this.dir, `shutdown-${this.token}.json`), {
+                at: Date.now(),
+                errors: this.errors,
+            });
+            // Keep the process claim until a launcher proves this exact actor is gone.
+        }
+    }
+}
+const base = process.argv.at(2);
+const rootId = process.argv.at(3);
+const token = process.argv.at(4);
+const firstId = process.argv.at(5);
+if (base === undefined || rootId === undefined || token === undefined || firstId === undefined) {
+    throw new Error("Expected saved conversation and actor claim.");
+}
+await new Actor(base, launchAt(base, firstId, path.basename(base)), token).serve();