@astralyn/pi 1.4.8 → 1.4.10

package/dist/core/tasks/delivery.d.ts

@@ -1,15 +1,19 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { CustomMessage } from "../messages.ts";
-import type { TaskDeliveryLedger } from "./types.ts";
+import type { TaskSnapshot, TasksContext } from "./types.ts";
+/** All the delivery policy needs from a runtime: its public, session-independent surface. */
+export type TaskDeliveryService = Pick<TasksContext, "enabled" | "closed" | "list" | "retain">;
 export interface TaskDeliveryOptions {
-    service(): TaskDeliveryLedger;
+    service(): TaskDeliveryService;
     canDeliver(): boolean;
     deliver(message: CustomMessage, waitForPersistence: () => Promise<void>): Promise<void>;
     warn(event: string, message: string): void;
 }
 /**
- * Sole owner of delivery policy: pausing, failure tracking, the in-flight completion and wait
- * receipts. The runtime only answers per-record questions through TaskDeliveryLedger.
+ * Sole owner of "has this completion reached the model": the pending queue, claims, the in-flight
+ * completion, failures, pauses, wait receipts and observation holds. An undelivered completion is
+ * a retention lease on its task, so the runtime keeps the record and its output exactly as long
+ * as delivery needs them, and a bare runtime carries no delivery concept at all.
  */
 export declare class TaskDelivery {
     private readonly options;
@@ -17,14 +21,45 @@ export declare class TaskDelivery {
     private pauses;
     private timer?;
     private delivery?;
+    /** Settlement order. */
+    private readonly completions;
+    /** Task IDs under an observation hold or wait receipt, with the number of holders. */
+    private readonly holds;
     private readonly failures;
     private readonly waits;
+    private readonly listeners;
     constructor(options: TaskDeliveryOptions);
     private get service();
     private warn;
+    /** Called whenever what `hasDeliverableWork()` reads may have changed. */
+    subscribe(listener: () => void): () => void;
+    private changed;
+    /**
+     * Whether a completion is in flight or will be delivered without further input: queued on the
+     * current runtime, visible on the branch and not failed. A failed delivery only retries on the
+     * next input, so it does not count. Held completions count: releasing the hold, or the
+     * acknowledgement that replaces it, always follows.
+     */
+    hasDeliverableWork(): boolean;
     /** Nestable across asynchronous preflight and service replacement. */
     pause(): () => void;
     retry(): void;
+    /** A handed-off task settled on `service`; it awaits automatic delivery under a retention lease. */
+    enqueue(service: TaskDeliveryService, taskId: string): void;
+    /** The model has the result (or the host consumed it): stop waiting to deliver and release the lease. */
+    acknowledge(taskId: string): void;
+    /** Release every lease held for a runtime that closed or was replaced, so its output cleanup can run. */
+    discard(service: TaskDeliveryService): void;
+    /**
+     * Keep `taskIds` out of automatic delivery until the release runs. Holds may precede
+     * settlement, and releasing one re-evaluates the queue.
+     */
+    hold(taskIds: readonly string[]): () => void;
+    /**
+     * Completions that would be delivered next, oldest launch first: on the visible branch, not
+     * claimed and not held. Failed deliveries stay listed until the next retry.
+     */
+    pending(): TaskSnapshot[];
     schedule(): void;
     private canDeliver;
     private drain;
@@ -36,10 +71,10 @@ export declare class TaskDelivery {
     /** Acknowledge only successful appends, using identity even when metadata was rewritten. */
     messagePersisted(message: AgentMessage): void;
     /**
-     * A wait observed a settled background task. The runtime still holds it; take over that hold
-     * until the wait's tool result is persisted, then acknowledge it instead of notifying.
+     * A wait observed a settled background task. Its observation hold is still in place; take over
+     * the hold until the wait's tool result is persisted, then acknowledge it instead of notifying.
      */
-    bindWait(service: TaskDeliveryLedger, toolCallId: string, taskId: string): void;
+    bindWait(toolCallId: string, taskId: string): void;
     private acknowledgeWait;
     private releaseWaits;
     dispose(): void;

package/dist/core/tasks/delivery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../../src/core/tasks/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,mBAAmB;IACnC,OAAO,IAAI,kBAAkB,CAAC;IAC9B,UAAU,IAAI,OAAO,CAAC;IACtB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAUD;;;GAGG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,KAAK,CAAC,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuF;gBACjG,OAAO,EAAE,mBAAmB;IAGxC,OAAO,KAAK,OAAO,GAElB;IACD,OAAO,CAAC,IAAI;IAGZ,sEAAsE;IACtE,KAAK,IAAI,MAAM,IAAI;IAWnB,KAAK,IAAI,IAAI;IAKb,QAAQ,IAAI,IAAI;IAWhB,OAAO,CAAC,UAAU;YAMJ,KAAK;IAiDnB,mFAAmF;IACnF,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAK3C,gFAAgF;IAChF,UAAU,IAAI,IAAI;IAQlB,YAAY,IAAI,IAAI;IAIpB,4FAA4F;IAC5F,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAU7C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK/E,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,YAAY;IAKpB,OAAO,IAAI,IAAI;CAOf"}
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../../src/core/tasks/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D,6FAA6F;AAC7F,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;AAE/F,MAAM,WAAW,mBAAmB;IACnC,OAAO,IAAI,mBAAmB,CAAC;IAC/B,UAAU,IAAI,OAAO,CAAC;IACtB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAmBD;;;;;GAKG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,KAAK,CAAC,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,wBAAwB;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0D;IAChF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBACvC,OAAO,EAAE,mBAAmB;IAGxC,OAAO,KAAK,OAAO,GAElB;IACD,OAAO,CAAC,IAAI;IAGZ,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,OAAO,CAAC,OAAO;IAUf;;;;;OAKG;IACH,kBAAkB,IAAI,OAAO;IAY7B,sEAAsE;IACtE,KAAK,IAAI,MAAM,IAAI;IAWnB,KAAK,IAAI,IAAI;IAMb,oGAAoG;IACpG,OAAO,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAO3D,yGAAyG;IACzG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQjC,yGAAyG;IACzG,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAS3C;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,IAAI;IAiB5C;;;OAGG;IACH,OAAO,IAAI,YAAY,EAAE;IASzB,QAAQ,IAAI,IAAI;IAWhB,OAAO,CAAC,UAAU;YAMJ,KAAK;IAiDnB,mFAAmF;IACnF,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAK3C,gFAAgF;IAChF,UAAU,IAAI,IAAI;IAQlB,YAAY,IAAI,IAAI;IAIpB,4FAA4F;IAC5F,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAU7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlD,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,YAAY;IAKpB,OAAO,IAAI,IAAI;CAWf"}

package/dist/core/tasks/delivery.js

@@ -1,14 +1,21 @@
 import { taskCompletionMessage } from "./presentation.js";
 /**
- * Sole owner of delivery policy: pausing, failure tracking, the in-flight completion and wait
- * receipts. The runtime only answers per-record questions through TaskDeliveryLedger.
+ * Sole owner of "has this completion reached the model": the pending queue, claims, the in-flight
+ * completion, failures, pauses, wait receipts and observation holds. An undelivered completion is
+ * a retention lease on its task, so the runtime keeps the record and its output exactly as long
+ * as delivery needs them, and a bare runtime carries no delivery concept at all.
  */
 export class TaskDelivery {
     constructor(options) {
         this.disposed = false;
         this.pauses = 0;
+        /** Settlement order. */
+        this.completions = new Map();
+        /** Task IDs under an observation hold or wait receipt, with the number of holders. */
+        this.holds = new Map();
         this.failures = new Set();
         this.waits = new Map();
+        this.listeners = new Set();
         this.options = options;
     }
     get service() {
@@ -17,6 +24,44 @@ export class TaskDelivery {
     warn(event, message) {
         this.options.warn(event, message);
     }
+    /** Called whenever what `hasDeliverableWork()` reads may have changed. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    changed() {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                // Observers cannot interrupt delivery.
+            }
+        }
+    }
+    /**
+     * Whether a completion is in flight or will be delivered without further input: queued on the
+     * current runtime, visible on the branch and not failed. A failed delivery only retries on the
+     * next input, so it does not count. Held completions count: releasing the hold, or the
+     * acknowledgement that replaces it, always follows.
+     */
+    hasDeliverableWork() {
+        if (this.disposed)
+            return false;
+        const service = this.service;
+        if (service.closed)
+            return false;
+        if (this.delivery)
+            return true;
+        if (!service.enabled || this.completions.size === 0)
+            return false;
+        return service.list().some((task) => {
+            const completion = this.completions.get(task.id);
+            return completion?.service === service && !this.failures.has(task.id);
+        });
+    }
     /** Nestable across asynchronous preflight and service replacement. */
     pause() {
         this.pauses++;
@@ -32,6 +77,71 @@ export class TaskDelivery {
     retry() {
         this.failures.clear();
         this.schedule();
+        this.changed();
+    }
+    /** A handed-off task settled on `service`; it awaits automatic delivery under a retention lease. */
+    enqueue(service, taskId) {
+        if (this.disposed || service.closed || this.completions.has(taskId))
+            return;
+        this.completions.set(taskId, { service, release: service.retain(taskId), claimed: false });
+        this.schedule();
+        this.changed();
+    }
+    /** The model has the result (or the host consumed it): stop waiting to deliver and release the lease. */
+    acknowledge(taskId) {
+        const completion = this.completions.get(taskId);
+        if (!completion)
+            return;
+        this.completions.delete(taskId);
+        completion.release();
+        this.changed();
+    }
+    /** Release every lease held for a runtime that closed or was replaced, so its output cleanup can run. */
+    discard(service) {
+        for (const [id, completion] of [...this.completions]) {
+            if (completion.service !== service)
+                continue;
+            this.completions.delete(id);
+            completion.release();
+        }
+        this.changed();
+    }
+    /**
+     * Keep `taskIds` out of automatic delivery until the release runs. Holds may precede
+     * settlement, and releasing one re-evaluates the queue.
+     */
+    hold(taskIds) {
+        const ids = [...taskIds];
+        for (const id of ids)
+            this.holds.set(id, (this.holds.get(id) ?? 0) + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            for (const id of ids) {
+                const count = (this.holds.get(id) ?? 1) - 1;
+                if (count > 0)
+                    this.holds.set(id, count);
+                else
+                    this.holds.delete(id);
+            }
+            this.schedule();
+            this.changed();
+        };
+    }
+    /**
+     * Completions that would be delivered next, oldest launch first: on the visible branch, not
+     * claimed and not held. Failed deliveries stay listed until the next retry.
+     */
+    pending() {
+        const service = this.service;
+        if (service.closed)
+            return [];
+        return service.list().filter((task) => {
+            const completion = this.completions.get(task.id);
+            return completion?.service === service && !completion.claimed && !this.holds.has(task.id);
+        });
     }
     schedule() {
         if (this.disposed || this.timer || this.delivery)
@@ -55,17 +165,16 @@ export class TaskDelivery {
                 if (!retained.has(id))
                     this.failures.delete(id);
         }
-        const task = service.pendingNotifications().find((task) => !this.failures.has(task.id));
+        const task = this.pending().find((task) => !this.failures.has(task.id));
         if (!task)
             return;
+        const completion = this.completions.get(task.id);
         const message = taskCompletionMessage(task);
-        if (!service.claimNotification(task.id))
-            return;
+        completion.claimed = true;
         // Exactly one completion may be in flight, whether queued for steering or running its
         // own turn; there is no separate claim registry.
         const delivery = {
             id: task.id,
-            service,
             message,
             phase: "pending",
         };
@@ -84,16 +193,16 @@ export class TaskDelivery {
         }
         finally {
             if (delivery.phase !== "persisted") {
-                service.releaseNotification(task.id);
+                completion.claimed = false;
                 if (service === this.service)
                     this.failures.add(task.id);
                 const reason = deliveryError instanceof Error ? `: ${deliveryError.message}` : "";
                 this.warn("task_delivery", `Background completion delivery failed for ${task.id}${reason}; it will retry on the next input.`);
             }
             this.delivery = undefined;
-            const current = this.service;
-            if (this.canDeliver(current) && current.pendingNotifications().some((task) => !this.failures.has(task.id)))
+            if (this.canDeliver(this.service) && this.pending().some((task) => !this.failures.has(task.id)))
                 this.schedule();
+            this.changed();
         }
     }
     /** Record dequeueing before message hooks can fail or rewrite the notification. */
@@ -118,26 +227,26 @@ export class TaskDelivery {
         const delivery = this.delivery;
         if (delivery?.message === message && delivery.phase !== "persisted") {
             delivery.phase = "persisted";
-            delivery.service.markDelivered(delivery.id);
+            this.acknowledge(delivery.id);
             delivery.queued?.resolve();
         }
         if (message.role === "toolResult")
             this.acknowledgeWait(message.toolCallId);
     }
     /**
-     * A wait observed a settled background task. The runtime still holds it; take over that hold
-     * until the wait's tool result is persisted, then acknowledge it instead of notifying.
+     * A wait observed a settled background task. Its observation hold is still in place; take over
+     * the hold until the wait's tool result is persisted, then acknowledge it instead of notifying.
      */
-    bindWait(service, toolCallId, taskId) {
+    bindWait(toolCallId, taskId) {
         this.waits.get(toolCallId)?.release();
-        this.waits.set(toolCallId, { service, taskId, release: service.holdDelivery(taskId) });
+        this.waits.set(toolCallId, { taskId, release: this.hold([taskId]) });
     }
     acknowledgeWait(toolCallId) {
         const receipt = this.waits.get(toolCallId);
         if (!receipt)
             return;
         this.waits.delete(toolCallId);
-        receipt.service.markDelivered(receipt.taskId);
+        this.acknowledge(receipt.taskId);
         receipt.release();
     }
     releaseWaits() {
@@ -148,10 +257,15 @@ export class TaskDelivery {
     dispose() {
         this.disposed = true;
         this.releaseWaits();
+        for (const completion of this.completions.values())
+            completion.release();
+        this.completions.clear();
         this.delivery?.queued?.reject(new Error("the session was disposed"));
         if (this.timer)
             clearTimeout(this.timer);
         this.timer = undefined;
+        this.changed();
+        this.listeners.clear();
     }
 }
 //# sourceMappingURL=delivery.js.map

package/dist/core/tasks/delivery.js.map

@@ -1 +1 @@
-{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../../../src/core/tasks/delivery.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentMessage } from \"@earendil-works/pi-agent-core\";\nimport type { CustomMessage } from \"../messages.ts\";\nimport { taskCompletionMessage } from \"./presentation.ts\";\nimport type { TaskDeliveryLedger } from \"./types.ts\";\n\nexport interface TaskDeliveryOptions {\n\tservice(): TaskDeliveryLedger;\n\tcanDeliver(): boolean;\n\tdeliver(message: CustomMessage, waitForPersistence: () => Promise<void>): Promise<void>;\n\twarn(event: string, message: string): void;\n}\ninterface Delivery {\n\tid: string;\n\tservice: TaskDeliveryLedger;\n\t/** Agent-core preserves message identity; extension rewrites mutate it in place. */\n\tmessage: CustomMessage;\n\tphase: \"pending\" | \"started\" | \"persisted\";\n\tqueued?: { resolve(): void; reject(reason: Error): void };\n}\n\n/**\n * Sole owner of delivery policy: pausing, failure tracking, the in-flight completion and wait\n * receipts. The runtime only answers per-record questions through TaskDeliveryLedger.\n */\nexport class TaskDelivery {\n\tprivate readonly options: TaskDeliveryOptions;\n\tprivate disposed = false;\n\tprivate pauses = 0;\n\tprivate timer?: ReturnType<typeof setTimeout>;\n\tprivate delivery?: Delivery;\n\tprivate readonly failures = new Set<string>();\n\tprivate readonly waits = new Map<string, { service: TaskDeliveryLedger; taskId: string; release(): void }>();\n\tconstructor(options: TaskDeliveryOptions) {\n\t\tthis.options = options;\n\t}\n\tprivate get service(): TaskDeliveryLedger {\n\t\treturn this.options.service();\n\t}\n\tprivate warn(event: string, message: string): void {\n\t\tthis.options.warn(event, message);\n\t}\n\t/** Nestable across asynchronous preflight and service replacement. */\n\tpause(): () => void {\n\t\tthis.pauses++;\n\t\tlet released = false;\n\t\treturn () => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tthis.pauses--;\n\t\t\tthis.schedule();\n\t\t};\n\t}\n\n\tretry(): void {\n\t\tthis.failures.clear();\n\t\tthis.schedule();\n\t}\n\n\tschedule(): void {\n\t\tif (this.disposed || this.timer || this.delivery) return;\n\t\tthis.timer = setTimeout(() => {\n\t\t\tthis.timer = undefined;\n\t\t\tvoid this.drain().catch(() =>\n\t\t\t\tthis.warn(\"task_delivery\", \"Background notification drain failed; delivery was not confirmed.\"),\n\t\t\t);\n\t\t}, 0);\n\t\tthis.timer.unref?.();\n\t}\n\n\tprivate canDeliver(service: TaskDeliveryLedger): boolean {\n\t\treturn (\n\t\t\t!this.disposed && service === this.service && service.enabled && this.pauses === 0 && this.options.canDeliver()\n\t\t);\n\t}\n\n\tprivate async drain(): Promise<void> {\n\t\tconst service = this.service;\n\t\tif (this.delivery || !this.canDeliver(service)) return;\n\t\tif (this.failures.size) {\n\t\t\tconst retained = new Set(service.list().map((task) => task.id));\n\t\t\tfor (const id of this.failures) if (!retained.has(id)) this.failures.delete(id);\n\t\t}\n\t\tconst task = service.pendingNotifications().find((task) => !this.failures.has(task.id));\n\t\tif (!task) return;\n\t\tconst message = taskCompletionMessage(task);\n\t\tif (!service.claimNotification(task.id)) return;\n\t\t// Exactly one completion may be in flight, whether queued for steering or running its\n\t\t// own turn; there is no separate claim registry.\n\t\tconst delivery: Delivery = {\n\t\t\tid: task.id,\n\t\t\tservice,\n\t\t\tmessage,\n\t\t\tphase: \"pending\",\n\t\t};\n\t\tthis.delivery = delivery;\n\t\tlet deliveryError: unknown;\n\t\ttry {\n\t\t\tawait this.options.deliver(\n\t\t\t\tdelivery.message,\n\t\t\t\t() =>\n\t\t\t\t\tnew Promise<void>((resolve, reject) => {\n\t\t\t\t\t\tif (delivery.phase === \"persisted\") resolve();\n\t\t\t\t\t\telse delivery.queued = { resolve, reject };\n\t\t\t\t\t}),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tdeliveryError = error;\n\t\t} finally {\n\t\t\tif (delivery.phase !== \"persisted\") {\n\t\t\t\tservice.releaseNotification(task.id);\n\t\t\t\tif (service === this.service) this.failures.add(task.id);\n\t\t\t\tconst reason = deliveryError instanceof Error ? `: ${deliveryError.message}` : \"\";\n\t\t\t\tthis.warn(\n\t\t\t\t\t\"task_delivery\",\n\t\t\t\t\t`Background completion delivery failed for ${task.id}${reason}; it will retry on the next input.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tthis.delivery = undefined;\n\t\t\tconst current = this.service;\n\t\t\tif (this.canDeliver(current) && current.pendingNotifications().some((task) => !this.failures.has(task.id)))\n\t\t\t\tthis.schedule();\n\t\t}\n\t}\n\n\t/** Record dequeueing before message hooks can fail or rewrite the notification. */\n\tmessageStarted(message: AgentMessage): void {\n\t\tconst delivery = this.delivery;\n\t\tif (delivery?.message === message && delivery.phase === \"pending\") delivery.phase = \"started\";\n\t}\n\n\t/** A queued message that was never emitted remains claimed for the next run. */\n\tagentEnded(): void {\n\t\tthis.releaseWaits();\n\t\tconst delivery = this.delivery;\n\t\tif (delivery?.phase === \"started\") {\n\t\t\tdelivery.queued?.reject(new Error(\"the completion message was not persisted\"));\n\t\t}\n\t}\n\n\tqueueCleared(): void {\n\t\tthis.delivery?.queued?.reject(new Error(\"the completion message was dequeued before delivery\"));\n\t}\n\n\t/** Acknowledge only successful appends, using identity even when metadata was rewritten. */\n\tmessagePersisted(message: AgentMessage): void {\n\t\tconst delivery = this.delivery;\n\t\tif (delivery?.message === message && delivery.phase !== \"persisted\") {\n\t\t\tdelivery.phase = \"persisted\";\n\t\t\tdelivery.service.markDelivered(delivery.id);\n\t\t\tdelivery.queued?.resolve();\n\t\t}\n\t\tif (message.role === \"toolResult\") this.acknowledgeWait(message.toolCallId);\n\t}\n\n\t/**\n\t * A wait observed a settled background task. The runtime still holds it; take over that hold\n\t * until the wait's tool result is persisted, then acknowledge it instead of notifying.\n\t */\n\tbindWait(service: TaskDeliveryLedger, toolCallId: string, taskId: string): void {\n\t\tthis.waits.get(toolCallId)?.release();\n\t\tthis.waits.set(toolCallId, { service, taskId, release: service.holdDelivery(taskId) });\n\t}\n\n\tprivate acknowledgeWait(toolCallId: string): void {\n\t\tconst receipt = this.waits.get(toolCallId);\n\t\tif (!receipt) return;\n\t\tthis.waits.delete(toolCallId);\n\t\treceipt.service.markDelivered(receipt.taskId);\n\t\treceipt.release();\n\t}\n\n\tprivate releaseWaits(): void {\n\t\tfor (const receipt of this.waits.values()) receipt.release();\n\t\tthis.waits.clear();\n\t}\n\n\tdispose(): void {\n\t\tthis.disposed = true;\n\t\tthis.releaseWaits();\n\t\tthis.delivery?.queued?.reject(new Error(\"the session was disposed\"));\n\t\tif (this.timer) clearTimeout(this.timer);\n\t\tthis.timer = undefined;\n\t}\n}\n"]}
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../../../src/core/tasks/delivery.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentMessage } from \"@earendil-works/pi-agent-core\";\nimport type { CustomMessage } from \"../messages.ts\";\nimport { taskCompletionMessage } from \"./presentation.ts\";\nimport type { TaskSnapshot, TasksContext } from \"./types.ts\";\n\n/** All the delivery policy needs from a runtime: its public, session-independent surface. */\nexport type TaskDeliveryService = Pick<TasksContext, \"enabled\" | \"closed\" | \"list\" | \"retain\">;\n\nexport interface TaskDeliveryOptions {\n\tservice(): TaskDeliveryService;\n\tcanDeliver(): boolean;\n\tdeliver(message: CustomMessage, waitForPersistence: () => Promise<void>): Promise<void>;\n\twarn(event: string, message: string): void;\n}\n\n/** A settled handoff the model has not yet seen, kept retained by a lease until it has. */\ninterface Completion {\n\tservice: TaskDeliveryService;\n\t/** The retention lease: the record and its output stay available until delivery or acknowledgement. */\n\trelease(): void;\n\t/** Handed to the host and awaiting persistence. */\n\tclaimed: boolean;\n}\n\ninterface Delivery {\n\tid: string;\n\t/** Agent-core preserves message identity; extension rewrites mutate it in place. */\n\tmessage: CustomMessage;\n\tphase: \"pending\" | \"started\" | \"persisted\";\n\tqueued?: { resolve(): void; reject(reason: Error): void };\n}\n\n/**\n * Sole owner of \"has this completion reached the model\": the pending queue, claims, the in-flight\n * completion, failures, pauses, wait receipts and observation holds. An undelivered completion is\n * a retention lease on its task, so the runtime keeps the record and its output exactly as long\n * as delivery needs them, and a bare runtime carries no delivery concept at all.\n */\nexport class TaskDelivery {\n\tprivate readonly options: TaskDeliveryOptions;\n\tprivate disposed = false;\n\tprivate pauses = 0;\n\tprivate timer?: ReturnType<typeof setTimeout>;\n\tprivate delivery?: Delivery;\n\t/** Settlement order. */\n\tprivate readonly completions = new Map<string, Completion>();\n\t/** Task IDs under an observation hold or wait receipt, with the number of holders. */\n\tprivate readonly holds = new Map<string, number>();\n\tprivate readonly failures = new Set<string>();\n\tprivate readonly waits = new Map<string, { taskId: string; release(): void }>();\n\tprivate readonly listeners = new Set<() => void>();\n\tconstructor(options: TaskDeliveryOptions) {\n\t\tthis.options = options;\n\t}\n\tprivate get service(): TaskDeliveryService {\n\t\treturn this.options.service();\n\t}\n\tprivate warn(event: string, message: string): void {\n\t\tthis.options.warn(event, message);\n\t}\n\t/** Called whenever what `hasDeliverableWork()` reads may have changed. */\n\tsubscribe(listener: () => void): () => void {\n\t\tthis.listeners.add(listener);\n\t\treturn () => {\n\t\t\tthis.listeners.delete(listener);\n\t\t};\n\t}\n\n\tprivate changed(): void {\n\t\tfor (const listener of [...this.listeners]) {\n\t\t\ttry {\n\t\t\t\tlistener();\n\t\t\t} catch {\n\t\t\t\t// Observers cannot interrupt delivery.\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Whether a completion is in flight or will be delivered without further input: queued on the\n\t * current runtime, visible on the branch and not failed. A failed delivery only retries on the\n\t * next input, so it does not count. Held completions count: releasing the hold, or the\n\t * acknowledgement that replaces it, always follows.\n\t */\n\thasDeliverableWork(): boolean {\n\t\tif (this.disposed) return false;\n\t\tconst service = this.service;\n\t\tif (service.closed) return false;\n\t\tif (this.delivery) return true;\n\t\tif (!service.enabled || this.completions.size === 0) return false;\n\t\treturn service.list().some((task) => {\n\t\t\tconst completion = this.completions.get(task.id);\n\t\t\treturn completion?.service === service && !this.failures.has(task.id);\n\t\t});\n\t}\n\n\t/** Nestable across asynchronous preflight and service replacement. */\n\tpause(): () => void {\n\t\tthis.pauses++;\n\t\tlet released = false;\n\t\treturn () => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tthis.pauses--;\n\t\t\tthis.schedule();\n\t\t};\n\t}\n\n\tretry(): void {\n\t\tthis.failures.clear();\n\t\tthis.schedule();\n\t\tthis.changed();\n\t}\n\n\t/** A handed-off task settled on `service`; it awaits automatic delivery under a retention lease. */\n\tenqueue(service: TaskDeliveryService, taskId: string): void {\n\t\tif (this.disposed || service.closed || this.completions.has(taskId)) return;\n\t\tthis.completions.set(taskId, { service, release: service.retain(taskId), claimed: false });\n\t\tthis.schedule();\n\t\tthis.changed();\n\t}\n\n\t/** The model has the result (or the host consumed it): stop waiting to deliver and release the lease. */\n\tacknowledge(taskId: string): void {\n\t\tconst completion = this.completions.get(taskId);\n\t\tif (!completion) return;\n\t\tthis.completions.delete(taskId);\n\t\tcompletion.release();\n\t\tthis.changed();\n\t}\n\n\t/** Release every lease held for a runtime that closed or was replaced, so its output cleanup can run. */\n\tdiscard(service: TaskDeliveryService): void {\n\t\tfor (const [id, completion] of [...this.completions]) {\n\t\t\tif (completion.service !== service) continue;\n\t\t\tthis.completions.delete(id);\n\t\t\tcompletion.release();\n\t\t}\n\t\tthis.changed();\n\t}\n\n\t/**\n\t * Keep `taskIds` out of automatic delivery until the release runs. Holds may precede\n\t * settlement, and releasing one re-evaluates the queue.\n\t */\n\thold(taskIds: readonly string[]): () => void {\n\t\tconst ids = [...taskIds];\n\t\tfor (const id of ids) this.holds.set(id, (this.holds.get(id) ?? 0) + 1);\n\t\tlet released = false;\n\t\treturn () => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tfor (const id of ids) {\n\t\t\t\tconst count = (this.holds.get(id) ?? 1) - 1;\n\t\t\t\tif (count > 0) this.holds.set(id, count);\n\t\t\t\telse this.holds.delete(id);\n\t\t\t}\n\t\t\tthis.schedule();\n\t\t\tthis.changed();\n\t\t};\n\t}\n\n\t/**\n\t * Completions that would be delivered next, oldest launch first: on the visible branch, not\n\t * claimed and not held. Failed deliveries stay listed until the next retry.\n\t */\n\tpending(): TaskSnapshot[] {\n\t\tconst service = this.service;\n\t\tif (service.closed) return [];\n\t\treturn service.list().filter((task) => {\n\t\t\tconst completion = this.completions.get(task.id);\n\t\t\treturn completion?.service === service && !completion.claimed && !this.holds.has(task.id);\n\t\t});\n\t}\n\n\tschedule(): void {\n\t\tif (this.disposed || this.timer || this.delivery) return;\n\t\tthis.timer = setTimeout(() => {\n\t\t\tthis.timer = undefined;\n\t\t\tvoid this.drain().catch(() =>\n\t\t\t\tthis.warn(\"task_delivery\", \"Background notification drain failed; delivery was not confirmed.\"),\n\t\t\t);\n\t\t}, 0);\n\t\tthis.timer.unref?.();\n\t}\n\n\tprivate canDeliver(service: TaskDeliveryService): boolean {\n\t\treturn (\n\t\t\t!this.disposed && service === this.service && service.enabled && this.pauses === 0 && this.options.canDeliver()\n\t\t);\n\t}\n\n\tprivate async drain(): Promise<void> {\n\t\tconst service = this.service;\n\t\tif (this.delivery || !this.canDeliver(service)) return;\n\t\tif (this.failures.size) {\n\t\t\tconst retained = new Set(service.list().map((task) => task.id));\n\t\t\tfor (const id of this.failures) if (!retained.has(id)) this.failures.delete(id);\n\t\t}\n\t\tconst task = this.pending().find((task) => !this.failures.has(task.id));\n\t\tif (!task) return;\n\t\tconst completion = this.completions.get(task.id)!;\n\t\tconst message = taskCompletionMessage(task);\n\t\tcompletion.claimed = true;\n\t\t// Exactly one completion may be in flight, whether queued for steering or running its\n\t\t// own turn; there is no separate claim registry.\n\t\tconst delivery: Delivery = {\n\t\t\tid: task.id,\n\t\t\tmessage,\n\t\t\tphase: \"pending\",\n\t\t};\n\t\tthis.delivery = delivery;\n\t\tlet deliveryError: unknown;\n\t\ttry {\n\t\t\tawait this.options.deliver(\n\t\t\t\tdelivery.message,\n\t\t\t\t() =>\n\t\t\t\t\tnew Promise<void>((resolve, reject) => {\n\t\t\t\t\t\tif (delivery.phase === \"persisted\") resolve();\n\t\t\t\t\t\telse delivery.queued = { resolve, reject };\n\t\t\t\t\t}),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tdeliveryError = error;\n\t\t} finally {\n\t\t\tif (delivery.phase !== \"persisted\") {\n\t\t\t\tcompletion.claimed = false;\n\t\t\t\tif (service === this.service) this.failures.add(task.id);\n\t\t\t\tconst reason = deliveryError instanceof Error ? `: ${deliveryError.message}` : \"\";\n\t\t\t\tthis.warn(\n\t\t\t\t\t\"task_delivery\",\n\t\t\t\t\t`Background completion delivery failed for ${task.id}${reason}; it will retry on the next input.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tthis.delivery = undefined;\n\t\t\tif (this.canDeliver(this.service) && this.pending().some((task) => !this.failures.has(task.id)))\n\t\t\t\tthis.schedule();\n\t\t\tthis.changed();\n\t\t}\n\t}\n\n\t/** Record dequeueing before message hooks can fail or rewrite the notification. */\n\tmessageStarted(message: AgentMessage): void {\n\t\tconst delivery = this.delivery;\n\t\tif (delivery?.message === message && delivery.phase === \"pending\") delivery.phase = \"started\";\n\t}\n\n\t/** A queued message that was never emitted remains claimed for the next run. */\n\tagentEnded(): void {\n\t\tthis.releaseWaits();\n\t\tconst delivery = this.delivery;\n\t\tif (delivery?.phase === \"started\") {\n\t\t\tdelivery.queued?.reject(new Error(\"the completion message was not persisted\"));\n\t\t}\n\t}\n\n\tqueueCleared(): void {\n\t\tthis.delivery?.queued?.reject(new Error(\"the completion message was dequeued before delivery\"));\n\t}\n\n\t/** Acknowledge only successful appends, using identity even when metadata was rewritten. */\n\tmessagePersisted(message: AgentMessage): void {\n\t\tconst delivery = this.delivery;\n\t\tif (delivery?.message === message && delivery.phase !== \"persisted\") {\n\t\t\tdelivery.phase = \"persisted\";\n\t\t\tthis.acknowledge(delivery.id);\n\t\t\tdelivery.queued?.resolve();\n\t\t}\n\t\tif (message.role === \"toolResult\") this.acknowledgeWait(message.toolCallId);\n\t}\n\n\t/**\n\t * A wait observed a settled background task. Its observation hold is still in place; take over\n\t * the hold until the wait's tool result is persisted, then acknowledge it instead of notifying.\n\t */\n\tbindWait(toolCallId: string, taskId: string): void {\n\t\tthis.waits.get(toolCallId)?.release();\n\t\tthis.waits.set(toolCallId, { taskId, release: this.hold([taskId]) });\n\t}\n\n\tprivate acknowledgeWait(toolCallId: string): void {\n\t\tconst receipt = this.waits.get(toolCallId);\n\t\tif (!receipt) return;\n\t\tthis.waits.delete(toolCallId);\n\t\tthis.acknowledge(receipt.taskId);\n\t\treceipt.release();\n\t}\n\n\tprivate releaseWaits(): void {\n\t\tfor (const receipt of this.waits.values()) receipt.release();\n\t\tthis.waits.clear();\n\t}\n\n\tdispose(): void {\n\t\tthis.disposed = true;\n\t\tthis.releaseWaits();\n\t\tfor (const completion of this.completions.values()) completion.release();\n\t\tthis.completions.clear();\n\t\tthis.delivery?.queued?.reject(new Error(\"the session was disposed\"));\n\t\tif (this.timer) clearTimeout(this.timer);\n\t\tthis.timer = undefined;\n\t\tthis.changed();\n\t\tthis.listeners.clear();\n\t}\n}\n"]}

package/dist/core/tasks/execution.d.ts

@@ -14,10 +14,13 @@ export interface ExecutionHost {
  * One live task: its caller, controller, parent link and executor callbacks.
  *
  * A caller may be handed off to the background whenever no executor preflight is in
- * progress: before `run` starts (queued) or after the executor calls `accept()`.
+ * progress: before `run` starts (queued) or after the executor calls `accept()`. A release
+ * requested during preflight waits for `accept()`; if the run settles first, the caller is
+ * answered inline and the task never becomes background.
  */
 export declare class Execution<T> {
     readonly record: TaskRecord;
+    readonly kind: string;
     readonly concurrency?: {
         key: string;
         limit: number;
@@ -31,39 +34,49 @@ export declare class Execution<T> {
     private readonly modeListeners;
     private resolveCaller;
     private rejectCaller;
-    private resolveDone;
     private onUpdate?;
     private releaseParentSignal;
     private usage?;
-    private started;
-    private accepted;
-    private handedOff;
-    private detachRequested;
+    private phase;
+    private placement;
+    private readonly reason;
     /** The executor's `run` promise once started. */
     private running?;
     constructor(host: ExecutionHost, record: TaskRecord, execution: TaskExecution<T>);
     get task(): Readonly<TaskSnapshot>;
     get aborted(): boolean;
-    /** Executor preflight never races a handoff; queued work has not begun any. */
-    private get handoffAllowed();
     /** Waiting for a concurrency slot: registered, but `run` has not started. */
     get queued(): boolean;
+    /** Holds a background slot: handed off, or asked to be and waiting for the executor to accept. */
+    get holdsBackgroundSlot(): boolean;
     get detachable(): boolean;
     /** Stop forwarding to the launching tool call: parent cancellation and progress no longer reach it. */
     releaseParent(): void;
     start(): void;
-    handoff(): void;
-    requestDetach(): void;
-    completeDetach(): void;
+    /** Queued background work returns at once; started work is released at its own `accept()`. */
+    handOffIfQueued(): void;
+    /**
+     * Ask to move the caller to the background. The placement changes now; the returned
+     * notification is for the caller of a batch to run after every placement has changed, so no
+     * listener ever observes a half-moved set.
+     */
+    detach(): () => void;
     cancel(): boolean;
     private onModeChange;
     private accept;
     /**
-     * Hand off unless `run` has already settled. A reaction on an already settled promise is
-     * queued at once, ahead of the pending-check below whatever the promise's chain depth, so
-     * the outcome never depends on how `start()` chains its own handlers.
+     * Hand off unless `run` has already settled. This observes the `run` promise's own settlement,
+     * not the phase `finish()` sets: a reaction on an already settled promise is queued at once,
+     * ahead of the pending-check below whatever the promise's chain depth, so the outcome never
+     * depends on how many hops `start()` chains before `finish()`.
      */
     private handoffIfRunning;
+    /**
+     * Release the caller with a background outcome if it asked to leave and the executor's
+     * preflight is over. The task is background exactly from here on.
+     */
+    private handoff;
+    private announceBackground;
     private publish;
     private attachOutput;
     private finish;

package/dist/core/tasks/execution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../../src/core/tasks/execution.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAU1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEX,WAAW,EACX,aAAa,EAGb,YAAY,EAGZ,eAAe,EAEf,MAAM,YAAY,CAAC;AAEpB,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,IAAI,IAAI,CAAC;IACb,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC;IAC3D,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAeD;;;;;GAKG;AACH,qBAAa,SAAS,CAAC,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0B;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuC;IACrE,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAuC;IACxD,OAAO,CAAC,mBAAmB,CAAwB;IACnD,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAU;IACjC,iDAAiD;IACjD,OAAO,CAAC,OAAO,CAAC,CAA6B;gBAEjC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IAuChF,IAAI,IAAI,IAAI,QAAQ,CAAC,YAAY,CAAC,CAEjC;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,+EAA+E;IAC/E,OAAO,KAAK,cAAc,GAEzB;IAED,6EAA6E;IAC7E,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,uGAAuG;IACvG,aAAa,IAAI,IAAI;IAMrB,KAAK,IAAI,IAAI;IAsBb,OAAO,IAAI,IAAI;IAoBf,aAAa,IAAI,IAAI;IAQrB,cAAc,IAAI,IAAI;IAWtB,MAAM,IAAI,OAAO;IAWjB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,MAAM;IAUd;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,OAAO;IAiBf,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,MAAM;CAoDd"}
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../../src/core/tasks/execution.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAU1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEX,WAAW,EACX,aAAa,EAGb,YAAY,EAGZ,eAAe,EAEf,MAAM,YAAY,CAAC;AAEpB,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,IAAI,IAAI,CAAC;IACb,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC;IAC3D,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAyBD;;;;;;;GAOG;AACH,qBAAa,SAAS,CAAC,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0B;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuC;IACrE,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,QAAQ,CAAC,CAAuC;IACxD,OAAO,CAAC,mBAAmB,CAAwB;IACnD,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,iDAAiD;IACjD,OAAO,CAAC,OAAO,CAAC,CAA6B;gBAEjC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IAwChF,IAAI,IAAI,IAAI,QAAQ,CAAC,YAAY,CAAC,CAEjC;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,6EAA6E;IAC7E,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,kGAAkG;IAClG,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,uGAAuG;IACvG,aAAa,IAAI,IAAI;IAMrB,KAAK,IAAI,IAAI;IAsBb,8FAA8F;IAC9F,eAAe,IAAI,IAAI;IAIvB;;;;OAIG;IACH,MAAM,IAAI,MAAM,IAAI;IAQpB,MAAM,IAAI,OAAO;IAWjB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,MAAM;IAUd;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,OAAO;IAiBf,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,MAAM;CAmDd"}