@abot-ai/runtime 1.0.0

package/dist/src/web-ui/local-runtime/contracts.d.ts

@@ -0,0 +1,33 @@
+import type { RuntimeApplication } from "../../runtime/composition.js";
+import type { RequestSteeringInbox } from "../../runtime/request/request-steering.js";
+export type JsonObject = Record<string, unknown>;
+export type LocalRuntimeBackendOptions = {
+    rootDir?: string;
+    configPath?: string;
+    defaultEnvironmentId: string;
+};
+export type RuntimeEnvironment = RuntimeApplication;
+export type RuntimeSetupRequirement = {
+    status: "setup_required";
+    code: "runtime_configuration_required";
+    message: string;
+};
+export type RuntimeAvailability = {
+    status: "ready";
+} | RuntimeSetupRequirement;
+export type RuntimeModelCatalogState = {
+    defaultProfileId: string;
+    profiles: Record<string, unknown>[];
+    availability: RuntimeAvailability;
+};
+export type ActiveRequest = {
+    requestId: string;
+    sessionId: string;
+    environmentId: string;
+    startedAt: number;
+    lastEventAt: number;
+    lastEventName: string;
+    events: JsonObject[];
+    finalState: JsonObject | null;
+    requestSteering: RequestSteeringInbox;
+};

package/dist/src/web-ui/local-runtime/contracts.js

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

package/dist/src/web-ui/local-runtime/control-routes.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { LocalRequestExecution } from "./request-execution.js";
+export declare class LocalRuntimeControlRoutes {
+    private readonly requests;
+    private agentMode;
+    constructor(requests: LocalRequestExecution);
+    health(res: ServerResponse): void;
+    agentModeRoute(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    assistantStatus(res: ServerResponse): void;
+    assistantMutationFallback(res: ServerResponse): void;
+}

package/dist/src/web-ui/local-runtime/control-routes.js

@@ -0,0 +1,52 @@
+import { resolveAgentMode } from "../../shared/agent.js";
+import { readBody, readJsonBody, sendJson } from "./http.js";
+export class LocalRuntimeControlRoutes {
+    requests;
+    agentMode = "reasoning";
+    constructor(requests) {
+        this.requests = requests;
+    }
+    health(res) {
+        const details = this.requests.healthDetails();
+        sendJson(res, 200, {
+            ok: true,
+            source: "local-runtime",
+            agentMode: this.agentMode,
+            activeStreamingRequests: details.length,
+            activeStreamingRequestDetails: details,
+        });
+    }
+    async agentModeRoute(req, res) {
+        if (req.method === "POST") {
+            const body = readJsonBody(await readBody(req));
+            this.agentMode = resolveAgentMode(body.mode);
+        }
+        sendJson(res, 200, {
+            ok: true,
+            mode: this.agentMode,
+            supportedModes: ["fast", "reasoning", "deep", "auto"],
+        });
+    }
+    assistantStatus(res) {
+        sendJson(res, 200, {
+            ok: true,
+            source: "local-runtime",
+            nextWake: {},
+            nextGoal: {},
+            totals: { goals: 0, enabledGoals: 0, pendingTasks: 0, disabledGoals: 0 },
+            recentDeliveries: [],
+            recentNotifications: [],
+            recentDecisions: [],
+            activeExperiments: [],
+            disabledGoals: [],
+            learning: { feedbackCount: 0, reflectionCount: 0, goalHealth: [] },
+        });
+    }
+    assistantMutationFallback(res) {
+        sendJson(res, 200, {
+            ok: true,
+            status: "skipped",
+            reason: "assistant_host_not_configured",
+        });
+    }
+}

package/dist/src/web-ui/local-runtime/environment-registry.d.ts

@@ -0,0 +1,12 @@
+import type { LocalRuntimeBackendOptions, RuntimeEnvironment, RuntimeModelCatalogState, RuntimeSetupRequirement } from "./contracts.js";
+export declare class RuntimeEnvironmentRegistry {
+    private readonly options;
+    private readonly environments;
+    constructor(options: LocalRuntimeBackendOptions);
+    modelCatalog(environmentId: string): RuntimeModelCatalogState;
+    setupRequirement(environmentId: string): RuntimeSetupRequirement | null;
+    get(environmentId: string): RuntimeEnvironment;
+    profileEnv(environmentId: string): Record<string, string | undefined>;
+    private loadConfig;
+    private emptyModelCatalog;
+}

package/dist/src/web-ui/local-runtime/environment-registry.js

@@ -0,0 +1,58 @@
+import { createRuntimeApplication } from "../../runtime/composition.js";
+import { loadRuntimeConfig } from "../../runtime/config.js";
+import { inspectRuntimeConfigFileWithMeta } from "../../runtime/config/loader.js";
+import { loadRuntimeModelCatalog } from "../../runtime/model/model-catalog.js";
+import { inspectRuntimeSetupRequirement } from "./runtime-availability.js";
+export class RuntimeEnvironmentRegistry {
+    options;
+    environments = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    modelCatalog(environmentId) {
+        const source = inspectRuntimeConfigFileWithMeta(this.options.rootDir ?? process.cwd(), this.options.configPath ?? process.env.LLM_RUNTIME_CONFIG_FILE);
+        const setupRequirement = inspectRuntimeSetupRequirement(source);
+        if (setupRequirement) {
+            return this.emptyModelCatalog(setupRequirement);
+        }
+        const catalog = loadRuntimeModelCatalog(this.loadConfig(environmentId));
+        return {
+            ...catalog,
+            availability: { status: "ready" },
+        };
+    }
+    setupRequirement(environmentId) {
+        const availability = this.modelCatalog(environmentId).availability;
+        return availability.status === "setup_required" ? availability : null;
+    }
+    get(environmentId) {
+        const normalized = environmentId || this.options.defaultEnvironmentId;
+        const existing = this.environments.get(normalized);
+        if (existing)
+            return existing;
+        const config = this.loadConfig(normalized);
+        const environment = createRuntimeApplication(config);
+        this.environments.set(normalized, environment);
+        return environment;
+    }
+    profileEnv(environmentId) {
+        return {
+            ...process.env,
+            LLM_RUNTIME_PROFILE: environmentId || this.options.defaultEnvironmentId,
+        };
+    }
+    loadConfig(environmentId) {
+        return loadRuntimeConfig({
+            rootDir: this.options.rootDir,
+            configPath: this.options.configPath,
+            profileId: environmentId || this.options.defaultEnvironmentId,
+        });
+    }
+    emptyModelCatalog(availability) {
+        return {
+            defaultProfileId: "",
+            profiles: [],
+            availability,
+        };
+    }
+}

package/dist/src/web-ui/local-runtime/http.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ConfigFileKind } from "../config-dashboard-backend.js";
+import type { JsonObject } from "./contracts.js";
+export declare function sendJson(res: ServerResponse, statusCode: number, payload: JsonObject): void;
+export declare function sendAttachmentBytes(res: ServerResponse, bytes: Buffer, mimeType: string): void;
+export declare function readBody(req: IncomingMessage, options?: {
+    maxBytes?: number;
+}): Promise<Buffer>;
+export declare function getString(value: unknown): string;
+export declare function getNumber(value: unknown): number;
+export declare function readJsonBody(body: Buffer): JsonObject;
+export declare function requestEnvironmentId(url: URL, body: JsonObject | null, fallback: string): string;
+export declare function pathSegments(pathname: string): string[];
+export declare function readConfigFileKind(value: unknown): ConfigFileKind | null;

package/dist/src/web-ui/local-runtime/http.js

@@ -0,0 +1,78 @@
+export function sendJson(res, statusCode, payload) {
+    res.writeHead(statusCode, {
+        "content-type": "application/json; charset=utf-8",
+    });
+    res.end(JSON.stringify(payload));
+}
+export function sendAttachmentBytes(res, bytes, mimeType) {
+    res.writeHead(200, {
+        "cache-control": "private, no-store",
+        "content-length": String(bytes.byteLength),
+        "content-type": mimeType,
+        "x-content-type-options": "nosniff",
+    });
+    res.end(bytes);
+}
+export function readBody(req, options = {}) {
+    return new Promise((resolveBody, reject) => {
+        const chunks = [];
+        let bytesRead = 0;
+        let settled = false;
+        const rejectOnce = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        };
+        req.on("data", (chunk) => {
+            if (settled)
+                return;
+            bytesRead += chunk.byteLength;
+            if (options.maxBytes !== undefined && bytesRead > options.maxBytes) {
+                rejectOnce(new Error("request_body_too_large"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (settled)
+                return;
+            settled = true;
+            resolveBody(Buffer.concat(chunks));
+        });
+        req.on("error", rejectOnce);
+    });
+}
+export function getString(value) {
+    return typeof value === "string" ? value : "";
+}
+export function getNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+export function readJsonBody(body) {
+    if (body.length === 0)
+        return {};
+    const parsed = JSON.parse(body.toString("utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("JSON object body required");
+    }
+    return parsed;
+}
+export function requestEnvironmentId(url, body, fallback) {
+    return (getString(body?.environment) ||
+        getString(body?.environmentId) ||
+        getString(url.searchParams.get("environment")) ||
+        getString(url.searchParams.get("environmentId")) ||
+        fallback)
+        .trim()
+        .toLowerCase();
+}
+export function pathSegments(pathname) {
+    return pathname.split("/").filter(Boolean).map(decodeURIComponent);
+}
+export function readConfigFileKind(value) {
+    const kind = getString(value);
+    return kind === "runtime" || kind === "requestRunner" || kind === "model"
+        ? kind
+        : null;
+}

package/dist/src/web-ui/local-runtime/realtime-controller.d.ts

@@ -0,0 +1,15 @@
+import type WebSocket from "ws";
+import type { LocalRuntimeBackendOptions } from "./contracts.js";
+import { RuntimeEnvironmentRegistry } from "./environment-registry.js";
+import { RealtimeClientHub } from "./realtime-hub.js";
+import { LocalRequestExecution } from "./request-execution.js";
+export declare class LocalRealtimeController {
+    private readonly options;
+    private readonly environments;
+    private readonly requests;
+    private readonly clients;
+    constructor(options: LocalRuntimeBackendOptions, environments: RuntimeEnvironmentRegistry, requests: LocalRequestExecution, clients: RealtimeClientHub);
+    connect(client: WebSocket): void;
+    private handleMessage;
+    private resume;
+}

package/dist/src/web-ui/local-runtime/realtime-controller.js

@@ -0,0 +1,69 @@
+import { getNumber, getString, requestEnvironmentId } from "./http.js";
+export class LocalRealtimeController {
+    options;
+    environments;
+    requests;
+    clients;
+    constructor(options, environments, requests, clients) {
+        this.options = options;
+        this.environments = environments;
+        this.requests = requests;
+        this.clients = clients;
+    }
+    connect(client) {
+        this.clients.add(client);
+        client.on("message", (data) => {
+            void this.handleMessage(client, data.toString()).catch((error) => {
+                this.clients.send(client, {
+                    type: "control",
+                    name: "local_runtime_realtime_error",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        });
+    }
+    async handleMessage(client, raw) {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return;
+        const message = parsed;
+        if (message.type === "tool_approval_response") {
+            this.requests.resolveToolApproval(message);
+            return;
+        }
+        if (message.type === "steer_request") {
+            this.clients.send(client, this.requests.handleSteer(message));
+            return;
+        }
+        if (message.type !== "resume_request")
+            return;
+        await this.resume(client, message);
+    }
+    async resume(client, message) {
+        const requestId = getString(message.requestId);
+        if (!requestId)
+            return;
+        const environmentId = requestEnvironmentId(new URL("/", "http://localhost"), message, this.options.defaultEnvironmentId);
+        const environment = this.environments.get(environmentId);
+        const replay = await environment.services.sessions.getRequestReplayById(requestId, getNumber(message.afterSeq));
+        for (const event of replay?.events ?? []) {
+            this.clients.send(client, { ...event, environment: environmentId });
+        }
+        if (replay?.finalState?.status === "completed") {
+            this.clients.send(client, {
+                type: "completed",
+                requestId,
+                environment: environmentId,
+                output: replay.finalState.output,
+            });
+        }
+        if (replay?.finalState?.status === "failed") {
+            this.clients.send(client, {
+                type: "failed",
+                requestId,
+                environment: environmentId,
+                error: replay.finalState.error,
+            });
+        }
+    }
+}

package/dist/src/web-ui/local-runtime/realtime-hub.d.ts

@@ -0,0 +1,8 @@
+import type WebSocket from "ws";
+import type { JsonObject } from "./contracts.js";
+export declare class RealtimeClientHub {
+    private readonly clients;
+    add(client: WebSocket): void;
+    broadcast(payload: JsonObject): void;
+    send(client: WebSocket, payload: JsonObject): void;
+}

package/dist/src/web-ui/local-runtime/realtime-hub.js

@@ -0,0 +1,18 @@
+export class RealtimeClientHub {
+    clients = new Set();
+    add(client) {
+        this.clients.add(client);
+        const remove = () => this.clients.delete(client);
+        client.on("close", remove);
+        client.on("error", remove);
+    }
+    broadcast(payload) {
+        for (const client of this.clients)
+            this.send(client, payload);
+    }
+    send(client, payload) {
+        if (client.readyState !== client.OPEN)
+            return;
+        client.send(JSON.stringify(payload));
+    }
+}

package/dist/src/web-ui/local-runtime/request-execution.d.ts

@@ -0,0 +1,18 @@
+import type { ServerResponse } from "node:http";
+import type { JsonObject, RuntimeEnvironment } from "./contracts.js";
+import { RealtimeClientHub } from "./realtime-hub.js";
+export declare class LocalRequestExecution {
+    private readonly realtime;
+    private readonly activeRequests;
+    private readonly pendingToolApprovals;
+    constructor(realtime: RealtimeClientHub);
+    start(res: ServerResponse, body: JsonObject, environmentId: string, environment: RuntimeEnvironment): Promise<void>;
+    activeReplay(requestId: string, afterSeq: number): JsonObject | undefined;
+    healthDetails(): JsonObject[];
+    handleSteer(message: JsonObject): JsonObject;
+    resolveToolApproval(message: JsonObject): void;
+    private run;
+    private createToolApprovalController;
+    private publishRaw;
+    private publish;
+}

package/dist/src/web-ui/local-runtime/request-execution.js

@@ -0,0 +1,199 @@
+import { createRequestSteeringInbox, } from "../../runtime/request/request-steering.js";
+import { getNumber, getString, sendJson } from "./http.js";
+function createRequestId() {
+    const random = Math.random().toString(36).slice(2, 8);
+    return `web-${Date.now()}-${random}`;
+}
+export class LocalRequestExecution {
+    realtime;
+    activeRequests = new Map();
+    pendingToolApprovals = new Map();
+    constructor(realtime) {
+        this.realtime = realtime;
+    }
+    async start(res, body, environmentId, environment) {
+        const text = getString(body.text).trim();
+        const sessionId = getString(body.sessionId).trim();
+        if (!text || !sessionId) {
+            sendJson(res, 400, {
+                ok: false,
+                error: !text ? "text_required" : "sessionId_required",
+            });
+            return;
+        }
+        const requestId = createRequestId();
+        const requestSteering = createRequestSteeringInbox({ requestId });
+        const request = {
+            type: "run_request",
+            requestId,
+            sessionId,
+            text,
+            agentMode: body.agentMode,
+            modelPreference: body.modelPreference,
+            toolPermissionMode: body.toolPermissionMode,
+            attachments: Array.isArray(body.attachments) ? body.attachments : [],
+        };
+        this.activeRequests.set(requestId, {
+            requestId,
+            sessionId,
+            environmentId,
+            startedAt: Date.now(),
+            lastEventAt: Date.now(),
+            lastEventName: "request.started",
+            events: [],
+            finalState: null,
+            requestSteering,
+        });
+        void this.run(environment, request, environmentId, sessionId, requestSteering)
+            .catch((error) => {
+            this.publish({
+                type: "failed",
+                requestId,
+                sessionId,
+                environment: environmentId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => this.activeRequests.delete(requestId));
+        sendJson(res, 200, { ok: true, requestId, sessionId });
+    }
+    activeReplay(requestId, afterSeq) {
+        const active = this.activeRequests.get(requestId);
+        if (!active)
+            return undefined;
+        return {
+            ok: true,
+            requestId: active.requestId,
+            events: active.events.filter((event) => getNumber(event.eventSequence) > afterSeq),
+            finalState: active.finalState,
+        };
+    }
+    healthDetails() {
+        return [...this.activeRequests.values()].map((request) => ({
+            requestId: request.requestId,
+            sessionId: request.sessionId,
+            environment: request.environmentId,
+            startedAt: request.startedAt,
+            lastEventAt: request.lastEventAt,
+            lastEventName: request.lastEventName,
+            idleMs: Date.now() - request.lastEventAt,
+        }));
+    }
+    handleSteer(message) {
+        const requestId = getString(message.requestId).trim();
+        const steerId = getString(message.steerId).trim();
+        const text = getString(message.text).trim();
+        const active = requestId ? this.activeRequests.get(requestId) : undefined;
+        const result = active?.requestSteering.append({ steerId, text }) ??
+            { ok: false, reason: "request_not_active" };
+        return result.ok
+            ? {
+                type: "steer_ack",
+                requestId,
+                steerId,
+                accepted: true,
+                acceptedSequence: result.update.sequence,
+            }
+            : {
+                type: "steer_ack",
+                requestId,
+                steerId,
+                accepted: false,
+                reason: result.reason,
+            };
+    }
+    resolveToolApproval(message) {
+        const approvalId = getString(message.approvalId);
+        if (!approvalId)
+            return;
+        const pending = this.pendingToolApprovals.get(approvalId);
+        if (!pending)
+            return;
+        pending.resolve({
+            approved: message.approved === true,
+            reason: getString(message.reason).trim() || undefined,
+        });
+    }
+    async run(environment, request, environmentId, sessionId, requestSteering) {
+        const localWs = {
+            send: (data) => this.publishRaw(data, { environmentId, sessionId }),
+        };
+        await environment.requests.handle(localWs, request, {
+            toolApprovalController: this.createToolApprovalController(),
+            requestSteering,
+        });
+    }
+    createToolApprovalController() {
+        return {
+            requestToolApproval: (request, options) => new Promise((resolve) => {
+                if (options?.abortSignal?.aborted) {
+                    resolve({
+                        approved: false,
+                        reason: "Tool approval was cancelled.",
+                    });
+                    return;
+                }
+                const complete = (decision) => {
+                    this.pendingToolApprovals.delete(request.approvalId);
+                    options?.abortSignal?.removeEventListener("abort", onAbort);
+                    resolve(decision);
+                };
+                const onAbort = () => complete({
+                    approved: false,
+                    reason: "Tool approval was cancelled.",
+                });
+                options?.abortSignal?.addEventListener("abort", onAbort, {
+                    once: true,
+                });
+                this.pendingToolApprovals.set(request.approvalId, {
+                    requestId: request.requestId,
+                    resolve: complete,
+                });
+            }),
+        };
+    }
+    publishRaw(data, context) {
+        try {
+            const parsed = JSON.parse(data);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return;
+            this.publish({
+                ...parsed,
+                sessionId: context.sessionId,
+                environment: context.environmentId,
+            });
+        }
+        catch {
+            this.publish({
+                type: "control",
+                name: "local_runtime_invalid_event",
+                output: data,
+            });
+        }
+    }
+    publish(payload) {
+        const requestId = getString(payload.requestId);
+        const active = requestId ? this.activeRequests.get(requestId) : undefined;
+        if (active) {
+            active.lastEventAt = Date.now();
+            active.lastEventName =
+                getString(payload.name) || getString(payload.type) || "event";
+            active.events.push(payload);
+            if (payload.type === "completed") {
+                active.finalState = {
+                    status: "completed",
+                    output: getString(payload.output),
+                    completedAt: Date.now(),
+                };
+            }
+            if (payload.type === "failed") {
+                active.finalState = {
+                    status: "failed",
+                    error: getString(payload.error),
+                    completedAt: Date.now(),
+                };
+            }
+        }
+        this.realtime.broadcast(payload);
+    }
+}

package/dist/src/web-ui/local-runtime/runtime-availability.d.ts

@@ -0,0 +1,3 @@
+import type { InspectedRuntimeConfigFile } from "../../runtime/config/loader.js";
+import type { RuntimeSetupRequirement } from "./contracts.js";
+export declare function inspectRuntimeSetupRequirement(source: InspectedRuntimeConfigFile): RuntimeSetupRequirement | null;

package/dist/src/web-ui/local-runtime/runtime-availability.js

@@ -0,0 +1,45 @@
+import { buildRuntimeModelConfiguration } from "../../runtime/config/builders.js";
+import { isRecord } from "../../runtime/config/utils.js";
+import { validateRuntimeConfigFile } from "../../runtime/config/validation.js";
+function setupRequired(message) {
+    return {
+        status: "setup_required",
+        code: "runtime_configuration_required",
+        message,
+    };
+}
+export function inspectRuntimeSetupRequirement(source) {
+    if (!source.exists) {
+        return setupRequired("No runtime configuration was found. Choose a provider and model to finish setup.");
+    }
+    validateRuntimeConfigFile(source.config, source.path, {
+        allowIncompleteSetup: true,
+    });
+    const modelPolicy = buildRuntimeModelConfiguration(source.config, {
+        mainConfigPath: source.path,
+    }).modelPolicy;
+    const providers = modelPolicy?.providers ?? {};
+    const profiles = Object.values(modelPolicy?.profiles ?? {});
+    if (Object.keys(providers).length === 0) {
+        return setupRequired("No usable model provider is configured. Choose a provider and model to finish setup.");
+    }
+    if (profiles.length === 0) {
+        return setupRequired("No model profile has a concrete model ID. Add a model connected to a declared provider.");
+    }
+    const usableProfile = profiles.find((profile) => {
+        const modelId = profile.model?.trim();
+        const providerId = profile.provider?.trim();
+        return !!modelId && !!providerId && Object.hasOwn(providers, providerId);
+    });
+    if (!usableProfile) {
+        return setupRequired("No model profile resolves to a declared provider. Connect a model profile to one of the configured providers.");
+    }
+    const requestRunner = isRecord(source.config.requestRunner)
+        ? source.config.requestRunner
+        : undefined;
+    if (typeof requestRunner?.configRef !== "string" ||
+        requestRunner.configRef.trim().length === 0) {
+        return setupRequired("A model is configured, but the request-runner configuration is missing. Run the initializer to finish setup.");
+    }
+    return null;
+}

package/dist/src/web-ui/local-runtime-backend.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type WebSocket from "ws";
+import type { LocalRuntimeBackendOptions } from "./local-runtime/contracts.js";
+export type { LocalRuntimeBackendOptions } from "./local-runtime/contracts.js";
+/** Stable server-facing facade for the direct Runtime Web UI backend. */
+export declare class LocalRuntimeWebBackend {
+    private readonly environments;
+    private readonly api;
+    private readonly realtime;
+    private readonly controls;
+    constructor(options: LocalRuntimeBackendOptions);
+    handleHttp(req: IncomingMessage, res: ServerResponse, pathname: string): Promise<boolean>;
+    handleRealtimeConnection(client: WebSocket): void;
+}