@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/prepared-execution.js

@@ -0,0 +1,152 @@
+import { requiresToolActionApproval } from "../../../../capabilities/tool-permission-mode.js";
+import { buildToolCompletedEventActions, buildToolCompletedEventMetadata, buildToolLifecycleEventCopy, } from "../../../../capabilities/tool-event-metadata.js";
+import { buildToolExecutorEventMetadata, } from "../shared/event-metadata.js";
+import { requestNormalInvocationApproval } from "./approval.js";
+import { createPreparedInvocationRejectionEmitter } from "./rejection-event.js";
+import { createFileOutputPresentation } from "./file-output-presentation.js";
+import { executeWithToolResources } from "./tool-media-execution.js";
+export function createPreparedNormalInvocation(params) {
+    const force = params.source.operation.approval === "always" ||
+        params.target.operation.approval === "always";
+    const approvalRequest = requiresToolActionApproval(params.executor.toolPermissionMode, force)
+        ? Object.freeze({
+            ...(params.restoredApprovalRequest ?? {
+                requestId: params.executor.requestId,
+                approvalId: params.executor.nextApprovalId(),
+                call: params.call,
+                ...(params.eventMeta ? { meta: params.eventMeta } : {}),
+            }),
+            call: params.call,
+        })
+        : undefined;
+    const identity = (binding) => ({
+        tool: binding.registration.toolName,
+        operationId: binding.operation.operationId,
+        contractVersion: binding.registration.contract.version,
+    });
+    const snapshot = Object.freeze(structuredClone({
+        kind: "registered_tool_normal_invocation_v1",
+        source: identity(params.source),
+        target: identity(params.target),
+        call: params.call,
+        acceptedControls: params.acceptedControls,
+        actionFingerprint: params.actionFingerprint,
+        toolPermissionMode: params.executor.toolPermissionMode,
+        ...(params.intent ? { intent: params.intent } : {}),
+        ...(params.eventMeta ? { eventMeta: params.eventMeta } : {}),
+        ...(params.executionIdentity
+            ? { executionIdentity: params.executionIdentity }
+            : {}),
+        ...(approvalRequest ? { approvalRequest } : {}),
+    }));
+    let decision;
+    let decisionRecorded = false;
+    return Object.freeze({
+        status: "prepared",
+        actionFingerprint: params.actionFingerprint,
+        acceptedControls: params.acceptedControls,
+        snapshot,
+        ...(approvalRequest ? { approvalRequest } : {}),
+        applyApprovalDecision(bound) {
+            if (!approvalRequest ||
+                bound.approvalId !== approvalRequest.approvalId ||
+                bound.actionFingerprint !== params.actionFingerprint ||
+                decision)
+                throw new Error("prepared_approval_decision_mismatch");
+            decision = Object.freeze({ ...bound.decision });
+            decisionRecorded = bound.recorded === true;
+        },
+        emitRejection: createPreparedInvocationRejectionEmitter({
+            tool: params.source.registration.toolName,
+            eventMeta: params.eventMeta,
+            onEvent: params.executor.onEvent,
+        }),
+        execute: (executionId, executorIdentity) => executePreparedNormalInvocation({
+            ...params,
+            ...(approvalRequest ? { approvalRequest } : {}),
+            ...(decision ? { decision, decisionRecorded } : {}),
+            ...(executionId ? { executionId } : {}),
+            ...(executorIdentity ? { executorIdentity } : {}),
+        }),
+    });
+}
+async function executePreparedNormalInvocation(params) {
+    const approval = await requestNormalInvocationApproval({
+        ...(params.approvalRequest
+            ? { preparedRequest: params.approvalRequest }
+            : {}),
+        ...(params.decision
+            ? { decision: params.decision, decisionRecorded: params.decisionRecorded }
+            : {}),
+        ...(params.executorIdentity
+            ? { executorIdentity: params.executorIdentity }
+            : {}),
+        ...(params.executionId ? { executionId: params.executionId } : {}),
+        requestId: params.executor.requestId,
+        abortSignal: params.executor.abortSignal,
+        toolPermissionMode: params.executor.toolPermissionMode,
+        ...(params.executor.toolApprovalController
+            ? { toolApprovalController: params.executor.toolApprovalController }
+            : {}),
+        nextApprovalId: params.executor.nextApprovalId,
+        ...(params.executor.onEvent ? { onEvent: params.executor.onEvent } : {}),
+        call: params.call,
+        ...(params.eventMeta ? { eventMeta: params.eventMeta } : {}),
+        force: params.source.operation.approval === "always" ||
+            params.target.operation.approval === "always",
+    });
+    if (!approval.ok)
+        return approval.rejection;
+    params.executor.abortSignal.throwIfAborted();
+    const startedCopy = buildToolLifecycleEventCopy(params.target.registration.definition, "started");
+    params.executor.onEvent?.("tool.started", {
+        ...buildToolExecutorEventMetadata(params.executorIdentity),
+        ...(params.executionId ? { executionId: params.executionId } : {}),
+        tool: params.call.tool,
+        ...(params.intent ? { intent: params.intent, intentSource: "model" } : {}),
+        ...(params.eventMeta ? { meta: params.eventMeta } : {}),
+        ...(startedCopy ?? {}),
+    });
+    const fileOutputPresentation = createFileOutputPresentation(params.executor.sharedState?.runtimePaths);
+    const result = await executeWithToolResources({
+        registry: params.executor.toolRegistry,
+        call: params.call,
+        resources: params.executor.toolResources,
+        ...(params.executionId && params.executorIdentity
+            ? {
+                owner: {
+                    executionId: params.executionId,
+                    callId: params.executorIdentity.callId,
+                },
+            }
+            : {}),
+        options: {
+            abortSignal: params.executor.abortSignal,
+            reportFileOutput: fileOutputPresentation.report,
+            ...(params.executor.sharedState
+                ? { sharedState: params.executor.sharedState }
+                : {}),
+        },
+    });
+    const completionActions = Object.freeze(buildToolCompletedEventActions(params.call, result, params.target.registration.definition).map((action) => Object.freeze({ ...action })));
+    const completedMeta = fileOutputPresentation.finish(result, buildToolCompletedEventMetadata(params.call, result, params.target.registration.definition), params.target.operation.effect);
+    const completedCopy = buildToolLifecycleEventCopy(params.target.registration.definition, result.ok ? "completed" : "failed");
+    const completedEventMeta = params.executionMetadata
+        ? { ...completedMeta, ...params.executionMetadata }
+        : completedMeta;
+    params.executor.onEvent?.("tool.completed", {
+        ...buildToolExecutorEventMetadata(params.executorIdentity),
+        ...(params.executionId ? { executionId: params.executionId } : {}),
+        tool: params.source.registration.toolName,
+        ok: result.ok,
+        actions: completionActions,
+        ...(completedEventMeta ? { meta: completedEventMeta } : {}),
+        ...(completedCopy ?? {}),
+    });
+    return Object.freeze({
+        status: "executed",
+        effect: params.target.operation.effect,
+        result,
+        completionActions,
+    });
+}

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/prepared-snapshot.d.ts

@@ -0,0 +1,28 @@
+import type { ToolCall, RegisteredToolNormalInvocation } from "../../../../capabilities/tool-types.js";
+import type { ToolApprovalRequest, ToolPermissionMode } from "../../../ports.js";
+import type { RegisteredToolNormalInvocationExecutorParams, RegisteredToolNormalInvocationPreparation } from "../shared/contracts.js";
+type OperationIdentity = Readonly<{
+    tool: string;
+    operationId: string;
+    contractVersion: number;
+}>;
+export type RegisteredToolInvocationSnapshot = Readonly<{
+    kind: "registered_tool_normal_invocation_v1";
+    source: OperationIdentity;
+    target: OperationIdentity;
+    call: ToolCall;
+    acceptedControls: Readonly<Record<string, unknown>>;
+    actionFingerprint: string;
+    toolPermissionMode: ToolPermissionMode;
+    intent?: string;
+    eventMeta?: Record<string, unknown>;
+    executionIdentity?: string;
+    approvalRequest?: ToolApprovalRequest;
+}>;
+/** Validate a saved exact call; restoration never invokes normalization or payload authoring. */
+export declare function restoreNormalInvocation(params: {
+    executor: RegisteredToolNormalInvocationExecutorParams;
+    registrations: readonly RegisteredToolNormalInvocation[];
+    snapshot: unknown;
+}): RegisteredToolNormalInvocationPreparation;
+export {};

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/prepared-snapshot.js

@@ -0,0 +1,118 @@
+import { permitsRequiredToolMode, requiresToolActionApproval, } from "../../../../capabilities/tool-permission-mode.js";
+import { createRegisteredToolActionFingerprint } from "../shared/action-fingerprint.js";
+import { captureToolCall, resolveExactTargetOperation, validateCompleteCall, } from "./call-binding.js";
+import { captureExecutionBinding } from "./execution-binding.js";
+import { createPreparedNormalInvocation } from "./prepared-execution.js";
+/** Validate a saved exact call; restoration never invokes normalization or payload authoring. */
+export function restoreNormalInvocation(params) {
+    const value = params.snapshot;
+    if (!isInvocationSnapshot(value))
+        throw invalid();
+    if (value.toolPermissionMode !== params.executor.toolPermissionMode)
+        throw invalid();
+    const source = findOperation(params.registrations, value.source);
+    const target = findOperation(params.registrations, value.target);
+    const call = captureToolCall(value.call);
+    if (!source || !target || !call || call.tool !== target.registration.toolName)
+        throw invalid();
+    const resolved = resolveExactTargetOperation(params.registrations, call);
+    if (!resolved.ok ||
+        resolved.binding.operation.operationId !== target.operation.operationId)
+        throw invalid();
+    if (source.operation.effect !== target.operation.effect)
+        throw invalid();
+    for (const binding of [source, target]) {
+        if (!permitsRequiredToolMode(params.executor.toolPermissionMode, binding.registration.definition.requiredPermissionMode))
+            throw invalid();
+    }
+    const validation = validateCompleteCall({
+        adapter: target.registration.adapter,
+        call,
+        rejectedCode: "checkpoint_call_invalid",
+        failedCode: "checkpoint_validation_failed",
+        failedMessage: "The saved invocation could not be validated.",
+    });
+    if (!validation.ok)
+        throw invalid();
+    const binding = captureExecutionBinding(target.registration.adapter, call);
+    if (!binding.ok)
+        throw invalid();
+    const fingerprint = createRegisteredToolActionFingerprint({
+        contractVersion: target.registration.contract.version,
+        operationId: target.operation.operationId,
+        call,
+        ...(binding.identity ? { executionIdentity: binding.identity } : {}),
+    });
+    if (fingerprint !== value.actionFingerprint ||
+        binding.identity !== value.executionIdentity)
+        throw invalid();
+    const force = source.operation.approval === "always" ||
+        target.operation.approval === "always";
+    const required = requiresToolActionApproval(params.executor.toolPermissionMode, force);
+    if (required !== Boolean(value.approvalRequest))
+        throw invalid();
+    if (value.approvalRequest) {
+        if (!isRequestApproval(value.approvalRequest, params.executor.requestId))
+            throw invalid();
+        const approvalFingerprint = createRegisteredToolActionFingerprint({
+            contractVersion: target.registration.contract.version,
+            operationId: target.operation.operationId,
+            call: value.approvalRequest.call,
+            ...(binding.identity ? { executionIdentity: binding.identity } : {}),
+        });
+        if (approvalFingerprint !== fingerprint)
+            throw invalid();
+    }
+    return createPreparedNormalInvocation({
+        executor: params.executor,
+        source,
+        target,
+        call,
+        actionFingerprint: fingerprint,
+        acceptedControls: Object.freeze(structuredClone(value.acceptedControls)),
+        eventMeta: value.eventMeta,
+        ...(value.intent ? { intent: value.intent } : {}),
+        ...(binding.identity ? { executionIdentity: binding.identity } : {}),
+        ...(binding.metadata ? { executionMetadata: binding.metadata } : {}),
+        ...(value.approvalRequest
+            ? { restoredApprovalRequest: value.approvalRequest }
+            : {}),
+    });
+}
+function isInvocationSnapshot(value) {
+    if (!value || value.kind !== "registered_tool_normal_invocation_v1")
+        return false;
+    return (isRecord(value.acceptedControls) &&
+        isRecord(value.call) &&
+        typeof value.call.tool === "string" &&
+        isRecord(value.call.params) &&
+        typeof value.actionFingerprint === "string" &&
+        value.actionFingerprint.length > 0 &&
+        (value.intent === undefined || typeof value.intent === "string") &&
+        (value.eventMeta === undefined || isRecord(value.eventMeta)) &&
+        (value.executionIdentity === undefined ||
+            typeof value.executionIdentity === "string") &&
+        (value.approvalRequest === undefined || isRecord(value.approvalRequest)));
+}
+function isRequestApproval(approval, requestId) {
+    if (!isRecord(approval) ||
+        approval.requestId !== requestId ||
+        !isRecord(approval.call))
+        return false;
+    return (typeof approval.approvalId === "string" &&
+        approval.approvalId.trim().length > 0);
+}
+function findOperation(registrations, identity) {
+    if (!identity)
+        return undefined;
+    const registration = registrations.find((entry) => entry.toolName === identity.tool &&
+        entry.contract.version === identity.contractVersion);
+    const operation = registration?.contract.operations.find((entry) => entry.operationId === identity.operationId);
+    return registration && operation ? { registration, operation } : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalid() {
+    return new Error("registered_tool_snapshot_incompatible");
+}

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/run.js

@@ -1,13 +1,10 @@
 import { permitsRequiredToolMode } from "../../../../capabilities/tool-permission-mode.js";
-import { buildToolCompletedEventActions, buildToolCompletedEventMetadata, buildToolLifecycleEventCopy, } from "../../../../capabilities/tool-event-metadata.js";
-import { requestNormalInvocationApproval } from "./approval.js";
-import { createPreparedInvocationRejectionEmitter } from "./rejection-event.js";
+import { createPreparedNormalInvocation } from "./prepared-execution.js";
 import { captureToolCall, materializeCall, resolveExactTargetOperation, validateCompleteCall, } from "./call-binding.js";
 import { createRegisteredToolActionFingerprint } from "../shared/action-fingerprint.js";
-import { buildToolExecutorEventMetadata, buildToolIntentEventMetadata, } from "../shared/event-metadata.js";
+import { buildToolIntentEventMetadata } from "../shared/event-metadata.js";
 import { prepareCompleteInvocationInput } from "../payload/input-preparation.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
-import { createFileOutputPresentation } from "./file-output-presentation.js";
 import { captureExecutionBinding } from "./execution-binding.js";
 export async function executeNormalInvocation(params) {
     const prepared = prepareNormalInvocation(params);
@@ -74,92 +71,22 @@ export function prepareNormalInvocation(params) {
             ? { executionIdentity: executionBinding.identity }
             : {}),
     });
-    return Object.freeze({
-        status: "prepared",
+    return createPreparedNormalInvocation({
+        executor,
+        source,
+        target: target.binding,
+        call: normalizedCall.call,
         actionFingerprint,
         acceptedControls: preparedInput.controls,
-        emitRejection: createPreparedInvocationRejectionEmitter({
-            tool: source.registration.toolName,
-            eventMeta,
-            onEvent: executor.onEvent,
-        }),
-        execute: (executionId, executorIdentity) => executePreparedNormalInvocation({
-            ...(executionId ? { executionId } : {}),
-            ...(executorIdentity ? { executorIdentity } : {}),
-            executor,
-            source,
-            target: target.binding,
-            call: normalizedCall.call,
-            eventMeta,
-            ...(executionBinding.metadata
-                ? { executionMetadata: executionBinding.metadata }
-                : {}),
-            input: params.input,
-        }),
-    });
-}
-async function executePreparedNormalInvocation(params) {
-    const approval = await requestNormalInvocationApproval({
-        ...(params.executorIdentity
-            ? { executorIdentity: params.executorIdentity }
-            : {}),
-        ...(params.executionId ? { executionId: params.executionId } : {}),
-        requestId: params.executor.requestId,
-        abortSignal: params.executor.abortSignal,
-        toolPermissionMode: params.executor.toolPermissionMode,
-        ...(params.executor.toolApprovalController
-            ? { toolApprovalController: params.executor.toolApprovalController }
-            : {}),
-        nextApprovalId: params.executor.nextApprovalId,
-        ...(params.executor.onEvent ? { onEvent: params.executor.onEvent } : {}),
-        call: params.call,
-        ...(params.eventMeta ? { eventMeta: params.eventMeta } : {}),
-        force: params.source.operation.approval === "always" ||
-            params.target.operation.approval === "always",
-    });
-    if (!approval.ok)
-        return approval.rejection;
-    params.executor.abortSignal.throwIfAborted();
-    const startedCopy = buildToolLifecycleEventCopy(params.target.registration.definition, "started");
-    params.executor.onEvent?.("tool.started", {
-        ...buildToolExecutorEventMetadata(params.executorIdentity),
-        ...(params.executionId ? { executionId: params.executionId } : {}),
-        tool: params.call.tool,
-        ...(params.input.intent
-            ? { intent: params.input.intent, intentSource: "model" }
+        eventMeta,
+        ...(params.input.intent ? { intent: params.input.intent } : {}),
+        ...(executionBinding.identity
+            ? { executionIdentity: executionBinding.identity }
             : {}),
-        ...(params.eventMeta ? { meta: params.eventMeta } : {}),
-        ...(startedCopy ?? {}),
-    });
-    const fileOutputPresentation = createFileOutputPresentation(params.executor.sharedState?.runtimePaths);
-    const result = await params.executor.toolRegistry.execute(params.call, {
-        abortSignal: params.executor.abortSignal,
-        reportFileOutput: fileOutputPresentation.report,
-        ...(params.executor.sharedState
-            ? { sharedState: params.executor.sharedState }
+        ...(executionBinding.metadata
+            ? { executionMetadata: executionBinding.metadata }
             : {}),
     });
-    const completionActions = Object.freeze(buildToolCompletedEventActions(params.call, result, params.target.registration.definition).map((action) => Object.freeze({ ...action })));
-    const completedMeta = fileOutputPresentation.finish(result, buildToolCompletedEventMetadata(params.call, result, params.target.registration.definition), params.target.operation.effect);
-    const completedCopy = buildToolLifecycleEventCopy(params.target.registration.definition, result.ok ? "completed" : "failed");
-    const completedEventMeta = params.executionMetadata
-        ? { ...completedMeta, ...params.executionMetadata }
-        : completedMeta;
-    params.executor.onEvent?.("tool.completed", {
-        ...buildToolExecutorEventMetadata(params.executorIdentity),
-        ...(params.executionId ? { executionId: params.executionId } : {}),
-        tool: params.source.registration.toolName,
-        ok: result.ok,
-        actions: completionActions,
-        ...(completedEventMeta ? { meta: completedEventMeta } : {}),
-        ...(completedCopy ?? {}),
-    });
-    return Object.freeze({
-        status: "executed",
-        effect: params.target.operation.effect,
-        result,
-        completionActions,
-    });
 }
 function normalizeToolCall(source, sourceCall) {
     try {

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/tool-media-execution.d.ts

@@ -0,0 +1,12 @@
+import type { ToolCall } from "../../../../capabilities/tool-types.js";
+import type { ToolExecutionOptions, ToolRegistry } from "../../../ports.js";
+import type { RequestToolResources } from "../../../capabilities/request-tool-resources.js";
+import type { ToolMediaOwner } from "../../../attachments/request-tool-media.js";
+/** The admitted call, rather than a tool's arguments, owns every media write. */
+export declare function executeWithToolResources(params: {
+    registry: Pick<ToolRegistry, "execute">;
+    call: ToolCall;
+    options: ToolExecutionOptions;
+    resources?: RequestToolResources;
+    owner?: ToolMediaOwner;
+}): Promise<import("../../../../capabilities/tool-types.js").ToolExecutionResult>;

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/tool-media-execution.js

@@ -0,0 +1,30 @@
+/** The admitted call, rather than a tool's arguments, owns every media write. */
+export async function executeWithToolResources(params) {
+    const execution = params.resources && params.owner && params.options.abortSignal
+        ? params.resources.media.beginExecution(params.owner, params.options.abortSignal)
+        : undefined;
+    try {
+        const result = await params.registry.execute(params.call, {
+            ...params.options,
+            ...(execution ? { media: execution.writer } : {}),
+            ...(params.resources
+                ? {
+                    onRequestDispose: params.resources.onRequestDispose,
+                    requestWork: params.resources.work,
+                    requestState: params.resources.state,
+                }
+                : {}),
+        });
+        if (result.media?.length && !execution)
+            throw new Error("tool_media_execution_unbound");
+        execution?.finish(result.media);
+        return result;
+    }
+    catch (error) {
+        execution?.finish();
+        throw error;
+    }
+    finally {
+        execution?.close();
+    }
+}

package/dist/src/runtime/adapters/registered-tool-normal-invocations/executor.js

@@ -4,6 +4,7 @@ import { projectRuntimePathBindings } from "./catalog/runtime-path-bindings.js";
 import { executeNormalInvocation, prepareNormalInvocation, } from "./execution/run.js";
 import { emitNormalInvocationPayloadLifecycle } from "./payload/lifecycle.js";
 import { prepareNormalInvocationPayloadLifecycle } from "./payload/lifecycle.js";
+import { restoreNormalInvocation } from "./execution/prepared-snapshot.js";
 import { prepareNormalInvocationRejectionEvent } from "./execution/rejection-event.js";
 /**
  * Captures one selected ToolRegistry snapshot and executes its ordinary
@@ -37,6 +38,7 @@ export function createRegisteredToolNormalInvocationExecutor(params) {
     })));
     return Object.freeze({
         operations,
+        restore: (snapshot) => restoreNormalInvocation({ executor: params, registrations, snapshot }),
         prepareRejectionEvent(input) {
             return prepareNormalInvocationRejectionEvent({
                 operationByHandle,

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/contracts.d.ts

@@ -1,6 +1,8 @@
+import type { BoundApprovalDecision } from "../../../orchestration/worker-capabilities/approval-contracts.js";
 import type { ToolEventExecutorIdentity } from "./event-metadata.js";
+import type { RequestToolResources } from "../../../capabilities/request-tool-resources.js";
 import type { RegisteredToolNormalInvocation, ToolActionSummary, ToolExecutionResult, ToolExecutionSharedState, ToolNormalInvocationEffect, ToolNormalInvocationOperation } from "../../../../capabilities/tool-types.js";
-import type { ToolApprovalController, ToolPermissionMode, ToolRegistry } from "../../../ports.js";
+import type { ToolApprovalController, ToolApprovalRequest, ToolPermissionMode, ToolRegistry } from "../../../ports.js";
 import type { RegisteredToolPayloadContextPlan, RegisteredToolStagedPayloadPlan } from "../../registered-tool-payload-plan.js";
 /**
  * Opaque request-scoped authority for one config-filtered ordinary operation.
@@ -34,6 +36,9 @@ export type RegisteredToolNormalInvocationExecution = Readonly<{
 export type RegisteredToolNormalInvocationResult = RegisteredToolNormalInvocationExecution | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolPreparedNormalInvocation = Readonly<{
     status: "prepared";
+    snapshot: unknown;
+    approvalRequest?: ToolApprovalRequest;
+    applyApprovalDecision(decision: BoundApprovalDecision): void;
     /** Opaque identity of the exact normalized call that would be executed. */
     actionFingerprint: string;
     /** Exact validated non-payload controls accepted for this invocation. */
@@ -62,6 +67,7 @@ export type RegisteredToolPreparedNormalInvocationPayloadLifecycle = Readonly<{
 export type RegisteredToolNormalInvocationPayloadLifecyclePreparation = RegisteredToolPreparedNormalInvocationPayloadLifecycle | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolNormalInvocationExecutor = Readonly<{
     operations: readonly RegisteredToolNormalInvocationProjection[];
+    restore(snapshot: unknown): RegisteredToolNormalInvocationPreparation;
     /** Prepares client-only rejection reporting for a registered source handle. */
     prepareRejectionEvent(input: Readonly<{
         handle: RegisteredToolNormalInvocationHandle;
@@ -130,6 +136,7 @@ export type BoundOperation = Readonly<{
     stagedPayloadPlan?: RegisteredToolStagedPayloadPlan;
 }>;
 export type RegisteredToolNormalInvocationExecutorParams = Readonly<{
+    toolResources?: RequestToolResources;
     registrations: readonly RegisteredToolNormalInvocation[];
     toolRegistry: Pick<ToolRegistry, "execute">;
     requestId: string;

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

@@ -1,8 +1,10 @@
+import type { RequestToolResources } from "../../capabilities/request-tool-resources.js";
 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<{
+    toolResources?: RequestToolResources;
     /**
      * Must return the already config-filtered, request-bound registry. The
      * callback is first invoked when a caller requests the public descriptor

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

@@ -1,8 +1,12 @@
+import { createTechnicalExecutionFailureResult } from "../../orchestration/worker-capabilities/execution/adapter-result-normalization.js";
+import { createWorkerCapabilityExecutionErrorOutcomeFingerprint } from "../../orchestration/worker-capabilities/outcome-fingerprint.js";
+import { createPreparedWorkerInvocation } from "./prepared-execution.js";
+import { restorePreparedWorkerInvocation, createPreparedRejectionSnapshot, } from "./prepared-snapshot.js";
 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, payloadRejection, prepareOperationPayload, } from "./payload-lifecycle.js";
-import { attachTargetReferences, observeExternalResult, projectSelectedTargetReferences, } from "./result-observer.js";
+import { payloadRejection, prepareOperationPayload, } from "./payload-lifecycle.js";
+import { attachTargetReferences, projectSelectedTargetReferences, } from "./result-observer.js";
 import { resolveEffectiveOperationTargetControls } from "./runtime-path-controls.js";
 import { createRegisteredToolPreparationAttemptFingerprint } from "../registered-tool-normal-invocations/shared/action-fingerprint.js";
 import { createWorkerCapabilityPreparationFailureFingerprint } from "../../orchestration/worker-capabilities/preparation-fingerprint.js";
@@ -45,6 +49,9 @@ function createWorkerAdapter(params) {
         async prepare(input) {
             return prepareRegisteredToolWorkerAdapter(params, input);
         },
+        async restore(input, snapshot) {
+            return restorePreparedWorkerInvocation(params, input, snapshot);
+        },
         async execute(input) {
             const preparationInput = Object.freeze({
                 ...input,
@@ -77,17 +84,17 @@ async function prepareRegisteredToolWorkerAdapter(params, input) {
                 : {}),
             error,
         });
+        const failedResult = {
+            ...createTechnicalExecutionFailureResult(error),
+            failureOutcomeFingerprint: createWorkerCapabilityExecutionErrorOutcomeFingerprint(error) ?? null,
+        };
         return Object.freeze({
             ...(actionFingerprint ? { actionFingerprint } : {}),
             acceptedControls: input.controls,
+            snapshot: createPreparedRejectionSnapshot(operationId, actionFingerprint, input.controls, failedResult),
+            onAdmitted: payloadObservability.release,
             execute: async (executionId) => {
-                try {
-                    payloadObservability.release(executionId);
-                }
-                catch (releaseError) {
-                    tracePreparedExecutionFailed(params, input, operationId, executionId, releaseError);
-                    throw releaseError;
-                }
+                payloadObservability.release(executionId);
                 tracePreparedExecutionFailed(params, input, operationId, executionId, error, registeredPreparationFailureIssueCode(error));
                 throw error;
             },
@@ -179,55 +186,7 @@ async function prepareRegisteredToolWorkerCapability(params, input, payloadObser
                 : { materializedParams: preparedPayload.materializedParams }),
         });
     }
-    return Object.freeze({
-        actionFingerprint: normalPreparation.actionFingerprint,
-        acceptedControls: normalPreparation.acceptedControls,
-        execute: async (executionId) => {
-            try {
-                payloadObservability.release(executionId);
-                tracePreparedExecutionStarted(params, input, operationId, executionId);
-                const rejectedExecution = executionFreshnessRejection(input.executionFreshness);
-                if (rejectedExecution) {
-                    normalPreparation.emitRejection({
-                        executionId,
-                        executorIdentity: input.call,
-                        errorCode: rejectedExecution.sourceIssueCode,
-                    });
-                    return completeRuntimeRejection({
-                        params,
-                        input,
-                        operationId,
-                        executionId,
-                        selectedTargetReferences,
-                        rejectedExecution,
-                    });
-                }
-                const externalResult = await normalPreparation.execute(executionId, input.call);
-                const observed = observeExternalResult(externalResult, params.projection.operation.effect, input.call.parentCallId === null);
-                const observedResult = attachTargetReferences(observed.result, selectedTargetReferences);
-                traceRegisteredToolWorkerCapabilityExecutionCompleted(params.diagnostic, operationId, input.call, 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) {
-                tracePreparedExecutionFailed(params, input, operationId, executionId, error);
-                throw error;
-            }
-        },
-    });
+    return createPreparedWorkerInvocation(params, input, normalPreparation, selectedTargetReferences, payloadObservability);
 }
 function preparedRuntimeRejection(input) {
     return Object.freeze({
@@ -241,6 +200,19 @@ function preparedRuntimeRejection(input) {
                 : { materializedParams: input.materializedParams }),
         }),
         acceptedControls: input.effectiveControls,
+        snapshot: createPreparedRejectionSnapshot(input.operationId, createRegisteredToolPreparationAttemptFingerprint({
+            operationId: input.operationId,
+            controls: input.effectiveControls,
+            rejectionCode: input.rejectedExecution.sourceIssueCode,
+            ...(input.payload === undefined ? {} : { payload: input.payload }),
+            ...(input.materializedParams === undefined
+                ? {}
+                : { materializedParams: input.materializedParams }),
+        }), input.effectiveControls, attachTargetReferences({
+            ...input.rejectedExecution.result,
+            exactResult: input.rejectedExecution.exactResult,
+        }, input.selectedTargetReferences)),
+        onAdmitted: input.payloadObservability.release,
         execute: async (executionId) => {
             try {
                 input.payloadObservability.release(executionId);