@abot-ai/runtime 1.0.0 → 1.1.0

package/dist/src/runtime/adapters/long-term-memory/file-lock/contracts.d.ts

@@ -0,0 +1,31 @@
+export declare const LOCK_RETRY_DELAY_MS = 10;
+export declare const LOCK_ACQUIRE_TIMEOUT_MS = 2000;
+export declare const INCOMPLETE_LOCK_GRACE_MS = 30000;
+export declare const MAX_LOCK_RECORD_BYTES = 1024;
+export declare const LEASE_DIRECTORY_NAME = "lease";
+export declare const OWNER_FILE_PATTERN: RegExp;
+export type FileLockOptions = Readonly<{
+    waitMs?: number;
+    retryDelayMs?: number;
+    processIsAlive?: (pid: number) => boolean;
+}>;
+export type LockRecord = Readonly<{
+    pid: number;
+    token: string;
+    createdAt: string;
+}>;
+export type DirectoryLockSnapshot = Readonly<{
+    kind: "directory";
+    modifiedAtMs: number;
+    hasLeaseDirectory: boolean;
+    ownerFileName?: string;
+    ownerPid?: number;
+    record?: LockRecord;
+    reclaimable: boolean;
+}>;
+export type LockSnapshot = DirectoryLockSnapshot | Readonly<{
+    kind: "legacy_file";
+}>;
+export declare function ownerFileName(token: string): string;
+export declare function directorySnapshot(snapshot: Omit<DirectoryLockSnapshot, "kind">): DirectoryLockSnapshot;
+export declare function fileSystemErrorCode(error: unknown): string | undefined;

package/dist/src/runtime/adapters/long-term-memory/file-lock/contracts.js

@@ -0,0 +1,17 @@
+export const LOCK_RETRY_DELAY_MS = 10;
+export const LOCK_ACQUIRE_TIMEOUT_MS = 2_000;
+export const INCOMPLETE_LOCK_GRACE_MS = 30_000;
+export const MAX_LOCK_RECORD_BYTES = 1_024;
+export const LEASE_DIRECTORY_NAME = "lease";
+export const OWNER_FILE_PATTERN = /^owner-([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.json$/iu;
+export function ownerFileName(token) {
+    return `owner-${token}.json`;
+}
+export function directorySnapshot(snapshot) {
+    return Object.freeze({ kind: "directory", ...snapshot });
+}
+export function fileSystemErrorCode(error) {
+    return error !== null && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : undefined;
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/install.d.ts

@@ -0,0 +1 @@
+export declare function installLockDirectory(lockPath: string, token: string): Promise<void>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/install.js

@@ -0,0 +1,36 @@
+import { mkdir, open, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { removeDirectoryIfEmpty, removeStagingLock } from "./cleanup.js";
+import { LEASE_DIRECTORY_NAME, ownerFileName } from "./contracts.js";
+export async function installLockDirectory(lockPath, token) {
+    const stagingPath = `${lockPath}.${process.pid}.${token}.pending`;
+    const stagingOwnerPath = join(stagingPath, ownerFileName(token));
+    let handle;
+    let claimedLockPath = false;
+    let installed = false;
+    try {
+        await mkdir(stagingPath, { mode: 0o700 });
+        handle = await open(stagingOwnerPath, "wx", 0o600);
+        await handle.writeFile(JSON.stringify({
+            pid: process.pid,
+            token,
+            createdAt: new Date().toISOString(),
+        }), "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await mkdir(lockPath, { mode: 0o700 });
+        claimedLockPath = true;
+        await rename(stagingPath, join(lockPath, LEASE_DIRECTORY_NAME));
+        installed = true;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        if (!installed) {
+            await removeStagingLock(stagingPath, stagingOwnerPath);
+            if (claimedLockPath) {
+                await removeDirectoryIfEmpty(lockPath);
+            }
+        }
+    }
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/owner-record.d.ts

@@ -0,0 +1,2 @@
+import { type DirectoryLockSnapshot } from "./contracts.js";
+export declare function readOwnerRecord(lockPath: string, entryName: string, expectedToken: string, directoryModifiedAtMs: number): Promise<DirectoryLockSnapshot>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/owner-record.js

@@ -0,0 +1,114 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { directorySnapshot, fileSystemErrorCode, LEASE_DIRECTORY_NAME, MAX_LOCK_RECORD_BYTES, } from "./contracts.js";
+export async function readOwnerRecord(lockPath, entryName, expectedToken, directoryModifiedAtMs) {
+    let handle;
+    try {
+        handle = await open(join(lockPath, LEASE_DIRECTORY_NAME, entryName), constants.O_RDONLY | constants.O_NOFOLLOW);
+        const before = await handle.stat({ bigint: true });
+        const modifiedAtMs = Math.max(directoryModifiedAtMs, Number(before.mtimeMs));
+        const hasReadableRecord = before.isFile() &&
+            before.size > 0n &&
+            before.size <= BigInt(MAX_LOCK_RECORD_BYTES);
+        if (!hasReadableRecord) {
+            return directorySnapshot({
+                modifiedAtMs,
+                hasLeaseDirectory: true,
+                ownerFileName: entryName,
+                reclaimable: true,
+            });
+        }
+        const raw = await readStableRecord(handle, before);
+        if (raw === undefined) {
+            return directorySnapshot({
+                modifiedAtMs,
+                hasLeaseDirectory: true,
+                ownerFileName: entryName,
+                reclaimable: false,
+            });
+        }
+        const parsed = parseLockRecord(raw, expectedToken);
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            ownerFileName: entryName,
+            reclaimable: true,
+            ...parsed,
+        });
+    }
+    catch (error) {
+        return snapshotReadFailure(error, directoryModifiedAtMs, entryName);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function readStableRecord(handle, before) {
+    const bytes = Buffer.alloc(Number(before.size));
+    let offset = 0;
+    while (offset < bytes.length) {
+        const result = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (result.bytesRead <= 0)
+            return undefined;
+        offset += result.bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    const recordChangedWhileReading = !after.isFile() ||
+        after.dev !== before.dev ||
+        after.ino !== before.ino ||
+        after.size !== before.size ||
+        after.mtimeNs !== before.mtimeNs ||
+        after.ctimeNs !== before.ctimeNs;
+    return recordChangedWhileReading ? undefined : bytes.toString("utf8");
+}
+function snapshotReadFailure(error, modifiedAtMs, entryName) {
+    const code = fileSystemErrorCode(error);
+    if (code === "ENOENT") {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: false,
+        });
+    }
+    if (code === "ELOOP") {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            ownerFileName: entryName,
+            reclaimable: true,
+        });
+    }
+    throw error;
+}
+function parseLockRecord(raw, expectedToken) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return Object.freeze({});
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return Object.freeze({});
+    }
+    const candidate = value;
+    const ownerPid = Number.isSafeInteger(candidate.pid) && Number(candidate.pid) > 0
+        ? Number(candidate.pid)
+        : undefined;
+    const hasValidRecord = ownerPid !== undefined &&
+        candidate.token === expectedToken &&
+        typeof candidate.createdAt === "string" &&
+        Number.isFinite(Date.parse(candidate.createdAt));
+    if (!hasValidRecord) {
+        return Object.freeze({ ...(ownerPid === undefined ? {} : { ownerPid }) });
+    }
+    return Object.freeze({
+        ownerPid,
+        record: Object.freeze({
+            pid: ownerPid,
+            token: expectedToken,
+            createdAt: candidate.createdAt,
+        }),
+    });
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/snapshot.d.ts

@@ -0,0 +1,2 @@
+import { type LockSnapshot } from "./contracts.js";
+export declare function readLockSnapshot(lockPath: string): Promise<LockSnapshot | undefined>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/snapshot.js

@@ -0,0 +1,103 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { directorySnapshot, fileSystemErrorCode, LEASE_DIRECTORY_NAME, OWNER_FILE_PATTERN, } from "./contracts.js";
+import { readOwnerRecord } from "./owner-record.js";
+export async function readLockSnapshot(lockPath) {
+    const lockInfo = await readLockInfo(lockPath);
+    if (!lockInfo)
+        return undefined;
+    if (!lockInfo.isDirectory()) {
+        return Object.freeze({ kind: "legacy_file" });
+    }
+    let lockEntries;
+    try {
+        lockEntries = await readdir(lockPath, { withFileTypes: true });
+    }
+    catch (error) {
+        const code = fileSystemErrorCode(error);
+        if (code === "ENOENT")
+            return undefined;
+        if (code === "ENOTDIR") {
+            return Object.freeze({ kind: "legacy_file" });
+        }
+        throw error;
+    }
+    if (lockEntries.length === 0) {
+        return directorySnapshot({
+            modifiedAtMs: lockInfo.mtimeMs,
+            hasLeaseDirectory: false,
+            reclaimable: true,
+        });
+    }
+    const hasExpectedLeaseDirectory = lockEntries.length === 1 &&
+        lockEntries[0]?.name === LEASE_DIRECTORY_NAME &&
+        lockEntries[0].isDirectory();
+    if (!hasExpectedLeaseDirectory) {
+        return directorySnapshot({
+            modifiedAtMs: lockInfo.mtimeMs,
+            hasLeaseDirectory: false,
+            reclaimable: false,
+        });
+    }
+    return readLeaseSnapshot(lockPath, lockInfo.mtimeMs);
+}
+async function readLockInfo(lockPath) {
+    try {
+        return await lstat(lockPath);
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function readLeaseSnapshot(lockPath, lockModifiedAtMs) {
+    const leasePath = join(lockPath, LEASE_DIRECTORY_NAME);
+    let leaseInfo;
+    let leaseEntries;
+    try {
+        leaseInfo = await lstat(leasePath);
+        if (!leaseInfo.isDirectory()) {
+            return invalidLeaseSnapshot(lockModifiedAtMs);
+        }
+        leaseEntries = await readdir(leasePath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) === "ENOENT") {
+            return invalidLeaseSnapshot(lockModifiedAtMs);
+        }
+        throw error;
+    }
+    const modifiedAtMs = Math.max(lockModifiedAtMs, leaseInfo.mtimeMs);
+    if (leaseEntries.length === 0) {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: true,
+        });
+    }
+    if (leaseEntries.length !== 1 || !leaseEntries[0]?.isFile()) {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: false,
+        });
+    }
+    const entryName = leaseEntries[0].name;
+    const token = OWNER_FILE_PATTERN.exec(entryName)?.[1];
+    if (!token) {
+        return directorySnapshot({
+            modifiedAtMs,
+            hasLeaseDirectory: true,
+            reclaimable: false,
+        });
+    }
+    return readOwnerRecord(lockPath, entryName, token, modifiedAtMs);
+}
+function invalidLeaseSnapshot(modifiedAtMs) {
+    return directorySnapshot({
+        modifiedAtMs,
+        hasLeaseDirectory: false,
+        reclaimable: false,
+    });
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock.d.ts

@@ -0,0 +1,2 @@
+import type { FileLockOptions } from "./file-lock/contracts.js";
+export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/src/runtime/adapters/long-term-memory/file-lock.js

@@ -0,0 +1,10 @@
+import { acquireFileLock } from "./file-lock/acquisition.js";
+export async function withFileLock(lockPath, operation, options = {}) {
+    const release = await acquireFileLock(lockPath, options);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}

package/dist/src/runtime/adapters/long-term-memory/file-repository.d.ts

@@ -0,0 +1,2 @@
+import type { LongTermMemoryRepository } from "../../long-term-memory/contracts.js";
+export declare function createFileLongTermMemoryRepository(directory: string): LongTermMemoryRepository;

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

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { advanceMemorySnapshot, createEmptyMemorySnapshot, parseMemorySnapshot, } from "../../long-term-memory/repository-state.js";
+import { withFileLock } from "./file-lock.js";
+const STORE_FILE_NAME = "memory.json";
+const LOCK_FILE_NAME = "memory.lock";
+const PRIVATE_STORE_FILE_MODE = 0o600;
+export function createFileLongTermMemoryRepository(directory) {
+    const storePath = join(directory, STORE_FILE_NAME);
+    const lockPath = join(directory, LOCK_FILE_NAME);
+    return Object.freeze({
+        read: () => readSnapshot(storePath),
+        update: async (mutate) => {
+            await mkdir(directory, { recursive: true });
+            return withFileLock(lockPath, async () => {
+                const current = await readSnapshot(storePath);
+                const next = advanceMemorySnapshot(current, mutate(current));
+                await writeSnapshot(storePath, next);
+                return next;
+            });
+        },
+    });
+}
+async function readSnapshot(storePath) {
+    try {
+        return parseMemorySnapshot(JSON.parse(await readFile(storePath, "utf8")));
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return createEmptyMemorySnapshot();
+        }
+        throw error;
+    }
+}
+async function writeSnapshot(storePath, snapshot) {
+    await mkdir(dirname(storePath), { recursive: true });
+    const temporaryPath = `${storePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporaryPath, JSON.stringify(snapshot, null, 2), {
+            encoding: "utf8",
+            flag: "wx",
+            mode: PRIVATE_STORE_FILE_MODE,
+        });
+        await rename(temporaryPath, storePath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissingFile(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/src/runtime/adapters/long-term-memory/in-memory-repository.d.ts

@@ -0,0 +1,2 @@
+import type { LongTermMemoryRepository, LongTermMemoryRepositorySnapshot } from "../../long-term-memory/contracts.js";
+export declare function createInMemoryLongTermMemoryRepository(initial?: LongTermMemoryRepositorySnapshot): LongTermMemoryRepository;

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

@@ -0,0 +1,21 @@
+import { advanceMemorySnapshot, createEmptyMemorySnapshot, } from "../../long-term-memory/repository-state.js";
+export function createInMemoryLongTermMemoryRepository(initial = createEmptyMemorySnapshot()) {
+    let snapshot = initial;
+    let writeTail = Promise.resolve();
+    return Object.freeze({
+        async read() {
+            await writeTail;
+            return snapshot;
+        },
+        async update(mutate) {
+            let updated = snapshot;
+            const write = writeTail.then(() => {
+                updated = advanceMemorySnapshot(snapshot, mutate(snapshot));
+                snapshot = updated;
+            });
+            writeTail = write.catch(() => undefined);
+            await write;
+            return updated;
+        },
+    });
+}

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

@@ -0,0 +1,5 @@
+import type { LongTermMemoryOnboardingConfigRepository } from "../../long-term-memory/onboarding/contracts.js";
+export declare function createFileLongTermMemoryOnboardingConfigRepository(params: {
+    rootDir: string;
+    configPath?: string;
+}): LongTermMemoryOnboardingConfigRepository;

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,
     });