@abot-ai/runtime 1.0.0

package/dist/src/runtime/admin/config-control.d.ts

@@ -0,0 +1,42 @@
+import type { RuntimeConfigFile, RuntimeConfigJsonSchema } from "../config/types.js";
+import type { RuntimeConfig } from "../ports.js";
+export type RuntimeConfigMetadata = {
+    rootDir: string;
+    configPath: string;
+    exists: boolean;
+};
+export type RuntimeConfigGetResult = {
+    metadata: RuntimeConfigMetadata;
+    fileConfig: RuntimeConfigFile;
+    effectiveConfig: RuntimeConfig;
+};
+export type RuntimeConfigValidationResult = {
+    ok: true;
+    config: RuntimeConfigFile;
+} | {
+    ok: false;
+    issues: string[];
+    message: string;
+};
+export type RuntimeConfigPatchResult = RuntimeConfigValidationResult & {
+    metadata: RuntimeConfigMetadata;
+    backupPath?: string;
+    restartRequired: boolean;
+};
+export declare function getRuntimeConfigSchema(): RuntimeConfigJsonSchema;
+export declare function getRuntimeConfig(params?: {
+    rootDir?: string;
+    configPath?: string;
+    env?: Record<string, string | undefined>;
+}): RuntimeConfigGetResult;
+export declare function validateRuntimeConfigCandidate(params: {
+    config?: unknown;
+    patch?: unknown;
+    rootDir?: string;
+    configPath?: string;
+}): RuntimeConfigValidationResult;
+export declare function patchRuntimeConfig(params: {
+    patch: unknown;
+    rootDir?: string;
+    configPath?: string;
+}): Promise<RuntimeConfigPatchResult>;

package/dist/src/runtime/admin/config-control.js

@@ -0,0 +1,211 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadRuntimeConfig } from "../config.js";
+import { DEFAULT_RUNTIME_CONFIG_FILE } from "../config/constants.js";
+import { loadRuntimeConfigFile } from "../config/loader.js";
+import { RUNTIME_CONFIG_JSON_SCHEMA } from "../config/schema.js";
+import { RuntimeConfigValidationError, validateRuntimeConfigFile, } from "../config/validation.js";
+const NON_SECRET_TOKEN_CONFIG_KEYS = new Set([
+    "contextwindowtokens",
+    "outputreservetokens",
+    "safetyreservetokens",
+    "attachmentreservetokens",
+    "formattokenaccounting",
+    "fixedoverheadtokens",
+    "tokenestimation",
+    "asciicharacterspertoken",
+    "nonasciibytespertoken",
+    "messageoverheadtokens",
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function resolveConfigPath(rootDir, configPath) {
+    return configPath
+        ? join(rootDir, configPath)
+        : join(rootDir, DEFAULT_RUNTIME_CONFIG_FILE);
+}
+function redactConfigValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(redactConfigValue);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const redacted = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const normalizedKey = key.toLowerCase();
+        redacted[key] =
+            (normalizedKey.includes("token") &&
+                !NON_SECRET_TOKEN_CONFIG_KEYS.has(normalizedKey)) ||
+                normalizedKey.includes("secret") ||
+                normalizedKey.endsWith("apikey")
+                ? "[redacted]"
+                : redactConfigValue(entry);
+    }
+    return redacted;
+}
+function redactRuntimeConfig(config) {
+    return redactConfigValue(config);
+}
+function readConfigMetadata(params) {
+    const resolvedPath = resolveConfigPath(params.rootDir, params.configPath);
+    return {
+        rootDir: params.rootDir,
+        configPath: resolvedPath,
+        exists: existsSync(resolvedPath),
+    };
+}
+function cloneConfig(config) {
+    return JSON.parse(JSON.stringify(config));
+}
+function mergePatch(base, patch) {
+    const output = cloneConfig(base);
+    for (const [key, value] of Object.entries(patch)) {
+        if (isRecord(value) && isRecord(output[key])) {
+            output[key] = mergePatch(output[key], value);
+            continue;
+        }
+        output[key] = value;
+    }
+    return output;
+}
+function validationFailure(error) {
+    if (error instanceof RuntimeConfigValidationError) {
+        return {
+            ok: false,
+            issues: error.issues,
+            message: error.message,
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        ok: false,
+        issues: [message],
+        message,
+    };
+}
+function validateConfig(config, configPath) {
+    try {
+        validateRuntimeConfigFile(config, configPath);
+        return {
+            ok: true,
+            config,
+        };
+    }
+    catch (error) {
+        return validationFailure(error);
+    }
+}
+async function readExistingConfigText(configPath) {
+    try {
+        return await readFile(configPath, "utf-8");
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+function backupPathFor(configPath) {
+    const stamp = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d{3}Z$/, "Z");
+    return `${configPath}.${stamp}.bak`;
+}
+export function getRuntimeConfigSchema() {
+    return RUNTIME_CONFIG_JSON_SCHEMA;
+}
+export function getRuntimeConfig(params = {}) {
+    const rootDir = params.rootDir ?? process.cwd();
+    const metadata = readConfigMetadata({
+        rootDir,
+        configPath: params.configPath,
+    });
+    const fileConfig = loadRuntimeConfigFile(rootDir, params.configPath);
+    const effectiveConfig = redactRuntimeConfig(loadRuntimeConfig({
+        rootDir,
+        configPath: params.configPath,
+        env: params.env,
+    }));
+    return {
+        metadata,
+        fileConfig: redactConfigValue(fileConfig),
+        effectiveConfig,
+    };
+}
+export function validateRuntimeConfigCandidate(params) {
+    const rootDir = params.rootDir ?? process.cwd();
+    const resolvedPath = resolveConfigPath(rootDir, params.configPath);
+    if (params.config !== undefined) {
+        if (!isRecord(params.config)) {
+            return {
+                ok: false,
+                issues: ["config must be an object"],
+                message: "config must be an object",
+            };
+        }
+        return validateConfig(params.config, resolvedPath);
+    }
+    if (!isRecord(params.patch)) {
+        return {
+            ok: false,
+            issues: ["patch must be an object"],
+            message: "patch must be an object",
+        };
+    }
+    const currentConfig = loadRuntimeConfigFile(rootDir, params.configPath);
+    const candidate = mergePatch(currentConfig, params.patch);
+    return validateConfig(candidate, resolvedPath);
+}
+export async function patchRuntimeConfig(params) {
+    const rootDir = params.rootDir ?? process.cwd();
+    const metadata = readConfigMetadata({
+        rootDir,
+        configPath: params.configPath,
+    });
+    if (!isRecord(params.patch)) {
+        return {
+            ok: false,
+            issues: ["patch must be an object"],
+            message: "patch must be an object",
+            metadata,
+            restartRequired: false,
+        };
+    }
+    const currentConfig = loadRuntimeConfigFile(rootDir, params.configPath);
+    const nextConfig = mergePatch(currentConfig, params.patch);
+    const validation = validateConfig(nextConfig, metadata.configPath);
+    if (!validation.ok) {
+        return {
+            ...validation,
+            metadata,
+            restartRequired: false,
+        };
+    }
+    await mkdir(dirname(metadata.configPath), { recursive: true });
+    const existingText = await readExistingConfigText(metadata.configPath);
+    const backupPath = existingText === null ? undefined : backupPathFor(metadata.configPath);
+    if (backupPath && existingText !== null) {
+        await writeFile(backupPath, existingText, "utf-8");
+    }
+    const tempPath = `${metadata.configPath}.tmp-${process.pid}-${Date.now()}`;
+    await writeFile(tempPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8");
+    await rename(tempPath, metadata.configPath);
+    return {
+        ok: true,
+        config: redactConfigValue(nextConfig),
+        metadata: {
+            ...metadata,
+            exists: true,
+        },
+        ...(backupPath ? { backupPath } : {}),
+        restartRequired: true,
+    };
+}

package/dist/src/runtime/admin/system-control.d.ts

@@ -0,0 +1,89 @@
+export type RuntimeStatusResult = {
+    pid: number;
+    uptimeMs: number;
+    startedAt: string;
+    now: string;
+    cwd: string;
+    node: {
+        version: string;
+        platform: NodeJS.Platform;
+        arch: string;
+    };
+    memory: NodeJS.MemoryUsage;
+    config: {
+        rootDir: string;
+        configPath: string;
+        configExists: boolean;
+        traceFile: string;
+    };
+    restart: {
+        supported: boolean;
+        strategy: "systemctl-user";
+    };
+};
+export type RuntimeLogTailResult = {
+    path: string;
+    exists: boolean;
+    sizeBytes: number;
+    maxBytes: number;
+    lineCount: number;
+    lines: string[];
+    entries: unknown[];
+};
+export type RuntimeRestartRequest = {
+    reason?: string;
+    delayMs: number;
+};
+export type RuntimeRestartResult = {
+    accepted: true;
+    pid: number;
+    reason?: string;
+    delayMs: number;
+    scheduledAt: string;
+    strategy: "systemctl-user";
+    modelGateway?: {
+        scheduled: boolean;
+        url: string;
+    };
+};
+export type RuntimeRestartHandler = (request: RuntimeRestartRequest) => void | Promise<void>;
+export type RuntimeManagedServiceId = "runtime_prod" | "runtime_dev" | "model_gateway";
+export type RuntimeManagedServiceRestartRequest = {
+    serviceId: RuntimeManagedServiceId;
+    unit: string;
+    delayMs: number;
+};
+export type RuntimeManagedServiceRestartResult = {
+    accepted: true;
+    serviceId: RuntimeManagedServiceId;
+    unit: string;
+    label: string;
+    delayMs: number;
+    scheduledAt: string;
+    strategy: "systemctl-user";
+};
+export type RuntimeManagedServiceRestartHandler = (request: RuntimeManagedServiceRestartRequest) => void | Promise<void>;
+export type RuntimeModelGatewayRestartOptions = {
+    url?: string;
+    fetchImpl?: typeof fetch;
+};
+export declare function getRuntimeStatus(params?: {
+    rootDir?: string;
+    configPath?: string;
+    env?: Record<string, string | undefined>;
+}): RuntimeStatusResult;
+export declare function tailRuntimeLog(params?: {
+    rootDir?: string;
+    configPath?: string;
+    env?: Record<string, string | undefined>;
+    lines?: unknown;
+    maxBytes?: unknown;
+}): Promise<RuntimeLogTailResult>;
+export declare function requestRuntimeRestart(params?: {
+    reason?: unknown;
+    delayMs?: unknown;
+}, restartHandler?: RuntimeRestartHandler, modelGatewayRestart?: RuntimeModelGatewayRestartOptions): RuntimeRestartResult;
+export declare function requestRuntimeManagedServiceRestart(params?: {
+    serviceId?: unknown;
+    delayMs?: unknown;
+}, restartHandler?: RuntimeManagedServiceRestartHandler): RuntimeManagedServiceRestartResult;

package/dist/src/runtime/admin/system-control.js

@@ -0,0 +1,227 @@
+import { execFile } from "node:child_process";
+import { open, stat } from "node:fs/promises";
+import { promisify } from "node:util";
+import { loadRuntimeConfig } from "../config.js";
+import { getRuntimeConfig } from "./config-control.js";
+const execFileAsync = promisify(execFile);
+const STARTED_AT = new Date(Date.now() - process.uptime() * 1000);
+const DEFAULT_LOG_LINES = 200;
+const DEFAULT_LOG_MAX_BYTES = 64 * 1024;
+const MAX_LOG_LINES = 1000;
+const MAX_LOG_MAX_BYTES = 1024 * 1024;
+const DEFAULT_RESTART_DELAY_MS = 250;
+const MAX_RESTART_DELAY_MS = 30_000;
+const MANAGED_SERVICE_RESTART_UNITS = [
+    "model-gateway.service",
+    "abot.service",
+    "abot-dev.service",
+];
+const MANAGED_SERVICES = {
+    runtime_prod: {
+        unit: "llm-runtime.service",
+        label: "PROD runtime",
+    },
+    runtime_dev: {
+        unit: "llm-runtime-dev.service",
+        label: "DEV runtime",
+    },
+    model_gateway: {
+        unit: "model-gateway.service",
+        label: "Model gateway",
+    },
+};
+function runtimeConfigFromOptions(params) {
+    return loadRuntimeConfig({
+        rootDir: params.rootDir,
+        configPath: params.configPath,
+        env: params.env,
+    });
+}
+function readPositiveInt(value, fallback, max) {
+    const numeric = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number(value)
+            : NaN;
+    if (!Number.isFinite(numeric) || numeric <= 0) {
+        return fallback;
+    }
+    return Math.min(Math.floor(numeric), max);
+}
+function parseJsonLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return { raw: line };
+    }
+}
+async function readTailBytes(path, maxBytes) {
+    const fileStat = await stat(path);
+    const sizeBytes = fileStat.size;
+    const length = Math.min(sizeBytes, maxBytes);
+    if (length <= 0) {
+        return { sizeBytes, text: "" };
+    }
+    const file = await open(path, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        await file.read(buffer, 0, length, sizeBytes - length);
+        return {
+            sizeBytes,
+            text: buffer.toString("utf-8"),
+        };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function restartManagedServiceUnits(units) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    const runtimeDir = process.env.XDG_RUNTIME_DIR ??
+        (uid !== null ? `/run/user/${uid}` : undefined);
+    const busAddress = process.env.DBUS_SESSION_BUS_ADDRESS ??
+        (runtimeDir ? `unix:path=${runtimeDir}/bus` : undefined);
+    await execFileAsync("systemctl", ["--user", "restart", ...units], {
+        timeout: 20_000,
+        env: {
+            ...process.env,
+            ...(runtimeDir ? { XDG_RUNTIME_DIR: runtimeDir } : {}),
+            ...(busAddress ? { DBUS_SESSION_BUS_ADDRESS: busAddress } : {}),
+        },
+    });
+}
+function defaultRestartHandler() {
+    return restartManagedServiceUnits(MANAGED_SERVICE_RESTART_UNITS);
+}
+function defaultManagedServiceRestartHandler(request) {
+    return restartManagedServiceUnits([request.unit]);
+}
+function resolveManagedServiceId(value) {
+    if (typeof value !== "string") {
+        throw new Error("invalid_service_id");
+    }
+    const serviceId = value.trim();
+    if (!(serviceId in MANAGED_SERVICES)) {
+        throw new Error("invalid_service_id");
+    }
+    return serviceId;
+}
+export function getRuntimeStatus(params = {}) {
+    const config = runtimeConfigFromOptions(params);
+    const metadata = getRuntimeConfig(params).metadata;
+    return {
+        pid: process.pid,
+        uptimeMs: Math.floor(process.uptime() * 1000),
+        startedAt: STARTED_AT.toISOString(),
+        now: new Date().toISOString(),
+        cwd: process.cwd(),
+        node: {
+            version: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        memory: process.memoryUsage(),
+        config: {
+            rootDir: metadata.rootDir,
+            configPath: metadata.configPath,
+            configExists: metadata.exists,
+            traceFile: config.paths.traceFile,
+        },
+        restart: {
+            supported: true,
+            strategy: "systemctl-user",
+        },
+    };
+}
+export async function tailRuntimeLog(params = {}) {
+    const config = runtimeConfigFromOptions(params);
+    const linesLimit = readPositiveInt(params.lines, DEFAULT_LOG_LINES, MAX_LOG_LINES);
+    const maxBytes = readPositiveInt(params.maxBytes, DEFAULT_LOG_MAX_BYTES, MAX_LOG_MAX_BYTES);
+    try {
+        const tail = await readTailBytes(config.paths.traceFile, maxBytes);
+        const lines = tail.text.split(/\r?\n/).filter(Boolean).slice(-linesLimit);
+        return {
+            path: config.paths.traceFile,
+            exists: true,
+            sizeBytes: tail.sizeBytes,
+            maxBytes,
+            lineCount: lines.length,
+            lines,
+            entries: lines.map(parseJsonLine),
+        };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return {
+                path: config.paths.traceFile,
+                exists: false,
+                sizeBytes: 0,
+                maxBytes,
+                lineCount: 0,
+                lines: [],
+                entries: [],
+            };
+        }
+        throw error;
+    }
+}
+export function requestRuntimeRestart(params = {}, restartHandler = defaultRestartHandler, modelGatewayRestart = {}) {
+    const reason = typeof params.reason === "string" && params.reason.trim()
+        ? params.reason.trim()
+        : undefined;
+    const delayMs = readPositiveInt(params.delayMs, DEFAULT_RESTART_DELAY_MS, MAX_RESTART_DELAY_MS);
+    const request = {
+        ...(reason ? { reason } : {}),
+        delayMs,
+    };
+    void modelGatewayRestart;
+    const timer = setTimeout(() => {
+        const restart = async () => {
+            await restartHandler(request);
+        };
+        void restart().catch(() => {
+            process.exit(1);
+        });
+    }, delayMs);
+    timer.unref?.();
+    return {
+        accepted: true,
+        pid: process.pid,
+        ...(reason ? { reason } : {}),
+        delayMs,
+        scheduledAt: new Date().toISOString(),
+        strategy: "systemctl-user",
+    };
+}
+export function requestRuntimeManagedServiceRestart(params = {}, restartHandler = defaultManagedServiceRestartHandler) {
+    const serviceId = resolveManagedServiceId(params.serviceId);
+    const service = MANAGED_SERVICES[serviceId];
+    const delayMs = readPositiveInt(params.delayMs, DEFAULT_RESTART_DELAY_MS, MAX_RESTART_DELAY_MS);
+    const request = {
+        serviceId,
+        unit: service.unit,
+        delayMs,
+    };
+    const timer = setTimeout(() => {
+        const restart = async () => {
+            await restartHandler(request);
+        };
+        void restart().catch(() => {
+            process.exit(1);
+        });
+    }, delayMs);
+    timer.unref?.();
+    return {
+        accepted: true,
+        serviceId,
+        unit: service.unit,
+        label: service.label,
+        delayMs,
+        scheduledAt: new Date().toISOString(),
+        strategy: "systemctl-user",
+    };
+}

package/dist/src/runtime/attachments/store.d.ts

@@ -0,0 +1,32 @@
+import type { RuntimeAttachmentKind, RuntimeAttachmentReference } from "../../shared/attachments.js";
+export type { RuntimeAttachmentKind, RuntimeAttachmentReference };
+export type RuntimeAttachmentSaveInput = {
+    sessionId: string;
+    requestId: string;
+    kind: RuntimeAttachmentKind;
+    mimeType: string;
+    bytes: Uint8Array;
+    name?: string;
+};
+export type RuntimeAttachmentResolution = {
+    metadata: RuntimeAttachmentReference;
+    absolutePath: string;
+};
+export type RuntimeAttachmentStore = {
+    saveAttachment: (input: RuntimeAttachmentSaveInput) => Promise<RuntimeAttachmentReference>;
+    validateAttachmentReferences: (attachments: RuntimeAttachmentReference[], options?: {
+        sessionId?: string;
+    }) => Promise<RuntimeAttachmentReference[]>;
+    resolveAttachment: (attachment: RuntimeAttachmentReference) => Promise<RuntimeAttachmentResolution>;
+    deleteAttachment?: (attachment: RuntimeAttachmentReference, options?: {
+        sessionId?: string;
+    }) => Promise<void>;
+    deleteSessionAttachments: (sessionId: string) => Promise<void>;
+};
+export type FileAttachmentStoreOptions = {
+    attachmentsDir: string;
+    maxAttachmentBytes?: number;
+};
+export declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+export declare function parseRuntimeAttachmentReferences(value: unknown): RuntimeAttachmentReference[];
+export declare function createFileAttachmentStore(options: FileAttachmentStoreOptions): RuntimeAttachmentStore;