@abot-ai/runtime 1.0.0

package/dist/src/cli/abot.js

@@ -0,0 +1,102 @@
+import { join, resolve } from "node:path";
+import { runAddRuntimeModel } from "../../scripts/add-runtime-model.js";
+import { runInitRuntime } from "../../scripts/init-runtime.js";
+import { createModelGatewayServer, resolveModelGatewayPort, } from "../model-gateway/server.js";
+import { loadDotEnvFile } from "../shared/load-dotenv.js";
+import { startWebUiServer } from "../web-ui/server.js";
+import { resolveWebUiAddress } from "../web-ui/web-ui-address.js";
+function printHelp() {
+    console.log([
+        "ABot Runtime",
+        "",
+        "Usage:",
+        "  abot init --provider <provider> --model <model-id> [options]",
+        "  abot add-model --profile <profile-id> --provider <provider> --model <model-id> [options]",
+        "  abot start",
+        "",
+        "Commands:",
+        "  init       Create the first machine-local runtime configuration.",
+        "  add-model  Add a provider/model profile without replacing existing ones.",
+        "  start      Start the local model gateway and Web UI.",
+    ].join("\n"));
+}
+function closeServer(server) {
+    return new Promise((resolveClose, reject) => {
+        server.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolveClose();
+        });
+    });
+}
+async function runStart(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log("Usage: abot start");
+        return;
+    }
+    if (args.length > 0) {
+        throw new Error(`unknown start argument: ${args[0]}`);
+    }
+    const rootDir = process.cwd();
+    loadDotEnvFile(join(rootDir, ".env"));
+    const webAddress = resolveWebUiAddress(process.env);
+    const appDir = resolve(import.meta.dirname, "../web-ui/app");
+    let gateway;
+    try {
+        gateway = createModelGatewayServer();
+        const gatewayPort = resolveModelGatewayPort();
+        gateway.listen(gatewayPort, "127.0.0.1", () => {
+            console.log(`model gateway listening on http://127.0.0.1:${gatewayPort}`);
+        });
+    }
+    catch (error) {
+        console.warn(`model gateway not started: ${error instanceof Error ? error.message : String(error)}`);
+        console.warn("Complete model setup, stop ABot, and run abot start again.");
+    }
+    const webUi = startWebUiServer({
+        appDir,
+        rootDir,
+        host: webAddress.listenHost,
+        port: webAddress.port,
+        setupCommandMode: "package",
+    });
+    console.log(`Open ${webAddress.browserUrl}`);
+    await new Promise((resolveExit, rejectExit) => {
+        let closing = false;
+        const shutdown = () => {
+            if (closing)
+                return;
+            closing = true;
+            void Promise.all([
+                webUi.close(),
+                ...(gateway ? [closeServer(gateway)] : []),
+            ]).then(() => resolveExit(), rejectExit);
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}
+export async function runAbotCli(argv = process.argv.slice(2)) {
+    const [command, ...args] = argv;
+    if (!command ||
+        command === "help" ||
+        command === "--help" ||
+        command === "-h") {
+        printHelp();
+        return;
+    }
+    if (command === "init") {
+        await runInitRuntime(args, { commandMode: "package" });
+        return;
+    }
+    if (command === "add-model") {
+        await runAddRuntimeModel(args, { commandMode: "package" });
+        return;
+    }
+    if (command === "start") {
+        await runStart(args);
+        return;
+    }
+    throw new Error(`unknown command: ${command}`);
+}

package/dist/src/cli/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runAbotCli } from "./abot.js";
+runAbotCli().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/src/model-gateway/client/chat.d.ts

@@ -0,0 +1,5 @@
+import type { InvokeModelGatewayParams, ModelGatewayClientOptions, StreamMeta } from "./contracts.js";
+export declare function invokeModelGatewayWithOptions(params: InvokeModelGatewayParams, options?: ModelGatewayClientOptions): Promise<{
+    text: string;
+    meta: StreamMeta;
+}>;

package/dist/src/model-gateway/client/chat.js

@@ -0,0 +1,116 @@
+import { traceDebug } from "../../runtime/observability/debug-logger.js";
+import { buildModelInvocationMetrics } from "./invocation-metrics.js";
+import { buildChatGatewayRequestBody, resolveMetricMessages, resolveRequestMessages, } from "./message-projection.js";
+import { resolveClientOptions } from "./options.js";
+import { ChatStreamAccumulator, classifyEmptyResponse, InactivityBoundStreamReader, } from "./stream-consumer.js";
+export async function invokeModelGatewayWithOptions(params, options = {}) {
+    const clientOptions = resolveClientOptions(options);
+    const url = clientOptions.baseUrl;
+    const requestId = typeof params.debugRequestId === "string" ? params.debugRequestId : "";
+    const requestMessages = resolveRequestMessages(params);
+    const metricMessages = resolveMetricMessages(params);
+    const startedAt = Date.now();
+    const modelPolicy = params.modelPolicy ?? clientOptions.modelPolicy;
+    const requestBody = buildChatGatewayRequestBody(params, requestMessages, modelPolicy);
+    traceDebug("model-gateway.client", "chat.request.start", {
+        requestId,
+        url: `${url}/chat`,
+        agentMode: params.agentMode,
+        taskType: params.taskType,
+        modelStep: params.modelStep,
+        modelPreference: params.modelPreference,
+        modelPolicyDefaultProfileId: modelPolicy?.defaults?.profileId,
+        textLength: typeof params.text === "string" ? params.text.length : 0,
+        messageCount: requestMessages.length,
+    });
+    const response = await fetch(url + "/chat", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        signal: params.abortSignal,
+        body: JSON.stringify(requestBody),
+    });
+    traceDebug("model-gateway.client", "chat.response.received", {
+        requestId,
+        status: response.status,
+        ok: response.ok,
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        traceDebug("model-gateway.client", "chat.response.error", {
+            requestId,
+            status: response.status,
+            bodyLength: errorText.length,
+            bodyPreview: errorText.slice(0, 400),
+        });
+        throw new Error(`bridge_request_failed:${response.status}:${errorText || "empty error body"}`);
+    }
+    if (!response.body) {
+        traceDebug("model-gateway.client", "chat.response.no_body", {
+            requestId,
+        });
+        throw new Error("no stream");
+    }
+    const streamReader = new InactivityBoundStreamReader(response.body.getReader(), params.abortSignal, clientOptions.getStreamInactivityTimeoutMs);
+    const stream = new ChatStreamAccumulator(params);
+    while (true) {
+        const { done, value } = await streamReader.read();
+        if (done)
+            break;
+        stream.acceptChunk(value);
+    }
+    stream.flushPending();
+    const meta = stream.toMeta(response.status);
+    traceDebug("model-gateway.client", "chat.stream.completed", {
+        requestId,
+        chunkCount: meta.chunkCount,
+        totalBytes: meta.totalBytes,
+        thinkingEvents: meta.thinkingEvents,
+        contentEvents: meta.contentEvents,
+        contentEmptyEvents: meta.contentEmptyEvents,
+        invalidJsonLines: meta.invalidJsonLines,
+        unknownTypeCounts: meta.unknownTypeCounts,
+        outputLength: stream.text.length,
+        terminalEventCount: meta.terminalEventCount,
+        ...(stream.providerCompletionReason !== undefined
+            ? { providerCompletionReason: stream.providerCompletionReason }
+            : {}),
+        ...(stream.providerUsage ? { usage: stream.providerUsage } : {}),
+    });
+    if (stream.text.trim().length === 0) {
+        const emptyReason = classifyEmptyResponse(meta);
+        traceDebug("model-gateway.client", "chat.stream.empty_output", {
+            requestId,
+            emptyReason,
+            responseShape: {
+                status: meta.status,
+                chunkCount: meta.chunkCount,
+                totalBytes: meta.totalBytes,
+                thinkingEvents: meta.thinkingEvents,
+                contentEvents: meta.contentEvents,
+                contentEmptyEvents: meta.contentEmptyEvents,
+                invalidJsonLines: meta.invalidJsonLines,
+                unknownTypeCounts: meta.unknownTypeCounts,
+            },
+        });
+        meta.emptyReason = emptyReason;
+    }
+    traceDebug("runtime.model", "model.invocation.metrics", buildModelInvocationMetrics({
+        requestId,
+        modelStep: params.modelStep,
+        taskType: params.taskType,
+        agentMode: params.agentMode,
+        text: params.text,
+        messages: metricMessages,
+        outputText: stream.text,
+        providerUsage: stream.providerUsage,
+        terminalEventCount: meta.terminalEventCount,
+        ...(stream.providerCompletionReason !== undefined
+            ? { providerCompletionReason: stream.providerCompletionReason }
+            : {}),
+        durationMs: Date.now() - startedAt,
+        status: "success",
+    }));
+    return { text: stream.text, meta };
+}

package/dist/src/model-gateway/client/contracts.d.ts

@@ -0,0 +1,71 @@
+import type { AgentMode, ModelReasoningLevel, ModelStep } from "../../shared/types.js";
+import type { StreamCallbacks } from "../client-stream-parser.js";
+import type { ModelGatewayAttachment, ModelGatewayPolicyConfig, ModelPreference, ModelTokenUsage } from "../types.js";
+export type ModelMetricMessage = {
+    role: string;
+    content: string;
+    systemMessageKind?: string;
+    contextMessageKind?: string;
+    attachments?: ModelGatewayAttachment[];
+    toolCallCount?: number;
+    toolResultCount?: number;
+};
+export type InvokeModelGatewayParams = StreamCallbacks & {
+    text?: string;
+    messages?: unknown;
+    agentMode: AgentMode;
+    taskType?: string;
+    modelStep?: ModelStep;
+    modelOverride?: string;
+    reasoningOverride?: ModelReasoningLevel;
+    modelPreference?: ModelPreference;
+    modelPolicy?: ModelGatewayPolicyConfig;
+    abortSignal: AbortSignal;
+    debugRequestId?: string;
+    format?: "json" | Record<string, unknown>;
+};
+export type InvokeRawModelGatewayParams = {
+    prompt: string;
+    agentMode: AgentMode;
+    taskType?: string;
+    modelStep?: ModelStep;
+    modelOverride?: string;
+    reasoningOverride?: ModelReasoningLevel;
+    modelPreference?: ModelPreference;
+    modelPolicy?: ModelGatewayPolicyConfig;
+    abortSignal: AbortSignal;
+    debugRequestId?: string;
+    format?: "json" | Record<string, unknown>;
+};
+export type ModelGatewayClientOptions = {
+    baseUrl?: string;
+    streamInactivityTimeoutMs?: number;
+    modelPolicy?: ModelGatewayPolicyConfig;
+    inputTokenCountProviders?: readonly string[];
+};
+export type EmptyResponseReason = "thinking_only_response" | "parser_or_stream_assembly_failure" | "unrecognized_stream_event_shape" | "content_events_without_text" | "empty_stream_body" | "unknown_empty_response";
+export type StreamMeta = {
+    status: number;
+    chunkCount: number;
+    totalBytes: number;
+    thinkingEvents: number;
+    contentEvents: number;
+    contentEmptyEvents: number;
+    invalidJsonLines: number;
+    unknownTypeCounts: Record<string, number>;
+    outputLength: number;
+    terminalEventCount: number;
+    providerCompletionReason?: string | null;
+    emptyReason?: EmptyResponseReason;
+    usage?: ModelTokenUsage;
+};
+export type RawModelGatewayResult = {
+    text: string;
+    meta: {
+        status: number;
+        outputLength: number;
+        thinkingLength: number;
+        providerCompletionReason?: string | null;
+        usage?: ModelTokenUsage;
+    };
+};

package/dist/src/model-gateway/client/contracts.js

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

package/dist/src/model-gateway/client/input-token-count.d.ts

@@ -0,0 +1,4 @@
+import type { ModelGatewayInputTokenCountParams, ModelGatewayInputTokenCountResult } from "../types.js";
+import type { ModelGatewayClientOptions } from "./contracts.js";
+export type InputTokenCountCache = Map<string, ModelGatewayInputTokenCountResult>;
+export declare function countModelGatewayInputTokensWithOptions(params: ModelGatewayInputTokenCountParams, options?: ModelGatewayClientOptions, cache?: InputTokenCountCache): Promise<ModelGatewayInputTokenCountResult | undefined>;

package/dist/src/model-gateway/client/input-token-count.js

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { traceDebug } from "../../runtime/observability/debug-logger.js";
+import { buildChatGatewayRequestBody, resolveRequestMessages, } from "./message-projection.js";
+import { resolveClientOptions } from "./options.js";
+const INPUT_TOKEN_COUNT_CACHE_MAX_ENTRIES = 64;
+function createInputTokenCountCacheKey(provider, requestBody) {
+    return createHash("sha256")
+        .update(provider)
+        .update("\0")
+        .update(JSON.stringify(requestBody))
+        .digest("hex");
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isPositiveSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function parseInputTokenCountResult(value) {
+    const body = value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+    const inputTokens = body.inputTokens;
+    const contextWindowTokens = body.contextWindowTokens;
+    const profileId = body.profileId;
+    const provider = body.provider;
+    const model = body.model;
+    const hasValidTokenCounts = isNonNegativeSafeInteger(inputTokens) &&
+        isPositiveSafeInteger(contextWindowTokens);
+    const hasValidModelBinding = isNonEmptyString(profileId) &&
+        isNonEmptyString(provider) &&
+        isNonEmptyString(model);
+    const hasExpectedSource = body.source === "provider_input_token_count";
+    const isValidResponse = hasValidTokenCounts && hasValidModelBinding && hasExpectedSource;
+    if (!isValidResponse) {
+        throw new Error("model_gateway_input_token_count_response_invalid");
+    }
+    return Object.freeze({
+        inputTokens,
+        contextWindowTokens,
+        profileId,
+        provider,
+        model,
+        source: "provider_input_token_count",
+    });
+}
+function updateInputTokenCountCache(cache, cacheKey, result) {
+    if (!cache) {
+        return;
+    }
+    cache.set(cacheKey, result);
+    if (cache.size <= INPUT_TOKEN_COUNT_CACHE_MAX_ENTRIES) {
+        return;
+    }
+    const oldestKey = cache.keys().next().value;
+    if (typeof oldestKey === "string") {
+        cache.delete(oldestKey);
+    }
+}
+export async function countModelGatewayInputTokensWithOptions(params, options = {}, cache) {
+    const clientOptions = resolveClientOptions(options);
+    const provider = params.provider.trim();
+    if (!clientOptions.inputTokenCountProviders.has(provider)) {
+        return undefined;
+    }
+    const requestMessages = resolveRequestMessages(params);
+    const modelPolicy = params.modelPolicy ?? clientOptions.modelPolicy;
+    const requestBody = buildChatGatewayRequestBody(params, requestMessages, modelPolicy);
+    const cacheKey = createInputTokenCountCacheKey(provider, requestBody);
+    const cached = cache?.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const requestId = params.debugRequestId?.trim() ?? "";
+    const startedAt = Date.now();
+    traceDebug("model-gateway.client", "input_tokens.request.start", {
+        requestId,
+        url: `${clientOptions.baseUrl}/input-tokens`,
+        provider,
+        modelStep: params.modelStep,
+        messageCount: requestMessages.length,
+    });
+    const response = await fetch(`${clientOptions.baseUrl}/input-tokens`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        signal: params.abortSignal,
+        body: JSON.stringify(requestBody),
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        throw new Error(`bridge_input_token_count_failed:${response.status}:${errorText || "empty error body"}`);
+    }
+    const result = parseInputTokenCountResult(await response.json().catch(() => undefined));
+    if (result.provider !== provider) {
+        throw new Error("model_gateway_input_token_count_provider_mismatch");
+    }
+    traceDebug("model-gateway.client", "input_tokens.request.completed", {
+        requestId,
+        provider: result.provider,
+        profileId: result.profileId,
+        model: result.model,
+        inputTokens: result.inputTokens,
+        durationMs: Date.now() - startedAt,
+    });
+    updateInputTokenCountCache(cache, cacheKey, result);
+    return result;
+}

package/dist/src/model-gateway/client/invocation-metrics.d.ts

@@ -0,0 +1,17 @@
+import type { ModelTokenUsage } from "../types.js";
+import type { ModelMetricMessage } from "./contracts.js";
+export declare function buildModelInvocationMetrics(params: {
+    requestId?: string;
+    modelStep?: string;
+    taskType?: string;
+    agentMode?: string;
+    text?: string;
+    messages?: ModelMetricMessage[];
+    outputText?: string;
+    providerUsage?: ModelTokenUsage;
+    terminalEventCount?: number;
+    providerCompletionReason?: string | null;
+    durationMs: number;
+    status: "success" | "error";
+    error?: string;
+}): Record<string, unknown>;

package/dist/src/model-gateway/client/invocation-metrics.js

@@ -0,0 +1,107 @@
+function countMessageChars(messages, role) {
+    return (messages ?? [])
+        .filter((message) => !role || message.role === role)
+        .reduce((sum, message) => sum + message.content.length, 0);
+}
+function countMessages(messages, role) {
+    return (messages ?? []).filter((message) => !role || message.role === role)
+        .length;
+}
+function estimateTokens(chars) {
+    return Math.ceil(chars / 4);
+}
+function getSystemMessageMetricCategory(message) {
+    if (message.systemMessageKind) {
+        return message.systemMessageKind;
+    }
+    if (message.contextMessageKind) {
+        return message.contextMessageKind;
+    }
+    const normalized = message.content.trim();
+    const firstLine = normalized.split("\n")[0]?.trim() || "unknown_system";
+    return `system:${firstLine.slice(0, 80)}`;
+}
+function buildSystemMessageBreakdown(messages) {
+    const byCategory = new Map();
+    for (const message of messages ?? []) {
+        if (message.role !== "system") {
+            continue;
+        }
+        const category = getSystemMessageMetricCategory(message);
+        const current = byCategory.get(category) ?? { count: 0, chars: 0 };
+        current.count += 1;
+        current.chars += message.content.length;
+        byCategory.set(category, current);
+    }
+    return [...byCategory.entries()]
+        .map(([category, value]) => ({
+        category,
+        count: value.count,
+        chars: value.chars,
+        estimatedTokens: estimateTokens(value.chars),
+    }))
+        .sort((left, right) => right.chars - left.chars);
+}
+export function buildModelInvocationMetrics(params) {
+    const textChars = params.text?.length ?? 0;
+    const messagesChars = countMessageChars(params.messages);
+    const toolCallCount = (params.messages ?? []).reduce((total, message) => total + (message.toolCallCount ?? 0), 0);
+    const toolResultCount = (params.messages ?? []).reduce((total, message) => total + (message.toolResultCount ?? 0), 0);
+    const systemChars = countMessageChars(params.messages, "system");
+    const nonSystemChars = messagesChars - systemChars;
+    const totalInputChars = messagesChars > 0 ? messagesChars : textChars;
+    const outputChars = params.outputText?.length ?? 0;
+    const systemMessageBreakdown = buildSystemMessageBreakdown(params.messages);
+    const estimatedInputTokens = estimateTokens(totalInputChars);
+    const estimatedOutputTokens = estimateTokens(outputChars);
+    const inputTokens = params.providerUsage?.inputTokens ?? estimatedInputTokens;
+    const outputTokens = params.providerUsage?.outputTokens ?? estimatedOutputTokens;
+    const totalTokens = params.providerUsage?.totalTokens ?? inputTokens + outputTokens;
+    const cachedInputTokens = params.providerUsage?.cachedInputTokens;
+    return {
+        requestId: params.requestId ?? "",
+        modelStep: params.modelStep ?? "",
+        taskType: params.taskType ?? "",
+        agentMode: params.agentMode ?? "",
+        messageCount: countMessages(params.messages),
+        systemMessageCount: countMessages(params.messages, "system"),
+        nonSystemMessageCount: countMessages(params.messages) - countMessages(params.messages, "system"),
+        textChars,
+        messagesChars,
+        ...(toolCallCount > 0 || toolResultCount > 0
+            ? { toolCallCount, toolResultCount }
+            : {}),
+        inputCharsSource: messagesChars > 0 ? "messages" : "text",
+        systemChars,
+        nonSystemChars,
+        systemMessageBreakdown,
+        largestSystemMessageCategory: systemMessageBreakdown[0]?.category ?? "",
+        largestSystemMessageChars: systemMessageBreakdown[0]?.chars ?? 0,
+        totalInputChars,
+        estimatedInputTokens,
+        outputChars,
+        estimatedOutputTokens,
+        tokenUsageSource: params.providerUsage ? "provider" : "estimated",
+        inputTokens,
+        outputTokens,
+        totalTokens,
+        ...(cachedInputTokens !== undefined
+            ? {
+                cachedInputTokens,
+                uncachedInputTokens: inputTokens - cachedInputTokens,
+            }
+            : {}),
+        ...(params.providerUsage?.reasoningTokens !== undefined
+            ? { reasoningTokens: params.providerUsage.reasoningTokens }
+            : {}),
+        ...(params.terminalEventCount !== undefined
+            ? { terminalEventCount: params.terminalEventCount }
+            : {}),
+        ...("providerCompletionReason" in params
+            ? { providerCompletionReason: params.providerCompletionReason }
+            : {}),
+        durationMs: params.durationMs,
+        status: params.status,
+        ...(params.error ? { error: params.error } : {}),
+    };
+}

package/dist/src/model-gateway/client/message-projection.d.ts

@@ -0,0 +1,23 @@
+import type { AgentMode, ModelReasoningLevel, ModelStep } from "../../shared/types.js";
+import type { ChatMessage, ModelGatewayPolicyConfig, ModelPreference } from "../types.js";
+import type { ModelMetricMessage } from "./contracts.js";
+export declare function projectModelGatewayMetricMessages(messages: readonly ChatMessage[]): ModelMetricMessage[];
+export declare function resolveRequestMessages(params: {
+    text?: string;
+    messages?: unknown;
+}): ChatMessage[];
+export declare function buildChatGatewayRequestBody(params: Readonly<{
+    text?: string;
+    agentMode: AgentMode;
+    taskType?: string;
+    modelStep?: ModelStep;
+    modelOverride?: string;
+    reasoningOverride?: ModelReasoningLevel;
+    modelPreference?: ModelPreference;
+    debugRequestId?: string;
+    format?: "json" | Record<string, unknown>;
+}>, messages: readonly ChatMessage[], modelPolicy: ModelGatewayPolicyConfig | undefined): Record<string, unknown>;
+export declare function resolveMetricMessages(params: {
+    text?: string;
+    messages?: unknown;
+}): ModelMetricMessage[];