@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/runtime/adapters/long-term-memory/migration-backup.js

@@ -0,0 +1,44 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { parseMemorySnapshot } from "../../long-term-memory/repository-state.js";
+/** Preserve one private rollback snapshot before each incompatible replacement. */
+export async function preserveMemoryMigrationBackup(storePath, current, next) {
+    const version = memoryUpgradeVersion(current, next);
+    if (version === undefined)
+        return;
+    const original = await readExistingSnapshot(storePath);
+    if (original === undefined)
+        return;
+    const backupPath = `${storePath}.pre-v${version}.backup`;
+    try {
+        await writeFile(backupPath, original, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (!hasFileErrorCode(error, "EEXIST"))
+            throw error;
+        const existing = parseMemorySnapshot(JSON.parse(await readFile(backupPath, "utf8")));
+        if (existing.schemaVersion >= version)
+            throw new Error("long_term_memory_migration_backup_invalid");
+    }
+}
+function memoryUpgradeVersion(current, next) {
+    if (current.schemaVersion < 5 && next.schemaVersion === 5)
+        return 5;
+    if (current.schemaVersion < 4 && next.schemaVersion === 4)
+        return 4;
+    return undefined;
+}
+async function readExistingSnapshot(storePath) {
+    try {
+        return await readFile(storePath, "utf8");
+    }
+    catch (error) {
+        if (hasFileErrorCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+}
+function hasFileErrorCode(error, code) {
+    if (!error || typeof error !== "object")
+        return false;
+    return "code" in error && error.code === code;
+}

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

@@ -1,60 +1,34 @@
-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";
+import { ConfigFileConflictError, withConfigFileTransaction, } from "../config-file-transaction.js";
 export function createFileLongTermMemoryOnboardingConfigRepository(params) {
     const source = () => inspectRuntimeConfigFileWithMeta(params.rootDir, params.configPath);
     return Object.freeze({
         async read() {
             const current = source();
-            if (!current.exists) {
+            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) {
+            if (!current.exists)
                 throw new Error(`runtime_config_not_found:${current.path}`);
+            try {
+                return await withConfigFileTransaction(current.path, async (transaction) => {
+                    if (!transaction.snapshot.exists)
+                        throw new Error(`runtime_config_not_found:${current.path}`);
+                    const result = await transaction.write(config, { expectedConfig });
+                    return Object.freeze({
+                        configPath: transaction.path,
+                        backupPath: result.backupPath,
+                    });
+                });
             }
-            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) {
+            catch (error) {
+                if (error instanceof ConfigFileConflictError)
                     throw new Error("long_term_memory_config_changed");
-                }
-                return writeConfigSnapshot(lockedCurrent.path, config);
-            });
+                throw error;
+            }
         },
     });
 }
-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/passive-learning-runtime.d.ts

@@ -0,0 +1,28 @@
+import type { RuntimeConfig, ModelGatewayClient, SessionStore } from "../ports.js";
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+/** The environment owns learning; the paired desktop owns native collection. */
+export declare function createRuntimePassiveLearning(params: {
+    config: RuntimeConfig;
+    models: ModelGatewayClient;
+    memory: LongTermMemoryService;
+    sessions?: SessionStore;
+}): Readonly<{
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    configure(input: Partial<import("../passive-learning/contracts.js").PassiveLearningPreferences>): Promise<import("../passive-learning/contracts.js").PassiveLearningStatus>;
+    status(): Promise<import("../passive-learning/contracts.js").PassiveLearningStatus>;
+    clearPending(): Promise<import("../passive-learning/contracts.js").PassiveLearningStatus>;
+    restartCollection?(): Promise<import("../passive-learning/contracts.js").PassiveLearningStatus>;
+    batches(input?: Readonly<{
+        limit?: number;
+    }>): Promise<readonly import("../passive-learning/contracts.js").LearningBatchSummary[]>;
+    batch(id: string): Promise<import("../passive-learning/contracts.js").LearningBatch | undefined>;
+    accept(event: import("../../shared/passive-observation.js").HostObservationEvent): void;
+    flush(): Promise<void>;
+    beginInteractive(): () => void;
+    subscribe(listener: (event?: import("../passive-learning/contracts.js").LearningChangedEvent) => void): () => void;
+    dismissProposal?(id: string): Promise<void>;
+    sessionDeleted?(sessionId: string): Promise<void>;
+    notifyKnowledgeChanged?(): void;
+    candidates?(): Promise<readonly Omit<import("../long-term-memory/maturation/contracts.js").LearningCandidateRecord, "embedding">[]>;
+}>;

package/dist/src/runtime/adapters/passive-learning-runtime.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { connectHostObservations } from "../../computer-access/companion/observation-client.js";
+import { createPassiveLearningService } from "../passive-learning/service.js";
+import { createRuntimePassiveLearningModel } from "../passive-learning/model.js";
+import { createCoWorkerResourceDependencies } from "./co-worker-resources.js";
+/** The environment owns learning; the paired desktop owns native collection. */
+export function createRuntimePassiveLearning(params) {
+    const { config, models, memory } = params;
+    const ownerId = createHash("sha256")
+        .update(config.paths.runtimeDir)
+        .digest("hex");
+    return createPassiveLearningService({
+        ownerId,
+        directory: join(config.paths.runtimeDir, "passive-learning"),
+        memory,
+        model: createRuntimePassiveLearningModel({ config, models }),
+        backgroundDependencies: (context) => createCoWorkerResourceDependencies({
+            config, models, memory, context, ownerId, directory: join(config.paths.runtimeDir, "passive-learning"),
+            sessions: params.sessions,
+        }),
+        connect: (input) => connectHostObservations({
+            ...input,
+            ownerId,
+            rootDir: config.paths.rootDir,
+        }),
+    });
+}

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

@@ -28,12 +28,16 @@ function captureAdapter(toolName, adapter) {
         return undefined;
     const normalizeCall = adapter.normalizeCall;
     const validateCall = adapter.validateCall;
-    if ((normalizeCall !== undefined && typeof normalizeCall !== "function") ||
-        (validateCall !== undefined && typeof validateCall !== "function")) {
+    const executionBinding = adapter.executionBinding;
+    if (!hasOnlyAdapterFunctions([normalizeCall, validateCall, executionBinding])) {
         throw new TypeError(`Invalid ordinary invocation adapter registration: ${toolName}`);
     }
     return Object.freeze({
         ...(normalizeCall ? { normalizeCall } : {}),
         ...(validateCall ? { validateCall } : {}),
+        ...(executionBinding ? { executionBinding } : {}),
     });
 }
+function hasOnlyAdapterFunctions(values) {
+    return values.every((value) => value === undefined || typeof value === "function");
+}

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

@@ -1,8 +1,11 @@
 import type { ToolCall } from "../../../../capabilities/tool-types.js";
 import { type ToolEventExecutorIdentity } from "../shared/event-metadata.js";
-import type { ToolApprovalController, ToolPermissionMode } from "../../../ports.js";
+import type { ToolApprovalController, ToolApprovalRequest, ToolApprovalDecision, ToolPermissionMode } from "../../../ports.js";
 import type { RegisteredToolNormalInvocationRejection } from "../shared/contracts.js";
 export declare function requestNormalInvocationApproval(params: {
+    preparedRequest?: ToolApprovalRequest;
+    decision?: ToolApprovalDecision;
+    decisionRecorded?: boolean;
     executionId?: string;
     executorIdentity?: ToolEventExecutorIdentity;
     requestId: string;

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

@@ -1,15 +1,26 @@
+import { requiresToolActionApproval } from "../../../../capabilities/tool-permission-mode.js";
 import { buildToolExecutorEventMetadata, } from "../shared/event-metadata.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
+function recommendsFullPlusForForcedAction(mode, force) {
+    if (mode !== "full_access")
+        return false;
+    return force;
+}
 export async function requestNormalInvocationApproval(params) {
-    if (!params.force && params.toolPermissionMode !== "ask") {
+    if (!requiresToolActionApproval(params.toolPermissionMode, params.force)) {
         return Object.freeze({ ok: true });
     }
-    const approvalId = params.nextApprovalId();
+    const approvalId = params.preparedRequest?.approvalId ?? params.nextApprovalId();
+    if (params.decision)
+        return applyDecision(params, approvalId, params.decision);
     params.onEvent?.("tool.approval.required", {
         ...buildToolExecutorEventMetadata(params.executorIdentity),
         ...(params.executionId ? { executionId: params.executionId } : {}),
         approvalId,
         tool: params.call.tool,
+        ...(recommendsFullPlusForForcedAction(params.toolPermissionMode, params.force)
+            ? { recommendedToolPermissionMode: "full_plus" }
+            : {}),
         ...(params.eventMeta ? { meta: params.eventMeta } : {}),
     });
     if (!params.toolApprovalController) {
@@ -27,28 +38,35 @@ export async function requestNormalInvocationApproval(params) {
         };
     }
     const decision = await params.toolApprovalController.requestToolApproval({
-        requestId: params.requestId,
-        approvalId,
-        call: params.call,
-        ...(params.eventMeta ? { meta: params.eventMeta } : {}),
+        ...(params.preparedRequest ?? {
+            requestId: params.requestId,
+            approvalId,
+            call: params.call,
+            ...(params.eventMeta ? { meta: params.eventMeta } : {}),
+        }),
     }, { abortSignal: params.abortSignal });
+    return applyDecision(params, approvalId, decision);
+}
+function applyDecision(params, approvalId, decision) {
     if (decision.approved) {
-        params.onEvent?.("tool.approval.granted", {
+        if (!params.decisionRecorded)
+            params.onEvent?.("tool.approval.granted", {
+                ...buildToolExecutorEventMetadata(params.executorIdentity),
+                ...(params.executionId ? { executionId: params.executionId } : {}),
+                approvalId,
+                tool: params.call.tool,
+            });
+        return Object.freeze({ ok: true });
+    }
+    const message = decision.reason?.trim() || "Tool execution was rejected.";
+    if (!params.decisionRecorded)
+        params.onEvent?.("tool.approval.rejected", {
             ...buildToolExecutorEventMetadata(params.executorIdentity),
             ...(params.executionId ? { executionId: params.executionId } : {}),
             approvalId,
             tool: params.call.tool,
+            reason: message,
         });
-        return Object.freeze({ ok: true });
-    }
-    const message = decision.reason?.trim() || "Tool execution was rejected.";
-    params.onEvent?.("tool.approval.rejected", {
-        ...buildToolExecutorEventMetadata(params.executorIdentity),
-        ...(params.executionId ? { executionId: params.executionId } : {}),
-        approvalId,
-        tool: params.call.tool,
-        reason: message,
-    });
     return {
         ok: false,
         rejection: rejectNormalInvocation("tool_approval_rejected", message),

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

@@ -0,0 +1,11 @@
+import type { ToolCall, ToolCallAdapter } from "../../../../capabilities/tool-types.js";
+import { rejectNormalInvocation } from "../shared/rejection.js";
+/** Private execution identity and human disclosure never enter model controls. */
+export declare function captureExecutionBinding(adapter: ToolCallAdapter | undefined, call: ToolCall): Readonly<{
+    ok: true;
+    identity?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}> | Readonly<{
+    ok: false;
+    rejection: ReturnType<typeof rejectNormalInvocation>;
+}>;

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

@@ -0,0 +1,37 @@
+import { rejectNormalInvocation } from "../shared/rejection.js";
+/** Private execution identity and human disclosure never enter model controls. */
+export function captureExecutionBinding(adapter, call) {
+    if (!adapter?.executionBinding)
+        return { ok: true };
+    try {
+        const binding = adapter.executionBinding(call);
+        if (!hasBoundExecutionIdentity(binding)) {
+            return rejectExecutionBinding();
+        }
+        return Object.freeze({
+            ok: true,
+            identity: binding.identity,
+            ...(binding.metadata
+                ? { metadata: Object.freeze(structuredClone(binding.metadata)) }
+                : {}),
+        });
+    }
+    catch {
+        return rejectExecutionBinding();
+    }
+}
+function hasBoundExecutionIdentity(binding) {
+    if (!binding || typeof binding !== "object")
+        return false;
+    if (!("identity" in binding))
+        return false;
+    if (typeof binding.identity !== "string")
+        return false;
+    return binding.identity.trim().length > 0;
+}
+function rejectExecutionBinding() {
+    return {
+        ok: false,
+        rejection: rejectNormalInvocation("normal_invocation_execution_binding_unavailable", "The registered action could not bind its execution destination for this request."),
+    };
+}

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/file-output-presentation.d.ts

@@ -0,0 +1,7 @@
+import { type ToolFileOutputReporter } from "../../../../capabilities/file-output-presentation.js";
+import type { ToolEventMetadata, ToolExecutionResult, ToolExecutionSharedState, ToolNormalInvocationEffect } from "../../../../capabilities/tool-types.js";
+/** One invocation-local presentation collector; canonical results are untouched. */
+export declare function createFileOutputPresentation(runtimePaths: ToolExecutionSharedState["runtimePaths"]): Readonly<{
+    report: ToolFileOutputReporter;
+    finish(result: ToolExecutionResult, metadata: ToolEventMetadata | undefined, effect: ToolNormalInvocationEffect): ToolEventMetadata | undefined;
+}>;

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/file-output-presentation.js

@@ -0,0 +1,105 @@
+import { isAbsolute } from "node:path";
+import { isToolFileOutputLocation, parseToolFileOutputRootIdentity, parseToolFileOutputReceipt, } from "../../../../capabilities/file-output-presentation.js";
+import { createRuntimeToolPathResolver } from "../../../capabilities/runtime-target-path.js";
+import { captureFileOutputRootId } from "../../../capabilities/file-output-root-identity.js";
+function matchesReportedFileTarget(target, resolved) {
+    if (target.location !== resolved.location)
+        return false;
+    if (target.rootPath !== resolved.rootPath)
+        return false;
+    if (target.absolutePath !== resolved.absolutePath)
+        return false;
+    if (target.relativePath !== resolved.relativePath)
+        return false;
+    return target.logicalPath === resolved.logicalPath;
+}
+function captureReportedFileOutput(report, resolver) {
+    const rootIdentity = parseToolFileOutputRootIdentity(report.rootIdentity);
+    if (!rootIdentity)
+        return undefined;
+    const target = report.target;
+    if (!isToolFileOutputLocation(target.location))
+        return undefined;
+    if (!isAbsolute(target.absolutePath))
+        return undefined;
+    const resolved = resolver.resolve(target.absolutePath, {
+        requirePath: true,
+        allowedLocations: [target.location],
+    });
+    if (!matchesReportedFileTarget(target, resolved))
+        return undefined;
+    return parseToolFileOutputReceipt({
+        version: 1,
+        location: target.location,
+        rootId: captureFileOutputRootId(target.location, resolved.rootPath, rootIdentity),
+        relativePath: target.relativePath,
+        logicalPath: target.logicalPath,
+        operation: report.operation,
+    });
+}
+function isSameFileOutputReceipt(left, right) {
+    if (left.rootId !== right.rootId)
+        return false;
+    if (left.relativePath !== right.relativePath)
+        return false;
+    return left.operation === right.operation;
+}
+function hasConflictingFileOutputReceipt(previous, next) {
+    if (!previous)
+        return false;
+    return !isSameFileOutputReceipt(previous, next);
+}
+function canPublishFileOutput(result, effect) {
+    if (!result.ok)
+        return false;
+    if (result.data?.mutationEvidence !== true)
+        return false;
+    return effect !== "read_only";
+}
+function omitReservedFileOutput(metadata) {
+    const { fileOutput: _untrustedFileOutput, ...rest } = metadata ?? {};
+    return rest;
+}
+/** One invocation-local presentation collector; canonical results are untouched. */
+export function createFileOutputPresentation(runtimePaths) {
+    const resolver = createRuntimeToolPathResolver(runtimePaths);
+    let receipt;
+    let rejected = false;
+    let finished = false;
+    const report = (input) => {
+        if (finished)
+            return;
+        if (rejected)
+            return;
+        try {
+            const captured = captureReportedFileOutput(input, resolver);
+            if (!captured) {
+                rejected = true;
+                return;
+            }
+            if (hasConflictingFileOutputReceipt(receipt, captured)) {
+                rejected = true;
+                return;
+            }
+            receipt = captured;
+        }
+        catch {
+            rejected = true;
+        }
+    };
+    return Object.freeze({
+        report,
+        finish(result, metadata, effect) {
+            finished = true;
+            const base = omitReservedFileOutput(metadata);
+            const fallback = Object.keys(base).length > 0 ? base : undefined;
+            if (rejected)
+                return fallback;
+            if (!receipt)
+                return fallback;
+            if (!canPublishFileOutput(result, effect))
+                return fallback;
+            return { ...base, fileOutput: receipt };
+        },
+    });
+}

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

@@ -0,0 +1,16 @@
+import type { ToolCall } from "../../../../capabilities/tool-types.js";
+import type { ToolApprovalRequest } from "../../../ports.js";
+import type { BoundOperation, RegisteredToolNormalInvocationExecutorParams, RegisteredToolPreparedNormalInvocation } from "../shared/contracts.js";
+export declare function createPreparedNormalInvocation(params: {
+    executor: RegisteredToolNormalInvocationExecutorParams;
+    source: BoundOperation;
+    target: BoundOperation;
+    call: ToolCall;
+    actionFingerprint: string;
+    acceptedControls: Readonly<Record<string, unknown>>;
+    intent?: string;
+    eventMeta?: Record<string, unknown>;
+    executionIdentity?: string;
+    executionMetadata?: Readonly<Record<string, unknown>>;
+    restoredApprovalRequest?: ToolApprovalRequest;
+}): RegisteredToolPreparedNormalInvocation;

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 {};