@abot-ai/runtime 1.0.0

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

@@ -0,0 +1,80 @@
+import { normalizeRoleCallWorkingDirectory } from "../../role-calls/index.js";
+import { childInvocationError, sameCallFrame, sameStrings, sameWorkerCapabilityScope, } from "../shared/runtime-invariants.js";
+export function isValidOpenedChildProjection(ledger, opened, callerCall, input, dependencyResultRefs, childCall) {
+    return (ledger.current() === opened.head &&
+        opened.head.state.activeCallId === opened.effect.childCallId &&
+        childCall?.parentCallId === callerCall.callId &&
+        childCall.roleId === input.roleId &&
+        childCall.objective === input.objective &&
+        sameWorkerCapabilityScope(childCall.workerCapabilityScope, input.workerCapabilityScope) &&
+        childCall.workingDirectory ===
+            normalizeRoleCallWorkingDirectory(input.workingDirectory) &&
+        (input.plannerPlan !== undefined) ===
+            (opened.effect.planItemIds !== undefined) &&
+        sameStrings(childCall.dependencyResultRefs, dependencyResultRefs) &&
+        childCall.status === "active");
+}
+export function isValidChildReturnTransition(commit, opened) {
+    return ((opened.effect.planItemIds === undefined) ===
+        (commit.effect.planItemIds === undefined) &&
+        sameStrings(opened.effect.planItemIds ?? [], commit.effect.planItemIds ?? []));
+}
+export function isValidResumeProjection(resume, resumedCall) {
+    return (resume.callerCallId === resumedCall.callId &&
+        resume.invocationAttempt === resumedCall.activationCount);
+}
+export function projectPriorDirectSiblingResultRefs(head, callerCall) {
+    const resultRefs = callerCall.childCallIds.flatMap((childCallId) => {
+        const child = head.state.calls.find((candidate) => candidate.callId === childCallId);
+        return child?.parentCallId === callerCall.callId &&
+            child.status === "completed" &&
+            child.resultRef !== null
+            ? [child.resultRef]
+            : [];
+    });
+    return Object.freeze(resultRefs);
+}
+export function resolveActiveCaller(params) {
+    try {
+        if (params.head.state.requestId !== params.requestId) {
+            return { ok: false, issueCode: "request_id_mismatch" };
+        }
+        if (params.head.state.phase !== "running" ||
+            params.head.state.activeCallId !== params.expectedCall.callId) {
+            return { ok: false, issueCode: "call_not_current" };
+        }
+        const call = params.head.state.calls.find((candidate) => candidate.callId === params.expectedCall.callId);
+        if (!call)
+            return { ok: false, issueCode: "call_unavailable" };
+        if (call.status !== "active") {
+            return { ok: false, issueCode: "call_not_active" };
+        }
+        if (!sameCallFrame(call, params.expectedCall)) {
+            return { ok: false, issueCode: "call_identity_mismatch" };
+        }
+        return { ok: true, call };
+    }
+    catch {
+        return { ok: false, issueCode: "ledger_head_invalid" };
+    }
+}
+export function requireResumedCallerCall(commit, previousCall) {
+    const resumedCall = commit.head.state.calls.find((candidate) => candidate.callId === previousCall.callId);
+    if (commit.head.state.phase !== "running" ||
+        commit.head.state.activeCallId !== previousCall.callId ||
+        resumedCall?.status !== "active" ||
+        resumedCall.activationCount !== previousCall.activationCount + 1 ||
+        resumedCall.callId !== previousCall.callId ||
+        resumedCall.parentCallId !== previousCall.parentCallId ||
+        resumedCall.roleId !== previousCall.roleId ||
+        resumedCall.depth !== previousCall.depth ||
+        resumedCall.objective !== previousCall.objective ||
+        resumedCall.workingDirectory !== previousCall.workingDirectory ||
+        resumedCall.resultRef !== previousCall.resultRef ||
+        resumedCall.childCallIds.length !== previousCall.childCallIds.length + 1 ||
+        !previousCall.childCallIds.every((childCallId, index) => resumedCall.childCallIds[index] === childCallId) ||
+        resumedCall.childCallIds.at(-1) !== commit.effect.childCallId) {
+        throw childInvocationError(previousCall.roleId, "caller_resume_projection_invalid");
+    }
+    return resumedCall;
+}

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

@@ -0,0 +1,22 @@
+import type { RoleChildInvocationResult, RoleExecutorRegistry } from "../contracts.js";
+type RoleChildInvocationInput<TContext, TValue> = Parameters<RoleExecutorRegistry<TContext, TValue>["invokeChild"]>[0];
+export declare class ChildInvocationTransaction<TContext, TValue> {
+    private readonly params;
+    private readonly diagnostic;
+    private readonly transactions;
+    constructor(params: Readonly<{
+        input: RoleChildInvocationInput<TContext, TValue>;
+        registeredRoleIds: RoleExecutorRegistry<TContext, TValue>["roleIds"];
+        isRoleRegistered(roleId: RoleChildInvocationInput<TContext, TValue>["roleId"]): boolean;
+        executeRole: RoleExecutorRegistry<TContext, TValue>["execute"];
+    }>);
+    run(): Promise<RoleChildInvocationResult<TValue>>;
+    private readExpectedCallerHead;
+    private requireActiveCaller;
+    private requireInvocableChildRole;
+    private traceChildRequested;
+    private openChild;
+    private returnChild;
+    private rejectChild;
+}
+export {};

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

@@ -0,0 +1,232 @@
+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";
+import { isValidChildReturnTransition, isValidOpenedChildProjection, isValidResumeProjection, projectPriorDirectSiblingResultRefs, requireResumedCallerCall, resolveActiveCaller, } from "./state-validation.js";
+import { createDiagnostic, } from "../shared/diagnostic-context.js";
+import { childInvocationError, readLedgerOrReject, } from "../shared/runtime-invariants.js";
+export class ChildInvocationTransaction {
+    params;
+    diagnostic;
+    transactions;
+    constructor(params) {
+        this.params = params;
+        this.transactions = resolveRoleCallTransactions(params.input.ledger);
+        this.diagnostic = createDiagnostic({
+            requestId: params.input.requestId,
+            call: params.input.callerCall,
+            registeredRoleIds: params.registeredRoleIds,
+        });
+    }
+    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 execution = await this.params.executeRole({
+            requestId: this.params.input.requestId,
+            context: this.params.input.context,
+            call: openedChild.call,
+            ledger: this.params.input.ledger,
+        });
+        traceRoleExecutorChildCompleted(this.diagnostic, {
+            childCallId: openedChild.call.callId,
+            childRoleId: openedChild.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,
+        });
+    }
+    readExpectedCallerHead() {
+        const { input } = this.params;
+        let before;
+        try {
+            before = input.ledger.current();
+        }
+        catch {
+            this.rejectChild({
+                issueCode: "ledger_read_failed",
+                callerCall: input.callerCall,
+            });
+        }
+        if (before !== input.expectedHead) {
+            this.rejectChild({
+                issueCode: "child_request_state_changed",
+                callerCall: input.callerCall,
+            });
+        }
+        return before;
+    }
+    requireActiveCaller(before) {
+        const { input } = this.params;
+        const callerAuthority = resolveActiveCaller({
+            head: before,
+            requestId: input.requestId,
+            expectedCall: input.callerCall,
+        });
+        if (!callerAuthority.ok) {
+            this.rejectChild({
+                issueCode: callerAuthority.issueCode,
+                callerCall: input.callerCall,
+            });
+        }
+        return callerAuthority.call;
+    }
+    requireInvocableChildRole(callerCall) {
+        const { input } = this.params;
+        if (input.roleId === callerCall.roleId) {
+            this.rejectChild({
+                issueCode: "child_role_matches_caller",
+                callerCall,
+            });
+        }
+        if (!this.params.isRoleRegistered(input.roleId)) {
+            this.rejectChild({
+                issueCode: "child_executor_not_registered",
+                callerCall,
+            });
+        }
+    }
+    traceChildRequested(callerCall, dependencyResultRefs) {
+        const { input } = this.params;
+        traceRoleExecutorChildRequested(this.diagnostic, {
+            childRoleId: input.roleId,
+            childObjectiveLength: input.objective.length,
+            dependencyResolution: "all_prior_direct_siblings_v1",
+            inheritedSiblingResultCount: dependencyResultRefs.length,
+            inheritedSiblingResultRefs: dependencyResultRefs,
+            dependencyResultCount: dependencyResultRefs.length,
+            dependencyResultRefs,
+            ...workerCapabilityScopeDiagnosticFields(input.workerCapabilityScope),
+            ...workingDirectoryDiagnosticFields(input.workingDirectory),
+            ...planBindingDiagnosticFields(input.plannerPlan),
+            fromActivation: callerCall.activationCount,
+            turnCount: input.turnCount,
+        });
+    }
+    async openChild(before, callerCall, dependencyResultRefs) {
+        const { input } = this.params;
+        const openedResult = await this.transactions.openChild({
+            expectedHead: before,
+            callerCallId: callerCall.callId,
+            roleId: input.roleId,
+            objective: input.objective,
+            dependencyResultRefs,
+            ...(input.workerCapabilityScope
+                ? { workerCapabilityScope: input.workerCapabilityScope }
+                : {}),
+            ...(input.workingDirectory !== undefined
+                ? { workingDirectory: input.workingDirectory }
+                : {}),
+            ...(input.plannerPlan ? { plannerPlan: input.plannerPlan } : {}),
+        });
+        if (!openedResult.ok) {
+            this.rejectChild({
+                issueCode: openedResult.issueCode,
+                callerCall,
+            });
+        }
+        const opened = openedResult.commit;
+        const openedChildCallId = opened.effect.childCallId;
+        const childCall = opened.head.state.calls.find((candidate) => candidate.callId === openedChildCallId);
+        if (!isValidOpenedChildProjection(input.ledger, opened, callerCall, input, dependencyResultRefs, childCall)) {
+            this.rejectChild({
+                issueCode: "child_open_projection_invalid",
+                callerCall,
+            });
+        }
+        traceRoleExecutorChildStarted(this.diagnostic, {
+            childCallId: childCall.callId,
+            childRoleId: childCall.roleId,
+            childDepth: childCall.depth,
+            dependencyResultCount: childCall.dependencyResultRefs.length,
+            dependencyResultRefs: childCall.dependencyResultRefs,
+            ...workerCapabilityScopeDiagnosticFields(childCall.workerCapabilityScope),
+            ...workingDirectoryDiagnosticFields(childCall.workingDirectory),
+            ...(opened.effect.planItemIds
+                ? { planItemIds: opened.effect.planItemIds }
+                : {}),
+            turnCount: input.turnCount,
+        });
+        return Object.freeze({ commit: opened, call: childCall });
+    }
+    async returnChild(openedChild, callerCall, execution) {
+        const { input } = this.params;
+        const beforeReturn = readLedgerOrReject({
+            ledger: input.ledger,
+            diagnostic: this.diagnostic,
+            turnCount: input.turnCount,
+        });
+        const returnedResult = await this.transactions.returnChild({
+            expectedHead: beforeReturn,
+            callerCallId: callerCall.callId,
+            childCallId: openedChild.call.callId,
+            outcome: execution.outcome,
+            summary: execution.summary,
+        });
+        if (!returnedResult.ok) {
+            this.rejectChild({
+                issueCode: returnedResult.issueCode,
+                callerCall,
+                childRoleId: openedChild.call.roleId,
+            });
+        }
+        const returned = returnedResult.commit;
+        if (!isValidChildReturnTransition(returned, openedChild.commit)) {
+            this.rejectChild({
+                issueCode: "child_return_transition_invalid",
+                callerCall,
+                childRoleId: openedChild.call.roleId,
+            });
+        }
+        const returnCommit = requireRoleCallChildReturnCommit(returned);
+        let resume;
+        let resumedCall;
+        try {
+            resume = projectRoleChildReturnContext(input.ledger, returned);
+            resumedCall = requireResumedCallerCall(returnCommit, callerCall);
+        }
+        catch {
+            this.rejectChild({
+                issueCode: "child_return_projection_invalid",
+                callerCall,
+                childRoleId: openedChild.call.roleId,
+            });
+        }
+        if (!isValidResumeProjection(resume, resumedCall)) {
+            this.rejectChild({
+                issueCode: "caller_resume_projection_invalid",
+                callerCall,
+                childRoleId: openedChild.call.roleId,
+            });
+        }
+        traceRoleExecutorChildContinued(this.diagnostic, {
+            childCallId: openedChild.call.callId,
+            childRoleId: openedChild.call.roleId,
+            resultRef: returnCommit.effect.resultRef,
+            fromActivation: callerCall.activationCount,
+            toActivation: resumedCall.activationCount,
+            ...(returnCommit.effect.planItemIds
+                ? { planItemIds: returnCommit.effect.planItemIds }
+                : {}),
+            turnCount: input.turnCount,
+        });
+        return returnCommit;
+    }
+    rejectChild(params) {
+        const { input } = this.params;
+        traceRoleExecutorChildRejected(this.diagnostic, {
+            issueCode: params.issueCode,
+            childRoleId: params.childRoleId ?? input.roleId,
+            fromActivation: params.callerCall.activationCount,
+            turnCount: input.turnCount,
+        });
+        throw childInvocationError(params.callerCall.roleId, params.issueCode);
+    }
+}

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

@@ -0,0 +1,72 @@
+import type { RoleCallChildReturnCommit, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead, RoleCallPlanBinding, RoleCallWorkerCapabilityScope } from "../role-calls/index.js";
+import type { RuntimeDelegateRoleId } from "../roles.js";
+export type RoleExecutionOutcome = "completed" | "failed";
+export type RoleExecutionResult<TValue = unknown> = Readonly<{
+    kind: "terminal";
+    outcome: RoleExecutionOutcome;
+    summary: string;
+    value?: TValue;
+}>;
+export type RoleChildInvocationResult<TValue = unknown> = Readonly<{
+    execution: RoleExecutionResult<TValue>;
+    returnCommit: RoleCallChildReturnCommit;
+}>;
+export type RoleCapabilityExecutionContinuationReference = Readonly<{
+    kind: "capability_execution";
+    executionId: string;
+}>;
+export type RoleCapabilityBatchExecutionContinuationReference = Readonly<{
+    kind: "capability_batch_execution";
+    executionIds: readonly string[];
+}>;
+export type RoleChildContinuationReference = Readonly<{
+    kind: "role_child";
+    commit: RoleCallChildReturnCommit;
+}>;
+export type RoleExecutionContinuationReference = RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference | RoleChildContinuationReference;
+export type RoleExecutionContinuation = Readonly<{
+    kind: "continue";
+    continuation: RoleCapabilityExecutionContinuationReference | RoleCapabilityBatchExecutionContinuationReference;
+}>;
+export type RoleExecutionChildInvocation = Readonly<{
+    kind: "invoke_role";
+    roleId: RuntimeDelegateRoleId;
+    objective: string;
+    workerCapabilityScope?: RoleCallWorkerCapabilityScope;
+    workingDirectory?: string;
+    plannerPlan?: RoleCallPlanBinding;
+}>;
+export type RoleExecutorActivationResult<TValue = unknown> = RoleExecutionResult<TValue> | RoleExecutionContinuation | RoleExecutionChildInvocation;
+export type RoleExecutorInput<TContext> = Readonly<{
+    context: TContext;
+    call: RoleCallFrame;
+    ledger: RoleCallLedger;
+    availableChildRoleIds: readonly RuntimeDelegateRoleId[];
+    continuation?: RoleExecutionContinuationReference;
+}>;
+export type RoleExecutor<TContext, TValue = unknown> = Readonly<{
+    roleId: RuntimeDelegateRoleId;
+    execute(input: RoleExecutorInput<TContext>): Promise<RoleExecutorActivationResult<TValue>>;
+}>;
+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>>;
+}>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,100 @@
+import type { RoleCallFrame } from "../role-calls/index.js";
+import type { RuntimeDelegateRoleId } from "../roles.js";
+import type { RoleExecutionOutcome, RoleExecutorRegistry } from "./contracts.js";
+type RoleExecutorDiagnosticContext = Readonly<{
+    requestId: string;
+    call: RoleCallFrame;
+    registeredRoleIds: RoleExecutorRegistry<unknown>["roleIds"];
+}>;
+export type RoleExecutorAttemptDiagnosticContext = Readonly<{
+    requestIdLength: number;
+    callIdLength: number;
+    attemptedRoleId?: RuntimeDelegateRoleId;
+    registeredRoleIds: RoleExecutorRegistry<unknown>["roleIds"];
+}>;
+export declare function traceRoleExecutorResolved(context: RoleExecutorDiagnosticContext): void;
+export declare function traceRoleExecutorUnavailable(context: RoleExecutorAttemptDiagnosticContext): void;
+export declare function traceRoleExecutorInitialStateRejected(context: RoleExecutorAttemptDiagnosticContext, issueCode: string): void;
+export declare function traceRoleExecutorStarted(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    availableChildRoleIds: readonly RuntimeDelegateRoleId[];
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorCompleted(context: RoleExecutorDiagnosticContext, result: Readonly<{
+    outcome: RoleExecutionOutcome;
+    summaryLength: number;
+    hasValue: boolean;
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorContinued(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    executionId?: string;
+    executionIds?: readonly string[];
+    fromActivation: number;
+    toActivation: number;
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorChildRequested(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    childRoleId: RuntimeDelegateRoleId;
+    childObjectiveLength: number;
+    dependencyResolution: "all_prior_direct_siblings_v1";
+    inheritedSiblingResultCount: number;
+    inheritedSiblingResultRefs: readonly string[];
+    dependencyResultCount: number;
+    dependencyResultRefs: readonly string[];
+    planBindingMode?: "declare" | "select" | "extend";
+    plannedItemCount?: number;
+    selectedPlanItemIndexes?: readonly number[];
+    selectedPlanItemIds?: readonly string[];
+    selectedPlanItemCount?: number;
+    workerCapabilityCatalogGroupIds?: readonly string[];
+    workerCapabilityCatalogGroupCount?: number;
+    workingDirectoryIncluded?: boolean;
+    workingDirectoryLength?: number;
+    fromActivation: number;
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorChildStarted(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    childCallId: string;
+    childRoleId: RuntimeDelegateRoleId;
+    childDepth: number;
+    dependencyResultCount: number;
+    dependencyResultRefs: readonly string[];
+    planItemIds?: readonly string[];
+    workerCapabilityCatalogGroupIds?: readonly string[];
+    workerCapabilityCatalogGroupCount?: number;
+    workingDirectoryIncluded?: boolean;
+    workingDirectoryLength?: number;
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorChildCompleted(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    childCallId: string;
+    childRoleId: RuntimeDelegateRoleId;
+    outcome: RoleExecutionOutcome;
+    summaryLength: number;
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorChildContinued(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    childCallId: string;
+    childRoleId: RuntimeDelegateRoleId;
+    resultRef: string;
+    fromActivation: number;
+    toActivation: number;
+    planItemIds?: readonly string[];
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorChildRejected(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    issueCode: string;
+    childRoleId?: RuntimeDelegateRoleId;
+    fromActivation: number;
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorContinuationRejected(context: RoleExecutorDiagnosticContext, params: Readonly<{
+    issueCode: string;
+    executionId?: string;
+    executionIds?: readonly string[];
+    fromActivation: number;
+    turnCount: number;
+}>): void;
+export declare function traceRoleExecutorStateRejected(context: RoleExecutorDiagnosticContext, issueCode: string, turnCount: number): void;
+export declare function traceRoleExecutorResultRejected(context: RoleExecutorDiagnosticContext, issueCode: string): void;
+export declare function traceRoleExecutorFailed(context: RoleExecutorDiagnosticContext, error: unknown): void;
+export {};

package/dist/src/runtime/orchestration/role-executors/diagnostics.js

@@ -0,0 +1,133 @@
+import { traceDebug } from "../../observability/debug-logger.js";
+import { classifyRuntimeErrorType } from "../../observability/error-type.js";
+const ROLE_EXECUTOR_LOG_SCOPE = "runtime.role_executors";
+export function traceRoleExecutorResolved(context) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.resolved", {
+        ...projectCall(context),
+    });
+}
+export function traceRoleExecutorUnavailable(context) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.unavailable", {
+        ...projectAttempt(context),
+    });
+}
+export function traceRoleExecutorInitialStateRejected(context, issueCode) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "state.rejected", {
+        ...projectAttempt(context),
+        issueCode,
+        turnCount: 0,
+    });
+}
+export function traceRoleExecutorStarted(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.started", {
+        ...projectCall(context),
+        ...params,
+    });
+}
+export function traceRoleExecutorCompleted(context, result) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.completed", {
+        ...projectCall(context),
+        ...result,
+    });
+}
+export function traceRoleExecutorContinued(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.continued", {
+        ...projectCall(context),
+        continuationKind: params.executionIds
+            ? "capability_batch_execution"
+            : "capability_execution",
+        ...params,
+    });
+}
+export function traceRoleExecutorChildRequested(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "child.requested", {
+        ...projectCall(context),
+        ...params,
+    });
+}
+export function traceRoleExecutorChildStarted(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "child.started", {
+        ...projectCall(context),
+        ...params,
+    });
+}
+export function traceRoleExecutorChildCompleted(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "child.completed", {
+        ...projectCall(context),
+        ...params,
+    });
+}
+export function traceRoleExecutorChildContinued(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.continued", {
+        ...projectCall(context),
+        continuationKind: "role_child",
+        ...params,
+    });
+}
+export function traceRoleExecutorChildRejected(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "child.rejected", {
+        ...projectCall(context),
+        issueCode: params.issueCode,
+        ...(params.childRoleId ? { childRoleId: params.childRoleId } : {}),
+        fromActivation: params.fromActivation,
+        turnCount: params.turnCount,
+    });
+}
+export function traceRoleExecutorContinuationRejected(context, params) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "continuation.rejected", {
+        ...projectCall(context),
+        continuationKind: params.executionIds
+            ? "capability_batch_execution"
+            : "capability_execution",
+        issueCode: params.issueCode,
+        ...(params.executionId ? { executionId: params.executionId } : {}),
+        ...(params.executionIds ? { executionIds: params.executionIds } : {}),
+        fromActivation: params.fromActivation,
+        turnCount: params.turnCount,
+    });
+}
+export function traceRoleExecutorStateRejected(context, issueCode, turnCount) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "state.rejected", {
+        ...projectCall(context),
+        issueCode,
+        turnCount,
+    });
+}
+export function traceRoleExecutorResultRejected(context, issueCode) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "result.rejected", {
+        ...projectCall(context),
+        validationStage: "executor_result",
+        issueCode,
+    });
+}
+export function traceRoleExecutorFailed(context, error) {
+    traceDebug(ROLE_EXECUTOR_LOG_SCOPE, "executor.failed", {
+        ...projectCall(context),
+        errorType: classifyRuntimeErrorType(error),
+    });
+}
+function projectCall(context) {
+    return {
+        requestId: context.requestId,
+        callId: context.call.callId,
+        parentCallId: context.call.parentCallId,
+        roleId: context.call.roleId,
+        depth: context.call.depth,
+        activationCount: context.call.activationCount,
+        objectiveLength: context.call.objective?.length ?? 0,
+        workingDirectoryIncluded: context.call.workingDirectory !== undefined,
+        workingDirectoryLength: context.call.workingDirectory?.length ?? 0,
+        registeredRoleIds: context.registeredRoleIds,
+    };
+}
+function projectAttempt(context) {
+    return {
+        requestIdLength: context.requestIdLength,
+        callIdLength: context.callIdLength,
+        roleIdRecognized: context.attemptedRoleId !== undefined,
+        ...(context.attemptedRoleId
+            ? { attemptedRoleId: context.attemptedRoleId }
+            : {}),
+        registeredRoleIds: context.registeredRoleIds,
+    };
+}

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

@@ -0,0 +1,2 @@
+export * from "./contracts.js";
+export * from "./registry.js";

package/dist/src/runtime/orchestration/role-executors/index.js

@@ -0,0 +1,2 @@
+export * from "./contracts.js";
+export * from "./registry.js";

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

@@ -0,0 +1,2 @@
+import type { RoleExecutor, RoleExecutorRegistry } from "./contracts.js";
+export declare function createRoleExecutorRegistry<TContext, TValue = unknown>(executors: readonly RoleExecutor<TContext, TValue>[]): RoleExecutorRegistry<TContext, TValue>;