@abot-ai/runtime 1.8.1 → 2.0.0

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

@@ -2,6 +2,7 @@ import { assertCompactionStagePlan, assertPreparationStageBinding, } from "./con
 import { resolveRequestBudgetInputTokens, } from "../context/request-context-budget.js";
 import { ContextCompactionDiagnostics, compactionIssueCode, compactionMeasurement, } from "./context-compaction-diagnostics.js";
 import { isCompactionSteeringSuperseded } from "./model-step-steering.js";
+import { ModelStepTimeoutError } from "../steps/model-step-timeout.js";
 export function requiresContextCompaction(eligible, assessment) {
     if (!eligible)
         return false;
@@ -39,6 +40,11 @@ function canAdmitReusedCompactedContext(assessment, controller, messages) {
         return false;
     return controller?.hasExhaustedVerifiedCompactionSources?.(messages) === true;
 }
+function hasChangedOptionalContextProjection(candidate, previous) {
+    if (!candidate)
+        return false;
+    return candidate !== previous;
+}
 /** The model boundary owns budget decisions; stages own source selection only. */
 export async function admitCompactedContext(params) {
     params.assertCurrent();
@@ -54,6 +60,23 @@ export async function admitCompactedContext(params) {
     let onlyEmptyActiveSource = false;
     try {
         params.assertCurrent();
+        const optionalProjection = params.controller?.projectForCompaction?.(current.messages);
+        if (hasChangedOptionalContextProjection(optionalProjection, current.messages)) {
+            params.assertCurrent();
+            const assessment = await params.assess(optionalProjection);
+            params.assertCurrent();
+            current = { messages: optionalProjection, assessment };
+        }
+        if (isCompactedEnvelopeAdmissible(current.assessment, params.assessment)) {
+            diagnostics.trace("admitted", {
+                outcome: "admitted",
+                reason: "optional_context_removed_within_budget",
+                committedScopes,
+                ...compactionMeasurement(current.assessment),
+                afterInputTokens: resolveRequestBudgetInputTokens(current.assessment.budget),
+            });
+            return current;
+        }
         if (canAdmitReusedCompactedContext(current.assessment, params.controller, current.messages)) {
             params.assertCurrent();
             diagnostics.trace("admitted", {
@@ -71,7 +94,9 @@ export async function admitCompactedContext(params) {
         for (const [stageIndex, stage] of stages.entries()) {
             activeStage = stage;
             params.assertCurrent();
-            const outcome = await stage.prepare(current.messages);
+            const outcome = await stage.prepare(current.messages, {
+                boundSteeringVersion: params.boundSteeringVersion,
+            });
             params.assertCurrent();
             const stageMetadata = {
                 stageIndex,
@@ -186,6 +211,8 @@ export async function admitCompactedContext(params) {
                 ? {}
                 : { secondaryIssueCode: compactionIssueCode(error) }),
         });
+        if (isCompactionSteeringSuperseded(primary))
+            params.assertCurrent();
         throw primary;
     }
 }
@@ -208,7 +235,14 @@ function resolveCompactionFailureReason(error, signal) {
         return "request_aborted";
     if (isCompactionSteeringSuperseded(error))
         return "steering_superseded";
+    if (isCompactionModelStepTimeout(error))
+        return "context_compaction_timeout";
     if (compactionIssueCode(error) === "request_context_compaction_required")
         return "context_compaction_controller_unavailable";
     return "semantic_checkpoint_rejected";
 }
+function isCompactionModelStepTimeout(error) {
+    if (!(error instanceof ModelStepTimeoutError))
+        return false;
+    return error.modelStep === "context.compact";
+}

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

@@ -20,11 +20,19 @@ export type ModelStepCompactionStageOutcome = Readonly<{
 export type ModelStepCompactionStage = Readonly<{
     compactionScope: ModelStepCompactionScope;
     scopeId: string;
-    prepare(messages: readonly ChatMessage[]): Promise<ModelStepCompactionStageOutcome>;
+    prepare(messages: readonly ChatMessage[], context?: Readonly<{
+        boundSteeringVersion?: number;
+    }>): Promise<ModelStepCompactionStageOutcome>;
 }>;
 export type ModelStepContextCompactionController = Readonly<{
     /** Projects committed state once, before the complete envelope is assessed. */
     project(messages: readonly ChatMessage[]): ChatMessage[];
+    /**
+     * Drops only owned optional context once before semantic compaction.
+     * No model calls or persistent effects; mandatory messages remain unchanged.
+     * Return the same array when unchanged to avoid another budget measurement.
+     */
+    projectForCompaction?(messages: readonly ChatMessage[]): readonly ChatMessage[];
     /** Trusted projection proof plus a fresh source scan; never model-authored JSON. */
     hasExhaustedVerifiedCompactionSources?(messages: readonly ChatMessage[]): boolean;
     /** Ordered, invocation-local plan; never scans sources or calls the model. */

package/dist/src/runtime/model/input-token-count.js

@@ -11,6 +11,7 @@ export async function countModelInputTokens(params) {
         messages: params.messages,
         agentMode: params.request.agentMode,
         modelStep: params.modelStep,
+        ...(params.request.reasoningPreference ? { reasoningPreference: params.request.reasoningPreference } : {}),
         ...(params.request.modelPreference
             ? { modelPreference: params.request.modelPreference }
             : {}),

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

@@ -7,6 +7,8 @@ import { appendRequestSteeringContext } from "../request/request-steering-contex
 import { createModelStepAbort } from "../steps/model-step-timeout.js";
 import { acceptModelStepOutput } from "./model-step-acceptance.js";
 import { createModelContextAssessment } from "./model-context-assessment.js";
+import { admitOptionalModelContext } from "./optional-context-admission.js";
+import { invokeModelProvider, projectModelProviderFailureDiagnostics, } from "./provider-failure.js";
 import { isModelStepCompactionEligible, resolveModelContextAdmission, } from "./model-context-budget.js";
 import { resolveModelStepTimeout, } from "./model-step-timeout-policy.js";
 import { assertBoundModelStepSteeringCurrent, isModelStepSteeringSuperseded, assertModelStepAdmissionCurrent, ModelStepAdmissionSuperseded, } from "./model-step-steering.js";
@@ -154,6 +156,7 @@ class ModelStepInvocation {
             runnerConfig: request.runnerConfig,
             modelStep: params.modelStep,
             messages: params.messages,
+            configuredInstructionPolicy: params.configuredInstructionPolicy,
         });
         const compactionTriggerEligible = isModelStepCompactionEligible(params);
         const contextCompaction = compactionTriggerEligible
@@ -170,6 +173,7 @@ class ModelStepInvocation {
             runnerConfig: request.runnerConfig,
             agentMode: request.agentMode,
             modelStep: params.modelStep,
+            ...(request.reasoningPreference ? { reasoningPreference: request.reasoningPreference } : {}),
             ...(request.modelPreference
                 ? { modelPreference: request.modelPreference }
                 : {}),
@@ -183,6 +187,14 @@ class ModelStepInvocation {
             assertCurrent,
         });
         let assessment = await assess(messages);
+        if (params.optionalContextProjection) {
+            const optional = await admitOptionalModelContext({
+                messages, assessment, project: params.optionalContextProjection, assess, assertCurrent,
+                diagnostic: { requestId: request.requestId, modelStep: params.modelStep },
+            });
+            messages = [...optional.messages];
+            assessment = optional.assessment;
+        }
         const invocationId = this.input.nextInvocationId();
         if (requiresContextCompaction(compactionTriggerEligible, assessment)) {
             const admitted = await admitCompactedContext({
@@ -191,6 +203,8 @@ class ModelStepInvocation {
                 controller: contextCompaction,
                 assess,
                 assertCurrent,
+                boundSteeringVersion: params.boundSteeringVersion ??
+                    (this.input.ownsRequestSteering ? steeringSnapshot.version : undefined),
                 abortSignal: request.abortSignal,
                 identity: {
                     requestId: request.requestId,
@@ -361,6 +375,7 @@ class ModelStepInvocation {
             modelStep: params.modelStep,
             status,
             errorType: classifyRuntimeErrorType(error),
+            ...projectModelProviderFailureDiagnostics(error, params.messages),
             responseReceived: outputDiagnostics !== undefined,
             steeringVersion: attempt.steeringSnapshot.version,
             supersededAttemptCount: this.supersededAttemptCount,
@@ -381,10 +396,11 @@ class ModelStepAttempt {
     }
     invokeProvider() {
         const { request, params } = this.input;
-        return request.modelGatewayClient.invoke({
+        return invokeModelProvider(params.modelStep, () => request.modelGatewayClient.invoke({
             messages: this.input.messages,
             agentMode: request.agentMode,
             modelStep: params.modelStep,
+            ...(request.reasoningPreference ? { reasoningPreference: request.reasoningPreference } : {}),
             ...(request.modelPreference
                 ? { modelPreference: request.modelPreference }
                 : {}),
@@ -393,7 +409,7 @@ class ModelStepAttempt {
             debugRequestId: request.requestId,
             ...(params.format === undefined ? {} : { format: params.format }),
             onThinking: this.input.onThinking,
-        });
+        }));
     }
     recordOutputReceived(outputDiagnostics) {
         traceDebug("runtime.model", "step.output_received", {

package/dist/src/runtime/model/invoke-structured-step.d.ts

@@ -1,7 +1,8 @@
 import type { ChatMessage, ModelGatewayJsonSchemaFormat } from "../../model-gateway/types.js";
 import type { ModelStep } from "../../shared/model-steps.js";
+import type { ConfiguredStepInstructionPolicy } from "../config/runner/step-instructions.js";
 import type { BoundRequestModelInvocationContext } from "../request/contracts.js";
-import type { ModelStepContextCompactionController } from "./model-step-port.js";
+import type { ModelStepContextCompactionController, ModelStepOptionalContextProjection } from "./model-step-port.js";
 export type StructuredModelValidationIssue = Readonly<{
     code: string;
     path: string;
@@ -38,6 +39,8 @@ export declare function invokeStructuredModelStep<T>(params: {
     boundSteeringVersion?: number;
     invalidOutputReason: string;
     contextRetention?: "exact";
+    configuredInstructionPolicy?: ConfiguredStepInstructionPolicy;
+    optionalContextProjection?: ModelStepOptionalContextProjection;
     contextCompaction?: ModelStepContextCompactionController;
     parse: (text: string, abortSignal: AbortSignal) => StructuredModelParseResult<T> | Promise<StructuredModelParseResult<T>>;
 }): Promise<T>;

package/dist/src/runtime/model/invoke-structured-step.js

@@ -32,6 +32,10 @@ export async function invokeStructuredModelStep(params) {
             boundSteeringVersion: params.boundSteeringVersion,
             format: params.format,
             contextRetention: params.contextRetention,
+            configuredInstructionPolicy: params.configuredInstructionPolicy,
+            ...(params.optionalContextProjection
+                ? { optionalContextProjection: params.optionalContextProjection }
+                : {}),
             ...(params.contextCompaction
                 ? { contextCompaction: params.contextCompaction }
                 : {}),

package/dist/src/runtime/model/model-catalog.d.ts

@@ -7,6 +7,9 @@ export type RuntimeModelCatalogProfile = {
     provider: string;
     model: string;
     supportsThinking: boolean;
+    reasoningControls?: {
+        budgetTokens: boolean;
+    };
     capabilities: ModelGatewayProfileCapabilities;
     supportsImageInput: boolean;
 };

package/dist/src/runtime/model/model-catalog.js

@@ -1,3 +1,4 @@
+import { supportsModelReasoningBudget } from "../../shared/model-reasoning.js";
 import { MODEL_STEPS } from "../../shared/model-steps.js";
 import { loadRequestRunnerConfig } from "../config/runner/loader.js";
 import { createRequestModelPolicy } from "../config/runner/model-policy.js";
@@ -28,6 +29,7 @@ export function projectRuntimeModelCatalog(modelPolicy) {
             provider: providerConfig.type,
             model: profile.model,
             supportsThinking: profile.supportsThinking === true,
+            ...(supportsModelReasoningBudget({ provider: providerConfig.type, supportsThinking: profile.supportsThinking }) ? { reasoningControls: { budgetTokens: true } } : {}),
             capabilities: profile.capabilities ?? {
                 inputModalities: ["text"],
                 outputModalities: ["text"],

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

@@ -1,13 +1,17 @@
+import type { ModelReasoningPreference } from "../../shared/model-reasoning.js";
 import type { ModelGatewayFormat, ModelGatewayPolicyConfig, ModelPreference, ResolvedModelInvocation } from "../../model-gateway/types.js";
 import type { AgentMode } from "../../shared/types.js";
 import type { ModelStep } from "../../shared/model-steps.js";
 import type { RequestRunnerConfig } from "../config/runner/contracts.js";
+import { type ConfiguredStepInstructionPolicy } from "../config/runner/step-instructions.js";
 import type { RequestContextBudget } from "../context/request-context-contracts.js";
 export declare function resolveModelContextBudget(params: {
     runnerConfig: RequestRunnerConfig;
     agentMode: AgentMode;
     modelStep: ModelStep;
+    configuredInstructionPolicy?: ConfiguredStepInstructionPolicy;
     modelPreference?: ModelPreference;
+    reasoningPreference?: ModelReasoningPreference;
     modelPolicy?: ModelGatewayPolicyConfig;
 }): RequestContextBudget;
 export type ResolvedModelContextAdmission = Readonly<{
@@ -20,6 +24,7 @@ export declare function resolveModelContextAdmission(params: {
     agentMode: AgentMode;
     modelStep: ModelStep;
     modelPreference?: ModelPreference;
+    reasoningPreference?: ModelReasoningPreference;
     modelPolicy?: ModelGatewayPolicyConfig;
     requestFormat?: ModelGatewayFormat;
 }): ResolvedModelContextAdmission;

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

@@ -5,6 +5,7 @@ export function resolveModelContextBudget(params) {
     const configuredInstructionReserveTokens = estimateConfiguredStepInstructionReserveTokens({
         runnerConfig: params.runnerConfig,
         modelStep: params.modelStep,
+        configuredInstructionPolicy: params.configuredInstructionPolicy,
         ...(admission.budget.tokenEstimation
             ? { tokenEstimation: admission.budget.tokenEstimation }
             : {}),
@@ -21,6 +22,7 @@ export function resolveModelContextAdmission(params) {
         agentMode: params.agentMode,
         modelStep: params.modelStep,
         ...(params.requestFormat === undefined ? {} : { format: params.requestFormat }),
+        ...(params.reasoningPreference ? { reasoningPreference: params.reasoningPreference } : {}),
         ...(params.modelPreference
             ? { modelPreference: params.modelPreference }
             : {}),

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

@@ -1,5 +1,6 @@
 import type { ChatMessage } from "../../model-gateway/types.js";
 import type { ModelStep } from "../../shared/model-steps.js";
+import type { ConfiguredStepInstructionPolicy } from "../config/runner/step-instructions.js";
 import type { ModelStepContextCompactionController } from "./context-compaction-contracts.js";
 export type { ModelStepCompactionScope, ModelStepCompactionStage, ModelStepCompactionStageOutcome, ModelStepContextCompactionController, ModelStepContextCompactionPreparation, } from "./context-compaction-contracts.js";
 export type ModelStepOutputDiagnostics = Readonly<{
@@ -13,6 +14,8 @@ export type ModelStepOutputDiagnostics = Readonly<{
     providerOutputTokens?: number;
     providerTotalTokens?: number;
 }>;
+/** Removes only caller-owned optional context; mandatory messages stay exact. */
+export type ModelStepOptionalContextProjection = (messages: readonly ChatMessage[]) => readonly ChatMessage[];
 export type ModelStepInvocationInput<T> = Readonly<{
     modelStep: ModelStep;
     messages: ChatMessage[];
@@ -22,6 +25,10 @@ export type ModelStepInvocationInput<T> = Readonly<{
     format?: "json" | Record<string, unknown>;
     /** Exact input bypasses compaction, but must fit the shared input budget. */
     contextRetention?: "exact";
+    /** Isolated internal phases may omit the semantic step's configured guidance. */
+    configuredInstructionPolicy?: ConfiguredStepInstructionPolicy;
+    /** Pure optional omission after full-envelope assessment; never compacts or persists. */
+    optionalContextProjection?: ModelStepOptionalContextProjection;
     contextCompaction?: ModelStepContextCompactionController;
     /** Async validators must forward this attempt signal to their own work. */
     accept(text: string, diagnostics: ModelStepOutputDiagnostics, abortSignal: AbortSignal): T | Promise<T>;

package/dist/src/runtime/model/optional-context-admission.d.ts

@@ -0,0 +1,18 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { RequestMessagesBudgetAssessment } from "../context/request-context-budget.js";
+import type { ModelStepOptionalContextProjection } from "./model-step-port.js";
+type OptionalContextEnvelope = Readonly<{
+    messages: readonly ChatMessage[];
+    assessment: RequestMessagesBudgetAssessment;
+}>;
+/** Optional references yield at the existing pressure threshold, even for exact input. */
+export declare function admitOptionalModelContext(params: OptionalContextEnvelope & Readonly<{
+    project?: ModelStepOptionalContextProjection;
+    assess(messages: readonly ChatMessage[]): Promise<RequestMessagesBudgetAssessment>;
+    assertCurrent(): void;
+    diagnostic: Readonly<{
+        requestId: string;
+        modelStep: string;
+    }>;
+}>): Promise<OptionalContextEnvelope>;
+export {};

package/dist/src/runtime/model/optional-context-admission.js

@@ -0,0 +1,23 @@
+import { traceDebug } from "../observability/debug-logger.js";
+import { requiresContextCompaction } from "./context-compaction-admission.js";
+/** Optional references yield at the existing pressure threshold, even for exact input. */
+export async function admitOptionalModelContext(params) {
+    if (!params.project)
+        return params;
+    if (!requiresContextCompaction(true, params.assessment))
+        return params;
+    params.assertCurrent();
+    const messages = params.project(params.messages);
+    if (messages === params.messages)
+        return params;
+    params.assertCurrent();
+    const assessment = await params.assess(messages);
+    params.assertCurrent();
+    traceDebug("runtime.context", "optional_context.projected", {
+        ...params.diagnostic,
+        beforeMessageCount: params.messages.length,
+        afterMessageCount: messages.length,
+        fits: assessment.fits,
+    });
+    return { messages, assessment };
+}

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

@@ -0,0 +1,13 @@
+import { ModelGatewayInvocationError } from "../../model-gateway/client/invocation-error.js";
+import type { ModelStep } from "../../shared/model-steps.js";
+/** A transport/provider failure bound to the model step that actually invoked it. */
+export declare class ModelProviderFailure extends Error {
+    readonly modelStep: ModelStep;
+    readonly code = "model_provider_failure";
+    readonly stage: string;
+    constructor(modelStep: ModelStep, cause: ModelGatewayInvocationError);
+}
+/** Unrecognized local faults retain their identity and existing failure path. */
+export declare function invokeModelProvider<T>(modelStep: ModelStep, invoke: () => Promise<T>): Promise<T>;
+/** Retains bounded diagnostics when the failed child no longer escapes the request. */
+export declare function projectModelProviderFailureDiagnostics(error: unknown, messages: unknown): Record<string, unknown>;

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

@@ -0,0 +1,37 @@
+import { ModelGatewayInvocationError } from "../../model-gateway/client/invocation-error.js";
+import { permitsModelContentTrace } from "../../model-gateway/observability/content-trace-policy.js";
+/** A transport/provider failure bound to the model step that actually invoked it. */
+export class ModelProviderFailure extends Error {
+    modelStep;
+    code = "model_provider_failure";
+    stage;
+    constructor(modelStep, cause) {
+        super(cause.message, { cause });
+        this.modelStep = modelStep;
+        this.name = "ModelProviderFailure";
+        this.stage = `model_provider_${cause.kind}`;
+    }
+}
+/** Unrecognized local faults retain their identity and existing failure path. */
+export async function invokeModelProvider(modelStep, invoke) {
+    try {
+        return await invoke();
+    }
+    catch (error) {
+        if (!(error instanceof ModelGatewayInvocationError))
+            throw error;
+        throw new ModelProviderFailure(modelStep, error);
+    }
+}
+/** Retains bounded diagnostics when the failed child no longer escapes the request. */
+export function projectModelProviderFailureDiagnostics(error, messages) {
+    if (!(error instanceof ModelProviderFailure))
+        return {};
+    return {
+        providerFailureCode: error.code,
+        providerFailureStage: error.stage,
+        ...(permitsModelContentTrace(error.modelStep, messages)
+            ? { providerErrorPreview: error.message.slice(0, 400) }
+            : { contentOmitted: true }),
+    };
+}

package/dist/src/runtime/orchestration/role-calls/activation-budget.js

@@ -46,6 +46,7 @@ function resolveActivationReservationCallId(command) {
         case "update_capability_scope":
         case "reconsider_capability_selection":
         case "begin_memory_recall":
+        case "record_skill_read":
             return command.callId;
         default:
             return undefined;

package/dist/src/runtime/orchestration/role-calls/candidate-validation.js

@@ -4,6 +4,7 @@ import { isRoleCapabilitySelectionSupervisionState, } from "./capability-selecti
 import { isValidRoleCapabilitySelectionSupervision } from "./capability-selection-supervision-validation.js";
 import { hasInitialMemoryContext, validateRoleMemoryRecalls } from "./memory-recall-state-validation.js";
 import { isValidAdoptedModelWorkPlan } from "./work-plan-validation.js";
+import { validateRoleSkillReads } from "./skill-read.js";
 import { isRoleOperationFingerprint, isRoleOperationOutcomeFingerprintForOutcome, isSameRoleOperationIdentity, replayRoleOperationSupervisionEvidence, } from "./operation-supervision.js";
 import { isIssuedRoleOperationSupervisionInterventionForRequest } from "./operation-supervision-issuance.js";
 import { isRoleOperationSupervisionSettlementHistoryValid, isRoleOperationSupervisionState, } from "./operation-supervision-state-validation.js";
@@ -179,6 +180,7 @@ export function validateRoleCallState(state, policy) {
     issues.push(...validateRoleCallPlans(state, policy));
     validateCapabilityExecutions(state, policy, issues);
     issues.push(...validateRoleMemoryRecalls(state));
+    issues.push(...validateRoleSkillReads(state, policy));
     if (!isValidRoleOperationSupervision(state, policy)) {
         issues.push(issue("invalid_role_operation_supervision", "state.operationSupervision"));
     }

package/dist/src/runtime/orchestration/role-calls/checkpoint-state.js

@@ -72,7 +72,8 @@ function hasConsistentCheckpointRevision(revision, state) {
     const settlements = new Set(state.capabilityExecutions
         .filter((entry) => entry.status === "settled")
         .map(executionActivationIdentity));
-    const minimumCommits = state.calls.length + state.results.length + begins.size + settlements.size;
+    const minimumCommits = state.calls.length + state.results.length + begins.size + settlements.size +
+        (state.skillReads?.length ?? 0);
     if (revision < minimumCommits)
         return false;
     return state.results.every((result) => result.receipt === undefined || result.receipt.sourceRevision < revision);

package/dist/src/runtime/orchestration/role-calls/command-decoder.js

@@ -6,6 +6,7 @@ import { isRoleCapabilityId, } from "./contracts.js";
 import { parseRoleCallPlanBinding } from "./plan.js";
 import { normalizeRoleCallResultReceipt } from "./result-receipt.js";
 import { decodeMemoryRecallCommand } from "./memory-recall-decoder.js";
+import { decodeSkillReadCommand } from "./skill-read.js";
 import { decodeModelWorkPlanCommand } from "./work-plan-validation.js";
 import { parseRoleCallWorkerCapabilityScope } from "./worker-capability-scope.js";
 import { isRoleCallWorkingDirectoryRoleId, normalizeEstablishedRoleCallWorkingDirectory, normalizeRoleCallWorkingDirectory, } from "./working-directory.js";
@@ -15,6 +16,8 @@ export function decodeRoleCallCommand(input) {
         return { ok: false, code: "invalid_command" };
     }
     switch (input.type) {
+        case "record_skill_read":
+            return decodeSkillReadCommand(input);
         case "update_model_work_plan":
             return decodeModelWorkPlanCommand(input);
         case "begin_memory_recall":

package/dist/src/runtime/orchestration/role-calls/command-dispatch/skill-read-transition.d.ts

@@ -0,0 +1,4 @@
+import type { RoleCallPolicy, RoleCallState, RoleCallTransitionResult } from "../contracts.js";
+import type { RecordRoleSkillReadCommand } from "../skill-read.js";
+/** A synchronous core lookup returns in one commit without a child or waiting state. */
+export declare function recordSkillRead(state: RoleCallState, command: RecordRoleSkillReadCommand, policy: RoleCallPolicy): RoleCallTransitionResult;

package/dist/src/runtime/orchestration/role-calls/command-dispatch/skill-read-transition.js

@@ -0,0 +1,48 @@
+import { commit, reject } from "../reducer-primitives.js";
+import { replaceCall } from "./call-frame-state.js";
+/** A synchronous core lookup returns in one commit without a child or waiting state. */
+export function recordSkillRead(state, command, policy) {
+    const call = state.calls.find((candidate) => candidate.callId === command.callId);
+    if (!call)
+        return reject(state, "skill_read_caller_invalid");
+    const usesSupervisorContract = policy.authority.rootContractId === "supervisor";
+    if (!usesSupervisorContract)
+        return reject(state, "skill_read_caller_invalid");
+    const ownsActiveRequest = state.phase === "running" &&
+        state.activeCallId === command.callId &&
+        state.rootCallId === command.callId;
+    if (!ownsActiveRequest)
+        return reject(state, "skill_read_caller_invalid");
+    const isActiveSupervisorRoot = call.parentCallId === null &&
+        call.roleId === "supervisor" &&
+        call.status === "active";
+    if (!isActiveSupervisorRoot)
+        return reject(state, "skill_read_caller_invalid");
+    const previousReads = state.skillReads ?? [];
+    const matchesCurrentActivation = call.activationCount === command.invocationAttempt;
+    if (!matchesCurrentActivation)
+        return reject(state, "skill_read_invocation_mismatch");
+    const preservesSteeringOrder = command.steeringVersion >= (previousReads.at(-1)?.steeringVersion ?? 0);
+    if (!preservesSteeringOrder)
+        return reject(state, "skill_read_invocation_mismatch");
+    const { authority: _authority, type: _type, ...payload } = command;
+    const read = {
+        ...payload,
+        readId: `skill-read-${previousReads.length + 1}`,
+    };
+    return commit({
+        ...state,
+        calls: replaceCall(state.calls, {
+            ...call,
+            activationCount: call.activationCount + 1,
+        }),
+        skillReads: [...previousReads, read],
+    }, {
+        type: "skill_read_recorded",
+        callId: call.callId,
+        readId: read.readId,
+        invocationAttempt: read.invocationAttempt,
+        steeringVersion: read.steeringVersion,
+        operation: read.operation,
+    });
+}

package/dist/src/runtime/orchestration/role-calls/command-dispatch.js

@@ -3,11 +3,14 @@ import { beginCapabilityExecution, settleCapabilityExecution, } from "./command-
 import { reconsiderCapabilitySelection } from "./command-dispatch/capability-selection-transition.js";
 import { updateModelWorkPlan } from "./command-dispatch/work-plan-transition.js";
 import { beginMemoryRecall, settleMemoryRecall } from "./command-dispatch/memory-recall-transitions.js";
+import { recordSkillRead } from "./command-dispatch/skill-read-transition.js";
 import { establishWorkingDirectory, updateCapabilityScope, } from "./command-dispatch/call-scope-transitions.js";
 import { openChild, returnChild, } from "./command-dispatch/child-transitions.js";
 import { completeRootResponse, createRoot, } from "./command-dispatch/root-transitions.js";
 export function dispatchRoleCallCommand(state, command, policy, admittedHeadRevision) {
     switch (command.type) {
+        case "record_skill_read":
+            return recordSkillRead(state, command, policy);
         case "update_model_work_plan":
             return updateModelWorkPlan(state, command, policy);
         case "begin_memory_recall":

package/dist/src/runtime/orchestration/role-calls/contracts.d.ts

@@ -7,6 +7,7 @@ import type { RoleCapabilitySelectionReconsiderationCause } from "./reconsiderat
 import type { RoleCallResultReceipt } from "./result-receipt.js";
 import type { RoleInitialMemory, RoleMemoryRecall, RoleMemoryRecallCommand, RoleMemoryRecallCommitEffect, RoleMemoryRecallTransactions } from "./memory-recall-contract.js";
 import type { AdoptedModelWorkPlan, UpdateModelWorkPlanCommand, ModelWorkPlanCommitEffect, ModelWorkPlanTransactions } from "./work-plan-contracts.js";
+import type { RecordRoleSkillReadCommand, RoleSkillRead, RoleSkillReadCommitEffect } from "./skill-read.js";
 export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 18;
 export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v18";
 export declare const ROLE_CALL_OBJECTIVE_MAX_LENGTH = 8192;
@@ -191,6 +192,8 @@ export type RoleCallState = Readonly<{
     plans: readonly RoleCallPlanState[];
     capabilityExecutions: readonly RoleCapabilityExecution[];
     memoryRecalls: readonly RoleMemoryRecall[];
+    /** Immutable core reference reads; omitted on older checkpoints. */
+    skillReads?: readonly RoleSkillRead[];
     initialMemory?: RoleInitialMemory;
     operationSupervision: RoleOperationSupervisionState;
     capabilitySelectionSupervision: RoleCapabilitySelectionSupervisionState;
@@ -305,8 +308,8 @@ export type ReconsiderRoleCapabilitySelectionCommand = Readonly<{
     selection: RoleCapabilitySelectionProjection;
     cause: RoleCapabilitySelectionReconsiderationCause;
 }>;
-export type RoleCallLedgerCommand = UpdateModelWorkPlanCommand | RoleMemoryRecallCommand | CreateRootRoleCallCommand | CompleteRootResponseCommand | OpenChildRoleCallCommand | ReturnChildRoleCallCommand | BeginRoleCapabilityExecutionCommand | SettleRoleCapabilityExecutionCommand | BeginRoleCapabilityBatchCommand | SettleRoleCapabilityBatchCommand | UpdateRoleCapabilityScopeCommand | EstablishRoleCallWorkingDirectoryCommand | ReconsiderRoleCapabilitySelectionCommand;
-export type RoleCallCommitEffect = ModelWorkPlanCommitEffect | RoleMemoryRecallCommitEffect | Readonly<{
+export type RoleCallLedgerCommand = RecordRoleSkillReadCommand | UpdateModelWorkPlanCommand | RoleMemoryRecallCommand | CreateRootRoleCallCommand | CompleteRootResponseCommand | OpenChildRoleCallCommand | ReturnChildRoleCallCommand | BeginRoleCapabilityExecutionCommand | SettleRoleCapabilityExecutionCommand | BeginRoleCapabilityBatchCommand | SettleRoleCapabilityBatchCommand | UpdateRoleCapabilityScopeCommand | EstablishRoleCallWorkingDirectoryCommand | ReconsiderRoleCapabilitySelectionCommand;
+export type RoleCallCommitEffect = RoleSkillReadCommitEffect | ModelWorkPlanCommitEffect | RoleMemoryRecallCommitEffect | Readonly<{
     type: "root_created";
     callId: string;
 }> | Readonly<{
@@ -373,7 +376,7 @@ export type RoleCallValidationIssue = Readonly<{
     code: string;
     path: string;
 }>;
-export type RoleCallTransitionRejectionCode = "invalid_current_state" | "invalid_policy" | "invalid_command" | "root_already_created" | "root_missing" | "caller_not_active" | "root_response_not_allowed" | "supervisor_child_forbidden" | "child_role_not_authorized" | "child_dependency_invalid" | "planner_plan_binding_invalid" | "planner_plan_already_declared" | "planner_plan_missing" | "planner_plan_item_unavailable" | "planner_plan_incomplete" | "depth_limit_exceeded" | "call_limit_exceeded" | "child_return_mismatch" | "capability_caller_invalid" | "capability_invocation_mismatch" | "capability_execution_limit_exceeded" | "capability_execution_mismatch" | "capability_scope_update_invalid" | "working_directory_establishment_invalid" | "model_work_plan_update_invalid" | "capability_selection_reconsideration_invalid" | "capability_selection_supervision_limit_exceeded" | "operation_supervision_limit_exceeded" | "memory_recall_caller_invalid" | "memory_recall_invocation_mismatch" | "memory_recall_settlement_mismatch" | "role_activation_limit_exceeded";
+export type RoleCallTransitionRejectionCode = "invalid_current_state" | "invalid_policy" | "invalid_command" | "root_already_created" | "root_missing" | "caller_not_active" | "root_response_not_allowed" | "supervisor_child_forbidden" | "child_role_not_authorized" | "child_dependency_invalid" | "planner_plan_binding_invalid" | "planner_plan_already_declared" | "planner_plan_missing" | "planner_plan_item_unavailable" | "planner_plan_incomplete" | "depth_limit_exceeded" | "call_limit_exceeded" | "child_return_mismatch" | "capability_caller_invalid" | "capability_invocation_mismatch" | "capability_execution_limit_exceeded" | "capability_execution_mismatch" | "capability_scope_update_invalid" | "working_directory_establishment_invalid" | "model_work_plan_update_invalid" | "capability_selection_reconsideration_invalid" | "capability_selection_supervision_limit_exceeded" | "operation_supervision_limit_exceeded" | "skill_read_caller_invalid" | "skill_read_invocation_mismatch" | "memory_recall_caller_invalid" | "memory_recall_invocation_mismatch" | "memory_recall_settlement_mismatch" | "role_activation_limit_exceeded";
 export type RoleCallTransitionResult = Readonly<{
     ok: true;
     state: RoleCallState;

package/dist/src/runtime/orchestration/role-calls/contracts.js

@@ -25,13 +25,13 @@ export function isRoleCapabilityId(input) {
 }
 export const SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT = Object.freeze({
     id: "supervisor-worker-v1",
-    version: 2,
-    definitionHash: "sha256:2ee79cee6dbb27ffaeb59f84c4c838cf9d16a965ca4f07e7d638e8589868e036",
+    version: 3,
+    definitionHash: "sha256:f4283b1d3f8f86bba0177475d9368137f39eca54d452a06668c844f4173791c5",
     rootContractId: "supervisor",
     availableSubordinateContractIds: Object.freeze([
         "planner",
         "worker",
         "reviewer",
     ]),
-    capabilityAuthorities: Object.freeze(["worker"]),
+    capabilityAuthorities: Object.freeze(["root", "worker"]),
 });