@plurnk/plurnk-agui 3.0.0 → 4.0.0

package/dist/Portal.js

@@ -4,25 +4,29 @@
 // the seam, and route standard resume entries to resolveProposal. Transport-agnostic —
 // the HTTP/SSE listener (the outward edge) and workspace establishment (workspace-lifecycle
 // hook, pending) wrap this; the engine is testable against a mock seam today.
-var _a;
 import EventRouter from "./EventRouter.js";
-import { aliveChildren, descendantsState, stateDelta } from "./AguiPlus.js";
-import { selectWorkerLoop } from "@plurnk/plurnk-contracts";
+import { aliveChildren, spendState, stateDelta } from "./AguiPlus.js";
+import { Problems, Validator, selectWorkerLoop } from "@plurnk/plurnk-contracts";
+import { HttpProblemError } from "./action-results.js";
+import { runErrorEvents, serviceStoppingProblem } from "./run-events.js";
+import Translator, {} from "./Translator.js";
 import ProposalHitl, {} from "./ProposalHitl.js";
 import { EventType } from "./types.js";
-class Portal {
+export default class Portal {
     #seam;
     // A workspace may have several simultaneous AG-UI Runs. The worker/loop carried by
     // each notification selects its owner; a Run is not a second broadcast subscription.
     #threads = new Map();
     #hitl;
-    #activeInterrupts = new Map();
     #continuations = new Map();
     #deliveryTails = new Map();
+    // {§agui-subagents} The loops whose terminal the daemon has published and the Runs have yet to receive, in order.
+    #terminalsDue = new Set();
     #off = null;
+    #stopped = false;
     constructor(seam) {
         this.#seam = seam;
-        this.#hitl = new ProposalHitl(seam, (workspaceId, delivery) => this.#routeHitl(workspaceId, delivery));
+        this.#hitl = new ProposalHitl(seam, (workspaceId, delivery) => this.#enqueueDelivery(workspaceId, async () => this.#routeHitl(workspaceId, await delivery)));
     }
     // One subscription for the whole module: render each event only to its owning Run.
     start() {
@@ -30,25 +34,44 @@ class Portal {
         this.#off = this.#seam.subscribeToEvents((workspaceId, method, params) => {
             if (workspaceId === null)
                 return; // global (workspace/created) handled out-of-band
-            // {§agui-proposal-resolve} A descendant gate may require asynchronous
-            // topology lookup. A later terminal cannot close its controlling Run first.
-            if (method === "loop/terminated" && this.#deliveryTails.has(workspaceId)) {
+            if (method === "loop/terminated")
+                this.#terminalsDue.add(params.loopId);
+            // {§agui-proposal-resolve} {§agui-subagents} A workspace's events reach its Runs in the order the daemon
+            // published them: while a descendant's topology or loop is being read, every later event waits for it.
+            if (this.#deliveryTails.has(workspaceId)) {
                 this.#enqueueDelivery(workspaceId, async () => this.#routeNotification(workspaceId, method, params));
                 return;
             }
-            this.#routeNotification(workspaceId, method, params);
+            const observing = this.#routeNotification(workspaceId, method, params);
+            if (observing !== undefined)
+                this.#enqueueDelivery(workspaceId, async () => observing);
         });
     }
+    // Returns the descendants' events still being read for some Run's presentation, when there are any.
     #routeNotification(workspaceId, method, params) {
+        if (method === "loop/terminated")
+            this.#terminalsDue.delete(params.loopId);
+        const observing = [];
         for (const thread of this.#threads.get(workspaceId) ?? []) {
-            if (_a.#touchesChildren(thread, method, params))
-                void this.#refreshChildren(workspaceId, thread);
-            if (thread.descendants && _a.#observedActor(thread, method, params) !== null) {
-                this.#observeDescendant(workspaceId, thread, method, params);
+            if (Portal.#touchesStatus(thread, method, params))
+                void this.#refreshStatus(thread);
+            const actor = thread.descendants ? Portal.#observedActor(thread, method, params) : null;
+            if (actor !== null) {
+                observing.push(this.#observeDescendant(workspaceId, thread, actor, method, params));
                 continue;
             }
-            if (!_a.#ownsNotification(thread, method, params))
+            if (thread.descendants && method === "loop/terminated") {
+                const concluded = Portal.#concluded(thread, params);
+                if (concluded !== null) {
+                    if (concluded.length > 0)
+                        thread.emit(concluded);
+                    continue;
+                }
+            }
+            if (!Portal.#ownsNotification(thread, method, params)) {
+                Portal.#holdUnannounced(thread, method, params);
                 continue;
+            }
             if (method === "loop/packet" && thread.loopId === null) {
                 const loopId = params.loopId;
                 if (typeof loopId === "number")
@@ -67,40 +90,43 @@ class Portal {
             }
             // {§agui-broadcast-fan} — the row that announces an execution owns its stream for this Run
             // before any channel write: a stream/event is a race the action result must not win.
-            const opened = _a.#openedStream(method, params);
+            const opened = Portal.#openedStream(method, params);
             if (opened !== null)
                 thread.openStreams.add(opened);
             if (method === "stream/concluded")
-                thread.openStreams.delete(_a.#streamTarget(params));
-            const out = thread.router.route(method, params);
+                thread.openStreams.delete(Portal.#streamTarget(params));
+            const out = Portal.#finishing(thread, thread.router.route(method, params));
             if (out.length > 0)
                 thread.emit(out);
+            if (method === "log/entry" && opened !== null)
+                this.#releaseUnannounced(thread, opened);
             // {§agui-gate-deferral} — a terminal leaves the held gate durable for the next Run; any other
             // event that closed the reasoning lifecycle presents it now.
             if (method === "loop/terminated")
                 thread.deferredDelivery = null;
             else
                 this.#presentDeferred(workspaceId, thread);
-            if (method === "stream/concluded" && thread.openStreams.size === 0 && thread.deferredFinish !== null) {
+            if (thread.openStreams.size === 0 && thread.deferredFinish !== null) {
                 const deferred = thread.deferredFinish;
                 thread.deferredFinish = null;
-                this.#finishThread(thread, deferred);
+                this.#finishThread(thread, deferred.events, deferred.result);
             }
         }
+        return observing.length === 0 ? undefined : Promise.all(observing).then(() => undefined);
     }
-    // {§agui-status-children} {§agui-status-descendants} — the events after which the bound Worker's
-    // alive direct children or its descendants' spend may differ: another worker's loop concluded or
-    // began (it may be a child), another worker's turn settled its spend, or the bound Worker's own
+    // {§agui-status-children} {§agui-status-spend} — the events after which the bound Worker's alive
+    // direct children or its spend may differ: another worker's loop concluded or began (it may be a
+    // child), a turn settled its spend (its own or another worker's), or the bound Worker's own
     // WORK/FORK/KILL row landed (it spawned or killed one). The daemon is asked, never inferred.
-    static #touchesChildren(thread, method, params) {
-        if (thread.notificationScope !== "conversation")
+    static #touchesStatus(thread, method, params) {
+        if (thread.notificationScope !== "worker")
             return false;
         const payload = params;
         if (method === "loop/terminated" || method === "loop/packet") {
             return typeof payload.workerId === "number" && payload.workerId !== thread.workerId;
         }
         if (method === "notice/event") {
-            return typeof payload.workerId === "number" && payload.workerId !== thread.workerId
+            return typeof payload.workerId === "number"
                 && payload.notice?.source === "engine:turn" && payload.notice.kind === "turn_generated";
         }
         if (method === "log/entry") {
@@ -109,27 +135,46 @@ class Portal {
         }
         return false;
     }
-    async #refreshChildren(workspaceId, thread) {
+    // Publish only what differs from the gauge this Run's client holds, and nothing before its snapshot.
+    async #refreshStatus(thread) {
+        if (thread.gauge === null) {
+            thread.staleGauge = true;
+            return;
+        }
+        const workerId = thread.workerId;
+        if (workerId === null)
+            return;
+        const refresh = ++thread.gaugeRefresh;
         const [rows, accounting] = await Promise.all([
-            this.#seam.listWorkers(workspaceId, { parentWorkerId: thread.workerId }),
-            this.#seam.descendantAccounting({ workspaceId, workerId: thread.workerId, loopId: thread.loopId }),
+            this.#seam.listWorkers(thread.workspaceId, { parentWorkerId: workerId }),
+            this.#seam.workerAccounting({ workspaceId: thread.workspaceId, workerId }),
         ]);
-        if (!(this.#threads.get(workspaceId)?.has(thread) ?? false))
+        if (refresh !== thread.gaugeRefresh || thread.gauge === null)
+            return;
+        if (!(this.#threads.get(thread.workspaceId)?.has(thread) ?? false))
             return;
         const delta = [];
         const children = aliveChildren(rows);
-        if (children !== thread.children) {
-            thread.children = children;
+        if (children !== thread.gauge.children) {
             delta.push({ op: "replace", path: "/plurnk/status/children", value: children });
         }
-        const delegation = descendantsState(accounting);
-        if (thread.delegation === null || JSON.stringify(delegation) !== JSON.stringify(thread.delegation)) {
-            thread.delegation = delegation;
-            delta.push({ op: "replace", path: "/plurnk/status/descendants", value: delegation });
+        const spend = spendState(accounting);
+        if (JSON.stringify(spend) !== JSON.stringify(thread.gauge.spend)) {
+            delta.push({ op: "replace", path: "/plurnk/status/spend", value: spend });
         }
+        thread.gauge = { children, spend };
         if (delta.length > 0)
             thread.emit([stateDelta(delta)]);
     }
+    // The client now holds this status. A refresh asked for before, or racing, its reads runs after it.
+    #presentGauge(thread, status) {
+        const stale = thread.staleGauge || thread.gauge !== null;
+        thread.gauge = { children: status.children, spend: status.spend };
+        thread.staleGauge = false;
+        thread.gaugeRefresh += 1;
+        if (stale)
+            void this.#refreshStatus(thread);
+    }
     // {§agui-delegation-observation} — the actor of a row or stream event that is neither the bound
     // Worker nor a known stranger; null for everything else, so terminals, packets, reasoning and
     // notices stay the bound Worker's alone.
@@ -142,40 +187,167 @@ class Portal {
             return null;
         return actor;
     }
-    // Descendants' events ride the workspace's delivery chain: ordered among themselves, introduced
-    // once each from the daemon's topology, and never touching this Run's step, streams or terminal.
-    #observeDescendant(workspaceId, thread, method, params) {
-        const actor = _a.#observedActor(thread, method, params);
-        if (actor === null)
+    // A descendant's event is introduced once per actor from the daemon's topology, and never touches this Run's step,
+    // streams or terminal. The workspace's later events wait for it ({§agui-subagents}).
+    async #observeDescendant(workspaceId, thread, actor, method, params) {
+        let node = thread.tree?.get(actor);
+        if (node === undefined && thread.workerId !== null) {
+            thread.tree = await this.#descendantTree(workspaceId, thread.workerId);
+            node = thread.tree.get(actor);
+        }
+        if (!(this.#threads.get(workspaceId)?.has(thread) ?? false))
             return;
-        this.#enqueueDelivery(workspaceId, async () => {
-            if (!(this.#threads.get(workspaceId)?.has(thread) ?? false))
-                return;
-            let node = thread.tree?.get(actor);
-            if (node === undefined) {
-                thread.tree = await this.#descendantTree(workspaceId, thread.workerId);
-                node = thread.tree.get(actor);
-            }
-            if (node === undefined) {
-                thread.unrelated.add(actor);
-                return;
-            }
-            if (!thread.introduced.has(actor)) {
-                thread.introduced.add(actor);
-                thread.emit([{ type: EventType.CUSTOM, name: "plurnk.descendant", value: node }]);
+        if (node === undefined) {
+            thread.unrelated.add(actor);
+            return;
+        }
+        const subagent = method === "log/entry" ? await this.#rowSubagent(thread, node, params.entry.loop_id) : null;
+        if (!(this.#threads.get(workspaceId)?.has(thread) ?? false))
+            return;
+        // {§agui-delegation-observation} A subagent's start introduces its worker; any other descendant is introduced once
+        // before its first event.
+        const introduction = thread.introduced.has(actor) || subagent !== null ? []
+            : [{ type: EventType.CUSTOM, name: "plurnk.descendant", value: node }];
+        thread.introduced.add(actor);
+        const out = subagent === null
+            ? [...introduction, ...thread.router.route(method, params)]
+            : [...Portal.#present(subagent), ...subagent.translator.logEntry(params)];
+        if (out.length > 0)
+            thread.emit(out);
+    }
+    // {§agui-subagents} The subagent a descendant's row belongs to, when a call in view opened its loop.
+    async #rowSubagent(thread, node, loopId) {
+        const judged = thread.judged.get(loopId);
+        if (judged !== undefined)
+            return judged;
+        const loop = (await this.#seam.listWorkerLoops({ workspaceId: thread.workspaceId, workerId: node.workerId })).find(({ id }) => id === loopId);
+        if (loop !== undefined)
+            return this.#judge(thread, node, loop);
+        const unlisted = Promise.resolve(null);
+        thread.judged.set(loopId, unlisted);
+        return unlisted;
+    }
+    // {§agui-subagents} A descendant loop is a subagent of this Run when a call in view opened it: the bound Worker's,
+    // or one a subagent of this Run made. Each loop is judged once, from the daemon's record of what opened it, and the
+    // live and snapshot projections share the judgment.
+    #judge(thread, node, loop) {
+        let judged = thread.judged.get(loop.id);
+        if (judged === undefined) {
+            judged = this.#judgeLoop(thread, node, loop);
+            thread.judged.set(loop.id, judged);
+        }
+        return judged;
+    }
+    async #judgeLoop(thread, node, loop) {
+        const parent = loop.invocation === null ? null : await this.#opener(thread, loop.invocation);
+        if (parent === null)
+            return null;
+        const runId = `ops://${node.name}/${loop.sequence}`;
+        const subagent = {
+            runId, loopId: loop.id, workerId: node.workerId, worker: node.name, descendant: node, loopSequence: loop.sequence, parent,
+            translator: thread.router.subagentTranslator({ modelWorkerId: node.workerId, subagent: { runId, worker: node.name } }),
+            // A conclusion still on its way to this Run ends the segment when it arrives.
+            result: this.#terminalsDue.has(loop.id) ? null : loop.terminalResult,
+            segment: "unstarted",
+        };
+        thread.subagents.set(loop.id, subagent);
+        return subagent;
+    }
+    // {§agui-subagents} The call that opened a loop, as this Run's client identifies it, when this Run sees it.
+    async #opener(thread, invocation) {
+        const call = Translator.callOf(invocation.address);
+        if (invocation.workerId === thread.workerId)
+            return { call };
+        let node = thread.tree?.get(invocation.workerId);
+        if (node === undefined && thread.workerId !== null) {
+            thread.tree = await this.#descendantTree(thread.workspaceId, thread.workerId);
+            node = thread.tree.get(invocation.workerId);
+        }
+        if (node === undefined)
+            return null;
+        const loopSequence = Number(call.split("/")[0]);
+        const loop = (await this.#seam.listWorkerLoops({ workspaceId: thread.workspaceId, workerId: node.workerId })).find(({ sequence }) => sequence === loopSequence);
+        const subagent = loop === undefined ? null : await this.#judge(thread, node, loop);
+        return subagent === null ? null : { call: `${Translator.subagentIds(subagent.worker)}#${call}`, subagent };
+    }
+    // {§agui-subagents} A subagent's segment of this Run starts the first time the Run presents its work, after its
+    // parent's; a loop that concluded before the Run could see it ends it at once.
+    static #present(subagent) {
+        if (subagent.segment !== "unstarted")
+            return [];
+        const parent = subagent.parent.subagent;
+        const events = parent === undefined ? [] : Portal.#present(parent);
+        subagent.segment = "open";
+        events.push({
+            type: EventType.SUBAGENT_STARTED, subagentRunId: subagent.runId, name: subagent.worker, parentToolCallId: subagent.parent.call,
+            ...(parent === undefined ? {} : { parentSubagentRunId: parent.runId }),
+            metadata: { plurnk: { ...subagent.descendant } },
+        });
+        if (subagent.result !== null)
+            events.push(...Portal.#end(subagent, subagent.result));
+        return events;
+    }
+    // {§agui-subagents} A loop that completed finishes its subagent with its exact result; any other conclusion, a stop
+    // included, is the subagent's error, from its Problem Details.
+    static #end(subagent, result) {
+        subagent.segment = "ended";
+        const end = result.status < 400
+            ? { type: EventType.SUBAGENT_FINISHED, subagentRunId: subagent.runId, outcome: { type: "success" }, result }
+            : { type: EventType.SUBAGENT_ERROR, subagentRunId: subagent.runId, message: result.problem.detail, code: result.problem.type };
+        return [...subagent.translator.finish(), end];
+    }
+    // {§agui-subagents} A subagent's loop concluded: an open segment ends now, an unstarted one when it is presented;
+    // null for a loop that is no subagent of this Run.
+    static #concluded(thread, terminal) {
+        const subagent = thread.subagents.get(terminal.loopId);
+        if (subagent === undefined)
+            return null;
+        subagent.result = Validator.assertOperationResult(terminal.result);
+        return subagent.segment === "open" ? Portal.#end(subagent, subagent.result) : [];
+    }
+    // {§agui-subagents} The bound Worker's events, preceded by the end of every subagent segment when they finish the Run.
+    static #finishing(thread, events) {
+        return events.some(({ type }) => type === EventType.RUN_FINISHED) ? [...Portal.#closeSubagents(thread), ...events] : events;
+    }
+    // {§agui-subagents} A Run that finishes ends every segment it opened: a subagent still running is suspended, its
+    // work going on for a later Run to present, and each subagent's open step closes first.
+    static #closeSubagents(thread) {
+        return [...thread.subagents.values()].filter(({ segment }) => segment !== "unstarted").flatMap((subagent) => {
+            const events = subagent.translator.finish();
+            if (subagent.segment === "open") {
+                subagent.segment = "ended";
+                events.push({ type: EventType.SUBAGENT_FINISHED, subagentRunId: subagent.runId, outcome: { type: "suspended" } });
             }
-            const out = thread.router.route(method, params);
-            if (out.length > 0)
-                thread.emit(out);
+            return events;
         });
     }
+    // {§agui-snapshot} {§agui-subagents} The subagent runs a snapshot replays: each descendant loop a call in view opened,
+    // with the rows `history` reads from its worker's log.
+    async subagentHistory(thread, history) {
+        const bound = thread;
+        if (!bound.descendants || bound.workerId === null)
+            return [];
+        bound.tree = await this.#descendantTree(bound.workspaceId, bound.workerId);
+        const parts = [];
+        for (const node of [...bound.tree.values()].toSorted((left, right) => left.depth - right.depth)) {
+            const loops = await this.#seam.listWorkerLoops({ workspaceId: bound.workspaceId, workerId: node.workerId });
+            const subagents = (await Promise.all(loops.map((loop) => this.#judge(bound, node, loop))))
+                .filter((subagent) => subagent !== null);
+            if (subagents.length === 0)
+                continue;
+            const rows = await history(node.workerId);
+            for (const subagent of subagents)
+                parts.push({ subagent, entries: rows.filter(({ loop_id }) => loop_id === subagent.loopId) });
+        }
+        return parts;
+    }
     async #descendantTree(workspaceId, rootId) {
-        const byId = _a.#workerMap(await this.#seam.listWorkers(workspaceId));
+        const byId = Portal.#workerMap(await this.#seam.listWorkers(workspaceId));
         const tree = new Map();
         for (const candidate of byId.values()) {
             if (candidate.id === rootId || candidate.parentWorkerId === null)
                 continue;
-            const depth = _a.#ancestors(candidate.id, byId).indexOf(rootId) + 1;
+            const depth = Portal.#ancestors(candidate.id, byId).indexOf(rootId) + 1;
             if (depth > 0)
                 tree.set(candidate.id, { workerId: candidate.id, name: candidate.name, parentWorkerId: candidate.parentWorkerId, depth });
         }
@@ -192,7 +364,7 @@ class Portal {
             const attrs = entry.attrs;
             return typeof attrs?.stream === "string" && attrs.detached !== true ? attrs.stream : null;
         }
-        return method === "stream/event" ? _a.#streamTarget(params) : null;
+        return method === "stream/event" ? Portal.#streamTarget(params) : null;
     }
     static #streamTarget(params) {
         const target = params.target;
@@ -200,36 +372,85 @@ class Portal {
             throw new Error(`A stream notification names no target: ${JSON.stringify(params)}`);
         return target;
     }
+    // {§agui-broadcast-fan} An operation Run shares its runtime Worker with every other client operation and the
+    // daemon's own work, so it owns exactly its Loop: that Loop's rows and notices, and the streams those rows
+    // announced. Its action result settles it, never the Loop's terminal.
     static #ownsNotification(thread, method, params) {
         if (thread.notificationScope === "result")
             return false;
+        const operation = thread.notificationScope === "operation";
         const payload = params;
         const owns = (workerId, loopId) => typeof workerId === "number"
             && workerId === thread.workerId
-            && (thread.loopId === null || typeof loopId !== "number" || loopId === thread.loopId);
+            && (operation
+                ? thread.loopId !== null && loopId === thread.loopId
+                : thread.loopId === null || typeof loopId !== "number" || loopId === thread.loopId);
         switch (method) {
             case "workspace/preparation": return true;
             case "log/entry": return owns(payload.entry?.worker_id, payload.entry?.loop_id);
-            case "loop/terminated":
+            case "loop/terminated": return !operation && owns(payload.workerId, payload.loopId);
             case "loop/packet":
             case "reasoning/event":
             case "outside/event": return owns(payload.workerId, payload.loopId);
             case "notice/event": return payload.workerId === null
-                ? thread.notificationScope === "conversation"
+                ? thread.notificationScope === "worker"
                 : owns(payload.workerId, payload.loopId);
             case "stream/event":
-            case "stream/concluded": return owns(payload.workerId);
+            case "stream/concluded": return operation
+                ? payload.workerId === thread.workerId && thread.openStreams.has(Portal.#streamTarget(params))
+                : owns(payload.workerId);
             default: return false;
         }
     }
+    // A stream of an operation Run's Worker that no row of its Loop has announced: it may be this Run's own
+    // execution whose row is still to arrive, so its latest snapshot and conclusion wait for that row.
+    static #holdUnannounced(thread, method, params) {
+        if (thread.notificationScope !== "operation" || thread.loopId === null)
+            return;
+        if (method !== "stream/event" && method !== "stream/concluded")
+            return;
+        if (params.workerId !== thread.workerId)
+            return;
+        const target = Portal.#streamTarget(params);
+        const held = thread.unannounced.get(target) ?? { event: null, concluded: null };
+        thread.unannounced.set(target, method === "stream/event" ? { ...held, event: params } : { ...held, concluded: params });
+    }
+    // The row that announces a stream delivers what it held, in order; a stream already concluded stays closed.
+    #releaseUnannounced(thread, target) {
+        const held = thread.unannounced.get(target);
+        if (held === undefined)
+            return;
+        thread.unannounced.delete(target);
+        if (held.event !== null) {
+            const out = thread.router.route("stream/event", held.event);
+            if (out.length > 0)
+                thread.emit(out);
+        }
+        if (held.concluded !== null) {
+            thread.openStreams.delete(target);
+            const out = thread.router.route("stream/concluded", held.concluded);
+            if (out.length > 0)
+                thread.emit(out);
+        }
+    }
     stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
         this.#hitl.stop();
         this.#off?.();
         this.#off = null;
         this.#continuations.clear();
+        // {§agui-shutdown} Module close follows core settlement; remaining Runs are
+        // transport lifetimes, not unfinished worker obligations to await again.
+        for (const threads of this.#threads.values()) {
+            for (const thread of threads)
+                this.failThread(thread, runErrorEvents(serviceStoppingProblem()));
+        }
+        this.#threads.clear();
     }
     #emitDelivery(workspaceId, delivery, threads) {
-        if (delivery.batch.events.length === 0)
+        if (delivery.batch.gates.length === 0)
             return;
         for (const thread of threads) {
             const controlLoopId = thread.loopId
@@ -240,51 +461,63 @@ class Portal {
                 thread.deferredDelivery ??= delivery;
                 continue;
             }
+            // {§agui-proposal-resolve} Each gate's call reaches this Run before its interrupt, then the continuation records
+            // it as held, so the Run that resumes folds the settlement onto the call its client holds.
+            const shaped = delivery.batch.gates.map((gate) => ({ gate, ...Portal.#concerning(thread, gate) }));
             const paused = thread.router.interrupt();
-            for (const interrupt of delivery.batch.interrupts) {
-                const key = interrupt.toolCallId ?? interrupt.id;
-                const existing = this.#continuations.get(key);
-                if (existing === undefined || existing.inputRunId === thread.inputRunId)
-                    this.#continuations.set(key, {
-                        workspaceId,
-                        owner: delivery.recipient,
-                        gate: { workerId: delivery.workerId, loopId: delivery.loopId },
-                        control: { workerId: thread.workerId, loopId: controlLoopId },
-                        threadId: thread.threadId,
-                        inputRunId: thread.inputRunId,
-                        notificationScope: thread.notificationScope,
-                        state: paused.continuation,
-                    });
-            }
-            thread.emit([...delivery.batch.events, ...paused.events]);
+            const continuation = {
+                cancelOnDisconnect: thread.cancelOnDisconnect,
+                workspaceId,
+                owner: delivery.recipient,
+                gate: { workerId: delivery.workerId, loopId: delivery.loopId },
+                binding: { workerId: thread.workerId, loopId: controlLoopId },
+                modelWorkerId: thread.modelWorkerId,
+                threadId: thread.threadId,
+                state: {
+                    ...paused.continuation,
+                    currentTurn: paused.continuation.currentTurn
+                        ?? (thread.workerId === delivery.workerId ? delivery.turnId : null),
+                },
+            };
+            const interrupts = shaped.map(({ gate, concerns }) => {
+                const id = crypto.randomUUID();
+                this.#continuations.set(id, { key: gate.key, kind: gate.kind, continuation });
+                return { ...gate.interrupt, id, ...concerns };
+            });
+            // {§agui-subagents} The interrupt finishes the Run, so its subagents' segments end before it.
+            thread.emit([...delivery.batch.events, ...shaped.flatMap(({ events }) => events), ...paused.events, ...Portal.#closeSubagents(thread)], interrupts);
         }
     }
+    // {§agui-proposal-resolve} The call a gate's interrupt names on this Run, and the events that present it: the operation's
+    // own call, its worker's or an open subagent's, sent unless this Run's client holds it; none on a Run whose conversation
+    // holds no call of that worker.
+    static #concerning(thread, gate) {
+        if (gate.call === undefined)
+            return { concerns: {}, events: [] };
+        const { workerId, loopId, coordinate, entry } = gate.call;
+        if (thread.workerId === workerId)
+            return { concerns: { toolCallId: coordinate }, events: thread.router.gateCall(entry) };
+        const subagent = thread.subagents.get(loopId);
+        if (subagent?.workerId === workerId && subagent.segment === "open") {
+            return { concerns: { toolCallId: `${Translator.subagentIds(subagent.worker)}#${coordinate}`, subagentRunId: subagent.runId },
+                events: subagent.translator.gateCall(entry) };
+        }
+        return { concerns: {}, events: [] };
+    }
     #presentDeferred(workspaceId, thread) {
         const delivery = thread.deferredDelivery;
         if (delivery === null || thread.router.reasoningOpen)
             return;
         thread.deferredDelivery = null;
-        this.#withHitl(delivery.batch, () => this.#emitDelivery(workspaceId, delivery, [thread]));
-    }
-    #withHitl(batch, emit) {
-        for (const interrupt of batch.interrupts) {
-            this.#activeInterrupts.set(interrupt.toolCallId ?? interrupt.id, interrupt);
-        }
-        try {
-            emit(batch.events);
-        }
-        finally {
-            for (const interrupt of batch.interrupts) {
-                this.#activeInterrupts.delete(interrupt.toolCallId ?? interrupt.id);
-            }
-        }
+        this.#emitDelivery(workspaceId, delivery, [thread]);
     }
+    // {§agui-worker-owner} A gate reaches its owner's Runs that observe a worker: the one bound to its worker, else
+    // every one. An operation or result Run never presents one.
     #routeHitl(workspaceId, delivery) {
         const threads = [...(this.#threads.get(workspaceId) ?? [])]
-            .filter((thread) => thread.owner === delivery.recipient && thread.notificationScope !== "result");
+            .filter((thread) => thread.owner === delivery.recipient && thread.notificationScope === "worker");
         const exact = threads.filter((thread) => thread.workerId === delivery.workerId);
-        const recipients = exact.length > 0 ? exact : threads.filter((thread) => thread.notificationScope === "conversation");
-        this.#withHitl(delivery.batch, () => this.#emitDelivery(workspaceId, delivery, recipients));
+        this.#emitDelivery(workspaceId, delivery, exact.length > 0 ? exact : threads);
     }
     #enqueueDelivery(workspaceId, task) {
         const prior = this.#deliveryTails.get(workspaceId) ?? Promise.resolve();
@@ -336,51 +569,69 @@ class Portal {
             .filter(({ terminatedAt, terminalResult }) => terminatedAt === null && terminalResult === null));
         return active?.id ?? null;
     }
-    interruptForToolCall(toolCallId) {
-        return this.#activeInterrupts.get(toolCallId) ?? null;
+    // {§agui-action-binding} The model worker the Run that presented these interrupts bound, which their
+    // resume binds in turn; undefined when it bound none or the set names no one presentation of this thread.
+    resumedWorker(workspaceId, threadId, resume) {
+        const continuations = resume.map(({ interruptId }) => this.#continuations.get(interruptId)?.continuation);
+        const first = continuations[0];
+        if (first === undefined || continuations.some((candidate) => candidate !== first))
+            return undefined;
+        if (first.workspaceId !== workspaceId || first.threadId !== threadId)
+            return undefined;
+        return first.modelWorkerId ?? undefined;
     }
     // Bind a client's SSE to a workspace and AG-UI Run. The emit consumer ends its stream when it
     // sees RUN_FINISHED / RUN_ERROR (the router's terminal projection) — the engine
-    // owns notification routing; the edge owns the socket lifecycle. `workerId` is the lifecycle actor
-    // (client worker for client ops, conversation worker otherwise); `modelWorkerId`
-    // binds the render (null → the router lazily
-    // adopts the first model-origin row's worker — a fresh workspace's model worker is born
-    // at the drain).
+    // owns notification routing; the edge owns the socket lifecycle. `workerId` is the Worker the Run observes,
+    // null for one that observes none or, for an operation Run, until bindOperation; `modelWorkerId` is the model
+    // worker the Run binds and renders, null when it binds none ({§agui-action-binding}).
     openThread(args) {
+        if (this.#stopped)
+            throw new HttpProblemError(serviceStoppingProblem());
         const candidates = args.resume
-            ?.map(({ interruptId }) => this.#continuations.get(interruptId)) ?? [];
-        const restored = candidates.find((candidate) => candidate !== undefined
-            && candidate.workspaceId === args.workspaceId
-            && candidate.owner === args.owner
-            && candidate.threadId === args.threadId);
+            ?.map(({ interruptId }) => this.#continuations.get(interruptId)?.continuation) ?? [];
+        const first = candidates[0];
+        const restored = first !== undefined && candidates.every((candidate) => candidate === first)
+            && first.workspaceId === args.workspaceId && first.owner === args.owner && first.threadId === args.threadId
+            ? first : undefined;
         const continuation = restored?.state;
         const router = new EventRouter({
             threadId: args.threadId,
+            ...(args.replyThreads === undefined ? {} : { replyThreads: args.replyThreads }),
             runId: args.inputRunId ?? String(args.workerId),
             modelWorkerId: args.modelWorkerId ?? null,
             workspaceId: args.workspaceId,
             ...(continuation === undefined ? {} : { continuation }),
         });
         const t = {
+            workspaceId: args.workspaceId,
             owner: args.owner ?? null,
-            workerId: restored?.control.workerId ?? args.workerId,
-            loopId: restored?.control.loopId ?? null,
-            notificationScope: restored?.notificationScope ?? args.notificationScope,
+            family: args.family ?? null,
+            workerId: restored?.binding.workerId ?? args.workerId,
+            loopId: restored?.binding.loopId ?? null,
+            notificationScope: args.notificationScope,
+            modelWorkerId: args.modelWorkerId ?? null,
             router,
             emit: args.emit,
             threadId: args.threadId,
             inputRunId: args.inputRunId ?? String(args.workerId),
             openStreams: new Set(),
+            unannounced: new Map(),
             deferredFinish: null,
             pendingTerminations: [],
             resolvingInterrupts: args.resume !== undefined,
+            cancelOnDisconnect: restored?.cancelOnDisconnect ?? args.cancelOnDisconnect === true,
+            disconnected: false,
             deferredDelivery: null,
             descendants: args.descendants === true,
             tree: null,
             introduced: new Set(),
             unrelated: new Set(),
-            children: null,
-            delegation: null,
+            judged: new Map(),
+            subagents: new Map(),
+            gauge: null,
+            staleGauge: false,
+            gaugeRefresh: 0,
         };
         let set = this.#threads.get(args.workspaceId);
         if (set === undefined) {
@@ -391,43 +642,100 @@ class Portal {
         return t;
     }
     closeRun(workspaceId, t) { this.#threads.get(workspaceId)?.delete(t); }
-    runStarted(thread, state) {
-        return thread.router.runStarted(state);
-    }
-    replay(thread, entries, currentUser) {
-        return thread.router.replay(entries, currentUser);
+    // {§agui-run-disconnect} A message Run cancels its bound worker; an operation Run cancels exactly its own Loop,
+    // at once when known, else when its dispatch opens it.
+    disconnect(thread) {
+        const bound = thread;
+        if (bound.disconnected)
+            return;
+        bound.disconnected = true;
+        if (bound.cancelOnDisconnect)
+            this.#cancelOwned(bound);
+    }
+    #cancelOwned(thread) {
+        if (thread.notificationScope === "operation") {
+            const loopId = thread.loopId;
+            if (loopId === null)
+                return;
+            void this.#seam.cancelLoop({ workspaceId: thread.workspaceId, loopId, reason: "client_disconnected" }).catch((cause) => {
+                console.error(`AG-UI: cancelling client operation loop ${loopId} failed:`, cause);
+            });
+            return;
+        }
+        if (thread.workerId !== null)
+            this.#seam.cancelDrain(thread.workerId, "client_disconnected");
     }
-    #finishThread(thread, events) {
-        thread.emit([...events, ...thread.router.finish(), { type: EventType.RUN_FINISHED, threadId: thread.threadId, runId: thread.inputRunId, outcome: { type: "success" } }]);
+    // {§agui-broadcast-fan} An operation Run observes the Loop its dispatch opened, from before any statement runs.
+    bindOperation(thread, loop) {
+        const bound = thread;
+        bound.workerId = loop.workerId;
+        bound.loopId = loop.loopId;
+        if (bound.disconnected && bound.cancelOnDisconnect)
+            this.#cancelOwned(bound);
     }
-    finishThread(thread, events) {
+    // {§agui-status-children} {§agui-status-spend} — the snapshot is the gauge the status deltas patch.
+    runStarted(thread, state) {
+        const bound = thread;
+        const events = bound.router.runStarted(state);
+        const status = state?.type === EventType.STATE_SNAPSHOT
+            ? state.snapshot.plurnk?.status
+            : undefined;
+        if (status !== undefined)
+            this.#presentGauge(bound, status);
+        return events;
+    }
+    // A whole-gauge replacement: the client's gauge is this status from here on.
+    replaceStatus(thread, status) {
+        this.#presentGauge(thread, status);
+        return [stateDelta([{ op: "replace", path: "/plurnk/status", value: status }])];
+    }
+    // {§agui-snapshot} {§agui-subagents} The conversation, then the subagent runs it holds, each presented.
+    replay(thread, entries, currentUser, subagents = []) {
+        return [
+            ...thread.router.replay(entries, currentUser, subagents.map(({ subagent, entries: rows }) => ({ translator: subagent.translator, entries: rows }))),
+            ...subagents.flatMap(({ subagent }) => Portal.#present(subagent)),
+        ];
+    }
+    #finishThread(thread, events, result) {
+        const finished = { type: EventType.RUN_FINISHED, threadId: thread.threadId, runId: thread.inputRunId, outcome: { type: "success" },
+            ...(result === undefined ? {} : { result }) };
+        thread.emit([...events, ...thread.router.finish(), ...Portal.#closeSubagents(thread), finished]);
+    }
+    // The Run finishes with `events`, and `result` as its result when it has one.
+    finishThread(thread, events, result) {
         const bound = thread;
         if (bound.openStreams.size > 0) {
-            bound.deferredFinish = events;
+            bound.deferredFinish = { events, result };
             return;
         }
-        this.#finishThread(bound, events);
+        this.#finishThread(bound, events, result);
     }
     failThread(thread, events) {
         const bound = thread;
-        bound.emit([...bound.router.finish(), ...events]);
-    }
-    // Emit extra events + RUN_FINISHED through the resumed Run that owns the
-    // original action's worker and client thread —
-    // an action that paused on a proposal completes after the resume AG-UI Run rebound the
-    // stream, so its result must ride whichever response is live now, never the
-    // closure of the request that spawned it.
-    finishRun(workspaceId, workerId, threadId, events) {
-        for (const t of this.#threads.get(workspaceId) ?? []) {
-            if (t.notificationScope === "result" || t.workerId !== workerId || t.threadId !== threadId)
-                continue;
-            this.finishThread(t, events);
+        bound.emit([...bound.router.fail(), ...events]);
+    }
+    // {§agui-oauth-revocation} — every Run admitted under the family ends with the given events; the
+    // loops those Runs observed continue, since a revoked observer is not a cancelling one.
+    failFamily(family, events) {
+        for (const threads of this.#threads.values()) {
+            for (const thread of threads) {
+                if (thread.family !== family)
+                    continue;
+                this.failThread(thread, events);
+                threads.delete(thread);
+            }
         }
     }
     async #resurfaceControlled(workspaceId, thread) {
         if (thread.owner === null)
             return false;
         const deliveries = await this.#hitl.resurface(workspaceId, thread.owner);
+        const pendingKeys = new Set(deliveries.flatMap(({ batch }) => batch.gates.map(({ key }) => key)));
+        for (const [id, candidate] of this.#continuations) {
+            if (candidate.continuation.workspaceId === workspaceId && candidate.continuation.owner === thread.owner
+                && !pendingKeys.has(candidate.key))
+                this.#continuations.delete(id);
+        }
         if (deliveries.length === 0)
             return false;
         const delivery = deliveries.find(({ workerId }) => thread.workerId === workerId) ?? deliveries[0];
@@ -436,9 +744,9 @@ class Portal {
         if (thread.loopId === null) {
             thread.loopId = delivery.workerId === thread.workerId
                 ? delivery.loopId
-                : await this.#activeLoopId(workspaceId, thread.workerId);
+                : thread.workerId === null ? null : await this.#activeLoopId(workspaceId, thread.workerId);
         }
-        this.#withHitl(delivery.batch, () => this.#emitDelivery(workspaceId, delivery, [thread]));
+        this.#emitDelivery(workspaceId, delivery, [thread]);
         return true;
     }
     #bindLoop(thread, loopId) {
@@ -447,17 +755,19 @@ class Portal {
         thread.pendingTerminations = [];
         if (terminal === undefined)
             return false;
-        const out = thread.router.route("loop/terminated", terminal);
+        const out = Portal.#finishing(thread, thread.router.route("loop/terminated", terminal));
         if (out.length > 0)
             thread.emit(out);
         return true;
     }
-    // Synchronize one AG-UI observer with the durable conversation. A pending
+    // Synchronize one AG-UI observer with the bound worker's durable log. A pending
     // stopped-world is re-presented first; otherwise an active Loop stays attached
-    // and an idle conversation settles immediately. Returns true only while this
+    // and an idle worker settles immediately. Returns true only while this
     // thread remains attached to independently-owned live work.
     async synchronize(workspaceId, thread, waitForWork = false) {
         const bound = thread;
+        if (bound.workerId === null)
+            throw new Error("a synchronization Run reached the Portal without its worker");
         if (await this.#resurfaceControlled(workspaceId, bound))
             return false;
         const loop = selectWorkerLoop((await this.#seam.listWorkerLoops({ workspaceId, workerId: bound.workerId }))
@@ -475,14 +785,25 @@ class Portal {
     // Core before any pending stopped-world is re-presented.
     async run(thread, args) {
         const bound = thread;
+        // {§agui-snapshot} The submitting Run's client holds its own message; every other Run receives it.
+        const submitted = args.envelope?.message?.id;
+        if (typeof submitted === "string")
+            bound.router.submitted(submitted);
         const ack = await this.#seam.runLoop(args);
+        if (bound.disconnected) {
+            if (bound.cancelOnDisconnect)
+                this.#cancelOwned(bound);
+            return null;
+        }
+        if (!this.#threads.get(args.workspaceId)?.has(bound))
+            return null;
         if (await this.#resurfaceControlled(args.workspaceId, bound))
             return null;
         this.#bindLoop(bound, ack.loopId);
         return { loopId: ack.loopId };
     }
     cancel(workerId) { return this.#seam.cancelDrain(workerId); }
-    // A standard resume AG-UI Run binds to the persisted continuation before
+    // A standard resume AG-UI Run binds to its presentation's continuation before
     // releasing every addressed interrupt.
     async resolve(workspaceId, thread, entries) {
         const bound = thread;
@@ -490,45 +811,35 @@ class Portal {
             throw new Error("an observer cannot resolve interrupts");
         bound.resolvingInterrupts = true;
         const continuations = entries.map(({ interruptId }) => this.#continuations.get(interruptId));
-        const persisted = continuations.filter((continuation) => continuation !== undefined);
-        if (persisted.length > 0 && persisted.length !== entries.length) {
-            throw new Error("resume mixes persisted and unbound interrupts");
-        }
-        const continuation = persisted[0];
-        if (continuation !== undefined) {
-            for (const candidate of persisted) {
-                if (candidate.workspaceId !== continuation.workspaceId
-                    || candidate.owner !== continuation.owner
-                    || candidate.threadId !== continuation.threadId
-                    || candidate.gate.workerId !== continuation.gate.workerId
-                    || candidate.gate.loopId !== continuation.gate.loopId
-                    || candidate.control.workerId !== continuation.control.workerId
-                    || candidate.control.loopId !== continuation.control.loopId) {
-                    throw new Error("resume interrupts do not share one persisted control binding");
-                }
-            }
+        const recorded = continuations.filter((continuation) => continuation !== undefined);
+        if (recorded.length !== entries.length || recorded.length === 0) {
+            throw new HttpProblemError(Problems.create("agui:interrupt", "interrupt-not-pending", 409, "The resume addresses an unknown interrupt presentation.", {
+                stage: "interrupt-resolution", retryable: false,
+                recovery: "Refresh pending interrupts before resuming.",
+            }));
         }
-        await this.#hitl.resolve(workspaceId, bound.owner, entries, async (resolution) => {
-            if (continuation !== undefined) {
-                if (continuation.workspaceId !== workspaceId
-                    || continuation.owner !== bound.owner
-                    || continuation.threadId !== bound.threadId
-                    || continuation.gate.workerId !== resolution.workerId
-                    || continuation.gate.loopId !== resolution.loopId) {
-                    throw new Error("resume does not match its persisted interrupt binding");
-                }
-                bound.workerId = continuation.control.workerId;
-                bound.loopId = continuation.control.loopId;
-                bound.notificationScope = continuation.notificationScope;
-            }
-            else {
-                const exact = resolution.workerId === bound.workerId;
-                bound.loopId = exact
-                    ? resolution.loopId
-                    : await this.#activeLoopId(workspaceId, bound.workerId);
+        const continuation = recorded[0].continuation;
+        if (recorded.some((candidate) => candidate.continuation !== continuation)) {
+            throw new HttpProblemError(Problems.create("agui:interrupt", "interrupt-binding-invalid", 400, "The resume combines interrupts from different Runs."));
+        }
+        const resolutions = entries.map((entry, index) => ({ ...entry, interruptId: recorded[index].key }));
+        await this.#hitl.resolve(workspaceId, bound.owner, resolutions, (resolution) => {
+            if (continuation.workspaceId !== workspaceId
+                || continuation.owner !== bound.owner
+                || continuation.threadId !== bound.threadId
+                || continuation.gate.workerId !== resolution.workerId
+                || continuation.gate.loopId !== resolution.loopId) {
+                throw new HttpProblemError(Problems.create("agui:interrupt", "interrupt-binding-invalid", 400, "The resume does not match its interrupt's binding."));
             }
+            bound.workerId = continuation.binding.workerId;
+            bound.loopId = continuation.binding.loopId;
+            bound.cancelOnDisconnect = continuation.cancelOnDisconnect;
+            if (bound.disconnected)
+                throw new HttpProblemError(Problems.create("agui:interrupt", "connection-closed", 499, "The connection closed before the interrupt was resolved."));
         });
-        bound.emit(entries.map((entry) => ({
+        // A client interaction is its own call, answered by the response; a proposal's call is answered by its
+        // operation's settlement, which arrives as that row.
+        bound.emit(resolutions.filter((_entry, index) => recorded[index].kind === "interaction").map((entry) => ({
             type: EventType.TOOL_CALL_RESULT,
             toolCallId: entry.interruptId,
             messageId: `${entry.interruptId}/result`,
@@ -539,8 +850,11 @@ class Portal {
         bound.resolvingInterrupts = false;
         if (bound.loopId !== null)
             this.#bindLoop(bound, bound.loopId);
-        for (const { interruptId } of entries)
-            this.#continuations.delete(interruptId);
+        const resolvedIds = new Set(resolutions.map(({ interruptId }) => interruptId));
+        for (const [id, candidate] of this.#continuations) {
+            if (candidate.continuation.workspaceId === workspaceId && resolvedIds.has(candidate.key))
+                this.#continuations.delete(id);
+        }
         if (this.#threads.get(workspaceId)?.has(bound)) {
             const surfaced = await this.#resurfaceControlled(workspaceId, bound);
             if (!surfaced && bound.loopId === null)
@@ -548,6 +862,4 @@ class Portal {
         }
     }
 }
-_a = Portal;
-export default Portal;
 //# sourceMappingURL=Portal.js.map