@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/runtime/local-host/app-memory-dispatch.js

@@ -0,0 +1,103 @@
+const MEMORY_METHODS = [
+    "status",
+    "list",
+    "search",
+    "create",
+    "update",
+    "delete",
+    "clear",
+    "retrieve",
+    "processCandidates",
+    "scheduleCandidates",
+];
+const CONTEXT_METHODS = [
+    "search",
+    "create",
+    "update",
+    "retrieve",
+    "processCandidates",
+    "scheduleCandidates",
+];
+function readOperationId(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const operationId = value.operationId;
+    return typeof operationId === "string" && operationId
+        ? operationId
+        : undefined;
+}
+function isQueuedOperationCancelled(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return value.cancelled === true;
+}
+export class LocalMemoryDispatcher {
+    memory;
+    active = new Map();
+    constructor(memory) {
+        this.memory = memory;
+    }
+    async call(method, args, peer) {
+        const operation = method.slice("memory.".length);
+        if (operation === "cancel")
+            return this.cancel(args[0], peer.id);
+        if (!MEMORY_METHODS.includes(operation))
+            throw new Error("local_runtime_method_unknown");
+        const operationId = readOperationId(args.at(-1));
+        if (isQueuedOperationCancelled(args.at(-1)))
+            throw new Error("local_runtime_operation_cancelled");
+        const inputArgs = operationId ? args.slice(0, -1) : [...args];
+        if (operationId && this.active.has(operationId))
+            throw new Error("local_runtime_operation_already_active");
+        const controller = new AbortController();
+        const removeClose = peer.onClose(() => controller.abort());
+        if (operationId)
+            this.active.set(operationId, { peerId: peer.id, controller });
+        const callArgs = this.bindContext(operation, inputArgs, peer, controller.signal, operationId);
+        try {
+            const invoke = this.memory[operation];
+            return await invoke.apply(this.memory, callArgs);
+        }
+        finally {
+            removeClose();
+            if (operationId)
+                this.active.delete(operationId);
+        }
+    }
+    stop() {
+        for (const operation of this.active.values())
+            operation.controller.abort();
+        this.active.clear();
+    }
+    cancel(operationId, peerId) {
+        if (typeof operationId !== "string")
+            return false;
+        const operation = this.active.get(operationId);
+        if (!operation || operation.peerId !== peerId)
+            return false;
+        operation.controller.abort();
+        return true;
+    }
+    bindContext(operation, args, peer, abortSignal, operationId) {
+        if (!CONTEXT_METHODS.includes(operation))
+            return [...args];
+        const input = args[0];
+        if (!input || typeof input !== "object")
+            throw new Error("local_runtime_memory_input_invalid");
+        return [
+            {
+                ...input,
+                context: {
+                    ...input.context,
+                    abortSignal,
+                    onEvent: (name, extra) => {
+                        void peer
+                            .callClient("memory.event", [operationId, name, extra])
+                            .catch(() => undefined);
+                    },
+                },
+            },
+            ...args.slice(1),
+        ];
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type RuntimeDependencyOverrides } from "../composition.js";
+import type { RuntimeConfig } from "../ports.js";
+import type { LocalRuntimeOwner } from "./contracts.js";
+export declare function createLocalRuntimeOwner(config: RuntimeConfig, overrides?: RuntimeDependencyOverrides): Promise<LocalRuntimeOwner>;

package/dist/src/runtime/local-host/app-owner.js

@@ -0,0 +1,119 @@
+import { createRuntimeApplication, } from "../composition.js";
+import { LocalMemoryDispatcher } from "./app-memory-dispatch.js";
+import { LocalRequestControls, } from "./app-request-control.js";
+import { dispatchLocalServiceCall } from "./app-service-dispatch.js";
+import { LocalRuntimeOwnerActivity } from "./owner-activity.js";
+export async function createLocalRuntimeOwner(config, overrides = {}) {
+    const listeners = new Set();
+    const publish = (event) => {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                /* A subscribing view cannot change canonical request execution. */
+            }
+        }
+    };
+    const controls = new LocalRequestControls(publish);
+    const activity = new LocalRuntimeOwnerActivity();
+    const application = createRuntimeApplication(config, {
+        ...overrides,
+        scheduledRequestOptions: (run) => controls.scheduled(run),
+    });
+    const memory = new LocalMemoryDispatcher(application.services.longTermMemory);
+    const unsubscribe = application.subscribeScheduledEvents((event) => {
+        publish({ type: "scheduled.event", event });
+        if (event.type === "completed" || event.type === "failed")
+            controls.finish(String(event.requestId));
+    });
+    try {
+        await application.start();
+    }
+    catch (error) {
+        activity.stop();
+        application.services.requestAdmission?.close();
+        unsubscribe();
+        await application.stop();
+        throw error;
+    }
+    let shutdown;
+    return {
+        call(method, args, peer) {
+            return activity.run(async () => {
+                if (method === "controls.register")
+                    return controls.register(peer);
+                if (method === "request.steer")
+                    return controls.steer(args[0], args[1]);
+                if (method === "request.run")
+                    return runPeerRequest(application, controls, activity, args, peer);
+                if (method.startsWith("memory."))
+                    return memory.call(method, args, peer);
+                return dispatchLocalServiceCall(application.services, method, args);
+            });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        stop() {
+            if (shutdown)
+                return shutdown;
+            activity.stop();
+            application.services.requestAdmission?.close();
+            memory.stop();
+            controls.stop();
+            unsubscribe();
+            listeners.clear();
+            shutdown = application.stop();
+            return shutdown;
+        },
+        isIdle() {
+            if (!activity.isIdle())
+                return false;
+            return application.services.requestAdmission?.isIdle() ?? true;
+        },
+        async whenIdle() {
+            await Promise.all([
+                activity.whenIdle(),
+                application.services.requestAdmission?.whenIdle(),
+            ]);
+        },
+    };
+}
+async function runPeerRequest(application, controls, activity, args, peer) {
+    const message = args[0];
+    if (!message || typeof message.requestId !== "string")
+        throw new Error("local_runtime_request_invalid");
+    const options = controls.ordinary(message.requestId, peer, (args[1] ?? {}));
+    let connected = true;
+    const removeClose = peer.onClose(() => {
+        connected = false;
+    });
+    let delivery = Promise.resolve();
+    const socket = {
+        send(data) {
+            if (!connected)
+                return;
+            const event = JSON.parse(data);
+            delivery = delivery
+                .then(async () => {
+                if (connected)
+                    await peer.callClient("request.event", [message.requestId, event]);
+            })
+                .catch(() => {
+                connected = false;
+            });
+        },
+    };
+    try {
+        await peer.callClient("request.accepted", [message.requestId]);
+        activity.assertAcceptingRequests();
+        await application.requests.handle(socket, message, options);
+        await delivery;
+    }
+    finally {
+        removeClose();
+        controls.finish(message.requestId);
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { RuntimeRequestOptions } from "../composition.js";
+import { type RequestSteeringUpdate } from "../request/request-steering.js";
+import type { SchedulerRun } from "../scheduler/contracts.js";
+import type { LocalRuntimePeer } from "./contracts.js";
+export type LocalRequestRunOptions = {
+    approvalAvailable?: boolean;
+    steeringUpdates?: readonly RequestSteeringUpdate[];
+};
+export declare class LocalRequestControls {
+    private readonly publish;
+    private readonly active;
+    private readonly controlPeers;
+    private readonly pendingApprovals;
+    constructor(publish: (event: unknown) => void);
+    register(peer: LocalRuntimePeer): Promise<void>;
+    ordinary(requestId: string, peer: LocalRuntimePeer, options: LocalRequestRunOptions): RuntimeRequestOptions;
+    scheduled(run: SchedulerRun): RuntimeRequestOptions;
+    steer(requestId: unknown, update: unknown): unknown;
+    finish(requestId: string): void;
+    stop(): void;
+    private open;
+    private approvals;
+    private requestApproval;
+}

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

@@ -0,0 +1,135 @@
+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 } : {}),
+    };
+}
+export class LocalRequestControls {
+    publish;
+    active = new Map();
+    controlPeers = new Map();
+    pendingApprovals = new Set();
+    constructor(publish) {
+        this.publish = publish;
+    }
+    async register(peer) {
+        if (!this.controlPeers.has(peer.id)) {
+            this.controlPeers.set(peer.id, peer);
+            peer.onClose(() => this.controlPeers.delete(peer.id));
+        }
+        const runs = [...this.active.values()].flatMap((entry) => entry.run ? [entry.run] : []);
+        // 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);
+        try {
+            for (const update of options.steeringUpdates ?? []) {
+                const accepted = steering.append(update);
+                if (!accepted.ok)
+                    throw new Error(accepted.reason);
+            }
+        }
+        catch (error) {
+            this.finish(requestId);
+            throw error;
+        }
+        return {
+            requestSteering: steering,
+            ...(options.approvalAvailable
+                ? { toolApprovalController: this.approvals(peer) }
+                : {}),
+        };
+    }
+    scheduled(run) {
+        const steering = this.open(run.requestId, run);
+        this.publish({ type: "scheduled.started", run });
+        const peer = this.controlPeers.values().next().value;
+        return {
+            requestSteering: steering,
+            ...(peer ? { toolApprovalController: this.approvals(peer) } : {}),
+        };
+    }
+    steer(requestId, update) {
+        if (typeof requestId !== "string")
+            return { ok: false, reason: "request_not_active" };
+        const control = this.active.get(requestId);
+        if (!control)
+            return { ok: false, reason: "request_not_active" };
+        if (!update || typeof update !== "object")
+            return { ok: false, reason: "invalid_steer_request" };
+        const input = update;
+        if (typeof input.steerId !== "string" || typeof input.text !== "string")
+            return { ok: false, reason: "invalid_steer_request" };
+        return control.steering.append({
+            steerId: input.steerId,
+            text: input.text,
+        });
+    }
+    finish(requestId) {
+        const entry = this.active.get(requestId);
+        this.active.delete(requestId);
+        void entry?.steering.close();
+    }
+    stop() {
+        this.controlPeers.clear();
+        for (const cancel of this.pendingApprovals)
+            cancel();
+        // Active canonical requests own their inbox lifetime until finalization.
+        this.active.clear();
+    }
+    open(requestId, run) {
+        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 } : {}) });
+        return steering;
+    }
+    approvals(peer) {
+        return {
+            requestToolApproval: (request, options) => this.requestApproval(peer, request, options?.abortSignal),
+        };
+    }
+    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.",
+            }));
+        });
+    }
+}

package/dist/src/runtime/local-host/app-service-dispatch.d.ts

@@ -0,0 +1,5 @@
+import type { RuntimeEnvironmentServices } from "../composition.js";
+export declare const LOCAL_SESSION_METHODS: readonly ["getOrCreateSession", "getAllSessions", "listSessions", "getSessionById", "getSessionSnapshot", "getRequestReplayById", "updateSessionTitle", "updateSessionRuntimeMode", "appendMessage", "appendContextEntry", "upsertArtifactPaths", "startRequestStream", "appendRequestEvent", "deleteSession", "deleteSessionWithStats", "resetSession", "clearSessionMessages", "deleteMessage", "deleteMessageWithStats", "compareAndSwapSessionMemoryCheckpoint"];
+export declare const LOCAL_ATTACHMENT_METHODS: readonly ["saveAttachment", "validateAttachmentReferences", "resolveAttachment", "deleteAttachment", "deleteSessionAttachments"];
+export declare const LOCAL_SCHEDULER_METHODS: readonly ["tick", "create", "list", "get", "update", "pause", "resume", "cancel", "runNow", "deleteSession", "listRuns"];
+export declare function dispatchLocalServiceCall(services: RuntimeEnvironmentServices, method: string, args: readonly unknown[]): Promise<unknown>;

package/dist/src/runtime/local-host/app-service-dispatch.js

@@ -0,0 +1,64 @@
+export const LOCAL_SESSION_METHODS = [
+    "getOrCreateSession",
+    "getAllSessions",
+    "listSessions",
+    "getSessionById",
+    "getSessionSnapshot",
+    "getRequestReplayById",
+    "updateSessionTitle",
+    "updateSessionRuntimeMode",
+    "appendMessage",
+    "appendContextEntry",
+    "upsertArtifactPaths",
+    "startRequestStream",
+    "appendRequestEvent",
+    "deleteSession",
+    "deleteSessionWithStats",
+    "resetSession",
+    "clearSessionMessages",
+    "deleteMessage",
+    "deleteMessageWithStats",
+    "compareAndSwapSessionMemoryCheckpoint",
+];
+export const LOCAL_ATTACHMENT_METHODS = [
+    "saveAttachment",
+    "validateAttachmentReferences",
+    "resolveAttachment",
+    "deleteAttachment",
+    "deleteSessionAttachments",
+];
+export const LOCAL_SCHEDULER_METHODS = [
+    "tick",
+    "create",
+    "list",
+    "get",
+    "update",
+    "pause",
+    "resume",
+    "cancel",
+    "runNow",
+    "deleteSession",
+    "listRuns",
+];
+function selectServiceMethod(target, method, methods) {
+    if (!methods.includes(method))
+        throw new Error("local_runtime_method_unknown");
+    if (!target)
+        throw new Error("local_runtime_service_unavailable");
+    const selected = target[method];
+    if (typeof selected !== "function")
+        throw new Error("local_runtime_method_unavailable");
+    return selected.bind(target);
+}
+export async function dispatchLocalServiceCall(services, method, args) {
+    const [service, operation, extra] = method.split(".");
+    if (!operation || extra)
+        throw new Error("local_runtime_method_unknown");
+    if (service === "sessions")
+        return selectServiceMethod(services.sessions, operation, LOCAL_SESSION_METHODS)(...args);
+    if (service === "attachments")
+        return selectServiceMethod(services.attachments, operation, LOCAL_ATTACHMENT_METHODS)(...args);
+    if (service === "scheduler")
+        return selectServiceMethod(services.scheduler, operation, LOCAL_SCHEDULER_METHODS)(...args);
+    throw new Error("local_runtime_method_unknown");
+}

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

@@ -0,0 +1,3 @@
+import type { RuntimeConfig } from "../ports.js";
+/** Rejects attaching a caller whose resolved execution configuration differs. */
+export declare function resolveLocalRuntimeIdentity(config: RuntimeConfig): string;

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

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+/** Rejects attaching a caller whose resolved execution configuration differs. */
+export function resolveLocalRuntimeIdentity(config) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalConfigValue(config)))
+        .digest("hex");
+}
+function canonicalConfigValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalConfigValue);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, canonicalConfigValue(entry)]));
+}

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

@@ -0,0 +1,7 @@
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+import type { LocalRuntimeCallHandler } from "./contracts.js";
+/** Moves cancellation and callbacks explicitly; executable values never cross IPC. */
+export declare function createLocalMemoryClient(call: LocalRuntimeCallHandler, enabled: boolean): {
+    service: LongTermMemoryService;
+    handleEvent(args: readonly unknown[]): void;
+};

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

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+/** Moves cancellation and callbacks explicitly; executable values never cross IPC. */
+export function createLocalMemoryClient(call, enabled) {
+    const eventListeners = new Map();
+    async function invoke(method, input) {
+        const operationId = randomUUID();
+        const operation = { operationId, cancelled: false };
+        const record = input;
+        const context = record?.context;
+        if (context?.abortSignal?.aborted)
+            throw context.abortSignal.reason;
+        const { abortSignal, onEvent, ...serializableContext } = context ?? {};
+        const argument = context
+            ? { ...record, context: serializableContext }
+            : input;
+        if (onEvent)
+            eventListeners.set(operationId, onEvent);
+        const abort = () => {
+            operation.cancelled = true;
+            void call("memory.cancel", [operationId]).catch(() => undefined);
+        };
+        abortSignal?.addEventListener("abort", abort, { once: true });
+        try {
+            return await call(`memory.${method}`, [argument, operation]);
+        }
+        finally {
+            abortSignal?.removeEventListener("abort", abort);
+            eventListeners.delete(operationId);
+        }
+    }
+    const service = {
+        enabled,
+        status: () => invoke("status"),
+        list: (input) => invoke("list", input),
+        search: (input) => invoke("search", input),
+        create: (input) => invoke("create", input),
+        update: (input) => invoke("update", input),
+        delete: (input) => invoke("delete", input),
+        clear: () => invoke("clear"),
+        retrieve: (input) => invoke("retrieve", input),
+        processCandidates: (input) => invoke("processCandidates", input),
+        scheduleCandidates: (input) => {
+            void invoke("scheduleCandidates", input).catch((error) => {
+                console.error("Local runtime memory scheduling failed:", error);
+            });
+        },
+    };
+    return {
+        service,
+        handleEvent(args) {
+            eventListeners.get(String(args[0]))?.(String(args[1]), args[2]);
+        },
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { RuntimeRequestHandler, RuntimeRequestOptions } from "../composition.js";
+import type { SchedulerRun } from "../scheduler/contracts.js";
+import type { LocalRuntimeCallHandler } from "./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 active;
+    private readonly approvals;
+    private readonly listeners;
+    constructor(call: LocalRuntimeCallHandler, scheduledOptions?: ((run: SchedulerRun) => RuntimeRequestOptions) | undefined);
+    readonly requests: RuntimeRequestHandler;
+    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 publish;
+}