@abot-ai/runtime 1.0.0

package/dist/src/runtime/model/model-step-capability-policy.js

@@ -0,0 +1,49 @@
+import { resolveEffectiveInvocationProfile } from "../../shared/invocation-profile-selection.js";
+function resolveConfiguredProfile(profileId, policy) {
+    return policy?.profiles?.[profileId];
+}
+function resolveCalibrationProfileId(params) {
+    const step = typeof params.modelStep === "string" ? params.modelStep.trim() : "";
+    const slotId = step ? params.modelPolicy?.defaults?.steps?.[step] : "";
+    if (!slotId) {
+        return params.resolvedProfileId;
+    }
+    if (params.modelPolicy?.invocationProfiles?.[slotId] ||
+        resolveConfiguredProfile(slotId, params.modelPolicy)) {
+        return params.resolvedProfileId;
+    }
+    const calibrationProfileId = params.resolvedProfile.calibration?.[slotId]?.profileId?.trim();
+    return calibrationProfileId || params.resolvedProfileId;
+}
+export function resolvedModelStepImageAttachmentProfileId(params) {
+    const resolvedProfile = resolveEffectiveInvocationProfile({
+        ...params,
+        resolveProfile: resolveConfiguredProfile,
+    });
+    if (!resolvedProfile) {
+        return undefined;
+    }
+    const profileId = resolveCalibrationProfileId({
+        modelStep: params.modelStep,
+        modelPolicy: params.modelPolicy,
+        resolvedProfileId: resolvedProfile.profileId,
+        resolvedProfile: resolvedProfile.profile,
+    });
+    const profile = resolveConfiguredProfile(profileId, params.modelPolicy);
+    return profileReferencesConfiguredProvider({
+        profileId,
+        modelPolicy: params.modelPolicy,
+    }) && profile?.capabilities?.inputModalities?.includes("image")
+        ? profileId
+        : undefined;
+}
+function profileReferencesConfiguredProvider(params) {
+    const profile = params.modelPolicy?.profiles?.[params.profileId];
+    const providerId = profile?.provider?.trim();
+    return Boolean(providerId &&
+        params.modelPolicy?.providers &&
+        Object.hasOwn(params.modelPolicy.providers, providerId));
+}
+export function resolvedModelStepSupportsImageAttachments(params) {
+    return resolvedModelStepImageAttachmentProfileId(params) !== undefined;
+}

package/dist/src/runtime/model/model-step-port.d.ts

@@ -0,0 +1,37 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { ModelStep } from "../../shared/model-steps.js";
+export type ModelStepOutputDiagnostics = Readonly<{
+    outputLength: number;
+    transportOutputLength?: number;
+    terminalEventCount?: number;
+    providerCompletionReason?: string | null;
+    providerInputTokens?: number;
+    providerOutputTokens?: number;
+    providerTotalTokens?: number;
+}>;
+export type ModelStepContextCompactionPreparation = Readonly<{
+    messages: ChatMessage[];
+    commit(): void | Promise<void>;
+    scopeId: string;
+    sourceRevision: number | string;
+    coveredSourceCount: number;
+}>;
+export type ModelStepContextCompactionController = Readonly<{
+    compactionScope: "active_request" | "session_history";
+    /** Replaces already-covered exact working messages before assessment. */
+    project(messages: readonly ChatMessage[]): ChatMessage[];
+    /** Generates one replacement checkpoint without committing it yet. */
+    prepare(messages: readonly ChatMessage[]): Promise<ModelStepContextCompactionPreparation>;
+}>;
+export type ModelStepInvocationInput<T> = Readonly<{
+    modelStep: ModelStep;
+    messages: ChatMessage[];
+    timeoutReason: string;
+    format?: "json" | Record<string, unknown>;
+    contextCompaction?: ModelStepContextCompactionController;
+    accept(text: string, diagnostics: ModelStepOutputDiagnostics): T;
+}>;
+/** Request-owned port shared by every model step in one accepted request. */
+export type RequestModelStepPort = Readonly<{
+    invoke<T>(params: ModelStepInvocationInput<T>): Promise<T>;
+}>;

package/dist/src/runtime/model/model-step-port.js

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

package/dist/src/runtime/model/model-step-timeout-policy.d.ts

@@ -0,0 +1,15 @@
+import type { ModelGatewayPolicyConfig, ModelPreference } from "../../model-gateway/types.js";
+import type { ModelStep } from "../../shared/model-steps.js";
+export type ResolvedModelStepTimeout = Readonly<{
+    timeoutMs: number;
+    source: "runner" | "model_calibration";
+    selectedProfileId?: string;
+    calibrationSlotId?: string;
+}>;
+/** Resolves a model-specific step timeout without changing model selection. */
+export declare function resolveModelStepTimeout(params: {
+    modelStep: ModelStep;
+    fallbackTimeoutMs: number;
+    modelPreference?: ModelPreference;
+    modelPolicy?: ModelGatewayPolicyConfig;
+}): ResolvedModelStepTimeout;

package/dist/src/runtime/model/model-step-timeout-policy.js

@@ -0,0 +1,34 @@
+import { resolveEffectiveInvocationProfile } from "../../shared/invocation-profile-selection.js";
+function resolveConfiguredProfile(profileId, policy) {
+    return policy?.profiles?.[profileId];
+}
+/** Resolves a model-specific step timeout without changing model selection. */
+export function resolveModelStepTimeout(params) {
+    const selected = resolveEffectiveInvocationProfile({
+        modelStep: params.modelStep,
+        modelPreference: params.modelPreference,
+        modelPolicy: params.modelPolicy,
+        resolveProfile: resolveConfiguredProfile,
+    });
+    const selectedProfileId = selected?.profileId;
+    const slotId = params.modelPolicy?.defaults?.steps?.[params.modelStep];
+    const slotIsDirectSelection = !!slotId &&
+        (!!params.modelPolicy?.invocationProfiles?.[slotId] ||
+            !!params.modelPolicy?.profiles?.[slotId]);
+    const calibration = selected && slotId && !slotIsDirectSelection
+        ? selected.profile.calibration?.[slotId]
+        : undefined;
+    if (calibration?.timeoutMs !== undefined) {
+        return {
+            timeoutMs: calibration.timeoutMs,
+            source: "model_calibration",
+            selectedProfileId,
+            calibrationSlotId: slotId,
+        };
+    }
+    return {
+        timeoutMs: params.fallbackTimeoutMs,
+        source: "runner",
+        ...(selectedProfileId ? { selectedProfileId } : {}),
+    };
+}

package/dist/src/runtime/model/provider-completion.d.ts

@@ -0,0 +1,13 @@
+import type { ModelStepOutputDiagnostics } from "./invoke-step.js";
+/** A provider returned only a prefix because its physical output capacity ended. */
+export declare class ModelOutputIncompleteError extends Error {
+    readonly code = "output_incomplete";
+    readonly stage = "provider_completion";
+    readonly providerCompletionReason: string | null;
+    readonly providerInputTokens?: number;
+    readonly providerOutputTokens?: number;
+    readonly providerTotalTokens?: number;
+    constructor(diagnostics: ModelStepOutputDiagnostics);
+}
+export declare function isOutputLimitCompletion(diagnostics: Pick<ModelStepOutputDiagnostics, "providerCompletionReason">): boolean;
+export declare function resolveOutputIncompleteError(diagnostics: ModelStepOutputDiagnostics): ModelOutputIncompleteError | undefined;

package/dist/src/runtime/model/provider-completion.js

@@ -0,0 +1,29 @@
+/** A provider returned only a prefix because its physical output capacity ended. */
+export class ModelOutputIncompleteError extends Error {
+    code = "output_incomplete";
+    stage = "provider_completion";
+    providerCompletionReason;
+    providerInputTokens;
+    providerOutputTokens;
+    providerTotalTokens;
+    constructor(diagnostics) {
+        super("output_incomplete");
+        this.name = "ModelOutputIncompleteError";
+        this.providerCompletionReason =
+            diagnostics.providerCompletionReason ?? null;
+        this.providerInputTokens = diagnostics.providerInputTokens;
+        this.providerOutputTokens = diagnostics.providerOutputTokens;
+        this.providerTotalTokens = diagnostics.providerTotalTokens;
+    }
+}
+export function isOutputLimitCompletion(diagnostics) {
+    const reason = diagnostics.providerCompletionReason?.toLowerCase() ?? "";
+    return (reason.includes("length") ||
+        reason.includes("max_token") ||
+        reason.includes("max_output"));
+}
+export function resolveOutputIncompleteError(diagnostics) {
+    return isOutputLimitCompletion(diagnostics)
+        ? new ModelOutputIncompleteError(diagnostics)
+        : undefined;
+}

package/dist/src/runtime/model/repair-prompts.d.ts

@@ -0,0 +1,13 @@
+type RepairIssue = Readonly<{
+    code: string;
+    path: string;
+    message: string;
+}>;
+export declare const STRUCTURED_MODEL_MAX_REPAIR_ATTEMPTS = 2;
+export declare function buildStructuredModelRepairHint(params: Readonly<{
+    repairAttempt: number;
+    stage: string;
+    issues: readonly RepairIssue[];
+    repeatedInvalidOutput: boolean;
+}>): string;
+export {};

package/dist/src/runtime/model/repair-prompts.js

@@ -0,0 +1,22 @@
+export const STRUCTURED_MODEL_MAX_REPAIR_ATTEMPTS = 2;
+export function buildStructuredModelRepairHint(params) {
+    const issueLines = params.issues.map((issue, index) => `${index + 1}. ${issue.path}: ${issue.message} (${issue.code})`);
+    return [
+        "Your previous output was rejected before it caused any role, capability, tool, or ledger action.",
+        "Correct the same decision for the same assignment now.",
+        `Repair attempt: ${params.repairAttempt}.`,
+        `Validation stage: ${params.stage}.`,
+        ...(params.repeatedInvalidOutput
+            ? [
+                "Your last correction repeated the same invalid output. Change the listed fields before returning.",
+            ]
+            : []),
+        "Return exactly one complete corrected JSON object matching the supplied schema and nothing else.",
+        "Do not repeat the rejected output unchanged. Do not explain, apologize, invoke anything, or describe the correction.",
+        "Correct every listed issue:",
+        ...(issueLines.length > 0
+            ? issueLines
+            : ["1. Rebuild the complete decision from the supplied schema."]),
+        "Follow the supplied schema for absent values: use null when the schema requires the property, and omit it only when omission is allowed.",
+    ].join("\n");
+}

package/dist/src/runtime/model/structured-decision-envelope.d.ts

@@ -0,0 +1,4 @@
+export declare const STRUCTURED_DECISION_ENVELOPE_KEY: "decision";
+export declare function createStructuredDecisionEnvelopeSchema(variants: readonly Record<string, unknown>[]): Record<string, unknown>;
+export declare function structuredDecisionVariantSchemaPath(index: number, variantCount: number): string;
+export declare function readStructuredDecisionEnvelope(value: unknown): Record<string, unknown> | undefined;

package/dist/src/runtime/model/structured-decision-envelope.js

@@ -0,0 +1,47 @@
+export const STRUCTURED_DECISION_ENVELOPE_KEY = "decision";
+export function createStructuredDecisionEnvelopeSchema(variants) {
+    if (variants.length === 0) {
+        throw new Error("structured_decision_variants_empty");
+    }
+    return {
+        type: "object",
+        properties: {
+            [STRUCTURED_DECISION_ENVELOPE_KEY]: variants.length === 1
+                ? variants[0]
+                : {
+                    anyOf: [...variants],
+                },
+        },
+        required: [STRUCTURED_DECISION_ENVELOPE_KEY],
+        additionalProperties: false,
+    };
+}
+export function structuredDecisionVariantSchemaPath(index, variantCount) {
+    if (!Number.isInteger(index) ||
+        index < 0 ||
+        !Number.isInteger(variantCount) ||
+        variantCount < 1 ||
+        index >= variantCount) {
+        throw new Error("structured_decision_variant_path_invalid");
+    }
+    const decisionPath = `/properties/${STRUCTURED_DECISION_ENVELOPE_KEY}`;
+    return variantCount === 1 ? decisionPath : `${decisionPath}/anyOf/${index}`;
+}
+export function readStructuredDecisionEnvelope(value) {
+    const envelope = asRecord(value);
+    if (!envelope ||
+        Object.keys(envelope).length !== 1 ||
+        !Object.prototype.hasOwnProperty.call(envelope, STRUCTURED_DECISION_ENVELOPE_KEY)) {
+        return undefined;
+    }
+    return asRecord(envelope[STRUCTURED_DECISION_ENVELOPE_KEY]);
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null
+        ? value
+        : undefined;
+}

package/dist/src/runtime/model/thinking-trace.d.ts

@@ -0,0 +1,6 @@
+import type { SessionThinkingTraceStatus } from "../../sessions/types.js";
+export type RuntimeThinkingTrace = {
+    step: string;
+    status: SessionThinkingTraceStatus;
+    text: string;
+};

package/dist/src/runtime/model/thinking-trace.js

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

package/dist/src/runtime/observability/debug-logger.d.ts

@@ -0,0 +1,27 @@
+import type { RuntimeLogRotationConfig } from "../ports.js";
+export type DebugLoggerConfig = {
+    traceFile?: string;
+    enabled?: boolean;
+    rotation?: RuntimeLogRotationConfig;
+};
+/** Owns the single process-wide trace configuration and serialized write queue. */
+export declare class ProcessDebugLogger {
+    private config;
+    private writeQueue;
+    private cachedDefaultLogPath;
+    configure(config?: DebugLoggerConfig): void;
+    reset(): void;
+    trace(scope: string, event: string, data?: Record<string, unknown>): void;
+    /** Waits for every trace write queued before this call to settle. */
+    drain(): Promise<void>;
+    private shouldTrace;
+    private resolveDefaultLogPath;
+    private getLogPath;
+    private getRotationConfig;
+    private appendLogLine;
+    private writeLine;
+}
+export declare const processDebugLogger: ProcessDebugLogger;
+export declare function configureDebugLogger(config?: DebugLoggerConfig): void;
+export declare function resetDebugLoggerConfig(): void;
+export declare function traceDebug(scope: string, event: string, data?: Record<string, unknown>): void;

package/dist/src/runtime/observability/debug-logger.js

@@ -0,0 +1,132 @@
+import { join } from "node:path";
+import { loadRuntimeConfig } from "../config.js";
+import { DEFAULT_RUNTIME_LOGGING_ENABLED, DEFAULT_RUNTIME_LOG_ROTATION_CONFIG, } from "../config/constants.js";
+import { DEFAULT_RUNTIME_TRACE_FILE } from "../config/layout.js";
+import { appendTraceLineWithRotation, } from "./log-rotation.js";
+const LEGACY_DEFAULT_LOG_PATH = join(process.cwd(), DEFAULT_RUNTIME_TRACE_FILE);
+function readTraceEnabledOverride() {
+    const value = process.env.LLM_RUNTIME_TRACE?.trim().toLowerCase();
+    if (!value) {
+        return undefined;
+    }
+    return !(value === "0" || value === "false" || value === "off");
+}
+function getDefaultLogPathCacheKey() {
+    return JSON.stringify({
+        cwd: process.cwd(),
+        profile: process.env.LLM_RUNTIME_PROFILE ?? "",
+        runtimeDir: process.env.LLM_RUNTIME_DIR ?? "",
+        traceFile: process.env.LLM_RUNTIME_TRACE_FILE ?? "",
+    });
+}
+function warnCleanupFailure(warning) {
+    console.warn(JSON.stringify({
+        scope: "runtime.debug-logger",
+        event: warning.event,
+        ts: new Date().toISOString(),
+        traceFile: warning.traceFile,
+        error: warning.error,
+        paths: warning.paths,
+    }));
+}
+/** Owns the single process-wide trace configuration and serialized write queue. */
+export class ProcessDebugLogger {
+    config = {};
+    writeQueue = Promise.resolve();
+    cachedDefaultLogPath;
+    configure(config = {}) {
+        this.config = {
+            ...this.config,
+            ...config,
+        };
+    }
+    reset() {
+        this.config = {};
+        this.writeQueue = Promise.resolve();
+        this.cachedDefaultLogPath = undefined;
+    }
+    trace(scope, event, data = {}) {
+        if (!this.shouldTrace()) {
+            return;
+        }
+        const payload = {
+            scope,
+            event,
+            ts: new Date().toISOString(),
+            ...data,
+        };
+        const line = JSON.stringify(payload);
+        console.log(line);
+        void this.writeLine(line).catch((error) => {
+            console.error(JSON.stringify({
+                scope: "runtime.debug-logger",
+                event: "write.failed",
+                ts: new Date().toISOString(),
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
+    /** Waits for every trace write queued before this call to settle. */
+    async drain() {
+        await this.writeQueue;
+    }
+    shouldTrace() {
+        const envOverride = readTraceEnabledOverride();
+        if (envOverride !== undefined) {
+            return envOverride;
+        }
+        if (typeof this.config.enabled === "boolean") {
+            return this.config.enabled;
+        }
+        return DEFAULT_RUNTIME_LOGGING_ENABLED;
+    }
+    resolveDefaultLogPath() {
+        const cacheKey = getDefaultLogPathCacheKey();
+        if (this.cachedDefaultLogPath?.key === cacheKey) {
+            return this.cachedDefaultLogPath.path;
+        }
+        let path = LEGACY_DEFAULT_LOG_PATH;
+        try {
+            path = loadRuntimeConfig({ rootDir: process.cwd() }).paths.traceFile;
+        }
+        catch {
+            path = LEGACY_DEFAULT_LOG_PATH;
+        }
+        this.cachedDefaultLogPath = {
+            key: cacheKey,
+            path,
+        };
+        return path;
+    }
+    getLogPath() {
+        const envPath = process.env.LLM_RUNTIME_TRACE_FILE?.trim();
+        return envPath || this.config.traceFile || this.resolveDefaultLogPath();
+    }
+    getRotationConfig() {
+        return this.config.rotation ?? DEFAULT_RUNTIME_LOG_ROTATION_CONFIG;
+    }
+    async appendLogLine(line) {
+        await appendTraceLineWithRotation({
+            traceFile: this.getLogPath(),
+            line,
+            rotation: this.getRotationConfig(),
+            onWarning: warnCleanupFailure,
+        });
+    }
+    async writeLine(line) {
+        this.writeQueue = this.writeQueue
+            .catch(() => undefined)
+            .then(() => this.appendLogLine(line));
+        return this.writeQueue;
+    }
+}
+export const processDebugLogger = new ProcessDebugLogger();
+export function configureDebugLogger(config = {}) {
+    processDebugLogger.configure(config);
+}
+export function resetDebugLoggerConfig() {
+    processDebugLogger.reset();
+}
+export function traceDebug(scope, event, data = {}) {
+    processDebugLogger.trace(scope, event, data);
+}

package/dist/src/runtime/observability/error-type.d.ts

@@ -0,0 +1 @@
+export declare function classifyRuntimeErrorType(error: unknown): string;

package/dist/src/runtime/observability/error-type.js

@@ -0,0 +1,33 @@
+export function classifyRuntimeErrorType(error) {
+    try {
+        if (error instanceof TypeError)
+            return "TypeError";
+        if (error instanceof RangeError)
+            return "RangeError";
+        if (error instanceof SyntaxError)
+            return "SyntaxError";
+        if (error instanceof ReferenceError)
+            return "ReferenceError";
+        if (error instanceof URIError)
+            return "URIError";
+        if (error instanceof EvalError)
+            return "EvalError";
+        if (error instanceof Error)
+            return "Error";
+    }
+    catch {
+        return "unknown";
+    }
+    switch (typeof error) {
+        case "string":
+        case "number":
+        case "boolean":
+        case "bigint":
+        case "symbol":
+        case "undefined":
+        case "function":
+            return typeof error;
+        default:
+            return "unknown";
+    }
+}

package/dist/src/runtime/observability/log-rotation.d.ts

@@ -0,0 +1,24 @@
+import { appendFile, mkdir, readdir, rename, stat, unlink } from "node:fs/promises";
+import type { RuntimeLogRotationConfig } from "../ports.js";
+type LogRotationFileOps = {
+    appendFile: typeof appendFile;
+    mkdir: typeof mkdir;
+    readdir: typeof readdir;
+    rename: typeof rename;
+    stat: typeof stat;
+    unlink: typeof unlink;
+};
+export type LogRotationWarning = {
+    traceFile: string;
+    event: "cleanup.failed";
+    error: string;
+    paths: string[];
+};
+export declare function appendTraceLineWithRotation(options: {
+    traceFile: string;
+    line: string;
+    rotation: RuntimeLogRotationConfig;
+    onWarning?: (warning: LogRotationWarning) => void;
+    fileOps?: LogRotationFileOps;
+}): Promise<void>;
+export {};

package/dist/src/runtime/observability/log-rotation.js

@@ -0,0 +1,142 @@
+import { appendFile, mkdir, readdir, rename, stat, unlink, } from "node:fs/promises";
+import { dirname, join, parse } from "node:path";
+const ROTATED_LOG_TIMESTAMP_PATTERN = /^(?<date>\d{4}-\d{2}-\d{2})T(?<hour>\d{2})-(?<minute>\d{2})-(?<second>\d{2})-(?<millisecond>\d{3})Z$/;
+const DEFAULT_FILE_OPS = {
+    appendFile,
+    mkdir,
+    readdir,
+    rename,
+    stat,
+    unlink,
+};
+function isMissingFileError(error) {
+    return (!!error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function buildRotationTimestamp(date) {
+    return date.toISOString().replaceAll(":", "-").replace(".", "-");
+}
+function buildRotatedLogPath(traceFile, date) {
+    const parsed = parse(traceFile);
+    return join(parsed.dir, `${parsed.name}.${buildRotationTimestamp(date)}${parsed.ext}`);
+}
+function parseRotationTimestamp(value) {
+    const match = ROTATED_LOG_TIMESTAMP_PATTERN.exec(value);
+    if (!match?.groups) {
+        return null;
+    }
+    const isoTimestamp = `${match.groups.date}T${match.groups.hour}:${match.groups.minute}:${match.groups.second}.${match.groups.millisecond}Z`;
+    const rotatedAtMs = Date.parse(isoTimestamp);
+    return Number.isFinite(rotatedAtMs) ? rotatedAtMs : null;
+}
+function readRotatedTimestampFromName(traceFile, entryName) {
+    const parsed = parse(traceFile);
+    const prefix = `${parsed.name}.`;
+    if (!entryName.startsWith(prefix) || !entryName.endsWith(parsed.ext)) {
+        return null;
+    }
+    const timestamp = entryName.slice(prefix.length, entryName.length - parsed.ext.length);
+    return parseRotationTimestamp(timestamp);
+}
+async function rotateActiveLogIfNeeded(traceFile, rotation, fileOps) {
+    let fileStat;
+    try {
+        fileStat = await fileOps.stat(traceFile);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return;
+        }
+        throw error;
+    }
+    const maxBytes = rotation.maxFileSizeMb * 1024 * 1024;
+    if (fileStat.size < maxBytes) {
+        return;
+    }
+    await fileOps.rename(traceFile, buildRotatedLogPath(traceFile, new Date()));
+}
+async function listRotatedLogs(traceFile, fileOps) {
+    const parsed = parse(traceFile);
+    let entries;
+    try {
+        entries = await fileOps.readdir(parsed.dir);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return [];
+        }
+        throw error;
+    }
+    const rotatedFiles = [];
+    for (const entryName of entries) {
+        const rotatedAtMs = readRotatedTimestampFromName(traceFile, entryName);
+        if (rotatedAtMs === null) {
+            continue;
+        }
+        const path = join(parsed.dir, entryName);
+        try {
+            const fileStat = await fileOps.stat(path);
+            if (!fileStat.isFile()) {
+                continue;
+            }
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                continue;
+            }
+            throw error;
+        }
+        rotatedFiles.push({ path, rotatedAtMs });
+    }
+    return rotatedFiles;
+}
+async function cleanupRotatedLogs(traceFile, rotation, fileOps, onWarning) {
+    const rotatedFiles = await listRotatedLogs(traceFile, fileOps);
+    if (rotatedFiles.length === 0) {
+        return;
+    }
+    const maxAgeMs = rotation.maxAgeDays * 24 * 60 * 60 * 1000;
+    const cutoffMs = Date.now() - maxAgeMs;
+    const expiredPaths = rotatedFiles
+        .filter((file) => file.rotatedAtMs < cutoffMs)
+        .map((file) => file.path);
+    const retainedCandidates = rotatedFiles
+        .filter((file) => file.rotatedAtMs >= cutoffMs)
+        .sort((left, right) => right.rotatedAtMs - left.rotatedAtMs);
+    const overflowPaths = retainedCandidates
+        .slice(rotation.maxFiles)
+        .map((file) => file.path);
+    const pathsToDelete = [...new Set([...expiredPaths, ...overflowPaths])];
+    if (pathsToDelete.length === 0) {
+        return;
+    }
+    const failedPaths = [];
+    for (const path of pathsToDelete) {
+        try {
+            await fileOps.unlink(path);
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                continue;
+            }
+            failedPaths.push(path);
+        }
+    }
+    if (failedPaths.length > 0) {
+        onWarning?.({
+            traceFile,
+            event: "cleanup.failed",
+            error: `Failed to prune ${failedPaths.length} rotated runtime log file(s)`,
+            paths: failedPaths,
+        });
+    }
+}
+export async function appendTraceLineWithRotation(options) {
+    const fileOps = options.fileOps ?? DEFAULT_FILE_OPS;
+    await fileOps.mkdir(dirname(options.traceFile), { recursive: true });
+    await rotateActiveLogIfNeeded(options.traceFile, options.rotation, fileOps);
+    await fileOps.appendFile(options.traceFile, `${options.line}\n`, "utf-8");
+    await cleanupRotatedLogs(options.traceFile, options.rotation, fileOps, options.onWarning);
+}

package/dist/src/runtime/orchestration/capability-adapters/descriptor.d.ts

@@ -0,0 +1,13 @@
+import { type WorkerCapabilityDescriptor } from "../worker-capabilities/contracts.js";
+export type CapabilityDescriptorNormalization = Readonly<{
+    ok: true;
+    value: WorkerCapabilityDescriptor;
+}> | Readonly<{
+    ok: false;
+    issueCode: string;
+}>;
+/**
+ * Contract projection only. Adapter construction and execution remain owned by
+ * the shared role-call capability binding.
+ */
+export declare function normalizeCapabilityDescriptor(descriptor: WorkerCapabilityDescriptor): CapabilityDescriptorNormalization;