@abot-ai/runtime 1.0.0

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/catalog.js

@@ -0,0 +1,144 @@
+import { WORKER_CAPABILITY_COUNT_MAX, normalizeWorkerCapabilityControlsSchema, partitionWorkerCapabilityControlsSchema, } from "../../orchestration/worker-capabilities/index.js";
+import { isRoleCapabilityId } from "../../orchestration/role-calls/index.js";
+import { projectRuntimePathBindings } from "../registered-tool-normal-invocations.js";
+import { deriveRegisteredToolStagedPayloadPlan, } from "../registered-tool-payload-plan.js";
+import { RegisteredToolWorkerCapabilityCompositionError } from "./errors.js";
+export function resolveRegisteredToolCapabilityCatalog(registry, payloadAuthorAvailable) {
+    const registrations = captureRegistrySnapshot(registry);
+    const selected = resolveAvailableOperations(registrations, payloadAuthorAvailable);
+    const operationIds = Object.freeze(selected.map(({ operation }) => operation.operationId));
+    const descriptors = Object.freeze(selected.map(({ registration, operation, stagedPayloadPlan }) => projectWorkerDescriptor(registration.definition, operation, stagedPayloadPlan)));
+    return Object.freeze({
+        registry,
+        selected,
+        operationIds,
+        descriptors,
+    });
+}
+function captureRegistrySnapshot(registry) {
+    if (typeof registry !== "object" ||
+        registry === null ||
+        typeof registry.listNormalInvocations !== "function") {
+        throw new RegisteredToolWorkerCapabilityCompositionError("normal_invocation_registry_unavailable");
+    }
+    const registrations = Reflect.apply(registry.listNormalInvocations, registry, []);
+    if (!Array.isArray(registrations)) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("normal_invocation_registry_invalid");
+    }
+    return Object.freeze([...registrations]);
+}
+function resolveAvailableOperations(registrations, payloadAuthorAvailable) {
+    const selected = registrations.flatMap((registration) => registration.contract.operations.map((operation) => {
+        const stagedPayloadPlan = deriveRegisteredToolStagedPayloadPlan(registration.definition, operation);
+        return Object.freeze({
+            registration,
+            operation,
+            ...(stagedPayloadPlan ? { stagedPayloadPlan } : {}),
+        });
+    }));
+    if (selected.length > WORKER_CAPABILITY_COUNT_MAX) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("operation_count_exceeded");
+    }
+    const seen = new Set();
+    for (const entry of selected) {
+        const operationId = entry.operation.operationId;
+        if (seen.has(operationId)) {
+            throw new RegisteredToolWorkerCapabilityCompositionError("operation_ambiguous", operationId);
+        }
+        seen.add(operationId);
+        validateWorkerOperation(entry.operation, entry.stagedPayloadPlan, payloadAuthorAvailable);
+    }
+    return Object.freeze(selected);
+}
+function validateWorkerOperation(operation, stagedPayloadPlan, payloadAuthorAvailable) {
+    if (!isRoleCapabilityId(operation.operationId)) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("capability_id_unsupported", operation.operationId);
+    }
+    if (operation.effect !== "read_only" &&
+        operation.effect !== "mutating" &&
+        operation.effect !== "mixed") {
+        throw new RegisteredToolWorkerCapabilityCompositionError("operation_effect_unsupported", operation.operationId);
+    }
+    if (!normalizeWorkerCapabilityControlsSchema(stagedPayloadPlan?.publicInput ?? operation.input).ok) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("operation_controls_unsupported", operation.operationId);
+    }
+    if (operation.payload && !payloadAuthorAvailable) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("operation_payload_author_unavailable", operation.operationId);
+    }
+}
+function projectWorkerDescriptor(definition, operation, stagedPayloadPlan) {
+    const controls = normalizeWorkerCapabilityControlsSchema(stagedPayloadPlan?.publicInput ?? operation.input);
+    if (!controls.ok) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("operation_controls_unsupported", operation.operationId);
+    }
+    const selectionControlIds = definition.payloadChannelSpec?.targetRole === "operation_target"
+        ? definition.payloadChannelSpec.targetParam
+            ? [definition.payloadChannelSpec.targetParam]
+            : undefined
+        : [];
+    const controlsPartition = partitionWorkerCapabilityControlsSchema(controls.value, selectionControlIds);
+    if (!controlsPartition.ok || selectionControlIds === undefined) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("operation_target_control_invalid", operation.operationId);
+    }
+    const runtimePathControlIds = projectRuntimePathControlIds(definition, operation, controls.value);
+    const effect = operation.effect === "mutating"
+        ? "mutation"
+        : operation.effect === "mixed"
+            ? "mixed"
+            : "observation";
+    const catalogGroups = Object.freeze([
+        ...(definition.catalogGroups ?? ["other"]),
+    ]);
+    return Object.freeze({
+        capabilityId: operation.operationId,
+        summary: operation.summary,
+        effect,
+        controls: controls.value,
+        ...(runtimePathControlIds.length > 0 ? { runtimePathControlIds } : {}),
+        ...(controlsPartition.value.selectionControlIds.length > 0
+            ? { selectionControlIds: controlsPartition.value.selectionControlIds }
+            : {}),
+        ...(definition.controlsRefinement
+            ? { controlsRefinement: definition.controlsRefinement }
+            : {}),
+        catalogGroups,
+    });
+}
+function projectRuntimePathControlIds(definition, operation, controls) {
+    const controlIds = projectRuntimePathBindings(definition, operation).map(({ param }) => param);
+    if (controlIds.length === 0) {
+        return Object.freeze([]);
+    }
+    if (new Set(controlIds).size !== controlIds.length ||
+        controlIds.some((controlId) => typeof controlId !== "string" ||
+            !Object.hasOwn(controls.properties, controlId))) {
+        throw new RegisteredToolWorkerCapabilityCompositionError("operation_runtime_path_control_invalid", operation.operationId);
+    }
+    return Object.freeze([...controlIds]);
+}
+export function narrowRegistrations(selections) {
+    const selectedByRegistration = new Map();
+    for (const selection of selections) {
+        const operations = selectedByRegistration.get(selection.registration) ?? [];
+        operations.push(selection.operation);
+        selectedByRegistration.set(selection.registration, operations);
+    }
+    return Object.freeze([...selectedByRegistration].map(([registration, operations]) => Object.freeze({
+        toolName: registration.toolName,
+        definition: registration.definition,
+        contract: Object.freeze({
+            version: registration.contract.version,
+            operations: Object.freeze([...operations]),
+        }),
+        ...(registration.adapter ? { adapter: registration.adapter } : {}),
+    })));
+}
+export function prepareSharedState(registry, sessionId, requestContext) {
+    const initial = Object.freeze({
+        currentSessionId: sessionId,
+        ...(requestContext ? { requestContext } : {}),
+    });
+    return registry.prepareSharedState
+        ? registry.prepareSharedState(initial)
+        : initial;
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/contracts.d.ts

@@ -0,0 +1,33 @@
+import type { RegisteredToolNormalInvocation, ToolExecutionRequestContext, ToolNormalInvocationOperation } from "../../../capabilities/tool-types.js";
+import type { WorkerCapabilityDescriptor, WorkerCapabilityPayloadAuthor } from "../../orchestration/worker-capabilities/index.js";
+import type { ToolApprovalController, ToolPermissionMode, ToolRegistry } from "../../ports.js";
+import type { RegisteredToolStagedPayloadPlan } from "../registered-tool-payload-plan.js";
+export type RegisteredToolWorkerCapabilityProviderParams = Readonly<{
+    /**
+     * Must return the already config-filtered, request-bound registry. The
+     * callback is first invoked when a caller requests the public descriptor
+     * catalog. Execution state and adapters remain lazy until getAdapters().
+     */
+    getRequestToolRegistry(): ToolRegistry;
+    requestId: string;
+    sessionId: string;
+    requestContext?: ToolExecutionRequestContext;
+    abortSignal: AbortSignal;
+    toolPermissionMode: ToolPermissionMode;
+    toolApprovalController?: ToolApprovalController;
+    payloadAuthor?: WorkerCapabilityPayloadAuthor;
+    loadActionSkillContext?(toolName: string): Promise<string>;
+    nextApprovalId(): string;
+    onEvent?(name: string, payload: Record<string, unknown>): void;
+}>;
+export type SelectedOperation = Readonly<{
+    registration: RegisteredToolNormalInvocation;
+    operation: ToolNormalInvocationOperation;
+    stagedPayloadPlan?: RegisteredToolStagedPayloadPlan;
+}>;
+export type ResolvedCapabilityCatalog = Readonly<{
+    registry: ToolRegistry;
+    selected: readonly SelectedOperation[];
+    operationIds: readonly string[];
+    descriptors: readonly WorkerCapabilityDescriptor[];
+}>;

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/contracts.js

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

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class RegisteredToolWorkerCapabilityCompositionError extends TypeError {
+    readonly issueCode: string;
+    readonly operationId?: string;
+    constructor(issueCode: string, operationId?: string);
+}
+export declare class RegisteredToolWorkerCapabilityExecutionError extends TypeError {
+    readonly issueCode: string;
+    constructor(issueCode: string);
+}
+export declare function executionProtocolError(issueCode: string): RegisteredToolWorkerCapabilityExecutionError;
+export declare function normalizeResolutionError(error: unknown): Error;

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/errors.js

@@ -0,0 +1,30 @@
+export class RegisteredToolWorkerCapabilityCompositionError extends TypeError {
+    issueCode;
+    operationId;
+    constructor(issueCode, operationId) {
+        super([
+            "registered_tool_worker_capability_provider",
+            issueCode,
+            ...(operationId ? [operationId] : []),
+        ].join(":"));
+        this.name = "RegisteredToolWorkerCapabilityCompositionError";
+        this.issueCode = issueCode;
+        this.operationId = operationId;
+    }
+}
+export class RegisteredToolWorkerCapabilityExecutionError extends TypeError {
+    issueCode;
+    constructor(issueCode) {
+        super(`registered_tool_worker_capability_execution:${issueCode}`);
+        this.name = "RegisteredToolWorkerCapabilityExecutionError";
+        this.issueCode = issueCode;
+    }
+}
+export function executionProtocolError(issueCode) {
+    return new RegisteredToolWorkerCapabilityExecutionError(issueCode);
+}
+export function normalizeResolutionError(error) {
+    return error instanceof RegisteredToolWorkerCapabilityCompositionError
+        ? error
+        : new RegisteredToolWorkerCapabilityCompositionError("resolution_failed");
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/execution.d.ts

@@ -0,0 +1,12 @@
+import type { ToolExecutionSharedState } from "../../../capabilities/tool-types.js";
+import { type WorkerCapabilityAdapter, type WorkerCapabilityDescriptor, type WorkerCapabilityPayloadAuthor } from "../../orchestration/worker-capabilities/index.js";
+import type { RegisteredToolNormalInvocationExecutor } from "../registered-tool-normal-invocations.js";
+import { type RegisteredToolWorkerCapabilityProviderDiagnostic } from "../registered-tool-worker-capability-diagnostics.js";
+export declare function projectWorkerAdapters<TContext>(params: Readonly<{
+    operationIds: readonly string[];
+    descriptors: readonly WorkerCapabilityDescriptor[];
+    executor: RegisteredToolNormalInvocationExecutor;
+    sharedState: ToolExecutionSharedState;
+    diagnostic: RegisteredToolWorkerCapabilityProviderDiagnostic;
+    payloadAuthor?: WorkerCapabilityPayloadAuthor;
+}>): readonly WorkerCapabilityAdapter<TContext>[];

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/execution.js

@@ -0,0 +1,155 @@
+import { assertWorkerCapabilityWithinScope, projectWorkerCapabilityScope, WorkerCapabilityScopeError, } from "../../orchestration/worker-capabilities/index.js";
+import { traceRegisteredToolWorkerCapabilityExecutionCompleted, traceRegisteredToolWorkerCapabilityExecutionFailed, traceRegisteredToolWorkerCapabilityExecutionStarted, } from "../registered-tool-worker-capability-diagnostics.js";
+import { RegisteredToolWorkerCapabilityCompositionError, RegisteredToolWorkerCapabilityExecutionError, } from "./errors.js";
+import { executionFreshnessRejection, prepareOperationPayload, } from "./payload-lifecycle.js";
+import { attachTargetReferences, observeExternalResult, projectSelectedTargetReferences, } from "./result-observer.js";
+import { resolveEffectiveOperationTargetControls } from "./runtime-path-controls.js";
+export function projectWorkerAdapters(params) {
+    const projections = new Map();
+    for (const projection of params.executor.operations) {
+        const operationId = projection.operation.operationId;
+        if (projections.has(operationId)) {
+            throw new RegisteredToolWorkerCapabilityCompositionError("projected_operation_ambiguous", operationId);
+        }
+        projections.set(operationId, projection);
+    }
+    const descriptors = new Map(params.descriptors.map((descriptor) => [
+        descriptor.capabilityId,
+        descriptor,
+    ]));
+    return Object.freeze(params.operationIds.map((operationId) => {
+        const projection = projections.get(operationId);
+        const descriptor = descriptors.get(operationId);
+        if (!projection || !descriptor) {
+            throw new RegisteredToolWorkerCapabilityCompositionError("projected_operation_unavailable", operationId);
+        }
+        return createWorkerAdapter({
+            projection,
+            descriptor,
+            scopeDescriptors: params.descriptors,
+            executor: params.executor,
+            sharedState: params.sharedState,
+            diagnostic: params.diagnostic,
+            ...(params.payloadAuthor
+                ? { payloadAuthor: params.payloadAuthor }
+                : {}),
+        });
+    }));
+}
+function createWorkerAdapter(params) {
+    const operationId = params.projection.operation.operationId;
+    const operationEffect = params.projection.operation.effect;
+    return Object.freeze({
+        descriptor: params.descriptor,
+        async execute(input) {
+            try {
+                const capabilityScope = projectWorkerCapabilityScope({
+                    entries: params.scopeDescriptors,
+                    scope: input.call.workerCapabilityScope,
+                    descriptorOf: (descriptor) => descriptor,
+                });
+                assertWorkerCapabilityWithinScope(capabilityScope, params.descriptor);
+            }
+            catch (error) {
+                const scopedError = error instanceof WorkerCapabilityScopeError
+                    ? new RegisteredToolWorkerCapabilityCompositionError(error.issueCode, operationId)
+                    : error;
+                traceRegisteredToolWorkerCapabilityExecutionFailed(params.diagnostic, operationId, input.call, input.executionId, scopedError, error instanceof WorkerCapabilityScopeError
+                    ? error.issueCode
+                    : "capability_scope_validation_failed");
+                throw scopedError;
+            }
+            traceRegisteredToolWorkerCapabilityExecutionStarted(params.diagnostic, operationId, input.call, input.executionId, input.intent.length, Object.keys(input.controls).length);
+            try {
+                const effectiveControls = resolveEffectiveOperationTargetControls({
+                    descriptor: params.descriptor,
+                    controls: input.controls,
+                    runtimePathBindings: params.projection.runtimePathBindings ?? Object.freeze([]),
+                    workingDirectory: input.call.workingDirectory,
+                    sharedState: params.sharedState,
+                });
+                const selectedTargetReferences = projectSelectedTargetReferences(params.projection, effectiveControls, input.call.parentCallId === null
+                    ? params.descriptor.selectionControlIds
+                    : undefined);
+                const preparedPayload = await prepareOperationPayload({
+                    projection: params.projection,
+                    executor: params.executor,
+                    sharedState: params.sharedState,
+                    ...(params.payloadAuthor
+                        ? { payloadAuthor: params.payloadAuthor }
+                        : {}),
+                    call: input.call,
+                    executionId: input.executionId,
+                    descriptor: params.descriptor,
+                    intent: input.intent,
+                    controls: effectiveControls,
+                    ...(input.dependencyResults
+                        ? { dependencyResults: input.dependencyResults }
+                        : {}),
+                    settledCapabilityResults: input.settledCapabilityResults,
+                    diagnostic: params.diagnostic,
+                    ...(input.executionFreshness
+                        ? { executionFreshness: input.executionFreshness }
+                        : {}),
+                });
+                const completeRejectedExecution = (rejectedExecution) => {
+                    const canonicalResult = Object.freeze({
+                        ...rejectedExecution.result,
+                        exactResult: rejectedExecution.exactResult,
+                    });
+                    const preparedResult = attachTargetReferences(canonicalResult, selectedTargetReferences);
+                    traceRegisteredToolWorkerCapabilityExecutionCompleted(params.diagnostic, operationId, input.call, input.executionId, preparedResult, "rejected", {
+                        sourceIssueCode: rejectedExecution.sourceIssueCode,
+                        summaryProjection: "runtime_rejection",
+                        completionActions: Object.freeze([]),
+                    });
+                    return preparedResult;
+                };
+                if (preparedPayload.status === "rejected") {
+                    return completeRejectedExecution(preparedPayload);
+                }
+                const rejectedExecution = executionFreshnessRejection(input.executionFreshness);
+                if (rejectedExecution) {
+                    return completeRejectedExecution(rejectedExecution);
+                }
+                const externalResult = await params.executor.execute({
+                    handle: params.projection.handle,
+                    controls: effectiveControls,
+                    ...(preparedPayload.body === undefined
+                        ? {}
+                        : { payload: preparedPayload.body }),
+                    ...(preparedPayload.materializedParams === undefined
+                        ? {}
+                        : {
+                            materializedParams: preparedPayload.materializedParams,
+                        }),
+                    intent: input.intent,
+                });
+                const observed = observeExternalResult(externalResult, operationEffect, input.call.parentCallId === null);
+                const observedResult = attachTargetReferences(observed.result, selectedTargetReferences);
+                traceRegisteredToolWorkerCapabilityExecutionCompleted(params.diagnostic, operationId, input.call, input.executionId, observedResult, externalResult.status, {
+                    ...(observed.sourceIssueCode
+                        ? { sourceIssueCode: observed.sourceIssueCode }
+                        : {}),
+                    summaryProjection: externalResult.status === "executed" &&
+                        observedResult.outcome === "succeeded" &&
+                        observedResult.observedEffect === "mutation"
+                        ? externalResult.completionActions.length > 0
+                            ? "logical_completion_actions"
+                            : "mutation_evidence_only"
+                        : "bounded_external_result",
+                    completionActions: externalResult.status === "executed"
+                        ? externalResult.completionActions
+                        : Object.freeze([]),
+                });
+                return observedResult;
+            }
+            catch (error) {
+                traceRegisteredToolWorkerCapabilityExecutionFailed(params.diagnostic, operationId, input.call, input.executionId, error, error instanceof RegisteredToolWorkerCapabilityExecutionError
+                    ? error.issueCode
+                    : "execution_failed");
+                throw error;
+            }
+        },
+    });
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-authoring-result.d.ts

@@ -0,0 +1,5 @@
+import type { WorkerCapabilityPayloadAuthoringResult } from "../../orchestration/worker-capabilities/index.js";
+export declare function normalizePayloadAuthoringResult(input: unknown, minBytes: number, maxBytes: number, responseFormat?: "json" | Readonly<Record<string, unknown>>): WorkerCapabilityPayloadAuthoringResult | Readonly<{
+    status: "failed";
+    code: "payload_author_result_invalid";
+}>;

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-authoring-result.js

@@ -0,0 +1,60 @@
+import { validateJsonSchemaValue } from "../../model/json-schema-value.js";
+import { isPlainRecord } from "./values.js";
+export function normalizePayloadAuthoringResult(input, minBytes, maxBytes, responseFormat) {
+    if (!isPlainRecord(input) || Object.keys(input).length !== 2) {
+        return Object.freeze({
+            status: "failed",
+            code: "payload_author_result_invalid",
+        });
+    }
+    if (input.status === "authored" && typeof input.body === "string") {
+        const body = normalizeAdapterAuthoredBody(input.body, responseFormat);
+        if (body === undefined) {
+            return Object.freeze({
+                status: "failed",
+                code: "payload_model_output_invalid",
+            });
+        }
+        const payloadBytes = Buffer.byteLength(body, "utf8");
+        if (payloadBytes < minBytes) {
+            return Object.freeze({
+                status: "failed",
+                code: "payload_body_too_small",
+            });
+        }
+        if (payloadBytes <= maxBytes) {
+            return Object.freeze({ status: "authored", body });
+        }
+    }
+    if (input.status === "failed" && isPayloadAuthorFailureCode(input.code)) {
+        return Object.freeze({ status: "failed", code: input.code });
+    }
+    return Object.freeze({
+        status: "failed",
+        code: "payload_author_result_invalid",
+    });
+}
+function normalizeAdapterAuthoredBody(body, responseFormat) {
+    if (!responseFormat)
+        return body;
+    try {
+        const parsed = JSON.parse(body);
+        if (responseFormat !== "json" &&
+            validateJsonSchemaValue(responseFormat, parsed)) {
+            return undefined;
+        }
+        return JSON.stringify(parsed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPayloadAuthorFailureCode(input) {
+    return (input === "payload_context_invalid" ||
+        input === "payload_context_budget_exceeded" ||
+        input === "payload_model_unavailable" ||
+        input === "payload_model_invocation_failed" ||
+        input === "payload_model_output_invalid" ||
+        input === "payload_body_too_small" ||
+        input === "payload_body_too_large");
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-lifecycle.d.ts

@@ -0,0 +1,30 @@
+import type { ToolExecutionSharedState } from "../../../capabilities/tool-types.js";
+import type { CapabilityAdapterResult } from "../../orchestration/capability-adapters/index.js";
+import type { WorkerCapabilityAdapterResult, WorkerCapabilityExecutionFreshness, WorkerCapabilityPayloadAuthor } from "../../orchestration/worker-capabilities/index.js";
+import type { RegisteredToolNormalInvocationExecutor, RegisteredToolNormalInvocationProjection } from "../registered-tool-normal-invocations.js";
+import type { RegisteredToolWorkerCapabilityProviderDiagnostic } from "../registered-tool-worker-capability-diagnostics.js";
+export declare function prepareOperationPayload(params: Readonly<{
+    projection: RegisteredToolNormalInvocationProjection;
+    executor: RegisteredToolNormalInvocationExecutor;
+    sharedState: ToolExecutionSharedState;
+    payloadAuthor?: WorkerCapabilityPayloadAuthor;
+    call: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["call"];
+    executionId: string;
+    descriptor: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["descriptor"];
+    intent: string;
+    controls: Readonly<Record<string, unknown>>;
+    dependencyResults?: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["dependencyResults"];
+    settledCapabilityResults: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["settledCapabilityResults"];
+    diagnostic: RegisteredToolWorkerCapabilityProviderDiagnostic;
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}>): Promise<Readonly<{
+    status: "ready";
+    body?: string;
+    materializedParams?: Readonly<Record<string, string>>;
+}> | Readonly<{
+    status: "rejected";
+    result: WorkerCapabilityAdapterResult;
+    sourceIssueCode: string;
+    exactResult: CapabilityAdapterResult;
+}>>;
+export { executionFreshnessRejection, payloadRejection, } from "./payload-rejection.js";

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-lifecycle.js

@@ -0,0 +1,119 @@
+import { resolveRegisteredToolPayloadRelatedArtifactContexts } from "../registered-tool-payload-plan.js";
+import { normalizePayloadAuthoringResult } from "./payload-authoring-result.js";
+import { executionFreshnessRejection, payloadRejection, rejectPayloadLifecycle, STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, } from "./payload-rejection.js";
+import { prepareStagedOperationPayload } from "./payload-stages.js";
+export async function prepareOperationPayload(params) {
+    if (params.projection.stagedPayloadPlan) {
+        return prepareStagedOperationPayload({
+            plan: params.projection.stagedPayloadPlan,
+            handle: params.projection.handle,
+            executor: params.executor,
+            sharedState: params.sharedState,
+            ...(params.payloadAuthor ? { payloadAuthor: params.payloadAuthor } : {}),
+            call: params.call,
+            executionId: params.executionId,
+            descriptor: params.descriptor,
+            intent: params.intent,
+            controls: params.controls,
+            ...(params.dependencyResults
+                ? { dependencyResults: params.dependencyResults }
+                : {}),
+            settledCapabilityResults: params.settledCapabilityResults,
+            diagnostic: params.diagnostic,
+            ...(params.executionFreshness
+                ? { executionFreshness: params.executionFreshness }
+                : {}),
+        });
+    }
+    const contract = params.projection.operation.payload;
+    if (!contract) {
+        return Object.freeze({ status: "ready" });
+    }
+    if (!params.payloadAuthor) {
+        return payloadRejection("operation_payload_author_unavailable", "The capability payload author is unavailable.");
+    }
+    const lifecycle = {
+        handle: params.projection.handle,
+        controls: params.controls,
+        intent: params.intent,
+    };
+    const started = params.executor.emitPayloadLifecycle({
+        ...lifecycle,
+        phase: "started",
+    });
+    if (started.status === "rejected") {
+        return payloadRejection(started.code, started.message);
+    }
+    let rawAuthored;
+    try {
+        const contextScope = params.projection.payloadContextPlan?.contextScope ?? "standard";
+        const relatedArtifactContexts = await resolveRegisteredToolPayloadRelatedArtifactContexts({
+            contextScope,
+            targetParam: params.projection.payloadContextPlan?.targetParam,
+            controls: params.controls,
+            sharedState: params.sharedState,
+            settledCapabilityResults: params.settledCapabilityResults,
+        });
+        rawAuthored = await params.payloadAuthor.author({
+            call: params.call,
+            executionId: params.executionId,
+            descriptor: params.descriptor,
+            controls: params.controls,
+            contextScope,
+            ...(params.dependencyResults
+                ? { dependencyResults: params.dependencyResults }
+                : {}),
+            settledCapabilityResults: params.settledCapabilityResults,
+            ...(params.executionFreshness
+                ? { requestSteering: params.executionFreshness.token }
+                : {}),
+            ...(relatedArtifactContexts.length > 0
+                ? { relatedArtifactContexts }
+                : {}),
+            contract: {
+                instructions: contract.instructions,
+                minBytes: contract.minBytes ?? 0,
+                maxBytes: contract.maxBytes,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw error;
+        }
+        return rejectPayloadLifecycle({
+            executor: params.executor,
+            lifecycle,
+            code: "payload_author_failed",
+            message: "The capability payload could not be prepared.",
+        });
+    }
+    const superseded = executionFreshnessRejection(params.executionFreshness);
+    if (superseded) {
+        return rejectPayloadLifecycle({
+            executor: params.executor,
+            lifecycle,
+            code: STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION,
+            message: STEERING_SUPERSEDED_SUMMARY,
+            fallback: superseded,
+        });
+    }
+    const authored = normalizePayloadAuthoringResult(rawAuthored, contract.minBytes ?? 0, contract.maxBytes);
+    if (authored.status === "failed") {
+        return rejectPayloadLifecycle({
+            executor: params.executor,
+            lifecycle,
+            code: authored.code,
+            message: "The capability payload could not be prepared.",
+        });
+    }
+    const completed = params.executor.emitPayloadLifecycle({
+        ...lifecycle,
+        phase: "completed",
+    });
+    if (completed.status === "rejected") {
+        return payloadRejection(completed.code, completed.message);
+    }
+    return Object.freeze({ status: "ready", body: authored.body });
+}
+export { executionFreshnessRejection, payloadRejection, } from "./payload-rejection.js";

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-rejection.d.ts

@@ -0,0 +1,20 @@
+import type { CapabilityAdapterResult } from "../../orchestration/capability-adapters/index.js";
+import type { WorkerCapabilityAdapterResult, WorkerCapabilityExecutionFreshness } from "../../orchestration/worker-capabilities/index.js";
+import type { RegisteredToolNormalInvocationExecutor } from "../registered-tool-normal-invocations.js";
+export declare const STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION: "steering_superseded_before_external_execution";
+export declare const STEERING_SUPERSEDED_SUMMARY = "steering_superseded_before_external_execution: No external execution occurred because a newer active-request update superseded this capability invocation.";
+export type PayloadLifecycleContext = Readonly<Omit<Parameters<RegisteredToolNormalInvocationExecutor["emitPayloadLifecycle"]>[0], "phase" | "errorCode">>;
+export declare function rejectPayloadLifecycle(params: {
+    executor: RegisteredToolNormalInvocationExecutor;
+    lifecycle: PayloadLifecycleContext;
+    code: string;
+    message: string;
+    fallback?: ReturnType<typeof payloadRejection>;
+}): ReturnType<typeof payloadRejection>;
+export declare function payloadRejection(sourceIssueCode: string, summary: string): Readonly<{
+    status: "rejected";
+    result: WorkerCapabilityAdapterResult;
+    sourceIssueCode: string;
+    exactResult: CapabilityAdapterResult;
+}>;
+export declare function executionFreshnessRejection(freshness: WorkerCapabilityExecutionFreshness | undefined): ReturnType<typeof payloadRejection> | undefined;