@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/dist/agent/shell.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { readChildProcessIdentity } from "../shared/post-exit-stdio-guard.js";
+import { readChildProcessIdentity, readProcessClock } from "../shared/post-exit-stdio-guard.js";
 import { read, write } from "./storage.js";
 import { processSchema } from "./contracts.js";
 import { verifyProcess } from "./process.js";
@@ -39,5 +39,6 @@ write(path.join(directory, "shells", token, `${randomUUID()}.json`), {
     pid,
     identity,
     token,
+    clock: readProcessClock(),
 }, true);
 verifyOwner(directory, token);

package/dist/agent/storage.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { readJsonProjection } from "../shared/journal-frames.js";
 import { Assert } from "./typebox.js";
 import { launchSchema, successorSchema } from "./contracts.js";
+import { hasErrorCode } from "../shared/unknown.js";
 export function missing(error) {
     return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
@@ -19,31 +20,47 @@ export function read(file, schema, select = () => true) {
         throw error;
     }
     Assert(schema, value);
-    // TypeBox's generic Static<T> is intentionally the asserted schema's type.
-    // oxlint-disable-next-line typescript/no-unsafe-return
     return value;
 }
-export function write(file, value, exclusive = false) {
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    const temp = `${file}.${randomUUID()}.tmp`;
-    const fd = fs.openSync(temp, "wx", 0o600);
+/** Publish complete bytes without replacing a winner, even where Android denies hard links. */
+function publishExclusive(temp, file) {
     try {
-        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
-        fs.fsyncSync(fd);
+        fs.linkSync(temp, file);
+        return false;
     }
-    finally {
-        fs.closeSync(fd);
+    catch (error) {
+        if (!["EACCES", "EPERM", "ENOTSUP"].some((code) => hasErrorCode(error, code))) {
+            throw error;
+        }
+        // The immutable, private backing file must outlive its atomic no-clobber symlink.
+        fs.symlinkSync(path.basename(temp), file);
+        return true;
     }
+}
+export function write(file, value, exclusive = false) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${randomUUID()}.${exclusive ? "data" : "tmp"}`;
+    const fd = fs.openSync(temp, "wx", 0o600);
+    let retained = false;
     try {
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
         if (exclusive) {
-            fs.linkSync(temp, file);
+            retained = publishExclusive(temp, file);
         }
         else {
             fs.renameSync(temp, file);
         }
     }
     finally {
-        fs.rmSync(temp, { force: true });
+        if (!retained) {
+            fs.rmSync(temp, { force: true });
+        }
     }
 }
 export function safeId(id) {

package/dist/agent/tool-schemas.js

@@ -0,0 +1,20 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "./typebox.js";
+// Main-session tool parameters only; the detached runner must not load pi-ai values.
+export const delegateSchema = Type.Object({
+    prompt: Type.String({ minLength: 1 }),
+    name: Type.Optional(Type.String({ minLength: 1 })),
+    cwd: Type.Optional(Type.String({ minLength: 1 })),
+    model: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Exact provider/model ID (:thinking and any case need host support); no fuzzy match or fallback.",
+    })),
+    context: Type.Optional(StringEnum(["fresh", "fork"])),
+}, { additionalProperties: false });
+export const runsSchema = Type.Object({
+    action: StringEnum(["list", "inspect", "continue", "stop"]),
+    id: Type.Optional(Type.String()),
+    prompt: Type.Optional(Type.String({ minLength: 1 })),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    length: Type.Optional(Type.Integer({ minimum: 4, maximum: 262144 })),
+}, { additionalProperties: false });

package/dist/agent/typebox.js

@@ -9,12 +9,17 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
-import { packageRoot } from "./host.js";
-const require = createRequire(path.join(packageRoot(), "dist/index.js"));
-// The detached runner needs the selected host's dependencies, not Jiti aliases.
+import { isChild, packageRoot } from "./host.js";
+// Pi aliases these imports to its own instance (including bundled virtual modules).
+// Only the detached runner needs absolute imports from the selected host package.
+const require = isChild() ? createRequire(path.join(packageRoot(), "dist/index.js")) : undefined;
 // oxlint-disable-next-line typescript/no-unsafe-assignment
-const typebox = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox")).href));
+const typebox = require === undefined
+    ? await import("typebox")
+    : await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox")).href));
 // oxlint-disable-next-line typescript/no-unsafe-assignment
-const value = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox/value")).href));
+const value = require === undefined
+    ? await import("typebox/value")
+    : await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("typebox/value")).href));
 export const { Type } = typebox;
 export const Assert = value.Assert;

package/dist/agent/usage.js

@@ -1,127 +1,12 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { journalStamp } from "../shared/native-journal.js";
-import { isDeepStrictEqual } from "node:util";
 import { nativeProjection } from "../shared/journal-projections.js";
 import { scanJournal } from "../shared/journal-frames.js";
 import { isRecord } from "../shared/unknown.js";
 import { Assert } from "./typebox.js";
 import { contributionsSchema, resultSchema, } from "./contracts.js";
 import { read, runDirectory, write } from "./storage.js";
-export function sumUsage(values) {
-    const total = {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        totalTokens: 0,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-    };
-    for (const { usage } of values) {
-        for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"]) {
-            total[key] += usage[key];
-        }
-        for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"]) {
-            total.cost[key] += usage.cost[key];
-        }
-        for (const key of ["reasoning", "cacheWrite1h"]) {
-            if (usage[key] !== undefined) {
-                total[key] = (total[key] ?? 0) + usage[key];
-            }
-        }
-    }
-    return total;
-}
-function intents(details) {
-    if (!isRecord(details) || details.agentUsage === undefined) {
-        return;
-    }
-    const values = details.agentUsage;
-    Assert(contributionsSchema, values);
-    return values;
-}
-function publishedContributions(entry) {
-    if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message)) {
-        return [];
-    }
-    const message = entry.message;
-    if (message.role !== "toolResult" ||
-        (message.toolName !== "delegate" && message.toolName !== "agent_runs")) {
-        return [];
-    }
-    const values = intents(message.details);
-    if (values === undefined || !isDeepStrictEqual(sumUsage(values), message.usage)) {
-        return [];
-    }
-    return values;
-}
-const receiptProjection = (keys) => {
-    if (keys.length === 0 || keys[0] === "type") {
-        return true;
-    }
-    if (keys[0] !== "message") {
-        return false;
-    }
-    if (keys.length === 1 || ["role", "toolName", "usage"].includes(String(keys[1]))) {
-        return true;
-    }
-    return keys[1] === "details" && (keys.length === 2 || keys[2] === "agentUsage");
-};
-function priorUsage(ctx) {
-    const values = new Map();
-    const file = ctx.sessionManager.getSessionFile();
-    if (file !== undefined) {
-        scanJournal(file, receiptProjection, ({ value: entry }) => {
-            for (const value of publishedContributions(entry)) {
-                values.set(value.id, value);
-            }
-        }, { policy: "live", requireNewline: true });
-    }
-    for (const entry of ctx.sessionManager.getEntries()) {
-        for (const value of publishedContributions(entry)) {
-            values.set(value.id, value);
-        }
-    }
-    return values;
-}
-function uncharged(values, prior) {
-    const pending = [];
-    for (const value of values) {
-        const earlier = prior.get(value.id);
-        if (earlier && !isDeepStrictEqual(earlier, value)) {
-            throw new Error(`Conflicting native usage contribution ${value.id}`);
-        }
-        if (!earlier) {
-            pending.push(value);
-            prior.set(value.id, value);
-        }
-    }
-    return pending;
-}
-export function registerUsage(pi) {
-    pi.on("message_end", (event, ctx) => {
-        const message = event.message;
-        if (message.role !== "toolResult" ||
-            (message.toolName !== "delegate" && message.toolName !== "agent_runs")) {
-            return;
-        }
-        const values = intents(message.details);
-        if (values === undefined || !isRecord(message.details)) {
-            return;
-        }
-        const pending = uncharged(values, priorUsage(ctx));
-        const { usage: _usage, ...rest } = message;
-        // Finalized native tool messages are serialized even for concurrent tools.
-        // Preparing or discarding a result cannot reserve a charge.
-        return {
-            message: {
-                ...rest,
-                details: { ...message.details, agentUsage: pending },
-                ...(pending.length > 0 ? { usage: sumUsage(pending) } : {}),
-            },
-        };
-    });
-}
 function billing(entry) {
     if (entry.checkpoint === true) {
         return;

package/dist/agent/view.js

@@ -1,23 +1,38 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readOutputPage } from "../shared/output-page.js";
-import { actor, alive } from "./process.js";
+import { actor, alive, observeAlive } from "./process.js";
 import { admissionSchema, commandSchema, exitSchema, successorSchema, } from "./contracts.js";
 import { conversation, read, runDirectory } from "./storage.js";
 import { published } from "./notifications.js";
 import { readCanonicalResult, readResult } from "./usage.js";
 import { Type } from "./typebox.js";
 const commandMetadataSchema = Type.Pick(commandSchema, ["id", "runId", "action", "createdAt"]);
-export function toolResult(value, text = JSON.stringify(value, null, 2)) {
+function toolResult(value, text) {
     return { content: [{ type: "text", text }], details: value };
 }
-function processView(base, launch) {
+function receiptResult(result) {
+    return result === undefined
+        ? undefined
+        : {
+            id: result.id,
+            owner: result.owner,
+            status: result.status,
+            endedAt: result.endedAt,
+            terminalEntryId: result.terminalEntryId,
+            error: result.error,
+            accountingError: result.accountingError,
+            accountingPending: result.accountingPending,
+        };
+}
+/** `observed` holds batched liveness by actor token; any other actor gets a fresh check. */
+function processView(base, launch, observed) {
     const identity = actor(base, launch);
     const exit = identity
         ? read(path.join(conversation(base, launch), `exit-${identity.token}.json`), exitSchema)
         : undefined;
     return {
-        live: identity !== undefined && alive(identity),
+        live: identity !== undefined && (observed?.get(identity.token) ?? alive(identity)),
         exit: exit ?? null,
         exitKnown: exit !== undefined,
     };
@@ -60,7 +75,7 @@ function guidanceView(base, launches) {
 }
 function metadata(base, launch, result, options) {
     const directory = runDirectory(base, launch.id);
-    const process = processView(base, launch);
+    const process = processView(base, launch, options.observed);
     const outputFile = path.join(directory, "output.txt");
     const admission = read(path.join(conversation(base, launch), "admissions", `${launch.id}.json`), admissionSchema);
     const status = result?.status ??
@@ -89,12 +104,18 @@ function metadata(base, launch, result, options) {
         guidance: options.guidance,
     };
 }
-export function summaries(base, launches, ctx) {
+async function summaries(base, launches, ctx) {
     const guidance = guidanceView(base, launches);
+    const identities = [
+        ...new Map(launches.map((launch) => [launch.rootId, actor(base, launch)])).values(),
+    ].filter((identity) => identity !== undefined);
+    const verdicts = await observeAlive(identities);
+    const observed = new Map(identities.map((identity, index) => [identity.token, verdicts[index]]));
     return launches.map((launch) => {
         const view = metadata(base, launch, readCanonicalResult(base, launch), {
             ctx,
             guidance: guidance.get(launch.id) ?? [],
+            observed,
         });
         return {
             ...view,
@@ -109,7 +130,7 @@ export function summaries(base, launches, ctx) {
         };
     });
 }
-export function projection(base, launch, ctx, input = {}) {
+function projection(base, launch, ctx, input = {}) {
     const view = metadata(base, launch, readResult(base, launch), {
         ctx,
         guidance: guidanceView(base, [launch]).get(launch.id) ?? [],
@@ -119,6 +140,22 @@ export function projection(base, launch, ctx, input = {}) {
         output: outputView(view.outputFile, input),
     };
 }
+export function renderReceipt(base, launch, ctx, receipt) {
+    const details = { ...projection(base, launch, ctx), ...receipt };
+    const model = { ...details, result: receiptResult(details.result) };
+    return toolResult(details, JSON.stringify(model, null, 2));
+}
+export async function renderInventory(base, launches, ctx, input) {
+    const offset = input.offset ?? 0;
+    const runs = await summaries(base, launches.slice(offset, offset + 50), ctx);
+    const details = {
+        runs,
+        offset,
+        nextOffset: offset + runs.length < launches.length ? offset + runs.length : undefined,
+        total: launches.length,
+    };
+    return toolResult(details, JSON.stringify(details, null, 2));
+}
 function receiptText(details) {
     return details.nativeReceipt !== null
         ? `Native completion receipt: published (${details.nativeReceipt}); publication does not prove model consumption.`
@@ -148,15 +185,8 @@ function resultText(details) {
         `Native journal: ${details.sessionFile}`,
     ].join("\n");
 }
-export function render(base, launch, ctx, input = {}) {
-    const view = projection(base, launch, ctx, input);
-    const details = {
-        ...view,
-        receivedResult: input.receivedResult === true,
-        ...(input.receivedResult === true && view.result?.contributions !== undefined
-            ? { agentUsage: view.result.contributions }
-            : {}),
-    };
+export function renderInspection(base, launch, ctx, input = {}) {
+    const details = projection(base, launch, ctx, input);
     return {
         ...toolResult(details, resultText(details)),
         isError: details.result?.status === "failed",

package/dist/agent/wake.js

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+import { journalStamp } from "../shared/native-journal.js";
+import { missing } from "./storage.js";
+/** Identity and change stamp of a path; "" when absent. */
+export function pathStamp(file) {
+    try {
+        const stat = fs.statSync(file, { bigint: true, throwIfNoEntry: false });
+        return stat === undefined ? "" : journalStamp(stat);
+    }
+    catch {
+        return "unreadable";
+    }
+}
+/** Native change hints for one directory identity; owners still reconcile canonical files. */
+export class DirectoryWatch {
+    watcher;
+    armed = "";
+    checked = "";
+    failed = false;
+    directory;
+    relevant;
+    wake;
+    constructor(directory, relevant, wake) {
+        this.directory = directory;
+        this.relevant = relevant;
+        this.wake = wake;
+    }
+    ensure() {
+        const stat = fs.statSync(this.directory, { bigint: true, throwIfNoEntry: false });
+        const identity = stat?.isDirectory() === true ? `${stat.dev}:${stat.ino}` : "";
+        const checked = this.checked;
+        this.checked = stat === undefined ? "" : `${identity}:${stat.mtimeNs}:${stat.ctimeNs}`;
+        if (this.watcher !== undefined && identity === this.armed) {
+            return checked === this.checked ? "watching" : "changed";
+        }
+        // A replaced directory leaves an inode watch silent on Linux.
+        this.close();
+        return identity === "" || this.failed ? "unwatched" : this.arm(identity);
+    }
+    arm(identity) {
+        try {
+            const watcher = fs.watch(this.directory, { persistent: false }, (_event, file) => {
+                if (watcher === this.watcher && this.relevant(file)) {
+                    this.wake();
+                }
+            });
+            watcher.on("error", () => {
+                if (watcher === this.watcher) {
+                    this.failed = true;
+                    this.close();
+                    this.wake();
+                }
+            });
+            this.watcher = watcher;
+            this.armed = identity;
+            return "armed";
+        }
+        catch (error) {
+            // Unsupported platforms and watch limits keep their owner's polling fallback.
+            this.failed = !missing(error);
+            return "unwatched";
+        }
+    }
+    close() {
+        this.watcher?.close();
+        this.watcher = undefined;
+        this.armed = "";
+    }
+}
+/** A coalesced wake for one owner loop; raised until that loop takes it. */
+export class Wake {
+    raised = true;
+    resolve;
+    raise = () => {
+        this.raised = true;
+        this.resolve?.();
+    };
+    take() {
+        const raised = this.raised;
+        this.raised = false;
+        return raised;
+    }
+    /** Returns at once for a wake raised since the last take. */
+    async sleep(ms) {
+        if (this.raised) {
+            return;
+        }
+        const { promise, resolve } = Promise.withResolvers();
+        const timer = setTimeout(() => {
+            resolve("elapsed");
+        }, ms);
+        this.resolve = () => {
+            resolve("woken");
+        };
+        await promise;
+        clearTimeout(timer);
+        this.resolve = undefined;
+    }
+}

package/dist/build-info.js

@@ -1 +1 @@
-export const EXTENSION_BUILD = Object.freeze({"version":"0.50.0","sha256":"030b516d81cb57e1faa44c99a09eb3eba9eca4a3b9d14e53836d7b54b900ced2"});
+export const EXTENSION_BUILD = Object.freeze({"version":"0.51.0","sha256":"fc084c36d416e6ea9947600b7d1fdef98c84a82f3408dea2ea028a9c485ac31e"});

package/dist/intercom-client.d.ts

@@ -0,0 +1,26 @@
+import { type IntercomClientOptions as BrokerOptions } from "./pi-intercom/broker/client.ts";
+import { type DeliveryGuard, type LastMessageQuery, type LastMessageResult, type ReceiptQuery, type ReceiptResult, type SendOptions, type SendResult, type SessionInfo } from "./pi-intercom/types.ts";
+export type { ContextTarget, DeliveryGuard, LastMessageQuery, LastMessageResult, MessageDelivery, NativeReceipt, PublicationReplyHint, ReceiptQuery, ReceiptResult, SendResult, SessionInfo, } from "./pi-intercom/types.ts";
+export type GuardedSendOptions = Omit<SendOptions, "messageId" | "guard" | "expectsReply" | "replyTo" | "human" | "topic" | "passive" | "delivery"> & {
+    readonly messageId: string;
+    readonly guard: DeliveryGuard;
+    readonly expectsReply: false;
+    readonly delivery: "queue" | "steer" | "passive";
+};
+export interface IntercomClientOptions extends BrokerOptions {
+    readonly spawn: false;
+    readonly session: Omit<SessionInfo, "id" | "guardedDelivery" | "applicationGuard" | "topics" | "subscriptions">;
+    readonly requestedId?: string;
+    readonly onError?: (error: Readonly<Error>) => void;
+}
+export interface IntercomClient {
+    readonly sessionId: string | null;
+    readonly isConnected: () => boolean;
+    readonly listSessions: () => Promise<readonly SessionInfo[]>;
+    readonly send: (to: string, options: GuardedSendOptions) => Promise<SendResult>;
+    readonly last: (to: string, query?: LastMessageQuery) => Promise<LastMessageResult>;
+    readonly receipt: (to: string, query: ReceiptQuery) => Promise<ReceiptResult>;
+    readonly disconnect: () => Promise<void>;
+}
+/** Connect to an existing native broker. No Pi runtime, broker spawn or automatic retry. */
+export declare function connectIntercom(options: IntercomClientOptions): Promise<IntercomClient>;

package/dist/intercom-client.js

@@ -0,0 +1,45 @@
+import { IntercomClient as BrokerClient, } from "./pi-intercom/broker/client.js";
+import { isDeliveryGuard, } from "./pi-intercom/types.js";
+import { isRecord } from "./shared/unknown.js";
+function requireNoSpawn(value) {
+    if (value !== false) {
+        throw new Error("The supported Intercom client requires spawn:false.");
+    }
+}
+function guardedSend(to, input) {
+    return (isRecord(input) &&
+        isDeliveryGuard(input.guard) &&
+        to === input.guard.peerId &&
+        typeof input.messageId === "string" &&
+        input.expectsReply === false &&
+        input.delivery !== undefined);
+}
+/** Connect to an existing native broker. No Pi runtime, broker spawn or automatic retry. */
+export async function connectIntercom(options) {
+    requireNoSpawn(options.spawn);
+    const client = new BrokerClient(options);
+    client.on("error", (error) => options.onError?.(error));
+    try {
+        await client.connect(options.session, options.requestedId);
+    }
+    catch (error) {
+        await client.disconnect();
+        throw error;
+    }
+    return Object.freeze({
+        get sessionId() {
+            return client.sessionId;
+        },
+        isConnected: () => client.isConnected(),
+        listSessions: () => client.listSessions(),
+        async send(to, input) {
+            if (!guardedSend(to, input)) {
+                throw new Error("An exact guarded nonblocking send with an original message ID is required.");
+            }
+            return await client.send(to, input);
+        },
+        last: (to, query) => client.last(to, query),
+        receipt: (to, query) => client.receipt(to, query),
+        disconnect: () => client.disconnect(),
+    });
+}

package/dist/pi-intercom/agent-dir.d.ts

@@ -0,0 +1 @@
+export declare function getPiAgentDir(): string;

package/dist/pi-intercom/bridge-session.js

@@ -4,6 +4,7 @@ import { IntercomClient } from "./broker/client.js";
 import { resolveSessionProjectId } from "./session-targets.js";
 import { Fault, cancelled, log, wait } from "./bridge-protocol.js";
 import { Mailbox } from "./bridge-mailbox.js";
+import { hasErrorCode } from "../shared/unknown.js";
 import { resolveBridgeTarget, bridgeSessionList } from "./bridge-target.js";
 const MAX_REQUESTS = 8;
 const IDLE_TIMEOUT = 5 * 60 * 1000;
@@ -222,7 +223,7 @@ export class Session {
         }
         catch (error) {
             cancelled(signal);
-            if (error instanceof Error && error.message === "List sessions timeout") {
+            if (hasErrorCode(error, "list_timeout")) {
                 throw new Fault(504, "list_timeout", "Broker session list deadline exceeded.");
             }
             throw new Fault(503, "broker_unavailable", "Broker session list failed.");