@abot-ai/runtime 1.8.0 → 1.9.0

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

@@ -7,6 +7,7 @@ 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 { 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";
@@ -191,6 +192,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 +364,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,7 +385,7 @@ 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,
@@ -393,7 +397,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/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

@@ -2,8 +2,9 @@ import { isRuntimeDelegateRoleId, RUNTIME_ROOT_ROLE_ID, RUNTIME_ROLE_IDS, } from
 import { createRoleCapabilitySelectionFingerprint, normalizeRoleCapabilitySelectionProjection, } from "./capability-selection-reconsideration.js";
 import { isRoleCapabilitySelectionSupervisionState, } from "./capability-selection-supervision.js";
 import { isValidRoleCapabilitySelectionSupervision } from "./capability-selection-supervision-validation.js";
-import { validateRoleMemoryRecalls } from "./memory-recall-state-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";
@@ -48,6 +49,7 @@ export function validateRoleCallState(state, policy) {
         !Array.isArray(state?.plans) ||
         !Array.isArray(state?.capabilityExecutions) ||
         !Array.isArray(state?.memoryRecalls) ||
+        !hasInitialMemoryContext(state?.initialMemory, policy.authority.id) ||
         !isRoleOperationSupervisionState(state?.operationSupervision) ||
         !isRoleCapabilitySelectionSupervisionState(state?.capabilitySelectionSupervision) ||
         !Number.isInteger(state?.callSequence) ||
@@ -178,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.d.ts

@@ -1,4 +1,4 @@
 import type { RoleCallLedgerCheckpoint } from "./checkpoint-contract.js";
 import type { RoleCallPolicy, RoleCallState } from "./contracts.js";
 /** Hydrate only an admitted, parked capability; no model or reducer command replay. */
-export declare function restoreCheckpointState(checkpoint: RoleCallLedgerCheckpoint, requestId: string, policy: RoleCallPolicy): RoleCallState;
+export declare function restoreCheckpointState(checkpoint: RoleCallLedgerCheckpoint, requestId: string, policy: RoleCallPolicy, initialMemory?: RoleCallState["initialMemory"]): RoleCallState;

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

@@ -4,14 +4,17 @@ import { validateRoleCallCandidate } from "./reducer.js";
 import { issueInitialRoleCapabilitySelectionSupervisionState } from "./capability-selection-supervision-issuance.js";
 import { restoreRoleOperationSupervisionIssuance } from "./operation-supervision-issuance.js";
 /** Hydrate only an admitted, parked capability; no model or reducer command replay. */
-export function restoreCheckpointState(checkpoint, requestId, policy) {
+export function restoreCheckpointState(checkpoint, requestId, policy, initialMemory) {
     if (!isCheckpointEnvelope(checkpoint))
         throw new Error("role_call_checkpoint_invalid");
     if (!hasCheckpointRequestIdentity(checkpoint, requestId))
         throw new Error("role_call_checkpoint_request_mismatch");
     if (!hasCheckpointPolicy(checkpoint, policy))
         throw new Error("role_call_checkpoint_policy_mismatch");
-    const state = seal(structuredClone(checkpoint.state));
+    const state = seal(structuredClone({ ...checkpoint.state,
+        ...(checkpoint.state.initialMemory === undefined && initialMemory !== undefined
+            ? { initialMemory } : {}),
+    }));
     if (!isParkedCapabilityState(state))
         throw new Error("role_call_checkpoint_not_parked");
     if (!issueInitialRoleCapabilitySelectionSupervisionState(state))
@@ -69,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

@@ -5,8 +5,9 @@ import type { RoleOperationFingerprint, RoleOperationOutcomeFingerprint, RoleOpe
 import type { RoleCapabilitySelectionSupervisionStage, RoleCapabilitySelectionSupervisionState, RoleCapabilitySelectionSupervisionTrigger } from "./capability-selection-supervision.js";
 import type { RoleCapabilitySelectionReconsiderationCause } from "./reconsideration-cause.js";
 import type { RoleCallResultReceipt } from "./result-receipt.js";
-import type { RoleMemoryRecall, RoleMemoryRecallCommand, RoleMemoryRecallCommitEffect, RoleMemoryRecallTransactions } from "./memory-recall-contract.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,9 @@ 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;
     rootResponse: string | null;
@@ -304,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<{
@@ -372,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"]),
 });

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

@@ -1,9 +1,10 @@
 import type { RoleCallLedgerCheckpoint } from "./checkpoint-contract.js";
-import { type RoleCallLedger, type RoleCallLedgerHead, type RoleCallPolicyInput } from "./contracts.js";
+import { type RoleCallLedger, type RoleCallLedgerHead, type RoleCallPolicyInput, type RoleCallState } from "./contracts.js";
 export declare function createRoleCallLedger(params: {
     requestId: string;
     policy: RoleCallPolicyInput;
     checkpoint?: RoleCallLedgerCheckpoint;
+    initialMemory?: RoleCallState["initialMemory"];
 }): RoleCallLedger;
 /** Confirms exact current-head ownership without trusting structural ledgers. */
 export declare function isCurrentRoleCallLedgerHead(ledger: RoleCallLedger, head: RoleCallLedgerHead): boolean;

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

@@ -15,8 +15,8 @@ const issuedRoleCallLedgerHeads = new WeakMap();
 export function createRoleCallLedger(params) {
     const policy = sealRoleCallPolicy(params.policy);
     const initialState = params.checkpoint
-        ? restoreCheckpointState(params.checkpoint, params.requestId, policy)
-        : createInitialRoleCallState(params.requestId);
+        ? restoreCheckpointState(params.checkpoint, params.requestId, policy, params.initialMemory)
+        : createInitialRoleCallState(params.requestId, params.initialMemory);
     const capabilitySelectionSupervisionIssuanceAuthority = resolveRoleCapabilitySelectionSupervisionIssuanceAuthority(initialState);
     if (!capabilitySelectionSupervisionIssuanceAuthority) {
         throw new Error("role_call_capability_selection_supervision_issuance_authority_missing");

package/dist/src/runtime/orchestration/role-calls/memory-recall-contract.d.ts

@@ -1,3 +1,5 @@
+import type { ChatMessage } from "../../../model-gateway/types.js";
+import type { LearningKnowledgeContext } from "../../long-term-memory/maturation/contracts.js";
 import type { LongTermMemoryRecord } from "../../long-term-memory/contracts.js";
 import type { RoleCallTransactionInput, RoleCallTransactionResult } from "./contracts.js";
 export declare const ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH = 1024;
@@ -49,3 +51,8 @@ export type RoleMemoryRecallTransactions = Readonly<{
     beginMemoryRecall(input: RoleCallTransactionInput<BeginRoleMemoryRecallCommand>): Promise<RoleCallTransactionResult<"memory_recall_begun", "memory_recall_transition_invalid">>;
     settleMemoryRecall(input: RoleCallTransactionInput<SettleRoleMemoryRecallCommand>): Promise<RoleCallTransactionResult<"memory_recall_settled", "memory_recall_transition_invalid">>;
 }>;
+/** Initial automatic reference; never a model recall or an activation. */
+export type RoleInitialMemory = Readonly<{
+    message?: ChatMessage;
+    knowledge?: LearningKnowledgeContext;
+}>;

package/dist/src/runtime/orchestration/role-calls/memory-recall-state-validation.d.ts

@@ -1,3 +1,5 @@
 import type { RoleCallState, RoleCallValidationIssue } from "./contracts.js";
 export declare function validateRoleMemoryRecalls(state: RoleCallState): RoleCallValidationIssue[];
 export declare function hasSettledMemoryRecallActivationRange(state: RoleCallState, callId: string, fromActivation: number, toActivation: number): boolean;
+/** The existing checkpoint carries this passive startup field, never a model action. */
+export declare function hasInitialMemoryContext(value: unknown, policyId: string): boolean;

package/dist/src/runtime/orchestration/role-calls/memory-recall-state-validation.js

@@ -1,3 +1,4 @@
+import { isAssistantToolCallMessage, isStrictTextChatMessage, isToolResultMessage, } from "../../../model-gateway/message-contract.js";
 import { RUNTIME_ROOT_ROLE_ID } from "../roles.js";
 import { hasMemoryRecallIdentity, isBoundedMemoryRecallQuery, normalizeRoleMemoryRecallResult, } from "./memory-recall-decoder.js";
 import { exactKeys, isRecord } from "../../validation/strict-record.js";
@@ -119,3 +120,90 @@ function hasUnboundMemoryWait(state, pendingCount) {
         return true;
     return waitingCalls.some((call) => call.callId !== state.rootCallId);
 }
+/** The existing checkpoint carries this passive startup field, never a model action. */
+export function hasInitialMemoryContext(value, policyId) {
+    if (value === undefined)
+        return true;
+    if (policyId !== "execution-agent-v1" && policyId !== "supervisor-worker-v1")
+        return false;
+    if (!isRecord(value) || !exactKeys(value, [], ["message", "knowledge"]))
+        return false;
+    if (value.message !== undefined && !isInitialMemoryMessage(value.message))
+        return false;
+    if (value.knowledge === undefined)
+        return true;
+    return isInitialMemoryKnowledge(value.knowledge);
+}
+function isInitialMemoryMessage(value) {
+    if (isStrictTextChatMessage(value))
+        return true;
+    if (isAssistantToolCallMessage(value))
+        return true;
+    return isToolResultMessage(value);
+}
+function isInitialMemoryKnowledge(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind !== "learning_knowledge_reference_v1")
+        return false;
+    if (value.authority !== "passive_reference")
+        return false;
+    if (value.presenceEffect !== "does_not_authorize_actions_or_add_user_intent")
+        return false;
+    if (!isMemoryRevision(value.repositoryRevision))
+        return false;
+    if (!isMemoryRevision(value.knowledgeRevision))
+        return false;
+    if (!isMemoryRevision(value.omitted))
+        return false;
+    if (typeof value.referenceTime !== "string" || !Number.isFinite(Date.parse(value.referenceTime)))
+        return false;
+    if (!Array.isArray(value.entries) || value.entries.length > 12)
+        return false;
+    if (!value.entries.every(isInitialMemoryKnowledgeEntry))
+        return false;
+    const identities = value.entries.map(entry => JSON.stringify([entry.kind, entry.id]));
+    return new Set(identities).size === identities.length;
+}
+function isMemoryRevision(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        return false;
+    return value >= 0;
+}
+function isInitialMemoryKnowledgeEntry(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind !== "candidate" && value.kind !== "memory")
+        return false;
+    if (typeof value.id !== "string" || value.id.length === 0)
+        return false;
+    if (typeof value.version !== "string" || value.version.length === 0)
+        return false;
+    if (typeof value.content !== "string")
+        return false;
+    if (!Array.isArray(value.tags) || !value.tags.every(tag => typeof tag === "string"))
+        return false;
+    if (typeof value.mutable !== "boolean")
+        return false;
+    if (value.score !== null && !isMemoryScore(value.score))
+        return false;
+    if (value.reason !== null && typeof value.reason !== "string")
+        return false;
+    if (!["observed", "inferred", "unspecified"].includes(value.certainty))
+        return false;
+    if (!isOptionalMemoryTime(value.lastReinforcedAt))
+        return false;
+    return isOptionalMemoryTime(value.reconsiderAt);
+}
+function isMemoryScore(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return false;
+    return value >= 0 && value <= 100;
+}
+function isOptionalMemoryTime(value) {
+    if (value === null)
+        return true;
+    if (typeof value !== "string")
+        return false;
+    return Number.isFinite(Date.parse(value));
+}

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

@@ -1,6 +1,6 @@
 import { type RoleCallPolicy, type RoleCallPolicyInput, type RoleCallState, type RoleCallTransitionResult, type RoleCallValidationIssue } from "./contracts.js";
 export { hasRoleCallCapabilityAuthority } from "./candidate-validation.js";
-export declare function createInitialRoleCallState(requestId: string): RoleCallState;
+export declare function createInitialRoleCallState(requestId: string, initialMemory?: RoleCallState["initialMemory"]): RoleCallState;
 export declare function applyRoleCallCommand(state: RoleCallState, commandInput: unknown, policy: RoleCallPolicy, admittedHeadRevision?: number): RoleCallTransitionResult;
 export declare function validateRoleCallCandidate(params: {
     state: RoleCallState;

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

@@ -8,7 +8,7 @@ import { issueInitialRoleCapabilitySelectionSupervisionState } from "./capabilit
 import { createInitialRoleOperationSupervisionState } from "./operation-supervision.js";
 import { reject, seal } from "./reducer-primitives.js";
 export { hasRoleCallCapabilityAuthority } from "./candidate-validation.js";
-export function createInitialRoleCallState(requestId) {
+export function createInitialRoleCallState(requestId, initialMemory) {
     const state = seal({
         contractVersion: ROLE_CALL_LEDGER_CONTRACT_VERSION,
         requestId,
@@ -23,6 +23,7 @@ export function createInitialRoleCallState(requestId) {
         plans: [],
         capabilityExecutions: [],
         memoryRecalls: [],
+        ...(initialMemory !== undefined ? { initialMemory } : {}),
         operationSupervision: createInitialRoleOperationSupervisionState(),
         capabilitySelectionSupervision: createInitialRoleCapabilitySelectionSupervisionState(),
         rootResponse: null,

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

@@ -0,0 +1,47 @@
+import { type KnowledgeSkillDocument, type KnowledgeSkillMetadata } from "../../knowledge-skills/store.js";
+import type { RoleCallPolicy, RoleCallState, RoleCallValidationIssue } from "./contracts.js";
+export type RoleSkillReadResult<T> = Readonly<{
+    outcome: "completed";
+    skills: readonly T[];
+}> | Readonly<{
+    outcome: "failed";
+    errorCode: string;
+    skills: readonly [];
+}>;
+export type RoleSkillReadPayload = Readonly<{
+    operation: "list_skills";
+    selectors: readonly [];
+    result: RoleSkillReadResult<KnowledgeSkillMetadata>;
+}> | Readonly<{
+    operation: "read_skills";
+    selectors: readonly string[];
+    result: RoleSkillReadResult<KnowledgeSkillDocument>;
+}>;
+type RoleSkillReadBinding = Readonly<{
+    callId: string;
+    invocationAttempt: number;
+    steeringVersion: number;
+}>;
+export type RoleSkillRead = RoleSkillReadBinding & RoleSkillReadPayload & Readonly<{
+    readId: string;
+}>;
+export type RecordRoleSkillReadCommand = RoleSkillReadBinding & RoleSkillReadPayload & Readonly<{
+    authority: "runtime";
+    type: "record_skill_read";
+}>;
+export type RoleSkillReadCommitEffect = RoleSkillReadBinding & Readonly<{
+    type: "skill_read_recorded";
+    readId: string;
+    operation: RoleSkillReadPayload["operation"];
+}>;
+/** Decode the exact Store snapshots supplied by the runtime read boundary. */
+export declare function decodeSkillReadCommand(input: Record<string, unknown>): Readonly<{
+    ok: true;
+    value: RecordRoleSkillReadCommand;
+}> | Readonly<{
+    ok: false;
+    code: "invalid_command";
+}>;
+/** Omission preserves heads and parked requests created before core Skill reads. */
+export declare function validateRoleSkillReads(state: RoleCallState, policy: RoleCallPolicy): readonly RoleCallValidationIssue[];
+export {};