@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/runtime/orchestration/role-executors/activation/loop.js

@@ -1,9 +1,12 @@
+import { isRoleApprovalWait, validateRoleApprovalWait, } from "../approval-continuation.js";
+import { createEnteredChildInvocation } from "../child-invocation/entered-child.js";
 import { isRuntimeDelegateRoleId } from "../../roles.js";
 import { traceRoleExecutorCompleted, traceRoleExecutorFailed, traceRoleExecutorInitialStateRejected, traceRoleExecutorResolved, traceRoleExecutorResultRejected, traceRoleExecutorStarted, traceRoleExecutorStateRejected, traceRoleExecutorUnavailable, } from "../diagnostics.js";
 import { requireResumedCallerCall } from "../child-invocation/state-validation.js";
 import { createAttemptDiagnostic, createDiagnostic, } from "../shared/diagnostic-context.js";
 import { readLedgerOrReject, stateError, } from "../shared/runtime-invariants.js";
 import { continueRoleThroughCapability } from "./capability-continuation.js";
+import { executeRoleWithModelOutputFailure } from "./model-output-failure.js";
 import { normalizeRoleExecutorActivationResult } from "./result-normalization.js";
 import { resolveCurrentCall } from "./state-validation.js";
 export class RoleActivationLoop {
@@ -13,8 +16,12 @@ export class RoleActivationLoop {
     constructor(params) {
         this.params = params;
         this.expectedCall = params.input.call;
+        this.continuationReference = params.input.continuationState?.capability;
     }
     async run() {
+        const continued = await this.continueEnteredChild();
+        if (continued)
+            return continued;
         const { executor, call } = this.resolveInitialActivation();
         this.expectedCall = call;
         for (let turnCount = 1;; turnCount += 1) {
@@ -24,6 +31,28 @@ export class RoleActivationLoop {
                 return terminal;
         }
     }
+    async continueEnteredChild() {
+        const continuation = this.params.input.continuationState;
+        if (!continuation?.callers.length)
+            return undefined;
+        const previousCall = continuation.callers[0].callerCall;
+        if (previousCall.callId !== this.expectedCall.callId)
+            throw stateError("approval_caller_cursor_mismatch");
+        const child = await this.params.invokeChild(createEnteredChildInvocation({
+            requestId: this.params.input.requestId,
+            context: this.params.input.context,
+            ledger: this.params.input.ledger,
+            continuation,
+        }));
+        if (isRoleApprovalWait(child))
+            return child;
+        this.expectedCall = requireResumedCallerCall(child.returnCommit, previousCall);
+        this.continuationReference = Object.freeze({
+            kind: "role_child",
+            commit: child.returnCommit,
+        });
+        return undefined;
+    }
     resolveInitialActivation() {
         const { input, registeredRoleIds, executorByRoleId } = this.params;
         const attemptedRoleId = isRuntimeDelegateRoleId(input.call.roleId)
@@ -55,7 +84,7 @@ export class RoleActivationLoop {
         const initialAuthority = resolveCurrentCall({
             head: initialHead,
             requestId: input.requestId,
-            expectedCall: input.call,
+            expectedCall: this.expectedCall,
         });
         if (!initialAuthority.ok) {
             traceRoleExecutorInitialStateRejected(initialAttemptDiagnostic, initialAuthority.issueCode);
@@ -115,7 +144,7 @@ export class RoleActivationLoop {
             turnCount,
         });
         try {
-            const result = normalizeRoleExecutorActivationResult(await executor.execute({
+            const result = normalizeRoleExecutorActivationResult(await executeRoleWithModelOutputFailure(executor, {
                 context: input.context,
                 call: activation.call,
                 ledger: input.ledger,
@@ -123,7 +152,7 @@ export class RoleActivationLoop {
                 ...(this.continuationReference
                     ? { continuation: this.continuationReference }
                     : {}),
-            }), activation.before.policy.limits.maxResultChars, activation.before.policy.limits.maxObjectiveChars);
+            }, activation.before.policy.limits.maxResultChars, input.requestId), activation.before.policy.limits.maxObjectiveChars);
             if (!result.ok) {
                 traceRoleExecutorResultRejected(activation.diagnostic, result.issueCode);
                 throw new Error("role_executor_result_invalid:" +
@@ -131,12 +160,15 @@ export class RoleActivationLoop {
                     ":" +
                     result.issueCode);
             }
+            if (isRoleApprovalWait(result.value)) {
+                validateRoleApprovalWait(input.ledger, activation.call, result.value);
+                return result.value;
+            }
             if (result.value.kind === "terminal") {
                 return this.completeTerminal(activation, result.value, turnCount);
             }
             if (result.value.kind === "invoke_role") {
-                await this.continueThroughChild(activation, result.value, turnCount);
-                return undefined;
+                return this.continueThroughChild(activation, result.value, turnCount);
             }
             const continued = continueRoleThroughCapability({
                 ledger: input.ledger,
@@ -178,6 +210,7 @@ export class RoleActivationLoop {
     async continueThroughChild(activation, result, turnCount) {
         const { input } = this.params;
         const child = await this.params.invokeChild({
+            allowApprovalWait: input.allowApprovalWait,
             requestId: input.requestId,
             context: input.context,
             callerCall: activation.call,
@@ -194,6 +227,8 @@ export class RoleActivationLoop {
             ...(result.plannerPlan ? { plannerPlan: result.plannerPlan } : {}),
             turnCount,
         });
+        if (isRoleApprovalWait(child))
+            return child;
         const continuationReference = Object.freeze({
             kind: "role_child",
             commit: child.returnCommit,

package/dist/src/runtime/orchestration/role-executors/activation/model-output-failure.d.ts

@@ -0,0 +1,3 @@
+import type { RoleExecutor, RoleExecutorActivationResult, RoleExecutorInput } from "../contracts.js";
+/** Contains recognized model-output failure or step timeout in the current call. */
+export declare function executeRoleWithModelOutputFailure<TContext, TValue>(executor: RoleExecutor<TContext, TValue>, input: RoleExecutorInput<TContext>, maxSummaryLength: number, requestId: string): Promise<RoleExecutorActivationResult<TValue>>;

package/dist/src/runtime/orchestration/role-executors/activation/model-output-failure.js

@@ -0,0 +1,98 @@
+import { resolveModelOutputFailure, } from "../../../model/invalid-output-failure.js";
+import { ModelOutputIncompleteError } from "../../../model/provider-completion.js";
+import { ModelStepTimeoutError } from "../../../steps/model-step-timeout.js";
+import { traceDebug } from "../../../observability/debug-logger.js";
+/** Contains recognized model-output failure or step timeout in the current call. */
+export async function executeRoleWithModelOutputFailure(executor, input, maxSummaryLength, requestId) {
+    try {
+        return await executor.execute(input);
+    }
+    catch (error) {
+        const failure = resolveChildModelOutputFailure(error);
+        if (!failure)
+            throw error;
+        if (!isModelOutputFailureOwnedByRole(failure, input.call.roleId)) {
+            throw error;
+        }
+        traceDebug("runtime.role_executors", "executor.invalid_output.returning", {
+            requestId,
+            callId: input.call.callId,
+            parentCallId: input.call.parentCallId,
+            roleId: input.call.roleId,
+            disposition: "return_failed_child",
+            ...failure,
+        });
+        return Object.freeze({
+            kind: "terminal",
+            outcome: "failed",
+            summary: buildModelOutputFailureSummary(failure, input, maxSummaryLength),
+        });
+    }
+}
+function resolveChildModelOutputFailure(error) {
+    if (error instanceof ModelStepTimeoutError) {
+        return Object.freeze({
+            code: error.code,
+            modelStep: error.modelStep,
+            validationStage: error.stage,
+            issues: [],
+        });
+    }
+    if (!(error instanceof ModelOutputIncompleteError)) {
+        return resolveModelOutputFailure(error);
+    }
+    if (!error.modelStep)
+        return undefined;
+    return Object.freeze({
+        code: error.code,
+        modelStep: error.modelStep,
+        validationStage: error.stage,
+        issues: [],
+    });
+}
+function isModelOutputFailureOwnedByRole(failure, roleId) {
+    switch (failure.modelStep) {
+        case "planner.graph":
+        case "planner.decision":
+            return roleId === "planner";
+        case "worker.decision":
+        case "worker.result":
+        case "capability.controls":
+            return roleId === "worker";
+        case "auditor.decision":
+        case "reviewer.decision":
+            return roleId === "reviewer";
+        case "context.compact":
+            return isDelegatedModelOutputRole(roleId);
+        default:
+            return false;
+    }
+}
+function isDelegatedModelOutputRole(roleId) {
+    if (roleId === "planner")
+        return true;
+    if (roleId === "worker")
+        return true;
+    return roleId === "reviewer";
+}
+function buildModelOutputFailureSummary(failure, input, maxSummaryLength) {
+    const summary = JSON.stringify({
+        kind: "runtime_role_model_output_failure_v1",
+        authority: "runtime_validation",
+        presenceEffect: "passive_failure_not_work_or_review_evidence",
+        callId: input.call.callId,
+        parentCallId: input.call.parentCallId,
+        roleId: input.call.roleId,
+        reason: failure.code,
+        modelStep: failure.modelStep,
+        validationStage: failure.validationStage,
+    });
+    if (fitsModelOutputFailureSummary(summary, maxSummaryLength))
+        return summary;
+    // The canonical result still carries failure and exact caller binding when
+    // a legal custom result budget is too small for the diagnostic capsule.
+    return "Invalid model output.".slice(0, maxSummaryLength);
+}
+function fitsModelOutputFailureSummary(summary, maxSummaryLength) {
+    return summary.length <= maxSummaryLength;
+}

package/dist/src/runtime/orchestration/role-executors/activation/result-normalization.d.ts

@@ -1,5 +1,5 @@
 import type { RoleExecutorActivationResult } from "../contracts.js";
-export declare function normalizeRoleExecutorActivationResult<TValue>(input: RoleExecutorActivationResult<TValue>, maxSummaryLength: number, maxObjectiveLength: number): Readonly<{
+export declare function normalizeRoleExecutorActivationResult<TValue>(input: RoleExecutorActivationResult<TValue>, maxObjectiveLength: number): Readonly<{
     ok: true;
     value: RoleExecutorActivationResult<TValue>;
 }> | Readonly<{

package/dist/src/runtime/orchestration/role-executors/activation/result-normalization.js

@@ -1,9 +1,12 @@
-import { isRoleCallWorkingDirectoryRoleId, normalizeRoleCallWorkingDirectory, normalizeRoleCallResultReceipt, parseRoleCallPlanBinding, parseRoleCallWorkerCapabilityScope, } from "../../role-calls/index.js";
+import { isRoleCallWorkingDirectoryRoleId, isRoleCallResultText, normalizeRoleCallWorkingDirectory, normalizeRoleCallResultReceipt, parseRoleCallPlanBinding, parseRoleCallWorkerCapabilityScope, } from "../../role-calls/index.js";
 import { isRuntimeDelegateRoleId } from "../../roles.js";
-export function normalizeRoleExecutorActivationResult(input, maxSummaryLength, maxObjectiveLength) {
+import { isRoleApprovalWait } from "../approval-continuation.js";
+export function normalizeRoleExecutorActivationResult(input, maxObjectiveLength) {
     if (!isPlainRecord(input)) {
         return { ok: false, issueCode: "result_not_object" };
     }
+    if (isRoleApprovalWait(input))
+        return { ok: true, value: input };
     if (input.kind === "terminal") {
         const receipt = normalizeRoleCallResultReceipt(input.receipt);
         if (!hasExactKeys(input, ["kind", "outcome", "summary"], ["receipt", "value"]) ||
@@ -11,9 +14,7 @@ export function normalizeRoleExecutorActivationResult(input, maxSummaryLength, m
             receipt === null) {
             return { ok: false, issueCode: "terminal_shape_invalid" };
         }
-        if (typeof input.summary !== "string" ||
-            input.summary.trim().length === 0 ||
-            input.summary.length > maxSummaryLength) {
+        if (!isRoleCallResultText(input.summary)) {
             return { ok: false, issueCode: "summary_invalid" };
         }
         return {

package/dist/src/runtime/orchestration/role-executors/approval-continuation.d.ts

@@ -0,0 +1,20 @@
+import type { RoleCallFrame, RoleCallLedger } from "../role-calls/index.js";
+import type { WorkerCapabilityApprovalWait } from "../worker-capabilities/approval-contracts.js";
+import type { RoleCapabilityBatchExecutionContinuationReference, RoleCapabilityExecutionContinuationReference } from "./contracts.js";
+/** The already-open child boundary. It carries no commit or writer authority. */
+export type EnteredChildCursor = Readonly<{
+    callerCall: RoleCallFrame;
+    childCallId: string;
+    planItemIds?: readonly string[];
+    turnCount: number;
+}>;
+export type RoleApprovalWait = WorkerCapabilityApprovalWait & Readonly<{
+    callers: readonly EnteredChildCursor[];
+}>;
+export type RoleApprovalContinuation = Readonly<{
+    callers: readonly EnteredChildCursor[];
+    capability: RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference;
+}>;
+export declare function isRoleApprovalWait(value: unknown): value is RoleApprovalWait;
+export declare function bindRoleApprovalWait(wait: WorkerCapabilityApprovalWait): RoleApprovalWait;
+export declare function validateRoleApprovalWait(ledger: RoleCallLedger, call: RoleCallFrame, wait: RoleApprovalWait): void;

package/dist/src/runtime/orchestration/role-executors/approval-continuation.js

@@ -0,0 +1,34 @@
+export function isRoleApprovalWait(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("kind" in value) || value.kind !== "awaiting_approval")
+        return false;
+    return "callers" in value && Array.isArray(value.callers);
+}
+export function bindRoleApprovalWait(wait) {
+    return Object.freeze({ ...wait, callers: Object.freeze([]) });
+}
+export function validateRoleApprovalWait(ledger, call, wait) {
+    const head = ledger.current();
+    if (wait.group.requestId !== head.state.requestId)
+        throw new Error("role_approval_request_mismatch");
+    if (wait.group.callId !== call.callId)
+        throw new Error("role_approval_call_mismatch");
+    if (wait.group.invocationAttempt !== call.activationCount)
+        throw new Error("role_approval_activation_mismatch");
+    if (head.state.activeCallId !== call.callId)
+        throw new Error("role_approval_active_call_mismatch");
+    const current = head.state.calls.find((entry) => entry.callId === call.callId);
+    if (current?.status !== "waiting_for_capability")
+        throw new Error("role_approval_call_not_waiting");
+    const running = head.state.capabilityExecutions.filter((entry) => entry.status === "running");
+    if (running.length !== wait.group.entries.length)
+        throw new Error("role_approval_group_incomplete");
+    for (const entry of wait.group.entries) {
+        const execution = running.find((candidate) => candidate.executionId === entry.executionId);
+        if (execution?.callId !== call.callId)
+            throw new Error("role_approval_execution_mismatch");
+        if (execution.actionFingerprint !== entry.actionFingerprint)
+            throw new Error("role_approval_action_mismatch");
+    }
+}

package/dist/src/runtime/orchestration/role-executors/child-invocation/entered-child.d.ts

@@ -0,0 +1,19 @@
+import type { RoleCallFrame, RoleCallLedger } from "../../role-calls/index.js";
+import type { EnteredChildCursor, RoleApprovalContinuation } from "../approval-continuation.js";
+import type { RoleChildInvocationInput } from "../contracts.js";
+import type { DelegateRoleCallFrame } from "./state-validation.js";
+export type EnteredChild = Readonly<{
+    call: DelegateRoleCallFrame;
+    callerCall: RoleCallFrame;
+    cursor: EnteredChildCursor;
+}>;
+export declare function restoreEnteredChild(ledger: RoleCallLedger, cursor: EnteredChildCursor): EnteredChild;
+/** Both root and delegate callers re-enter the original child transaction. */
+export declare function createEnteredChildInvocation<TContext, TValue>(params: {
+    requestId: string;
+    context: TContext;
+    ledger: RoleCallLedger;
+    continuation: RoleApprovalContinuation;
+}): RoleChildInvocationInput<TContext> & {
+    allowApprovalWait: true;
+};

package/dist/src/runtime/orchestration/role-executors/child-invocation/entered-child.js

@@ -0,0 +1,55 @@
+import { isDeepStrictEqual } from "node:util";
+import { isRuntimeDelegateRoleId } from "../../roles.js";
+export function restoreEnteredChild(ledger, cursor) {
+    const state = ledger.current().state;
+    const caller = state.calls.find((call) => call.callId === cursor.callerCall.callId);
+    const child = state.calls.find((call) => call.callId === cursor.childCallId);
+    if (caller?.status !== "waiting_for_child")
+        throw new Error("role_approval_caller_not_waiting");
+    if (caller.childCallIds.at(-1) !== cursor.childCallId)
+        throw new Error("role_approval_child_order_invalid");
+    const priorCaller = {
+        ...caller,
+        status: "active",
+        childCallIds: caller.childCallIds.slice(0, -1),
+    };
+    if (!isDeepStrictEqual(priorCaller, cursor.callerCall))
+        throw new Error("role_approval_caller_identity_invalid");
+    if (child?.parentCallId !== caller.callId)
+        throw new Error("role_approval_child_parent_invalid");
+    if (!isRuntimeDelegateRoleId(child.roleId))
+        throw new Error("role_approval_child_role_invalid");
+    if (child.status === "completed")
+        throw new Error("role_approval_child_already_returned");
+    if (!Number.isSafeInteger(cursor.turnCount) || cursor.turnCount < 1)
+        throw new Error("role_approval_turn_invalid");
+    const planItems = state.plans.flatMap((plan) => plan.itemStates
+        .filter((item) => item.childCallId === child.callId)
+        .map((item) => item.itemId));
+    if (!isDeepStrictEqual(planItems, cursor.planItemIds ?? []))
+        throw new Error("role_approval_plan_binding_invalid");
+    return {
+        call: child,
+        callerCall: cursor.callerCall,
+        cursor,
+    };
+}
+/** Both root and delegate callers re-enter the original child transaction. */
+export function createEnteredChildInvocation(params) {
+    const cursor = params.continuation.callers[0];
+    if (!cursor)
+        throw new Error("role_approval_child_cursor_missing");
+    const entered = restoreEnteredChild(params.ledger, cursor);
+    return {
+        allowApprovalWait: true,
+        requestId: params.requestId,
+        context: params.context,
+        ledger: params.ledger,
+        callerCall: cursor.callerCall,
+        expectedHead: params.ledger.current(),
+        roleId: entered.call.roleId,
+        objective: entered.call.objective,
+        turnCount: cursor.turnCount,
+        entered: params.continuation,
+    };
+}

package/dist/src/runtime/orchestration/role-executors/child-invocation/state-validation.d.ts

@@ -1,7 +1,6 @@
 import type { RoleCallChildReturnCommit, RoleCallCommitEffect, RoleCallFrame, RoleCallLedger, RoleCallLedgerCommit, RoleCallLedgerHead } from "../../role-calls/index.js";
 import type { RuntimeDelegateRoleId } from "../../roles.js";
-import type { RoleExecutorRegistry } from "../contracts.js";
-type RoleChildInvocationInput<TContext, TValue> = Parameters<RoleExecutorRegistry<TContext, TValue>["invokeChild"]>[0];
+import type { RoleChildInvocationInput } from "../contracts.js";
 export type ChildOpenedCommit = RoleCallLedgerCommit & Readonly<{
     effect: Extract<RoleCallCommitEffect, {
         type: "child_opened";
@@ -19,8 +18,10 @@ export type OpenedChild = Readonly<{
     commit: ChildOpenedCommit;
     call: DelegateRoleCallFrame;
 }>;
-export declare function isValidOpenedChildProjection<TContext, TValue>(ledger: RoleCallLedger, opened: ChildOpenedCommit, callerCall: RoleCallFrame, input: RoleChildInvocationInput<TContext, TValue>, dependencyResultRefs: readonly string[], childCall: RoleCallFrame | undefined): childCall is DelegateRoleCallFrame;
-export declare function isValidChildReturnTransition(commit: ChildReturnedCommit, opened: ChildOpenedCommit): boolean;
+export declare function isValidOpenedChildProjection<TContext, TValue>(ledger: RoleCallLedger, opened: ChildOpenedCommit, callerCall: RoleCallFrame, input: RoleChildInvocationInput<TContext>, dependencyResultRefs: readonly string[], childCall: RoleCallFrame | undefined): childCall is DelegateRoleCallFrame;
+export declare function isValidChildReturnTransition(commit: ChildReturnedCommit, opened: Readonly<{
+    planItemIds?: readonly string[];
+}>): boolean;
 export declare function isValidResumeProjection(resume: Readonly<{
     callerCallId: string;
     invocationAttempt: number;
@@ -38,4 +39,3 @@ export declare function resolveActiveCaller(params: Readonly<{
     issueCode: string;
 }>;
 export declare function requireResumedCallerCall(commit: RoleCallChildReturnCommit, previousCall: RoleCallFrame): RoleCallFrame;
-export {};

package/dist/src/runtime/orchestration/role-executors/child-invocation/state-validation.js

@@ -15,9 +15,9 @@ export function isValidOpenedChildProjection(ledger, opened, callerCall, input,
         childCall.status === "active");
 }
 export function isValidChildReturnTransition(commit, opened) {
-    return ((opened.effect.planItemIds === undefined) ===
+    return ((opened.planItemIds === undefined) ===
         (commit.effect.planItemIds === undefined) &&
-        sameStrings(opened.effect.planItemIds ?? [], commit.effect.planItemIds ?? []));
+        sameStrings(opened.planItemIds ?? [], commit.effect.planItemIds ?? []));
 }
 export function isValidResumeProjection(resume, resumedCall) {
     return (resume.callerCallId === resumedCall.callId &&

package/dist/src/runtime/orchestration/role-executors/child-invocation/transaction.d.ts

@@ -1,16 +1,17 @@
-import type { RoleChildInvocationResult, RoleExecutorRegistry } from "../contracts.js";
-type RoleChildInvocationInput<TContext, TValue> = Parameters<RoleExecutorRegistry<TContext, TValue>["invokeChild"]>[0];
+import { type RoleApprovalWait } from "../approval-continuation.js";
+import type { RoleChildInvocationResult, RoleExecutionResult, RoleExecutorRegistry, RoleChildInvocationInput, RoleExecutionInput } from "../contracts.js";
 export declare class ChildInvocationTransaction<TContext, TValue> {
     private readonly params;
     private readonly diagnostic;
     private readonly transactions;
     constructor(params: Readonly<{
-        input: RoleChildInvocationInput<TContext, TValue>;
+        input: RoleChildInvocationInput<TContext>;
         registeredRoleIds: RoleExecutorRegistry<TContext, TValue>["roleIds"];
-        isRoleRegistered(roleId: RoleChildInvocationInput<TContext, TValue>["roleId"]): boolean;
-        executeRole: RoleExecutorRegistry<TContext, TValue>["execute"];
+        isRoleRegistered(roleId: RoleChildInvocationInput<TContext>["roleId"]): boolean;
+        executeRole(input: RoleExecutionInput<TContext>): Promise<RoleExecutionResult<TValue> | RoleApprovalWait>;
     }>);
-    run(): Promise<RoleChildInvocationResult<TValue>>;
+    run(): Promise<RoleChildInvocationResult<TValue> | RoleApprovalWait>;
+    private enterChild;
     private readExpectedCallerHead;
     private requireActiveCaller;
     private requireInvocableChildRole;
@@ -19,4 +20,3 @@ export declare class ChildInvocationTransaction<TContext, TValue> {
     private returnChild;
     private rejectChild;
 }
-export {};

package/dist/src/runtime/orchestration/role-executors/child-invocation/transaction.js

@@ -1,3 +1,5 @@
+import { isRoleApprovalWait, } from "../approval-continuation.js";
+import { restoreEnteredChild } from "./entered-child.js";
 import { projectRoleChildReturnContext, requireRoleCallChildReturnCommit, resolveRoleCallTransactions, } from "../../role-calls/index.js";
 import { traceRoleExecutorChildCompleted, traceRoleExecutorChildContinued, traceRoleExecutorChildRejected, traceRoleExecutorChildRequested, traceRoleExecutorChildStarted, } from "../diagnostics.js";
 import { planBindingDiagnosticFields, workerCapabilityScopeDiagnosticFields, workingDirectoryDiagnosticFields, } from "./diagnostic-fields.js";
@@ -18,30 +20,60 @@ export class ChildInvocationTransaction {
         });
     }
     async run() {
-        const before = this.readExpectedCallerHead();
-        const callerCall = this.requireActiveCaller(before);
-        this.requireInvocableChildRole(callerCall);
-        const dependencyResultRefs = projectPriorDirectSiblingResultRefs(before, callerCall);
-        this.traceChildRequested(callerCall, dependencyResultRefs);
-        const openedChild = await this.openChild(before, callerCall, dependencyResultRefs);
+        const entered = await this.enterChild();
         const execution = await this.params.executeRole({
+            allowApprovalWait: this.params.input.allowApprovalWait,
             requestId: this.params.input.requestId,
             context: this.params.input.context,
-            call: openedChild.call,
+            call: entered.call,
             ledger: this.params.input.ledger,
+            ...(this.params.input.entered
+                ? {
+                    continuationState: {
+                        ...this.params.input.entered,
+                        callers: this.params.input.entered.callers.slice(1),
+                    },
+                }
+                : {}),
         });
+        if (isRoleApprovalWait(execution)) {
+            return Object.freeze({
+                ...execution,
+                callers: Object.freeze([entered.cursor, ...execution.callers]),
+            });
+        }
         traceRoleExecutorChildCompleted(this.diagnostic, {
-            childCallId: openedChild.call.callId,
-            childRoleId: openedChild.call.roleId,
+            childCallId: entered.call.callId,
+            childRoleId: entered.call.roleId,
             outcome: execution.outcome,
             summaryLength: execution.summary.length,
             turnCount: this.params.input.turnCount,
         });
-        const returnCommit = await this.returnChild(openedChild, callerCall, execution);
-        return Object.freeze({
-            execution,
-            returnCommit,
-        });
+        const returnCommit = await this.returnChild(entered, entered.callerCall, execution);
+        return Object.freeze({ execution, returnCommit });
+    }
+    async enterChild() {
+        const saved = this.params.input.entered?.callers[0];
+        if (saved)
+            return restoreEnteredChild(this.params.input.ledger, saved);
+        const before = this.readExpectedCallerHead();
+        const callerCall = this.requireActiveCaller(before);
+        this.requireInvocableChildRole(callerCall);
+        const dependencyResultRefs = projectPriorDirectSiblingResultRefs(before, callerCall);
+        this.traceChildRequested(callerCall, dependencyResultRefs);
+        const opened = await this.openChild(before, callerCall, dependencyResultRefs);
+        return {
+            call: opened.call,
+            callerCall,
+            cursor: Object.freeze({
+                callerCall,
+                childCallId: opened.call.callId,
+                turnCount: this.params.input.turnCount,
+                ...(opened.commit.effect.planItemIds
+                    ? { planItemIds: opened.commit.effect.planItemIds }
+                    : {}),
+            }),
+        };
     }
     readExpectedCallerHead() {
         const { input } = this.params;
@@ -179,7 +211,7 @@ export class ChildInvocationTransaction {
             });
         }
         const returned = returnedResult.commit;
-        if (!isValidChildReturnTransition(returned, openedChild.commit)) {
+        if (!isValidChildReturnTransition(returned, openedChild.cursor)) {
             this.rejectChild({
                 issueCode: "child_return_transition_invalid",
                 callerCall,

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

@@ -1,5 +1,6 @@
 import type { RoleCallChildReturnCommit, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleCallOperationSupervisionInterventionCommit, RoleCallPlanBinding, RoleCallResultReceipt, RoleCallWorkerCapabilityScope } from "../role-calls/index.js";
 import type { RuntimeDelegateRoleId } from "../roles.js";
+import type { RoleApprovalContinuation, RoleApprovalWait } from "./approval-continuation.js";
 export type RoleExecutionOutcome = "completed" | "failed";
 export type RoleExecutionResult<TValue = unknown> = Readonly<{
     kind: "terminal";
@@ -41,7 +42,7 @@ export type RoleExecutionChildInvocation = Readonly<{
     workingDirectory?: string;
     plannerPlan?: RoleCallPlanBinding;
 }>;
-export type RoleExecutorActivationResult<TValue = unknown> = RoleExecutionResult<TValue> | RoleExecutionContinuation | RoleExecutionChildInvocation;
+export type RoleExecutorActivationResult<TValue = unknown> = RoleExecutionResult<TValue> | RoleApprovalWait | RoleExecutionContinuation | RoleExecutionChildInvocation;
 export type RoleExecutorInput<TContext> = Readonly<{
     context: TContext;
     call: RoleCallFrame;
@@ -53,25 +54,41 @@ export type RoleExecutor<TContext, TValue = unknown> = Readonly<{
     roleId: RuntimeDelegateRoleId;
     execute(input: RoleExecutorInput<TContext>): Promise<RoleExecutorActivationResult<TValue>>;
 }>;
+export type RoleChildInvocationInput<TContext> = Readonly<{
+    requestId: string;
+    context: TContext;
+    callerCall: RoleCallFrame;
+    ledger: RoleCallLedger;
+    expectedHead: RoleCallLedgerHead;
+    roleId: RuntimeDelegateRoleId;
+    objective: string;
+    workerCapabilityScope?: RoleCallWorkerCapabilityScope;
+    workingDirectory?: string;
+    plannerPlan?: RoleCallPlanBinding;
+    turnCount: number;
+    entered?: RoleApprovalContinuation;
+    allowApprovalWait?: boolean;
+}>;
+export type RoleExecutionInput<TContext> = Readonly<{
+    requestId: string;
+    context: TContext;
+    call: RoleCallFrame;
+    ledger: RoleCallLedger;
+    continuationState?: RoleApprovalContinuation;
+    allowApprovalWait?: boolean;
+}>;
 export type RoleExecutorRegistry<TContext, TValue = unknown> = Readonly<{
     roleIds: readonly RuntimeDelegateRoleId[];
-    invokeChild(input: Readonly<{
-        requestId: string;
-        context: TContext;
-        callerCall: RoleCallFrame;
-        ledger: RoleCallLedger;
-        expectedHead: RoleCallLedgerHead;
-        roleId: RuntimeDelegateRoleId;
-        objective: string;
-        workerCapabilityScope?: RoleCallWorkerCapabilityScope;
-        workingDirectory?: string;
-        plannerPlan?: RoleCallPlanBinding;
-        turnCount: number;
-    }>): Promise<RoleChildInvocationResult<TValue>>;
-    execute(input: Readonly<{
-        requestId: string;
-        context: TContext;
-        call: RoleCallFrame;
-        ledger: RoleCallLedger;
-    }>): Promise<RoleExecutionResult<TValue>>;
+    invokeChild(input: RoleChildInvocationInput<TContext> & {
+        allowApprovalWait: true;
+    }): Promise<RoleChildInvocationResult<TValue> | RoleApprovalWait>;
+    invokeChild(input: RoleChildInvocationInput<TContext> & {
+        allowApprovalWait?: false;
+    }): Promise<RoleChildInvocationResult<TValue>>;
+    execute(input: RoleExecutionInput<TContext> & {
+        allowApprovalWait: true;
+    }): Promise<RoleExecutionResult<TValue> | RoleApprovalWait>;
+    execute(input: RoleExecutionInput<TContext> & {
+        allowApprovalWait?: false;
+    }): Promise<RoleExecutionResult<TValue>>;
 }>;