@fitchmultz/pi-subagents 0.49.1 → 0.50.0

package/dist/runs/background/result-watcher.js

@@ -1,435 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { setImmediate as yieldToInput } from "node:timers/promises";
-import { getRunMetadataDir } from "../shared/supervisor-questions.js";
-import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.js";
-import { createFileCoalescer } from "../../shared/file-coalescer.js";
-import { journalStamp } from "../../shared/journal-reader.js";
-import { SUBAGENT_ASYNC_COMPLETE_EVENT, } from "../../shared/types.js";
-import { completionEvent, deliverResultIntercom, prepareResult, readResultEnvelope, } from "./result-payload.js";
-import { errorCode, hasText } from "./async-value.js";
-const RESTART_DELAY_MS = 3000;
-const POLL_INTERVAL_MS = 3000;
-function notFound(error) {
-    return (errorCode(error) === "ENOENT" ||
-        errorCode(error instanceof Error ? error.cause : undefined) === "ENOENT");
-}
-function pollingRequired(error) {
-    const code = errorCode(error);
-    return code === "EMFILE" || code === "ENOSPC";
-}
-/** Owns admitted background deliveries, watcher resources, and shutdown generations. */
-class ResultWatcher {
-    pi;
-    state;
-    resultsDir;
-    deps;
-    periodicScanTimer = null;
-    processingCompletionKeys = new Set();
-    inFlight = new Set();
-    startTail = Promise.resolve();
-    generation = 0;
-    preserveBeforeGeneration = 0;
-    joiningGeneration;
-    foreignResults = new Map();
-    scheduled = new Set();
-    drainGeneration;
-    constructor(pi, state, resultsDir, deps) {
-        this.pi = pi;
-        this.state = state;
-        this.resultsDir = resultsDir;
-        this.deps = deps;
-        this.state.resultFileCoalescer = createFileCoalescer(this.scheduleResult, 50);
-    }
-    isForeignUnchanged(resultPath) {
-        const cached = this.foreignResults.get(resultPath);
-        if (!cached ||
-            cached.sessionId !== this.state.currentSessionId ||
-            cached.ownerSessionId !== this.state.ownedRuns?.get(cached.runId)?.ownerSessionId) {
-            return false;
-        }
-        return (cached.stamp === journalStamp(fs.statSync(resultPath, { bigint: true })) &&
-            (cached.canonicalPath === undefined ||
-                cached.canonicalStamp === journalStamp(fs.statSync(cached.canonicalPath, { bigint: true }))));
-    }
-    resultPath(file) {
-        return path.isAbsolute(file) ? file : path.join(this.resultsDir, file);
-    }
-    needsRecovery(run) {
-        return (run.source === "async" &&
-            (run.accounting?.state === "incomplete" || !hasText(run.delivery?.entryId)));
-    }
-    candidateFiles() {
-        const files = fs.existsSync(this.resultsDir)
-            ? fs.readdirSync(this.resultsDir).filter((name) => name.endsWith(".json"))
-            : [];
-        const notified = new Map(files.map((file, index) => [file, index]));
-        for (const run of this.state.ownedRuns?.values() ?? []) {
-            if (!this.needsRecovery(run)) {
-                continue;
-            }
-            const file = path.join(getRunMetadataDir(run.runId), "result.json");
-            if (!fs.existsSync(file)) {
-                continue;
-            }
-            // Disposable hints cannot veto canonical recovery, including corrupt hints.
-            const notification = notified.get(`${run.runId}.json`);
-            if (notification === undefined) {
-                files.push(file);
-            }
-            else {
-                files[notification] = file;
-            }
-        }
-        return files;
-    }
-    pendingResultFiles() {
-        const files = this.candidateFiles();
-        const present = new Set(files.map((file) => this.resultPath(file)));
-        for (const file of this.foreignResults.keys()) {
-            if (!present.has(file)) {
-                this.foreignResults.delete(file);
-            }
-        }
-        return files.filter((file) => {
-            const resultPath = this.resultPath(file);
-            try {
-                return !this.isForeignUnchanged(resultPath);
-            }
-            catch (error) {
-                if (notFound(error)) {
-                    this.foreignResults.delete(resultPath);
-                    return false;
-                }
-                return true;
-            }
-        });
-    }
-    foreign(envelope) {
-        const run = this.state.ownedRuns?.get(envelope.runId);
-        const sessionId = envelope.data.sessionId;
-        const foreign = hasText(sessionId)
-            ? sessionId !== this.state.currentSessionId &&
-                run?.ownerSessionId !== this.state.currentSessionId
-            : run === undefined;
-        if (foreign) {
-            this.foreignResults.set(envelope.resultPath, {
-                stamp: envelope.stamp,
-                sessionId: this.state.currentSessionId,
-                runId: envelope.runId,
-                ownerSessionId: run?.ownerSessionId,
-                canonicalPath: envelope.canonicalPath,
-                canonicalStamp: envelope.canonicalStamp,
-            });
-        }
-        else {
-            this.foreignResults.delete(envelope.resultPath);
-        }
-        return foreign;
-    }
-    consumeNotification(envelope, key) {
-        // Native queue admission is not publication. Retain the only legacy saved result until publication.
-        if (!envelope.durableFile &&
-            envelope.canonicalPath === undefined &&
-            this.deps.isCompletionPublished !== undefined &&
-            !this.deps.isCompletionPublished(envelope.runId, key)) {
-            return;
-        }
-        const hint = envelope.durableFile
-            ? path.join(this.resultsDir, `${envelope.runId}.json`)
-            : envelope.resultPath;
-        if (fs.existsSync(hint)) {
-            fs.unlinkSync(hint);
-        }
-    }
-    alreadyHandled(envelope, key) {
-        const handled = this.deps.reconcileDelivery === undefined
-            ? this.state.isRunResultConsumed?.(envelope.runId) === true
-            : this.deps.reconcileDelivery(envelope.runId, key);
-        if (handled) {
-            this.consumeNotification(envelope, key);
-            return true;
-        }
-        if (this.state.waitingRuns?.has(envelope.runId) === true) {
-            this.pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
-                ...envelope.data,
-                runId: envelope.runId,
-                suppressNotification: true,
-                intercomResultDelivered: false,
-            });
-            return true;
-        }
-        return false;
-    }
-    claimCompletion(envelope, key) {
-        if (this.processingCompletionKeys.has(key)) {
-            return false;
-        }
-        // Owned queue/receipt reconciliation remains authoritative after TTL expiry.
-        if (markSeenWithTtl(this.state.completionSeen, key, Date.now(), 10 * 60 * 1000)) {
-            this.consumeNotification(envelope, key);
-            return false;
-        }
-        this.processingCompletionKeys.add(key);
-        return true;
-    }
-    async deliverClaimed(envelope, prepared, key, ownership) {
-        const delivered = await deliverResultIntercom(this.pi.events, envelope, prepared);
-        // Stop/session callbacks may change generation and owner during suspension.
-        if ((ownership.generation !== this.generation &&
-            ownership.generation !== this.joiningGeneration) ||
-            ownership.sessionId !== this.state.currentSessionId) {
-            this.state.completionSeen.delete(key);
-            return false;
-        }
-        // Shutdown closes native turn ingress; accepted acknowledgements are still recorded.
-        if (!delivered && ownership.generation < this.preserveBeforeGeneration) {
-            return false;
-        }
-        this.pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, completionEvent(envelope, prepared, key, delivered));
-        return true;
-    }
-    releaseCompletion(key, emitted) {
-        if (!hasText(key)) {
-            return;
-        }
-        this.processingCompletionKeys.delete(key);
-        if (!emitted) {
-            this.state.completionSeen.delete(key);
-        }
-    }
-    handleResult = async (file) => {
-        const startedGeneration = this.generation;
-        const ownerSessionId = this.state.currentSessionId;
-        let claimed;
-        let emitted = false;
-        const resultPath = this.resultPath(file);
-        if (!fs.existsSync(resultPath)) {
-            return;
-        }
-        try {
-            if (this.isForeignUnchanged(resultPath)) {
-                return;
-            }
-            const envelope = readResultEnvelope(file, this.resultsDir);
-            if (this.foreign(envelope)) {
-                return;
-            }
-            const key = buildCompletionKey({ ...envelope.data, id: envelope.runId });
-            if (this.alreadyHandled(envelope, key)) {
-                return;
-            }
-            const prepared = prepareResult(envelope);
-            if (prepared === undefined) {
-                return;
-            }
-            if (!this.claimCompletion(envelope, key)) {
-                return;
-            }
-            claimed = key;
-            emitted = await this.deliverClaimed(envelope, prepared, key, {
-                generation: startedGeneration,
-                sessionId: ownerSessionId,
-            });
-            if (emitted) {
-                this.consumeNotification(envelope, key);
-            }
-        }
-        catch (error) {
-            if (!notFound(error)) {
-                console.error(`Failed to process subagent result file '${resultPath}':`, error);
-            }
-        }
-        finally {
-            this.releaseCompletion(claimed, emitted);
-        }
-    };
-    startBatch(files, generation) {
-        for (const file of files) {
-            if (generation !== this.generation) {
-                return;
-            }
-            const tail = this.handleResult(file)
-                .catch((error) => {
-                console.error(`Subagent delivery failed for '${file}':`, error);
-            })
-                .finally(() => {
-                this.inFlight.delete(tail);
-            });
-            this.inFlight.add(tail);
-        }
-    }
-    async drain(generation) {
-        try {
-            while (this.scheduled.size > 0) {
-                // Batches yield to native input; later starts depend on this generation guard.
-                // oxlint-disable-next-line no-await-in-loop
-                await yieldToInput();
-                if (generation !== this.generation) {
-                    return;
-                }
-                const files = [...this.scheduled].slice(0, 4);
-                for (const file of files) {
-                    this.scheduled.delete(file);
-                }
-                const start = () => {
-                    this.startBatch(files, generation);
-                };
-                if (this.deps.withReceiptBatch) {
-                    this.deps.withReceiptBatch(start);
-                }
-                else {
-                    start();
-                }
-            }
-        }
-        finally {
-            if (this.drainGeneration === generation) {
-                this.drainGeneration = undefined;
-            }
-        }
-    }
-    scheduleResult = (file) => {
-        this.scheduled.add(file);
-        if (this.drainGeneration === this.generation) {
-            return;
-        }
-        this.drainGeneration = this.generation;
-        const generation = this.generation;
-        this.startTail = this.startTail
-            .then(() => this.drain(generation))
-            .catch((error) => {
-            console.error("Failed to drain admitted subagent results:", error);
-        });
-    };
-    primeExistingResults = () => {
-        try {
-            this.pendingResultFiles().forEach(this.scheduleResult);
-        }
-        catch (error) {
-            if (!notFound(error)) {
-                console.error(`Failed to scan subagent result directory '${this.resultsDir}':`, error);
-            }
-        }
-    };
-    ensurePeriodicScan() {
-        if (this.periodicScanTimer) {
-            return;
-        }
-        this.periodicScanTimer = setInterval(this.primeExistingResults, POLL_INTERVAL_MS);
-        this.periodicScanTimer.unref();
-    }
-    clearPeriodicScan() {
-        if (this.periodicScanTimer) {
-            clearInterval(this.periodicScanTimer);
-            this.periodicScanTimer = null;
-        }
-    }
-    startPollingFallback(reason) {
-        this.state.watcher?.close();
-        this.state.watcher = null;
-        this.clearPeriodicScan();
-        if (this.state.watcherRestartTimer) {
-            return;
-        }
-        console.error(`Subagent result watcher for '${this.resultsDir}' fell back to polling because native fs.watch is unavailable (${errorCode(reason) ?? "unknown error"}).`);
-        this.primeExistingResults();
-        this.state.watcherRestartTimer = setInterval(this.primeExistingResults, POLL_INTERVAL_MS);
-        this.state.watcherRestartTimer.unref();
-    }
-    scheduleRestart() {
-        if (this.state.watcherRestartTimer) {
-            return;
-        }
-        this.state.watcherRestartTimer = setTimeout(() => {
-            this.state.watcherRestartTimer = null;
-            try {
-                fs.mkdirSync(this.resultsDir, { recursive: true });
-                this.startResultWatcher();
-            }
-            catch (error) {
-                if (pollingRequired(error)) {
-                    this.startPollingFallback(error);
-                    return;
-                }
-                console.error(`Failed to restart subagent result watcher for '${this.resultsDir}':`, error);
-                this.scheduleRestart();
-            }
-        }, RESTART_DELAY_MS);
-        this.state.watcherRestartTimer.unref();
-    }
-    startResultWatcher = () => {
-        if (this.state.watcher) {
-            this.ensurePeriodicScan();
-            return;
-        }
-        if (this.state.watcherRestartTimer) {
-            clearTimeout(this.state.watcherRestartTimer);
-            clearInterval(this.state.watcherRestartTimer);
-            this.state.watcherRestartTimer = null;
-        }
-        try {
-            this.state.watcher = fs.watch(this.resultsDir, (event, file) => {
-                if (event !== "rename" || !hasText(file)) {
-                    return;
-                }
-                if (file.endsWith(".json") && fs.existsSync(path.join(this.resultsDir, file))) {
-                    this.state.resultFileCoalescer.schedule(file);
-                }
-            });
-            this.state.watcher.on("error", (error) => {
-                if (pollingRequired(error)) {
-                    this.startPollingFallback(error);
-                    return;
-                }
-                console.error(`Subagent result watcher failed for '${this.resultsDir}':`, error);
-                this.state.watcher?.close();
-                this.state.watcher = null;
-                this.scheduleRestart();
-            });
-            this.state.watcher.unref();
-            this.ensurePeriodicScan();
-        }
-        catch (error) {
-            if (pollingRequired(error)) {
-                this.startPollingFallback(error);
-                return;
-            }
-            console.error(`Failed to start subagent result watcher for '${this.resultsDir}':`, error);
-            this.state.watcher = null;
-            this.scheduleRestart();
-        }
-    };
-    stopResultWatcher = (options = {}) => {
-        this.joiningGeneration = options.joinInFlight === true ? this.generation : undefined;
-        this.generation++;
-        if (options.preservePending === true) {
-            this.preserveBeforeGeneration = this.generation;
-        }
-        this.state.watcher?.close();
-        this.state.watcher = null;
-        this.clearPeriodicScan();
-        if (this.state.watcherRestartTimer) {
-            clearTimeout(this.state.watcherRestartTimer);
-            clearInterval(this.state.watcherRestartTimer);
-        }
-        this.state.watcherRestartTimer = null;
-        this.state.resultFileCoalescer.clear();
-        this.scheduled.clear();
-        this.foreignResults.clear();
-    };
-    joinInFlight = async () => {
-        await this.startTail;
-        await Promise.all(this.inFlight);
-        this.joiningGeneration = undefined;
-    };
-}
-export function createResultWatcher(pi, state, resultsDir, deps = {}) {
-    const watcher = new ResultWatcher(pi, state, resultsDir, deps);
-    return {
-        startResultWatcher: watcher.startResultWatcher,
-        primeExistingResults: watcher.primeExistingResults,
-        stopResultWatcher: watcher.stopResultWatcher,
-        joinInFlight: watcher.joinInFlight,
-    };
-}

package/dist/runs/background/run-id-resolver.js

@@ -1,84 +0,0 @@
-import { ASYNC_DIR, RESULTS_DIR } from "../../shared/types.js";
-import { hasText } from "./async-value.js";
-import { formatRunIdAmbiguity } from "../shared/run-id-ambiguity.js";
-import { exactAsyncRunLocation, findAsyncRunPrefixMatches } from "./async-run-location.js";
-import { assertSafeNestedId, findNestedRunMatchesById, findNestedRouteForRootId, } from "../shared/nested-events.js";
-function nestedScopeFromState(state) {
-    if (!state) {
-        return undefined;
-    }
-    const routes = [];
-    const seen = new Set();
-    const add = (route) => {
-        if (!route) {
-            return;
-        }
-        const key = `${route.rootRunId}:${route.eventSink}:${route.controlInbox}`;
-        if (seen.has(key)) {
-            return;
-        }
-        seen.add(key);
-        routes.push({ ...route });
-    };
-    for (const run of state.ownedRuns?.values() ?? []) {
-        add(findNestedRouteForRootId(run.runId));
-    }
-    for (const job of state.asyncJobs.values()) {
-        add(job.nestedRoute);
-    }
-    return { routes };
-}
-function resolveExact(id, location, scope, preferDirect) {
-    const exists = hasText(location.asyncDir) || hasText(location.resultPath);
-    if (exists && preferDirect) {
-        return { kind: "async", id, location };
-    }
-    const matches = findNestedRunMatchesById(id, scope === undefined ? {} : { scope });
-    if (matches.length > 1) {
-        throw new Error(`Nested run id '${id}' is ambiguous across authorized registries. Provide the full id after stale registries are cleaned up.`);
-    }
-    const match = matches.at(0);
-    if (match) {
-        return { kind: "nested", id, match };
-    }
-    return exists ? { kind: "async", id, location } : undefined;
-}
-function resolvePrefix(id, options, preferDirect) {
-    const asyncMatches = findAsyncRunPrefixMatches(id, options.asyncDirRoot ?? ASYNC_DIR, options.resultsDir ?? RESULTS_DIR);
-    const nestedMatches = findNestedRunMatchesById(id, { prefix: true, scope: options.nested });
-    const matches = [];
-    for (const match of asyncMatches) {
-        if (!preferDirect(match.id) && nestedMatches.some((nested) => nested.run.id === match.id)) {
-            continue;
-        }
-        matches.push({ kind: "async", id: match.id, location: match.location });
-    }
-    for (const match of nestedMatches) {
-        if (preferDirect(match.run.id) &&
-            asyncMatches.some((candidate) => candidate.id === match.run.id)) {
-            continue;
-        }
-        matches.push({ kind: "nested", id: match.run.id, match });
-    }
-    const unique = new Map(matches.map((match) => [
-        match.kind === "nested" ? `nested:${match.match.rootRunId}:${match.id}` : `async:${match.id}`,
-        match,
-    ]));
-    const values = [...unique.values()];
-    if (values.length > 1) {
-        throw new Error(formatRunIdAmbiguity("subagent", id, values.map((match) => `${match.kind}:${match.id}`)));
-    }
-    return values.at(0);
-}
-export function resolveSubagentRunId(id, deps = {}) {
-    assertSafeNestedId("id", id);
-    const root = deps.asyncDirRoot ?? ASYNC_DIR;
-    const results = deps.resultsDir ?? RESULTS_DIR;
-    const scope = deps.nested ?? nestedScopeFromState(deps.state);
-    // Storage discovery must not hide an authorized descendant route in a session scope.
-    const preferDirect = (runId) => scope === undefined ||
-        deps.state?.ownedRuns?.has(runId) === true ||
-        deps.state?.asyncJobs.has(runId) === true;
-    const exact = resolveExact(id, exactAsyncRunLocation(id, root, results), scope, preferDirect(id));
-    return exact ?? resolvePrefix(id, { ...deps, nested: scope }, preferDirect);
-}