@abot-ai/runtime 1.2.0 → 1.3.0

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

@@ -51,6 +51,7 @@ export type RuntimeLongTermMemoryConfig = {
     enabled: boolean;
     emitClientEvents: boolean;
     embeddingProfileId?: string;
+    maxRecallCallsPerRequest?: number;
 };
 export type RuntimeConfig = {
     runtimeId: string;
@@ -81,12 +82,15 @@ export type RuntimeHostStartOptions = {
     toolRegistry?: ToolRegistry;
 };
 export type RuntimeHostHandle = {
+    /** Optional for custom hosts; default hosts expose scheduler startup readiness. */
+    ready?: Promise<void>;
     stop: () => Promise<void>;
 };
 export type RuntimeHost = {
     start: (options?: RuntimeHostStartOptions) => RuntimeHostHandle;
 };
 export type AppendSessionMessageOptions = {
+    schedule?: import("../sessions/schedule-metadata.js").ScheduleMessageReference;
     lastAgentMode?: AgentMode;
     grounding?: SessionMessageGrounding;
     observationMeta?: SessionMessageObservationMeta;

package/dist/src/runtime/request/bound-runtime-handler.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeEnvironmentServices, RuntimeRequestHandler } from "../composition.js";
+export declare function createBoundRuntimeRequestHandler(services: RuntimeEnvironmentServices): RuntimeRequestHandler;

package/dist/src/runtime/request/bound-runtime-handler.js

@@ -0,0 +1,25 @@
+import { handleRunRequest } from "./handler.js";
+export function createBoundRuntimeRequestHandler(services) {
+    const environmentOptions = {
+        runtimeConfig: services.config,
+        eventSinkFactory: services.events,
+        modelGatewayClient: services.models,
+        sessionStore: services.sessions,
+        attachmentStore: services.attachments,
+        toolRegistry: services.tools,
+        sessionMemoryCompactor: services.sessionMemoryCompactor,
+        longTermMemory: services.longTermMemory,
+    };
+    return Object.freeze({
+        handle(ws, message, requestOptions = {}) {
+            const invoke = () => handleRunRequest(ws, message, {
+                ...environmentOptions,
+                ...requestOptions,
+            });
+            if (services.requestAdmission) {
+                return services.requestAdmission.run(typeof message.sessionId === "string" ? message.sessionId : "", invoke);
+            }
+            return invoke();
+        },
+    });
+}

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

@@ -1,5 +1,6 @@
 import type { ModelGatewayAttachment, ModelGatewayPolicyConfig, ModelPreference } from "../../model-gateway/types.js";
 import type { AgentMode } from "../../shared/types.js";
+import type { ScheduleMessageReference } from "../../sessions/schedule-metadata.js";
 import type { RuntimeAttachmentStore } from "../attachments/store.js";
 import type { RuntimeThinkingTrace } from "../model/thinking-trace.js";
 import type { EventSinkFactory, ModelGatewayClient, RuntimeConfig, ToolApprovalController, ToolPermissionMode, ToolRegistry } from "../ports.js";
@@ -42,6 +43,7 @@ export type RequestExecutionSeed = Readonly<{
     sessionId: string;
     prompt: string;
     temporalContext?: RequestTemporalContext;
+    scheduledExecution?: ScheduleMessageReference;
     historyMessages: readonly RequestHistoryMessage[];
     sessionArtifactPaths?: readonly string[];
     shouldGenerateSessionTitle: boolean;
@@ -56,6 +58,8 @@ export type RequestExecutionSeed = Readonly<{
     contextCompactionStore?: RequestContextCompactionStore;
     sessionMemory?: RequestSessionMemory;
     longTermMemory?: LongTermMemoryService;
+    /** Frozen request-local availability limit for explicit memory recall. */
+    memoryRecallLimit?: number;
     requestSteering?: RequestSteeringInbox;
     toolPermissionMode: ToolPermissionMode;
     toolApprovalController?: ToolApprovalController;
@@ -76,6 +80,7 @@ export type RequestIdentity = Readonly<{
 export type AcceptedRequestInput = Readonly<{
     prompt: RequestExecutionSeed["prompt"];
     temporalContext?: RequestExecutionSeed["temporalContext"];
+    scheduledExecution?: RequestExecutionSeed["scheduledExecution"];
     attachments?: RequestExecutionSeed["attachments"];
     agentMode: RequestExecutionSeed["agentMode"];
 }>;
@@ -97,6 +102,7 @@ export type RequestModelRuntime = Readonly<{
 /** Core-owned passive memory service; never part of capability execution. */
 export type RequestMemoryRuntime = Readonly<{
     longTermMemory?: RequestExecutionSeed["longTermMemory"];
+    memoryRecallLimit?: RequestExecutionSeed["memoryRecallLimit"];
 }>;
 /** Request-local cancellation, steering, capability controls, and events. */
 export type RequestLifecycleRuntime = Readonly<{

package/dist/src/runtime/request/execution-agent-root-execution.js

@@ -19,6 +19,9 @@ export const EXECUTION_AGENT_ROOT_CONTRACT = Object.freeze({
             includeTitle: options.includeTitle,
             allowPlanner: options.allowedRoleIds.includes("planner"),
             allowAuditor: options.allowedRoleIds.includes("reviewer"),
+            ...(options.memoryRecallMessage
+                ? { memoryRecallMessage: options.memoryRecallMessage }
+                : {}),
         });
         return Object.freeze({
             decision: projectKernelDecision(outcome.decision, outcome.steeringVersion),
@@ -31,6 +34,9 @@ export const EXECUTION_AGENT_ROOT_CONTRACT = Object.freeze({
             head: options.head,
             call: options.callFrame,
             steeringSnapshot: projectRequestSteeringSnapshot(requestSteering, options.steeringVersion),
+            ...(options.memoryRecallMessage
+                ? { memoryRecallMessage: options.memoryRecallMessage }
+                : {}),
         });
     },
 });
@@ -42,6 +48,12 @@ function projectKernelDecision(decision, steeringVersion) {
         ...(decision.title !== undefined ? { title: decision.title } : {}),
     };
     switch (decision.action) {
+        case "recall_memory":
+            return Object.freeze({
+                action: "recall_memory",
+                query: decision.query,
+                ...presentation,
+            });
         case "reconsider_capability_selection":
             return Object.freeze({
                 action: "reconsider_capability_selection",

package/dist/src/runtime/request/execution-facets.js

@@ -9,6 +9,9 @@ export function createRequestSeedFacets(seed) {
         ...(seed.temporalContext !== undefined
             ? { temporalContext: seed.temporalContext }
             : {}),
+        ...(seed.scheduledExecution !== undefined
+            ? { scheduledExecution: seed.scheduledExecution }
+            : {}),
         ...(seed.attachments !== undefined
             ? { attachments: seed.attachments }
             : {}),
@@ -38,6 +41,9 @@ export function createRequestSeedFacets(seed) {
         modelGatewayClient: seed.modelGatewayClient,
     });
     const memory = Object.freeze({
+        ...(seed.memoryRecallLimit !== undefined
+            ? { memoryRecallLimit: seed.memoryRecallLimit }
+            : {}),
         ...(seed.longTermMemory !== undefined
             ? { longTermMemory: seed.longTermMemory }
             : {}),

package/dist/src/runtime/request/execution-scope-surfaces.js

@@ -53,6 +53,11 @@ export function createScopeSurface(input) {
     const { facets, policy, modelInvocation, modelSteps, capabilities } = input;
     return createFrozenSurface({
         ...requestSeedDescriptors(facets, policy.selection, true),
+        ...(facets.input.scheduledExecution !== undefined
+            ? {
+                scheduledExecution: enumerableGetter(() => facets.input.scheduledExecution),
+            }
+            : {}),
         ...(facets.session.sessionMemory !== undefined
             ? {
                 sessionMemory: enumerableGetter(() => facets.session.sessionMemory),
@@ -63,6 +68,11 @@ export function createScopeSurface(input) {
                 longTermMemory: enumerableGetter(() => facets.memory.longTermMemory),
             }
             : {}),
+        ...(facets.memory.memoryRecallLimit !== undefined
+            ? {
+                memoryRecallLimit: enumerableGetter(() => facets.memory.memoryRecallLimit),
+            }
+            : {}),
         executionPolicy: enumerableGetter(() => policy.executionPolicy),
         modelSteps: enumerableGetter(() => modelSteps),
         workerCapabilities: enumerableGetter(() => capabilities),

package/dist/src/runtime/request/execution-scope.d.ts

@@ -8,7 +8,7 @@ export type RequestCapabilityCompositionView = BoundRequestModelInvocationContex
  * Stable request-owned context delivered to capability adapters.
  * Passive session artifact paths and request containers are excluded.
  */
-export type RequestCapabilityExecutionView = Readonly<Omit<RequestExecutionSeed, "sessionArtifactPaths" | "sessionMemory" | "longTermMemory">> & BoundRequestModelInvocationContext;
+export type RequestCapabilityExecutionView = Readonly<Omit<RequestExecutionSeed, "sessionArtifactPaths" | "sessionMemory" | "longTermMemory" | "memoryRecallLimit" | "scheduledExecution">> & BoundRequestModelInvocationContext;
 export type RequestWorkerCapabilities = Readonly<{
     provider: WorkerCapabilityAdapterProvider<RequestCapabilityExecutionView> & Partial<ToolAvailabilitySource>;
     executionContext: RequestCapabilityExecutionView;

package/dist/src/runtime/request/handler.js

@@ -6,6 +6,7 @@ import { failRequest, finalizeRequest, } from "../lifecycle/request-finalizer.js
 import { resolveModelSelection } from "../model/model-selection.js";
 import { resolveRequestDependencies } from "./dependencies.js";
 import { parseRequestInput } from "./input.js";
+import { resolveScheduledExecution } from "./scheduled-execution.js";
 import { runRequestRunner } from "./runner.js";
 import { createRequestWorkerCapabilityProvider } from "./worker-capability-composition.js";
 import { resolveRequestExecutionPolicy } from "./role-executor-composition.js";
@@ -61,6 +62,7 @@ class RequestHandlingSession {
         }
     }
     async execute() {
+        const schedule = resolveScheduledExecution(this.options, this.input);
         const { requestId, sessionId, prompt, rawAttachments, rawAgentMode, rawModelPreference, toolPermissionMode, } = this.input;
         const { eventSinkFactory, modelGatewayClient, sessionStore, attachmentStore, loadDecisionEnvironment, toolApprovalController, sessionMemoryCompactor, longTermMemory, } = this.dependencies;
         const { runnerConfig, modelPolicy, modelExecutionPolicies } = loadDecisionEnvironment();
@@ -112,15 +114,18 @@ class RequestHandlingSession {
             sessionStore,
             attachmentStore,
             events: this.events,
+            ...(schedule ? { schedule } : {}),
         });
         this.bindSteeringPersistence();
         this.enterModelStage();
         const sessionArtifactPaths = snapshotSessionArtifactPathTargets(openedSession.session.artifactPaths);
+        const memoryRecallLimit = this.options.runtimeConfig?.longTermMemory?.maxRecallCallsPerRequest;
         const runnerRequestSeed = {
             requestId,
             sessionId,
             prompt: initializedRequest.prompt,
             temporalContext: this.temporalContext,
+            ...(schedule ? { scheduledExecution: schedule } : {}),
             historyMessages,
             shouldGenerateSessionTitle: generateSessionTitle,
             runnerConfig,
@@ -139,6 +144,7 @@ class RequestHandlingSession {
             contextCompactionStore: createRequestContextCompactionStore(),
             sessionMemory,
             longTermMemory,
+            ...(memoryRecallLimit !== undefined ? { memoryRecallLimit } : {}),
             requestSteering: this.requestSteering,
             toolPermissionMode,
             ...(toolApprovalController ? { toolApprovalController } : {}),

package/dist/src/runtime/request/root-contract.d.ts

@@ -1,4 +1,6 @@
 import type { ModelStep } from "../../shared/model-steps.js";
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { MemoryRecallDecision } from "../steps/memory-recall-decision.js";
 import type { RequestToolResultsView } from "../context/request-tool-results.js";
 import type { ExecutionPolicyAuthoritySnapshot, RoleCallChildReturnCommit, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleCallWorkerCapabilityScope, RoleCapabilitySelectionProjection, RoleCapabilitySelectionReconsiderationCause, RoleChildReturnContext } from "../orchestration/role-calls/index.js";
 import type { RuntimeDelegateRoleId } from "../orchestration/roles.js";
@@ -13,8 +15,9 @@ export type RootContractCallIdentity = Readonly<{
     depth: number;
     invocationAttempt: number;
 }>;
-export type RootContractDecision = Readonly<{
+export type RootContractDecision = MemoryRecallDecision | Readonly<{
     action: "respond";
+    responseRecommendation?: string;
     acknowledgement?: string;
     title?: string;
 }> | Readonly<{
@@ -82,15 +85,18 @@ export type RootContractAdapter<TRequest> = Readonly<{
         includeTitle: boolean;
         allowedRoleIds: readonly RuntimeDelegateRoleId[];
         availableWorkerCapabilityCatalog: readonly WorkerCapabilityCatalogGroup[];
+        memoryRecallMessage?: ChatMessage;
         resume?: RoleChildReturnContext;
     }>): Promise<RootContractDecisionOutcome>;
     authorResponse(request: TRequest, options: Readonly<{
         head: RoleCallLedgerHead;
         callFrame: RoleCallFrame;
         steeringVersion: number;
+        responseRecommendation?: string;
         call: RootContractCallIdentity;
         toolResults: RequestToolResultsView;
         resume?: RoleChildReturnContext;
+        memoryRecallMessage?: ChatMessage;
     }>): Promise<RootAuthoredResponse>;
 }>;
 export type CompiledExecutionPolicy<TRequest> = Readonly<{

package/dist/src/runtime/request/root-execution-kernel.js

@@ -1,11 +1,15 @@
 import { projectRequestToolResults } from "../context/request-tool-results.js";
 import { emitRuntimeStatus } from "../events/runtime-status.js";
+import { isModelStepSteeringSuperseded } from "../model/model-step-steering.js";
 import { resolveRoleCallTransactions, } from "../orchestration/role-calls/index.js";
 import { RUNTIME_ROOT_ROLE_ID } from "../orchestration/roles.js";
 import { createRoleCapabilityBinding, isWorkerCapabilityOperationSupervisionLimitError, projectWorkerCapabilityCatalogGroups, } from "../orchestration/worker-capabilities/index.js";
 import { runDegradedFinalization } from "../steps/degraded-finalization/run.js";
 import { projectRequestSteeringSnapshot, resolveRequestSteeringInbox, } from "./request-steering.js";
-import { traceSupervisorRootAcknowledgementPublished, traceSupervisorRootActivationFailed, traceSupervisorRootActivationStarted, traceSupervisorRootObservationHandoffBound, traceSupervisorRootInvocationSuperseded, traceSupervisorRootResponseSuperseded, } from "./supervisor-root-execution-diagnostics.js";
+import { traceSupervisorRootAcknowledgementPublished, traceSupervisorRootActivationFailed, traceSupervisorRootActivationStarted, traceSupervisorRootInvocationSuperseded, traceSupervisorRootResponseSuperseded, } from "./supervisor-root-execution-diagnostics.js";
+import { bindSupervisorObservationHandoff, projectSupervisorFinalObservation, } from "./root-observation-handoff.js";
+import { performRootMemoryRecall } from "./root-memory-recall.js";
+import { projectRootMemoryRecallMessage } from "../long-term-memory/recall-context.js";
 import { createPlainRootAuthoredResponse } from "../orchestration/final-response/authoring-contract.js";
 const CONTINUE_ROOT_EXECUTION = Object.freeze({
     kind: "continue",
@@ -40,7 +44,7 @@ class RootExecutionSession {
         this.requestSteering = resolveRequestSteeringInbox(params.request.requestSteering);
     }
     async run() {
-        // Every non-terminal decision consumes a ledger-bounded child call.
+        // Every accepted continuation reserves its next activation in the ledger.
         for (;;) {
             const control = await this.runActivation();
             if (control.kind === "complete") {
@@ -61,6 +65,10 @@ class RootExecutionSession {
             return await this.executeDecision(decisionActivation, attempt);
         }
         catch (error) {
+            if (isModelStepSteeringSuperseded(error)) {
+                this.traceResponseSuperseded(error.boundSteeringVersion, "after_response");
+                return CONTINUE_ROOT_EXECUTION;
+            }
             traceSupervisorRootActivationFailed({
                 diagnostic: this.diagnostic,
                 failureStage: attempt.failureStage,
@@ -107,6 +115,11 @@ class RootExecutionSession {
         const decisionOutcome = await this.policy.rootContract.decide(this.request, {
             head: activation.head,
             callFrame: activation.call,
+            memoryRecallMessage: projectRootMemoryRecallMessage({
+                head: activation.head,
+                callId: activation.call.callId,
+                steeringVersion: this.requestSteering.snapshot().version,
+            }),
             call: activation.callIdentity,
             toolResults: decisionToolResults,
             includeAcknowledgement: this.resume === undefined && !this.acknowledgementPublished,
@@ -163,6 +176,18 @@ class RootExecutionSession {
     }
     async executeDecision(activation, attempt) {
         const { decision } = activation;
+        if (decision.action === "recall_memory") {
+            attempt.failureStage = "recall_memory";
+            await performRootMemoryRecall({
+                request: this.request,
+                ledger: this.ledger,
+                head: activation.head,
+                call: activation.call,
+                steeringVersion: activation.decisionSteeringVersion,
+                query: decision.query,
+            });
+            return CONTINUE_ROOT_EXECUTION;
+        }
         if (decision.action === "invoke_role") {
             return this.invokeRole(activation, decision, attempt);
         }
@@ -379,6 +404,12 @@ class RootExecutionSession {
         const authoredResponse = decision.action === "blocked"
             ? createPlainRootAuthoredResponse(decision.response)
             : await this.policy.rootContract.authorResponse(this.request, {
+                responseRecommendation: decision.responseRecommendation,
+                memoryRecallMessage: projectRootMemoryRecallMessage({
+                    head: activation.head,
+                    callId: activation.call.callId,
+                    steeringVersion: activation.decisionSteeringVersion,
+                }),
                 head: activation.head,
                 callFrame: activation.call,
                 steeringVersion: activation.decisionSteeringVersion,
@@ -470,41 +501,6 @@ function createRootExecutionFreshness(params) {
         isCurrent: () => params.requestSteering.isCurrent(snapshot.version),
     });
 }
-function bindSupervisorObservationHandoff(params) {
-    const { callerCallId, childCallId, resultRef } = params.returnCommit.effect;
-    if (params.resume.callerCallId !== callerCallId ||
-        params.resume.returnedChildCallId !== childCallId ||
-        params.resume.returnedResultRef !== resultRef ||
-        !params.resume.completedChildren.some((child) => child.callerCallId === callerCallId &&
-            child.childCallId === childCallId &&
-            child.resultRef === resultRef)) {
-        throw new Error("supervisor_observation_handoff_source_invalid");
-    }
-    const handoff = Object.freeze({
-        callerCallId,
-        childCallId,
-        resultRef,
-        finalObservation: params.finalObservation,
-    });
-    traceSupervisorRootObservationHandoffBound({
-        diagnostic: params.diagnostic,
-        callerCallId,
-        childCallId,
-        resultRef,
-        replaced: params.replaced,
-        observationContentLength: params.finalObservation.observationContent.length,
-    });
-    return handoff;
-}
-function projectSupervisorFinalObservation(handoff, resume) {
-    if (resume?.callerCallId !== handoff.callerCallId ||
-        !resume.completedChildren.some((child) => child.callerCallId === handoff.callerCallId &&
-            child.childCallId === handoff.childCallId &&
-            child.resultRef === handoff.resultRef)) {
-        throw new Error("supervisor_observation_handoff_source_invalid");
-    }
-    return handoff.finalObservation;
-}
 function emitSupervisorResumeStatus(request) {
     emitRuntimeStatus(request, {
         stage: "supervisor",

package/dist/src/runtime/request/root-memory-recall.d.ts

@@ -0,0 +1,11 @@
+import { type RoleCallFrame, type RoleCallLedger, type RoleCallLedgerHead } from "../orchestration/role-calls/index.js";
+import type { RequestExecutionScope } from "./execution-scope.js";
+/** One service invocation, one canonical settlement, then the existing root loop resumes. */
+export declare function performRootMemoryRecall(params: {
+    request: RequestExecutionScope;
+    ledger: RoleCallLedger;
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    steeringVersion: number;
+    query: string;
+}): Promise<void>;

package/dist/src/runtime/request/root-memory-recall.js

@@ -0,0 +1,71 @@
+import { resolveRoleCallTransactions, } from "../orchestration/role-calls/index.js";
+import { boundMemoryRecallResult, unavailableMemoryRecall, } from "../long-term-memory/recall-result.js";
+import { classifyMemoryFailure } from "../long-term-memory/diagnostics.js";
+import { resolveRequestSteeringInbox } from "./request-steering.js";
+/** One service invocation, one canonical settlement, then the existing root loop resumes. */
+export async function performRootMemoryRecall(params) {
+    const { request } = params;
+    const steering = resolveRequestSteeringInbox(request.requestSteering);
+    request.abortSignal.throwIfAborted();
+    if (!steering.isCurrent(params.steeringVersion))
+        return;
+    if (request.longTermMemory?.enabled !== true) {
+        throw new Error("memory_recall_not_available");
+    }
+    const transactions = resolveRoleCallTransactions(params.ledger);
+    const started = await transactions.beginMemoryRecall({
+        expectedHead: params.head,
+        callId: params.call.callId,
+        invocationAttempt: params.call.activationCount,
+        steeringVersion: params.steeringVersion,
+        query: params.query,
+    });
+    if (!started.ok) {
+        throw new Error(`role_call_ledger_rejected:${started.issueCode}`);
+    }
+    request.abortSignal.throwIfAborted();
+    const retrieved = steering.isCurrent(params.steeringVersion)
+        ? await retrieveRootMemory(params)
+        : supersededMemoryRecall();
+    request.abortSignal.throwIfAborted();
+    const result = steering.isCurrent(params.steeringVersion)
+        ? retrieved
+        : supersededMemoryRecall();
+    const settled = await transactions.settleMemoryRecall({
+        expectedHead: started.commit.head,
+        callId: params.call.callId,
+        recallId: started.commit.effect.recallId,
+        invocationAttempt: params.call.activationCount,
+        steeringVersion: params.steeringVersion,
+        result,
+    });
+    if (!settled.ok) {
+        throw new Error(`role_call_ledger_rejected:${settled.issueCode}`);
+    }
+}
+async function retrieveRootMemory(params) {
+    const { request } = params;
+    try {
+        return boundMemoryRecallResult(await request.longTermMemory.retrieve({
+            query: params.query,
+            context: {
+                requestId: request.requestId,
+                sessionId: request.sessionId,
+                abortSignal: request.abortSignal,
+                onEvent: request.onEvent,
+            },
+        }));
+    }
+    catch (error) {
+        if (request.abortSignal.aborted)
+            throw error;
+        return unavailableMemoryRecall(classifyMemoryFailure(error));
+    }
+}
+function supersededMemoryRecall() {
+    return Object.freeze({
+        outcome: "superseded",
+        records: Object.freeze([]),
+        omittedRecordCount: 0,
+    });
+}

package/dist/src/runtime/request/root-observation-handoff.d.ts

@@ -0,0 +1,17 @@
+import type { RoleCallChildReturnCommit, RoleChildReturnContext } from "../orchestration/role-calls/index.js";
+import type { RequestObservation } from "./result.js";
+import { type SupervisorRootDiagnosticContext } from "./supervisor-root-execution-diagnostics.js";
+export type RootObservationHandoff = Readonly<{
+    callerCallId: string;
+    childCallId: string;
+    resultRef: string;
+    finalObservation: RequestObservation;
+}>;
+export declare function bindSupervisorObservationHandoff(params: {
+    diagnostic: SupervisorRootDiagnosticContext;
+    returnCommit: RoleCallChildReturnCommit;
+    resume: RoleChildReturnContext;
+    finalObservation: RequestObservation;
+    replaced: boolean;
+}): RootObservationHandoff;
+export declare function projectSupervisorFinalObservation(handoff: RootObservationHandoff, resume: RoleChildReturnContext | undefined): RequestObservation;

package/dist/src/runtime/request/root-observation-handoff.js

@@ -0,0 +1,44 @@
+import { traceSupervisorRootObservationHandoffBound, } from "./supervisor-root-execution-diagnostics.js";
+export function bindSupervisorObservationHandoff(params) {
+    const { callerCallId, childCallId, resultRef } = params.returnCommit.effect;
+    const source = { callerCallId, childCallId, resultRef };
+    if (!hasBoundObservationReturn(params.resume, source)) {
+        throw new Error("supervisor_observation_handoff_source_invalid");
+    }
+    const handoff = Object.freeze({
+        ...source,
+        finalObservation: params.finalObservation,
+    });
+    traceSupervisorRootObservationHandoffBound({
+        diagnostic: params.diagnostic,
+        ...source,
+        replaced: params.replaced,
+        observationContentLength: params.finalObservation.observationContent.length,
+    });
+    return handoff;
+}
+export function projectSupervisorFinalObservation(handoff, resume) {
+    if (!hasObservationSource(resume, handoff)) {
+        throw new Error("supervisor_observation_handoff_source_invalid");
+    }
+    return handoff.finalObservation;
+}
+function hasBoundObservationReturn(resume, source) {
+    if (resume.returnedChildCallId !== source.childCallId)
+        return false;
+    if (resume.returnedResultRef !== source.resultRef)
+        return false;
+    return hasObservationSource(resume, source);
+}
+function hasObservationSource(resume, source) {
+    if (resume?.callerCallId !== source.callerCallId)
+        return false;
+    return resume.completedChildren.some((child) => hasObservationIdentity(child, source));
+}
+function hasObservationIdentity(child, source) {
+    if (child.callerCallId !== source.callerCallId)
+        return false;
+    if (child.childCallId !== source.childCallId)
+        return false;
+    return child.resultRef === source.resultRef;
+}

package/dist/src/runtime/request/scheduled-execution.d.ts

@@ -0,0 +1,9 @@
+import type { ScheduleMessageReference } from "../../sessions/schedule-metadata.js";
+import type { RuntimeRequestOptions } from "../composition.js";
+import type { SchedulerRun } from "../scheduler/contracts.js";
+import type { RequestHandlerOptions } from "./contracts.js";
+export declare function withScheduledExecution(options: RuntimeRequestOptions | undefined, run: SchedulerRun): RuntimeRequestOptions;
+export declare function resolveScheduledExecution(options: RequestHandlerOptions, identity: {
+    requestId: string;
+    sessionId: string;
+}): ScheduleMessageReference | undefined;

package/dist/src/runtime/request/scheduled-execution.js

@@ -0,0 +1,32 @@
+// Only scheduler-owned execution can mint this option. It survives host option
+// spreads but cannot be supplied by a decoded public request or RPC payload.
+const scheduledExecution = Symbol("scheduledExecution");
+export function withScheduledExecution(options, run) {
+    const captured = Object.freeze({
+        requestId: run.requestId,
+        sessionId: run.sessionId,
+        reference: Object.freeze({
+            jobId: run.jobId,
+            runId: run.id,
+            title: run.title,
+            scheduledAt: run.scheduledAt,
+            triggerType: run.trigger,
+        }),
+    });
+    const bound = {
+        ...options,
+        [scheduledExecution]: captured,
+    };
+    return bound;
+}
+export function resolveScheduledExecution(options, identity) {
+    const captured = options[scheduledExecution];
+    if (!captured)
+        return undefined;
+    const matchesRequest = captured.requestId === identity.requestId;
+    const matchesSession = captured.sessionId === identity.sessionId;
+    if (!matchesRequest || !matchesSession) {
+        throw new Error("scheduled_request_identity_mismatch");
+    }
+    return captured.reference;
+}

package/dist/src/runtime/request/session-admission.d.ts

@@ -0,0 +1,17 @@
+/** Coordinates background admission with requests from every environment caller. */
+export declare class SessionRequestAdmission {
+    private readonly isDeleted;
+    private readonly active;
+    private readonly reserved;
+    private readonly waiters;
+    private readonly idleWaiters;
+    private closed;
+    constructor(isDeleted: (sessionId: string) => boolean);
+    tryReserve(sessionId: string): (() => void) | null;
+    run<T>(sessionId: string, execute: () => Promise<T>): Promise<T>;
+    close(): void;
+    whenIdle(): Promise<void>;
+    private requireOpenAdmission;
+    isIdle(): boolean;
+    private notifyIdle;
+}