@astralyn/pi 0.87.6 → 1.0.0

package/dist/core/background/service.js

@@ -1,641 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { parseBackgroundHistory } from "./history.js";
-import { BACKGROUND_TITLE_BYTES, boundedResult, boundText, finiteLimit, readOutputSlice, sliceText } from "./output.js";
-import { readBackgroundProjection } from "./presentation.js";
-import { BackgroundExecutionError, BackgroundLookupError, isForegroundShellTask, SUBAGENT_BACKGROUND_REJECTION, } from "./types.js";
-function errorText(error) {
-    try {
-        return boundText(error instanceof Error ? error.message : String(error), 4096);
-    }
-    catch {
-        return "Background execution failed (unprintable error)";
-    }
-}
-function storeResult(task, result, truncated = false) {
-    const bounded = boundedResult(result);
-    task.result = bounded;
-    task.resultTruncated =
-        truncated ||
-            bounded.content.length !== result.content.length ||
-            bounded.content.some((block, index) => {
-                const original = result.content[index];
-                return original?.type !== "text" || block.type !== "text" || block.text !== original.text;
-            });
-}
-function oldestTask(tasks) {
-    let oldest;
-    for (const task of tasks) {
-        if (!oldest || task.endedAt < oldest.endedAt)
-            oldest = task;
-    }
-    return oldest;
-}
-/** Session-local supervision. Executors own their processes, workers and output files. */
-export class BackgroundService {
-    get closed() {
-        return this._closed;
-    }
-    constructor(options = {}) {
-        this.records = new Map();
-        this.listeners = new Set();
-        this._closed = false;
-        this.cleanups = new Set();
-        this.pauses = 0;
-        this.options = options;
-        this.configuredEnabled = options.enabled ?? false;
-        this.maxActive = Math.max(1, finiteLimit(options.maxActive, 8, 128));
-        this.maxHistory = finiteLimit(options.maxHistory, 32, 1024);
-        // Separate foreground shell history, plus the existing history/protected-record allowance.
-        this.maxRetained = this.maxActive + 2 * Math.max(1, this.maxHistory) + this.maxHistory;
-    }
-    /**
-     * Rehydrate terminal version-2 custom data only, newest endedAt in each history
-     * (later input wins ties). Existing runtime records win ID collisions. No execution, accounting,
-     * notification, or deletion ownership is restored, including for worker projections.
-     * The host supplies the current branch; closed services ignore restoration.
-     */
-    restoreHistory(records) {
-        if (this.closed)
-            return;
-        // Restoration must not evict runtime-owned records or run their cleanup callbacks.
-        const history = this.historyRecords();
-        const shells = history.filter((record) => isForegroundShellTask(record.task)).length;
-        const shellCapacity = Math.max(0, this.maxHistory - shells);
-        const taskCapacity = Math.max(0, this.maxHistory - (history.length - shells));
-        const capacity = Math.max(0, Math.min(shellCapacity + taskCapacity, this.maxRetained - this.records.size - this.cleanups.size));
-        const newest = new Map();
-        for (const value of records) {
-            const task = parseBackgroundHistory(value);
-            if (!task)
-                continue;
-            const existing = this.records.get(task.id);
-            if (existing) {
-                if (existing.settled)
-                    existing.visible = true;
-                continue;
-            }
-            if (capacity === 0)
-                continue;
-            const previous = newest.get(task.id);
-            if (previous && previous.endedAt > task.endedAt)
-                continue;
-            newest.delete(task.id);
-            const shell = isForegroundShellTask(task);
-            const limit = shell ? shellCapacity : taskCapacity;
-            if (limit === 0)
-                continue;
-            newest.set(task.id, task);
-            const group = [...newest.values()].filter((candidate) => isForegroundShellTask(candidate) === shell);
-            if (group.length > limit)
-                newest.delete(oldestTask(group).id);
-            if (newest.size > capacity) {
-                // Protected runtime records can leave less room than both histories allow.
-                // Restore inspectable tasks before hidden foreground shell logs in that case.
-                const foreground = [...newest.values()].filter(isForegroundShellTask);
-                newest.delete(oldestTask(foreground.length ? foreground : newest.values()).id);
-            }
-        }
-        for (const task of [...newest.values()].sort((a, b) => a.endedAt - b.endedAt)) {
-            this.records.set(task.id, {
-                task,
-                controller: new AbortController(),
-                accepted: false,
-                handedOff: false,
-                detachRequested: false,
-                settled: true,
-                accounted: true,
-                visible: true,
-                suppressed: true,
-                delivery: "delivered",
-                pins: 0,
-                waiters: new Set(),
-                removeParent: () => { },
-                handoff: () => { },
-                done: Promise.resolve(),
-            });
-        }
-    }
-    get enabled() {
-        return this.configuredEnabled && !this.closed && this.options.role !== "subagent";
-    }
-    setEnabled(enabled) {
-        this.configuredEnabled = enabled;
-        this.emit();
-    }
-    async execute(execution) {
-        // Admission and registration happen synchronously, before invoking user code or awaiting anything.
-        if (this.options.role === "subagent")
-            throw new Error(SUBAGENT_BACKGROUND_REJECTION);
-        if (this.closed)
-            throw new Error("Background service is closed");
-        if (!this.enabled)
-            throw new Error("Background execution is not available in this host");
-        if (execution.signal?.aborted)
-            throw execution.signal.reason ?? new Error("Execution aborted");
-        if ([...this.records.values()].filter((record) => !record.settled).length >= this.maxActive) {
-            throw new Error(`Background execution limit reached (${this.maxActive})`);
-        }
-        if (this.records.size + this.cleanups.size >= this.maxRetained) {
-            throw new Error("Background history retention limit reached; deliver pending notifications or release pinned or claimed records");
-        }
-        const anchorId = this.options.anchor?.() ?? null;
-        if (anchorId !== null && Buffer.byteLength(anchorId) > 8192)
-            throw new Error("Background branch anchor is too large");
-        const task = {
-            id: `${execution.kind}-${randomUUID()}`,
-            kind: execution.kind,
-            title: boundText(execution.title, BACKGROUND_TITLE_BYTES),
-            toolCallId: boundText(execution.toolCallId, 512),
-            anchorId,
-            mode: execution.background ? "background" : "foreground",
-            status: "queued",
-            startedAt: Date.now(),
-            command: execution.command === undefined ? undefined : boundText(execution.command, 8192),
-            commandTruncated: execution.command === undefined ? undefined : boundText(execution.command, 8192) !== execution.command,
-            cwd: execution.cwd === undefined ? undefined : boundText(execution.cwd, 4096),
-        };
-        let resolveCaller;
-        let rejectCaller;
-        const caller = new Promise((resolve, reject) => {
-            resolveCaller = resolve;
-            rejectCaller = reject;
-        });
-        let resolveDone;
-        const record = {
-            task,
-            controller: new AbortController(),
-            accepted: false,
-            handedOff: false,
-            detachRequested: execution.background ?? false,
-            settled: false,
-            accounted: false,
-            visible: true,
-            suppressed: false,
-            delivery: "pending",
-            pins: 0,
-            waiters: new Set(),
-            removeParent: () => { },
-            handoff: () => {
-                if (!record.accepted ||
-                    !record.detachRequested ||
-                    record.settled ||
-                    record.handedOff ||
-                    this.closed ||
-                    record.suppressed ||
-                    record.controller.signal.aborted)
-                    return;
-                record.handedOff = true;
-                task.mode = "background";
-                record.removeParent();
-                resolveCaller({ kind: "background", task: this.snapshot(record) });
-                this.emit();
-            },
-            done: new Promise((resolve) => {
-                resolveDone = resolve;
-            }),
-        };
-        const parentSignal = execution.signal;
-        let onUpdate = execution.background ? undefined : execution.onUpdate;
-        const parentAbort = () => {
-            if (!record.detachRequested || !record.accepted)
-                this.cancel(record);
-        };
-        parentSignal?.addEventListener("abort", parentAbort, { once: true });
-        record.removeParent = () => {
-            parentSignal?.removeEventListener("abort", parentAbort);
-            onUpdate = undefined;
-        };
-        this.records.set(task.id, record);
-        const control = {
-            id: task.id,
-            signal: record.controller.signal,
-            get mode() {
-                return task.mode;
-            },
-            accept: () => {
-                if (record.settled || record.accepted || this.closed || record.controller.signal.aborted)
-                    return;
-                record.accepted = true;
-                if (task.status === "queued")
-                    task.status = "running";
-                if (record.detachRequested)
-                    record.removeParent();
-                // Let an already available final result win over a handoff.
-                queueMicrotask(() => queueMicrotask(record.handoff));
-                this.emit();
-            },
-            publish: (result, projection) => {
-                if (record.settled || this.closed)
-                    return;
-                storeResult(task, result);
-                if (result.usage !== undefined)
-                    record.publishedUsage = structuredClone(result.usage);
-                if (projection)
-                    task.projection = readBackgroundProjection(projection);
-                if (!record.detachRequested && !record.handedOff) {
-                    try {
-                        onUpdate?.(result);
-                    }
-                    catch {
-                        /* UI observers cannot stop execution. */
-                    }
-                }
-                this.emit();
-            },
-            setOutputPath: (path, cleanup) => {
-                if (record.settled) {
-                    if (cleanup)
-                        throw new Error("Background execution has settled");
-                    return;
-                }
-                if (record.cleanup)
-                    throw new Error("Managed output is already registered");
-                // Never truncate a real filesystem path into a different path.
-                if (Buffer.byteLength(path) > 8192)
-                    throw new Error("Background output path is too large");
-                record.cleanup = cleanup;
-                task.outputPath = path;
-                this.emit();
-            },
-        };
-        const finish = (completion, error) => {
-            if (record.settled)
-                return;
-            record.settled = true;
-            record.removeParent();
-            task.endedAt = Date.now();
-            const failed = completion === undefined;
-            task.status =
-                completion?.status ??
-                    (error instanceof BackgroundExecutionError
-                        ? error.status
-                        : record.controller.signal.aborted
-                            ? "cancelled"
-                            : failed
-                                ? "failed"
-                                : "completed");
-            if (completion) {
-                storeResult(task, completion.result);
-                if (completion.error !== undefined)
-                    task.error = boundText(completion.error, 4096);
-                if (completion.exitCode !== undefined)
-                    task.exitCode = completion.exitCode;
-            }
-            if (failed) {
-                task.error = errorText(error);
-                storeResult(task, {
-                    content: [{ type: "text", text: task.error }, ...(task.result?.content ?? [])],
-                    details: task.result?.details,
-                }, task.resultTruncated);
-            }
-            let settlementWarning;
-            try {
-                this.options.onSettled?.(this.snapshot(record), completion?.usage ?? completion?.result.usage ?? record.publishedUsage);
-            }
-            catch (accountingError) {
-                const warning = `Usage settlement failed: ${errorText(accountingError)}`;
-                settlementWarning = warning;
-                task.error = boundText([task.error, warning].filter(Boolean).join("\n"), 8192);
-                storeResult(task, {
-                    content: [{ type: "text", text: warning }, ...(task.result?.content ?? [])],
-                    details: task.result?.details,
-                }, task.resultTruncated);
-            }
-            record.publishedUsage = undefined;
-            record.accounted = true;
-            if (!record.handedOff) {
-                record.delivery = "delivered";
-                if (failed)
-                    rejectCaller(error);
-                else {
-                    const { usage: _usage, ...result } = completion.result;
-                    if (settlementWarning)
-                        result.content = [{ type: "text", text: settlementWarning }, ...result.content];
-                    resolveCaller({ kind: "result", result, status: task.status, error: task.error });
-                }
-            }
-            for (const waiter of [...record.waiters])
-                waiter();
-            resolveDone();
-            this.trim();
-            this.emit();
-        };
-        // The rejection handler is installed immediately, including for synchronous preflight throws.
-        try {
-            const running = execution.run(control);
-            void Promise.resolve(running).then((result) => finish(result), (error) => finish(undefined, error));
-        }
-        catch (error) {
-            finish(undefined, error);
-        }
-        this.emit();
-        return caller;
-    }
-    detachForeground() {
-        if (!this.enabled)
-            return 0;
-        const records = [...this.records.values()].filter((record) => !record.settled && !record.detachRequested && !record.controller.signal.aborted);
-        // Update the whole batch before callbacks/observers can re-enter.
-        for (const record of records) {
-            record.detachRequested = true;
-            record.task.mode = "background";
-            if (record.accepted)
-                record.removeParent();
-        }
-        for (const record of records)
-            record.handoff();
-        if (records.length)
-            this.emit();
-        return records.length;
-    }
-    list() {
-        return [...this.records.values()].filter((record) => record.visible).map((record) => this.snapshot(record));
-    }
-    lookup(id) {
-        const exact = this.records.get(id);
-        if (exact)
-            return exact;
-        const matches = [...this.records.values()].filter(({ task }) => task.id.startsWith(id) || task.id.slice(task.kind.length + 1).startsWith(id));
-        if (!id || matches.length !== 1) {
-            throw new BackgroundLookupError(matches.length > 1 ? "ambiguous" : "unknown", matches.map((record) => this.snapshot(record)));
-        }
-        return matches[0];
-    }
-    get(id) {
-        return this.snapshot(this.lookup(id));
-    }
-    async read(id, options = {}) {
-        const record = this.lookup(id);
-        const release = this.pin(record.task.id);
-        try {
-            const task = this.snapshot(record);
-            if (task.outputPath) {
-                try {
-                    return { task, ...(await readOutputSlice(task.outputPath, options)) };
-                }
-                catch (error) {
-                    return {
-                        task,
-                        readError: boundText(`Output could not be read: ${errorText(error)}`, 4096),
-                        ...sliceText(this.resultText(task), options),
-                    };
-                }
-            }
-            return { task, readError: record.readError, ...sliceText(this.resultText(task), options) };
-        }
-        finally {
-            release();
-        }
-    }
-    resultText(task) {
-        return boundText(task.result?.content
-            .filter((block) => block.type === "text")
-            .map((block) => block.text)
-            .join("\n") ||
-            task.projection?.text ||
-            task.error ||
-            "No output yet.");
-    }
-    /** Observe completion without consuming delivery; the host acknowledges only persisted tool results. */
-    async wait(id, timeoutMs = 20_000, signal) {
-        if (signal?.aborted)
-            throw signal.reason ?? new Error("Wait aborted");
-        const record = this.lookup(id);
-        if (record.settled)
-            return this.snapshot(record);
-        return new Promise((resolve, reject) => {
-            let finished = false;
-            let timer;
-            const complete = (aborted = false) => {
-                if (finished)
-                    return;
-                finished = true;
-                if (timer !== undefined)
-                    clearTimeout(timer);
-                signal?.removeEventListener("abort", abort);
-                record.waiters.delete(wake);
-                if (aborted)
-                    reject(signal?.reason ?? new Error("Wait aborted"));
-                else
-                    resolve(this.snapshot(record));
-                this.trim();
-                this.emit();
-            };
-            const wake = () => complete();
-            const abort = () => complete(true);
-            record.waiters.add(wake);
-            signal?.addEventListener("abort", abort, { once: true });
-            timer = setTimeout(wake, finiteLimit(timeoutMs, 20_000, 60_000));
-            if (this.closed)
-                wake();
-        });
-    }
-    kill(id) {
-        return this.cancel(this.lookup(id));
-    }
-    cancel(record) {
-        if (record.settled || record.controller.signal.aborted)
-            return false;
-        record.task.status = "stopping";
-        record.controller.abort();
-        this.emit();
-        return true;
-    }
-    subscribe(listener) {
-        if (this.closed)
-            return () => { };
-        this.listeners.add(listener);
-        return () => {
-            this.listeners.delete(listener);
-        };
-    }
-    /**
-     * Pins defer history eviction and completion delivery, so a live read or a watched row
-     * never races an automatic notification for the same record. Releasing resumes both, and
-     * announces the record only when that unblocks a delivery.
-     */
-    pin(id) {
-        const record = this.lookup(id);
-        record.pins++;
-        let released = false;
-        return () => {
-            if (released)
-                return;
-            released = true;
-            record.pins--;
-            this.trim();
-            if (!this.closed && this.pauses === 0 && this.candidate(record))
-                this.emit();
-        };
-    }
-    pause() {
-        this.pauses++;
-        let resumed = false;
-        return () => {
-            if (resumed)
-                return;
-            resumed = true;
-            this.pauses--;
-            this.emit();
-        };
-    }
-    pendingNotifications() {
-        if (this.closed || this.pauses > 0)
-            return [];
-        return [...this.records.values()]
-            .filter((record) => this.candidate(record))
-            .map((record) => this.snapshot(record));
-    }
-    /**
-     * A pinned record is being read or watched, so its completion is not announced yet:
-     * a terminal `bg wait` or `bg read` delivers the result as its own tool result instead.
-     */
-    candidate(record) {
-        return (record.visible &&
-            record.settled &&
-            record.accounted &&
-            record.handedOff &&
-            !record.suppressed &&
-            record.delivery === "pending" &&
-            record.waiters.size === 0 &&
-            record.pins === 0);
-    }
-    claimNotification(id) {
-        if (this.closed || this.pauses > 0)
-            return false;
-        const record = this.records.get(id);
-        if (!record || !this.candidate(record))
-            return false;
-        record.delivery = "claimed";
-        return true;
-    }
-    markDelivered(id) {
-        const record = this.records.get(id);
-        if (!record)
-            return;
-        record.delivery = "delivered";
-        this.trim();
-    }
-    releaseNotification(id) {
-        const record = this.records.get(id);
-        if (!record || record.delivery !== "claimed")
-            return;
-        record.delivery = "pending";
-        this.trim();
-        this.emit();
-    }
-    close() {
-        if (this.closed)
-            return;
-        this._closed = true;
-        this.listeners.clear();
-        for (const record of this.records.values()) {
-            record.suppressed = true;
-            record.removeParent();
-            this.cancel(record);
-            for (const waiter of [...record.waiters])
-                waiter();
-        }
-        this.trim();
-    }
-    async shutdown(graceMs = 2000) {
-        this.close();
-        await this.drain([...this.records.values()], graceMs);
-    }
-    async cancelOutsideBranch(ancestors) {
-        for (const record of this.records.values()) {
-            record.visible = record.task.anchorId === null || ancestors.has(record.task.anchorId);
-            // Returning to a branch revives its undelivered completions; restored history
-            // stays delivered and suppressed.
-            if (record.visible && record.delivery === "pending")
-                record.suppressed = false;
-        }
-        const outside = [...this.records.values()].filter((record) => !record.visible);
-        for (const record of outside)
-            record.suppressed = true;
-        for (const record of outside)
-            this.cancel(record);
-        this.trim();
-        this.emit();
-        await this.drain(outside, 2000);
-    }
-    async drain(records, graceMs) {
-        let timer;
-        try {
-            await Promise.race([
-                Promise.all(records.map((record) => record.done)).then(() => Promise.all(this.cleanups)),
-                new Promise((resolve) => {
-                    timer = setTimeout(resolve, finiteLimit(graceMs, 2000, 60_000));
-                }),
-            ]);
-        }
-        finally {
-            if (timer !== undefined)
-                clearTimeout(timer);
-        }
-    }
-    snapshot(record) {
-        return structuredClone(record.task);
-    }
-    cleanupOutput(record) {
-        if (!record.settled || record.pins || record.waiters.size || !record.cleanup)
-            return;
-        const cleanup = record.cleanup;
-        record.cleanup = undefined;
-        // Snapshots retain final bounded text; expired files are never needed to render history.
-        record.task.outputPath = undefined;
-        record.readError = "Output has expired: the managed log was released; showing the stored result.";
-        const pending = Promise.resolve()
-            .then(cleanup)
-            .catch((error) => {
-            try {
-                this.options.onCleanupError?.(errorText(error));
-            }
-            catch {
-                /* Cleanup/reporting is best effort, never an unhandled rejection. */
-            }
-        })
-            .finally(() => this.cleanups.delete(pending));
-        this.cleanups.add(pending);
-    }
-    /** Pending delivery, active reads and pins have their own bounded retention allowance. */
-    historyRecords() {
-        return [...this.records.values()].filter((record) => record.settled && record.delivery === "delivered" && !record.pins && !record.waiters.size);
-    }
-    trim() {
-        if (this.closed) {
-            for (const record of this.records.values())
-                this.cleanupOutput(record);
-            return;
-        }
-        // Undelivered notifications and claims are never evicted. Admission bounds all retention.
-        const history = this.historyRecords();
-        // Delivered history can be restored from branch snapshots; hidden rows must
-        // not occupy the current branch's history budget. Pending results stay owned.
-        const expired = history.filter((record) => !record.visible);
-        for (const shell of [false, true]) {
-            const group = history.filter((record) => record.visible && isForegroundShellTask(record.task) === shell);
-            group.sort((left, right) => (left.task.endedAt ?? 0) - (right.task.endedAt ?? 0));
-            expired.push(...group.slice(0, Math.max(0, group.length - this.maxHistory)));
-        }
-        for (const record of expired) {
-            this.records.delete(record.task.id);
-            this.cleanupOutput(record);
-        }
-    }
-    emit() {
-        if (this.closed)
-            return;
-        for (const listener of [...this.listeners]) {
-            if (this.closed)
-                break;
-            try {
-                listener();
-            }
-            catch {
-                /* Observers do not own execution or delivery. */
-            }
-        }
-    }
-}
-//# sourceMappingURL=service.js.map