@abot-ai/runtime 1.8.0 → 1.9.0

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

@@ -1,3 +1,5 @@
+import type { KnowledgeSkillStore } from "../knowledge-skills/store.js";
+import type { AvailableSkillsSource } from "../knowledge-skills/available-skills.js";
 import { type RuntimeFilesystemScope } from "../context/runtime-filesystem-scope.js";
 import { type SuperFailureFinalization } from "./super-failure-explanation.js";
 import type { ToolAvailabilitySource } from "../capabilities/tool-availability.js";
@@ -5,7 +7,7 @@ import type { WorkerCapabilityAdapterProvider } from "../orchestration/worker-ca
 import type { AcceptedRequestInput, BoundRequestModelInvocationContext, RequestSessionSnapshot, RequestExecutionSeed, RequestIdentity, RequestLifecycleRuntime, RequestModelInvocationView, RequestModelRuntime, RequestMemoryRuntime, RequestPresentation } from "./contracts.js";
 import type { CompiledExecutionPolicy } from "./root-contract.js";
 /** Request fields required while the request-bound capability catalog is built. */
-export type RequestCapabilityCompositionView = BoundRequestModelInvocationContext & Readonly<Pick<RequestExecutionSeed, "sessionId" | "prompt" | "historyMessages" | "toolPermissionMode" | "toolApprovalController" | "effectPersistence" | "onEvent" | "contextCompactionStore">>;
+export type RequestCapabilityCompositionView = BoundRequestModelInvocationContext & Readonly<Pick<RequestExecutionSeed, "sessionId" | "prompt" | "historyMessages" | "sessionMemory" | "attachments" | "toolPermissionMode" | "toolApprovalController" | "effectPersistence" | "onEvent" | "contextCompactionStore">>;
 /**
  * Stable request-owned context delivered to capability adapters.
  * Passive session artifact paths and request containers are excluded.
@@ -13,7 +15,7 @@ export type RequestCapabilityCompositionView = BoundRequestModelInvocationContex
 export type RequestCapabilityExecutionView = Readonly<Omit<RequestExecutionSeed, "sessionArtifactPaths" | "sessionMemory" | "longTermMemory" | "memoryRecallLimit" | "scheduledExecution">> & BoundRequestModelInvocationContext;
 export type RequestWorkerCapabilities = Readonly<{
     filesystemScope?: RuntimeFilesystemScope;
-    provider: WorkerCapabilityAdapterProvider<RequestCapabilityExecutionView> & Partial<ToolAvailabilitySource>;
+    provider: WorkerCapabilityAdapterProvider<RequestCapabilityExecutionView> & Partial<ToolAvailabilitySource & AvailableSkillsSource>;
     executionContext: RequestCapabilityExecutionView;
 }>;
 export type RequestExecutionPolicyFacet = Readonly<{
@@ -35,12 +37,14 @@ export type RequestExecutionScope = RequestExecutionSeed & BoundRequestModelInvo
     capabilities: RequestWorkerCapabilities;
     superFailureFinalization?: SuperFailureFinalization;
     workerCapabilities: RequestWorkerCapabilities;
+    knowledgeSkillStore?: KnowledgeSkillStore;
 }>;
 export type CompiledRequestExecutionPolicy = RequestExecutionScope["executionPolicy"];
 export type RequestWorkerCapabilityProviderSource = Pick<RequestExecutionScope, "workerCapabilities">;
 export type RequestWorkerCapabilityCatalog = Pick<WorkerCapabilityAdapterProvider<RequestCapabilityExecutionView>, "getDescriptors" | "getExecutionGuidance">;
 export declare function createRequestExecutionScope(input: Readonly<{
     seed: RequestExecutionSeed;
+    knowledgeSkillStore?: KnowledgeSkillStore;
     requestWorkingDirectory?: string;
     executionPolicy: CompiledRequestExecutionPolicy;
     superFailureFinalization?: SuperFailureFinalization;

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

@@ -1,3 +1,6 @@
+import { matchesToolSelectionId } from "../../shared/tool-selection.js";
+import { CORE_TOOL_CONTRACTS } from "../capabilities/core-tool-contracts.js";
+import { captureModelPluginConfig } from "../config/model-plugin-config.js";
 import { captureRuntimeFilesystemScope, } from "../context/runtime-filesystem-scope.js";
 import { createSuperFailureFinalization, } from "./super-failure-explanation.js";
 import { RequestModelStepInvoker } from "../model/invoke-step.js";
@@ -22,6 +25,9 @@ export function createRequestExecutionScope(input) {
         modelInvocation,
         modelSteps,
         capabilities,
+        ...(input.knowledgeSkillStore && !isSkillStoreDeniedForModel(input.seed)
+            ? { knowledgeSkillStore: input.knowledgeSkillStore }
+            : {}),
         superFailureFinalization: input.superFailureFinalization ??
             createSuperFailureFinalization({
                 request: input.seed,
@@ -44,3 +50,8 @@ function createRequestExecutionPolicyFacet(selection, executionPolicy) {
         executionPolicy,
     });
 }
+/** Direct core reads retain the same captured model restriction as abot_skills. */
+function isSkillStoreDeniedForModel(seed) {
+    const deniedSelectors = captureModelPluginConfig(seed.executionPolicySelection?.plugins)?.deny ?? [];
+    return deniedSelectors.some((selector) => matchesToolSelectionId("", CORE_TOOL_CONTRACTS.skills.name, selector));
+}

package/dist/src/runtime/request/payload-settled-evidence.d.ts

@@ -0,0 +1,11 @@
+import { type SemanticCompactionSource } from "../context/semantic-compaction/contracts.js";
+import type { projectExecutionPayloadCompactedEvidence } from "./execution-payload-compacted-evidence.js";
+type PayloadSettledResult = ReturnType<typeof projectExecutionPayloadCompactedEvidence>["results"][number];
+/** Keep the adapter envelope exact and the pre-projection compaction identity stable. */
+export declare function projectPayloadSettledEvidence(results: readonly PayloadSettledResult[]): Readonly<{
+    results: readonly PayloadSettledResult[];
+    resultSourceOverrides: readonly SemanticCompactionSource[];
+    deduplicatedReferenceDataCount: number;
+    deduplicatedReferenceDataChars: number;
+}>;
+export {};

package/dist/src/runtime/request/payload-settled-evidence.js

@@ -0,0 +1,29 @@
+import { findExactEvidencePath } from "../context/exact-evidence-match.js";
+import { createSemanticCompactionSha256Fingerprint, } from "../context/semantic-compaction/contracts.js";
+/** Keep the adapter envelope exact and the pre-projection compaction identity stable. */
+export function projectPayloadSettledEvidence(results) {
+    const resultSourceOverrides = [];
+    let deduplicatedReferenceDataChars = 0;
+    const projected = results.map((result) => {
+        if (!("adapterResult" in result) || !result.referenceData)
+            return result;
+        const representedAt = findExactEvidencePath(result.adapterResult, result.referenceData);
+        if (!representedAt)
+            return result;
+        deduplicatedReferenceDataChars += result.referenceData.length;
+        const content = JSON.stringify(result);
+        resultSourceOverrides.push(Object.freeze({
+            sourceRef: `payload-result:${result.executionId}`,
+            sourceFingerprint: createSemanticCompactionSha256Fingerprint(content),
+            content,
+        }));
+        const { referenceData: _referenceData, ...singleCopyResult } = result;
+        return Object.freeze(singleCopyResult);
+    });
+    return Object.freeze({
+        results: Object.freeze(projected),
+        resultSourceOverrides: Object.freeze(resultSourceOverrides),
+        deduplicatedReferenceDataCount: resultSourceOverrides.length,
+        deduplicatedReferenceDataChars,
+    });
+}

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

@@ -211,6 +211,7 @@ export async function prepareRequestExecution(params) {
     resources.assertRestoredStateClaimed();
     const request = createRequestExecutionScope({
         seed,
+        ...(options.knowledgeSkillStore ? { knowledgeSkillStore: options.knowledgeSkillStore } : {}),
         requestWorkingDirectory,
         executionPolicy,
         ...(superFailureFinalization ? { superFailureFinalization } : {}),
@@ -227,6 +228,7 @@ export async function prepareRequestExecution(params) {
                 ? { runtimeConfig: options.runtimeConfig }
                 : {}),
             ...(toolRegistry ? { toolRegistryOverride: toolRegistry } : {}),
+            knowledgeSkillStore: options.knowledgeSkillStore,
         }),
     });
     return {

package/dist/src/runtime/request/role-call-delegation-events.d.ts

@@ -0,0 +1,19 @@
+import type { RoleCallLedger, RoleCallLedgerCommit } from "../orchestration/role-calls/index.js";
+import { type RuntimeDelegateRoleId } from "../orchestration/roles.js";
+export type RequestRoleDelegationEvent = Readonly<{
+    name: "role.delegated";
+    payload: Readonly<{
+        callerCallId: string;
+        callerRole: "supervisor";
+        childCallId: string;
+        childRole: RuntimeDelegateRoleId;
+        objective: string;
+    }>;
+}>;
+/** Projects the accepted assignment without changing role state or active stage. */
+export declare function projectRequestRoleDelegationCommit(commit: RoleCallLedgerCommit): RequestRoleDelegationEvent | undefined;
+/** Uses the existing synchronous commit boundary, including emission faults. */
+export declare function attachRequestRoleDelegationEvents(params: Readonly<{
+    ledger: RoleCallLedger;
+    onEvent(name: string, payload: Record<string, unknown>): void;
+}>): void;

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

@@ -0,0 +1,52 @@
+import { consumeUnexpectedThenable } from "../orchestration/synchronous-boundary.js";
+import { isRuntimeDelegateRoleId, } from "../orchestration/roles.js";
+/** Projects the accepted assignment without changing role state or active stage. */
+export function projectRequestRoleDelegationCommit(commit) {
+    if (!isDirectSupervisorChildOpen(commit))
+        return undefined;
+    const child = commit.head.state.calls.find((call) => call.callId === commit.effect.childCallId);
+    if (!isDirectSupervisorChild(child, commit.effect.callerCallId))
+        return undefined;
+    return Object.freeze({
+        name: "role.delegated",
+        payload: Object.freeze({
+            callerCallId: commit.effect.callerCallId,
+            callerRole: "supervisor",
+            childCallId: child.callId,
+            childRole: child.roleId,
+            objective: child.objective,
+        }),
+    });
+}
+/** Uses the existing synchronous commit boundary, including emission faults. */
+export function attachRequestRoleDelegationEvents(params) {
+    params.ledger.commits.subscribe((commit) => {
+        const event = projectRequestRoleDelegationCommit(commit);
+        if (!event)
+            return;
+        const emitted = Reflect.apply(params.onEvent, undefined, [
+            event.name,
+            event.payload,
+        ]);
+        if (consumeUnexpectedThenable(emitted))
+            throw new TypeError("Request delegation event sink must be synchronous.");
+    });
+}
+function isDirectSupervisorChildOpen(commit) {
+    if (commit.effect.type !== "child_opened")
+        return false;
+    if (commit.head.policy.authority.rootContractId !== "supervisor")
+        return false;
+    return commit.effect.callerCallId === commit.head.state.rootCallId;
+}
+function isDirectSupervisorChild(child, callerCallId) {
+    if (!child)
+        return false;
+    if (child.parentCallId !== callerCallId)
+        return false;
+    if (child.depth !== 1)
+        return false;
+    if (!isRuntimeDelegateRoleId(child.roleId))
+        return false;
+    return typeof child.objective === "string";
+}

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

@@ -0,0 +1,19 @@
+import { type RoleCallLedger, type RoleCallLedgerCommit } from "../orchestration/role-calls/index.js";
+export type RequestRoleReturnEvent = Readonly<{
+    name: "role.returned";
+    payload: Readonly<{
+        callerCallId: string;
+        callerRole: "supervisor";
+        childCallId: string;
+        childRole: "planner";
+        outcome: "completed" | "failed";
+        summary: string;
+    }>;
+}>;
+/** Projects the stored Planner result without changing role state or active stage. */
+export declare function projectRequestRoleReturnCommit(commit: RoleCallLedgerCommit): RequestRoleReturnEvent | undefined;
+/** Uses the existing synchronous commit boundary, including emission faults. */
+export declare function attachRequestRoleReturnEvents(params: Readonly<{
+    ledger: RoleCallLedger;
+    onEvent(name: string, payload: Record<string, unknown>): void;
+}>): void;

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,16 @@ 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;
 }> | Readonly<{
@@ -91,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>;
@@ -99,6 +109,8 @@ export type RootContractAdapter<TRequest> = Readonly<{
         callFrame: RoleCallFrame;
         steeringVersion: number;
         responseRecommendation?: string;
+        responseRecommendationOrigin?: "skill_authoring_no_save";
+        directResponse?: RootAuthoredResponse;
         call: RootContractCallIdentity;
         toolResults: RequestToolResultsView;
         resume?: RoleChildReturnContext;

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,8 @@ 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,
                     callId: activation.call.callId,
@@ -585,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 {};