@abot-ai/runtime 1.0.0

package/dist/scripts/init-runtime.js

@@ -0,0 +1,254 @@
+import { constants } from "node:fs";
+import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildModelConfig, buildProviderConfig, isRecord, parseBaseUrl, parseProvider, readJsonObject, resolveRuntimePackageRoot, writeJsonObject, } from "./runtime-setup-files.js";
+import { getInitNextSteps, getInitUsage, } from "./runtime-setup-presentation.js";
+const ENV_FILE = ".env";
+const ENV_EXAMPLE_FILE = "examples/env.example";
+const LOCAL_CONFIG_FILE = "local/runtime.config.json";
+const LOCAL_REQUEST_RUNNER_CONFIG_FILE = "local/request-runner.config.json";
+const LOCAL_MODEL_CONFIG_FILE = "local/models/default.config.json";
+const CONFIG_EXAMPLE_FILE = join("examples", "runtime.config.example.json");
+const REQUEST_RUNNER_CONFIG_EXAMPLE_FILE = join("examples", "request-runner.config.example.json");
+const MODEL_CONFIG_EXAMPLE_FILE = join("examples", "models", "default.config.json");
+const REQUIRED_ENV_LINE = "LLM_RUNTIME_CONFIG_FILE=local/runtime.config.json";
+const RUNTIME_DIRS = [
+    join(".runtime", "compiled"),
+    join(".runtime", "shared", "logs"),
+    join(".runtime", "prod"),
+    join(".runtime", "prod", "sandbox"),
+    join(".runtime", "prod", "sessions"),
+    join(".runtime", "dev"),
+    join(".runtime", "dev", "sandbox"),
+    join(".runtime", "dev", "sessions"),
+];
+function requireValue(argv, index, flag) {
+    const value = argv[index + 1]?.trim();
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function parseArgs(argv, commandMode) {
+    let rootDir = process.cwd();
+    let provider;
+    let model;
+    let baseUrl;
+    let force = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--provider") {
+            provider = parseProvider(requireValue(argv, index, "--provider"));
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--provider=")) {
+            provider = parseProvider(arg.slice("--provider=".length).trim());
+            continue;
+        }
+        if (arg === "--model") {
+            model = requireValue(argv, index, "--model");
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--model=")) {
+            model = arg.slice("--model=".length).trim();
+            if (!model) {
+                throw new Error("--model requires a value");
+            }
+            continue;
+        }
+        if (arg === "--base-url") {
+            baseUrl = parseBaseUrl(requireValue(argv, index, "--base-url"));
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--base-url=")) {
+            baseUrl = parseBaseUrl(arg.slice("--base-url=".length));
+            continue;
+        }
+        if (arg === "--root") {
+            rootDir = resolve(requireValue(argv, index, "--root"));
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--root=")) {
+            const value = arg.slice("--root=".length).trim();
+            if (!value) {
+                throw new Error("--root requires a path");
+            }
+            rootDir = resolve(value);
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            printHelp(commandMode);
+            process.exit(0);
+        }
+        throw new Error(`unknown argument: ${arg}`);
+    }
+    if (!provider) {
+        throw new Error("--provider is required");
+    }
+    if (!model) {
+        throw new Error("--model is required");
+    }
+    if (baseUrl && provider !== "ollama") {
+        throw new Error("--base-url is supported only with --provider ollama");
+    }
+    return { rootDir, provider, model, baseUrl, force };
+}
+function printHelp(commandMode) {
+    console.log([
+        getInitUsage(commandMode),
+        "",
+        "Creates local runtime starter files without committing secrets:",
+        "- .env",
+        "- local/runtime.config.json",
+        "- local/request-runner.config.json",
+        "- local/models/default.config.json",
+        "- .runtime/compiled",
+        "- .runtime/shared/logs",
+        "- .runtime/prod and .runtime/dev",
+        "",
+        "Both --provider and --model are required; the runtime has no built-in model choice.",
+        "--base-url configures the Ollama origin when Ollama runs outside the runtime host.",
+    ].join("\n"));
+}
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeIfMissing(params) {
+    const targetExists = await exists(params.targetPath);
+    if (targetExists && !params.force) {
+        return "kept";
+    }
+    await mkdir(dirname(params.targetPath), { recursive: true });
+    await copyFile(params.sourcePath, params.targetPath);
+    return targetExists ? "overwritten" : "created";
+}
+function ensureEnvLineContent(raw) {
+    const lines = raw.split(/\r?\n/);
+    const hasConfigLine = lines.some((line) => line.trim().startsWith("LLM_RUNTIME_CONFIG_FILE="));
+    if (hasConfigLine) {
+        return raw.endsWith("\n") ? raw : `${raw}\n`;
+    }
+    const terminated = raw.endsWith("\n") ? raw : `${raw}\n`;
+    return `${terminated}${REQUIRED_ENV_LINE}\n`;
+}
+async function ensureEnvLine(envPath) {
+    const raw = await readFile(envPath, "utf-8");
+    const next = ensureEnvLineContent(raw);
+    if (next === raw) {
+        return false;
+    }
+    await writeFile(envPath, next, "utf-8");
+    return true;
+}
+async function configureRuntimeProvider(configPath, provider, baseUrl) {
+    const config = await readJsonObject(configPath);
+    const models = isRecord(config.models) ? config.models : {};
+    const { defaults: _ignoredDefaults, ...modelSettings } = models;
+    const providers = {
+        [provider]: buildProviderConfig(provider, baseUrl),
+    };
+    config.models = {
+        ...modelSettings,
+        providers,
+        profiles: {
+            default: {
+                configRef: "./models/default.config.json",
+            },
+        },
+    };
+    await writeJsonObject(configPath, config);
+}
+async function configureModelProfile(configPath, provider, model) {
+    const config = await readJsonObject(configPath);
+    await writeJsonObject(configPath, buildModelConfig(config, provider, model));
+}
+async function configureRunner(configPath) {
+    const config = await readJsonObject(configPath);
+    const models = isRecord(config.models) ? config.models : {};
+    const defaults = isRecord(models.defaults) ? models.defaults : {};
+    config.models = {
+        ...models,
+        defaults: {
+            ...defaults,
+            profileId: "default",
+        },
+    };
+    await writeJsonObject(configPath, config);
+}
+export async function runInitRuntime(argv = process.argv.slice(2), runOptions = {}) {
+    const commandMode = runOptions.commandMode ?? "source";
+    const options = parseArgs(argv, commandMode);
+    const templateRoot = resolveRuntimePackageRoot(import.meta.dirname);
+    const envPath = join(options.rootDir, ENV_FILE);
+    const configPath = join(options.rootDir, LOCAL_CONFIG_FILE);
+    const requestRunnerConfigPath = join(options.rootDir, LOCAL_REQUEST_RUNNER_CONFIG_FILE);
+    const modelConfigPath = join(options.rootDir, LOCAL_MODEL_CONFIG_FILE);
+    await mkdir(options.rootDir, { recursive: true });
+    const envStatus = await writeIfMissing({
+        sourcePath: join(templateRoot, ENV_EXAMPLE_FILE),
+        targetPath: envPath,
+        force: options.force,
+    });
+    const envLineChanged = await ensureEnvLine(envPath);
+    const configStatus = await writeIfMissing({
+        sourcePath: join(templateRoot, CONFIG_EXAMPLE_FILE),
+        targetPath: configPath,
+        force: options.force,
+    });
+    const requestRunnerConfigStatus = await writeIfMissing({
+        sourcePath: join(templateRoot, REQUEST_RUNNER_CONFIG_EXAMPLE_FILE),
+        targetPath: requestRunnerConfigPath,
+        force: options.force,
+    });
+    const modelConfigStatus = await writeIfMissing({
+        sourcePath: join(templateRoot, MODEL_CONFIG_EXAMPLE_FILE),
+        targetPath: modelConfigPath,
+        force: options.force,
+    });
+    if (configStatus !== "kept") {
+        await configureRuntimeProvider(configPath, options.provider, options.baseUrl);
+    }
+    if (requestRunnerConfigStatus !== "kept") {
+        await configureRunner(requestRunnerConfigPath);
+    }
+    if (modelConfigStatus !== "kept") {
+        await configureModelProfile(modelConfigPath, options.provider, options.model);
+    }
+    await Promise.all(RUNTIME_DIRS.map((runtimeDir) => mkdir(join(options.rootDir, runtimeDir), { recursive: true })));
+    console.log([
+        "abot initialized",
+        `root: ${options.rootDir}`,
+        `provider: ${options.provider}`,
+        `model: ${options.model}`,
+        ...(options.baseUrl ? [`base URL: ${options.baseUrl}`] : []),
+        `.env: ${envStatus}${envLineChanged ? " + config pointer" : ""}`,
+        `${LOCAL_CONFIG_FILE}: ${configStatus}`,
+        `${LOCAL_REQUEST_RUNNER_CONFIG_FILE}: ${requestRunnerConfigStatus}`,
+        `${LOCAL_MODEL_CONFIG_FILE}: ${modelConfigStatus}`,
+        "created runtime directories: .runtime/compiled, .runtime/shared/logs, .runtime/prod, .runtime/dev",
+        "",
+        ...getInitNextSteps(commandMode),
+    ].join("\n"));
+}
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === invokedPath) {
+    runInitRuntime().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/scripts/runtime-setup-files.d.ts

@@ -0,0 +1,12 @@
+export type Provider = string;
+export type JsonObject = Record<string, unknown>;
+export declare function resolveRuntimePackageRoot(startDir: string): string;
+export declare function isRecord(value: unknown): value is JsonObject;
+export declare function parseProvider(value: string): Provider;
+export declare function parseBaseUrl(value: string): string;
+export declare function readJsonObject(path: string): Promise<JsonObject>;
+export declare function writeJsonObject(path: string, value: JsonObject, options?: Readonly<{
+    exclusive?: boolean;
+}>): Promise<void>;
+export declare function buildProviderConfig(provider: Provider, baseUrl?: string): JsonObject;
+export declare function buildModelConfig(template: JsonObject, provider: Provider, model: string): JsonObject;

package/dist/scripts/runtime-setup-files.js

@@ -0,0 +1,96 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export function resolveRuntimePackageRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, "examples", "runtime.config.example.json")) &&
+            existsSync(join(current, "package.json"))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new Error("could not locate the @abot-ai/runtime package root");
+        }
+        current = parent;
+    }
+}
+export function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function parseProvider(value) {
+    const provider = value.trim();
+    if (!/^[A-Za-z][A-Za-z0-9._-]*$/u.test(provider)) {
+        throw new Error("--provider must be a provider adapter identifier");
+    }
+    return provider;
+}
+export function parseBaseUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch {
+        throw new Error("--base-url must be a valid HTTP or HTTPS origin");
+    }
+    if (!["http:", "https:"].includes(parsed.protocol) ||
+        !parsed.hostname ||
+        parsed.username ||
+        parsed.password ||
+        parsed.search ||
+        parsed.hash ||
+        (parsed.pathname && parsed.pathname !== "/")) {
+        throw new Error("--base-url must be a valid HTTP or HTTPS origin");
+    }
+    return `${parsed.protocol}//${parsed.host}`;
+}
+export async function readJsonObject(path) {
+    const parsed = JSON.parse(await readFile(path, "utf-8"));
+    if (!isRecord(parsed)) {
+        throw new Error(`${path} must contain a JSON object`);
+    }
+    return parsed;
+}
+export async function writeJsonObject(path, value, options = {}) {
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
+        encoding: "utf-8",
+        ...(options.exclusive ? { flag: "wx" } : {}),
+    });
+}
+export function buildProviderConfig(provider, baseUrl) {
+    if (provider === "openai") {
+        return {
+            type: "openai",
+            apiKeyEnv: "OPENAI_API_KEY",
+        };
+    }
+    if (provider === "ollama") {
+        return {
+            type: "ollama",
+            baseUrl: baseUrl ?? "http://127.0.0.1:11434",
+        };
+    }
+    return { type: provider };
+}
+export function buildModelConfig(template, provider, model) {
+    const context = isRecord(template.context) ? template.context : {};
+    return {
+        ...template,
+        label: model,
+        provider,
+        model,
+        ...(provider === "openai"
+            ? {
+                execution: {
+                    policy: "execution-agent-v1",
+                },
+            }
+            : {}),
+        context: {
+            ...context,
+            formatTokenAccounting: {
+                mode: provider === "ollama" ? "none" : "estimate",
+            },
+        },
+    };
+}

package/dist/scripts/runtime-setup-presentation.d.ts

@@ -0,0 +1,6 @@
+export type RuntimeSetupCommandMode = "source" | "package";
+export declare function getInitUsage(mode: RuntimeSetupCommandMode): string;
+export declare function getAddModelUsage(mode: RuntimeSetupCommandMode): string;
+export declare function getMissingInitializationInstruction(mode: RuntimeSetupCommandMode): string;
+export declare function getInitNextSteps(mode: RuntimeSetupCommandMode): readonly string[];
+export declare function getRestartInstruction(mode: RuntimeSetupCommandMode): string;

package/dist/scripts/runtime-setup-presentation.js

@@ -0,0 +1,34 @@
+function commandForMode(mode, sourceCommand, packageCommand) {
+    return mode === "package" ? packageCommand : sourceCommand;
+}
+export function getInitUsage(mode) {
+    const command = commandForMode(mode, "npm run init --", "npx abot init");
+    return `Usage: ${command} --provider <provider-adapter> --model <model-id> [--base-url <provider-origin>] [--force] [--root <dir>]`;
+}
+export function getAddModelUsage(mode) {
+    const command = commandForMode(mode, "npm run add-model --", "npx abot add-model");
+    return `Usage: ${command} --profile <profile-id> --provider <provider-adapter> --model <model-id> [--base-url <provider-origin>] [--default] [--root <dir>]`;
+}
+export function getMissingInitializationInstruction(mode) {
+    return commandForMode(mode, "run npm run init first", "run npx abot init first");
+}
+export function getInitNextSteps(mode) {
+    if (mode === "package") {
+        return [
+            "Getting started:",
+            "1. Review .env and local/*.config.json for your machine.",
+            "2. Set provider credentials in .env when required.",
+            "3. Start ABot with npx abot start.",
+        ];
+    }
+    return [
+        "Getting started:",
+        "1. Review .env and local/*.config.json for your machine.",
+        "2. Start npm run model-gateway.",
+        "3. Start npm run dev in another terminal.",
+        "4. Optional: start npm run web-ui for the local browser client.",
+    ];
+}
+export function getRestartInstruction(mode) {
+    return commandForMode(mode, "restart the model gateway and Web UI to load the new profile", "restart ABot with npx abot start to load the new profile");
+}

package/dist/src/bridge/request-steering.d.ts

@@ -0,0 +1,8 @@
+import type WebSocket from "ws";
+import { type RequestSteeringInbox } from "../runtime/request/request-steering.js";
+export type BridgeRequestSteeringRegistry = Readonly<{
+    close(requestId: string, inbox: RequestSteeringInbox): Promise<void>;
+    handleMessage(ws: WebSocket, message: Record<string, unknown>): Promise<boolean>;
+    open(requestId: string): RequestSteeringInbox;
+}>;
+export declare function createBridgeRequestSteeringRegistry(): BridgeRequestSteeringRegistry;

package/dist/src/bridge/request-steering.js

@@ -0,0 +1,90 @@
+import { traceDebug } from "../runtime/observability/debug-logger.js";
+import { createRequestSteeringInbox, } from "../runtime/request/request-steering.js";
+const LOG_SCOPE = "agent-bridge.request_steering";
+export function createBridgeRequestSteeringRegistry() {
+    const active = new Map();
+    return Object.freeze({
+        async close(requestId, inbox) {
+            const current = active.get(requestId);
+            if (current?.inbox === inbox) {
+                active.delete(requestId);
+            }
+            await inbox.close();
+            traceDebug(LOG_SCOPE, "request.closed", {
+                requestId,
+                activeRequestCount: active.size,
+            });
+        },
+        async handleMessage(ws, message) {
+            if (message.type !== "steer_request") {
+                return false;
+            }
+            const requestId = readString(message.requestId).trim();
+            const steerId = readString(message.steerId).trim();
+            const text = readString(message.text).trim();
+            const current = active.get(requestId);
+            const result = current?.inbox.append({ steerId, text }) ??
+                Object.freeze({
+                    ok: false,
+                    reason: "request_not_active",
+                });
+            const response = result.ok
+                ? {
+                    type: "steer_ack",
+                    requestId,
+                    steerId,
+                    accepted: true,
+                    acceptedSequence: result.update.sequence,
+                }
+                : {
+                    type: "steer_ack",
+                    requestId,
+                    steerId,
+                    accepted: false,
+                    reason: result.reason,
+                };
+            await sendJson(ws, response);
+            traceDebug(LOG_SCOPE, result.ok ? "message.accepted" : "message.rejected", {
+                requestId,
+                steerId,
+                accepted: result.ok,
+                ...(result.ok
+                    ? {
+                        acceptedSequence: result.update.sequence,
+                        duplicate: result.duplicate,
+                        textLength: text.length,
+                    }
+                    : { reason: result.reason }),
+            });
+            return true;
+        },
+        open(requestId) {
+            if (!requestId.trim()) {
+                throw new Error("request_steering_request_id_required");
+            }
+            if (active.has(requestId)) {
+                throw new Error("request_steering_request_already_active");
+            }
+            const inbox = createRequestSteeringInbox({ requestId });
+            active.set(requestId, Object.freeze({ inbox, requestId }));
+            traceDebug(LOG_SCOPE, "request.opened", {
+                requestId,
+                activeRequestCount: active.size,
+            });
+            return inbox;
+        },
+    });
+}
+async function sendJson(ws, payload) {
+    await new Promise((resolve, reject) => {
+        ws.send(JSON.stringify(payload), (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+function readString(value) {
+    return typeof value === "string" ? value : "";
+}

package/dist/src/bridge/runtime-admin.d.ts

@@ -0,0 +1,13 @@
+import type WebSocket from "ws";
+import { type RuntimeManagedServiceRestartHandler, type RuntimeRestartHandler } from "../runtime/admin/system-control.js";
+type JsonObject = Record<string, unknown>;
+export declare function handleRuntimeAdminBridgeMessage(ws: WebSocket, msg: JsonObject, options?: {
+    rootDir?: string;
+    configPath?: string;
+    env?: Record<string, string | undefined>;
+    modelGatewayUrl?: string;
+    modelGatewayRestartFetch?: typeof fetch;
+    restartHandler?: RuntimeRestartHandler;
+    managedServiceRestartHandler?: RuntimeManagedServiceRestartHandler;
+}): Promise<boolean>;
+export {};