@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/dist/agent/index.js

@@ -0,0 +1,456 @@
+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 { isChild, errorText } from "./host.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 { notifications, deliver, settle } from "./notifications.js";
+import { prepareLaunch } from "./launch.js";
+import { renderReceipt, renderInventory, renderInspection } from "./view.js";
+import { legacyDirectory, legacyNotifications } from "./legacy.js";
+import { DirectoryWatch, pathStamp } from "./wake.js";
+import { savedContinuation } from "./saved.js";
+import { executionCwd } from "./cwd.js";
+import { getPiAgentDir } from "../pi-intercom/agent-dir.js";
+import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.js";
+/** `handoff` and `provisional` mean another worker under the same launcher may still own these children. */
+function retainsChildren(event) {
+    const disposition = Reflect.get(event, "disposition");
+    return disposition === "handoff" || disposition === "provisional";
+}
+function managedHost(context) {
+    const host = Reflect.get(context, "managedHost");
+    if (typeof host !== "object" || host === null) {
+        return undefined;
+    }
+    const owner = Reflect.get(host, "owner");
+    const pid = typeof owner === "object" && owner !== null ? Reflect.get(owner, "pid") : undefined;
+    const ready = Reflect.get(host, "ready");
+    return typeof pid === "number" && Number.isSafeInteger(pid) && ready instanceof Promise
+        ? { owner: { pid }, ready: ready.then((accepted) => accepted === true) }
+        : undefined;
+}
+/** Legacy results are optional; their reconciliation reports an invalid configured root. */
+function legacyInput() {
+    try {
+        return [legacyDirectory()];
+    }
+    catch {
+        return [];
+    }
+}
+class AgentRuntime {
+    ctx;
+    // A managed launcher owns children across worker replacement; otherwise this process does.
+    host;
+    accepted = false;
+    base = "";
+    owner = "";
+    generation = "";
+    // Polling remains only while change hints are unavailable or a reconciliation failed.
+    timer;
+    woken;
+    // Change hints for the owner directory, legacy results and every awaited canonical file.
+    watches = new Map();
+    awaited = new Set();
+    // Input stamps the last reconciliation saw; a one-second probe recovers dropped hints.
+    observed = new Map();
+    probe;
+    closing = false;
+    reset = Promise.resolve();
+    shutdown = new AbortController();
+    child = isChild();
+    agentDir = path.resolve(getPiAgentDir());
+    pi;
+    constructor(pi) {
+        this.pi = pi;
+    }
+    checkMain() {
+        if (isChild()) {
+            throw new Error("Only a main session may delegate or control agent runs.");
+        }
+        if (this.closing || !this.ctx || this.base.length === 0) {
+            throw new Error("Agent runtime is not attached.");
+        }
+    }
+    wake = () => {
+        this.woken ??= setImmediate(() => {
+            this.woken = undefined;
+            this.scan();
+        }).unref();
+    };
+    recover = () => {
+        for (const [file, seen] of this.observed) {
+            if (pathStamp(file) !== seen) {
+                this.wake();
+                return;
+            }
+        }
+    };
+    scan = () => {
+        clearTimeout(this.timer);
+        if (this.closing || !this.ctx || this.child) {
+            return;
+        }
+        const inputs = () => [this.base, ...legacyInput(), ...this.awaited];
+        const before = new Map(inputs().map((file) => [file, pathStamp(file)]));
+        let reconciled = true;
+        try {
+            const { notices, awaited } = notifications(this.ctx, this.base, this.owner);
+            this.awaited = awaited;
+            try {
+                notices.unshift(...legacyNotifications(this.ctx));
+            }
+            catch (error) {
+                console.error(`Legacy completion reconciliation: ${errorText(error)}`);
+            }
+            deliver(this.pi, this.ctx, notices);
+        }
+        catch (error) {
+            reconciled = false;
+            console.error(`Agent completion reconciliation: ${errorText(error)}`);
+        }
+        // Newly awaited files were absent when read, or are rechecked once by the probe.
+        this.observed = new Map(inputs().map((file) => [file, before.get(file) ?? ""]));
+        const next = this.watch();
+        if (!reconciled || next === "poll") {
+            this.timer = setTimeout(this.scan, 200).unref();
+        }
+        else if (next === "rescan") {
+            // Publications before arming had no hint; reconcile once more after it.
+            this.wake();
+        }
+    };
+    /** Watches every directory that can publish an awaited input; legacy results may never exist. */
+    watch() {
+        const legacy = legacyInput();
+        const directories = [
+            ...new Set([this.base, ...legacy, ...[...this.awaited].map((file) => path.dirname(file))]),
+        ];
+        for (const [directory, watch] of this.watches) {
+            if (!directories.includes(directory)) {
+                watch.close();
+                this.watches.delete(directory);
+            }
+        }
+        const states = directories.map((directory) => {
+            let watch = this.watches.get(directory);
+            if (watch === undefined) {
+                const every = directory === this.base || legacy.includes(directory);
+                watch = new DirectoryWatch(directory, (file) => every || file === null || this.awaited.has(path.join(directory, file)), this.wake);
+                this.watches.set(directory, watch);
+            }
+            return [directory, watch.ensure()];
+        });
+        if (states.some(([directory, state]) => state === "unwatched" && !legacy.includes(directory))) {
+            return "poll";
+        }
+        return states.some(([, state]) => state === "armed") ? "rescan" : "hints";
+    }
+    unwatch() {
+        clearTimeout(this.timer);
+        clearInterval(this.probe);
+        this.observed.clear();
+        clearImmediate(this.woken);
+        this.woken = undefined;
+        for (const watch of this.watches.values()) {
+            watch.close();
+        }
+        this.watches.clear();
+        this.awaited = new Set();
+    }
+    start(context) {
+        this.host = managedHost(context);
+        if (this.host === undefined || this.accepted || this.child) {
+            this.reset = this.reset.then(() => this.attach(context));
+            return this.reset;
+        }
+        // Attach and publish only after the launcher retires rollback: an unready replacement
+        // must neither adopt children nor append completions to a journal it may abandon.
+        // Readiness follows session_start, so never await it here.
+        this.owner = context.sessionManager.getSessionId();
+        this.base = ownerDirectory(this.agentDir, this.owner);
+        this.host.ready
+            .then(async (accepted) => {
+            if (accepted && !this.closing) {
+                this.accepted = true;
+                await this.start(context);
+            }
+        })
+            .catch((error) => {
+            console.error(`Agent runtime attachment: ${errorText(error)}`);
+        });
+        return undefined;
+    }
+    ownerIdentity() {
+        return ownIdentity(this.host?.owner.pid);
+    }
+    async attach(context) {
+        this.unwatch();
+        this.ctx = context;
+        if (this.child) {
+            return;
+        }
+        this.owner = context.sessionManager.getSessionId();
+        this.base = ownerDirectory(this.agentDir, this.owner);
+        this.generation = randomUUID();
+        await fs.promises.mkdir(this.base, { recursive: true, mode: 0o700 });
+        write(path.join(this.base, "attachment.json"), {
+            ...this.ownerIdentity(),
+            generation: this.generation,
+            attached: true,
+        });
+        if (this.closing) {
+            return;
+        }
+        // Recovery and watch setup stay off the awaited startup path.
+        this.timer = setTimeout(this.scan, 200).unref();
+        this.probe = setInterval(this.recover, 1000).unref();
+    }
+    async dispose(retain) {
+        this.closing = true;
+        this.unwatch();
+        this.shutdown.abort();
+        await this.reset;
+        if (!retain && this.base.length > 0) {
+            const file = path.join(this.base, "attachment.json");
+            const attachment = read(file, attachmentSchema);
+            if (attachment !== undefined && this.releases(attachment)) {
+                write(file, {
+                    ...this.ownerIdentity(),
+                    generation: attachment.generation,
+                    attached: false,
+                });
+                await stopChildren(this.base, this.owner);
+            }
+        }
+        this.ctx = undefined;
+    }
+    releases(attachment) {
+        if (attachment.generation === this.generation) {
+            return true;
+        }
+        // An unready replacement never attached, but exiting still releases the launcher-owned children.
+        return (this.generation.length === 0 && attachment.attached && attachment.pid === this.host?.owner.pid);
+    }
+    stop(launch) {
+        const base = this.base;
+        const { targets: live, command: id } = requestStop(base, launch);
+        if (live.length === 0) {
+            return renderReceipt(base, launch, this.ctx, {
+                stopAcknowledged: false,
+                note: "No matching live actor or owned shell; process exit code remains unknown.",
+            });
+        }
+        const escalation = setTimeout(() => {
+            try {
+                live.forEach((target) => {
+                    signalProcess(target, "SIGKILL");
+                });
+            }
+            catch (error) {
+                console.error(`Agent stop escalation: ${errorText(error)}`);
+            }
+        }, 3000);
+        escalation.unref();
+        return renderReceipt(base, launch, this.ctx, {
+            stopRequest: id,
+            stopAcknowledged: false,
+            note: "Stop requested; neither native admission nor process exit is implied.",
+        });
+    }
+    async delegate(input, signal, context) {
+        this.checkMain();
+        await this.reset;
+        if (signal?.aborted === true) {
+            throw new Error("Delegation cancelled before launch.");
+        }
+        const launch = await prepareLaunch({
+            input,
+            context,
+            base: this.base,
+            owner: this.owner,
+            agentDir: this.agentDir,
+            thinking: context.thinkingLevel ?? this.pi.getThinkingLevel(),
+            executionCwd: executionCwd(this.pi, context),
+        });
+        this.checkMain();
+        enqueue(this.base, launch, "run");
+        await ensureActor(this.base, launch, this.shutdown.signal);
+        return renderReceipt(this.base, launch, this.ctx, {
+            receipt: "launch",
+            note: "Launch accepted, not completion or native receipt publication. Completion arrives as a notification; do other work or end the turn instead of polling.",
+        });
+    }
+    list(input) {
+        const all = list(this.base)
+            .map((id) => launchAt(this.base, id, this.owner))
+            .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) {
+            return result;
+        }
+        const admission = read(path.join(conversation(this.base, launch), "admissions", `${launch.id}.json`), admissionSchema);
+        if (!admission || admission.id !== launch.id || admission.action !== "run") {
+            return "pending";
+        }
+        return;
+    }
+    async retryContinuation(launch, input) {
+        const identity = actor(this.base, launch);
+        const command = read(path.join(conversation(this.base, launch), "commands", `${launch.id}.json`), commandSchema);
+        if (input.prompt !== launch.prompt ||
+            (identity && alive(identity)) ||
+            command?.id !== launch.id ||
+            command.runId !== launch.id ||
+            command.action !== "run") {
+            throw new Error(`Run ${launch.id} is awaiting native admission. Retry requires the exact saved prompt, its existing queued Run command, and no live actor. Missing commands or ambiguous process claims require inspection. Admission or a canonical result arrives without polling: end the turn or do other work until the completion notification, then inspect once before sending another prompt. No new continuation was launched.`);
+        }
+        // Only an unadmitted durable command is retryable; keep all process/shell claim guards.
+        await ensureActor(this.base, launch, this.shutdown.signal);
+        return renderReceipt(this.base, launch, this.ctx, { receipt: "continuation" });
+    }
+    async continue(launch, input) {
+        if (input.prompt === undefined) {
+            throw new Error("continue requires the entire new prompt.");
+        }
+        if (!fs.existsSync(launch.sessionFile)) {
+            throw new Error("Missing saved native session; no process was launched.");
+        }
+        const completed = this.continuationResult(launch);
+        if (completed === "pending") {
+            return this.retryContinuation(launch, input);
+        }
+        const identity = actor(this.base, launch);
+        if (!completed && identity && alive(identity)) {
+            const command = enqueue(this.base, launch, "steer", { prompt: input.prompt });
+            return renderReceipt(this.base, launch, this.ctx, {
+                receipt: "guidance",
+                command,
+                note: "Guidance queued, not actual completion or model consumption.",
+            });
+        }
+        const next = this.successor(launch, input.prompt);
+        if (!next) {
+            return renderReceipt(this.base, latest(this.base, launch), this.ctx, {
+                receipt: "existing-successor",
+            });
+        }
+        // Retain successor claims on ambiguous after-launch failures: no replay.
+        enqueue(this.base, next, "run");
+        await ensureActor(this.base, next, this.shutdown.signal);
+        return renderReceipt(this.base, next, this.ctx, { receipt: "continuation" });
+    }
+    async continueSaved(input, context) {
+        if (input.prompt === undefined) {
+            throw new Error("continue requires the entire new prompt.");
+        }
+        const { launch, created } = savedContinuation({
+            id: input.id,
+            prompt: input.prompt,
+            context,
+            base: this.base,
+            agentDir: this.agentDir,
+        });
+        if (created) {
+            // The durable adoption claim survives ambiguous after-launch failures.
+            enqueue(this.base, launch, "run");
+            await ensureActor(this.base, launch, this.shutdown.signal);
+        }
+        return renderReceipt(this.base, launch, this.ctx, {
+            receipt: created ? "continuation" : "existing-successor",
+        });
+    }
+    async runs(input, context) {
+        this.checkMain();
+        await this.reset;
+        if (input.action === "list") {
+            return this.list(input);
+        }
+        this.scan();
+        if (input.id === undefined) {
+            throw new Error("id is required.");
+        }
+        if (input.action === "continue" &&
+            !fs.existsSync(path.join(runDirectory(this.base, input.id), "launch.json"))) {
+            return this.continueSaved({ ...input, id: input.id }, context);
+        }
+        const original = launchAt(this.base, input.id, this.owner);
+        if (input.action === "inspect") {
+            return renderInspection(this.base, original, this.ctx, input);
+        }
+        const launch = latest(this.base, original);
+        if (input.action === "stop") {
+            return this.stop(launch);
+        }
+        return this.continue(launch, input);
+    }
+    register() {
+        registerCompactMessages(this.pi, ["agent-completion", "subagent-notify"]);
+        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.
+            if (settle(this.owner, context.hasPendingMessages() || event.context.pendingMessages.length > 0)) {
+                // Released admissions may have been dropped from the queue rather than published.
+                this.wake();
+            }
+        });
+        this.pi.on("agent_settled", () => {
+            this.scan();
+        });
+        this.pi.on("session_shutdown", (event) => this.dispose(event.reason === "reload" || retainsChildren(event)));
+        if (this.child) {
+            this.pi.on("tool_call", (event) => {
+                if (event.toolName === "delegate" || event.toolName === "agent_runs") {
+                    return { block: true, reason: "Only main sessions may delegate or control agent runs." };
+                }
+                return;
+            });
+        }
+        const execute = (...args) => this.delegate(args[1], args[2], args[4]);
+        this.pi.registerTool({
+            name: "delegate",
+            label: "Delegate",
+            description: "Run a child on exactly this prompt; main sessions only. Fork copies the full conversation; default is fresh. Returns a receipt; completion is notified later: do other work or end the turn, don't poll.",
+            parameters: delegateSchema,
+            exposure: this.child ? "hidden" : "direct",
+            renderResult: renderCompactResult,
+            execute,
+        });
+        const runs = (...args) => this.runs(args[1], args[4]);
+        this.pi.registerTool({
+            name: "agent_runs",
+            label: "Agent runs",
+            description: "Manage your child runs without waiting; completions are notified. Inspect pages by byte offset, never interrupting. Continue takes the complete new prompt: it steers a live child or resumes the saved conversation.",
+            parameters: runsSchema,
+            exposure: this.child ? "hidden" : "direct",
+            renderResult: renderCompactResult,
+            execute: runs,
+        });
+    }
+}
+export default function agents(pi) {
+    new AgentRuntime(pi).register();
+}

package/dist/agent/journal-tail.js

@@ -0,0 +1,142 @@
+import * as fs from "node:fs";
+import { NativeJournal } from "../shared/native-journal.js";
+import { nativeProjection } from "../shared/journal-projections.js";
+import { isRecord, recordAt } from "../shared/unknown.js";
+export function plainText(value, length = 512) {
+    return Array.from(value.slice(0, length))
+        .map((char) => {
+        const code = char.codePointAt(0) ?? 0;
+        return code < 32 || (code >= 127 && code <= 159) ? " " : char;
+    })
+        .join("");
+}
+const PAGE_CHARS = 32 * 1024;
+const callFields = new Set(["type", "id", "name"]);
+const textFields = new Set(["text", "thinking"]);
+const metadata = (keys, root) => {
+    if (keys[0] === "message" &&
+        keys[1] === "content" &&
+        keys.length > 3 &&
+        !callFields.has(String(keys[3]))) {
+        return false;
+    }
+    return nativeProjection(keys, root);
+};
+function contentIndex(keys) {
+    if (keys[0] !== "message" || keys[1] !== "content") {
+        return undefined;
+    }
+    if (keys.length === 2) {
+        return -1;
+    }
+    return typeof keys[2] === "number" && textFields.has(String(keys[3])) ? keys[2] : undefined;
+}
+class TextPage {
+    chars = 0;
+    carry;
+    text = new Map();
+    start;
+    constructor(page) {
+        this.start = page * PAGE_CHARS;
+    }
+    add(index, chunk) {
+        const previous = this.carry;
+        this.carry = undefined;
+        if (previous && previous.index !== index) {
+            this.take(previous.index, previous.text);
+        }
+        const text = previous?.index === index ? previous.text + chunk : chunk;
+        const last = text.charCodeAt(text.length - 1);
+        const pending = last >= 0xd800 && last <= 0xdbff;
+        this.take(index, pending ? text.slice(0, -1) : text);
+        if (pending) {
+            this.carry = { index, text: text.slice(-1) };
+        }
+    }
+    take(index, text) {
+        const points = Array.from(text);
+        const from = Math.max(0, this.start - this.chars);
+        const to = Math.min(points.length, this.start + PAGE_CHARS - this.chars);
+        if (to > from) {
+            this.text.set(index, (this.text.get(index) ?? "") + points.slice(from, to).join(""));
+        }
+        this.chars += points.length;
+    }
+    finish(value, page) {
+        if (this.carry) {
+            this.take(this.carry.index, this.carry.text);
+        }
+        const message = { ...recordAt(value, "message") };
+        if (typeof message.content === "string") {
+            message.content = this.text.get(-1) ?? "";
+        }
+        if (Array.isArray(message.content)) {
+            for (const [index, block] of message.content.entries()) {
+                if (isRecord(block) && typeof block.type === "string" && textFields.has(block.type)) {
+                    block[block.type] = this.text.get(index) ?? "";
+                }
+            }
+        }
+        return { message, page, pages: Math.max(1, Math.ceil(this.chars / PAGE_CHARS)) };
+    }
+}
+/** Native indexing owns ancestry and publication; only requested message pages are hydrated. */
+export class ConversationJournal {
+    native;
+    branch;
+    constructor(file, sessionId) {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error("Child journal is not a regular file.");
+        }
+        this.native = new NativeJournal(file, "live", true, {
+            readBytes: 256 * 1024,
+            select: metadata,
+        });
+        if (this.native.records[0]?.value.id !== sessionId) {
+            throw new Error("Native journal identity does not match this child.");
+        }
+    }
+    entries(requested) {
+        const leaf = typeof requested === "string" && !this.native.byId.has(requested) ? undefined : requested;
+        if (this.branch?.length !== this.native.records.length || this.branch.leaf !== leaf) {
+            this.branch = {
+                length: this.native.records.length,
+                leaf,
+                entries: this.native.branch(leaf).filter((entry) => entry.value.type === "message"),
+            };
+        }
+        return this.branch.entries;
+    }
+    async call(id, result, signal) {
+        const contains = (entry) => {
+            const content = recordAt(entry.value, "message")?.content;
+            return (Array.isArray(content) &&
+                content.some((part) => isRecord(part) && part.type === "toolCall" && part.id === id));
+        };
+        const entries = this.branch?.entries ?? [];
+        const entry = entries
+            .slice(0, entries.findIndex((item) => item.value.id === result))
+            .findLast(contains);
+        const content = entry && (await this.page(entry, 0, { signal })).message.content;
+        return Array.isArray(content)
+            ? content.find((part) => isRecord(part) && part.type === "toolCall" && part.id === id)
+            : undefined;
+    }
+    async page(entry, page = 0, options = {}) {
+        const text = new TextPage(page);
+        const value = await this.native.project(entry, (keys, root) => {
+            if (contentIndex(keys) !== undefined && keys.length > 2) {
+                return 0;
+            }
+            return nativeProjection(keys, root);
+        }, (keys, chunk) => {
+            const index = contentIndex(keys);
+            if (index === undefined || (options.hideThinking === true && keys[3] === "thinking")) {
+                return;
+            }
+            text.add(index, chunk);
+        }, options.signal);
+        return text.finish(value, page);
+    }
+}