@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/dist/runs/background/completion-delivery.js

@@ -0,0 +1,245 @@
+import * as fs from "node:fs";
+import { RESULTS_DIR, SUBAGENT_ASYNC_COMPLETE_EVENT } from "../../shared/types.js";
+import { SessionEntryCursor } from "../../shared/session-entries.js";
+import { createParentReceiptReader } from "../shared/parent-receipts.js";
+import { finalizedChildUsage } from "../shared/parent-usage.js";
+import { ownedRunView, rememberOwnedRun, repairOwnedRunAccounting } from "../shared/run-records.js";
+import registerSubagentNotify from "./notify.js";
+import { createResultWatcher } from "./result-watcher.js";
+/** Completion authority is the published parent receipt, never queue/send acceptance. */
+export function createCompletionDelivery(pi, state, parentUsage) {
+    const store = globalThis, queueKey = "__pi_subagents_queued_notifications__";
+    // Native custom queues survive extension reload, so their admission authority must too.
+    const queued = store[queueKey] instanceof Map ? store[queueKey] : new Map();
+    store[queueKey] = queued;
+    pi.on("turn_end", (event, ctx) => {
+        // ponytail: this is the next batch, not the whole queue. Retain ambiguous
+        // admissions until publication or empty queues; selective removal needs a public full-queue snapshot.
+        const pending = event.context.pendingMessages.length > 0;
+        for (const [key, admission] of queued) {
+            if (admission.channel !== "notification" || admission.sessionId !== ctx.sessionManager.getSessionId())
+                continue;
+            admission.pending = pending;
+            if (!admission.pending) {
+                queued.delete(key);
+                state.completionSeen.delete(key);
+            }
+        }
+    });
+    const publishedReceipts = createParentReceiptReader("live");
+    const indexReceipts = (saved) => {
+        const completed = new Map(), singles = new Map();
+        const completions = new Map(), legacy = new Map();
+        for (const entry of saved.values()) {
+            const details = entry.type === "message" && entry.message.role === "toolResult" ? entry.message.details
+                : entry.type === "custom_message" ? entry.details : undefined;
+            const data = details;
+            const wait = entry.type === "message" ? data?.wait : data?.result?.details?.wait;
+            if (wait?.status === "completed") {
+                const target = wait.index === undefined ? completed : wait.index === 0 ? singles : undefined;
+                if (target && !target.has(wait.runId))
+                    target.set(wait.runId, entry);
+            }
+            if (entry.type !== "custom_message")
+                continue;
+            const completion = data?.completion ?? data?.subagentCompletion;
+            if (!completion?.runId)
+                continue;
+            for (const key of [completion.key, completion.completionId && `completion:${completion.completionId}`]) {
+                const identity = `${completion.runId}\0${key}`;
+                if (key && !completions.has(identity))
+                    completions.set(identity, entry);
+            }
+            if (!completion.completionId && (completion.ownerSessionId === undefined || completion.ownerSessionId === state.currentSessionId)
+                && !legacy.has(completion.runId))
+                legacy.set(completion.runId, entry);
+        }
+        return { saved, completed, singles, completions, legacy };
+    };
+    let batching = false;
+    let snapshot;
+    const readReceipts = () => {
+        const manager = state.lastUiContext?.sessionManager, file = manager?.getSessionFile();
+        const leaf = manager?.getLeafId?.(), count = manager?.getEntryCount?.();
+        if (batching && count !== undefined && snapshot && snapshot.manager === manager && snapshot.file === file && snapshot.leaf === leaf && snapshot.count === count)
+            return snapshot.index;
+        const index = indexReceipts(publishedReceipts.read(file));
+        if (batching)
+            snapshot = { manager, file, leaf, count, index };
+        return index;
+    };
+    const withReceiptBatch = (work) => {
+        // Proof is scoped to this synchronous stack, never async delivery. Every
+        // parent append changes count/leaf and forces another SHA-verified read.
+        batching = true;
+        snapshot = undefined;
+        try {
+            work();
+        }
+        finally {
+            batching = false;
+            snapshot = undefined;
+        }
+    };
+    const consumedReceipt = (index, runId) => index.completed.get(runId)
+        ?? (state.ownedRuns?.get(runId)?.mode === "single" ? index.singles.get(runId) : undefined);
+    const publishedReceipt = (index, runId, key) => consumedReceipt(index, runId)
+        ?? index.completions.get(`${runId}\0${key}`) ?? (key.startsWith("completion:legacy:") ? index.legacy.get(runId) : undefined);
+    const completedCursor = new SessionEntryCursor();
+    const receiptEntryIds = new Set();
+    const readParentChanges = () => {
+        const ctx = state.lastUiContext;
+        if (!ctx)
+            return;
+        const changes = completedCursor.read(ctx.sessionManager);
+        if (changes.reset)
+            receiptEntryIds.clear();
+        for (const entry of changes.entries) {
+            if (entry.type === "message" && entry.message.role === "toolResult") {
+                if (["subagent", "delegate", "agent_runs"].includes(entry.message.toolName))
+                    receiptEntryIds.add(entry.id);
+            }
+            else if (entry.type === "custom_message" && ["subagent-notify", "intercom_message", "subagent-slash-result"].includes(entry.customType))
+                receiptEntryIds.add(entry.id);
+        }
+    };
+    const consumed = (entry, runId) => {
+        const wait = entry.type === "message" ? entry.message?.details?.wait : entry.details?.result?.details?.wait;
+        const run = state.ownedRuns?.get(runId);
+        return wait?.runId === runId && wait.status === "completed" && (wait.index === undefined || run?.mode === "single" && wait.index === 0);
+    };
+    state.isRunResultConsumed = (runId) => Boolean(consumedReceipt(readReceipts(), runId));
+    const matches = (entry, runId, key) => {
+        if (consumed(entry, runId))
+            return true;
+        if (entry.type !== "custom_message")
+            return false;
+        const completion = entry.details?.completion ?? entry.details?.subagentCompletion;
+        return completion?.runId === runId && (completion.key === key || completion.completionId && `completion:${completion.completionId}` === key
+            || key.startsWith("completion:legacy:") && !completion.completionId && (completion.ownerSessionId === undefined || completion.ownerSessionId === state.currentSessionId));
+    };
+    const recordAccounting = (runId) => {
+        const run = state.ownedRuns?.get(runId), ctx = state.lastUiContext;
+        if (!run || !ctx)
+            return;
+        try {
+            repairOwnedRunAccounting(run);
+            const children = ownedRunView(run, state, { readConfiguration: false }).children;
+            const incomplete = children.find((child) => child.result?.accounting?.state === "incomplete");
+            const accounting = incomplete ? { state: "incomplete", error: incomplete.result?.accounting?.error }
+                : { state: parentUsage.isRecorded(finalizedChildUsage(children), ctx, readReceipts().saved) ? "complete" : "pending" };
+            rememberOwnedRun(state, { ...state.ownedRuns.get(runId), accounting });
+        }
+        catch (error) {
+            try {
+                rememberOwnedRun(state, { ...state.ownedRuns.get(runId), accounting: { state: "incomplete", error: String(error) } });
+            }
+            catch (saveError) {
+                console.error(`Could not save accounting projection for ${runId}:`, saveError);
+            }
+            console.error(`Subagent ${runId} accounting remains incomplete:`, error);
+        }
+    };
+    const reconcileDelivery = (runId, key, accounting = true) => {
+        const run = state.ownedRuns?.get(runId);
+        const index = readReceipts(), saved = index.saved;
+        const receipt = publishedReceipt(index, runId, key);
+        if (receipt) {
+            queued.delete(key);
+            state.completionSeen.delete(key);
+            // Save delivery before optional accounting. Even a failed owner append cannot
+            // make this published identity eligible for another notification.
+            try {
+                if (run)
+                    rememberOwnedRun(state, { ...run, completion: { id: key, state: "journaled", entryId: receipt.id },
+                        delivery: { notifiedAt: Date.parse(receipt.timestamp), intercomDelivered: receipt.type === "custom_message" && receipt.customType === "intercom_message", completionId: key, entryId: receipt.id } });
+            }
+            catch (error) {
+                console.error(`Could not save delivery projection for ${runId}:`, error);
+            }
+            if (accounting)
+                recordAccounting(runId);
+            return true;
+        }
+        const ctx = state.lastUiContext;
+        if (!ctx)
+            return true;
+        // An accepted but unflushed receipt or a native pending queue is ambiguous:
+        // keep pending rather than enqueueing a second copy. Official hosts expose
+        // queue occupancy, not individual queue contents.
+        readParentChanges();
+        if ([...receiptEntryIds].some((id) => {
+            if (saved.has(id))
+                return false; // Published candidates were checked above.
+            const entry = ctx.sessionManager.getEntry(id);
+            return entry !== undefined && matches(entry, runId, key);
+        })) {
+            queued.delete(key);
+            state.completionSeen.delete(key);
+            return true;
+        }
+        if (queued.has(key) || run?.completion?.id === key && run.completion.state === "queued") {
+            // The durable Intercom inbox owns its own queue/restart reconciliation.
+            // A remote acknowledgement exposes no parent commit/queue boundary.
+            if (run?.completion?.channel === "intercom")
+                return true;
+            // Settlement after abort need not drain the custom queue. Its actual
+            // turn boundary remains authoritative when coarse occupancy says idle.
+            if (queued.get(key)?.pending || !ctx.isIdle() || ctx.hasPendingMessages())
+                return true;
+            queued.delete(key);
+            state.completionSeen.delete(key);
+            if (run)
+                rememberOwnedRun(state, { ...run, completion: { id: key, state: "dropped" } });
+        }
+        return false;
+    };
+    const watcher = createResultWatcher(pi, state, RESULTS_DIR, { reconcileDelivery, withReceiptBatch,
+        isCompletionPublished: (runId, key) => Boolean(publishedReceipt(readReceipts(), runId, key)) });
+    let unsubscribe, unsubscribeNotify;
+    const markQueued = (runId, key, channel = "notification") => {
+        const run = state.ownedRuns?.get(runId);
+        queued.set(key, { sessionId: state.currentSessionId, pending: false, channel });
+        if (run)
+            rememberOwnedRun(state, { ...run, completion: { id: key, state: "queued", channel, queuedAt: Date.now() } });
+    };
+    const start = () => {
+        if (!unsubscribe) {
+            unsubscribeNotify = registerSubagentNotify(pi, (key, runId) => { if (runId)
+                markQueued(runId, key); });
+            unsubscribe = pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, (data) => {
+                const result = data;
+                const run = state.ownedRuns?.get(result.runId ?? result.id ?? "");
+                if (!run || result.sessionId !== state.currentSessionId && run.ownerSessionId !== state.currentSessionId)
+                    return;
+                if (result.completionKey) {
+                    if (result.intercomResultDelivered)
+                        markQueued(run.runId, result.completionKey, "intercom");
+                    reconcileDelivery(run.runId, result.completionKey);
+                }
+                if (result.suppressNotification)
+                    recordAccounting(run.runId);
+            });
+        }
+        fs.mkdirSync(RESULTS_DIR, { recursive: true });
+        watcher.startResultWatcher();
+        watcher.primeExistingResults();
+    };
+    const stopListening = () => {
+        unsubscribe?.();
+        unsubscribe = undefined;
+        unsubscribeNotify?.();
+        unsubscribeNotify = undefined;
+        publishedReceipts.clear();
+        completedCursor.reset();
+        receiptEntryIds.clear();
+    };
+    const stop = () => { watcher.stopResultWatcher(); stopListening(); };
+    const stopAndJoin = async (options = {}) => {
+        // Finish accepted delivery while the old owner and its listeners are valid.
+        watcher.stopResultWatcher({ ...options, joinInFlight: true });
+        await watcher.joinInFlight();
+        stopListening();
+    };
+    return { start, stop, stopAndJoin };
+}

package/dist/runs/background/notify.js

@@ -0,0 +1,71 @@
+/**
+ * Subagent completion notifications.
+ */
+import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "./completion-dedupe.js";
+import { SUBAGENT_ASYNC_COMPLETE_EVENT } from "../../shared/types.js";
+export default function registerSubagentNotify(pi, onQueued) {
+    const unsubscribeStoreKey = "__pi_subagents_notify_unsubscribe__";
+    const globalStore = globalThis;
+    const previousUnsubscribe = globalStore[unsubscribeStoreKey];
+    if (typeof previousUnsubscribe === "function") {
+        try {
+            previousUnsubscribe();
+        }
+        catch {
+            // Best effort cleanup for stale handlers from an older reload.
+        }
+    }
+    const seen = getGlobalSeenMap("__pi_subagents_notify_seen__");
+    const ttlMs = 10 * 60 * 1000;
+    const handleComplete = (data) => {
+        const result = data;
+        if (result.intercomResultDelivered === true || result.suppressNotification === true)
+            return;
+        const now = Date.now();
+        const key = buildCompletionKey(result, "notify");
+        // Owned completion keys are governed by the shared queue/journal lifecycle, not a TTL.
+        if ((!onQueued || !result.completionKey) && markSeenWithTtl(seen, key, now, ttlMs))
+            return;
+        const agent = result.agent ?? "unknown";
+        const summary = typeof result.summary === "string" ? result.summary : "";
+        const paused = !result.success && (result.exitCode === 0
+            || result.state === "paused"
+            || summary.startsWith("Paused after interrupt."));
+        const status = result.state === "blocked" ? "blocked" : paused ? "paused" : result.success ? "completed" : "failed";
+        const taskInfo = result.taskIndex !== undefined && result.totalTasks !== undefined
+            ? ` (${result.taskIndex + 1}/${result.totalTasks})`
+            : "";
+        const sessionLine = result.shareUrl
+            ? `Session: ${result.shareUrl}`
+            : result.shareError
+                ? `Session share error: ${result.shareError}`
+                : result.sessionFile
+                    ? `Session file: ${result.sessionFile}`
+                    : undefined;
+        const displaySummary = summary.trim() ? summary : "(no output)";
+        const content = [
+            `Background task ${status}: **${agent}**${taskInfo}`,
+            "",
+            displaySummary,
+            sessionLine ? "" : undefined,
+            sessionLine,
+        ]
+            .filter((line) => line !== undefined)
+            .join("\n");
+        pi.sendMessage({
+            customType: "subagent-notify",
+            content,
+            display: true,
+            ...(result.runId && result.completionKey ? { details: {
+                    agent, status, taskInfo: taskInfo.trim(), resultPreview: displaySummary.trim(),
+                    ...(sessionLine ? { sessionLabel: sessionLine.slice(0, sessionLine.indexOf(":")).toLowerCase(), sessionValue: sessionLine.slice(sessionLine.indexOf(":") + 1).trim() } : {}),
+                    completion: { runId: result.runId, key: result.completionKey },
+                } } : {}),
+        }, { triggerTurn: true });
+        if (result.completionKey)
+            onQueued?.(result.completionKey, result.runId);
+    };
+    const unsubscribe = pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete);
+    globalStore[unsubscribeStoreKey] = unsubscribe;
+    return unsubscribe;
+}

package/dist/runs/background/parallel-groups.js

@@ -0,0 +1,55 @@
+function isValidParallelGroup(group, stepCount, chainStepCount) {
+    if (typeof group !== "object" || group === null)
+        return false;
+    const { start, count, stepIndex } = group;
+    return typeof start === "number"
+        && typeof count === "number"
+        && typeof stepIndex === "number"
+        && Number.isInteger(start)
+        && Number.isInteger(count)
+        && Number.isInteger(stepIndex)
+        && start >= 0
+        && count >= 0
+        && stepIndex >= 0
+        && stepIndex < chainStepCount
+        && start + count <= stepCount;
+}
+export function normalizeParallelGroups(groups, stepCount, chainStepCount) {
+    if (!Array.isArray(groups))
+        return [];
+    const sorted = groups
+        .filter((group) => isValidParallelGroup(group, stepCount, chainStepCount))
+        .sort((left, right) => left.stepIndex - right.stepIndex || left.start - right.start);
+    const normalized = [];
+    const logicalSteps = new Set();
+    for (const group of sorted) {
+        if (logicalSteps.has(group.stepIndex) || normalized.some((existing) => group.start < existing.start + existing.count && existing.start < group.start + group.count))
+            continue;
+        logicalSteps.add(group.stepIndex);
+        normalized.push(group);
+    }
+    return normalized;
+}
+export function flatToLogicalStepIndex(flatIndex, chainStepCount, groups) {
+    let logicalIndex = 0;
+    let cursor = 0;
+    for (const group of groups) {
+        while (cursor < group.start && logicalIndex < chainStepCount) {
+            if (cursor === flatIndex)
+                return logicalIndex;
+            cursor++;
+            logicalIndex++;
+        }
+        if (flatIndex >= group.start && flatIndex < group.start + group.count)
+            return group.stepIndex;
+        cursor = group.start + group.count;
+        logicalIndex = group.stepIndex + 1;
+    }
+    while (cursor <= flatIndex && logicalIndex < chainStepCount) {
+        if (cursor === flatIndex)
+            return logicalIndex;
+        cursor++;
+        logicalIndex++;
+    }
+    return Math.max(0, chainStepCount - 1);
+}