@abot-ai/runtime 1.0.0

package/dist/src/runtime/steps/worker-decision/diagnostics.js

@@ -0,0 +1,298 @@
+import { traceDebug } from "../../observability/debug-logger.js";
+import { WORKER_ROLE_ID, } from "./contracts.js";
+import { WORKER_COMPLETION_EVIDENCE_POLICY } from "./prompt.js";
+const WORKER_LOG_SCOPE = "runtime.worker";
+export function traceWorkerContextProjected(params) {
+    traceDebug(WORKER_LOG_SCOPE, "context.projected", {
+        ...baseFields(params.diagnostic),
+        contextProjection: params.contextProjection,
+        objectiveLength: params.objectiveLength,
+        workingDirectoryIncluded: params.workingDirectory !== undefined,
+        workingDirectoryLength: params.workingDirectory?.length ?? 0,
+        messageCount: params.context.messages.length,
+        messageCharacterCount: params.context.messages.reduce((total, message) => total + message.content.length, 0),
+        historyMessageCount: 0,
+        attachmentCount: 0,
+        referenceMessageCount: params.referenceMessageCount,
+        continuationMessageCount: params.continuationMessageCount,
+        projectContextIncluded: false,
+        plannedWorkContextIncluded: false,
+        capabilityContextIncluded: params.capabilityIds.length > 0 ||
+            params.settledCapabilityResultCount > 0,
+        availableCapabilityCount: params.capabilityIds.length,
+        availableCapabilityIds: params.capabilityIds,
+        availableCapabilityAffordanceCharacterCount: params.capabilityAffordanceCharacterCount,
+        capabilityCatalogProjection: params.capabilityCatalogProjection,
+        capabilityCatalogGroupCount: params.capabilityCatalogGroupCount,
+        capabilityCatalogMembershipCount: params.capabilityCatalogMembershipCount,
+        capabilityCatalogGroupedCharacterCount: params.capabilityCatalogGroupedCharacterCount,
+        capabilityCatalogFlatCharacterCount: params.capabilityCatalogFlatCharacterCount,
+        executionGuidanceIncluded: params.executionGuidanceCharacterCount > 0,
+        executionGuidanceCharacterCount: params.executionGuidanceCharacterCount,
+        ...(params.selectedCapabilityId
+            ? { selectedCapabilityId: params.selectedCapabilityId }
+            : {}),
+        ...(params.selectedCapabilityIds
+            ? {
+                selectedCapabilityIds: params.selectedCapabilityIds,
+                selectedCapabilityCount: params.selectedCapabilityIds.length,
+            }
+            : {}),
+        ...(params.capabilitySelectionRejection
+            ? {
+                capabilitySelectionRejectionIncluded: true,
+                rejectedSelectionKind: params.capabilitySelectionRejection.rejectedSelectionKind,
+                rejectedCapabilityIds: params.capabilitySelectionRejection.rejectedCapabilityIds,
+                rejectedInvocationCount: params.capabilitySelectionRejection.rejectedInvocationCount,
+            }
+            : {}),
+        settledCapabilityResultCount: params.settledCapabilityResultCount,
+        settledCapabilitySummaryLength: params.settledCapabilitySummaryLength,
+        settledCapabilityReferenceDataSourceLength: params.settledCapabilityReferenceDataSourceLength,
+        requestToolResultsProjection: params.requestToolResultsProjection,
+        requestToolResultsProjectedCharacterCount: params.requestToolResultsProjectedCharacterCount,
+        roleDependencyContextIncluded: params.dependencyResultRefs.length > 0,
+        dependencyResultCount: params.dependencyResultRefs.length,
+        dependencyResultRefs: params.dependencyResultRefs,
+        dependencyResultSummaryLength: params.dependencyResultSummaryLength,
+        roleAssignmentScopeIncluded: params.assignmentScope !== undefined,
+        ...(params.assignmentScope
+            ? {
+                roleAssignmentScopeCallId: params.assignmentScope.scopeCallId,
+                roleAssignmentScopeRoleId: params.assignmentScope.scopeRoleId,
+                roleAssignmentScopeObjectiveLength: params.assignmentScope.scopeObjective.length,
+            }
+            : {}),
+        availableChildRoleCount: 0,
+        schemaCharacterCount: JSON.stringify(params.format.schema).length,
+        baseInstructionCharacterCount: params.baseInstructionCharacterCount,
+        configuredInstructionBlockCount: params.configuredInstructionBlockCount,
+        configuredInstructionCharacterCount: params.configuredInstructionCharacterCount,
+        configuredInstructionRefs: params.configuredInstructionRefs,
+        configuredInstructionContentHashes: params.configuredInstructionContentHashes,
+        sessionArtifactPathSelectionDeferred: params.sessionArtifactPathSelectionDeferred,
+        sessionArtifactPathContextIncluded: params.sessionArtifactPathProjectedCount > 0,
+        sessionArtifactPathAvailableCount: params.sessionArtifactPathAvailableCount,
+        sessionArtifactPathBoundedCount: params.sessionArtifactPathBoundedCount,
+        sessionArtifactPathEligibleCount: params.sessionArtifactPathEligibleCount,
+        sessionArtifactPathProjectedCount: params.sessionArtifactPathProjectedCount,
+        sessionArtifactPathOmittedCount: params.sessionArtifactPathOmittedCount,
+        estimatedInputTokens: params.context.budget.estimatedInputTokens,
+        availableInputTokens: params.context.budget.availableInputTokens,
+        allowedActions: params.allowedActions,
+    });
+}
+export function traceWorkerCapabilitySelectionReopened(params) {
+    traceDebug(WORKER_LOG_SCOPE, "capability_selection.reopened", {
+        ...baseFields(params.diagnostic),
+        mappedOutcome: "capability_selection_reopened",
+        rejectedSelectionKind: params.rejection.rejectedSelectionKind,
+        rejectedCapabilityIds: params.rejection.rejectedCapabilityIds,
+        rejectedInvocationCount: params.rejection.rejectedInvocationCount,
+        rejectionReasonLength: params.reasonLength,
+        rejectedSelectionExecutionStarted: false,
+        reopenAttempt: 1,
+        maxReopenAttempts: 1,
+    });
+}
+export function traceWorkerCapabilityRefinementSkipped(params) {
+    traceDebug(WORKER_LOG_SCOPE, "capability_refinement.skipped", {
+        ...baseFields(params.diagnostic),
+        capabilityId: params.capabilityId,
+        reason: "selection_controls_complete",
+        selectionControlCount: params.selectionControlCount,
+        remainingControlCount: 0,
+        executionGuidanceIncluded: false,
+    });
+}
+export function traceWorkerCapabilityResultProjected(params) {
+    const results = requireReturnedCapabilityResults(params.resume);
+    traceDebug(WORKER_LOG_SCOPE, "capability_result.projected", {
+        ...baseFields(params.diagnostic),
+        returnedExecutionIds: results.map((result) => result.executionId),
+        returnedCapabilityIds: results.map((result) => result.capabilityId),
+        returnedCapabilityCount: results.length,
+        ...(results.length === 1
+            ? {
+                executionId: results[0].executionId,
+                capabilityId: results[0].capabilityId,
+                declaredEffect: results[0].declaredEffect,
+                outcome: results[0].outcome,
+                observedEffect: results[0].observedEffect,
+                summaryLength: results[0].summary.length,
+            }
+            : {}),
+        capabilityInvocationAttempt: results[0]?.invocationAttempt,
+        outcomes: results.map((result) => result.outcome),
+        observedEffects: results.map((result) => result.observedEffect),
+        returnedSummaryLength: results.reduce((total, result) => total + result.summary.length, 0),
+        settledCapabilityResultCount: params.resume.settledResults.length,
+        settledCapabilityExecutionIds: params.resume.settledResults.map((settled) => settled.executionId),
+        settledCapabilityIds: params.resume.settledResults.map((settled) => settled.capabilityId),
+        settledCapabilitySummaryLength: params.resume.settledResults.reduce((total, settled) => total + settled.summary.length, 0),
+        referenceMessageCount: params.referenceMessageCount,
+        continuationMessageCount: params.continuationMessageCount,
+    });
+}
+export function traceWorkerEnvelopeAccepted(params) {
+    traceDebug(WORKER_LOG_SCOPE, "output.envelope.accepted", {
+        ...baseFields(params.diagnostic),
+        validationStage: "json_envelope",
+        outputLength: params.outputLength,
+        rootType: "object",
+        keyCount: params.keyCount,
+    });
+}
+export function traceWorkerEnvelopeRejected(params) {
+    traceDebug(WORKER_LOG_SCOPE, "output.envelope.rejected", {
+        ...baseFields(params.diagnostic),
+        validationStage: "json_envelope",
+        outputLength: params.outputLength,
+        issueCount: params.issues.length,
+        issues: boundedIssues(params.issues),
+    });
+}
+export function traceWorkerDecisionAccepted(params) {
+    traceDebug(WORKER_LOG_SCOPE, "decision.accepted", {
+        ...baseFields(params.diagnostic),
+        validationStage: "domain_parser",
+        selectedAction: params.decision.action,
+        ...decisionFields(params.decision),
+    });
+}
+export function traceWorkerClientIntentPublished(params) {
+    traceDebug(WORKER_LOG_SCOPE, "client_intent.published", {
+        ...baseFields(params.diagnostic),
+        capabilityId: params.capabilityId,
+        intentLength: params.intentLength,
+        intentSource: "capability_selection",
+        ...(params.guidanceDecisionIntentLength === undefined
+            ? {}
+            : {
+                guidanceDecisionIntentLength: params.guidanceDecisionIntentLength,
+                guidanceDecisionIntentChanged: params.guidanceDecisionIntentLength !== params.intentLength,
+            }),
+    });
+}
+export function traceWorkerClientBatchIntentsPublished(params) {
+    traceDebug(WORKER_LOG_SCOPE, "client_intent.batch_published", {
+        ...baseFields(params.diagnostic),
+        capabilityIds: params.capabilityIds,
+        intentLengths: params.intentLengths,
+        capabilityCount: params.capabilityIds.length,
+        intentSource: "capability_selection",
+        ...(params.guidanceDecisionIntentLengths
+            ? {
+                guidanceDecisionIntentLengths: params.guidanceDecisionIntentLengths,
+            }
+            : {}),
+    });
+}
+export function traceWorkerDecisionRejected(params) {
+    traceDebug(WORKER_LOG_SCOPE, "decision.rejected", {
+        ...baseFields(params.diagnostic),
+        validationStage: "domain_parser",
+        ...(params.selectedAction ? { selectedAction: params.selectedAction } : {}),
+        issueCount: params.issues.length,
+        issues: boundedIssues(params.issues),
+    });
+}
+export function traceWorkerModelStarted(params) {
+    traceDebug(WORKER_LOG_SCOPE, "model.started", {
+        ...baseFields(params.diagnostic),
+        messageCount: params.messageCount,
+        messageCharacterCount: params.messageCharacterCount,
+        allowedActions: params.allowedActions,
+    });
+}
+export function traceWorkerModelCompleted(params) {
+    traceDebug(WORKER_LOG_SCOPE, "model.completed", {
+        ...baseFields(params.diagnostic),
+        durationMs: params.durationMs,
+        selectedAction: params.decision.action,
+        ...decisionFields(params.decision),
+    });
+}
+function decisionFields(decision) {
+    if (decision.action === "return_result") {
+        return {
+            mappedOutcome: "result_authoring_required",
+        };
+    }
+    if (decision.action === "return_failure") {
+        return {
+            resultLength: decision.reason.length,
+            mappedOutcome: "failed",
+        };
+    }
+    if (decision.action === "invoke_capabilities") {
+        return {
+            capabilityIds: decision.invocations.map((invocation) => invocation.capabilityId),
+            capabilityCount: decision.invocations.length,
+            intentLengths: decision.invocations.map((invocation) => invocation.intent.length),
+            selectionControlsIncluded: decision.invocations.some((invocation) => "selectionControls" in invocation),
+            selectionControlKeyCounts: decision.invocations.map((invocation) => "selectionControls" in invocation && invocation.selectionControls
+                ? Object.keys(invocation.selectionControls).length
+                : 0),
+            controlsIncluded: decision.invocations.every((invocation) => "controls" in invocation),
+            ...(decision.invocations.every((invocation) => "controls" in invocation)
+                ? {
+                    controlsKeyCounts: decision.invocations.map((invocation) => Object.keys(invocation
+                        .controls).length),
+                }
+                : {}),
+            mappedOutcome: "capability_batch_requested",
+        };
+    }
+    return {
+        capabilityId: decision.capabilityId,
+        intentLength: decision.intent.length,
+        selectionControlsIncluded: "selectionControls" in decision,
+        ...("selectionControls" in decision && decision.selectionControls
+            ? {
+                selectionControlKeyCount: Object.keys(decision.selectionControls)
+                    .length,
+            }
+            : {}),
+        controlsIncluded: "controls" in decision,
+        ...("controls" in decision
+            ? { controlsKeyCount: Object.keys(decision.controls).length }
+            : {}),
+        mappedOutcome: "capability_requested",
+    };
+}
+export function traceWorkerModelFailed(params) {
+    traceDebug(WORKER_LOG_SCOPE, "model.failed", {
+        ...baseFields(params.diagnostic),
+        durationMs: params.durationMs,
+        errorType: params.errorType,
+        invalidStructuredOutput: params.invalidStructuredOutput,
+    });
+}
+function baseFields(diagnostic) {
+    return {
+        requestId: diagnostic.requestId,
+        role: WORKER_ROLE_ID,
+        modelStep: diagnostic.modelStep,
+        decisionPhase: diagnostic.decisionPhase,
+        callId: diagnostic.callId,
+        parentCallId: diagnostic.parentCallId,
+        depth: diagnostic.depth,
+        invocationAttempt: diagnostic.invocationAttempt,
+        completionEvidencePolicy: WORKER_COMPLETION_EVIDENCE_POLICY,
+    };
+}
+function boundedIssues(issues) {
+    return issues.map(({ code, path }) => ({ code, path }));
+}
+function requireReturnedCapabilityResults(resume) {
+    const returnedExecutionIds = "returnedExecutionIds" in resume
+        ? resume.returnedExecutionIds
+        : [resume.returnedExecutionId];
+    const results = resume.settledResults.slice(-returnedExecutionIds.length);
+    if (results.length !== returnedExecutionIds.length ||
+        !results.every((result, index) => result.executionId === returnedExecutionIds[index])) {
+        throw new Error("worker_capability_resume_result_missing");
+    }
+    return results;
+}

package/dist/src/runtime/steps/worker-decision/format.d.ts

@@ -0,0 +1,18 @@
+import type { ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+import { type WorkerCapabilityControls, type WorkerCapabilityDescriptor } from "../../orchestration/worker-capabilities/index.js";
+export declare function createWorkerDecisionFormat(options?: Readonly<{
+    capabilities?: readonly WorkerCapabilityDescriptor[];
+    maxBatchCapabilityExecutions?: number;
+    allowSingleCapabilityInvocation?: boolean;
+    pendingCapabilitySelection?: Readonly<{
+        capabilityId: string;
+        intent: string;
+        selectionControls?: WorkerCapabilityControls;
+    }>;
+    pendingCapabilityBatchSelection?: readonly Readonly<{
+        capabilityId: string;
+        intent: string;
+        selectionControls?: WorkerCapabilityControls;
+    }>[];
+}>): ModelGatewayJsonSchemaFormat;
+export declare function workerCapabilityBatchExecutionSlotId(index: number): string;

package/dist/src/runtime/steps/worker-decision/format.js

@@ -0,0 +1,306 @@
+import { createStructuredDecisionEnvelopeSchema, structuredDecisionVariantSchemaPath, } from "../../model/structured-decision-envelope.js";
+import { isRoleCapabilityId } from "../../orchestration/role-calls/index.js";
+import { WORKER_CAPABILITY_COUNT_MAX, normalizeWorkerCapabilityControlsSchema, partitionWorkerCapabilityControlsSchema, validateWorkerCapabilitySelectionControls, } from "../../orchestration/worker-capabilities/index.js";
+import { WORKER_CAPABILITY_INTENT_MAX_LENGTH, WORKER_RESULT_MAX_LENGTH, } from "./contracts.js";
+const WORKER_CAPABILITY_CLIENT_INTENT_DESCRIPTION = "Short client-facing statement of what will happen next. Presentation only; exclude sources, dependencies, controls, payload details, and execution instructions.";
+export function createWorkerDecisionFormat(options = {}) {
+    if (options.capabilities !== undefined &&
+        !Array.isArray(options.capabilities)) {
+        throw new Error("worker_capabilities_invalid");
+    }
+    const suppliedCapabilities = options.capabilities ?? [];
+    const maxBatchCapabilityExecutions = options.maxBatchCapabilityExecutions ?? 0;
+    const allowSingleCapabilityInvocation = options.allowSingleCapabilityInvocation !== false;
+    const uniqueCapabilityIds = new Set(suppliedCapabilities.map((capability) => capability?.capabilityId));
+    if (suppliedCapabilities.length > WORKER_CAPABILITY_COUNT_MAX ||
+        uniqueCapabilityIds.size !== suppliedCapabilities.length ||
+        !Number.isInteger(maxBatchCapabilityExecutions) ||
+        maxBatchCapabilityExecutions < 0) {
+        throw new Error("worker_capabilities_invalid");
+    }
+    const capabilities = Object.freeze(suppliedCapabilities.map((capability) => {
+        if (typeof capability !== "object" ||
+            capability === null ||
+            !isRoleCapabilityId(capability.capabilityId) ||
+            (capability.effect !== "observation" &&
+                capability.effect !== "mutation" &&
+                capability.effect !== "mixed")) {
+            throw new Error("worker_capabilities_invalid");
+        }
+        const controls = normalizeWorkerCapabilityControlsSchema(capability.controls);
+        if (!controls.ok) {
+            throw new Error("worker_capabilities_invalid");
+        }
+        const controlsPartition = partitionWorkerCapabilityControlsSchema(controls.value, capability.selectionControlIds);
+        if (!controlsPartition.ok) {
+            throw new Error("worker_capabilities_invalid");
+        }
+        return Object.freeze({
+            capabilityId: capability.capabilityId,
+            effect: capability.effect,
+            controls: controls.value,
+            controlsPartition: controlsPartition.value,
+        });
+    }));
+    const batchCapabilities = capabilities.filter((capability) => capability.effect === "observation");
+    const pendingCapabilitySelection = options.pendingCapabilitySelection;
+    const pendingCapabilityBatchSelection = options.pendingCapabilityBatchSelection;
+    if (pendingCapabilitySelection && pendingCapabilityBatchSelection) {
+        throw new Error("worker_pending_capability_selection_ambiguous");
+    }
+    if (pendingCapabilitySelection &&
+        (!validPendingSelection(pendingCapabilitySelection, capabilities) ||
+            pendingCapabilitySelection.intent.trim().length === 0 ||
+            pendingCapabilitySelection.intent.length >
+                WORKER_CAPABILITY_INTENT_MAX_LENGTH)) {
+        throw new Error("worker_pending_capability_selection_invalid");
+    }
+    if (pendingCapabilityBatchSelection &&
+        (!Array.isArray(pendingCapabilityBatchSelection) ||
+            pendingCapabilityBatchSelection.length < 2 ||
+            pendingCapabilityBatchSelection.length > maxBatchCapabilityExecutions ||
+            pendingCapabilityBatchSelection.some((pending) => !validPendingSelection(pending, batchCapabilities) ||
+                !batchCapabilities.some((capability) => capability.capabilityId === pending.capabilityId) ||
+                pending.intent.trim().length === 0 ||
+                pending.intent.length > WORKER_CAPABILITY_INTENT_MAX_LENGTH))) {
+        throw new Error("worker_pending_capability_batch_selection_invalid");
+    }
+    const decisionPhase = pendingCapabilitySelection || pendingCapabilityBatchSelection
+        ? "capability_execution"
+        : "capability_selection";
+    const pendingSingleCapability = pendingCapabilitySelection
+        ? capabilities.find(({ capabilityId }) => capabilityId === pendingCapabilitySelection.capabilityId)
+        : undefined;
+    const batchEnabled = maxBatchCapabilityExecutions >= 2 && batchCapabilities.length > 0;
+    const singleSelectionGroups = groupCapabilitiesBySelectionSchema(capabilities);
+    const batchSelectionGroups = groupCapabilitiesBySelectionSchema(batchCapabilities);
+    const singleCapabilityVariants = !allowSingleCapabilityInvocation
+        ? []
+        : decisionPhase === "capability_selection"
+            ? singleSelectionGroups.map((group) => exactObject({
+                action: literal("invoke_capability"),
+                capabilityId: enumeration(group.capabilities.map(({ capabilityId }) => capabilityId)),
+                intent: capabilityIntentSelectionSchema(),
+                ...(group.partition.selectionControlIds.length > 0
+                    ? {
+                        selectionControls: projectControlsSchema(group.partition.selectionSchema),
+                    }
+                    : {}),
+            }))
+            : pendingSingleCapability
+                ? [
+                    exactObject({
+                        action: literal("invoke_capability"),
+                        controls: projectControlsSchema(pendingSingleCapability.controlsPartition.remainingSchema),
+                    }),
+                ]
+                : [];
+    const pendingBatchCapabilities = pendingCapabilityBatchSelection?.map(({ capabilityId }) => batchCapabilities.find((capability) => capability.capabilityId === capabilityId));
+    const batchInvocationsSchema = pendingCapabilityBatchSelection
+        ? exactObject(Object.fromEntries(pendingBatchCapabilities.map((capability, index) => [
+            workerCapabilityBatchExecutionSlotId(index),
+            {
+                ...exactObject({
+                    controls: projectControlsSchema(capability.controlsPartition.remainingSchema),
+                }),
+                description: `Pending invocation ${index + 1} is frozen to capabilityId ${JSON.stringify(capability.capabilityId)} and any supplied selectionControls. Return only the remaining controls for this capability.`,
+            },
+        ])))
+        : {
+            type: "array",
+            minItems: 2,
+            maxItems: maxBatchCapabilityExecutions,
+            items: projectCapabilitySelectionItemSchema(batchSelectionGroups),
+        };
+    const variants = [
+        exactObject({
+            action: literal("return_result"),
+        }),
+        exactObject({
+            action: literal("return_failure"),
+            reason: boundedText(WORKER_RESULT_MAX_LENGTH),
+        }),
+        ...singleCapabilityVariants,
+        ...(batchEnabled
+            ? [
+                exactObject({
+                    action: literal("invoke_capabilities"),
+                    invocations: batchInvocationsSchema,
+                }),
+            ]
+            : []),
+    ];
+    const singleCapabilityVariantCount = allowSingleCapabilityInvocation
+        ? singleCapabilityVariants.length
+        : 0;
+    const batchVariantIndex = singleCapabilityVariantCount + 2;
+    return {
+        type: "json_schema",
+        name: "worker_decision",
+        strict: true,
+        postValidatedSchemaConstraints: [
+            {
+                keyword: "maxLength",
+                path: `${structuredDecisionVariantSchemaPath(1, variants.length)}/properties/reason/maxLength`,
+            },
+            ...(allowSingleCapabilityInvocation && singleCapabilityVariants.length > 0
+                ? decisionPhase === "capability_selection"
+                    ? singleSelectionGroups.flatMap((group, index) => {
+                        const variantPath = structuredDecisionVariantSchemaPath(2 + index, variants.length);
+                        return [
+                            {
+                                keyword: "maxLength",
+                                path: `${variantPath}/properties/intent/maxLength`,
+                            },
+                            ...collectControlMaxLengthConstraints(group.partition.selectionSchema, `${variantPath}/properties/selectionControls`),
+                        ];
+                    })
+                    : collectControlMaxLengthConstraints(pendingSingleCapability.controlsPartition.remainingSchema, `${structuredDecisionVariantSchemaPath(2, variants.length)}/properties/controls`)
+                : []),
+            ...(batchEnabled
+                ? decisionPhase === "capability_selection"
+                    ? collectBatchSelectionMaxLengthConstraints({
+                        groups: batchSelectionGroups,
+                        basePath: `${structuredDecisionVariantSchemaPath(batchVariantIndex, variants.length)}/properties/invocations/items`,
+                    })
+                    : pendingBatchCapabilities.flatMap((capability, index) => {
+                        const itemPath = `${structuredDecisionVariantSchemaPath(batchVariantIndex, variants.length)}/properties/invocations/properties/${workerCapabilityBatchExecutionSlotId(index)}/properties`;
+                        return collectControlMaxLengthConstraints(capability.controlsPartition.remainingSchema, `${itemPath}/controls`);
+                    })
+                : []),
+        ],
+        schema: createStructuredDecisionEnvelopeSchema(variants),
+    };
+}
+export function workerCapabilityBatchExecutionSlotId(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error("worker_capability_batch_execution_slot_invalid");
+    }
+    return `invocation_${index + 1}`;
+}
+function validPendingSelection(pending, capabilities) {
+    const capability = capabilities.find(({ capabilityId }) => capabilityId === pending.capabilityId);
+    if (!capability)
+        return false;
+    const expectsSelectionControls = capability.controlsPartition.selectionControlIds.length > 0;
+    if (Object.hasOwn(pending, "selectionControls") !== expectsSelectionControls) {
+        return false;
+    }
+    return validateWorkerCapabilitySelectionControls(capability.controlsPartition, pending.selectionControls ?? {}).ok;
+}
+function groupCapabilitiesBySelectionSchema(capabilities) {
+    const groups = new Map();
+    for (const capability of capabilities) {
+        const signature = JSON.stringify(capability.controlsPartition.selectionSchema);
+        const group = groups.get(signature) ?? {
+            capabilities: [],
+            partition: capability.controlsPartition,
+        };
+        group.capabilities.push(capability);
+        groups.set(signature, group);
+    }
+    return Object.freeze([...groups.values()].map((group) => Object.freeze({
+        capabilities: Object.freeze([...group.capabilities]),
+        partition: group.partition,
+    })));
+}
+function projectCapabilitySelectionItemSchema(groups) {
+    const variants = groups.map((group) => exactObject({
+        capabilityId: enumeration(group.capabilities.map(({ capabilityId }) => capabilityId)),
+        intent: capabilityIntentSelectionSchema(),
+        ...(group.partition.selectionControlIds.length > 0
+            ? {
+                selectionControls: projectControlsSchema(group.partition.selectionSchema),
+            }
+            : {}),
+    }));
+    return variants.length === 1 ? variants[0] : { anyOf: variants };
+}
+function collectBatchSelectionMaxLengthConstraints(params) {
+    return params.groups.flatMap((group, index) => {
+        const itemPath = params.groups.length === 1
+            ? params.basePath
+            : `${params.basePath}/anyOf/${index}`;
+        return [
+            {
+                keyword: "maxLength",
+                path: `${itemPath}/properties/intent/maxLength`,
+            },
+            ...collectControlMaxLengthConstraints(group.partition.selectionSchema, `${itemPath}/properties/selectionControls`),
+        ];
+    });
+}
+function projectControlsSchema(schema) {
+    const required = new Set(schema.required);
+    return {
+        type: "object",
+        properties: Object.fromEntries(Object.entries(schema.properties).map(([controlId, control]) => [
+            controlId,
+            required.has(controlId)
+                ? projectControlSchema(control)
+                : {
+                    anyOf: [projectControlSchema(control), { type: "null" }],
+                },
+        ])),
+        required: Object.keys(schema.properties),
+        additionalProperties: false,
+    };
+}
+function capabilityIntentSelectionSchema() {
+    return {
+        ...boundedText(WORKER_CAPABILITY_INTENT_MAX_LENGTH),
+        description: WORKER_CAPABILITY_CLIENT_INTENT_DESCRIPTION,
+    };
+}
+function projectControlSchema(control) {
+    if (control.type === "array") {
+        return {
+            type: "array",
+            items: projectControlSchema(control.items),
+            minItems: control.minItems,
+            maxItems: control.maxItems,
+        };
+    }
+    if (control.type === "string" && "enum" in control) {
+        return { type: "string", enum: [...control.enum] };
+    }
+    return { ...control };
+}
+function collectControlMaxLengthConstraints(schema, basePath) {
+    return Object.entries(schema.properties).flatMap(([controlId, control]) => {
+        const propertyPath = `${basePath}/properties/${escapeJsonPointer(controlId)}${schema.required.includes(controlId) ? "" : "/anyOf/0"}`;
+        if (control.type === "array") {
+            return collectScalarMaxLengthConstraint(control.items, `${propertyPath}/items`);
+        }
+        return collectScalarMaxLengthConstraint(control, propertyPath);
+    });
+}
+function collectScalarMaxLengthConstraint(control, path) {
+    return control.type === "string" && "maxLength" in control
+        ? [{ keyword: "maxLength", path: `${path}/maxLength` }]
+        : [];
+}
+function escapeJsonPointer(input) {
+    return input.replace(/~/gu, "~0").replace(/\//gu, "~1");
+}
+function exactObject(properties) {
+    return {
+        type: "object",
+        properties,
+        required: Object.keys(properties),
+        additionalProperties: false,
+    };
+}
+function literal(value) {
+    return enumeration([value]);
+}
+function enumeration(values) {
+    return { type: "string", enum: [...values] };
+}
+function boundedText(maxLength) {
+    return {
+        type: "string",
+        minLength: 1,
+        maxLength,
+    };
+}

package/dist/src/runtime/steps/worker-decision/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./contracts.js";
+export * from "./format.js";
+export * from "./input.js";
+export * from "./ledger-projection.js";
+export * from "./parser.js";
+export * from "./prompt.js";
+export * from "./result-author.js";
+export * from "./run.js";

package/dist/src/runtime/steps/worker-decision/index.js

@@ -0,0 +1,8 @@
+export * from "./contracts.js";
+export * from "./format.js";
+export * from "./input.js";
+export * from "./ledger-projection.js";
+export * from "./parser.js";
+export * from "./prompt.js";
+export * from "./result-author.js";
+export * from "./run.js";

package/dist/src/runtime/steps/worker-decision/input/canonical-state.d.ts

@@ -0,0 +1,19 @@
+import { type RoleCallFrame, type RoleCallLedger } from "../../../orchestration/role-calls/index.js";
+import { type WorkerCapabilityDescriptor } from "../../../orchestration/worker-capabilities/index.js";
+import type { RequestExecutionSeed } from "../../../request/contracts.js";
+import { projectWorkerDecisionCallIdentity } from "../contracts.js";
+import type { PreparedWorkerCanonicalState, WorkerDecisionCapabilityBinding, WorkerDecisionCapabilityResumeSource, WorkerDecisionCapabilitySource, WorkerDecisionInputOptions } from "./types.js";
+export declare function prepareWorkerCanonicalState(request: Pick<RequestExecutionSeed, "requestId" | "prompt"> & Partial<Pick<RequestExecutionSeed, "contextCompactionStore">>, options: WorkerDecisionInputOptions, callIdentity: ReturnType<typeof projectWorkerDecisionCallIdentity>): PreparedWorkerCanonicalState;
+export declare function projectCapabilities(params: Readonly<{
+    requestId: string;
+    call: RoleCallFrame;
+    binding?: WorkerDecisionCapabilityBinding;
+    authorityLedger?: RoleCallLedger;
+    deferRuntimePathControls: boolean;
+}>): readonly WorkerCapabilityDescriptor[];
+export declare function validateCanonicalSources(params: Readonly<{
+    requestId: string;
+    call: RoleCallFrame;
+    capabilitySource?: WorkerDecisionCapabilitySource;
+    resumeSource?: WorkerDecisionCapabilityResumeSource;
+}>): void;