@abot-ai/runtime 1.2.0 → 1.3.0

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

@@ -0,0 +1,145 @@
+/** Client projections only. The owner validates and commits every steering update. */
+export class LocalRuntimeClientRequests {
+    call;
+    scheduledOptions;
+    active = new Map();
+    approvals = new Map();
+    listeners = new Set();
+    constructor(call, scheduledOptions) {
+        this.call = call;
+        this.scheduledOptions = scheduledOptions;
+    }
+    requests = {
+        handle: async (ws, message, options = {}) => {
+            const requestId = String(message.requestId ?? "");
+            if (this.active.has(requestId))
+                throw new Error("local_runtime_request_already_active");
+            const state = this.open(requestId, options, (event) => ws.send(JSON.stringify(event)));
+            try {
+                await this.call("request.run", [
+                    message,
+                    {
+                        approvalAvailable: Boolean(options.toolApprovalController),
+                        steeringUpdates: options.requestSteering?.snapshot().updates ?? [],
+                    },
+                ]);
+            }
+            finally {
+                state.accept();
+                this.active.delete(requestId);
+            }
+        },
+        steer: async (requestId, input) => {
+            await this.active.get(requestId)?.accepted;
+            return (await this.call("request.steer", [
+                requestId,
+                input,
+            ]));
+        },
+    };
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    receive(event) {
+        if (!event || typeof event !== "object")
+            return;
+        const envelope = event;
+        if (envelope.type === "scheduled.started") {
+            const run = envelope.run;
+            if (this.active.has(run.requestId))
+                return;
+            const state = this.open(run.requestId, this.scheduledOptions?.(run) ?? {});
+            state.run = run;
+            state.accept();
+            return;
+        }
+        if (envelope.type !== "scheduled.event")
+            return;
+        const payload = envelope.event;
+        this.publish(payload);
+        if (payload.type === "completed" || payload.type === "failed") {
+            this.active.delete(String(payload.requestId));
+        }
+    }
+    async handleCallback(method, args) {
+        if (method === "scheduled.started") {
+            this.receive({ type: "scheduled.started", run: args[0] });
+            return null;
+        }
+        if (method === "request.accepted") {
+            this.active.get(String(args[0]))?.accept();
+            return null;
+        }
+        if (method === "request.event") {
+            this.active
+                .get(String(args[0]))
+                ?.send?.(args[1]);
+            return null;
+        }
+        if (method === "request.approval.cancel") {
+            this.approvals.get(String(args[0]))?.abort();
+            return null;
+        }
+        if (method !== "request.approval")
+            throw new Error("local_runtime_callback_unknown");
+        const request = args[0];
+        const approval = this.active.get(request.requestId)?.options
+            .toolApprovalController;
+        if (!approval)
+            return { approved: false, reason: "Tool approval is unavailable." };
+        const controller = new AbortController();
+        this.approvals.set(request.approvalId, controller);
+        try {
+            return await approval.requestToolApproval(request, {
+                abortSignal: controller.signal,
+            });
+        }
+        finally {
+            this.approvals.delete(request.approvalId);
+        }
+    }
+    close(disconnected = false) {
+        if (disconnected) {
+            for (const [requestId, state] of this.active) {
+                if (!state.run)
+                    continue;
+                this.publish({
+                    type: "failed",
+                    requestId,
+                    sessionId: state.run.sessionId,
+                    environment: state.run.environmentId,
+                    error: "local_runtime_disconnected_outcome_unknown",
+                });
+            }
+        }
+        for (const controller of this.approvals.values())
+            controller.abort();
+        for (const state of this.active.values())
+            state.accept();
+        this.active.clear();
+        this.approvals.clear();
+        this.listeners.clear();
+    }
+    open(requestId, options, send) {
+        let accept;
+        const accepted = new Promise((resolve) => {
+            accept = resolve;
+        });
+        const state = { options, send, accept, accepted };
+        this.active.set(requestId, state);
+        return state;
+    }
+    publish(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A client view cannot prevent request or approval cleanup.
+            }
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { SessionStore } from "../ports.js";
+import type { RuntimeAttachmentStore } from "../attachments/store.js";
+import type { SchedulerService } from "../scheduler/contracts.js";
+import type { LocalRuntimeCallHandler } from "./contracts.js";
+/** Projections of owner APIs; lifecycle remains with the managed application. */
+export declare function createLocalServiceClients(call: LocalRuntimeCallHandler): {
+    sessions: SessionStore;
+    attachments: RuntimeAttachmentStore;
+    scheduler: Omit<SchedulerService, "stop" | "start">;
+};

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

@@ -0,0 +1,14 @@
+import { bindManagedSessionAttachmentDeletion } from "../session/session-attachment-deletion.js";
+import { LOCAL_SESSION_METHODS, LOCAL_ATTACHMENT_METHODS, LOCAL_SCHEDULER_METHODS, } from "./app-service-dispatch.js";
+/** Projections of owner APIs; lifecycle remains with the managed application. */
+export function createLocalServiceClients(call) {
+    const service = (prefix, methods) => Object.fromEntries(methods.map((method) => [
+        method,
+        (...args) => call(`${prefix}.${method}`, args),
+    ]));
+    const sessions = service("sessions", LOCAL_SESSION_METHODS);
+    const attachments = service("attachments", LOCAL_ATTACHMENT_METHODS);
+    const scheduler = service("scheduler", LOCAL_SCHEDULER_METHODS);
+    bindManagedSessionAttachmentDeletion(sessions, attachments);
+    return { sessions, attachments, scheduler };
+}

package/dist/src/runtime/local-host/contracts.d.ts

@@ -0,0 +1,36 @@
+export type LocalRuntimeCallHandler = (method: string, args: readonly unknown[]) => Promise<unknown>;
+export type LocalRuntimePeer = Readonly<{
+    id: string;
+    callClient: LocalRuntimeCallHandler;
+    onClose: (listener: () => void) => () => void;
+}>;
+export type LocalRuntimeOwner = Readonly<{
+    call: (method: string, args: readonly unknown[], peer: LocalRuntimePeer) => Promise<unknown>;
+    subscribe: (listener: (event: unknown) => void) => () => void;
+    stop: () => Promise<void>;
+    /** Synchronous activity snapshot; stable after stop has closed intake. */
+    isIdle?: () => boolean;
+    /** Settles only after stopped-owner execution and persistence have finished. */
+    whenIdle?: () => Promise<void>;
+}>;
+export type LocalRuntimeConnection = Readonly<{
+    ownership: "owner" | "client";
+    call: (method: string, args?: readonly unknown[]) => Promise<unknown>;
+    subscribe: (listener: (event: unknown) => void) => () => void;
+    setClientHandler: (handler: LocalRuntimeCallHandler) => void;
+    onClose: (listener: () => void) => () => void;
+    close: () => Promise<void>;
+}>;
+export type LocalRuntimeConnectionOptions = Readonly<{
+    directory: string;
+    identity: string;
+    createOwner: () => Promise<LocalRuntimeOwner>;
+    startupTimeoutMs?: number;
+}>;
+export type LocalRuntimeEndpoint = Readonly<{
+    version: 1;
+    identity: string;
+    pid: number;
+    port: number;
+    token: string;
+}>;

package/dist/src/runtime/local-host/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/src/runtime/local-host/endpoint.d.ts

@@ -0,0 +1,7 @@
+import type { LocalRuntimeEndpoint } from "./contracts.js";
+export declare function localRuntimeEndpointPath(directory: string): string;
+export { ensurePrivateRuntimeDirectory } from "./private-directory.js";
+export declare function readLocalRuntimeEndpoint(directory: string): Promise<LocalRuntimeEndpoint | undefined>;
+export declare function writeLocalRuntimeEndpoint(directory: string, endpoint: LocalRuntimeEndpoint): Promise<void>;
+export declare function removeLocalRuntimeEndpoint(directory: string, token: string): Promise<void>;
+export declare function isLocalRuntimeProcessAlive(pid: number): boolean;

package/dist/src/runtime/local-host/endpoint.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { lstat, open, readFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { assertPrivateRuntimeAccess } from "./private-access.js";
+export function localRuntimeEndpointPath(directory) {
+    return join(directory, "endpoint.json");
+}
+export { ensurePrivateRuntimeDirectory } from "./private-directory.js";
+export async function readLocalRuntimeEndpoint(directory) {
+    const path = localRuntimeEndpointPath(directory);
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error("local_runtime_endpoint_not_private");
+        await assertPrivateRuntimeAccess(path, stat, "local_runtime_endpoint_not_private");
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (!isLocalRuntimeEndpoint(value))
+            throw new Error("local_runtime_invalid_endpoint");
+        return value;
+    }
+    catch (error) {
+        if (hasFileErrorCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+}
+export async function writeLocalRuntimeEndpoint(directory, endpoint) {
+    const path = localRuntimeEndpointPath(directory);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(endpoint), "utf8");
+        await handle.sync();
+        await handle.close();
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function removeLocalRuntimeEndpoint(directory, token) {
+    const endpoint = await readLocalRuntimeEndpoint(directory);
+    if (endpoint?.token !== token)
+        return;
+    await rm(localRuntimeEndpointPath(directory), { force: true });
+}
+export function isLocalRuntimeProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !hasFileErrorCode(error, "ESRCH");
+    }
+}
+function isLocalRuntimeEndpoint(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const endpoint = value;
+    if (endpoint.version !== 1)
+        return false;
+    if (typeof endpoint.identity !== "string" || !endpoint.identity)
+        return false;
+    if (!isPositiveInteger(endpoint.pid))
+        return false;
+    if (!isPositiveInteger(endpoint.port) || endpoint.port > 65_535)
+        return false;
+    return (typeof endpoint.token === "string" && /^[a-f0-9]{64}$/.test(endpoint.token));
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function hasFileErrorCode(error, code) {
+    if (!error || typeof error !== "object" || !("code" in error))
+        return false;
+    return error.code === code;
+}

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

@@ -0,0 +1,10 @@
+/** Keeps accepted RPC effects under the owner's lease until they settle. */
+export declare class LocalRuntimeOwnerActivity {
+    private readonly active;
+    private stopped;
+    assertAcceptingRequests(): void;
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    stop(): void;
+    isIdle(): boolean;
+    whenIdle(): Promise<void>;
+}

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

@@ -0,0 +1,30 @@
+/** Keeps accepted RPC effects under the owner's lease until they settle. */
+export class LocalRuntimeOwnerActivity {
+    active = new Set();
+    stopped = false;
+    assertAcceptingRequests() {
+        if (this.stopped)
+            throw new Error("local_runtime_owner_stopped");
+    }
+    async run(operation) {
+        this.assertAcceptingRequests();
+        const pending = operation();
+        this.active.add(pending);
+        try {
+            return await pending;
+        }
+        finally {
+            this.active.delete(pending);
+        }
+    }
+    stop() {
+        this.stopped = true;
+    }
+    isIdle() {
+        return this.active.size === 0;
+    }
+    async whenIdle() {
+        // stop closes intake synchronously before the transport asks for this fence.
+        await Promise.allSettled([...this.active]);
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { LocalRuntimeOwner } from "./contracts.js";
+/** Releasing a live owner's lease is separate from closing client transport. */
+export declare function releaseRuntimeOwnerWhenIdle(owner: LocalRuntimeOwner | undefined, release: () => Promise<void>): Promise<void>;

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

@@ -0,0 +1,15 @@
+/** Releasing a live owner's lease is separate from closing client transport. */
+export function releaseRuntimeOwnerWhenIdle(owner, release) {
+    if (!owner?.whenIdle)
+        return release();
+    const alreadyIdle = owner.isIdle?.() === true;
+    const retirement = owner.whenIdle().then(release);
+    if (alreadyIdle)
+        return retirement;
+    void retirement.catch((error) => {
+        // Fail closed: uncertainty must never admit a second environment writer.
+        // A true process exit still permits the normal abandoned-PID recovery.
+        console.error("Local runtime owner retirement failed:", error);
+    });
+    return Promise.resolve();
+}

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

@@ -0,0 +1,6 @@
+import type { LocalRuntimeEndpoint, LocalRuntimeOwner } from "./contracts.js";
+export declare function localRuntimeIdentityHeader(identity: string): string;
+export declare function startLocalRuntimeOwnerServer(identity: string, owner: LocalRuntimeOwner): Promise<{
+    endpoint: LocalRuntimeEndpoint;
+    close: () => Promise<void>;
+}>;

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

@@ -0,0 +1,88 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+import { closeHttpServerImmediately } from "../../shared/http-server-shutdown.js";
+import { LocalRuntimeRpcPeer } from "./rpc-peer.js";
+export function localRuntimeIdentityHeader(identity) {
+    return createHash("sha256").update(identity).digest("hex");
+}
+export async function startLocalRuntimeOwnerServer(identity, owner) {
+    const token = randomBytes(32).toString("hex");
+    const expectedIdentity = localRuntimeIdentityHeader(identity);
+    const peers = new Set();
+    const server = createServer((_request, response) => {
+        response.writeHead(404).end();
+    });
+    const sockets = new WebSocketServer({
+        server,
+        maxPayload: 64 * 1024 * 1024,
+        perMessageDeflate: false,
+        verifyClient: ({ req }) => isAuthenticatedLocalClient(req, token, expectedIdentity),
+    });
+    sockets.on("connection", (socket) => {
+        const rpc = new LocalRuntimeRpcPeer(socket);
+        const peer = Object.freeze({
+            id: rpc.id,
+            callClient: (method, args) => rpc.call(method, args),
+            onClose: (listener) => rpc.onClose(listener),
+        });
+        rpc.setHandler((method, args) => owner.call(method, args, peer));
+        peers.add(rpc);
+        rpc.onClose(() => {
+            peers.delete(rpc);
+        });
+    });
+    const unsubscribe = owner.subscribe((event) => {
+        for (const peer of peers)
+            peer.publish(event);
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", () => {
+                server.removeListener("error", reject);
+                resolve();
+            });
+        });
+    }
+    catch (error) {
+        unsubscribe();
+        sockets.close();
+        throw error;
+    }
+    const endpoint = {
+        version: 1,
+        identity,
+        pid: process.pid,
+        port: server.address().port,
+        token,
+    };
+    let shutdown;
+    return {
+        endpoint,
+        close: () => {
+            shutdown ??= closeOwner();
+            return shutdown;
+        },
+    };
+    async function closeOwner() {
+        unsubscribe();
+        const serverClosed = closeHttpServerImmediately(server, sockets);
+        for (const peer of peers)
+            peer.close();
+        await Promise.all([owner.stop(), serverClosed]);
+    }
+}
+function isAuthenticatedLocalClient(request, token, identity) {
+    if (request.socket.remoteAddress !== "127.0.0.1")
+        return false;
+    if (request.headers["x-abot-runtime-identity"] !== identity)
+        return false;
+    const authorization = request.headers.authorization ?? "";
+    const expected = `Bearer ${token}`;
+    const observedBytes = Buffer.from(authorization);
+    const expectedBytes = Buffer.from(expected);
+    if (observedBytes.length !== expectedBytes.length)
+        return false;
+    return timingSafeEqual(observedBytes, expectedBytes);
+}

package/dist/src/runtime/local-host/private-access.d.ts

@@ -0,0 +1,2 @@
+import type { Stats } from "node:fs";
+export declare function assertPrivateRuntimeAccess(path: string, stat: Stats, errorCode: string, newlyCreatedDirectory?: boolean): Promise<void>;

package/dist/src/runtime/local-host/private-access.js

@@ -0,0 +1,16 @@
+import { verifyWindowsPrivateAccess } from "./windows-private-access.js";
+export async function assertPrivateRuntimeAccess(path, stat, errorCode, newlyCreatedDirectory = false) {
+    if (process.platform === "win32") {
+        try {
+            await verifyWindowsPrivateAccess(path, newlyCreatedDirectory);
+            return;
+        }
+        catch {
+            throw new Error(errorCode);
+        }
+    }
+    if ((stat.mode & 0o077) !== 0)
+        throw new Error(errorCode);
+    if (process.getuid?.() !== stat.uid)
+        throw new Error(errorCode);
+}

package/dist/src/runtime/local-host/private-directory.d.ts

@@ -0,0 +1 @@
+export declare function ensurePrivateRuntimeDirectory(directory: string): Promise<void>;

package/dist/src/runtime/local-host/private-directory.js

@@ -0,0 +1,57 @@
+import { lstat, mkdir, mkdtemp, rename, rmdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { assertPrivateRuntimeAccess } from "./private-access.js";
+import { verifyWindowsPrivateAccess } from "./windows-private-access.js";
+export async function ensurePrivateRuntimeDirectory(directory) {
+    if (process.platform === "win32")
+        await installWindowsPrivateDirectory(directory);
+    else
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("local_runtime_directory_not_private");
+    await assertPrivateRuntimeAccess(directory, stat, "local_runtime_directory_not_private");
+}
+async function installWindowsPrivateDirectory(directory) {
+    if (await hasExistingPath(directory))
+        return;
+    const parent = dirname(directory);
+    await mkdir(parent, { recursive: true });
+    const temporary = await mkdtemp(join(parent, `.${basename(directory)}.private-`));
+    try {
+        await verifyWindowsPrivateAccess(temporary, true);
+        try {
+            await rename(temporary, directory);
+        }
+        catch (error) {
+            if (!(await hasExistingPath(directory)))
+                throw error;
+            // A concurrent creator won; the caller verifies its installed ACL below.
+        }
+    }
+    catch {
+        throw new Error("local_runtime_directory_not_private");
+    }
+    finally {
+        await rmdir(temporary).catch((error) => {
+            if (!isMissingPath(error))
+                throw error;
+        });
+    }
+}
+async function hasExistingPath(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isMissingPath(error))
+            return false;
+        throw error;
+    }
+}
+function isMissingPath(error) {
+    if (!error || typeof error !== "object" || !("code" in error))
+        return false;
+    return error.code === "ENOENT";
+}

package/dist/src/runtime/local-host/rpc-peer.d.ts

@@ -0,0 +1,22 @@
+import WebSocket from "ws";
+import type { LocalRuntimeCallHandler } from "./contracts.js";
+export declare class LocalRuntimeRpcPeer {
+    private readonly socket;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly pending;
+    private readonly events;
+    private readonly closedListeners;
+    private handler;
+    private closed;
+    constructor(socket: WebSocket);
+    setHandler(handler: LocalRuntimeCallHandler): void;
+    call(method: string, args?: readonly unknown[]): Promise<unknown>;
+    subscribe(listener: (event: unknown) => void): () => void;
+    onClose(listener: () => void): () => void;
+    publish(value: unknown): void;
+    close(): void;
+    private send;
+    private receive;
+    private respond;
+    private disconnected;
+}