@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/agent/notifications.js

@@ -1,10 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { receiptId } from "./receipts.js";
+import { completionReceipts } from "./receipts.js";
 import { readOutputPage } from "../shared/output-page.js";
-import { isRecord } from "../shared/unknown.js";
+import { journalStamp } from "../shared/native-journal.js";
 import { launchAt, list, runDirectory } from "./storage.js";
-import { readResult } from "./usage.js";
+import { readCanonicalResult, readResult } from "./usage.js";
 function queuedAdmissions() {
     const store = globalThis;
     const existing = store.__pi_single_agent_admissions__;
@@ -22,7 +22,7 @@ function queuedAdmissions() {
     return queued;
 }
 const admissions = queuedAdmissions();
-export function hold(owner, id) {
+function hold(owner, id) {
     const key = `${owner}/${id}`;
     if (admissions.has(key)) {
         return false;
@@ -36,52 +36,51 @@ export function release(owner, id) {
 export function isHeld(owner, id) {
     return admissions.has(`${owner}/${id}`);
 }
+/** Returns whether any admission was released for reconciliation. */
 export function settle(owner, pending) {
     if (pending) {
-        return;
+        return false;
     }
+    let released = false;
     for (const key of admissions) {
         if (key.startsWith(`${owner}/`)) {
             admissions.delete(key);
+            released = true;
         }
     }
+    return released;
 }
-function matches(value, launch) {
-    return (isRecord(value) &&
-        value.owner === launch.owner &&
-        value.id === launch.id &&
-        value.completed === true);
-}
-function toolReceipt(message, launch) {
-    if (!isRecord(message) || message.role !== "toolResult") {
-        return false;
-    }
-    return ((message.toolName === "delegate" || message.toolName === "agent_runs") &&
-        isRecord(message.details) &&
-        message.details.receivedResult === true &&
-        matches(message.details, launch));
+export function published(ctx, launch) {
+    return completionReceipts(ctx.sessionManager.getSessionFile(), launch.owner).get(launch.id);
 }
-function receipt(body, launch) {
-    if (!isRecord(body)) {
-        return false;
-    }
-    if (body.type === "custom_message" && body.customType === "agent-completion") {
-        return matches(body.details, launch);
+export function deliver(pi, ctx, notices) {
+    const idle = ctx.isIdle();
+    for (const [index, notice] of notices.entries()) {
+        hold(notice.owner, notice.id);
+        try {
+            // Pi defers settlement-triggered runs separately. Publish the idle batch first,
+            // then trigger once so no unstarted wakeup can outlive its admission hold.
+            pi.sendMessage(notice.message, {
+                triggerTurn: !idle || index === notices.length - 1,
+                deliverAs: "steer",
+            });
+        }
+        catch (error) {
+            release(notice.owner, notice.id);
+            throw error;
+        }
     }
-    return body.type === "message" && toolReceipt(body.message, launch);
-}
-export function published(ctx, launch) {
-    return receiptId(ctx.sessionManager.getSessionFile(), launch.owner, (body) => receipt(body, launch));
 }
-function send(pi, base, launch, result) {
+function notification(base, launch, result) {
     const file = path.join(runDirectory(base, launch.id), "output.txt");
     const page = fs.existsSync(file) ? readOutputPage(file, { offset: 0, length: 32768 }) : undefined;
     const more = page?.nextOffset !== undefined
         ? `\n[More output: agent_runs inspect id=${launch.id} offset=${page.nextOffset}; ${page.size} bytes total.]`
         : "";
-    hold(launch.owner, launch.id);
-    try {
-        pi.sendMessage({
+    return {
+        owner: launch.owner,
+        id: launch.id,
+        message: {
             customType: "agent-completion",
             display: true,
             content: `Agent run ${launch.id}: ${result.status}. ${result.error ?? ""}\n${page?.text ?? ""}${more}\nNative journal: ${launch.sessionFile}`,
@@ -93,27 +92,119 @@ function send(pi, base, launch, result) {
                 outputFile: file,
                 page,
             },
-        }, { triggerTurn: true, deliverAs: "followUp" });
+        },
+    };
+}
+// Validated settled runs by file stamp, so polling does not reparse unchanged history.
+const settledRuns = new Map();
+function stamp(file) {
+    const stat = fs.statSync(file, { bigint: true, throwIfNoEntry: false });
+    return stat === undefined ? undefined : journalStamp(stat);
+}
+function pendingJournal(file) {
+    try {
+        return { file, stamp: stamp(file) };
     }
-    catch (error) {
-        admissions.delete(`${launch.owner}/${launch.id}`);
-        throw error;
+    catch {
+        // Unavailable metadata cannot validate a cached attempt or hide execution.
+        return undefined;
     }
 }
-export function notify(pi, ctx, base, owner) {
-    for (const id of list(base)) {
-        const launch = launchAt(base, id, owner);
-        const result = readResult(base, launch);
-        if (!result) {
-            continue;
+function unchangedPending(pending) {
+    if (pending === undefined) {
+        return true;
+    }
+    const journal = pending.journal;
+    if (journal === undefined) {
+        return false;
+    }
+    const current = pendingJournal(journal.file);
+    return current !== undefined && current.stamp === journal.stamp;
+}
+function load(base, id, owner) {
+    const launch = launchAt(base, id, owner);
+    const result = readCanonicalResult(base, launch);
+    if (result?.accountingPending === undefined) {
+        return { launch, result };
+    }
+    // Only pending runs need this pre-read stamp to observe concurrent publication.
+    // readResult revalidates canonical state afterward: a miss intentionally reads result.json twice.
+    const journal = pendingJournal(launch.sessionFile);
+    return { launch, result: readResult(base, launch), journal };
+}
+function cacheableResult(loaded) {
+    return loaded.result?.accountingPending === undefined || loaded.journal !== undefined;
+}
+function completedRun({ base, owner, known, settled }, id) {
+    const directory = runDirectory(base, id);
+    const launch = stamp(path.join(directory, "launch.json"));
+    const result = stamp(path.join(directory, "result.json"));
+    const prior = known.get(id);
+    if (prior !== undefined &&
+        prior.launch === launch &&
+        prior.result === result &&
+        unchangedPending(prior.pending)) {
+        settled.set(id, prior);
+        return { id, ...prior, loaded: prior.pending };
+    }
+    const loaded = load(base, id, owner);
+    if (loaded.result === undefined) {
+        return;
+    }
+    const order = { endedAt: loaded.result.endedAt, createdAt: loaded.launch.createdAt };
+    // Pending accounting retries on child changes, even after the completion receipt.
+    // Ordinary settled history retains its launch/result-only idle probes.
+    const pending = loaded.result.accountingPending === undefined ? undefined : loaded;
+    if (launch !== undefined && result !== undefined && cacheableResult(loaded)) {
+        settled.set(id, { launch, result, pending, ...order });
+    }
+    return { id, ...order, loaded };
+}
+function completed(base, owner, awaited) {
+    const key = JSON.stringify([base, owner]);
+    const scan = {
+        base,
+        owner,
+        known: settledRuns.get(key) ?? new Map(),
+        settled: new Map(),
+    };
+    const runs = list(base).flatMap((id) => {
+        const run = completedRun(scan, id);
+        if (run === undefined) {
+            awaited.add(path.join(runDirectory(base, id), "result.json"));
         }
-        const key = `${owner}/${id}`;
-        if (published(ctx, launch) !== undefined) {
+        else if (run.loaded?.result?.accountingPending !== undefined) {
+            awaited.add(run.loaded.launch.sessionFile);
+        }
+        return run ?? [];
+    });
+    settledRuns.delete(key);
+    settledRuns.set(key, scan.settled);
+    if (settledRuns.size > 8) {
+        settledRuns.delete(settledRuns.keys().next().value ?? key);
+    }
+    return runs.sort((a, b) => {
+        if (a.endedAt !== b.endedAt) {
+            return a.endedAt - b.endedAt;
+        }
+        return a.createdAt !== b.createdAt ? a.createdAt - b.createdAt : a.id.localeCompare(b.id);
+    });
+}
+export function notifications(ctx, base, owner) {
+    const notices = [];
+    const awaited = new Set();
+    const runs = completed(base, owner, awaited);
+    const receipts = runs.length === 0 ? undefined : completionReceipts(ctx.sessionManager.getSessionFile(), owner);
+    for (const run of runs) {
+        const key = `${owner}/${run.id}`;
+        if (receipts?.get(run.id) !== undefined) {
             admissions.delete(key);
             continue;
         }
-        if (!admissions.has(key)) {
-            send(pi, base, launch, result);
+        const loaded = admissions.has(key) ? undefined : (run.loaded ?? load(base, run.id, owner));
+        if (loaded?.result !== undefined) {
+            notices.push(notification(base, loaded.launch, loaded.result));
         }
     }
+    return { notices, awaited };
 }

package/dist/agent/observation-state.js

@@ -0,0 +1,246 @@
+import { boundedJson } from "../shared/bounded-json.js";
+const VALUE_BUDGET = { bytes: 64 * 1024, nodes: 4096, depth: 32 };
+/** Longer native identifiers are left to the journal rather than keyed live. */
+export const NAME_CHARS = 1024;
+const RETAINED = { settlements: 128, tools: 256 };
+const WRITING = { text: "writing", thinking: "thinking", toolCall: "calling" };
+export class LiveTool {
+    partial;
+    rev = 0;
+    ended;
+    id;
+    name;
+    args;
+    argsJson;
+    partialJson;
+    resultJson;
+    constructor(id, name, args) {
+        this.id = id;
+        this.name = name;
+        this.args = args;
+    }
+    /** Replaceable progress: only the latest reference is projected at the next flush. */
+    progress(value) {
+        this.partial = value;
+        this.rev++;
+    }
+    projectedArgs(project) {
+        this.argsJson ??= project(this.args);
+        return this.argsJson;
+    }
+    projectedPartial(project) {
+        if (this.partialJson?.rev !== this.rev) {
+            this.partialJson = { rev: this.rev, json: project(this.partial) };
+        }
+        return this.partialJson.json;
+    }
+    projectedResult(project) {
+        this.resultJson ??= project(this.ended?.result);
+        return this.resultJson;
+    }
+}
+/**
+ * Single-writer actor state. Sparse tool hooks always keep the tool table, because native state
+ * retains neither progress, unpublished parallel results nor nested calls. Token-rate message
+ * events arrive only while a detail viewer observes; attaching seeds from public native state.
+ */
+export class LiveState {
+    version = 0;
+    activityVersion = 0;
+    message;
+    tools = new Map();
+    settlements = [];
+    settled = 0;
+    /** Live items dropped by a retention bound or a branch change; viewers resynchronize. */
+    evicted = 0;
+    events = 0;
+    toolEvents = 0;
+    progressUpdates = 0;
+    projections = 0;
+    unavailable = 0;
+    observing = false;
+    nextKey = 0;
+    queued = false;
+    closed = false;
+    watermark;
+    session;
+    changed;
+    failed;
+    constructor(session, changed, failed) {
+        this.session = session;
+        this.changed = changed;
+        this.failed = failed;
+        this.watermark = session.sessionManager.getLeafId();
+    }
+    /** Start or stop the transient message view; tools persist across viewers. */
+    observe(on) {
+        this.resolve();
+        this.observing = on;
+        this.message = undefined;
+        this.settlements.length = 0;
+        if (on) {
+            const streaming = this.session.state.streamingMessage;
+            if (streaming?.role === "assistant") {
+                this.assistant("message_start", streaming);
+            }
+        }
+        this.version++;
+        this.activityVersion++;
+    }
+    apply(event) {
+        this.events++;
+        if (event.type === "message_start" ||
+            event.type === "message_update" ||
+            event.type === "message_end") {
+            this.messageEvent(event);
+        }
+    }
+    messageEvent(event) {
+        if (event.message.role === "assistant") {
+            this.assistant(event.type, event.message);
+        }
+        if (event.type === "message_end" && !this.queued) {
+            this.queued = true;
+            // Native message_end listeners run just before the same job appends the entry.
+            queueMicrotask(this.settle);
+        }
+    }
+    assistant(type, message) {
+        let live = this.message;
+        if (type === "message_start" || live === undefined) {
+            // A previous message still here was never found in the session tree.
+            this.evicted += live === undefined ? 0 : 1;
+            live = { key: ++this.nextKey, message, ended: false };
+            this.message = live;
+        }
+        live.message = message;
+        live.ended = type === "message_end";
+        this.version++;
+    }
+    tool(event) {
+        this.toolEvents++;
+        this.version++;
+        if (event.type === "tool_execution_start") {
+            this.resolve();
+            this.startTool(event.toolCallId, event.toolName, event.args);
+            return;
+        }
+        const tool = this.tools.get(event.toolCallId);
+        if (event.type === "tool_execution_update") {
+            tool?.progress(event.partialResult);
+            this.progressUpdates++;
+        }
+        else if (tool) {
+            tool.ended = { isError: event.isError, result: event.result };
+            this.activityVersion++;
+        }
+    }
+    startTool(id, name, args) {
+        if (id.length > NAME_CHARS) {
+            this.unavailable++;
+            return;
+        }
+        const oldest = this.tools.size >= RETAINED.tools ? this.tools.keys().next() : undefined;
+        if (oldest?.done === false) {
+            this.tools.delete(oldest.value);
+            this.evicted++;
+        }
+        this.tools.set(id, new LiveTool(id, name, args));
+        this.activityVersion++;
+    }
+    settle = () => {
+        this.queued = false;
+        try {
+            if (!this.closed && this.resolve()) {
+                this.changed();
+            }
+        }
+        catch (error) {
+            this.failed(error);
+        }
+    };
+    /**
+     * Hand native messages appended since the last walk over to their session entries. A live
+     * message without an entry is unresolved publication and stays live. Returns whether anything
+     * changed.
+     */
+    resolve() {
+        const { appended, departed } = this.appended();
+        this.evicted += departed && this.observing ? 1 : 0;
+        for (const entry of appended) {
+            this.publish(entry, !departed && this.observing);
+        }
+        this.settlements.splice(0, Math.max(0, this.settlements.length - RETAINED.settlements));
+        const changed = appended.length > 0;
+        this.version += changed ? 1 : 0;
+        this.activityVersion += changed ? 1 : 0;
+        return changed;
+    }
+    /** Message entries since the previous walk, in journal order; each append is visited once. */
+    appended() {
+        const manager = this.session.sessionManager;
+        const appended = [];
+        let entry = manager.getLeafEntry();
+        const leaf = entry?.id ?? null;
+        while (entry !== undefined && entry.id !== this.watermark) {
+            if (entry.type === "message") {
+                appended.push(entry);
+            }
+            entry = entry.parentId === null ? undefined : manager.getEntry(entry.parentId);
+        }
+        // A leaf off the previous branch walked to the root once; its entries are not new.
+        const departed = entry === undefined && this.watermark !== null;
+        this.watermark = leaf;
+        return { appended: appended.reverse(), departed };
+    }
+    publish({ id, message }, settle) {
+        const call = message.role === "toolResult" ? message.toolCallId : "";
+        const tool = call.length > 0 && call.length <= NAME_CHARS ? call : null;
+        // A published result also retires the calls it made through ctx.executeTool().
+        const retired = (key) => tool !== null && (key === tool || key.startsWith(`${tool}/`));
+        for (const live of [...this.tools.keys()].filter(retired)) {
+            this.tools.delete(live);
+        }
+        const key = this.message?.message === message ? this.message.key : null;
+        this.message = key === null ? this.message : undefined;
+        if (settle) {
+            const seq = ++this.settled;
+            this.settlements.push({ seq, json: JSON.stringify([seq, id, key, tool]) });
+        }
+    }
+    dispose() {
+        this.closed = true;
+    }
+    project = (value) => {
+        this.projections++;
+        const result = boundedJson(value, VALUE_BUDGET);
+        if ("json" in result) {
+            return `{"json":${result.json}}`;
+        }
+        this.unavailable++;
+        return `{"unavailable":"${result.unavailable}"}`;
+    };
+    /** Sampled from public native state, so compact peers never need token-rate events. */
+    activity(busy) {
+        const { session } = this;
+        const running = [...this.tools.values()].filter((tool) => tool.ended === undefined);
+        const streaming = session.state.streamingMessage;
+        const content = streaming?.role === "assistant" ? streaming.content : undefined;
+        const last = content?.at(-1)?.type;
+        const phases = [
+            [running.length > 0, "tool"],
+            [content !== undefined, last === undefined ? "responding" : WRITING[last]],
+            [session.isCompacting, "compacting"],
+            [session.isRetrying, "retrying"],
+            [busy || session.isStreaming, "working"],
+        ];
+        const phase = phases.find(([active]) => active)?.[1] ?? "idle";
+        return JSON.stringify({
+            phase,
+            tools: running.slice(0, 3).map((tool) => tool.name.slice(0, 64)),
+            running: running.length,
+            model: this.session.model?.id,
+            thinking: this.session.thinkingLevel,
+        });
+    }
+}