@abot-ai/runtime 1.0.0

package/dist/src/runtime/config.js

@@ -0,0 +1,166 @@
+import { join } from "node:path";
+import { DEFAULT_RUNTIME_ID, DEFAULT_MODEL_GATEWAY_URL, } from "../shared/constants.js";
+import { loadDotEnvFile } from "../shared/load-dotenv.js";
+import { buildFeatureFlags, buildLoggingConfig, buildRuntimeModelConfiguration, buildPluginConfig, compactTimeouts, } from "./config/builders.js";
+import { DEFAULT_RUNTIME_AGENT_BRIDGE_URL, DEFAULT_RUNTIME_CONFIG_FILE, } from "./config/constants.js";
+import { validateEffectiveRuntimeModelConfig } from "./config/effective-model-config-validation.js";
+import { resolveRuntimeEnvironmentProfileSelection } from "./config/environment.js";
+import { RUNTIME_CONFIG_SCHEMA_FIELDS } from "./config/fields.js";
+import { loadRuntimeConfigFileWithMeta } from "./config/loader.js";
+import { resolveRequestRunnerConfigReference } from "./config/request-runner-config.js";
+import { loadRequestRunnerConfig } from "./config/runner/loader.js";
+import { DEFAULT_RUNTIME_COMPILED_DIR, DEFAULT_RUNTIME_SHARED_DIR, DEFAULT_AGENT_WORK_DIR, DEFAULT_RUNTIME_STATE_DIR, DEFAULT_WORKSPACE_SOURCE_DIR, RUNTIME_ATTACHMENTS_DIR_NAME, RUNTIME_LOGS_DIR_NAME, RUNTIME_SESSIONS_DIR_NAME, } from "./config/layout.js";
+import { createRuntimeConfigJsonSchema, RUNTIME_CONFIG_JSON_SCHEMA, } from "./config/schema.js";
+import { readConfigPositiveInt, readConfigString, readFirstString, readNestedConfigString, readPositiveInt, resolveRuntimePath, } from "./config/utils.js";
+import { RuntimeConfigValidationError } from "./config/validation.js";
+export { DEFAULT_RUNTIME_AGENT_BRIDGE_URL, DEFAULT_RUNTIME_CONFIG_FILE, RUNTIME_CONFIG_JSON_SCHEMA, RUNTIME_CONFIG_SCHEMA_FIELDS, RuntimeConfigValidationError, createRuntimeConfigJsonSchema, };
+function resolveRuntimeStatePath(params) {
+    const envValue = readFirstString(params.env ?? {}, params.envNames);
+    if (envValue) {
+        return resolveRuntimePath(params.rootDir, envValue);
+    }
+    const profileValue = readNestedConfigString(params.profilePaths, params.key);
+    if (profileValue) {
+        return resolveRuntimePath(params.rootDir, profileValue);
+    }
+    if (params.selectedProfile) {
+        return resolveRuntimePath(params.rootDir, params.fallback);
+    }
+    const baseValue = readNestedConfigString(params.basePaths, params.key);
+    return resolveRuntimePath(params.rootDir, baseValue ?? params.fallback);
+}
+export function loadRuntimeConfig(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    if (!options.env) {
+        loadDotEnvFile(options.envPath ?? join(rootDir, ".env"));
+    }
+    const env = options.env ?? process.env;
+    const configPath = options.configPath ?? readFirstString(env, ["LLM_RUNTIME_CONFIG_FILE"]);
+    const loadedConfig = loadRuntimeConfigFileWithMeta(rootDir, configPath);
+    const fileConfig = loadedConfig.config;
+    const requestRunner = resolveRequestRunnerConfigReference({
+        fileConfig,
+        mainConfigPath: loadedConfig.path,
+    });
+    if (!requestRunner) {
+        throw new RuntimeConfigValidationError(loadedConfig.path, [
+            "requestRunner.configRef is required",
+        ]);
+    }
+    const profileSelection = resolveRuntimeEnvironmentProfileSelection({
+        config: fileConfig,
+        env,
+        profileId: options.profileId,
+    });
+    const basePaths = profileSelection.basePaths ?? fileConfig.paths;
+    const runtimeDir = resolveRuntimePath(rootDir, readFirstString(env, ["LLM_RUNTIME_DIR"]) ??
+        readNestedConfigString(profileSelection.profilePaths, "runtimeDir") ??
+        readNestedConfigString(basePaths, "runtimeDir") ??
+        DEFAULT_RUNTIME_STATE_DIR);
+    const agentWorkDir = resolveRuntimePath(rootDir, readFirstString(env, ["LLM_RUNTIME_AGENT_WORK_DIR"]) ??
+        readNestedConfigString(profileSelection.profilePaths, "agentWorkDir") ??
+        readNestedConfigString(basePaths, "agentWorkDir") ??
+        DEFAULT_AGENT_WORK_DIR);
+    const compiledDir = resolveRuntimePath(rootDir, readFirstString(env, ["LLM_RUNTIME_COMPILED_DIR"]) ??
+        readNestedConfigString(profileSelection.profilePaths, "compiledDir") ??
+        readNestedConfigString(basePaths, "compiledDir") ??
+        DEFAULT_RUNTIME_COMPILED_DIR);
+    const sharedDir = resolveRuntimePath(rootDir, readFirstString(env, ["LLM_RUNTIME_SHARED_DIR"]) ??
+        readNestedConfigString(profileSelection.profilePaths, "sharedDir") ??
+        readNestedConfigString(basePaths, "sharedDir") ??
+        DEFAULT_RUNTIME_SHARED_DIR);
+    const traceFile = resolveRuntimeStatePath({
+        env,
+        envNames: ["LLM_RUNTIME_TRACE_FILE"],
+        profilePaths: profileSelection.profilePaths,
+        basePaths,
+        key: "traceFile",
+        rootDir,
+        runtimeDir,
+        fallback: join(runtimeDir, RUNTIME_LOGS_DIR_NAME, "runtime-debug.jsonl"),
+        selectedProfile: !!profileSelection.profileId,
+    });
+    const timeouts = compactTimeouts({
+        requestTimeoutMs: readPositiveInt(env, "LLM_RUNTIME_REQUEST_TIMEOUT_MS") ??
+            readConfigPositiveInt(fileConfig.timeouts, "requestTimeoutMs"),
+        requestInactivityTimeoutMs: readPositiveInt(env, "LLM_RUNTIME_REQUEST_INACTIVITY_TIMEOUT_MS") ??
+            readConfigPositiveInt(fileConfig.timeouts, "requestInactivityTimeoutMs"),
+        modelStepTimeoutMs: readPositiveInt(env, "LLM_RUNTIME_MODEL_STEP_TIMEOUT_MS") ??
+            readConfigPositiveInt(fileConfig.timeouts, "modelStepTimeoutMs"),
+        streamInactivityTimeoutMs: readPositiveInt(env, "LLM_RUNTIME_STREAM_INACTIVITY_TIMEOUT_MS") ??
+            readConfigPositiveInt(fileConfig.timeouts, "streamInactivityTimeoutMs"),
+    });
+    const featureFlags = buildFeatureFlags(fileConfig);
+    const pluginConfig = buildPluginConfig(fileConfig);
+    const modelConfiguration = buildRuntimeModelConfiguration(fileConfig, {
+        mainConfigPath: loadedConfig.path,
+    });
+    validateEffectiveRuntimeModelConfig({
+        configPath: loadedConfig.path,
+        modelPolicy: modelConfiguration.modelPolicy,
+        runnerConfig: loadRequestRunnerConfig({
+            configPath: requestRunner.configPath,
+        }),
+    });
+    const loggingConfig = buildLoggingConfig(fileConfig, env);
+    const agentBridgeToken = readFirstString(env, ["AGENT_BRIDGE_TOKEN"]) ??
+        readConfigString(fileConfig, "agentBridgeToken");
+    return {
+        runtimeId: profileSelection.profileId ?? DEFAULT_RUNTIME_ID,
+        agentBridgeUrl: readFirstString(env, ["AGENT_BRIDGE_URL"]) ??
+            readConfigString(fileConfig, "agentBridgeUrl") ??
+            options.defaultAgentBridgeUrl ??
+            DEFAULT_RUNTIME_AGENT_BRIDGE_URL,
+        ...(agentBridgeToken ? { agentBridgeToken } : {}),
+        modelGatewayUrl: readFirstString(env, ["MODEL_GATEWAY_URL", "SIMPLE_LLM_SERVER_URL"]) ??
+            readConfigString(fileConfig, "modelGatewayUrl") ??
+            DEFAULT_MODEL_GATEWAY_URL,
+        paths: {
+            rootDir,
+            runtimeDir,
+            agentWorkDir,
+            sessionsDir: resolveRuntimeStatePath({
+                env,
+                envNames: ["LLM_RUNTIME_SESSIONS_DIR"],
+                profilePaths: profileSelection.profilePaths,
+                basePaths,
+                key: "sessionsDir",
+                rootDir,
+                runtimeDir,
+                fallback: join(runtimeDir, RUNTIME_SESSIONS_DIR_NAME),
+                selectedProfile: !!profileSelection.profileId,
+            }),
+            attachmentsDir: resolveRuntimeStatePath({
+                env,
+                envNames: ["LLM_RUNTIME_ATTACHMENTS_DIR"],
+                profilePaths: profileSelection.profilePaths,
+                basePaths,
+                key: "attachmentsDir",
+                rootDir,
+                runtimeDir,
+                fallback: join(runtimeDir, RUNTIME_ATTACHMENTS_DIR_NAME),
+                selectedProfile: !!profileSelection.profileId,
+            }),
+            workspaceDir: readFirstString(env, ["LLM_RUNTIME_WORKSPACE_DIR"]) ??
+                resolveRuntimePath(rootDir, readNestedConfigString(profileSelection.profilePaths, "workspaceDir") ??
+                    readNestedConfigString(basePaths, "workspaceDir") ??
+                    DEFAULT_WORKSPACE_SOURCE_DIR),
+            sharedDir,
+            compiledDir,
+            traceFile,
+        },
+        logging: loggingConfig,
+        ...(timeouts ? { timeouts } : {}),
+        ...(pluginConfig ? { plugins: pluginConfig } : {}),
+        ...(modelConfiguration.modelPolicy
+            ? { models: modelConfiguration.modelPolicy }
+            : {}),
+        ...(modelConfiguration.executionPolicies
+            ? { modelExecutionPolicies: modelConfiguration.executionPolicies }
+            : {}),
+        requestRunner,
+        ...(featureFlags ? { featureFlags } : {}),
+    };
+}
+export const loadRuntimeConfigFromEnv = loadRuntimeConfig;
+export const createDefaultRuntimeConfig = loadRuntimeConfig;

package/dist/src/runtime/context/model-step-compaction.d.ts

@@ -0,0 +1,17 @@
+import type { ModelStep } from "../../shared/model-steps.js";
+import type { ModelStepContextCompactionController } from "../model/model-step-port.js";
+import { type SemanticCompactionSource, type SemanticCompactionRequest } from "./semantic-compaction/index.js";
+type ModelStepCompactionOptions = Readonly<{
+    call: Readonly<{
+        roleId: string;
+        callId: string;
+        objective: string | null;
+    }>;
+    sourceRevision: number;
+    allowedConsumers: readonly ModelStep[];
+    scopeId?: string;
+    scopeSuffix?: string;
+    resultSourceOverrides?: readonly SemanticCompactionSource[];
+}>;
+export declare function createModelStepCompactionController(request: SemanticCompactionRequest, options: ModelStepCompactionOptions): ModelStepContextCompactionController;
+export {};

package/dist/src/runtime/context/model-step-compaction.js

@@ -0,0 +1,456 @@
+import { SEMANTIC_COMPACTION_CONTEXT_LANE, assertValidSemanticCompactionCheckpoint, createSemanticCompactionSha256Fingerprint, generateSemanticCompactionCandidateBatched, sameSemanticCompactionCheckpointBinding, } from "./semantic-compaction/index.js";
+const PAYLOAD_CONTEXT_PREFIX = "Canonical runtime context:\n";
+export function createModelStepCompactionController(request, options) {
+    if (!options.call.objective) {
+        throw new Error("context_compaction_active_objective_required");
+    }
+    const scopeId = options.scopeId ??
+        [
+            "role",
+            options.call.roleId,
+            options.call.callId,
+            options.scopeSuffix ?? "continuation",
+        ].join(":");
+    const binding = Object.freeze({
+        requestId: request.requestId,
+        currentRequestFingerprint: createSemanticCompactionSha256Fingerprint(request.prompt),
+        roleId: options.call.roleId,
+        callId: options.call.callId,
+        objectiveFingerprint: createSemanticCompactionSha256Fingerprint(options.call.objective),
+        contextLane: SEMANTIC_COMPACTION_CONTEXT_LANE,
+        allowedConsumers: Object.freeze([...options.allowedConsumers]),
+    });
+    const store = request.contextCompactionStore;
+    if (!store) {
+        throw new Error("context_compaction_store_required");
+    }
+    const resultSourceOverrides = createResultSourceOverrideMap(options.resultSourceOverrides ?? []);
+    const readPrevious = () => {
+        const previous = store.get(scopeId);
+        if (!previous)
+            return undefined;
+        assertValidSemanticCompactionCheckpoint(previous);
+        if (!sameSemanticCompactionCheckpointBinding(previous, binding)) {
+            throw new Error("context_compaction_checkpoint_not_applicable");
+        }
+        return previous;
+    };
+    return Object.freeze({
+        compactionScope: "active_request",
+        project(messages) {
+            const previous = readPrevious();
+            return previous
+                ? projectCheckpointMessages(messages, scopeId, previous, resultSourceOverrides)
+                : [...messages];
+        },
+        async prepare(messages) {
+            const previous = readPrevious();
+            const scanned = scanCompactionSources(messages, scopeId, resultSourceOverrides);
+            const covered = new Map(previous?.sourceDigests.map((source) => [source.sourceRef, source]) ??
+                []);
+            const newSources = scanned
+                .map(({ source }) => source)
+                .filter((source) => {
+                const existing = covered.get(source.sourceRef);
+                if (!existing)
+                    return true;
+                if (existing.sourceFingerprint !== source.sourceFingerprint) {
+                    throw new Error("context_compaction_source_identity_conflict");
+                }
+                return false;
+            });
+            if (newSources.length === 0) {
+                if (!previous) {
+                    throw new Error("context_compaction_sources_empty");
+                }
+                return Object.freeze({
+                    messages: projectCheckpointMessages(messages, scopeId, previous, resultSourceOverrides),
+                    commit() { },
+                    scopeId,
+                    sourceRevision: previous.sourceRevision,
+                    coveredSourceCount: previous.sourceDigests.length,
+                });
+            }
+            const candidate = await generateSemanticCompactionCandidateBatched({
+                request,
+                scopeId,
+                binding,
+                sourceRevision: options.sourceRevision,
+                preservationObjective: options.call.objective,
+                ...(previous ? { previous } : {}),
+                sources: newSources,
+            });
+            return Object.freeze({
+                messages: projectCheckpointMessages(messages, scopeId, candidate, resultSourceOverrides),
+                commit() {
+                    store.commit(candidate);
+                },
+                scopeId,
+                sourceRevision: candidate.sourceRevision,
+                coveredSourceCount: candidate.sourceDigests.length,
+            });
+        },
+    });
+}
+function projectCheckpointMessages(messages, scopeId, checkpoint, resultSourceOverrides) {
+    const scanned = scanCompactionSources(messages, scopeId, resultSourceOverrides);
+    const covered = new Map(checkpoint.sourceDigests.map((source) => [source.sourceRef, source]));
+    const removable = new Set();
+    let insertionIndex = messages.length;
+    const checkpointEmbedded = messages.some(isCheckpointCarrierMessage);
+    for (const { index, source } of scanned) {
+        const exact = covered.get(source.sourceRef);
+        if (exact?.sourceFingerprint === source.sourceFingerprint) {
+            if (!isCheckpointCarrierMessage(messages[index])) {
+                removable.add(index);
+                insertionIndex = Math.min(insertionIndex, index);
+            }
+        }
+    }
+    messages.forEach((message, index) => {
+        if (isCheckpointMessage(message, scopeId)) {
+            removable.add(index);
+            insertionIndex = Math.min(insertionIndex, index);
+        }
+    });
+    const checkpointMessage = buildCheckpointMessage(checkpoint);
+    const projected = [];
+    let inserted = false;
+    messages.forEach((message, index) => {
+        const requestToolResults = projectRequestToolResultsCheckpointMessage(message, checkpoint, resultSourceOverrides);
+        const payloadContext = projectPayloadContextCheckpointMessage(message, checkpoint, resultSourceOverrides);
+        if (!checkpointEmbedded && !inserted && index === insertionIndex) {
+            projected.push(checkpointMessage);
+            inserted = true;
+        }
+        if (!removable.has(index)) {
+            projected.push(requestToolResults ?? payloadContext ?? message);
+        }
+    });
+    if (!checkpointEmbedded && !inserted)
+        projected.push(checkpointMessage);
+    return projected;
+}
+function buildCheckpointMessage(checkpoint) {
+    return Object.freeze({
+        role: "user",
+        content: JSON.stringify({
+            kind: checkpoint.kind,
+            authority: "runtime_role_continuation",
+            presenceEffect: "passive_continuity_not_user_intent_routing_or_completion",
+            scopeId: checkpoint.scopeId,
+            roleId: checkpoint.roleId,
+            callId: checkpoint.callId,
+            sourceRevision: checkpoint.sourceRevision,
+            coveredSources: checkpoint.sourceDigests.map(({ sourceRef, sourceFingerprint, digest }) => ({
+                sourceRef,
+                sourceFingerprint,
+                digest,
+            })),
+            continuation: checkpoint.continuation,
+        }),
+    });
+}
+function scanCompactionSources(messages, scopeId, resultSourceOverrides) {
+    const sources = [];
+    messages.forEach((message, index) => {
+        if (isCheckpointMessage(message, scopeId))
+            return;
+        for (const source of resolveMessageSources(message, resultSourceOverrides)) {
+            sources.push(Object.freeze({ index, source }));
+        }
+    });
+    return Object.freeze(sources);
+}
+function resolveMessageSources(message, resultSourceOverrides) {
+    if (message.role === "tool") {
+        return Object.freeze([
+            createMessageSource(`tool-result:${message.toolCallId}`, message),
+        ]);
+    }
+    if (message.role === "assistant" && message.toolCalls) {
+        return Object.freeze([
+            createMessageSource(`tool-action:${createSemanticCompactionSha256Fingerprint(message.toolCalls.map(({ callId }) => callId).join("\n")).slice("sha256:".length)}`, message),
+        ]);
+    }
+    if (!message.content)
+        return Object.freeze([]);
+    const payloadContext = parsePayloadContextRecord(message.content);
+    if (payloadContext) {
+        return Object.freeze(readRecordArray(payloadContext.settledCapabilityResults).flatMap((result) => {
+            const source = resolveScannableResultSource(result, "payload-result", resultSourceOverrides);
+            return source ? [source] : [];
+        }));
+    }
+    const record = parseJsonRecord(message.content);
+    if (record?.kind === "runtime_request_tool_results_v1") {
+        return Object.freeze(readRecordArray(record.results).flatMap((result) => {
+            const source = resolveScannableResultSource(result, undefined, resultSourceOverrides);
+            return source ? [source] : [];
+        }));
+    }
+    if (record?.kind === "runtime_child_result") {
+        const resultRef = readNonEmptyString(record.resultRef);
+        return resultRef
+            ? Object.freeze([
+                createMessageSource(`child-result:${resultRef}`, message),
+            ])
+            : Object.freeze([]);
+    }
+    if (record?.kind === "runtime_execution_agent_auditor_evidence_v1") {
+        return Object.freeze([
+            createMessageSource(hashedMessageSourceRef("role-evidence", message.content), message),
+        ]);
+    }
+    const header = parseJsonRecord(message.content.split("\n", 1)[0] ?? "");
+    if (header?.kind === "runtime_reviewer_evidence_v1") {
+        const evidenceRef = readNonEmptyString(header.evidenceRef);
+        return Object.freeze([
+            createMessageSource(evidenceRef
+                ? `reviewer-evidence:${evidenceRef}`
+                : hashedMessageSourceRef("reviewer-evidence", message.content), message),
+        ]);
+    }
+    return Object.freeze([]);
+}
+function createMessageSource(sourceRef, message) {
+    const content = JSON.stringify(message);
+    return Object.freeze({
+        sourceRef,
+        sourceFingerprint: createSemanticCompactionSha256Fingerprint(content),
+        content,
+    });
+}
+function hashedMessageSourceRef(prefix, content) {
+    return `${prefix}:${createSemanticCompactionSha256Fingerprint(content).slice("sha256:".length)}`;
+}
+function isCheckpointMessage(message, scopeId) {
+    if (!message.content)
+        return false;
+    const record = parseJsonRecord(message.content);
+    return (record?.kind === "runtime_semantic_compaction_checkpoint_v2" &&
+        record.scopeId === scopeId);
+}
+function isCheckpointCarrierMessage(message) {
+    return (parseJsonRecord(message.content)?.kind ===
+        "runtime_request_tool_results_v1" ||
+        parsePayloadContextRecord(message.content) !== undefined);
+}
+function projectRequestToolResultsCheckpointMessage(message, checkpoint, resultSourceOverrides) {
+    const record = parseJsonRecord(message.content);
+    if (record?.kind !== "runtime_request_tool_results_v1")
+        return undefined;
+    if (message.role !== "user" || message.attachments?.length) {
+        throw new Error("context_compaction_request_tool_results_invalid");
+    }
+    const previousProjection = parseRecord(record.semanticCheckpoint);
+    const previousScopeId = readNonEmptyString(previousProjection?.scopeId);
+    if (previousScopeId && previousScopeId !== checkpoint.scopeId) {
+        throw new Error("context_compaction_checkpoint_scope_conflict");
+    }
+    const covered = new Map(checkpoint.sourceDigests.map((source) => [source.sourceRef, source]));
+    const coveredResults = new Map();
+    for (const receipt of readRecordArray(previousProjection?.coveredResults)) {
+        const executionId = readNonEmptyString(receipt.executionId);
+        const fingerprint = readNonEmptyString(receipt.sourceFingerprint);
+        const source = executionId
+            ? resolveResultSource(receipt, undefined, resultSourceOverrides)
+            : undefined;
+        const exact = source ? covered.get(source.sourceRef) : undefined;
+        if (!executionId ||
+            !fingerprint ||
+            exact?.sourceFingerprint !== fingerprint) {
+            throw new Error("context_compaction_checkpoint_receipt_invalid");
+        }
+        coveredResults.set(executionId, receipt);
+    }
+    const remainingResults = [];
+    for (const result of readRecordArray(record.results)) {
+        const executionId = readNonEmptyString(result.executionId);
+        const source = resolveResultSource(result, undefined, resultSourceOverrides);
+        const exact = source ? covered.get(source.sourceRef) : undefined;
+        if (!executionId || !source || !exact) {
+            remainingResults.push(result);
+            continue;
+        }
+        if (source.sourceFingerprint !== exact.sourceFingerprint) {
+            throw new Error("context_compaction_source_identity_conflict");
+        }
+        const { referenceData: _referenceData, adapterResult: _adapterResult, ...receipt } = result;
+        coveredResults.set(executionId, Object.freeze({
+            ...receipt,
+            sourceFingerprint: exact.sourceFingerprint,
+        }));
+    }
+    return Object.freeze({
+        role: "user",
+        content: JSON.stringify({
+            ...record,
+            semanticCheckpoint: {
+                kind: checkpoint.kind,
+                scopeId: checkpoint.scopeId,
+                roleId: checkpoint.roleId,
+                callId: checkpoint.callId,
+                checkpointSourceRevision: checkpoint.sourceRevision,
+                presenceEffect: "passive_role_continuation_not_user_intent_or_completion",
+                coveredSources: checkpoint.sourceDigests.map(({ sourceRef, sourceFingerprint, digest }) => ({
+                    sourceRef,
+                    sourceFingerprint,
+                    digest,
+                })),
+                continuation: checkpoint.continuation,
+                coveredResults: [...coveredResults.values()],
+            },
+            results: remainingResults,
+        }),
+    });
+}
+function projectPayloadContextCheckpointMessage(message, checkpoint, resultSourceOverrides) {
+    const context = parsePayloadContextRecord(message.content);
+    if (!context)
+        return undefined;
+    if (message.role !== "user" || message.attachments?.length) {
+        throw new Error("context_compaction_payload_context_invalid");
+    }
+    const previousProjection = parseRecord(context.semanticCheckpoint);
+    const previousScopeId = readNonEmptyString(previousProjection?.scopeId);
+    if (previousScopeId && previousScopeId !== checkpoint.scopeId) {
+        throw new Error("context_compaction_checkpoint_scope_conflict");
+    }
+    const covered = new Map(checkpoint.sourceDigests.map((source) => [source.sourceRef, source]));
+    const coveredResults = new Map();
+    for (const receipt of readRecordArray(previousProjection?.coveredResults)) {
+        const executionId = readNonEmptyString(receipt.executionId);
+        const fingerprint = readNonEmptyString(receipt.sourceFingerprint);
+        const source = executionId
+            ? resolveResultSource(receipt, "payload-result", resultSourceOverrides)
+            : undefined;
+        const exact = source ? covered.get(source.sourceRef) : undefined;
+        if (!executionId ||
+            !fingerprint ||
+            exact?.sourceFingerprint !== fingerprint) {
+            throw new Error("context_compaction_checkpoint_receipt_invalid");
+        }
+        coveredResults.set(executionId, receipt);
+    }
+    const remainingResults = [];
+    for (const result of readRecordArray(context.settledCapabilityResults)) {
+        const executionId = readNonEmptyString(result.executionId);
+        const source = resolveResultSource(result, "payload-result", resultSourceOverrides);
+        const exact = source ? covered.get(source.sourceRef) : undefined;
+        if (!executionId || !source || !exact) {
+            remainingResults.push(result);
+            continue;
+        }
+        if (source.sourceFingerprint !== exact.sourceFingerprint) {
+            throw new Error("context_compaction_source_identity_conflict");
+        }
+        const { referenceData: _referenceData, adapterResult: _adapterResult, ...receipt } = result;
+        coveredResults.set(executionId, Object.freeze({
+            ...receipt,
+            sourceFingerprint: exact.sourceFingerprint,
+        }));
+    }
+    return Object.freeze({
+        role: "user",
+        content: `${PAYLOAD_CONTEXT_PREFIX}${JSON.stringify({
+            ...context,
+            semanticCheckpoint: {
+                kind: checkpoint.kind,
+                scopeId: checkpoint.scopeId,
+                roleId: checkpoint.roleId,
+                callId: checkpoint.callId,
+                checkpointSourceRevision: checkpoint.sourceRevision,
+                presenceEffect: "passive_role_continuation_not_user_intent_or_completion",
+                coveredSources: checkpoint.sourceDigests.map(({ sourceRef, sourceFingerprint, digest }) => ({
+                    sourceRef,
+                    sourceFingerprint,
+                    digest,
+                })),
+                continuation: checkpoint.continuation,
+                coveredResults: [...coveredResults.values()],
+            },
+            settledCapabilityResults: remainingResults,
+        })}`,
+    });
+}
+function parseJsonRecord(value) {
+    try {
+        const decoded = JSON.parse(value);
+        return decoded && typeof decoded === "object" && !Array.isArray(decoded)
+            ? decoded
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function createResultSourceOverrideMap(sources) {
+    const overrides = new Map();
+    for (const source of sources) {
+        if (!source.sourceRef.trim() ||
+            !source.content ||
+            createSemanticCompactionSha256Fingerprint(source.content) !==
+                source.sourceFingerprint ||
+            overrides.has(source.sourceRef)) {
+            throw new Error("context_compaction_source_override_invalid");
+        }
+        overrides.set(source.sourceRef, source);
+    }
+    return overrides;
+}
+function resolveResultSource(result, sourceRefPrefix, overrides) {
+    const executionId = readNonEmptyString(result.executionId);
+    if (!executionId)
+        return undefined;
+    const override = overrides.get(executionId);
+    if (override)
+        return override;
+    const content = JSON.stringify(result);
+    return Object.freeze({
+        sourceRef: sourceRefPrefix
+            ? `${sourceRefPrefix}:${executionId}`
+            : executionId,
+        sourceFingerprint: createSemanticCompactionSha256Fingerprint(content),
+        content,
+    });
+}
+/**
+ * A summary-only receipt is a passive index entry, not a second representation
+ * of the exact evidence body. Only exact evidence (or a canonical override)
+ * can become a semantic-compaction source.
+ */
+function resolveScannableResultSource(result, sourceRefPrefix, overrides) {
+    const executionId = readNonEmptyString(result.executionId);
+    if (!executionId)
+        return undefined;
+    if (!overrides.has(executionId) &&
+        !readNonEmptyString(result.referenceData) &&
+        !parseRecord(result.adapterResult)) {
+        return undefined;
+    }
+    return resolveResultSource(result, sourceRefPrefix, overrides);
+}
+function parseRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function parsePayloadContextRecord(value) {
+    return value.startsWith(PAYLOAD_CONTEXT_PREFIX)
+        ? parseJsonRecord(value.slice(PAYLOAD_CONTEXT_PREFIX.length))
+        : undefined;
+}
+function readRecordArray(value) {
+    return Array.isArray(value)
+        ? value.flatMap((entry) => {
+            const record = parseRecord(entry);
+            return record ? [record] : [];
+        })
+        : [];
+}
+function readNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}

package/dist/src/runtime/context/pinned-context-compaction.d.ts

@@ -0,0 +1,33 @@
+import type { ChatMessage, ModelGatewayJsonSchemaFormat } from "../../model-gateway/types.js";
+import type { RequestContextBudget, RequestContextPinnedPart } from "./request-context-contracts.js";
+import { type RequestMessagesBudgetAssessment } from "./request-context-budget.js";
+type RequestContextDiagnostic = Readonly<{
+    requestId: string;
+    modelStep: string;
+    callId?: string;
+}>;
+type RequestContextEventSink = (name: string, extra?: Record<string, unknown>) => void;
+export type PinnedContextProjection = Readonly<{
+    referenceMessages: readonly ChatMessage[];
+    continuationMessages: readonly ChatMessage[];
+    assessment: RequestMessagesBudgetAssessment;
+    compaction: Readonly<{
+        applied: boolean;
+        compactedSourceRefs: readonly string[];
+    }>;
+    errorCode?: "request_context_pinned_content_exceeds_budget" | "request_context_required_content_exceeds_budget" | "request_context_compaction_not_reducing";
+}>;
+export declare function projectPinnedContext(params: {
+    fixedMessages: readonly ChatMessage[];
+    currentMessage: ChatMessage;
+    currentMessagePlacement?: "before_continuation" | "after_continuation";
+    referenceParts: readonly RequestContextPinnedPart[];
+    continuationParts: readonly RequestContextPinnedPart[];
+    format?: ModelGatewayJsonSchemaFormat;
+    budget: RequestContextBudget;
+    diagnostic?: RequestContextDiagnostic;
+    onEvent?: RequestContextEventSink;
+    /** The outer model-step owns client-visible compaction lifecycle events. */
+    deferLifecycleToModelStep?: boolean;
+}): PinnedContextProjection;
+export {};