@astralyn/pi 0.87.5 → 0.99.0

package/dist/core/{background/service.js → tasks/runtime.js}

@@ -1,8 +1,10 @@
 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";
+import { boundedResult, boundText, finiteLimit, readOutputSlice, sliceText, TASK_TITLE_BYTES } from "./output.js";
+import { readTaskProjection } from "./presentation.js";
+import { TaskStore } from "./store.js";
+import { TASK_BACKGROUND_REJECTION, TaskExecutionError, TaskLookupError, } from "./types.js";
+import { TaskViewRegistry } from "./view.js";
+import { readTaskViewData } from "./view-data.js";
 function errorText(error) {
     try {
         return boundText(error instanceof Error ? error.message : String(error), 4096);
@@ -12,7 +14,7 @@ function errorText(error) {
     }
 }
 function storeResult(task, result, truncated = false) {
-    const bounded = boundedResult(result);
+    const bounded = boundedResult({ content: result.content, details: undefined });
     task.result = bounded;
     task.resultTruncated =
         truncated ||
@@ -22,24 +24,16 @@ function storeResult(task, result, truncated = false) {
                 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 {
+/** Session-local supervision. Executors own their processes, items and output files. */
+export class TaskRuntime {
     get closed() {
         return this._closed;
     }
     constructor(options = {}) {
-        this.records = new Map();
+        this.views = new TaskViewRegistry();
+        this.executions = new Map();
         this.listeners = new Set();
         this._closed = false;
-        this.cleanups = new Set();
         this.pauses = 0;
         this.options = options;
         this.configuredEnabled = options.enabled ?? false;
@@ -47,6 +41,7 @@ export class BackgroundService {
         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;
+        this.store = new TaskStore(this.maxHistory, this.maxRetained, () => this.closed, options.onCleanupError);
     }
     /**
      * Rehydrate terminal version-2 custom data only, newest endedAt in each history
@@ -55,68 +50,10 @@ export class BackgroundService {
      * 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(),
-            });
-        }
+        this.store.restoreHistory(records);
     }
     get enabled() {
-        return this.configuredEnabled && !this.closed && this.options.role !== "subagent";
+        return this.configuredEnabled && !this.closed && this.options.backgroundAllowed !== false;
     }
     setEnabled(enabled) {
         this.configuredEnabled = enabled;
@@ -124,27 +61,30 @@ export class BackgroundService {
     }
     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 (execution.background && this.options.backgroundAllowed === false)
+            throw new Error(TASK_BACKGROUND_REJECTION);
         if (this.closed)
             throw new Error("Background service is closed");
-        if (!this.enabled)
+        if (execution.background && !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) {
+        if ([...this.store.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) {
+        if (this.store.records.size + this.store.cleanups.size >= this.maxRetained) {
             throw new Error("Background history retention limit reached; deliver pending notifications or release pinned or claimed records");
         }
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(execution.kind))
+            throw new Error("Invalid task source");
         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),
+            format: execution.format ?? "report",
+            title: boundText(execution.title, TASK_TITLE_BYTES),
             toolCallId: boundText(execution.toolCallId, 512),
             anchorId,
             mode: execution.background ? "background" : "foreground",
@@ -163,30 +103,35 @@ export class BackgroundService {
         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,
+            deliveryHolds: 0,
             waiters: new Set(),
+        };
+        const active = {
+            controller: new AbortController(),
+            accepted: false,
+            handedOff: false,
+            detachRequested: execution.background ?? false,
+            modeListeners: new Set(),
             removeParent: () => { },
             handoff: () => {
-                if (!record.accepted ||
-                    !record.detachRequested ||
+                if (!active.accepted ||
+                    !active.detachRequested ||
                     record.settled ||
-                    record.handedOff ||
+                    active.handedOff ||
                     this.closed ||
                     record.suppressed ||
-                    record.controller.signal.aborted)
+                    active.controller.signal.aborted)
                     return;
+                active.handedOff = true;
                 record.handedOff = true;
                 task.mode = "background";
-                record.removeParent();
+                active.removeParent();
                 resolveCaller({ kind: "background", task: this.snapshot(record) });
                 this.emit();
             },
@@ -197,31 +142,41 @@ export class BackgroundService {
         const parentSignal = execution.signal;
         let onUpdate = execution.background ? undefined : execution.onUpdate;
         const parentAbort = () => {
-            if (!record.detachRequested || !record.accepted)
+            if (!active.detachRequested || !active.accepted)
                 this.cancel(record);
         };
         parentSignal?.addEventListener("abort", parentAbort, { once: true });
-        record.removeParent = () => {
+        active.removeParent = () => {
             parentSignal?.removeEventListener("abort", parentAbort);
             onUpdate = undefined;
         };
-        this.records.set(task.id, record);
+        this.store.records.set(task.id, record);
+        this.executions.set(task.id, active);
         const control = {
             id: task.id,
-            signal: record.controller.signal,
+            signal: active.controller.signal,
             get mode() {
                 return task.mode;
             },
+            onModeChange: (listener) => {
+                if (record.settled || this.closed)
+                    return () => { };
+                active.modeListeners.add(listener);
+                return () => {
+                    active.modeListeners.delete(listener);
+                };
+            },
+            requestCancel: () => this.cancel(record),
             accept: () => {
-                if (record.settled || record.accepted || this.closed || record.controller.signal.aborted)
+                if (record.settled || active.accepted || this.closed || active.controller.signal.aborted)
                     return;
-                record.accepted = true;
+                active.accepted = true;
                 if (task.status === "queued")
                     task.status = "running";
-                if (record.detachRequested)
-                    record.removeParent();
+                if (active.detachRequested)
+                    active.removeParent();
                 // Let an already available final result win over a handoff.
-                queueMicrotask(() => queueMicrotask(record.handoff));
+                queueMicrotask(() => queueMicrotask(active.handoff));
                 this.emit();
             },
             publish: (result, projection) => {
@@ -229,10 +184,10 @@ export class BackgroundService {
                     return;
                 storeResult(task, result);
                 if (result.usage !== undefined)
-                    record.publishedUsage = structuredClone(result.usage);
+                    active.publishedUsage = structuredClone(result.usage);
                 if (projection)
-                    task.projection = readBackgroundProjection(projection);
-                if (!record.detachRequested && !record.handedOff) {
+                    task.projection = readTaskProjection(projection);
+                if (!active.detachRequested && !active.handedOff) {
                     try {
                         onUpdate?.(result);
                     }
@@ -257,19 +212,26 @@ export class BackgroundService {
                 task.outputPath = path;
                 this.emit();
             },
+            publishView: (data) => {
+                if (record.settled || this.closed)
+                    return;
+                task.viewData = readTaskViewData(data);
+                this.emit();
+            },
         };
         const finish = (completion, error) => {
             if (record.settled)
                 return;
             record.settled = true;
-            record.removeParent();
+            active.modeListeners.clear();
+            active.removeParent();
             task.endedAt = Date.now();
             const failed = completion === undefined;
             task.status =
                 completion?.status ??
-                    (error instanceof BackgroundExecutionError
+                    (error instanceof TaskExecutionError
                         ? error.status
-                        : record.controller.signal.aborted
+                        : active.controller.signal.aborted
                             ? "cancelled"
                             : failed
                                 ? "failed"
@@ -290,7 +252,7 @@ export class BackgroundService {
             }
             let settlementWarning;
             try {
-                this.options.onSettled?.(this.snapshot(record), completion?.usage ?? completion?.result.usage ?? record.publishedUsage);
+                this.options.onSettled?.(this.snapshot(record), completion?.usage ?? completion?.result.usage ?? active.publishedUsage);
             }
             catch (accountingError) {
                 const warning = `Usage settlement failed: ${errorText(accountingError)}`;
@@ -301,9 +263,9 @@ export class BackgroundService {
                     details: task.result?.details,
                 }, task.resultTruncated);
             }
-            record.publishedUsage = undefined;
+            active.publishedUsage = undefined;
             record.accounted = true;
-            if (!record.handedOff) {
+            if (!active.handedOff) {
                 record.delivery = "delivered";
                 if (failed)
                     rejectCaller(error);
@@ -317,7 +279,8 @@ export class BackgroundService {
             for (const waiter of [...record.waiters])
                 waiter();
             resolveDone();
-            this.trim();
+            this.executions.delete(task.id);
+            this.store.trim();
             this.emit();
         };
         // The rejection handler is installed immediately, including for synchronous preflight throws.
@@ -334,30 +297,57 @@ export class BackgroundService {
     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();
-        }
+        const records = [...this.store.records.values()].filter((record) => {
+            const active = this.executions.get(record.task.id);
+            return active && !record.settled && !active.detachRequested && !active.controller.signal.aborted;
+        });
+        for (const record of records)
+            this.prepareDetach(record);
         for (const record of records)
-            record.handoff();
+            this.finishDetach(record);
         if (records.length)
             this.emit();
         return records.length;
     }
+    detach(id) {
+        const record = this.lookup(id);
+        const active = this.executions.get(record.task.id);
+        if (!this.enabled || !active || record.settled || active.detachRequested || active.controller.signal.aborted)
+            return false;
+        this.prepareDetach(record);
+        this.finishDetach(record);
+        this.emit();
+        return true;
+    }
+    prepareDetach(record) {
+        const active = this.executions.get(record.task.id);
+        active.detachRequested = true;
+        record.task.mode = "background";
+        if (active.accepted)
+            active.removeParent();
+    }
+    finishDetach(record) {
+        const active = this.executions.get(record.task.id);
+        active.handoff();
+        for (const listener of active.modeListeners) {
+            try {
+                listener(record.task.mode);
+            }
+            catch {
+                /* Executors own their diagnostics. */
+            }
+        }
+    }
     list() {
-        return [...this.records.values()].filter((record) => record.visible).map((record) => this.snapshot(record));
+        return [...this.store.records.values()].filter((record) => record.visible).map((record) => this.snapshot(record));
     }
     lookup(id) {
-        const exact = this.records.get(id);
+        const exact = this.store.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));
+        const matches = [...this.store.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)));
+            throw new TaskLookupError(matches.length > 1 ? "ambiguous" : "unknown", matches.map((record) => this.snapshot(record)));
         }
         return matches[0];
     }
@@ -366,7 +356,7 @@ export class BackgroundService {
     }
     async read(id, options = {}) {
         const record = this.lookup(id);
-        const release = this.pin(record.task.id);
+        const release = this.retain(record.task.id);
         try {
             const task = this.snapshot(record);
             if (task.outputPath) {
@@ -418,7 +408,7 @@ export class BackgroundService {
                     reject(signal?.reason ?? new Error("Wait aborted"));
                 else
                     resolve(this.snapshot(record));
-                this.trim();
+                this.store.trim();
                 this.emit();
             };
             const wake = () => complete();
@@ -434,10 +424,11 @@ export class BackgroundService {
         return this.cancel(this.lookup(id));
     }
     cancel(record) {
-        if (record.settled || record.controller.signal.aborted)
+        const active = this.executions.get(record.task.id);
+        if (!active || record.settled || active.controller.signal.aborted)
             return false;
         record.task.status = "stopping";
-        record.controller.abort();
+        active.controller.abort();
         this.emit();
         return true;
     }
@@ -450,11 +441,9 @@ export class BackgroundService {
         };
     }
     /**
-     * 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.
+     * Retention protects snapshots and logs only. Delivery has its own explicit hold.
      */
-    pin(id) {
+    retain(id) {
         const record = this.lookup(id);
         record.pins++;
         let released = false;
@@ -463,11 +452,24 @@ export class BackgroundService {
                 return;
             released = true;
             record.pins--;
-            this.trim();
+            this.store.trim();
             if (!this.closed && this.pauses === 0 && this.candidate(record))
                 this.emit();
         };
     }
+    holdDelivery(id) {
+        const record = this.lookup(id);
+        const releaseRetention = this.retain(id);
+        record.deliveryHolds++;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            record.deliveryHolds--;
+            releaseRetention();
+        };
+    }
     pause() {
         this.pauses++;
         let resumed = false;
@@ -482,80 +484,80 @@ export class BackgroundService {
     pendingNotifications() {
         if (this.closed || this.pauses > 0)
             return [];
-        return [...this.records.values()]
+        return [...this.store.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.
+     * Only explicit result-delivery holds delay an automatic completion.
      */
     candidate(record) {
         return (record.visible &&
             record.settled &&
             record.accounted &&
-            record.handedOff &&
+            record.handedOff === true &&
             !record.suppressed &&
             record.delivery === "pending" &&
             record.waiters.size === 0 &&
-            record.pins === 0);
+            record.deliveryHolds === 0);
     }
     claimNotification(id) {
         if (this.closed || this.pauses > 0)
             return false;
-        const record = this.records.get(id);
+        const record = this.store.records.get(id);
         if (!record || !this.candidate(record))
             return false;
         record.delivery = "claimed";
         return true;
     }
     markDelivered(id) {
-        const record = this.records.get(id);
+        const record = this.store.records.get(id);
         if (!record)
             return;
         record.delivery = "delivered";
-        this.trim();
+        this.store.trim();
     }
     releaseNotification(id) {
-        const record = this.records.get(id);
+        const record = this.store.records.get(id);
         if (!record || record.delivery !== "claimed")
             return;
         record.delivery = "pending";
-        this.trim();
+        this.store.trim();
         this.emit();
     }
     close() {
         if (this.closed)
             return;
         this._closed = true;
+        this.views.close();
         this.listeners.clear();
-        for (const record of this.records.values()) {
+        for (const record of this.store.records.values()) {
             record.suppressed = true;
-            record.removeParent();
+            this.executions.get(record.task.id)?.removeParent();
             this.cancel(record);
             for (const waiter of [...record.waiters])
                 waiter();
         }
-        this.trim();
+        this.store.trim();
     }
     async shutdown(graceMs = 2000) {
         this.close();
-        await this.drain([...this.records.values()], graceMs);
+        await this.drain([...this.store.records.values()], graceMs);
     }
     async cancelOutsideBranch(ancestors) {
-        for (const record of this.records.values()) {
+        for (const record of this.store.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);
+        const outside = [...this.store.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.store.trim();
         this.emit();
         await this.drain(outside, 2000);
     }
@@ -563,7 +565,7 @@ export class BackgroundService {
         let timer;
         try {
             await Promise.race([
-                Promise.all(records.map((record) => record.done)).then(() => Promise.all(this.cleanups)),
+                Promise.all(records.map((record) => this.executions.get(record.task.id)?.done)).then(() => Promise.all(this.store.cleanups)),
                 new Promise((resolve) => {
                     timer = setTimeout(resolve, finiteLimit(graceMs, 2000, 60_000));
                 }),
@@ -577,52 +579,6 @@ export class BackgroundService {
     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;
@@ -638,4 +594,4 @@ export class BackgroundService {
         }
     }
 }
-//# sourceMappingURL=service.js.map
+//# sourceMappingURL=runtime.js.map