@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/runtime/capabilities/request-tool-state.d.ts

@@ -0,0 +1,13 @@
+import type { ToolRequestState } from "../../capabilities/tool-request-resources.js";
+/** Pending capsules remain data-only until an owning plugin registers its codec. */
+export declare class RequestToolState {
+    private readonly pending;
+    private readonly owners;
+    private closed;
+    readonly port: ToolRequestState;
+    snapshot(): Readonly<Record<string, unknown>>;
+    restore(value: unknown): void;
+    assertRestoredStateClaimed(): void;
+    dispose(): Promise<void>;
+    private assertOpen;
+}

package/dist/src/runtime/capabilities/request-tool-state.js

@@ -0,0 +1,75 @@
+/** Pending capsules remain data-only until an owning plugin registers its codec. */
+export class RequestToolState {
+    pending = new Map();
+    owners = new Map();
+    closed = false;
+    port = Object.freeze({
+        read: (key) => {
+            this.assertOpen();
+            return structuredClone(this.pending.get(key));
+        },
+        register: (key, codec) => {
+            this.assertOpen();
+            if (!key || this.owners.has(key))
+                throw new Error("tool_request_state_owner_conflict");
+            this.owners.set(key, codec);
+            this.pending.delete(key);
+        },
+    });
+    snapshot() {
+        this.assertOpen();
+        return Object.fromEntries([
+            ...this.pending,
+            ...[...this.owners].map(([key, codec]) => [key, captureJson(codec.snapshot())]),
+        ]);
+    }
+    restore(value) {
+        this.assertOpen();
+        if (!value ||
+            typeof value !== "object" ||
+            Array.isArray(value) ||
+            this.pending.size ||
+            this.owners.size)
+            throw new Error("tool_request_state_invalid");
+        for (const [key, entry] of Object.entries(value))
+            this.pending.set(key, captureJson(entry));
+    }
+    assertRestoredStateClaimed() {
+        if (this.pending.size)
+            throw new Error("tool_request_state_owner_unavailable");
+    }
+    async dispose() {
+        this.closed = true;
+        const owners = [...this.owners.values()];
+        this.pending.clear();
+        this.owners.clear();
+        await Promise.allSettled(owners.map((owner) => Promise.resolve().then(() => owner.dispose?.())));
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error("tool_request_state_closed");
+    }
+}
+function captureJson(value) {
+    const visit = (input, seen) => {
+        if (input === null ||
+            typeof input === "string" ||
+            typeof input === "boolean")
+            return;
+        if (typeof input === "number" && Number.isFinite(input))
+            return;
+        if (typeof input !== "object" || seen.has(input))
+            throw new Error("tool_request_state_not_serializable");
+        const prototype = Object.getPrototypeOf(input);
+        if (!Array.isArray(input) &&
+            prototype !== Object.prototype &&
+            prototype !== null)
+            throw new Error("tool_request_state_not_serializable");
+        seen.add(input);
+        for (const child of Object.values(input))
+            visit(child, seen);
+        seen.delete(input);
+    };
+    visit(value, new Set());
+    return structuredClone(value);
+}

package/dist/src/runtime/capabilities/request-working-directory.d.ts

@@ -0,0 +1,3 @@
+import type { ToolExecutionSharedState } from "../../capabilities/tool-types.js";
+/** The immutable session root replaces only agent_work, never shared namespaces. */
+export declare function bindRequestWorkingDirectory(state: ToolExecutionSharedState, directory?: string): ToolExecutionSharedState;

package/dist/src/runtime/capabilities/request-working-directory.js

@@ -0,0 +1,12 @@
+import { isAbsolute } from "node:path";
+/** The immutable session root replaces only agent_work, never shared namespaces. */
+export function bindRequestWorkingDirectory(state, directory) {
+    if (directory === undefined)
+        return state;
+    if (!isAbsolute(directory))
+        throw new TypeError("request_working_directory_absolute_required");
+    return {
+        ...state,
+        runtimePaths: { ...state.runtimePaths, agentWorkDir: directory },
+    };
+}

package/dist/src/runtime/capabilities/scheduling/job-list-page.d.ts

@@ -11,7 +11,7 @@ export declare function createSchedulerJobPage(jobs: readonly SchedulerJob[], pa
         title: string;
         modelProfileId: string;
         agentMode: import("../../../shared/types.js").AgentMode;
-        toolPermissionMode: "full_access";
+        toolPermissionMode: import("../../scheduler/tool-permission-mode.js").SchedulerToolPermissionMode;
         timeZone: string;
         schedule: import("../../scheduler/contracts.js").SchedulerSchedule;
         state: import("../../scheduler/contracts.js").SchedulerJobState;

package/dist/src/runtime/composition.d.ts

@@ -1,4 +1,5 @@
 import type WebSocket from "ws";
+import type { RuntimeProjectService } from "./projects/contracts.js";
 import type { EventSinkFactory, ModelGatewayClient, RuntimeConfig, RuntimeHost, SessionStore, ToolRegistry } from "./ports.js";
 import type { RuntimeAttachmentStore } from "./attachments/store.js";
 import type { RequestHandlerOptions, RunRequestMessage } from "./request/contracts.js";
@@ -7,27 +8,31 @@ import type { LongTermMemoryService } from "./long-term-memory/contracts.js";
 import type { SchedulerRun, SchedulerService } from "./scheduler/contracts.js";
 import { SessionRequestAdmission } from "./request/session-admission.js";
 import type { RequestSteeringAppendResult } from "./request/request-steering.js";
+import type { PassiveLearningService } from "./passive-learning/contracts.js";
 export type RuntimeEnvironmentServices = Readonly<{
     config: RuntimeConfig;
     sessions: SessionStore;
+    projects?: RuntimeProjectService;
     attachments: RuntimeAttachmentStore;
     tools: ToolRegistry;
     models: ModelGatewayClient;
     events: EventSinkFactory;
     sessionMemoryCompactor: SessionMemoryCompactor;
     longTermMemory: LongTermMemoryService;
+    passiveLearning?: PassiveLearningService;
     scheduler?: SchedulerService;
     startScheduler?: () => Promise<void>;
     stopScheduler?: () => Promise<void>;
     requestAdmission?: SessionRequestAdmission;
 }>;
-export type RuntimeRequestOptions = Pick<RequestHandlerOptions, "toolApprovalController" | "requestSteering">;
+export type RuntimeRequestOptions = Pick<RequestHandlerOptions, "toolApprovalController" | "requestSteering" | "abortSignal" | "claimFinalization" | "durableApprovals" | "approvalExecution">;
 export type RuntimeRequestHandler = Readonly<{
+    cancel?: (requestId: string, sessionId: string, wait?: import("./request/cancellation.js").SavedWaitCancellation) => Promise<import("./request/cancellation.js").RequestCancellationResult>;
     steer?: (requestId: string, input: Readonly<{
         steerId: string;
         text: string;
     }>) => Promise<RequestSteeringAppendResult>;
-    handle: (ws: WebSocket, message: RunRequestMessage, options?: RuntimeRequestOptions) => Promise<void>;
+    handle: (ws: WebSocket, message: RunRequestMessage, options?: RuntimeRequestOptions) => Promise<import("./request/handler.js").RequestHandlerOutcome>;
 }>;
 export type RuntimeApplication = Readonly<{
     services: RuntimeEnvironmentServices;
@@ -47,6 +52,7 @@ export type RuntimeDependencies = {
     events: EventSinkFactory;
     sessionMemoryCompactor: SessionMemoryCompactor;
     longTermMemory: LongTermMemoryService;
+    passiveLearning?: PassiveLearningService;
     scheduler?: SchedulerService;
     startScheduler?: () => Promise<void>;
     stopScheduler?: () => Promise<void>;

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

@@ -1,4 +1,8 @@
 import type { RequestRunnerConfig } from "./contracts.js";
+/** Explicit configuration application refreshes only its selected runner. */
+export declare function invalidateRequestRunnerConfig(params: {
+    configPath: string;
+}): () => void;
 export declare function loadRequestRunnerConfig(params: {
     configPath: string;
 }): RequestRunnerConfig;

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

@@ -3,12 +3,32 @@ import { isAbsolute, resolve } from "node:path";
 import { deepFreezeConfig, formatConfigError } from "./validation.js";
 import { parseRequestRunnerConfig } from "./versioned-config.js";
 const configCache = new Map();
-export function loadRequestRunnerConfig(params) {
-    const configuredPath = params.configPath.trim();
+function requestRunnerConfigCachePath(value) {
+    const configuredPath = value.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);
+    return resolve(configuredPath);
+}
+/** Explicit configuration application refreshes only its selected runner. */
+export function invalidateRequestRunnerConfig(params) {
+    const configPath = requestRunnerConfigCachePath(params.configPath);
+    const previous = configCache.get(configPath);
+    configCache.delete(configPath);
+    let restored = false;
+    return () => {
+        if (restored)
+            return;
+        restored = true;
+        if (previous === undefined) {
+            configCache.delete(configPath);
+            return;
+        }
+        configCache.set(configPath, previous);
+    };
+}
+export function loadRequestRunnerConfig(params) {
+    const configPath = requestRunnerConfigCachePath(params.configPath);
     const cached = configCache.get(configPath);
     if (cached) {
         return cached;

package/dist/src/runtime/context/capability-brief-budget.d.ts

@@ -0,0 +1,18 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { RequestContextBudget } from "./request-context-contracts.js";
+import type { projectRequestContext } from "./request-context.js";
+type ContextInput = Parameters<typeof projectRequestContext>[0];
+/** Headroom for one passive brief without evicting existing request context. */
+export declare function resolveCapabilityBriefHeadroom(params: Readonly<{
+    context: ContextInput;
+    additionalBudgetMessages?: readonly ChatMessage[];
+}>): number;
+/** Computes capacity from concrete messages plus any not-yet-added reserves. */
+export declare function resolveCapabilityBriefMessageHeadroom(params: Readonly<{
+    messages: readonly ChatMessage[];
+    budget: RequestContextBudget;
+    format?: Readonly<{
+        schema: unknown;
+    }>;
+}>): number;
+export {};

package/dist/src/runtime/context/capability-brief-budget.js

@@ -0,0 +1,38 @@
+import { assessRequestMessagesBudget } from "./request-context-budget.js";
+/** Headroom for one passive brief without evicting existing request context. */
+export function resolveCapabilityBriefHeadroom(params) {
+    const { context } = params;
+    const messages = [
+        { role: "system", content: context.instructions },
+        ...(context.priorConversationMessages ?? []),
+        ...context.historyMessages,
+        ...(context.referenceMessages ?? []),
+        ...(context.referenceParts?.flatMap((part) => part.messages) ?? []),
+        ...(context.continuationMessages ?? []),
+        ...(context.continuationParts?.flatMap((part) => part.messages) ?? []),
+        {
+            role: "user",
+            content: context.prompt,
+            ...(context.attachments ? { attachments: context.attachments } : {}),
+        },
+        ...(params.additionalBudgetMessages ?? []),
+    ];
+    return resolveCapabilityBriefMessageHeadroom({
+        messages,
+        budget: context.budget,
+        ...(context.format ? { format: context.format } : {}),
+    });
+}
+/** Computes capacity from concrete messages plus any not-yet-added reserves. */
+export function resolveCapabilityBriefMessageHeadroom(params) {
+    const { budget } = assessRequestMessagesBudget(params);
+    // Reserve instructions not yet inserted against both the 70% threshold
+    // and the input ceiling. Strictly below: admission triggers on >=.
+    const instructionReserve = params.budget.configuredInstructionReserveTokens ?? 0;
+    const compactionHeadroom = budget.compactionTriggerInputTokens -
+        1 -
+        budget.estimatedInputTokens -
+        instructionReserve;
+    const admissionHeadroom = budget.availableInputTokens - budget.estimatedInputTokens;
+    return Math.max(0, Math.min(compactionHeadroom, admissionHeadroom));
+}

package/dist/src/runtime/context/capability-brief-readmission.d.ts

@@ -0,0 +1,21 @@
+import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { ToolAvailabilityOverviewGroup } from "../../plugin-sdk/tool-availability-overview.js";
+import type { ModelStepContextCompactionController } from "../model/model-step-port.js";
+import { type CapabilityBriefProjection } from "./capability-brief.js";
+import type { RequestContextBudget } from "./request-context-contracts.js";
+export type CapabilityBriefReadmissionOptions = Readonly<{
+    entries?: readonly ToolAvailabilityEntry[];
+    groups: readonly ToolAvailabilityOverviewGroup[];
+    budget: RequestContextBudget;
+    format?: Readonly<{
+        schema: unknown;
+    }>;
+    additionalBudgetMessages?: readonly ChatMessage[];
+}>;
+/** Re-admits an existing optional brief against the current attempt's context. */
+export declare function createCapabilityBriefReadmissionController(params: Readonly<{
+    controller: ModelStepContextCompactionController;
+    resolveOptions(): CapabilityBriefReadmissionOptions;
+    onReadmitted?(projection: CapabilityBriefProjection): void;
+}>): ModelStepContextCompactionController;

package/dist/src/runtime/context/capability-brief-readmission.js

@@ -0,0 +1,47 @@
+import { isCapabilityBriefMessage, projectCapabilityBriefAtHeadroom, } from "./capability-brief.js";
+import { resolveCapabilityBriefMessageHeadroom } from "./capability-brief-budget.js";
+/** Re-admits an existing optional brief against the current attempt's context. */
+export function createCapabilityBriefReadmissionController(params) {
+    const { controller } = params;
+    return Object.freeze({
+        get compactionScope() {
+            return controller.compactionScope;
+        },
+        project(messages) {
+            const projected = controller.project(messages);
+            const briefIndex = projected.findIndex(isCapabilityBriefMessage);
+            if (briefIndex < 0)
+                return projected;
+            const withoutBrief = projected.filter((_, index) => index !== briefIndex);
+            const options = params.resolveOptions();
+            const headroom = resolveCapabilityBriefMessageHeadroom({
+                messages: [
+                    ...withoutBrief,
+                    ...(options.additionalBudgetMessages ?? []),
+                ],
+                budget: options.budget,
+                format: options.format,
+            });
+            const replacement = projectCapabilityBriefAtHeadroom({
+                entries: options.entries,
+                groups: options.groups,
+                headroom,
+                tokenEstimation: options.budget.tokenEstimation,
+            });
+            if (replacement.message?.content === projected[briefIndex].content) {
+                return projected;
+            }
+            params.onReadmitted?.(replacement);
+            if (!replacement.message)
+                return withoutBrief;
+            return [
+                ...projected.slice(0, briefIndex),
+                replacement.message,
+                ...projected.slice(briefIndex + 1),
+            ];
+        },
+        prepare(messages) {
+            return controller.prepare(messages);
+        },
+    });
+}

package/dist/src/runtime/context/capability-brief.d.ts

@@ -1,10 +1,10 @@
-import type { ChatMessage } from "../../model-gateway/types.js";
+import type { ChatMessage, ModelTokenEstimationConfig } from "../../model-gateway/types.js";
 import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
 import { type ToolAvailabilityOverviewGroup, type ToolAvailabilityOverviewLevel } from "../../plugin-sdk/tool-availability-overview.js";
 import type { projectRequestContext } from "./request-context.js";
 export declare const CAPABILITY_BRIEF_KIND = "runtime_capability_brief_v1";
 export declare const CAPABILITY_BRIEF_MAX_TOKENS = 512;
-export type CapabilityBriefLevel = ToolAvailabilityOverviewLevel | "none";
+export type CapabilityBriefLevel = ToolAvailabilityOverviewLevel | "descriptions" | "none";
 export type CapabilityBriefProjection = Readonly<{
     level: CapabilityBriefLevel;
     message?: ChatMessage;
@@ -20,6 +20,13 @@ export declare function projectCapabilityBrief(params: Readonly<{
     context: ContextInput;
     additionalBudgetMessages?: readonly ChatMessage[];
 }>): CapabilityBriefProjection;
+/** Selects complete availability within the current invocation's input budget. */
+export declare function projectCapabilityBriefAtHeadroom(params: Readonly<{
+    entries?: readonly ToolAvailabilityEntry[];
+    groups: readonly ToolAvailabilityOverviewGroup[];
+    headroom: number;
+    tokenEstimation?: ModelTokenEstimationConfig;
+}>): CapabilityBriefProjection;
 /** Consumers explicitly remove this optional reference at narrower phases. */
 export declare function isCapabilityBriefMessage(message: ChatMessage): boolean;
 export {};

package/dist/src/runtime/context/capability-brief.js

@@ -1,20 +1,34 @@
 import { buildToolAvailabilityOverview, } from "../../plugin-sdk/tool-availability-overview.js";
-import { assessRequestMessagesBudget } from "./request-context-budget.js";
+import { resolveCapabilityBriefHeadroom } from "./capability-brief-budget.js";
+import { buildCapabilityDescriptions } from "./capability-descriptions.js";
 import { estimateMessageTokens } from "./token-estimator.js";
 export const CAPABILITY_BRIEF_KIND = "runtime_capability_brief_v1";
 export const CAPABILITY_BRIEF_MAX_TOKENS = 512;
 const CAPABILITY_BRIEF_PREFIX = `${CAPABILITY_BRIEF_KIND}\n`;
 /** Optional availability metadata admitted against the full context estimate. */
 export function projectCapabilityBrief(params) {
-    const budgetTokens = resolveCapabilityBriefBudget(params);
+    return projectCapabilityBriefAtHeadroom({
+        entries: params.entries,
+        groups: params.groups,
+        headroom: resolveCapabilityBriefHeadroom(params),
+        tokenEstimation: params.context.budget.tokenEstimation,
+    });
+}
+/** Selects complete availability within the current invocation's input budget. */
+export function projectCapabilityBriefAtHeadroom(params) {
+    const headroom = Math.max(0, params.headroom);
+    const compactBudgetTokens = Math.min(CAPABILITY_BRIEF_MAX_TOKENS, headroom);
     if (params.groups.length === 0) {
-        return omittedBrief(budgetTokens, "empty_catalog");
+        return omittedBrief(compactBudgetTokens, "empty_catalog");
     }
     const levels = hasCompleteCapabilityBriefEntries(params.entries, params.groups)
-        ? ["detailed", "titles", "groups"]
+        ? ["descriptions", "detailed", "titles", "groups"]
         : ["groups"];
     for (const level of levels) {
-        const body = buildToolAvailabilityOverview(params.entries ?? [], params.groups, level);
+        const budgetTokens = level === "descriptions" ? headroom : compactBudgetTokens;
+        const body = level === "descriptions"
+            ? buildCapabilityDescriptions(params.entries ?? [])
+            : buildToolAvailabilityOverview(params.entries ?? [], params.groups, level);
         const message = Object.freeze({
             role: "system",
             content: [
@@ -24,7 +38,7 @@ export function projectCapabilityBrief(params) {
                 body,
             ].join("\n"),
         });
-        const estimatedTokens = estimateMessageTokens(message, params.context.budget.tokenEstimation);
+        const estimatedTokens = estimateMessageTokens(message, params.tokenEstimation);
         if (!fitsCapabilityBriefBudget(estimatedTokens, budgetTokens))
             continue;
         return Object.freeze({
@@ -35,7 +49,7 @@ export function projectCapabilityBrief(params) {
             reason: "complete_catalog",
         });
     }
-    return omittedBrief(budgetTokens, "insufficient_budget");
+    return omittedBrief(compactBudgetTokens, "insufficient_budget");
 }
 /** Consumers explicitly remove this optional reference at narrower phases. */
 export function isCapabilityBriefMessage(message) {
@@ -43,38 +57,6 @@ export function isCapabilityBriefMessage(message) {
         return false;
     return message.content.startsWith(CAPABILITY_BRIEF_PREFIX);
 }
-function resolveCapabilityBriefBudget(params) {
-    const { context } = params;
-    const messages = [
-        { role: "system", content: context.instructions },
-        ...(context.priorConversationMessages ?? []),
-        ...context.historyMessages,
-        ...(context.referenceMessages ?? []),
-        ...(context.referenceParts?.flatMap((part) => part.messages) ?? []),
-        ...(context.continuationMessages ?? []),
-        ...(context.continuationParts?.flatMap((part) => part.messages) ?? []),
-        {
-            role: "user",
-            content: context.prompt,
-            ...(context.attachments ? { attachments: context.attachments } : {}),
-        },
-        ...(params.additionalBudgetMessages ?? []),
-    ];
-    const { budget } = assessRequestMessagesBudget({
-        messages,
-        budget: context.budget,
-        ...(context.format ? { format: context.format } : {}),
-    });
-    // Configured methodology is added later; reserve it for the 70% threshold
-    // as well as the input ceiling. Strictly below: admission triggers on >=.
-    const instructionReserve = context.budget.configuredInstructionReserveTokens ?? 0;
-    const compactionHeadroom = budget.compactionTriggerInputTokens -
-        1 -
-        budget.estimatedInputTokens -
-        instructionReserve;
-    const admissionHeadroom = budget.availableInputTokens - budget.estimatedInputTokens;
-    return Math.max(0, Math.min(CAPABILITY_BRIEF_MAX_TOKENS, compactionHeadroom, admissionHeadroom));
-}
 function hasCompleteCapabilityBriefEntries(entries, groups) {
     if (entries === undefined)
         return false;

package/dist/src/runtime/context/capability-descriptions.d.ts

@@ -0,0 +1,3 @@
+import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
+/** Complete request-registry facts; neither a selected subset nor tool schemas. */
+export declare function buildCapabilityDescriptions(entries: readonly ToolAvailabilityEntry[]): string;

package/dist/src/runtime/context/capability-descriptions.js

@@ -0,0 +1,23 @@
+/** Complete request-registry facts; neither a selected subset nor tool schemas. */
+export function buildCapabilityDescriptions(entries) {
+    const ordered = [...entries].sort(compareCapabilityDescriptions);
+    return JSON.stringify(ordered.map(({ toolName, operationId, summary, catalogGroups }) => ({
+        toolName,
+        operationId,
+        summary,
+        catalogGroups: [...new Set(catalogGroups)].sort(compareAscii),
+    })));
+}
+function compareCapabilityDescriptions(left, right) {
+    const byOperation = compareAscii(left.operationId, right.operationId);
+    if (byOperation !== 0)
+        return byOperation;
+    return compareAscii(left.toolName, right.toolName);
+}
+function compareAscii(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

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

@@ -7,6 +7,8 @@ export type RequestHistoryMessage = Readonly<{
     createdAt: string;
     requestId?: string;
     grounding?: SessionMessageGrounding;
+    /** Trusted persisted assistant-origin turn; never supplied as current user intent. */
+    assistantInitiativeId?: string;
 }>;
 export type RequestContextBudget = Readonly<{
     contextWindowTokens: number;

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

@@ -197,6 +197,10 @@ function collectConversationTurns(historyMessages) {
             turns.push(createConversationTurn(message));
             continue;
         }
+        if (message.assistantInitiativeId) {
+            turns.push({ source: [message], messages: [{ role: "assistant", content: message.content }] });
+            continue;
+        }
         const pendingTurn = findPendingConversationTurn(turns, message);
         if (!pendingTurn) {
             continue;
@@ -221,7 +225,7 @@ function createConversationTurn(user, assistant) {
     };
 }
 function findPendingConversationTurn(turns, assistant) {
-    const pendingTurns = turns.filter((turn) => turn.source.length === 1);
+    const pendingTurns = turns.filter((turn) => turn.source.length === 1 && turn.source[0]?.role === "user");
     if (assistant.requestId) {
         const exactMatch = findLastConversationTurn(pendingTurns, (turn) => turn.source[0]?.requestId === assistant.requestId);
         if (exactMatch) {

package/dist/src/runtime/context/semantic-compaction/snapshot.d.ts

@@ -0,0 +1,9 @@
+import type { SemanticCompactionCheckpoint, SemanticCompactionSource } from "./contracts.js";
+import { type RequestContextCompactionStore } from "./store.js";
+export type RequestContextCompactionSnapshot = Readonly<{
+    kind: "request_context_compaction_v1";
+    checkpoints: readonly SemanticCompactionCheckpoint[];
+    sources: readonly SemanticCompactionSource[];
+}>;
+export declare function captureRequestContextCompaction(store: RequestContextCompactionStore): RequestContextCompactionSnapshot;
+export declare function restoreRequestContextCompaction(snapshot: RequestContextCompactionSnapshot): RequestContextCompactionStore;

package/dist/src/runtime/context/semantic-compaction/snapshot.js

@@ -0,0 +1,20 @@
+import { createRequestContextCompactionStore, } from "./store.js";
+export function captureRequestContextCompaction(store) {
+    if (!store.snapshot)
+        throw new Error("context_compaction_snapshot_unavailable");
+    return store.snapshot();
+}
+export function restoreRequestContextCompaction(snapshot) {
+    if (snapshot?.kind !== "request_context_compaction_v1")
+        throw new Error("context_compaction_snapshot_invalid");
+    const store = createRequestContextCompactionStore();
+    store.registerSources(snapshot.sources);
+    for (const checkpoint of snapshot.checkpoints) {
+        for (const source of checkpoint.sourceDigests) {
+            if (!store.materializeSource(source.sourceRef, source.sourceFingerprint))
+                throw new Error("context_compaction_snapshot_source_missing");
+        }
+        store.commit(checkpoint);
+    }
+    return store;
+}

package/dist/src/runtime/context/semantic-compaction/store.d.ts

@@ -1,5 +1,7 @@
 import { SemanticCompactionCheckpoint, type SemanticCompactionSource } from "./contracts.js";
+import type { RequestContextCompactionSnapshot } from "./snapshot.js";
 export type RequestContextCompactionStore = Readonly<{
+    snapshot?(): RequestContextCompactionSnapshot;
     get(scopeId: string): SemanticCompactionCheckpoint | undefined;
     findByCallIds(callIds: readonly string[]): readonly SemanticCompactionCheckpoint[];
     registerSources(sources: readonly SemanticCompactionSource[]): void;

package/dist/src/runtime/context/semantic-compaction/store.js

@@ -3,6 +3,13 @@ export function createRequestContextCompactionStore() {
     const checkpoints = new Map();
     const sources = new Map();
     return Object.freeze({
+        snapshot() {
+            return Object.freeze({
+                kind: "request_context_compaction_v1",
+                checkpoints: Object.freeze([...checkpoints.values()]),
+                sources: Object.freeze([...sources.values()]),
+            });
+        },
         get(scopeId) {
             return checkpoints.get(scopeId);
         },

package/dist/src/runtime/context/session-memory/contracts.d.ts

@@ -4,6 +4,7 @@ import type { SessionRecord } from "../../../sessions/types.js";
 import type { SessionMemorySettledTurn } from "../../../sessions/memory/source.js";
 import type { RequestHistoryMessage } from "../request-context-contracts.js";
 import type { BoundRequestModelInvocationContext } from "../../request/contracts.js";
+import type { RequestSessionMemorySnapshot } from "./snapshot-state.js";
 export declare const SESSION_MEMORY_PROTECTED_TURN_COUNT = 10;
 export type SessionMemoryRequestProjection = Readonly<{
     priorConversationMessages: readonly ChatMessage[];
@@ -19,6 +20,7 @@ export type PreparedSessionMemoryCheckpoint = Readonly<{
     commit(): Promise<void>;
 }>;
 export type RequestSessionMemory = Readonly<{
+    snapshot?(): RequestSessionMemorySnapshot;
     project(): SessionMemoryRequestProjection;
     prepare(request: BoundRequestModelInvocationContext): Promise<PreparedSessionMemoryCheckpoint>;
 }>;
@@ -31,8 +33,11 @@ export type SessionMemoryCompactor = Readonly<{
 }>;
 export type CreateRequestSessionMemoryParams = Readonly<{
     sessionId: string;
-    session: SessionRecord;
     repository: SessionMemoryRepository;
     compactor: SessionMemoryCompactor;
     now?: () => Date;
-}>;
+}> & (Readonly<{
+    session: SessionRecord;
+}> | Readonly<{
+    snapshot: RequestSessionMemorySnapshot;
+}>);