@abot-ai/runtime 1.0.0

package/dist/src/runtime/config/runner/contracts.js

@@ -0,0 +1,6 @@
+import { MODEL_STEPS } from "../../../shared/model-steps.js";
+/** Every model step invoked by runtime and therefore requiring both policy and timeout config. */
+export const REQUEST_INVOKED_STEP_IDS = Object.values(MODEL_STEPS);
+export const REQUEST_STEP_INSTRUCTION_REF_MAX_COUNT = 8;
+export const REQUEST_STEP_INSTRUCTION_MAX_LENGTH = 32_000;
+export const REQUEST_STEP_INSTRUCTIONS_MAX_LENGTH = 48_000;

package/dist/src/runtime/config/runner/instruction-refs.d.ts

@@ -0,0 +1,6 @@
+import { type RequestStepInstructionBlock } from "./contracts.js";
+export declare function loadRequestStepInstructionBlocks(params: {
+    configPath: string;
+    stepId: string;
+    rawRefs: unknown;
+}): readonly RequestStepInstructionBlock[];

package/dist/src/runtime/config/runner/instruction-refs.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { REQUEST_STEP_INSTRUCTION_MAX_LENGTH, REQUEST_STEP_INSTRUCTION_REF_MAX_COUNT, REQUEST_STEP_INSTRUCTIONS_MAX_LENGTH, } from "./contracts.js";
+import { formatConfigError, invalidRuntimeConfig, requireConfigStringArray, } from "./validation.js";
+export function loadRequestStepInstructionBlocks(params) {
+    const field = `steps.${params.stepId}.instructionRefs`;
+    const refs = requireConfigStringArray(params.rawRefs, params.configPath, field);
+    if (refs.length === 0 ||
+        refs.length > REQUEST_STEP_INSTRUCTION_REF_MAX_COUNT) {
+        throw invalidRuntimeConfig(params.configPath, `${field} must contain between 1 and ${REQUEST_STEP_INSTRUCTION_REF_MAX_COUNT} unique Markdown references`);
+    }
+    const blocks = refs.map((ref, index) => loadInstructionBlock({
+        configPath: params.configPath,
+        field: `${field}[${index}]`,
+        ref,
+    }));
+    const totalLength = blocks.reduce((total, block) => total + block.content.length, 0);
+    if (totalLength > REQUEST_STEP_INSTRUCTIONS_MAX_LENGTH) {
+        throw invalidRuntimeConfig(params.configPath, `${field} content must contain at most ${REQUEST_STEP_INSTRUCTIONS_MAX_LENGTH} characters in total`);
+    }
+    return blocks;
+}
+function loadInstructionBlock(params) {
+    const resolvedPath = isAbsolute(params.ref)
+        ? resolve(params.ref)
+        : resolve(dirname(params.configPath), params.ref);
+    if (extname(resolvedPath).toLowerCase() !== ".md") {
+        throw invalidRuntimeConfig(params.configPath, `${params.field} must reference a Markdown file`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(resolvedPath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Unable to read runtime step instructions at ${resolvedPath}: ${formatConfigError(error)}`);
+    }
+    const content = raw.trim();
+    if (content.length === 0 ||
+        content.length > REQUEST_STEP_INSTRUCTION_MAX_LENGTH) {
+        throw invalidRuntimeConfig(params.configPath, `${params.field} content must contain between 1 and ${REQUEST_STEP_INSTRUCTION_MAX_LENGTH} characters`);
+    }
+    return {
+        ref: params.ref,
+        content,
+        contentHash: createHash("sha256").update(content).digest("hex"),
+    };
+}

package/dist/src/runtime/config/runner/loader.d.ts

@@ -0,0 +1,4 @@
+import { type RequestRunnerConfig } from "./contracts.js";
+export declare function loadRequestRunnerConfig(params: {
+    configPath: string;
+}): RequestRunnerConfig;

package/dist/src/runtime/config/runner/loader.js

@@ -0,0 +1,100 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { REQUEST_INVOKED_STEP_IDS, } from "./contracts.js";
+import { loadRequestStepInstructionBlocks } from "./instruction-refs.js";
+import { formatConfigError, invalidRuntimeConfig, deepFreezeConfig, requireExactConfigKeys, requireConfigRecord, requireConfigString, requireConfigStringMap, requirePositiveConfigInteger, } from "./validation.js";
+const configCache = new Map();
+export function loadRequestRunnerConfig(params) {
+    const configuredPath = params.configPath.trim();
+    if (!configuredPath || !isAbsolute(configuredPath)) {
+        throw new Error("runtime request runner configPath must be an absolute path resolved from runtime config");
+    }
+    const configPath = resolve(configuredPath);
+    const cached = configCache.get(configPath);
+    if (cached) {
+        return cached;
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Unable to read runtime request runner config at ${configPath}: ${formatConfigError(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid runtime request runner config JSON at ${configPath}: ${formatConfigError(error)}`);
+    }
+    const config = deepFreezeConfig(parseRequestRunnerConfig(parsed, configPath));
+    configCache.set(configPath, config);
+    return config;
+}
+function parseRequestRunnerConfig(value, configPath) {
+    const root = requireConfigRecord(value, configPath, "root");
+    const models = requireConfigRecord(root.models, configPath, "models");
+    requireExactConfigKeys(models, ["defaults"], configPath, "models");
+    const modelDefaults = requireConfigRecord(models.defaults, configPath, "models.defaults");
+    requireExactConfigKeys(modelDefaults, ["profileId", "steps"], configPath, "models.defaults");
+    const profileId = requireConfigString(modelDefaults.profileId, configPath, "models.defaults.profileId");
+    const rawModelSteps = requireConfigRecord(modelDefaults.steps, configPath, "models.defaults.steps");
+    for (const stepId of REQUEST_INVOKED_STEP_IDS) {
+        if (!Object.hasOwn(rawModelSteps, stepId)) {
+            throw invalidRuntimeConfig(configPath, `models.defaults.steps.${stepId} must select a model profile or calibration slot`);
+        }
+    }
+    requireExactConfigKeys(rawModelSteps, REQUEST_INVOKED_STEP_IDS, configPath, "models.defaults.steps");
+    const modelSteps = requireConfigStringMap(rawModelSteps, configPath, "models.defaults.steps");
+    const rawContext = requireConfigRecord(root.context, configPath, "context");
+    requireExactConfigKeys(root, ["models", "context", "steps"], configPath, "root");
+    requireExactConfigKeys(rawContext, [
+        "outputReserveTokens",
+        "safetyReserveTokens",
+        "attachmentReserveTokens",
+    ], configPath, "context");
+    const context = {
+        outputReserveTokens: requirePositiveConfigInteger(rawContext.outputReserveTokens, configPath, "context.outputReserveTokens"),
+        safetyReserveTokens: requirePositiveConfigInteger(rawContext.safetyReserveTokens, configPath, "context.safetyReserveTokens"),
+        attachmentReserveTokens: requirePositiveConfigInteger(rawContext.attachmentReserveTokens, configPath, "context.attachmentReserveTokens"),
+    };
+    const rawSteps = requireConfigRecord(root.steps, configPath, "steps");
+    for (const stepId of REQUEST_INVOKED_STEP_IDS) {
+        if (!Object.hasOwn(rawSteps, stepId)) {
+            throw invalidRuntimeConfig(configPath, `steps.${stepId} is required`);
+        }
+    }
+    requireExactConfigKeys(rawSteps, REQUEST_INVOKED_STEP_IDS, configPath, "steps");
+    const steps = Object.fromEntries(REQUEST_INVOKED_STEP_IDS.map((stepId) => {
+        const rawStep = rawSteps[stepId];
+        const step = requireConfigRecord(rawStep, configPath, `steps.${stepId}`);
+        const hasInstructionRefs = Object.hasOwn(step, "instructionRefs");
+        requireExactConfigKeys(step, ["timeoutMs", ...(hasInstructionRefs ? ["instructionRefs"] : [])], configPath, `steps.${stepId}`);
+        return [
+            stepId,
+            {
+                timeoutMs: requirePositiveConfigInteger(step.timeoutMs, configPath, `steps.${stepId}.timeoutMs`),
+                ...(hasInstructionRefs
+                    ? {
+                        instructionBlocks: loadRequestStepInstructionBlocks({
+                            configPath,
+                            stepId,
+                            rawRefs: step.instructionRefs,
+                        }),
+                    }
+                    : {}),
+            },
+        ];
+    }));
+    return {
+        models: {
+            defaults: {
+                profileId,
+                steps: modelSteps,
+            },
+        },
+        context,
+        steps,
+    };
+}

package/dist/src/runtime/config/runner/model-policy.d.ts

@@ -0,0 +1,6 @@
+import type { ModelGatewayPolicyConfig } from "../../../model-gateway/types.js";
+import type { RequestRunnerConfig } from "./contracts.js";
+export declare function createRequestModelPolicy(params: {
+    platformPolicy?: ModelGatewayPolicyConfig;
+    runnerConfig: RequestRunnerConfig;
+}): ModelGatewayPolicyConfig;

package/dist/src/runtime/config/runner/model-policy.js

@@ -0,0 +1,26 @@
+export function createRequestModelPolicy(params) {
+    const platformDefaults = params.platformPolicy?.defaults;
+    return {
+        ...(params.platformPolicy?.providers
+            ? { providers: params.platformPolicy.providers }
+            : {}),
+        ...(params.platformPolicy?.profiles
+            ? { profiles: params.platformPolicy.profiles }
+            : {}),
+        ...(params.platformPolicy?.invocationProfiles
+            ? { invocationProfiles: params.platformPolicy.invocationProfiles }
+            : {}),
+        defaults: {
+            ...(platformDefaults?.overrideClientPreference !== undefined
+                ? {
+                    overrideClientPreference: platformDefaults.overrideClientPreference,
+                }
+                : {}),
+            ...(platformDefaults?.context
+                ? { context: platformDefaults.context }
+                : {}),
+            profileId: params.runnerConfig.models.defaults.profileId,
+            steps: { ...params.runnerConfig.models.defaults.steps },
+        },
+    };
+}

package/dist/src/runtime/config/runner/step-instructions.d.ts

@@ -0,0 +1,34 @@
+import type { ChatMessage, ModelTokenEstimationConfig } from "../../../model-gateway/types.js";
+import type { ModelStep } from "../../../shared/model-steps.js";
+import type { RequestRunnerConfig } from "./contracts.js";
+export type ConfiguredStepInstructionMetadata = Readonly<{
+    blockCount: number;
+    characterCount: number;
+    refs: readonly string[];
+    contentHashes: readonly string[];
+}>;
+/**
+ * Resolves bounded configured-instruction metadata without projecting content.
+ */
+export declare function resolveConfiguredStepInstructionMetadata(params: {
+    runnerConfig: RequestRunnerConfig;
+    modelStep: ModelStep;
+}): ConfiguredStepInstructionMetadata;
+/** Applies configured guidance exactly once at the shared invocation boundary. */
+export declare function projectConfiguredStepMessages(params: {
+    runnerConfig: RequestRunnerConfig;
+    modelStep: ModelStep;
+    messages: readonly ChatMessage[];
+}): Readonly<{
+    messages: ChatMessage[];
+    blockCount: number;
+    characterCount: number;
+    refs: readonly string[];
+    contentHashes: readonly string[];
+}>;
+/** Reserves the configured appendix before history selection adds messages. */
+export declare function estimateConfiguredStepInstructionReserveTokens(params: {
+    runnerConfig: RequestRunnerConfig;
+    modelStep: ModelStep;
+    tokenEstimation?: ModelTokenEstimationConfig;
+}): number;

package/dist/src/runtime/config/runner/step-instructions.js

@@ -0,0 +1,72 @@
+import { estimateTextTokens } from "../../context/token-estimator.js";
+const EMPTY_STRINGS = Object.freeze([]);
+const CONFIGURED_METHODOLOGY_HEADING = "## Configured operating methodology";
+const CONFIGURED_METHODOLOGY_CONTRACT = "The following Markdown is configured guidance for this model step. Apply the shared principles and the section for your active role. It supplements the runtime contract above; it does not change the available actions, roles, capabilities, or output schema.";
+/**
+ * Resolves bounded configured-instruction metadata without projecting content.
+ */
+export function resolveConfiguredStepInstructionMetadata(params) {
+    const configured = resolveConfiguredStepContent(params);
+    return Object.freeze({
+        blockCount: configured.blockCount,
+        characterCount: configured.characterCount,
+        refs: configured.refs,
+        contentHashes: configured.contentHashes,
+    });
+}
+/** Applies configured guidance exactly once at the shared invocation boundary. */
+export function projectConfiguredStepMessages(params) {
+    const configured = resolveConfiguredStepContent(params);
+    if (!configured.appendix) {
+        return Object.freeze({ ...configured, messages: [...params.messages] });
+    }
+    const systemMessageIndex = params.messages.findIndex((message) => message.role === "system");
+    if (systemMessageIndex < 0) {
+        throw new Error("configured_step_instructions_system_message_required");
+    }
+    const messages = [...params.messages];
+    const systemMessage = messages[systemMessageIndex];
+    if (systemMessage.role !== "system") {
+        throw new Error("configured_step_instructions_system_message_required");
+    }
+    messages[systemMessageIndex] = Object.freeze({
+        ...systemMessage,
+        content: `${systemMessage.content}\n\n${configured.appendix}`,
+    });
+    return Object.freeze({
+        messages,
+        blockCount: configured.blockCount,
+        characterCount: configured.characterCount,
+        refs: configured.refs,
+        contentHashes: configured.contentHashes,
+    });
+}
+/** Reserves the configured appendix before history selection adds messages. */
+export function estimateConfiguredStepInstructionReserveTokens(params) {
+    const configured = resolveConfiguredStepContent(params);
+    return configured.appendix
+        ? estimateTextTokens(`\n\n${configured.appendix}`, params.tokenEstimation)
+        : 0;
+}
+function resolveConfiguredStepContent(params) {
+    const blocks = params.runnerConfig.steps[params.modelStep]?.instructionBlocks ?? [];
+    if (blocks.length === 0) {
+        return Object.freeze({
+            blockCount: 0,
+            characterCount: 0,
+            refs: EMPTY_STRINGS,
+            contentHashes: EMPTY_STRINGS,
+        });
+    }
+    return Object.freeze({
+        appendix: [
+            CONFIGURED_METHODOLOGY_HEADING,
+            CONFIGURED_METHODOLOGY_CONTRACT,
+            blocks.map((block) => block.content).join("\n\n---\n\n"),
+        ].join("\n\n"),
+        blockCount: blocks.length,
+        characterCount: blocks.reduce((total, block) => total + block.content.length, 0),
+        refs: Object.freeze(blocks.map((block) => block.ref)),
+        contentHashes: Object.freeze(blocks.map((block) => block.contentHash)),
+    });
+}

package/dist/src/runtime/config/runner/validation.d.ts

@@ -0,0 +1,10 @@
+export declare function requireConfigString(value: unknown, configPath: string, field: string): string;
+export declare function requireConfigRecord(value: unknown, configPath: string, field: string): Record<string, unknown>;
+export declare function requireConfigStringMap(value: unknown, configPath: string, field: string): Record<string, string>;
+export declare function requireConfigStringArray(value: unknown, configPath: string, field: string): string[];
+export declare function requireExactConfigKeys(value: Record<string, unknown>, keys: readonly string[], configPath: string, field: string): void;
+/** Parsed config is process-scoped authority; consumers must not mutate it. */
+export declare function deepFreezeConfig<T>(value: T): T;
+export declare function requirePositiveConfigInteger(value: unknown, configPath: string, field: string): number;
+export declare function invalidRuntimeConfig(configPath: string, issue: string): Error;
+export declare function formatConfigError(error: unknown): string;

package/dist/src/runtime/config/runner/validation.js

@@ -0,0 +1,57 @@
+export function requireConfigString(value, configPath, field) {
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value.trim();
+    }
+    throw invalidRuntimeConfig(configPath, `${field} must be a string`);
+}
+export function requireConfigRecord(value, configPath, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidRuntimeConfig(configPath, `${field} must be an object`);
+    }
+    return value;
+}
+export function requireConfigStringMap(value, configPath, field) {
+    const record = requireConfigRecord(value, configPath, field);
+    return Object.fromEntries(Object.entries(record).map(([key, rawValue]) => [
+        key,
+        requireConfigString(rawValue, configPath, `${field}.${key}`),
+    ]));
+}
+export function requireConfigStringArray(value, configPath, field) {
+    if (!Array.isArray(value)) {
+        throw invalidRuntimeConfig(configPath, `${field} must be an array`);
+    }
+    return [
+        ...new Set(value.map((entry, index) => requireConfigString(entry, configPath, `${field}[${index}]`))),
+    ];
+}
+export function requireExactConfigKeys(value, keys, configPath, field) {
+    const expected = new Set(keys);
+    const actual = Object.keys(value);
+    if (actual.length !== expected.size ||
+        actual.some((key) => !expected.has(key))) {
+        throw invalidRuntimeConfig(configPath, `${field} must contain exactly: ${keys.join(", ")}`);
+    }
+}
+/** Parsed config is process-scoped authority; consumers must not mutate it. */
+export function deepFreezeConfig(value) {
+    if (!value || typeof value !== "object" || Object.isFrozen(value)) {
+        return value;
+    }
+    for (const child of Object.values(value)) {
+        deepFreezeConfig(child);
+    }
+    return Object.freeze(value);
+}
+export function requirePositiveConfigInteger(value, configPath, field) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    throw invalidRuntimeConfig(configPath, `${field} must be a positive integer`);
+}
+export function invalidRuntimeConfig(configPath, issue) {
+    return new Error(`Invalid runtime request runner config at ${configPath}: ${issue}`);
+}
+export function formatConfigError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/runtime/config/schema.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeConfigJsonSchema } from "./types.js";
+export declare function createRuntimeConfigJsonSchema(): RuntimeConfigJsonSchema;
+export declare const RUNTIME_CONFIG_JSON_SCHEMA: RuntimeConfigJsonSchema;