@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/adapters/long-term-memory/onboarding-config-repository.js

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { chmod, copyFile, mkdir, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { inspectRuntimeConfigFileWithMeta } from "../../config/loader.js";
+import { withFileLock } from "./file-lock.js";
+export function createFileLongTermMemoryOnboardingConfigRepository(params) {
+    const source = () => inspectRuntimeConfigFileWithMeta(params.rootDir, params.configPath);
+    return Object.freeze({
+        async read() {
+            const current = source();
+            if (!current.exists) {
+                throw new Error(`runtime_config_not_found:${current.path}`);
+            }
+            return Object.freeze({ config: current.config, path: current.path });
+        },
+        async write(config, expectedConfig) {
+            const current = source();
+            if (!current.exists) {
+                throw new Error(`runtime_config_not_found:${current.path}`);
+            }
+            return withFileLock(`${current.path}.memory-onboarding.lock`, async () => {
+                const lockedCurrent = source();
+                if (!lockedCurrent.exists) {
+                    throw new Error(`runtime_config_not_found:${lockedCurrent.path}`);
+                }
+                const hasConflictingConfig = expectedConfig !== undefined &&
+                    !isDeepStrictEqual(lockedCurrent.config, expectedConfig);
+                if (hasConflictingConfig) {
+                    throw new Error("long_term_memory_config_changed");
+                }
+                return writeConfigSnapshot(lockedCurrent.path, config);
+            });
+        },
+    });
+}
+async function writeConfigSnapshot(configPath, config) {
+    await mkdir(dirname(configPath), { recursive: true });
+    const backupPath = createBackupPath(configPath);
+    const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+    const sourcePermissions = (await stat(configPath)).mode & 0o777;
+    await copyFile(configPath, backupPath);
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: sourcePermissions,
+        });
+        await chmod(temporaryPath, sourcePermissions);
+        await rename(temporaryPath, configPath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return Object.freeze({ configPath, backupPath });
+}
+function createBackupPath(configPath) {
+    const timestamp = new Date().toISOString().replace(/[:.]/gu, "-");
+    return `${configPath}.${timestamp}.bak`;
+}

package/dist/src/runtime/adapters/long-term-memory/onboarding-service.d.ts

@@ -0,0 +1,8 @@
+import { type ModelProviderAdapterRegistry } from "../../../model-gateway/index.js";
+import type { LongTermMemoryOnboardingService } from "../../long-term-memory/onboarding/contracts.js";
+export declare function createLocalLongTermMemoryOnboardingService(params: {
+    rootDir: string;
+    providerAdapters: ModelProviderAdapterRegistry;
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}): LongTermMemoryOnboardingService;

package/dist/src/runtime/adapters/long-term-memory/onboarding-service.js

@@ -0,0 +1,34 @@
+import { discoverEmbeddingModels, executeEmbeddingRequest, } from "../../../model-gateway/index.js";
+import { createLongTermMemoryOnboardingService } from "../../long-term-memory/onboarding/service.js";
+import { createFileLongTermMemoryOnboardingConfigRepository } from "./onboarding-config-repository.js";
+const EMBEDDING_PROBE_TEXT = "ABot long-term memory embedding capability probe.";
+export function createLocalLongTermMemoryOnboardingService(params) {
+    const repository = createFileLongTermMemoryOnboardingConfigRepository({
+        rootDir: params.rootDir,
+        ...(params.configPath ? { configPath: params.configPath } : {}),
+    });
+    return createLongTermMemoryOnboardingService({
+        repository,
+        probe: async (input) => {
+            const result = await executeEmbeddingRequest({
+                profileId: input.profileId,
+                texts: [EMBEDDING_PROBE_TEXT],
+                modelPolicy: input.modelPolicy,
+                abortSignal: input.abortSignal,
+                providerAdapters: params.providerAdapters,
+                ...(params.fetchImpl ? { fetchImpl: params.fetchImpl } : {}),
+            });
+            return Object.freeze({
+                modelFingerprint: result.modelFingerprint,
+                dimensions: result.dimensions,
+            });
+        },
+        discover: (input) => discoverEmbeddingModels({
+            providerId: input.providerId,
+            modelPolicy: input.modelPolicy,
+            abortSignal: input.abortSignal,
+            providerAdapters: params.providerAdapters,
+            ...(params.fetchImpl ? { fetchImpl: params.fetchImpl } : {}),
+        }),
+    });
+}

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

@@ -1,8 +1,14 @@
 import type { RegisteredToolNormalInvocation } from "../../../../capabilities/tool-types.js";
-import type { BoundOperation, RegisteredToolNormalInvocationExecutionInput, RegisteredToolNormalInvocationExecutorParams, RegisteredToolNormalInvocationResult } from "../shared/contracts.js";
+import type { BoundOperation, RegisteredToolNormalInvocationExecutionInput, RegisteredToolNormalInvocationExecutorParams, RegisteredToolNormalInvocationPreparation, RegisteredToolNormalInvocationPreparationInput, RegisteredToolNormalInvocationResult } from "../shared/contracts.js";
 export declare function executeNormalInvocation(params: {
     executor: RegisteredToolNormalInvocationExecutorParams;
     registrations: readonly RegisteredToolNormalInvocation[];
     operationByHandle: WeakMap<object, BoundOperation>;
     input: RegisteredToolNormalInvocationExecutionInput;
 }): Promise<RegisteredToolNormalInvocationResult>;
+export declare function prepareNormalInvocation(params: {
+    executor: RegisteredToolNormalInvocationExecutorParams;
+    registrations: readonly RegisteredToolNormalInvocation[];
+    operationByHandle: WeakMap<object, BoundOperation>;
+    input: RegisteredToolNormalInvocationPreparationInput;
+}): RegisteredToolNormalInvocationPreparation;

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

@@ -1,10 +1,17 @@
 import { buildToolCompletedEventActions, buildToolCompletedEventMetadata, buildToolLifecycleEventCopy, } from "../../../../capabilities/tool-event-metadata.js";
 import { requestNormalInvocationApproval } from "./approval.js";
 import { captureToolCall, materializeCall, resolveExactTargetOperation, validateCompleteCall, } from "./call-binding.js";
+import { createRegisteredToolActionFingerprint } from "../shared/action-fingerprint.js";
 import { buildToolIntentEventMetadata } from "../shared/event-metadata.js";
 import { prepareCompleteInvocationInput } from "../payload/input-preparation.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
 export async function executeNormalInvocation(params) {
+    const prepared = prepareNormalInvocation(params);
+    return prepared.status === "prepared"
+        ? prepared.execute()
+        : Promise.resolve(prepared);
+}
+export function prepareNormalInvocation(params) {
     const executor = params.executor;
     executor.abortSignal.throwIfAborted();
     const source = params.operationByHandle.get(params.input.handle);
@@ -43,41 +50,63 @@ export async function executeNormalInvocation(params) {
         return rejectNormalInvocation("normal_invocation_effect_changed", "A normalized ordinary invocation cannot change its declared execution effect.");
     }
     const eventMeta = buildToolIntentEventMetadata(normalizedCall.call, params.input.intent, target.binding.registration.definition);
+    const actionFingerprint = createRegisteredToolActionFingerprint({
+        contractVersion: target.binding.registration.contract.version,
+        operationId: target.binding.operation.operationId,
+        call: normalizedCall.call,
+    });
+    return Object.freeze({
+        status: "prepared",
+        actionFingerprint,
+        acceptedControls: preparedInput.controls,
+        execute: () => executePreparedNormalInvocation({
+            executor,
+            source,
+            target: target.binding,
+            call: normalizedCall.call,
+            eventMeta,
+            input: params.input,
+        }),
+    });
+}
+async function executePreparedNormalInvocation(params) {
     const approval = await requestNormalInvocationApproval({
-        requestId: executor.requestId,
-        abortSignal: executor.abortSignal,
-        toolPermissionMode: executor.toolPermissionMode,
-        ...(executor.toolApprovalController
-            ? { toolApprovalController: executor.toolApprovalController }
+        requestId: params.executor.requestId,
+        abortSignal: params.executor.abortSignal,
+        toolPermissionMode: params.executor.toolPermissionMode,
+        ...(params.executor.toolApprovalController
+            ? { toolApprovalController: params.executor.toolApprovalController }
             : {}),
-        nextApprovalId: executor.nextApprovalId,
-        ...(executor.onEvent ? { onEvent: executor.onEvent } : {}),
-        call: normalizedCall.call,
-        ...(eventMeta ? { eventMeta } : {}),
-        force: source.operation.approval === "always" ||
-            target.binding.operation.approval === "always",
+        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;
-    executor.abortSignal.throwIfAborted();
-    const startedCopy = buildToolLifecycleEventCopy(target.binding.registration.definition, "started");
-    executor.onEvent?.("tool.started", {
-        tool: normalizedCall.call.tool,
+    params.executor.abortSignal.throwIfAborted();
+    const startedCopy = buildToolLifecycleEventCopy(params.target.registration.definition, "started");
+    params.executor.onEvent?.("tool.started", {
+        tool: params.call.tool,
         ...(params.input.intent
             ? { intent: params.input.intent, intentSource: "model" }
             : {}),
-        ...(eventMeta ? { meta: eventMeta } : {}),
+        ...(params.eventMeta ? { meta: params.eventMeta } : {}),
         ...(startedCopy ?? {}),
     });
-    const result = await executor.toolRegistry.execute(normalizedCall.call, {
-        abortSignal: executor.abortSignal,
-        ...(executor.sharedState ? { sharedState: executor.sharedState } : {}),
+    const result = await params.executor.toolRegistry.execute(params.call, {
+        abortSignal: params.executor.abortSignal,
+        ...(params.executor.sharedState
+            ? { sharedState: params.executor.sharedState }
+            : {}),
     });
-    const completionActions = Object.freeze(buildToolCompletedEventActions(normalizedCall.call, result, target.binding.registration.definition).map((action) => Object.freeze({ ...action })));
-    const completedMeta = buildToolCompletedEventMetadata(normalizedCall.call, result, target.binding.registration.definition);
-    const completedCopy = buildToolLifecycleEventCopy(target.binding.registration.definition, result.ok ? "completed" : "failed");
-    executor.onEvent?.("tool.completed", {
-        tool: source.registration.toolName,
+    const completionActions = Object.freeze(buildToolCompletedEventActions(params.call, result, params.target.registration.definition).map((action) => Object.freeze({ ...action })));
+    const completedMeta = buildToolCompletedEventMetadata(params.call, result, params.target.registration.definition);
+    const completedCopy = buildToolLifecycleEventCopy(params.target.registration.definition, result.ok ? "completed" : "failed");
+    params.executor.onEvent?.("tool.completed", {
+        tool: params.source.registration.toolName,
         ok: result.ok,
         actions: completionActions,
         ...(completedMeta ? { meta: completedMeta } : {}),
@@ -85,7 +114,7 @@ export async function executeNormalInvocation(params) {
     });
     return Object.freeze({
         status: "executed",
-        effect: target.binding.operation.effect,
+        effect: params.target.operation.effect,
         result,
         completionActions,
     });

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

@@ -1,8 +1,9 @@
 import { deriveRegisteredToolPayloadContextPlan, deriveRegisteredToolStagedPayloadPlan, } from "../registered-tool-payload-plan.js";
 import { captureNormalInvocationRegistrations } from "./catalog/registrations.js";
 import { projectRuntimePathBindings } from "./catalog/runtime-path-bindings.js";
-import { executeNormalInvocation } from "./execution/run.js";
+import { executeNormalInvocation, prepareNormalInvocation, } from "./execution/run.js";
 import { emitNormalInvocationPayloadLifecycle } from "./payload/lifecycle.js";
+import { prepareNormalInvocationPayloadLifecycle } from "./payload/lifecycle.js";
 /**
  * Captures one selected ToolRegistry snapshot and executes its ordinary
  * invocation contracts. Normalization may only resolve another operation from
@@ -21,9 +22,7 @@ export function createRegisteredToolNormalInvocationExecutor(params) {
         operationByHandle.set(handle, Object.freeze({
             registration,
             operation,
-            ...(runtimePathBindings.length > 0
-                ? { runtimePathBindings }
-                : {}),
+            ...(runtimePathBindings.length > 0 ? { runtimePathBindings } : {}),
             ...(payloadContextPlan ? { payloadContextPlan } : {}),
             ...(stagedPayloadPlan ? { stagedPayloadPlan } : {}),
         }));
@@ -44,6 +43,21 @@ export function createRegisteredToolNormalInvocationExecutor(params) {
                 ...(params.onEvent ? { onEvent: params.onEvent } : {}),
             });
         },
+        preparePayloadLifecycle(input) {
+            return prepareNormalInvocationPayloadLifecycle({
+                operationByHandle,
+                input,
+                ...(params.onEvent ? { onEvent: params.onEvent } : {}),
+            });
+        },
+        prepare(input) {
+            return prepareNormalInvocation({
+                executor: params,
+                registrations,
+                operationByHandle,
+                input,
+            });
+        },
         execute(input) {
             return executeNormalInvocation({
                 executor: params,

package/dist/src/runtime/adapters/registered-tool-normal-invocations/payload/lifecycle.d.ts

@@ -1,6 +1,11 @@
-import type { BoundOperation, RegisteredToolNormalInvocationPayloadLifecycleInput, RegisteredToolNormalInvocationPayloadLifecycleResult } from "../shared/contracts.js";
+import type { BoundOperation, RegisteredToolNormalInvocationPayloadLifecycleInput, RegisteredToolNormalInvocationPayloadLifecyclePreparation, RegisteredToolNormalInvocationPayloadLifecycleResult } from "../shared/contracts.js";
 export declare function emitNormalInvocationPayloadLifecycle(params: {
     operationByHandle: WeakMap<object, BoundOperation>;
     input: RegisteredToolNormalInvocationPayloadLifecycleInput;
     onEvent?(name: string, payload: Record<string, unknown>): void;
 }): RegisteredToolNormalInvocationPayloadLifecycleResult;
+export declare function prepareNormalInvocationPayloadLifecycle(params: {
+    operationByHandle: WeakMap<object, BoundOperation>;
+    input: RegisteredToolNormalInvocationPayloadLifecycleInput;
+    onEvent?(name: string, payload: Record<string, unknown>): void;
+}): RegisteredToolNormalInvocationPayloadLifecyclePreparation;

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

@@ -3,6 +3,10 @@ import { buildToolIntentEventMetadata } from "../shared/event-metadata.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
 import { validatePublicInput } from "./input-preparation.js";
 export function emitNormalInvocationPayloadLifecycle(params) {
+    const prepared = prepareNormalInvocationPayloadLifecycle(params);
+    return prepared.status === "prepared" ? prepared.emit() : prepared;
+}
+export function prepareNormalInvocationPayloadLifecycle(params) {
     const source = params.operationByHandle.get(params.input.handle);
     if (!source) {
         return rejectNormalInvocation("normal_invocation_handle_invalid", "The selected ordinary capability is not registered for this request.");
@@ -28,24 +32,33 @@ export function emitNormalInvocationPayloadLifecycle(params) {
         payloadStageCount: lifecycleStage.stage.count,
         ...(eventMeta ? { meta: eventMeta } : {}),
     };
-    switch (params.input.phase) {
+    const event = materializePayloadLifecycleEvent(params.input, base);
+    return Object.freeze({
+        status: "prepared",
+        emit: () => {
+            params.onEvent?.(event.name, event.payload);
+            return Object.freeze({ status: "emitted" });
+        },
+    });
+}
+function materializePayloadLifecycleEvent(input, base) {
+    switch (input.phase) {
         case "started":
-            params.onEvent?.("tool.payload.started", base);
-            break;
+            return Object.freeze({ name: "tool.payload.started", payload: base });
         case "completed":
-            params.onEvent?.("tool.payload.completed", {
-                ...base,
-                ok: true,
+            return Object.freeze({
+                name: "tool.payload.completed",
+                payload: { ...base, ok: true },
             });
-            break;
         case "failed":
-            params.onEvent?.("tool.payload.failed", {
-                ...base,
-                ...(params.input.errorCode ? { error: params.input.errorCode } : {}),
+            return Object.freeze({
+                name: "tool.payload.failed",
+                payload: {
+                    ...base,
+                    ...(input.errorCode ? { error: input.errorCode } : {}),
+                },
             });
-            break;
     }
-    return Object.freeze({ status: "emitted" });
 }
 function resolvePayloadLifecycleStage(source, input) {
     const plan = source.stagedPayloadPlan;

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

@@ -0,0 +1,22 @@
+import type { ToolCall } from "../../../../capabilities/tool-types.js";
+/**
+ * Hashes the exact normalized tool call. The runtime core receives only this
+ * opaque identity and remains independent of tools, controls, and payloads.
+ */
+export declare function createRegisteredToolActionFingerprint(input: {
+    contractVersion: number;
+    operationId: string;
+    call: ToolCall;
+}): string;
+/**
+ * Identifies a fully bounded preparation attempt that could not become a
+ * normalized tool call. The stable rejection code keeps it disjoint from a
+ * later successful materialization of the same public controls.
+ */
+export declare function createRegisteredToolPreparationAttemptFingerprint(input: {
+    operationId: string;
+    controls: Readonly<Record<string, unknown>>;
+    rejectionCode: string;
+    payload?: string;
+    materializedParams?: Readonly<Record<string, string>>;
+}): string;

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/action-fingerprint.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+/**
+ * Hashes the exact normalized tool call. The runtime core receives only this
+ * opaque identity and remains independent of tools, controls, and payloads.
+ */
+export function createRegisteredToolActionFingerprint(input) {
+    const canonical = JSON.stringify([
+        "registered_tool_normal_invocation_v1",
+        input.contractVersion,
+        input.operationId,
+        input.call.tool,
+        canonicalEntries(input.call.params),
+    ]);
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+/**
+ * Identifies a fully bounded preparation attempt that could not become a
+ * normalized tool call. The stable rejection code keeps it disjoint from a
+ * later successful materialization of the same public controls.
+ */
+export function createRegisteredToolPreparationAttemptFingerprint(input) {
+    const canonical = JSON.stringify([
+        "operation_preparation_attempt_v1",
+        input.operationId,
+        canonicalEntries(input.controls),
+        input.rejectionCode,
+        input.payload === undefined ? null : digestText(input.payload),
+        input.materializedParams === undefined
+            ? null
+            : Object.freeze(Object.entries(input.materializedParams)
+                .sort(([left], [right]) => compareText(left, right))
+                .map(([key, value]) => Object.freeze([key, digestText(value)]))),
+    ]);
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+function digestText(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function canonicalEntries(input) {
+    return Object.freeze(Object.entries(input)
+        .sort(([left], [right]) => compareText(left, right))
+        .map(([key, value]) => Object.freeze([key, canonicalValue(value)])));
+}
+function canonicalValue(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((entry) => canonicalValue(entry)));
+    }
+    if (isPlainRecord(value))
+        return canonicalEntries(value);
+    return value;
+}
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function compareText(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

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

@@ -31,10 +31,26 @@ export type RegisteredToolNormalInvocationExecution = Readonly<{
     completionActions: readonly ToolActionSummary[];
 }>;
 export type RegisteredToolNormalInvocationResult = RegisteredToolNormalInvocationExecution | RegisteredToolNormalInvocationRejection;
+export type RegisteredToolPreparedNormalInvocation = Readonly<{
+    status: "prepared";
+    /** Opaque identity of the exact normalized call that would be executed. */
+    actionFingerprint: string;
+    /** Exact validated non-payload controls accepted for this invocation. */
+    acceptedControls: Readonly<Record<string, unknown>>;
+    execute(): Promise<RegisteredToolNormalInvocationResult>;
+}>;
+export type RegisteredToolNormalInvocationPreparation = RegisteredToolPreparedNormalInvocation | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolNormalInvocationPayloadLifecyclePhase = "started" | "completed" | "failed";
 export type RegisteredToolNormalInvocationPayloadLifecycleResult = Readonly<{
     status: "emitted";
 }> | RegisteredToolNormalInvocationRejection;
+export type RegisteredToolPreparedNormalInvocationPayloadLifecycle = Readonly<{
+    status: "prepared";
+    emit(): Readonly<{
+        status: "emitted";
+    }>;
+}>;
+export type RegisteredToolNormalInvocationPayloadLifecyclePreparation = RegisteredToolPreparedNormalInvocationPayloadLifecycle | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolNormalInvocationExecutor = Readonly<{
     operations: readonly RegisteredToolNormalInvocationProjection[];
     /**
@@ -52,6 +68,33 @@ export type RegisteredToolNormalInvocationExecutor = Readonly<{
         payloadStageCount?: number;
         outputParam?: string;
     }>): RegisteredToolNormalInvocationPayloadLifecycleResult;
+    /**
+     * Validates and materializes one payload lifecycle event without publishing
+     * it. The prepared event can be released only after canonical admission.
+     */
+    preparePayloadLifecycle(input: Readonly<{
+        handle: RegisteredToolNormalInvocationHandle;
+        controls: Readonly<Record<string, unknown>>;
+        /** Client-facing lifecycle metadata; never part of tool parameters. */
+        intent?: string;
+        phase: RegisteredToolNormalInvocationPayloadLifecyclePhase;
+        errorCode?: string;
+        payloadStage?: number;
+        payloadStageCount?: number;
+        outputParam?: string;
+    }>): RegisteredToolNormalInvocationPayloadLifecyclePreparation;
+    /**
+     * Fully validates and normalizes an invocation without approval or tool
+     * execution. The returned action fingerprint is safe for generic admission.
+     */
+    prepare(input: Readonly<{
+        handle: RegisteredToolNormalInvocationHandle;
+        controls: Readonly<Record<string, unknown>>;
+        payload?: string;
+        materializedParams?: Readonly<Record<string, string>>;
+        /** Client-facing lifecycle metadata; never part of tool parameters. */
+        intent?: string;
+    }>): RegisteredToolNormalInvocationPreparation;
     execute(input: Readonly<{
         handle: RegisteredToolNormalInvocationHandle;
         controls: Readonly<Record<string, unknown>>;
@@ -84,3 +127,4 @@ export type RegisteredToolNormalInvocationExecutorParams = Readonly<{
 }>;
 export type RegisteredToolNormalInvocationPayloadLifecycleInput = Parameters<RegisteredToolNormalInvocationExecutor["emitPayloadLifecycle"]>[0];
 export type RegisteredToolNormalInvocationExecutionInput = Parameters<RegisteredToolNormalInvocationExecutor["execute"]>[0];
+export type RegisteredToolNormalInvocationPreparationInput = Parameters<RegisteredToolNormalInvocationExecutor["prepare"]>[0];

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

@@ -1,3 +1,3 @@
 export { createRegisteredToolNormalInvocationExecutor } from "./registered-tool-normal-invocations/executor.js";
 export { projectRuntimePathBindings } from "./registered-tool-normal-invocations/catalog/runtime-path-bindings.js";
-export type { RegisteredToolNormalInvocationExecution, RegisteredToolNormalInvocationExecutor, RegisteredToolNormalInvocationHandle, RegisteredToolNormalInvocationPayloadLifecyclePhase, RegisteredToolNormalInvocationPayloadLifecycleResult, RegisteredToolNormalInvocationProjection, RegisteredToolNormalInvocationRejection, RegisteredToolNormalInvocationResult, } from "./registered-tool-normal-invocations/shared/contracts.js";
+export type { RegisteredToolNormalInvocationExecution, RegisteredToolNormalInvocationExecutor, RegisteredToolNormalInvocationHandle, RegisteredToolNormalInvocationPayloadLifecyclePhase, RegisteredToolNormalInvocationPayloadLifecyclePreparation, RegisteredToolNormalInvocationPayloadLifecycleResult, RegisteredToolNormalInvocationPreparation, RegisteredToolNormalInvocationProjection, RegisteredToolPreparedNormalInvocation, RegisteredToolPreparedNormalInvocationPayloadLifecycle, RegisteredToolNormalInvocationRejection, RegisteredToolNormalInvocationResult, } from "./registered-tool-normal-invocations/shared/contracts.js";

package/dist/src/runtime/adapters/registered-tool-payload-plan.d.ts

@@ -1,6 +1,4 @@
 import type { ToolDefinition, ToolExecutionSharedState, ToolNormalInvocationInput, ToolNormalInvocationOperation, ToolPayloadChannelSpec, ToolPayloadChannelStageSpec } from "../../capabilities/tool-types.js";
-import { type WorkerCapabilityPayloadRelatedArtifactContext } from "../orchestration/worker-capabilities/payload-contracts.js";
-import type { WorkerSettledCapabilityResult } from "../orchestration/worker-capabilities/contracts.js";
 export type RegisteredToolPayloadStage = Readonly<{
     outputParam: string;
     instructions: string;
@@ -72,13 +70,6 @@ export declare function resolveRegisteredToolPayloadTargetContext(params: {
     sharedState: ToolExecutionSharedState;
     materializedParams?: Readonly<Record<string, string>>;
 }): Promise<RegisteredToolPayloadTargetContext | undefined>;
-export declare function resolveRegisteredToolPayloadRelatedArtifactContexts(params: {
-    contextScope?: ToolPayloadChannelSpec["contextScope"];
-    targetParam?: string;
-    controls: Readonly<Record<string, unknown>>;
-    sharedState: ToolExecutionSharedState;
-    settledCapabilityResults: readonly WorkerSettledCapabilityResult[];
-}): Promise<readonly WorkerCapabilityPayloadRelatedArtifactContext[]>;
 export declare function materializeRegisteredToolPayloadStageResponseFormat(params: {
     stage: RegisteredToolPayloadStage;
     targetContext?: RegisteredToolPayloadTargetContext;

package/dist/src/runtime/adapters/registered-tool-payload-plan.js

@@ -1,7 +1,6 @@
 import { readFile, stat } from "node:fs/promises";
 import { TOOL_PAYLOAD_STAGE_LITERAL_OUTPUT_MAX_BYTES } from "../../capabilities/tool-types.js";
 import { resolveRuntimeTargetPath } from "../capabilities/runtime-target-path.js";
-import { WORKER_CAPABILITY_RELATED_ARTIFACT_CONTEXT_MAX_CHARS, WORKER_CAPABILITY_RELATED_ARTIFACT_CONTEXT_MAX_COUNT, } from "../orchestration/worker-capabilities/payload-contracts.js";
 export function deriveRegisteredToolPayloadContextPlan(definition, operation) {
     const spec = definition.payloadChannelSpec;
     if (!operation.payload ||
@@ -227,72 +226,6 @@ export async function resolveRegisteredToolPayloadTargetContext(params) {
         content,
     });
 }
-export async function resolveRegisteredToolPayloadRelatedArtifactContexts(params) {
-    if (params.contextScope !== "target_with_artifacts") {
-        return Object.freeze([]);
-    }
-    const currentTarget = resolveCurrentTarget(params);
-    const resolvedTargets = new Set();
-    const artifacts = [];
-    let totalCharacters = 0;
-    for (const result of params.settledCapabilityResults) {
-        if (result.outcome !== "succeeded")
-            continue;
-        for (const reference of result.references ?? []) {
-            let resolvedTarget;
-            try {
-                resolvedTarget = resolveRuntimeTargetPath(reference.target, params.sharedState);
-            }
-            catch {
-                continue;
-            }
-            if (resolvedTarget === currentTarget ||
-                resolvedTargets.has(resolvedTarget)) {
-                continue;
-            }
-            resolvedTargets.add(resolvedTarget);
-            try {
-                const targetStat = await stat(resolvedTarget);
-                if (!targetStat.isFile())
-                    continue;
-                const content = await readFile(resolvedTarget, "utf8");
-                if (content.length + totalCharacters >
-                    WORKER_CAPABILITY_RELATED_ARTIFACT_CONTEXT_MAX_CHARS) {
-                    continue;
-                }
-                artifacts.push(Object.freeze({
-                    sourceExecutionId: result.executionId,
-                    targetPath: reference.target,
-                    presentation: "full",
-                    content,
-                }));
-                totalCharacters += content.length;
-                if (artifacts.length >=
-                    WORKER_CAPABILITY_RELATED_ARTIFACT_CONTEXT_MAX_COUNT) {
-                    return Object.freeze(artifacts);
-                }
-            }
-            catch {
-                continue;
-            }
-        }
-    }
-    return Object.freeze(artifacts);
-}
-function resolveCurrentTarget(params) {
-    const rawTarget = params.targetParam
-        ? params.controls[params.targetParam]
-        : undefined;
-    if (typeof rawTarget !== "string" || rawTarget.trim().length === 0) {
-        return undefined;
-    }
-    try {
-        return resolveRuntimeTargetPath(rawTarget.trim(), params.sharedState);
-    }
-    catch {
-        return undefined;
-    }
-}
 function resolveBoundedTargetContext(params) {
     const stageIndex = params.plan.stages.indexOf(params.stage);
     const priorStages = params.plan.stages

package/dist/src/runtime/adapters/registered-tool-payload-related-artifacts.d.ts

@@ -0,0 +1,13 @@
+import type { ToolExecutionSharedState, ToolPayloadChannelSpec } from "../../capabilities/tool-types.js";
+import type { WorkerCapabilityPayloadSourceProvenance, WorkerSettledCapabilityResult } from "../orchestration/worker-capabilities/contracts.js";
+import { type WorkerCapabilityPayloadRelatedArtifactContext } from "../orchestration/worker-capabilities/payload-contracts.js";
+import type { RoleCallFrame } from "../orchestration/role-calls/contracts.js";
+export declare function resolveRegisteredToolPayloadRelatedArtifactContexts(params: {
+    contextScope?: ToolPayloadChannelSpec["contextScope"];
+    targetParam?: string;
+    controls: Readonly<Record<string, unknown>>;
+    sharedState: ToolExecutionSharedState;
+    call: RoleCallFrame;
+    assignmentProvenance?: WorkerCapabilityPayloadSourceProvenance;
+    settledCapabilityResults: readonly WorkerSettledCapabilityResult[];
+}): Promise<readonly WorkerCapabilityPayloadRelatedArtifactContext[]>;