@abot-ai/runtime 1.0.0

package/dist/src/runtime/context/pinned-context-compaction.js

@@ -0,0 +1,235 @@
+import { traceDebug } from "../observability/debug-logger.js";
+import { assessRequestMessagesBudget, resolveContextCompactionTriggerInputTokens, } from "./request-context-budget.js";
+import { estimateMessagesTokens } from "./token-estimator.js";
+export function projectPinnedContext(params) {
+    const states = validateAndIndexParts([
+        ...params.referenceParts,
+        ...params.continuationParts,
+    ]);
+    const fullProjection = assessStates(params, states);
+    const triggerInputTokens = resolveContextCompactionTriggerInputTokens(params.budget.contextWindowTokens);
+    const thresholdCrossed = fullProjection.assessment.budget.estimatedInputTokens >=
+        triggerInputTokens;
+    if (!thresholdCrossed && fullProjection.assessment.fits) {
+        return Object.freeze({
+            ...fullProjection,
+            compaction: NO_COMPACTION,
+            ...(!fullProjection.assessment.fits
+                ? { errorCode: "request_context_pinned_content_exceeds_budget" }
+                : {}),
+        });
+    }
+    const candidates = states
+        .map((state) => ({
+        state,
+        savings: estimatePartSavings(state.part, params.budget),
+    }))
+        .filter((candidate) => candidate.state.part.retention === "compactable" &&
+        candidate.savings > 0)
+        .sort((left, right) => right.savings - left.savings ||
+        left.state.order - right.state.order);
+    traceCompaction(params.diagnostic, "triggered", {
+        estimatedInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+        availableInputTokens: fullProjection.assessment.budget.availableInputTokens,
+        triggerInputTokens,
+        compactablePartCount: candidates.length,
+    });
+    if (candidates.length === 0) {
+        if (fullProjection.assessment.fits) {
+            traceCompaction(params.diagnostic, "skipped", {
+                reason: "no_compact_variant",
+            });
+            return Object.freeze({
+                ...fullProjection,
+                compaction: NO_COMPACTION,
+            });
+        }
+        emitCompactionEvent(params, "context.compaction.failed", {
+            phase: "failed",
+            reason: "required_content_exceeds_budget",
+            beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+            availableInputTokens: fullProjection.assessment.budget.availableInputTokens,
+        });
+        traceCompaction(params.diagnostic, params.deferLifecycleToModelStep ? "deferred" : "rejected", {
+            reason: "required_content_exceeds_budget",
+            compactedPartCount: 0,
+        });
+        return Object.freeze({
+            ...fullProjection,
+            compaction: NO_COMPACTION,
+            errorCode: "request_context_required_content_exceeds_budget",
+        });
+    }
+    emitCompactionEvent(params, "context.compaction.started", {
+        phase: "started",
+        beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+        triggerInputTokens,
+        compactablePartCount: candidates.length,
+    });
+    let nextStates = states;
+    let compactedProjection = fullProjection;
+    for (const candidate of candidates) {
+        nextStates = nextStates.map((state) => state.order === candidate.state.order
+            ? Object.freeze({ ...state, compacted: true })
+            : state);
+        compactedProjection = assessStates(params, nextStates);
+        if (compactedProjection.assessment.fits &&
+            compactedProjection.assessment.budget.estimatedInputTokens <
+                triggerInputTokens) {
+            break;
+        }
+    }
+    const compactedSourceRefs = Object.freeze(nextStates
+        .filter((state) => state.compacted)
+        .sort((left, right) => left.order - right.order)
+        .map((state) => state.part.sourceRef));
+    const compaction = Object.freeze({
+        applied: compactedSourceRefs.length > 0,
+        compactedSourceRefs,
+    });
+    if (!compactedProjection.assessment.fits) {
+        emitCompactionEvent(params, "context.compaction.failed", {
+            phase: "failed",
+            reason: "required_content_exceeds_budget",
+            beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+            afterInputTokens: compactedProjection.assessment.budget.estimatedInputTokens,
+            availableInputTokens: compactedProjection.assessment.budget.availableInputTokens,
+            compactedPartCount: compactedSourceRefs.length,
+        });
+        traceCompaction(params.diagnostic, params.deferLifecycleToModelStep ? "deferred" : "rejected", {
+            reason: "required_content_exceeds_budget",
+            beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+            afterInputTokens: compactedProjection.assessment.budget.estimatedInputTokens,
+            compactedPartCount: compactedSourceRefs.length,
+        });
+        return Object.freeze({
+            ...compactedProjection,
+            compaction,
+            errorCode: "request_context_required_content_exceeds_budget",
+        });
+    }
+    if (compactedProjection.assessment.budget.estimatedInputTokens >=
+        triggerInputTokens) {
+        emitCompactionEvent(params, "context.compaction.failed", {
+            phase: "failed",
+            reason: "compaction_not_reducing",
+            beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+            afterInputTokens: compactedProjection.assessment.budget.estimatedInputTokens,
+            triggerInputTokens,
+            compactedPartCount: compactedSourceRefs.length,
+        });
+        traceCompaction(params.diagnostic, params.deferLifecycleToModelStep ? "deferred" : "rejected", {
+            reason: "compaction_not_reducing",
+            beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+            afterInputTokens: compactedProjection.assessment.budget.estimatedInputTokens,
+            compactedPartCount: compactedSourceRefs.length,
+        });
+        return Object.freeze({
+            ...compactedProjection,
+            compaction,
+            errorCode: "request_context_compaction_not_reducing",
+        });
+    }
+    emitCompactionEvent(params, "context.compaction.completed", {
+        phase: "completed",
+        beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+        afterInputTokens: compactedProjection.assessment.budget.estimatedInputTokens,
+        triggerInputTokens,
+        compactedPartCount: compactedSourceRefs.length,
+    });
+    traceCompaction(params.diagnostic, "completed", {
+        beforeInputTokens: fullProjection.assessment.budget.estimatedInputTokens,
+        afterInputTokens: compactedProjection.assessment.budget.estimatedInputTokens,
+        triggerInputTokens,
+        compactedPartCount: compactedSourceRefs.length,
+        compactedSourceRefs,
+    });
+    return Object.freeze({
+        ...compactedProjection,
+        compaction,
+    });
+}
+const NO_COMPACTION = Object.freeze({
+    applied: false,
+    compactedSourceRefs: Object.freeze([]),
+});
+function validateAndIndexParts(parts) {
+    const sourceRefs = new Set();
+    return Object.freeze(parts.map((part, order) => {
+        if (!part.sourceRef.trim() || sourceRefs.has(part.sourceRef)) {
+            throw new Error("request_context_pinned_part_source_invalid");
+        }
+        sourceRefs.add(part.sourceRef);
+        if (part.messages.length === 0) {
+            throw new Error("request_context_pinned_part_messages_required");
+        }
+        if (part.retention === "compactable" &&
+            (!part.compactMessages || part.compactMessages.length === 0)) {
+            throw new Error("request_context_compact_projection_required");
+        }
+        return Object.freeze({ part, order, compacted: false });
+    }));
+}
+function assessStates(params, states) {
+    const referenceMessages = flattenPartMessages(states, "request_reference");
+    const continuationMessages = flattenPartMessages(states, "role_continuation");
+    const assessment = assessRequestMessagesBudget({
+        messages: params.currentMessagePlacement === "after_continuation"
+            ? [
+                ...params.fixedMessages,
+                ...referenceMessages,
+                ...continuationMessages,
+                params.currentMessage,
+            ]
+            : [
+                ...params.fixedMessages,
+                ...referenceMessages,
+                params.currentMessage,
+                ...continuationMessages,
+            ],
+        ...(params.format ? { format: params.format } : {}),
+        budget: params.budget,
+    });
+    return Object.freeze({
+        referenceMessages,
+        continuationMessages,
+        assessment,
+    });
+}
+function flattenPartMessages(states, category) {
+    return Object.freeze(states
+        .filter((state) => state.part.category === category)
+        .sort((left, right) => left.order - right.order)
+        .flatMap((state) => state.compacted
+        ? [...(state.part.compactMessages ?? state.part.messages)]
+        : [...state.part.messages]));
+}
+function estimatePartSavings(part, budget) {
+    if (part.retention !== "compactable" || !part.compactMessages) {
+        return 0;
+    }
+    return (estimateMessagesTokens(part.messages, budget.tokenEstimation) -
+        estimateMessagesTokens(part.compactMessages, budget.tokenEstimation));
+}
+function emitCompactionEvent(params, name, extra) {
+    if (params.deferLifecycleToModelStep) {
+        return;
+    }
+    params.onEvent?.(name, {
+        stage: "context_compaction",
+        ...(params.diagnostic?.modelStep
+            ? { modelStep: params.diagnostic.modelStep }
+            : {}),
+        ...extra,
+    });
+}
+function traceCompaction(diagnostic, phase, extra) {
+    if (!diagnostic) {
+        return;
+    }
+    traceDebug("runtime.context", `compaction.${phase}`, {
+        ...diagnostic,
+        phase: "request_projection",
+        ...extra,
+    });
+}

package/dist/src/runtime/context/request-context-budget.d.ts

@@ -0,0 +1,17 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { RequestContextBudget, RequestContextBudgetEstimate } from "./request-context-contracts.js";
+export type RequestMessagesBudgetAssessment = Readonly<{
+    fits: boolean;
+    budget: RequestContextBudgetEstimate;
+}>;
+export declare const CONTEXT_COMPACTION_TRIGGER_RATIO = 0.7;
+export declare function resolveContextCompactionTriggerInputTokens(contextWindowTokens: number): number;
+export declare function assessRequestMessagesBudget(params: {
+    messages: readonly ChatMessage[];
+    format?: Readonly<{
+        schema: unknown;
+    }>;
+    budget: RequestContextBudget;
+    measuredInputTokens?: number;
+}): RequestMessagesBudgetAssessment;
+export declare function resolveRequestBudgetInputTokens(budget: Pick<RequestContextBudgetEstimate, "estimatedInputTokens" | "measuredInputTokens">): number;

package/dist/src/runtime/context/request-context-budget.js

@@ -0,0 +1,51 @@
+import { estimateMessagesTokens, estimateTextTokens, } from "./token-estimator.js";
+export const CONTEXT_COMPACTION_TRIGGER_RATIO = 0.7;
+export function resolveContextCompactionTriggerInputTokens(contextWindowTokens) {
+    return Math.ceil(contextWindowTokens * CONTEXT_COMPACTION_TRIGGER_RATIO);
+}
+export function assessRequestMessagesBudget(params) {
+    const formatTokenAccounting = params.budget.formatTokenAccounting;
+    const formatReserveTokens = params.format && formatTokenAccounting?.mode !== "none"
+        ? estimateTextTokens(JSON.stringify(params.format.schema), params.budget.tokenEstimation) + (formatTokenAccounting?.fixedOverheadTokens ?? 0)
+        : 0;
+    const attachmentCount = params.messages.reduce((total, message) => total + (message.attachments?.length ?? 0), 0);
+    const attachmentReserveTokens = attachmentCount * params.budget.attachmentReserveTokens;
+    const configuredInstructionReserveTokens = params.budget.configuredInstructionReserveTokens ?? 0;
+    const availableInputTokens = params.budget.contextWindowTokens -
+        params.budget.outputReserveTokens -
+        params.budget.safetyReserveTokens -
+        configuredInstructionReserveTokens;
+    const estimatedInputTokens = estimateMessagesTokens(params.messages, params.budget.tokenEstimation) +
+        attachmentReserveTokens +
+        formatReserveTokens;
+    const measuredInputTokens = params.measuredInputTokens;
+    if (measuredInputTokens !== undefined &&
+        (!Number.isSafeInteger(measuredInputTokens) || measuredInputTokens < 0)) {
+        throw new TypeError("request_context_measured_input_tokens_invalid");
+    }
+    const assessedInputTokens = measuredInputTokens ?? estimatedInputTokens;
+    const remainingContextTokens = Math.max(0, params.budget.contextWindowTokens - assessedInputTokens);
+    const usedContextPercent = Math.round((assessedInputTokens / params.budget.contextWindowTokens) * 1_000) / 10;
+    return Object.freeze({
+        fits: availableInputTokens > 0 && assessedInputTokens <= availableInputTokens,
+        budget: Object.freeze({
+            contextWindowTokens: params.budget.contextWindowTokens,
+            availableInputTokens,
+            outputReserveTokens: params.budget.outputReserveTokens,
+            safetyReserveTokens: params.budget.safetyReserveTokens,
+            ...(configuredInstructionReserveTokens > 0
+                ? { configuredInstructionReserveTokens }
+                : {}),
+            formatReserveTokens,
+            attachmentReserveTokens,
+            estimatedInputTokens,
+            ...(measuredInputTokens !== undefined ? { measuredInputTokens } : {}),
+            remainingContextTokens,
+            usedContextPercent,
+            compactionTriggerInputTokens: resolveContextCompactionTriggerInputTokens(params.budget.contextWindowTokens),
+        }),
+    });
+}
+export function resolveRequestBudgetInputTokens(budget) {
+    return budget.measuredInputTokens ?? budget.estimatedInputTokens;
+}

package/dist/src/runtime/context/request-context-contracts.d.ts

@@ -0,0 +1,64 @@
+import type { ChatMessage, ModelFormatTokenAccountingConfig, ModelTokenEstimationConfig } from "../../model-gateway/types.js";
+import type { SessionMessageGrounding } from "../../sessions/types.js";
+export type RequestHistoryMessage = Readonly<{
+    id: string;
+    role: "user" | "assistant";
+    content: string;
+    createdAt: string;
+    requestId?: string;
+    grounding?: SessionMessageGrounding;
+}>;
+export type RequestContextBudget = Readonly<{
+    contextWindowTokens: number;
+    outputReserveTokens: number;
+    safetyReserveTokens: number;
+    attachmentReserveTokens: number;
+    /** Configured methodology not yet present during early context projection. */
+    configuredInstructionReserveTokens?: number;
+    formatTokenAccounting?: ModelFormatTokenAccountingConfig;
+    tokenEstimation?: ModelTokenEstimationConfig;
+}>;
+export type RequestContextPinnedPartCategory = "request_reference" | "role_continuation";
+export type RequestContextPinnedPart = Readonly<{
+    sourceRef: string;
+    category: RequestContextPinnedPartCategory;
+    retention: "exact" | "compactable";
+    messages: readonly ChatMessage[];
+    compactMessages?: readonly ChatMessage[];
+}>;
+export type RequestContextBudgetEstimate = Readonly<{
+    contextWindowTokens: number;
+    availableInputTokens: number;
+    outputReserveTokens: number;
+    safetyReserveTokens: number;
+    configuredInstructionReserveTokens?: number;
+    formatReserveTokens: number;
+    attachmentReserveTokens: number;
+    estimatedInputTokens: number;
+    /** Exact preflight count when the selected provider exposes that capability. */
+    measuredInputTokens?: number;
+    remainingContextTokens: number;
+    usedContextPercent: number;
+    compactionTriggerInputTokens: number;
+}>;
+export type RequestContextBudgetParts = Readonly<{
+    instructionInputTokens: number;
+    priorConversationInputTokens: number;
+    referenceInputTokens: number;
+    currentPromptInputTokens: number;
+    continuationInputTokens: number;
+    selectedHistoryInputTokens: number;
+    pinnedInputTokens: number;
+}>;
+export type RequestContextProjection = Readonly<{
+    messages: ChatMessage[];
+    selectedHistoryMessageIds: string[];
+    omittedHistoryMessageIds: string[];
+    budget: RequestContextBudgetEstimate & {
+        parts: RequestContextBudgetParts;
+    };
+    compaction: Readonly<{
+        applied: boolean;
+        compactedSourceRefs: readonly string[];
+    }>;
+}>;

package/dist/src/runtime/context/request-context-contracts.js

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

package/dist/src/runtime/context/request-context.d.ts

@@ -0,0 +1,30 @@
+import type { ChatMessage, ModelGatewayAttachment, ModelGatewayJsonSchemaFormat } from "../../model-gateway/types.js";
+import type { RequestContextBudget, RequestContextPinnedPart, RequestContextProjection, RequestHistoryMessage } from "./request-context-contracts.js";
+type RequestContextDiagnostic = Readonly<{
+    requestId: string;
+    modelStep: string;
+    callId?: string;
+}>;
+export { assessRequestMessagesBudget } from "./request-context-budget.js";
+export type { RequestMessagesBudgetAssessment } from "./request-context-budget.js";
+export declare function projectRequestContext(params: {
+    instructions: string;
+    format?: ModelGatewayJsonSchemaFormat;
+    historyMessages: readonly RequestHistoryMessage[];
+    prompt: string;
+    currentMessagePlacement?: "before_continuation" | "after_continuation";
+    attachments?: ModelGatewayAttachment[];
+    priorConversationMessages?: readonly ChatMessage[];
+    referenceMessages?: readonly ChatMessage[];
+    continuationMessages?: readonly ChatMessage[];
+    referenceParts?: readonly RequestContextPinnedPart[];
+    continuationParts?: readonly RequestContextPinnedPart[];
+    budget: RequestContextBudget;
+    diagnostic?: RequestContextDiagnostic;
+    onEvent?: (name: string, extra?: Record<string, unknown>) => void;
+    /** Allows the shared model-step admission gate to compact before dispatch. */
+    deferCompactionFailure?: boolean;
+    historyRetention?: "compaction_managed";
+}): RequestContextProjection;
+/** Returns the latest complete visible user-to-assistant turn, if one exists. */
+export declare function projectLatestCompleteConversationTurn(historyMessages: readonly RequestHistoryMessage[]): readonly [RequestHistoryMessage, RequestHistoryMessage] | undefined;

package/dist/src/runtime/context/request-context.js

@@ -0,0 +1,242 @@
+import { traceDebug } from "../observability/debug-logger.js";
+import { projectPinnedContext } from "./pinned-context-compaction.js";
+import { estimateMessagesTokens } from "./token-estimator.js";
+export { assessRequestMessagesBudget } from "./request-context-budget.js";
+export function projectRequestContext(params) {
+    const attachments = params.attachments ?? [];
+    const priorConversationMessages = params.priorConversationMessages ?? [];
+    const referenceParts = resolvePinnedParts({
+        category: "request_reference",
+        legacyMessages: params.referenceMessages,
+        parts: params.referenceParts,
+    });
+    const continuationParts = resolvePinnedParts({
+        category: "role_continuation",
+        legacyMessages: params.continuationMessages,
+        parts: params.continuationParts,
+    });
+    const fixedMessages = [
+        { role: "system", content: params.instructions },
+        ...priorConversationMessages,
+    ];
+    const currentMessage = {
+        role: "user",
+        content: params.prompt,
+        ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    const pinnedProjection = projectPinnedContext({
+        fixedMessages,
+        currentMessage,
+        ...(params.currentMessagePlacement
+            ? { currentMessagePlacement: params.currentMessagePlacement }
+            : {}),
+        referenceParts,
+        continuationParts,
+        ...(params.format ? { format: params.format } : {}),
+        budget: params.budget,
+        ...(params.diagnostic ? { diagnostic: params.diagnostic } : {}),
+        ...(params.onEvent ? { onEvent: params.onEvent } : {}),
+        ...(params.deferCompactionFailure
+            ? { deferLifecycleToModelStep: true }
+            : {}),
+    });
+    const referenceMessages = pinnedProjection.referenceMessages;
+    const continuationMessages = pinnedProjection.continuationMessages;
+    const pinnedAssessment = pinnedProjection.assessment;
+    const availableInputTokens = pinnedAssessment.budget.availableInputTokens;
+    const pinnedTokenEstimate = pinnedAssessment.budget.estimatedInputTokens;
+    const baseParts = Object.freeze({
+        instructionInputTokens: estimateMessagesTokens(fixedMessages.slice(0, 1), params.budget.tokenEstimation),
+        priorConversationInputTokens: estimateMessagesTokens(priorConversationMessages, params.budget.tokenEstimation),
+        referenceInputTokens: estimateMessagesTokens(referenceMessages, params.budget.tokenEstimation),
+        currentPromptInputTokens: estimateMessagesTokens([currentMessage], params.budget.tokenEstimation),
+        continuationInputTokens: estimateMessagesTokens(continuationMessages, params.budget.tokenEstimation),
+        selectedHistoryInputTokens: 0,
+        pinnedInputTokens: pinnedTokenEstimate,
+    });
+    if (!pinnedAssessment.fits) {
+        traceRequestContextBudgetAssessment({
+            diagnostic: params.diagnostic,
+            outcome: "rejected",
+            issueCode: pinnedProjection.errorCode ===
+                "request_context_required_content_exceeds_budget"
+                ? "required_content_exceeds_budget"
+                : "pinned_content_exceeds_budget",
+            budget: pinnedAssessment.budget,
+            parts: baseParts,
+            historyMessageCount: params.historyMessages.length,
+            selectedHistoryMessageCount: 0,
+            omittedHistoryMessageCount: params.historyMessages.length,
+            referenceMessageCount: referenceMessages.length,
+            continuationMessageCount: continuationMessages.length,
+            attachmentCount: attachments.length,
+        });
+        if (!params.deferCompactionFailure) {
+            throw new Error(pinnedProjection.errorCode ??
+                "request_context_pinned_content_exceeds_budget");
+        }
+    }
+    const turns = collectConversationTurns(params.historyMessages);
+    const selectedTurns = [];
+    let selectedMessageCount = 0;
+    let estimatedInputTokens = pinnedTokenEstimate;
+    for (let index = turns.length - 1; index >= 0; index -= 1) {
+        const turn = turns[index];
+        const historyIsCompactionManaged = params.historyRetention === "compaction_managed";
+        const turnTokens = estimateMessagesTokens(turn.messages, params.budget.tokenEstimation);
+        if (!historyIsCompactionManaged &&
+            estimatedInputTokens + turnTokens > availableInputTokens) {
+            break;
+        }
+        selectedTurns.unshift(turn);
+        selectedMessageCount += turn.messages.length;
+        estimatedInputTokens += turnTokens;
+    }
+    const selectedHistoryMessageIds = selectedTurns.flatMap((turn) => turn.source.map((message) => message.id));
+    const selectedIds = new Set(selectedHistoryMessageIds);
+    const historyMessageIds = params.historyMessages.map((message) => message.id);
+    const parts = Object.freeze({
+        ...baseParts,
+        selectedHistoryInputTokens: estimatedInputTokens - pinnedTokenEstimate,
+    });
+    const budget = Object.freeze({
+        ...pinnedAssessment.budget,
+        estimatedInputTokens,
+        parts,
+    });
+    traceRequestContextBudgetAssessment({
+        diagnostic: params.diagnostic,
+        outcome: "projected",
+        budget,
+        parts,
+        historyMessageCount: params.historyMessages.length,
+        selectedHistoryMessageCount: selectedHistoryMessageIds.length,
+        omittedHistoryMessageCount: historyMessageIds.length - selectedHistoryMessageIds.length,
+        referenceMessageCount: referenceMessages.length,
+        continuationMessageCount: continuationMessages.length,
+        attachmentCount: attachments.length,
+    });
+    const trailingMessages = params.currentMessagePlacement === "after_continuation"
+        ? [...continuationMessages, currentMessage]
+        : [currentMessage, ...continuationMessages];
+    return {
+        messages: [
+            ...fixedMessages,
+            ...selectedTurns.flatMap((turn) => turn.messages),
+            ...referenceMessages,
+            ...trailingMessages,
+        ],
+        selectedHistoryMessageIds,
+        omittedHistoryMessageIds: historyMessageIds.filter((id) => !selectedIds.has(id)),
+        budget,
+        compaction: pinnedProjection.compaction,
+    };
+}
+function resolvePinnedParts(params) {
+    const legacyMessages = params.legacyMessages ?? [];
+    if (legacyMessages.length > 0 && params.parts !== undefined) {
+        throw new Error("request_context_pinned_parts_conflict");
+    }
+    if (params.parts !== undefined) {
+        if (params.parts.some((part) => part.category !== params.category)) {
+            throw new Error("request_context_pinned_part_category_invalid");
+        }
+        return params.parts;
+    }
+    if (legacyMessages.length === 0) {
+        return Object.freeze([]);
+    }
+    return Object.freeze([
+        Object.freeze({
+            sourceRef: `legacy:${params.category}`,
+            category: params.category,
+            retention: "exact",
+            messages: Object.freeze([...legacyMessages]),
+        }),
+    ]);
+}
+function traceRequestContextBudgetAssessment(params) {
+    if (!params.diagnostic) {
+        return;
+    }
+    traceDebug("runtime.context", "budget.assessed", {
+        ...params.diagnostic,
+        phase: "request_projection",
+        outcome: params.outcome,
+        fits: params.outcome === "projected",
+        issueCode: params.issueCode ?? "",
+        ...params.budget,
+        ...params.parts,
+        historyMessageCount: params.historyMessageCount,
+        selectedHistoryMessageCount: params.selectedHistoryMessageCount,
+        omittedHistoryMessageCount: params.omittedHistoryMessageCount,
+        referenceMessageCount: params.referenceMessageCount,
+        continuationMessageCount: params.continuationMessageCount,
+        attachmentCount: params.attachmentCount,
+    });
+}
+/** Returns the latest complete visible user-to-assistant turn, if one exists. */
+export function projectLatestCompleteConversationTurn(historyMessages) {
+    const turns = collectConversationTurns(historyMessages);
+    for (let index = turns.length - 1; index >= 0; index -= 1) {
+        const source = turns[index].source;
+        if (source.length === 2 &&
+            source[0]?.role === "user" &&
+            source[1]?.role === "assistant") {
+            return Object.freeze([source[0], source[1]]);
+        }
+    }
+    return undefined;
+}
+function collectConversationTurns(historyMessages) {
+    const visibleMessages = historyMessages.filter((message) => message.grounding !== "tool_observation" &&
+        message.content.trim().length > 0);
+    const turns = [];
+    for (const message of visibleMessages) {
+        if (message.role === "user") {
+            turns.push(createConversationTurn(message));
+            continue;
+        }
+        const pendingTurn = findPendingConversationTurn(turns, message);
+        if (!pendingTurn) {
+            continue;
+        }
+        pendingTurn.source.push(message);
+        pendingTurn.messages.push({
+            role: "assistant",
+            content: message.content,
+        });
+    }
+    return turns;
+}
+function createConversationTurn(user, assistant) {
+    return {
+        source: assistant ? [user, assistant] : [user],
+        messages: [
+            { role: "user", content: user.content },
+            ...(assistant
+                ? [{ role: "assistant", content: assistant.content }]
+                : []),
+        ],
+    };
+}
+function findPendingConversationTurn(turns, assistant) {
+    const pendingTurns = turns.filter((turn) => turn.source.length === 1);
+    if (assistant.requestId) {
+        const exactMatch = findLastConversationTurn(pendingTurns, (turn) => turn.source[0]?.requestId === assistant.requestId);
+        if (exactMatch) {
+            return exactMatch;
+        }
+        return findLastConversationTurn(pendingTurns, (turn) => !turn.source[0]?.requestId);
+    }
+    return pendingTurns.at(-1);
+}
+function findLastConversationTurn(turns, predicate) {
+    for (let index = turns.length - 1; index >= 0; index -= 1) {
+        const turn = turns[index];
+        if (predicate(turn)) {
+            return turn;
+        }
+    }
+    return undefined;
+}

package/dist/src/runtime/context/request-source.d.ts

@@ -0,0 +1,33 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { ModelStep } from "../../shared/model-steps.js";
+import type { RequestHistoryMessage } from "./request-context-contracts.js";
+export declare const REQUEST_SOURCE_MESSAGE_KIND: "runtime_request_source_v1";
+export type RequestSourceView = Readonly<{
+    requestId: string;
+    sourceRef: string;
+    currentRequest: string;
+    precedingTurn?: RequestSourcePrecedingTurn;
+}>;
+export type RequestSourcePrecedingTurn = Readonly<{
+    user: RequestSourceTurnMessage;
+    assistant: RequestSourceTurnMessage;
+}>;
+export type RequestSourceTurnMessage = Readonly<{
+    id: string;
+    content: string;
+    requestId?: string;
+}>;
+/**
+ * Projects the exact current user request without interpreting, selecting,
+ * normalizing, or copying it into canonical orchestration state. When history
+ * is supplied, it also projects the mechanically latest complete visible
+ * conversation turn as bounded source data.
+ */
+export declare function projectRequestSource(params: Readonly<{
+    requestId: string;
+    prompt: string;
+    modelStep: ModelStep;
+    callId: string;
+    historyMessages?: readonly RequestHistoryMessage[];
+}>): RequestSourceView;
+export declare function buildRequestSourceMessage(view: RequestSourceView): ChatMessage;