@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/local-host/app-request-approvals.js

@@ -0,0 +1,150 @@
+export function hasApprovalDecisionIdentity(input) {
+    if (!input || typeof input !== "object")
+        return false;
+    const value = input;
+    if (typeof value.sessionId !== "string")
+        return false;
+    if (typeof value.requestId !== "string")
+        return false;
+    if (typeof value.approvalId !== "string")
+        return false;
+    if (typeof value.approved !== "boolean")
+        return false;
+    return value.reason === undefined || typeof value.reason === "string";
+}
+function readCallbackDecision(value) {
+    if (typeof value !== "object" || value === null)
+        return { approved: false, reason: "Tool approval response was invalid." };
+    const decision = value;
+    return {
+        approved: decision.approved === true,
+        ...(typeof decision.reason === "string" ? { reason: decision.reason } : {}),
+    };
+}
+/** Approval promises belong to the live request, never to a transport attempt. */
+export class LocalRequestApprovals {
+    pending = new Map();
+    list(sessionId) {
+        const entries = [...this.pending.values()].flatMap((group) => [
+            ...group.values(),
+        ]);
+        return entries
+            .filter((entry) => sessionId === undefined || entry.sessionId === sessionId)
+            .map((entry) => ({
+            sessionId: entry.sessionId,
+            request: structuredClone(entry.request),
+        }));
+    }
+    hasPending(requestId) {
+        return Boolean(this.pending.get(requestId)?.size);
+    }
+    decide(input) {
+        if (!hasApprovalDecisionIdentity(input))
+            return { accepted: false, reason: "invalid_approval_decision" };
+        const entry = this.pending.get(input.requestId)?.get(input.approvalId);
+        if (!entry)
+            return { accepted: false, reason: "approval_not_pending" };
+        if (entry.sessionId !== input.sessionId)
+            return { accepted: false, reason: "approval_identity_mismatch" };
+        entry.complete({
+            approved: input.approved,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        });
+        return { accepted: true };
+    }
+    wait(sessionId, peer, request, signal) {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        const snapshot = structuredClone(request);
+        const { requestId, approvalId } = snapshot;
+        const group = this.pending.get(requestId) ?? new Map();
+        if (group.has(approvalId))
+            throw new Error("local_runtime_approval_already_pending");
+        return new Promise((resolve, reject) => {
+            const release = (entry, notify = true) => {
+                if (group.get(approvalId) !== entry)
+                    return false;
+                group.delete(approvalId);
+                if (!group.size)
+                    this.pending.delete(requestId);
+                signal.removeEventListener("abort", cancel);
+                this.detachOffer(entry, notify);
+                return true;
+            };
+            const entry = {
+                sessionId,
+                request: snapshot,
+                complete: (decision, notify = true) => {
+                    if (release(entry, notify))
+                        resolve(decision);
+                },
+                abort: (reason) => {
+                    if (release(entry))
+                        reject(reason);
+                },
+            };
+            const cancel = () => entry.abort(signal.reason);
+            group.set(approvalId, entry);
+            this.pending.set(requestId, group);
+            signal.addEventListener("abort", cancel, { once: true });
+            if (peer)
+                this.offer(entry, peer);
+        });
+    }
+    detach(requestId) {
+        for (const entry of this.pending.get(requestId)?.values() ?? [])
+            this.detachOffer(entry);
+    }
+    attach(requestId, peer) {
+        for (const entry of this.pending.get(requestId)?.values() ?? [])
+            this.offer(entry, peer);
+    }
+    cancel(requestId) {
+        for (const entry of this.pending.get(requestId)?.values() ?? [])
+            entry.abort(new Error("request_activation_retired"));
+    }
+    offer(entry, peer) {
+        this.detachOffer(entry);
+        const offer = {
+            peer,
+            connected: true,
+            removeClose: () => { },
+        };
+        entry.offer = offer;
+        offer.removeClose = peer.onClose(() => {
+            offer.connected = false;
+        });
+        if (!offer.connected)
+            return;
+        void peer
+            .callClient("request.approval", [structuredClone(entry.request)])
+            .then((decision) => {
+            if (!this.isCurrentOffer(entry, offer))
+                return;
+            entry.complete(readCallbackDecision(decision), false);
+        }, () => {
+            // Delivery failure leaves the same canonical approval unresolved.
+            offer.connected = false;
+        });
+    }
+    isCurrentOffer(entry, offer) {
+        if (entry.offer !== offer)
+            return false;
+        return offer.connected;
+    }
+    detachOffer(entry, notify = true) {
+        const offer = entry.offer;
+        entry.offer = undefined;
+        if (!offer)
+            return;
+        offer.removeClose();
+        if (!offer.connected)
+            return;
+        offer.connected = false;
+        if (!notify)
+            return;
+        void offer.peer
+            .callClient("request.approval.cancel", [entry.request.approvalId])
+            .catch(() => undefined);
+    }
+}

package/dist/src/runtime/local-host/app-request-control.d.ts

@@ -1,9 +1,13 @@
 import type { RuntimeRequestOptions } from "../composition.js";
+import type { SessionWaitExpectation } from "../../sessions/request-lifecycle/contracts.js";
+import { type RequestCancellationResult } from "../request/cancellation.js";
 import { type RequestSteeringUpdate } from "../request/request-steering.js";
 import type { SchedulerRun } from "../scheduler/contracts.js";
 import type { LocalRuntimePeer } from "./contracts.js";
+import type { LocalPendingToolApproval, LocalToolApprovalDecisionResult } from "./request-approval-contracts.js";
 export type LocalRequestRunOptions = {
     approvalAvailable?: boolean;
+    durableApprovals?: boolean;
     steeringUpdates?: readonly RequestSteeringUpdate[];
 };
 export declare class LocalRequestControls {
@@ -11,14 +15,26 @@ export declare class LocalRequestControls {
     private readonly active;
     private readonly controlPeers;
     private readonly pendingApprovals;
+    private stopped;
     constructor(publish: (event: unknown) => void);
     register(peer: LocalRuntimePeer): Promise<void>;
-    ordinary(requestId: string, peer: LocalRuntimePeer, options: LocalRequestRunOptions): RuntimeRequestOptions;
+    ordinary(requestId: string, peer: LocalRuntimePeer, options: LocalRequestRunOptions, sessionId?: string, resumedWait?: SessionWaitExpectation): RuntimeRequestOptions;
     scheduled(run: SchedulerRun): RuntimeRequestOptions;
     steer(requestId: unknown, update: unknown): unknown;
     finish(requestId: string): void;
+    cancel(requestId: unknown, sessionId: unknown, wait?: unknown): RequestCancellationResult;
+    private matchesResumedWaitCancellation;
+    private claimFinalization;
     stop(): void;
     private open;
+    hasActiveRequest(requestId: unknown, sessionId: unknown): boolean;
+    listApprovals(sessionId?: unknown): LocalPendingToolApproval[];
+    decideApproval(input: unknown, peer: LocalRuntimePeer): LocalToolApprovalDecisionResult;
+    private requiresApprovalRequestAttachment;
+    attach(requestId: unknown, sessionId: unknown, peer: LocalRuntimePeer): Promise<void>;
+    send(requestId: string, event: unknown): void;
+    drain(requestId: string): Promise<void>;
+    private isAttachedApprovalPeer;
+    private getAttachableRequest;
     private approvals;
-    private requestApproval;
 }

package/dist/src/runtime/local-host/app-request-control.js

@@ -1,18 +1,14 @@
+import { createRequestInterruptionError } from "../request/interruption.js";
+import { createRequestCancellationError, } from "../request/cancellation.js";
 import { createRequestSteeringInbox, } from "../request/request-steering.js";
-function readApprovalDecision(value) {
-    if (typeof value !== "object" || value === null)
-        return { approved: false, reason: "Tool approval response was invalid." };
-    const decision = value;
-    return {
-        approved: decision.approved === true,
-        ...(typeof decision.reason === "string" ? { reason: decision.reason } : {}),
-    };
-}
+import { hasApprovalDecisionIdentity, LocalRequestApprovals, } from "./app-request-approvals.js";
+import { LocalRequestDelivery } from "./app-request-delivery.js";
 export class LocalRequestControls {
     publish;
     active = new Map();
     controlPeers = new Map();
-    pendingApprovals = new Set();
+    pendingApprovals = new LocalRequestApprovals();
+    stopped = false;
     constructor(publish) {
         this.publish = publish;
     }
@@ -25,8 +21,8 @@ export class LocalRequestControls {
         // Queue snapshots on the same ordered channel as subsequent run events.
         await Promise.all(runs.map((run) => peer.callClient("scheduled.started", [run])));
     }
-    ordinary(requestId, peer, options) {
-        const steering = this.open(requestId);
+    ordinary(requestId, peer, options, sessionId = "", resumedWait) {
+        const steering = this.open(requestId, sessionId);
         try {
             for (const update of options.steeringUpdates ?? []) {
                 const accepted = steering.append(update);
@@ -38,27 +34,38 @@ export class LocalRequestControls {
             this.finish(requestId);
             throw error;
         }
+        const control = this.active.get(requestId);
+        control.resumedWait = resumedWait;
+        control.peer = peer;
+        control.delivery.attach(peer);
         return {
+            abortSignal: control.abort.signal,
+            claimFinalization: () => this.claimFinalization(control),
             requestSteering: steering,
             ...(options.approvalAvailable
-                ? { toolApprovalController: this.approvals(peer) }
+                ? { toolApprovalController: this.approvals(requestId, control) }
                 : {}),
         };
     }
     scheduled(run) {
-        const steering = this.open(run.requestId, run);
+        const steering = this.open(run.requestId, run.sessionId, run);
+        const control = this.active.get(run.requestId);
         this.publish({ type: "scheduled.started", run });
         const peer = this.controlPeers.values().next().value;
         return {
+            abortSignal: control.abort.signal,
+            claimFinalization: () => this.claimFinalization(control),
             requestSteering: steering,
-            ...(peer ? { toolApprovalController: this.approvals(peer) } : {}),
+            ...(peer
+                ? { toolApprovalController: this.approvals(run.requestId, control) }
+                : {}),
         };
     }
     steer(requestId, update) {
         if (typeof requestId !== "string")
             return { ok: false, reason: "request_not_active" };
         const control = this.active.get(requestId);
-        if (!control)
+        if (!control || control.abort.signal.aborted)
             return { ok: false, reason: "request_not_active" };
         if (!update || typeof update !== "object")
             return { ok: false, reason: "invalid_steer_request" };
@@ -73,63 +80,147 @@ export class LocalRequestControls {
     finish(requestId) {
         const entry = this.active.get(requestId);
         this.active.delete(requestId);
+        this.pendingApprovals.cancel(requestId);
+        entry?.delivery.finish();
         void entry?.steering.close();
     }
+    cancel(requestId, sessionId, wait) {
+        const control = typeof requestId === "string" ? this.active.get(requestId) : undefined;
+        if (!control)
+            return { accepted: false, reason: "request_not_active" };
+        if (typeof sessionId !== "string" ||
+            !sessionId ||
+            sessionId !== control.sessionId)
+            return { accepted: false, reason: "session_mismatch" };
+        if (control.finalizing)
+            return { accepted: false, reason: "request_not_active" };
+        if (!this.matchesResumedWaitCancellation(control, wait))
+            return { accepted: false, reason: "request_not_active" };
+        control.abort.abort(createRequestCancellationError());
+        return { accepted: true };
+    }
+    matchesResumedWaitCancellation(control, input) {
+        if (input === undefined)
+            return true;
+        if (!input || typeof input !== "object")
+            return false;
+        const wait = control.resumedWait;
+        if (!wait)
+            return false;
+        const command = input;
+        if (typeof command.commandId !== "string" || !command.commandId)
+            return false;
+        if (command.generation !== wait.generation)
+            return false;
+        if (command.waitId !== wait.waitId)
+            return false;
+        return command.revision === wait.revision;
+    }
+    claimFinalization(control) {
+        // In-flight requests retain this exact control until canonical finalization.
+        control.abort.signal.throwIfAborted();
+        control.finalizing = true;
+    }
     stop() {
+        this.stopped = true;
         this.controlPeers.clear();
-        for (const cancel of this.pendingApprovals)
-            cancel();
-        // Active canonical requests own their inbox lifetime until finalization.
-        this.active.clear();
+        for (const [requestId, control] of this.active) {
+            control.abort.abort(createRequestInterruptionError());
+        }
+        // Accepted requests retain their controls and inboxes until finalization.
     }
-    open(requestId, run) {
+    open(requestId, sessionId, run) {
+        if (this.stopped)
+            throw new Error("local_runtime_owner_stopped");
         if (!requestId || this.active.has(requestId))
             throw new Error("local_runtime_request_already_active");
         const steering = createRequestSteeringInbox({ requestId });
-        this.active.set(requestId, { steering, ...(run ? { run } : {}) });
+        this.active.set(requestId, {
+            steering,
+            sessionId,
+            abort: new AbortController(),
+            finalizing: false,
+            delivery: new LocalRequestDelivery(requestId),
+            ...(run ? { run } : {}),
+        });
         return steering;
     }
-    approvals(peer) {
-        return {
-            requestToolApproval: (request, options) => this.requestApproval(peer, request, options?.abortSignal),
-        };
+    hasActiveRequest(requestId, sessionId) {
+        if (typeof requestId !== "string")
+            return false;
+        const control = this.active.get(requestId);
+        if (!control)
+            return false;
+        return control.sessionId === sessionId;
     }
-    requestApproval(peer, request, signal) {
-        if (signal?.aborted)
-            return Promise.resolve({
-                approved: false,
-                reason: "Tool approval was cancelled.",
-            });
-        return new Promise((resolve) => {
-            let settled = false;
-            let removeClose = () => { };
-            const complete = (decision) => {
-                if (settled)
-                    return;
-                settled = true;
-                signal?.removeEventListener("abort", cancel);
-                this.pendingApprovals.delete(cancel);
-                removeClose();
-                resolve(decision);
-            };
-            const cancel = () => {
-                void peer
-                    .callClient("request.approval.cancel", [request.approvalId])
-                    .catch(() => undefined);
-                complete({ approved: false, reason: "Tool approval was cancelled." });
-            };
-            this.pendingApprovals.add(cancel);
-            removeClose = peer.onClose(() => complete({
-                approved: false,
-                reason: "Tool approval connection was closed.",
-            }));
-            if (settled)
-                return;
-            signal?.addEventListener("abort", cancel, { once: true });
-            void peer.callClient("request.approval", [request]).then((decision) => complete(readApprovalDecision(decision)), () => complete({
-                approved: false,
-                reason: "Tool approval connection was closed.",
-            }));
+    listApprovals(sessionId) {
+        return this.pendingApprovals.list(sessionId).map((entry) => {
+            const run = this.active.get(entry.request.requestId)?.run;
+            return { ...entry, ...(run ? { run: structuredClone(run) } : {}) };
         });
     }
+    decideApproval(input, peer) {
+        if (!hasApprovalDecisionIdentity(input))
+            return this.pendingApprovals.decide(input);
+        const control = this.active.get(input.requestId);
+        if (this.requiresApprovalRequestAttachment(control, peer))
+            return { accepted: false, reason: "approval_request_not_attached" };
+        return this.pendingApprovals.decide(input);
+    }
+    requiresApprovalRequestAttachment(control, peer) {
+        if (!control)
+            return false;
+        if (control.run)
+            return false;
+        return control.peer !== peer;
+    }
+    async attach(requestId, sessionId, peer) {
+        const control = this.getAttachableRequest(requestId, sessionId);
+        this.pendingApprovals.detach(String(requestId));
+        control.peer = peer;
+        control.delivery.attach(peer);
+        // The readiness acknowledgement permits a decision immediately; bind first.
+        await peer.callClient("request.accepted", [requestId]);
+        if (this.isAttachedApprovalPeer(control, peer))
+            this.pendingApprovals.attach(String(requestId), peer);
+        await control.delivery.finished;
+    }
+    send(requestId, event) {
+        this.active.get(requestId)?.delivery.send(event);
+    }
+    async drain(requestId) {
+        await this.active.get(requestId)?.delivery.drain();
+    }
+    isAttachedApprovalPeer(control, peer) {
+        return control.peer === peer;
+    }
+    getAttachableRequest(requestId, sessionId) {
+        if (typeof requestId !== "string")
+            throw new Error("local_runtime_request_not_awaiting_approval");
+        const control = this.active.get(requestId);
+        if (!control)
+            throw new Error("local_runtime_request_not_awaiting_approval");
+        if (control.sessionId !== sessionId)
+            throw new Error("local_runtime_session_mismatch");
+        if (control.run)
+            throw new Error("local_runtime_request_is_scheduled");
+        if (!this.pendingApprovals.hasPending(requestId))
+            throw new Error("local_runtime_request_not_awaiting_approval");
+        return control;
+    }
+    approvals(requestId, control) {
+        return {
+            requestToolApproval: (request, options) => {
+                if (request.requestId !== requestId)
+                    throw new Error("local_runtime_approval_identity_mismatch");
+                if (this.stopped)
+                    control.abort.abort(createRequestInterruptionError());
+                const signal = options?.abortSignal
+                    ? AbortSignal.any([control.abort.signal, options.abortSignal])
+                    : control.abort.signal;
+                const peer = control.peer ?? this.controlPeers.values().next().value;
+                return this.pendingApprovals.wait(control.sessionId, peer, request, signal);
+            },
+        };
+    }
 }

package/dist/src/runtime/local-host/app-request-delivery.d.ts

@@ -0,0 +1,16 @@
+import type { LocalRuntimePeer } from "./contracts.js";
+/** Replaces a live request subscriber without replaying execution or past events. */
+export declare class LocalRequestDelivery {
+    private readonly requestId;
+    private target?;
+    private delivery;
+    private settle;
+    readonly finished: Promise<void>;
+    constructor(requestId: string);
+    attach(peer: LocalRuntimePeer): void;
+    send(event: unknown): void;
+    drain(): Promise<void>;
+    finish(): void;
+    private isCurrentTarget;
+    private detach;
+}

package/dist/src/runtime/local-host/app-request-delivery.js

@@ -0,0 +1,59 @@
+/** Replaces a live request subscriber without replaying execution or past events. */
+export class LocalRequestDelivery {
+    requestId;
+    target;
+    delivery = Promise.resolve();
+    settle;
+    finished = new Promise((resolve) => {
+        this.settle = resolve;
+    });
+    constructor(requestId) {
+        this.requestId = requestId;
+    }
+    attach(peer) {
+        this.detach();
+        const target = {
+            peer,
+            connected: true,
+            removeClose: () => { },
+        };
+        this.target = target;
+        target.removeClose = peer.onClose(() => {
+            target.connected = false;
+        });
+    }
+    send(event) {
+        const target = this.target;
+        if (!target?.connected)
+            return;
+        this.delivery = this.delivery
+            .then(async () => {
+            if (!this.isCurrentTarget(target))
+                return;
+            await target.peer.callClient("request.event", [this.requestId, event]);
+        })
+            .catch(() => {
+            target.connected = false;
+        });
+    }
+    drain() {
+        return this.delivery;
+    }
+    finish() {
+        this.detach();
+        this.settle();
+    }
+    isCurrentTarget(target) {
+        if (this.target !== target)
+            return false;
+        return target.connected;
+    }
+    detach() {
+        const target = this.target;
+        this.target = undefined;
+        if (!target)
+            return;
+        target.connected = false;
+        target.removeClose();
+    }
+}

package/dist/src/runtime/local-host/client-learning.d.ts

@@ -0,0 +1,10 @@
+import type { LearningChangedEvent, PassiveLearningService } from "../passive-learning/contracts.js";
+import type { LocalRuntimeCallHandler } from "./contracts.js";
+export type PassiveLearningManagement = Pick<PassiveLearningService, "status" | "configure" | "clearPending" | "restartCollection" | "batches" | "batch" | "candidates" | "dismissProposal">;
+/** Read models and invalidations only; collection is never owned by a client. */
+export declare function createLocalLearningClient(call: LocalRuntimeCallHandler): {
+    service: PassiveLearningManagement;
+    subscribe(listener: (event?: LearningChangedEvent) => void): () => void;
+    receive(event: unknown): void;
+    close(): void;
+};

package/dist/src/runtime/local-host/client-learning.js

@@ -0,0 +1,45 @@
+import { projectLearningChangedEvent } from "./learning-events.js";
+/** Read models and invalidations only; collection is never owned by a client. */
+export function createLocalLearningClient(call) {
+    const listeners = new Set();
+    const service = {
+        status: () => call("learning.status", []),
+        configure: (input) => call("learning.configure", [input]),
+        clearPending: () => call("learning.clearPending", []),
+        restartCollection: () => call("learning.restartCollection", []),
+        batches: (input) => call("learning.batches", [input]),
+        batch: (id) => call("learning.batch", [id]),
+        candidates: () => call("learning.candidates", []),
+        dismissProposal: (id) => call("learning.dismissProposal", [id]),
+    };
+    return {
+        service,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        receive(event) {
+            if (!event || typeof event !== "object")
+                return;
+            if (!("type" in event) || event.type !== "learning.changed")
+                return;
+            const change = projectLearningChangedEvent("event" in event ? event.event : undefined);
+            for (const listener of listeners) {
+                try {
+                    if (change)
+                        listener(change);
+                    else
+                        listener();
+                }
+                catch {
+                    /* Views do not own committed state. */
+                }
+            }
+        },
+        close() {
+            listeners.clear();
+        },
+    };
+}

package/dist/src/runtime/local-host/client-requests.d.ts

@@ -1,19 +1,31 @@
 import type { RuntimeRequestHandler, RuntimeRequestOptions } from "../composition.js";
 import type { SchedulerRun } from "../scheduler/contracts.js";
 import type { LocalRuntimeCallHandler } from "./contracts.js";
+import type { LocalPendingToolApproval, LocalToolApprovalDecisionInput, LocalToolApprovalDecisionResult } from "./request-approval-contracts.js";
 /** Client projections only. The owner validates and commits every steering update. */
 export declare class LocalRuntimeClientRequests {
     private readonly call;
     private readonly scheduledOptions?;
+    private readonly approvalCall;
     private readonly active;
-    private readonly approvals;
+    private readonly approvalCallbacks;
     private readonly listeners;
-    constructor(call: LocalRuntimeCallHandler, scheduledOptions?: ((run: SchedulerRun) => RuntimeRequestOptions) | undefined);
+    constructor(call: LocalRuntimeCallHandler, scheduledOptions?: ((run: SchedulerRun) => RuntimeRequestOptions) | undefined, approvalCall?: LocalRuntimeCallHandler);
     readonly requests: RuntimeRequestHandler;
+    readonly approvals: {
+        list: (sessionId?: string) => Promise<LocalPendingToolApproval[]>;
+        decide: (input: LocalToolApprovalDecisionInput) => Promise<LocalToolApprovalDecisionResult>;
+        attach: (requestId: string, sessionId: string, ws: Parameters<RuntimeRequestHandler["handle"]>[0], options?: RuntimeRequestOptions, onAccepted?: () => void) => Promise<void>;
+    };
     subscribe(listener: (event: Record<string, unknown>) => void): () => void;
     receive(event: unknown): void;
     handleCallback(method: string, args: readonly unknown[]): Promise<unknown>;
     close(disconnected?: boolean): void;
     private open;
+    private restoreCancellationDelivery;
+    private restoreApprovalDelivery;
+    private attachRequest;
+    private trackOwnerRequest;
+    private publishDisconnectedScheduledRequest;
     private publish;
 }