@abot-ai/runtime 1.8.1 → 2.0.0

package/dist/src/runtime/request/role-call-return-events.js

@@ -0,0 +1,63 @@
+import { consumeUnexpectedThenable } from "../orchestration/synchronous-boundary.js";
+import { isRoleCallResultText, } from "../orchestration/role-calls/index.js";
+/** Projects the stored Planner result without changing role state or active stage. */
+export function projectRequestRoleReturnCommit(commit) {
+    if (!isDirectSupervisorChildReturn(commit))
+        return undefined;
+    const child = commit.head.state.calls.find((call) => call.callId === commit.effect.childCallId);
+    if (!isReturnedPlanner(child, commit.effect))
+        return undefined;
+    const result = commit.head.state.results.find((candidate) => candidate.resultRef === child.resultRef);
+    if (!isMatchingPlannerResult(result, child))
+        return undefined;
+    return Object.freeze({
+        name: "role.returned",
+        payload: Object.freeze({
+            callerCallId: commit.effect.callerCallId,
+            callerRole: "supervisor",
+            childCallId: child.callId,
+            childRole: "planner",
+            outcome: result.outcome,
+            summary: result.summary,
+        }),
+    });
+}
+/** Uses the existing synchronous commit boundary, including emission faults. */
+export function attachRequestRoleReturnEvents(params) {
+    params.ledger.commits.subscribe((commit) => {
+        const event = projectRequestRoleReturnCommit(commit);
+        if (!event)
+            return;
+        const emitted = Reflect.apply(params.onEvent, undefined, [
+            event.name,
+            event.payload,
+        ]);
+        if (consumeUnexpectedThenable(emitted))
+            throw new TypeError("Request return event sink must be synchronous.");
+    });
+}
+function isDirectSupervisorChildReturn(commit) {
+    if (commit.effect.type !== "child_returned")
+        return false;
+    if (commit.head.policy.authority.rootContractId !== "supervisor")
+        return false;
+    return commit.effect.callerCallId === commit.head.state.rootCallId;
+}
+function isReturnedPlanner(child, effect) {
+    if (!child)
+        return false;
+    if (child.parentCallId !== effect.callerCallId || child.depth !== 1)
+        return false;
+    if (child.roleId !== "planner" || child.status !== "completed")
+        return false;
+    return child.resultRef === effect.resultRef;
+}
+function isMatchingPlannerResult(result, child) {
+    if (!result)
+        return false;
+    if (result.producerCallId !== child.callId || result.roleId !== child.roleId)
+        return false;
+    if (result.outcome !== "completed" && result.outcome !== "failed")
+        return false;
+    return isRoleCallResultText(result.summary);
+}

package/dist/src/runtime/request/role-executor-composition.js

@@ -43,10 +43,10 @@ export const EXECUTION_AGENT_ROLE_EXECUTORS = projectRequestRoleExecutorRegistry
 ]);
 const SUPERVISOR_WORKER_V1_POLICY_DEFINITION = Object.freeze({
     id: "supervisor-worker-v1",
-    version: 2,
+    version: 3,
     rootContract: SUPERVISOR_ROOT_CONTRACT,
     roleExecutors: REQUEST_ROLE_EXECUTORS,
-    capabilityAuthorities: Object.freeze(["worker"]),
+    capabilityAuthorities: Object.freeze(["root", "worker"]),
 });
 const EXECUTION_AGENT_V1_POLICY_DEFINITION = Object.freeze({
     id: "execution-agent-v1",

package/dist/src/runtime/request/root-capability-binding.d.ts

@@ -0,0 +1,24 @@
+import { type WorkerCapabilityBinding } from "../orchestration/worker-capabilities/index.js";
+import { type RoleCallLedger, type RoleCallLedgerHead, type RoleCallFrame } from "../orchestration/role-calls/index.js";
+import type { RequestExecutionScope, RequestCapabilityExecutionView } from "./execution-scope.js";
+import type { RootActivation } from "./root-execution-contracts.js";
+import type { RootContractDecision } from "./root-contract.js";
+/** Existing root capability preparation, shared without changing either policy's execution path. */
+export declare function prepareRootCapabilityBinding(params: {
+    request: RequestExecutionScope;
+    ledger: RoleCallLedger;
+    activation: RootActivation & Readonly<{
+        decisionSteeringVersion: number;
+    }>;
+    decision: Extract<RootContractDecision, {
+        action: "invoke_capability" | "invoke_capabilities";
+    }>;
+}): Promise<{
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    binding: WorkerCapabilityBinding<RequestCapabilityExecutionView>;
+}>;
+export declare function requireRootCallFrame(params: {
+    head: RoleCallLedgerHead;
+    callId: string;
+}): RoleCallFrame;

package/dist/src/runtime/request/root-capability-binding.js

@@ -0,0 +1,57 @@
+import { createRootExecutionFreshness } from "./capability-execution-freshness.js";
+import { createRoleCapabilityBinding } from "../orchestration/worker-capabilities/index.js";
+import { resolveRoleCallTransactions } from "../orchestration/role-calls/index.js";
+import { RUNTIME_ROOT_ROLE_ID } from "../orchestration/roles.js";
+import { resolveRequestSteeringInbox } from "./request-steering.js";
+/** Existing root capability preparation, shared without changing either policy's execution path. */
+export async function prepareRootCapabilityBinding(params) {
+    const { request, ledger, activation, decision } = params;
+    const transactions = resolveRoleCallTransactions(ledger);
+    const requestSteering = resolveRequestSteeringInbox(request.requestSteering);
+    let head = activation.head;
+    let call = activation.call;
+    if (decision.workingDirectory !== undefined) {
+        const established = await transactions.establishWorkingDirectory({
+            expectedHead: head,
+            callId: call.callId,
+            invocationAttempt: call.activationCount,
+            workingDirectory: decision.workingDirectory,
+        });
+        if (!established.ok) {
+            throw new Error(`role_call_ledger_rejected:${established.issueCode}`);
+        }
+        head = established.commit.head;
+        call = requireRootCallFrame({ head, callId: call.callId });
+    }
+    const binding = createRoleCapabilityBinding({
+        requestId: request.requestId,
+        context: request.workerCapabilities.executionContext,
+        call,
+        ledger,
+        adapters: request.workerCapabilities.provider.getAdapters(),
+        ...(request.approvalGate
+            ? { approvalGate: request.approvalGate }
+            : {}),
+        ...(request.executionPolicy.authority.capabilityAuthorities.includes("root")
+            ? {
+                executionFreshness: createRootExecutionFreshness({
+                    requestSteering,
+                    steeringVersion: activation.decisionSteeringVersion,
+                }),
+            }
+            : {}),
+    });
+    return { head, call, binding };
+}
+export function requireRootCallFrame(params) {
+    const call = params.head.state.calls.find((candidate) => candidate.callId === params.callId);
+    if (!call ||
+        call.callId !== params.head.state.rootCallId ||
+        call.parentCallId !== null ||
+        call.roleId !== RUNTIME_ROOT_ROLE_ID ||
+        call.depth !== 0 ||
+        call.status !== "active") {
+        throw new Error("supervisor_call_frame_missing");
+    }
+    return call;
+}

package/dist/src/runtime/request/root-capability-catalog.d.ts

@@ -0,0 +1,16 @@
+import type { ExecutionPolicyAuthoritySnapshot } from "../orchestration/role-calls/index.js";
+import type { RuntimeDelegateRoleId } from "../orchestration/roles.js";
+import type { WorkerCapabilityDescriptor } from "../orchestration/worker-capabilities/contracts.js";
+/** Capture both role projections from the same request-session descriptor read. */
+export declare function captureRootCapabilityCatalog(params: {
+    authority: ExecutionPolicyAuthoritySnapshot;
+    roleIds: readonly RuntimeDelegateRoleId[];
+    getDescriptors: () => readonly WorkerCapabilityDescriptor[];
+}): Readonly<{
+    availableWorkerCapabilityCatalog: readonly Readonly<{
+        groupId: import("../../capabilities/tool-types.js").ToolCatalogGroup;
+        memberCount: number;
+        effects: readonly import("../orchestration/worker-capabilities/contracts.js").WorkerCapabilityEffect[];
+    }>[];
+    availableSkillWriteOperationIds: readonly string[];
+}>;

package/dist/src/runtime/request/root-capability-catalog.js

@@ -0,0 +1,20 @@
+import { projectWorkerCapabilityCatalogGroups } from "../orchestration/worker-capabilities/index.js";
+import { isSupervisorSkillWriteCapabilityId, projectSupervisorWorkerCapabilityDescriptors, } from "../orchestration/worker-capabilities/supervisor-skill-authority.js";
+import { hasSuperContextContract } from "../context/super-context-policy.js";
+/** Capture both role projections from the same request-session descriptor read. */
+export function captureRootCapabilityCatalog(params) {
+    const descriptors = canCaptureRootCapabilityCatalog(params.authority, params.roleIds)
+        ? params.getDescriptors() : [];
+    const availableWorkerCapabilityCatalog = projectWorkerCapabilityCatalogGroups(projectSupervisorWorkerCapabilityDescriptors({ authority: params.authority, descriptors }));
+    const availableSkillWriteOperationIds = hasSuperContextContract(params.authority, "supervisor")
+        ? descriptors.map(({ capabilityId }) => capabilityId).filter(isSupervisorSkillWriteCapabilityId) : [];
+    return Object.freeze({ availableWorkerCapabilityCatalog,
+        availableSkillWriteOperationIds: Object.freeze(availableSkillWriteOperationIds) });
+}
+function canCaptureRootCapabilityCatalog(authority, roleIds) {
+    if (authority.capabilityAuthorities.includes("root"))
+        return true;
+    if (!roleIds.includes("worker"))
+        return false;
+    return authority.capabilityAuthorities.includes("worker");
+}

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

@@ -1,3 +1,5 @@
+import type { SupervisorSkillWriteSelection } from "../steps/supervisor-skill-authoring/contract.js";
+import type { SkillReadDecision } from "../steps/skill-read-decision.js";
 import type { ModelStep } from "../../shared/model-steps.js";
 import type { ModelWorkPlanUpdate } from "../orchestration/role-calls/work-plan-contracts.js";
 import type { ChatMessage } from "../../model-gateway/types.js";
@@ -16,9 +18,15 @@ export type RootContractCallIdentity = Readonly<{
     depth: number;
     invocationAttempt: number;
 }>;
-type RootContractAction = MemoryRecallDecision | Readonly<{
+type RootContractAction = SkillReadDecision | MemoryRecallDecision | Readonly<{
+    action: "prepare_skill_write";
+    selection: SupervisorSkillWriteSelection;
+    acknowledgement?: string;
+    title?: string;
+}> | Readonly<{
     action: "respond";
     responseRecommendation?: string;
+    responseRecommendationOrigin?: "skill_authoring_no_save";
     directResponse?: RootAuthoredResponse;
     acknowledgement?: string;
     title?: string;
@@ -92,6 +100,7 @@ export type RootContractAdapter<TRequest> = Readonly<{
         includeTitle: boolean;
         allowedRoleIds: readonly RuntimeDelegateRoleId[];
         availableWorkerCapabilityCatalog: readonly WorkerCapabilityCatalogGroup[];
+        availableSkillWriteOperationIds?: readonly string[];
         memoryRecallMessage?: ChatMessage;
         resume?: RoleChildReturnContext;
     }>): Promise<RootContractDecisionOutcome>;
@@ -100,6 +109,7 @@ export type RootContractAdapter<TRequest> = Readonly<{
         callFrame: RoleCallFrame;
         steeringVersion: number;
         responseRecommendation?: string;
+        responseRecommendationOrigin?: "skill_authoring_no_save";
         directResponse?: RootAuthoredResponse;
         call: RootContractCallIdentity;
         toolResults: RequestToolResultsView;

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

@@ -1,4 +1,6 @@
-import { createRootExecutionFreshness } from "./capability-execution-freshness.js";
+import { prepareRootCapabilityBinding, requireRootCallFrame } from "./root-capability-binding.js";
+import { captureRootCapabilityCatalog } from "./root-capability-catalog.js";
+import { prepareSupervisorSkillWrite } from "./supervisor-skill-write-preparation.js";
 import { bindRoleApprovalWait, isRoleApprovalWait, } from "../orchestration/role-executors/approval-continuation.js";
 import { isWorkerCapabilityApprovalWait } from "../orchestration/worker-capabilities/approval-contracts.js";
 import { createEnteredChildInvocation } from "../orchestration/role-executors/child-invocation/entered-child.js";
@@ -9,13 +11,12 @@ 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 { isWorkerCapabilityOperationSupervisionLimitError, } from "../orchestration/worker-capabilities/index.js";
 import { runPolicyDegradedFinalization, projectPolicyDegradedResult, } from "./policy-degraded-finalization.js";
 import { resolveRequestSteeringInbox, } from "./request-steering.js";
 import { traceSupervisorRootAcknowledgementPublished, traceSupervisorRootActivationFailed, traceSupervisorRootActivationStarted, traceSupervisorRootInvocationSuperseded, traceSupervisorRootResponseSuperseded, } from "./supervisor-root-execution-diagnostics.js";
 import { projectSupervisorFinalObservation, } from "./root-observation-handoff.js";
-import { performRootMemoryRecall } from "./root-memory-recall.js";
+import { isRootReferenceDecision, performRootReferenceAction } from "./root-reference-action.js";
 import { applyRootModelWorkPlan } from "./root-plan-update.js";
 import { projectRootMemoryRecallMessage } from "../long-term-memory/recall-context.js";
 import { createPlainRootAuthoredResponse } from "../orchestration/final-response/authoring-contract.js";
@@ -38,7 +39,7 @@ class RootExecutionSession {
     requestSteering;
     resume;
     observationHandoff;
-    availableWorkerCapabilityCatalog;
+    capabilityCatalog;
     acknowledgementPublished = false;
     titlePublished = false;
     constructor(params) {
@@ -162,12 +163,10 @@ class RootExecutionSession {
     }
     async decide(activation, attempt) {
         attempt.failureStage = "project_worker_catalog";
-        this.availableWorkerCapabilityCatalog ??=
-            this.policy.authority.capabilityAuthorities.includes("root") ||
-                (this.policy.roleExecutors.roleIds.includes("worker") &&
-                    this.policy.authority.capabilityAuthorities.includes("worker"))
-                ? projectWorkerCapabilityCatalogGroups(this.request.workerCapabilities.provider.getDescriptors())
-                : Object.freeze([]);
+        this.capabilityCatalog ??= captureRootCapabilityCatalog({
+            authority: this.policy.authority, roleIds: this.policy.roleExecutors.roleIds,
+            getDescriptors: () => this.request.workerCapabilities.provider.getDescriptors(),
+        });
         attempt.failureStage = "decide";
         const decisionToolResults = projectRequestToolResults({
             ledger: this.ledger,
@@ -190,7 +189,7 @@ class RootExecutionSession {
                 !this.titlePublished &&
                 this.request.shouldGenerateSessionTitle,
             allowedRoleIds: this.policy.roleExecutors.roleIds,
-            availableWorkerCapabilityCatalog: this.availableWorkerCapabilityCatalog,
+            ...this.capabilityCatalog,
             ...(this.resume ? { resume: this.resume } : {}),
         });
         const requiresFreshPresentation = this.policy.rootContract.deferRespondPresentation === true;
@@ -239,6 +238,22 @@ class RootExecutionSession {
     }
     async executeDecision(activation, attempt) {
         const { decision } = activation;
+        if (decision.action === "prepare_skill_write") {
+            attempt.failureStage = "apply_root_transition";
+            const prepared = await prepareSupervisorSkillWrite({
+                request: this.request, ledger: this.ledger,
+                activation: { ...activation, decision }, resume: this.resume,
+            });
+            if (!prepared)
+                return CONTINUE_ROOT_EXECUTION;
+            activation = prepared.activation;
+            this.resume = prepared.resume;
+            attempt.head = activation.head;
+            attempt.call = activation.call;
+            return prepared.activation.decision.action === "respond"
+                ? this.completeResponse(activation, prepared.activation.decision, attempt)
+                : this.invokeCapabilities(activation, prepared.activation.decision, attempt);
+        }
         if (decision.workPlan) {
             attempt.failureStage = "apply_root_transition";
             const updated = await applyRootModelWorkPlan({
@@ -255,16 +270,9 @@ class RootExecutionSession {
             attempt.head = updated.head;
             attempt.call = updated.call;
         }
-        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,
-            });
+        if (isRootReferenceDecision(decision)) {
+            attempt.failureStage = decision.action === "recall_memory" ? "recall_memory" : "apply_root_transition";
+            this.resume = await performRootReferenceAction(this.request, this.ledger, { ...activation, decision }, this.resume);
             return CONTINUE_ROOT_EXECUTION;
         }
         if (decision.action === "invoke_role") {
@@ -374,41 +382,11 @@ class RootExecutionSession {
             return CONTINUE_ROOT_EXECUTION;
         }
         attempt.failureStage = "invoke_child";
-        let head = activation.head;
-        let call = activation.call;
-        if (decision.workingDirectory !== undefined) {
-            const established = await this.transactions.establishWorkingDirectory({
-                expectedHead: head,
-                callId: call.callId,
-                invocationAttempt: call.activationCount,
-                workingDirectory: decision.workingDirectory,
-            });
-            if (!established.ok) {
-                throw new Error(`role_call_ledger_rejected:${established.issueCode}`);
-            }
-            head = established.commit.head;
-            attempt.head = head;
-            call = requireRootCallFrame({ head, callId: call.callId });
-            attempt.call = call;
-        }
-        const binding = createRoleCapabilityBinding({
-            requestId: this.request.requestId,
-            context: this.request.workerCapabilities.executionContext,
-            call,
-            ledger: this.ledger,
-            adapters: this.request.workerCapabilities.provider.getAdapters(),
-            ...(this.request.approvalGate
-                ? { approvalGate: this.request.approvalGate }
-                : {}),
-            ...(this.policy.authority.capabilityAuthorities.includes("root")
-                ? {
-                    executionFreshness: createRootExecutionFreshness({
-                        requestSteering: this.requestSteering,
-                        steeringVersion: activation.decisionSteeringVersion,
-                    }),
-                }
-                : {}),
+        const { head, call, binding } = await prepareRootCapabilityBinding({
+            request: this.request, ledger: this.ledger, activation, decision,
         });
+        attempt.head = head;
+        attempt.call = call;
         try {
             const execution = decision.action === "invoke_capability"
                 ? await binding.execute({
@@ -492,6 +470,7 @@ class RootExecutionSession {
             ? createPlainRootAuthoredResponse(decision.response)
             : await this.policy.rootContract.authorResponse(this.request, {
                 responseRecommendation: decision.responseRecommendation,
+                responseRecommendationOrigin: decision.responseRecommendationOrigin,
                 directResponse: decision.directResponse,
                 memoryRecallMessage: projectRootMemoryRecallMessage({
                     head: activation.head,
@@ -586,15 +565,3 @@ function emitSupervisorResumeStatus(request) {
         message: "Processing the delegated result...",
     });
 }
-function requireRootCallFrame(params) {
-    const call = params.head.state.calls.find((candidate) => candidate.callId === params.callId);
-    if (!call ||
-        call.callId !== params.head.state.rootCallId ||
-        call.parentCallId !== null ||
-        call.roleId !== RUNTIME_ROOT_ROLE_ID ||
-        call.depth !== 0 ||
-        call.status !== "active") {
-        throw new Error("supervisor_call_frame_missing");
-    }
-    return call;
-}

package/dist/src/runtime/request/root-reference-action.d.ts

@@ -0,0 +1,15 @@
+import type { RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleChildReturnContext } from "../orchestration/role-calls/index.js";
+import type { RootContractDecision } from "./root-contract.js";
+import type { RequestExecutionScope } from "./execution-scope.js";
+type RootReferenceDecision = Extract<RootContractDecision, {
+    action: "recall_memory" | "list_skills" | "read_skills";
+}>;
+export declare function isRootReferenceDecision(decision: RootContractDecision): decision is RootReferenceDecision;
+/** Core reference actions use the same root loop without opening a child. */
+export declare function performRootReferenceAction(request: RequestExecutionScope, ledger: RoleCallLedger, activation: {
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    decisionSteeringVersion: number;
+    decision: RootReferenceDecision;
+}, resume: RoleChildReturnContext | undefined): Promise<RoleChildReturnContext | undefined>;
+export {};

package/dist/src/runtime/request/root-reference-action.js

@@ -0,0 +1,48 @@
+import { projectStoredCompletedRoleChild } from "../orchestration/role-calls/child-return.js";
+import { performRootMemoryRecall } from "./root-memory-recall.js";
+import { performRootSkillRead } from "./root-skill-read.js";
+export function isRootReferenceDecision(decision) {
+    return ["recall_memory", "list_skills", "read_skills"].includes(decision.action);
+}
+/** Core reference actions use the same root loop without opening a child. */
+export async function performRootReferenceAction(request, ledger, activation, resume) {
+    const params = {
+        request,
+        ledger,
+        ...activation,
+        steeringVersion: activation.decisionSteeringVersion,
+        resume,
+    };
+    if (params.decision.action === "recall_memory") {
+        await performRootMemoryRecall({ ...params, query: params.decision.query });
+        return projectResumeAfterRootReferenceAction(params.ledger.current(), params.resume);
+    }
+    await performRootSkillRead({ ...params, decision: params.decision });
+    return projectResumeAfterRootReferenceAction(params.ledger.current(), params.resume);
+}
+/** A reference read advances the root activation without changing its completed children. */
+function projectResumeAfterRootReferenceAction(head, resume) {
+    if (!resume)
+        return undefined;
+    const call = head.state.calls.find(({ callId }) => callId === resume.callerCallId);
+    if (!call ||
+        call.callId !== head.state.rootCallId ||
+        call.status !== "active")
+        throw new Error("skill_read_resume_caller_invalid");
+    const completedChildren = call.childCallIds.flatMap((childCallId) => {
+        const child = head.state.calls.find(({ callId }) => callId === childCallId);
+        if (child?.status !== "completed")
+            return [];
+        return [
+            projectStoredCompletedRoleChild(head.state, { callerCallId: call.callId, childCallId }, head.policy),
+        ];
+    });
+    if (!completedChildren.some((child) => child.childCallId === resume.returnedChildCallId &&
+        child.resultRef === resume.returnedResultRef))
+        throw new Error("skill_read_resume_result_invalid");
+    return Object.freeze({
+        ...resume,
+        invocationAttempt: call.activationCount,
+        completedChildren: Object.freeze(completedChildren),
+    });
+}

package/dist/src/runtime/request/root-skill-read-admission.d.ts

@@ -0,0 +1,4 @@
+import type { RoleCallLedgerHead } from "../orchestration/role-calls/index.js";
+import type { SkillReadDecision } from "../steps/skill-read-decision.js";
+/** Enforce request-local read identity before any document lookup or ledger commit. */
+export declare function assertRootSkillReadAdmission(head: RoleCallLedgerHead, decision: SkillReadDecision): void;

package/dist/src/runtime/request/root-skill-read-admission.js

@@ -0,0 +1,14 @@
+import { collectSuccessfulSkillReadIdentities } from "../steps/supervisor-decision/skill-read-state.js";
+/** Enforce request-local read identity before any document lookup or ledger commit. */
+export function assertRootSkillReadAdmission(head, decision) {
+    if (decision.action !== "read_skills")
+        return;
+    const hasRepeatedRootSkillReadIds = new Set(decision.skillIds).size !== decision.skillIds.length;
+    if (hasRepeatedRootSkillReadIds)
+        throw new Error("skill_read_duplicate_ids");
+    const completedIds = new Set(collectSuccessfulSkillReadIdentities(head.state.skillReads ?? [])
+        .map(({ skillId }) => skillId));
+    const repeatsCompletedRootSkillRead = decision.skillIds.some((skillId) => completedIds.has(skillId));
+    if (repeatsCompletedRootSkillRead)
+        throw new Error("skill_read_already_completed");
+}

package/dist/src/runtime/request/root-skill-read.d.ts

@@ -0,0 +1,13 @@
+import type { RoleCallFrame, RoleCallLedger, RoleCallLedgerHead } from "../orchestration/role-calls/index.js";
+import type { SkillReadDecision } from "../steps/skill-read-decision.js";
+import type { RequestExecutionScope } from "./execution-scope.js";
+/** Read synchronously, then commit the exact snapshot and the next root activation together. */
+export declare function performRootSkillRead(params: {
+    request: RequestExecutionScope;
+    ledger: RoleCallLedger;
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    steeringVersion: number;
+    decision: SkillReadDecision;
+}): Promise<void>;
+export declare function canRootReadSkills(request: RequestExecutionScope, head: RoleCallLedgerHead, call: RoleCallFrame): boolean;

package/dist/src/runtime/request/root-skill-read.js

@@ -0,0 +1,110 @@
+import { findRoleActivationReservationIssue, resolveRoleActivationBudget, } from "../orchestration/role-calls/activation-budget.js";
+import { hasSuperContextContract } from "../context/super-context-policy.js";
+import { KnowledgeSkillError } from "../knowledge-skills/personal-contracts.js";
+import { emitRuntimeStatus } from "../events/runtime-status.js";
+import { resolveRequestSteeringInbox } from "./request-steering.js";
+import { assertRootSkillReadAdmission } from "./root-skill-read-admission.js";
+/** Read synchronously, then commit the exact snapshot and the next root activation together. */
+export async function performRootSkillRead(params) {
+    const { request, head, call } = params;
+    request.abortSignal.throwIfAborted();
+    const steering = resolveRequestSteeringInbox(request.requestSteering);
+    if (!steering.isCurrent(params.steeringVersion))
+        return;
+    if (!hasSuperContextContract(head.policy.authority, "supervisor"))
+        throw new Error("skill_read_policy_invalid");
+    if (!request.knowledgeSkillStore)
+        throw new Error("skill_read_unavailable");
+    const identity = {
+        authority: "runtime",
+        type: "record_skill_read",
+        callId: call.callId,
+        invocationAttempt: call.activationCount,
+        steeringVersion: params.steeringVersion,
+    };
+    const reservation = {
+        ...identity,
+        ...failedRead(params.decision, "knowledge_skill_unavailable"),
+    };
+    const exhausted = findRoleActivationReservationIssue(head.state, head.policy, reservation);
+    if (exhausted)
+        throw new Error(`role_call_ledger_rejected:${exhausted.code}`);
+    assertRootSkillReadAdmission(head, params.decision);
+    const payload = readStore(request.knowledgeSkillStore, params.decision);
+    request.abortSignal.throwIfAborted();
+    if (!steering.isCurrent(params.steeringVersion))
+        return;
+    const committed = await params.ledger.apply({
+        expectedHead: head,
+        command: { ...identity, ...payload },
+    });
+    if (!committed.ok)
+        throw new Error(`role_call_ledger_rejected:${committed.code}`);
+    emitRuntimeStatus(request, {
+        stage: "supervisor",
+        phase: "skills",
+        message: readStatus(payload),
+    });
+}
+function readStore(store, decision) {
+    try {
+        if (decision.action === "list_skills")
+            return {
+                operation: "list_skills",
+                selectors: [],
+                result: {
+                    outcome: "completed",
+                    skills: store.list().map((skill) => ({ ...skill })),
+                },
+            };
+        const skills = [];
+        for (const skillId of decision.skillIds) {
+            const skill = store.read(skillId);
+            if (!isExactRootSkillDocument(skill, skillId))
+                return failedRead(decision, "knowledge_skill_not_found");
+            skills.push({ ...skill });
+        }
+        return {
+            operation: "read_skills",
+            selectors: [...decision.skillIds],
+            result: {
+                outcome: "completed",
+                skills,
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof KnowledgeSkillError)
+            return failedRead(decision, error.code);
+        throw error;
+    }
+}
+function isExactRootSkillDocument(skill, skillId) {
+    return skill?.skillId === skillId;
+}
+function failedRead(decision, errorCode) {
+    const result = { outcome: "failed", errorCode, skills: [] };
+    if (decision.action === "list_skills")
+        return { operation: "list_skills", selectors: [], result };
+    return {
+        operation: "read_skills",
+        selectors: [...decision.skillIds],
+        result,
+    };
+}
+function readStatus(payload) {
+    if (payload.result.outcome === "failed")
+        return `Skill lookup failed: ${payload.result.errorCode}`;
+    if (payload.operation === "list_skills")
+        return `Listed ${payload.result.skills.length} Skills`;
+    return `Read Skills: ${payload.result.skills.map(({ name }) => name).join(", ")}`;
+}
+export function canRootReadSkills(request, head, call) {
+    if (!request.knowledgeSkillStore)
+        return false;
+    if (!hasSuperContextContract(head.policy.authority, "supervisor"))
+        return false;
+    return (call.activationCount <
+        resolveRoleActivationBudget(head.state, head.policy)
+            .maximumAcceptedActivationsPerCall);
+}

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

@@ -8,6 +8,8 @@ import { createRoleApprovalContinuation, validateRequestApprovalContinuation, }
 import { createRoleCallLedger, resolveRoleCallTransactions, } from "../orchestration/role-calls/index.js";
 import { traceDebug } from "../observability/debug-logger.js";
 import { attachRequestPlannerRoleCallEvents } from "./role-call-planner-events.js";
+import { attachRequestRoleDelegationEvents } from "./role-call-delegation-events.js";
+import { attachRequestRoleReturnEvents } from "./role-call-return-events.js";
 import { runRootExecutionKernel } from "./root-execution-kernel.js";
 import { persistSettledSessionArtifactPaths, } from "./session-artifact-path-persistence.js";
 export async function runRequestRunner(request, options = {}) {
@@ -40,6 +42,14 @@ export async function runRequestRunner(request, options = {}) {
         ledger,
         onEvent: request.onEvent,
     });
+    attachRequestRoleDelegationEvents({
+        ledger,
+        onEvent: request.onEvent,
+    });
+    attachRequestRoleReturnEvents({
+        ledger,
+        onEvent: request.onEvent,
+    });
     let result;
     try {
         let continuation;