@abot-ai/runtime 1.4.0 → 1.6.0

package/dist/src/runtime/adapters/co-worker-resources.js

@@ -0,0 +1,74 @@
+import { createRuntimePassiveLearningModel } from "../passive-learning/model.js";
+import { CoWorkerResourceBudget } from "../passive-learning/resources/budget.js";
+import { DEFAULT_CO_WORKER_RESOURCE_LIMITS } from "../passive-learning/resources/contracts.js";
+import { createCoWorkerResourceGateway } from "../passive-learning/resources/gateway.js";
+import { createRuntimeProactiveModel } from "../passive-learning/proactive/model.js";
+import { CoWorkerProactiveAgent } from "../passive-learning/proactive/agent.js";
+import { isWithinAnalysisWindow } from "../passive-learning/analysis-schedule.js";
+import { ScheduledLearningReassessment } from "../passive-learning/scheduled-reassessment.js";
+/** The environment shares one budget; foreground chat keeps its original clients. */
+export function createCoWorkerResourceDependencies(options) {
+    const { context } = options;
+    const budget = new CoWorkerResourceBudget({ directory: options.directory, limits: () => {
+            const preferences = context.preferences();
+            return { ...(preferences.resourceLimits ?? DEFAULT_CO_WORKER_RESOURCE_LIMITS), maxConcurrentCalls: preferences.maxConcurrentBatches ?? 1 };
+        } });
+    const original = createRuntimePassiveLearningModel(options);
+    const processingGateway = createCoWorkerResourceGateway({
+        gateway: options.models, budget, activity: "processing", assertActivityAllowed: context.assertProcessingAllowed,
+        supportsParallel: () => original.supportsParallelBatches?.(context.preferences().modelProfileId ?? "") ?? false,
+    });
+    async function assertMemoryAvailable(signal) {
+        signal.throwIfAborted();
+        context.assertProcessingAllowed();
+        const status = await options.memory.status();
+        signal.throwIfAborted();
+        context.assertProcessingAllowed();
+        if (!status.enabled || !status.available)
+            throw new Error("learning_memory_unavailable");
+    }
+    const gateway = {
+        ...processingGateway,
+        async invoke(input) { await assertMemoryAvailable(input.abortSignal); return processingGateway.invoke(input); },
+        async invokeRaw(input) { await assertMemoryAvailable(input.abortSignal); return processingGateway.invokeRaw(input); },
+        ...(processingGateway.embed ? { embed: async (input) => {
+                await assertMemoryAvailable(input.abortSignal);
+                return processingGateway.embed(input);
+            } } : {}),
+    };
+    const beforeEmbedding = async ({ signal, characters }) => {
+        await assertMemoryAvailable(signal);
+        return budget.reserve({ kind: "embedding", activity: "processing", signal, embeddingCharacters: characters,
+            supportsParallel: false, assertActivityAllowed: context.assertProcessingAllowed });
+    };
+    const learning = options.memory.learning;
+    const memory = {
+        ...options.memory,
+        ...(learning ? { learning: {
+                ...learning,
+                prepare: (input) => learning.prepare({ ...input, beforeEmbedding }),
+                apply: (input) => learning.apply({ ...input, beforeEmbedding }),
+            } } : {}),
+    };
+    const proactiveGateway = createCoWorkerResourceGateway({
+        gateway: options.models, budget, activity: "proactive",
+        assertActivityAllowed: () => {
+            if (!context.isStarted() || context.isInteractiveBusy() || !context.preferences().proactiveEnabled)
+                throw new Error("proactive_disabled");
+            if (!isWithinAnalysisWindow(Date.now(), context.preferences().proactiveWindow))
+                throw new Error("proactive_outside_window");
+        },
+        supportsParallel: () => original.supportsParallelBatches?.(context.preferences().proactiveModelProfileId ?? context.preferences().modelProfileId ?? "") ?? false,
+    });
+    const proactive = learning && options.sessions ? new CoWorkerProactiveAgent({ directory: options.directory,
+        context, memory: learning, sessions: options.sessions, budget, deliveryAdmission: options.deliveryAdmission,
+        model: createRuntimeProactiveModel({ config: options.config, models: proactiveGateway, sessions: options.sessions }) }) : undefined;
+    const model = createRuntimePassiveLearningModel({ ...options, models: gateway });
+    const reassessment = memory.learning ? new ScheduledLearningReassessment({ directory: options.directory,
+        environmentId: options.ownerId, context, memory: memory.learning, model,
+        resourceUsage: () => budget.status(), changed: () => { proactive?.knowledgeChanged(); context.changed(); } }) : undefined;
+    return { model, memory,
+        ...(proactive ? { proactive } : {}),
+        ...(reassessment ? { reassessment } : {}),
+        resourceUsage: () => budget.status() };
+}

package/dist/src/runtime/adapters/config-file-transaction.js

@@ -62,9 +62,16 @@ function parseSnapshotConfig(raw, options) {
         };
     }
 }
+async function requireRegularConfigFile(path) {
+    if ((await stat(path)).isFile())
+        return;
+    throw new Error("Configuration path must be a regular file.");
+}
 async function readSnapshot(path, options = {}) {
     let raw;
     try {
+        // Inspect before opening: special entries such as FIFOs can block a read.
+        await requireRegularConfigFile(path);
         raw = await readFile(path);
     }
     catch (error) {

package/dist/src/runtime/adapters/default-session-adapters.d.ts

@@ -1,3 +1,3 @@
 import type { ConversationContextProvider, SessionStore } from "../ports.js";
-export declare const defaultRuntimeSessionStore: Pick<SessionStore, "appendMessage" | "appendContextEntry" | "appendRequestEvent" | "compareAndSwapSessionMemoryCheckpoint" | "getAllSessions" | "getOrCreateSession" | "startRequestStream" | "upsertArtifactPaths" | "updateSessionRuntimeMode" | "updateSessionTitle">;
+export declare const defaultRuntimeSessionStore: Pick<SessionStore, "appendMessage" | "requestLifecycle" | "appendContextEntry" | "appendRequestEvent" | "compareAndSwapSessionMemoryCheckpoint" | "getAllSessions" | "getOrCreateSession" | "startRequestStream" | "upsertArtifactPaths" | "updateSessionRuntimeMode" | "updateSessionTitle">;
 export declare const defaultRuntimeConversationContextProvider: Pick<ConversationContextProvider, "buildContextBuckets">;

package/dist/src/runtime/adapters/file-session-store.js

@@ -2,6 +2,14 @@ import { SessionService } from "../../sessions/session-service.js";
 export function createFileSessionStore(options = {}) {
     const service = new SessionService(options);
     return {
+        requestLifecycle: service.requestLifecycle,
+        assertInteractiveSession: service.assertInteractiveSession.bind(service),
+        createAutomationSession: service.createAutomationSession.bind(service),
+        runAsAutomationSession: service.runAsAutomationSession.bind(service),
+        releaseAutomationSession: service.releaseAutomationSession.bind(service),
+        reconcileAutomationSessions: service.reconcileAutomationSessions.bind(service),
+        createAssistantConversation: service.createAssistantConversation.bind(service),
+        appendAssistantInitiative: service.appendAssistantInitiative.bind(service),
         getOrCreateSession: service.getOrCreateSession.bind(service),
         getAllSessions: service.getAllSessions.bind(service),
         listSessions: service.listSessions.bind(service),

package/dist/src/runtime/adapters/in-memory-session-store.js

@@ -4,10 +4,13 @@ import { assertValidSessionArtifactPathInputs, upsertSessionArtifactPaths, } fro
 import { clientVisibleMessages, compactRequestEvents, filterMessagesAfter, getRequestFinalState, getSessionRequest, isSameMessageId, normalizeAfterSeq, normalizeCursor, normalizeLimit, normalizeSessionTitle, toClientReplayEvent, toEpochMs, toSessionListItem, toSnapshotMessage, toSnapshotRequest, } from "../../sessions/record/projection.js";
 import { assertValidRequestId, assertValidSessionId, createContextEntryId, defaultCreateMessageId, pruneSupersededContextEntries, } from "../../sessions/record/rules.js";
 import { resolveSessionMemoryCheckpointCommit } from "../../sessions/memory/rules.js";
+import { assertSessionKindUnchanged, sessionKindCreationFields } from "../../sessions/spark-session.js";
+import { appendSparkInitiativeRecord } from "../../sessions/assistant-initiative-append.js";
 export function createInMemorySessionStore(options = {}) {
     const store = new InMemorySessionStore(options);
     return {
         getOrCreateSession: store.getOrCreateSession.bind(store),
+        appendAssistantInitiative: store.appendAssistantInitiative.bind(store),
         getAllSessions: store.getAllSessions.bind(store),
         listSessions: store.listSessions.bind(store),
         getSessionById: store.getSessionById.bind(store),
@@ -47,6 +50,7 @@ class InMemorySessionStore {
         const existing = this.sessions.get(sessionId);
         if (existing) {
             assertSessionProjectUnchanged(existing, options.project);
+            assertSessionKindUnchanged(existing, options.kind);
             return cloneSession(existing);
         }
         const timestamp = toIso(this.now);
@@ -55,7 +59,7 @@ class InMemorySessionStore {
             ...(options.project
                 ? { project: copySessionProject(options.project) }
                 : {}),
-            title: sessionId,
+            ...sessionKindCreationFields(sessionId, options),
             createdAt: timestamp,
             updatedAt: timestamp,
             lastAgentMode: "reasoning",
@@ -70,6 +74,14 @@ class InMemorySessionStore {
             .map(cloneSession)
             .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     }
+    async appendAssistantInitiative(sessionId, input) {
+        return this.runSessionMutation(sessionId, async () => {
+            const record = appendSparkInitiativeRecord(this.sessions.get(sessionId) ?? null, sessionId, input, this.now());
+            input.assertCurrent?.();
+            this.saveSession(record);
+            return cloneSession(record);
+        });
+    }
     async listSessions(params = {}) {
         const limit = normalizeLimit(params.limit);
         const offset = normalizeCursor(params.cursor);
@@ -93,6 +105,7 @@ class InMemorySessionStore {
         }
         return {
             sessionId,
+            ...(session.kind ? { kind: session.kind } : {}),
             ...(session.project ? { project: session.project } : {}),
             title: session.title,
             messages: filterMessagesAfter(clientVisibleMessages(session.messages), options.afterMessageId).map((message) => toSnapshotMessage(sessionId, message, session.requests ?? [])),

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

@@ -3,6 +3,7 @@ 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";
+import { preserveMemoryMigrationBackup } from "./migration-backup.js";
 const STORE_FILE_NAME = "memory.json";
 const LOCK_FILE_NAME = "memory.lock";
 const PRIVATE_STORE_FILE_MODE = 0o600;
@@ -16,6 +17,7 @@ export function createFileLongTermMemoryRepository(directory) {
             return withFileLock(lockPath, async () => {
                 const current = await readSnapshot(storePath);
                 const next = advanceMemorySnapshot(current, mutate(current));
+                await preserveMemoryMigrationBackup(storePath, current, next);
                 await writeSnapshot(storePath, next);
                 return next;
             });

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

@@ -0,0 +1,3 @@
+import type { LongTermMemoryRepositorySnapshot } from "../../long-term-memory/contracts.js";
+/** Preserve one private rollback snapshot before each incompatible replacement. */
+export declare function preserveMemoryMigrationBackup(storePath: string, current: LongTermMemoryRepositorySnapshot, next: LongTermMemoryRepositorySnapshot): Promise<void>;

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-service.d.ts

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

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

@@ -3,10 +3,11 @@ import { createLongTermMemoryOnboardingService } from "../../long-term-memory/on
 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 } : {}),
-    });
+    const repository = params.repository ??
+        createFileLongTermMemoryOnboardingConfigRepository({
+            rootDir: params.rootDir,
+            ...(params.configPath ? { configPath: params.configPath } : {}),
+        });
     return createLongTermMemoryOnboardingService({
         repository,
         probe: async (input) => {

package/dist/src/runtime/adapters/passive-learning-runtime.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeConfig, ModelGatewayClient, SessionStore } from "../ports.js";
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+import type { SessionRequestAdmission } from "../request/session-admission.js";
+/** The environment owns learning; the paired desktop owns native collection. */
+export declare function createRuntimePassiveLearning(params: {
+    config: RuntimeConfig;
+    models: ModelGatewayClient;
+    memory: LongTermMemoryService;
+    sessions?: SessionStore;
+    deliveryAdmission?: Pick<SessionRequestAdmission, "run">;
+}): 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;
+    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, deliveryAdmission: params.deliveryAdmission,
+        }),
+        connect: (input) => connectHostObservations({
+            ...input,
+            ownerId,
+            rootDir: config.paths.rootDir,
+        }),
+    });
+}

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

@@ -10,7 +10,9 @@ export async function requestNormalInvocationApproval(params) {
     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 } : {}),
@@ -36,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/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,203 @@
+import { createRegisteredToolResultBudget, assertRegisteredToolResultMetadataFits, } from "./result-budget.js";
+import { randomUUID } from "node:crypto";
+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 { rejectNormalInvocation } from "../shared/rejection.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, selectedReferences) => executePreparedNormalInvocation({
+            ...params,
+            selectedReferences,
+            ...(approvalRequest ? { approvalRequest } : {}),
+            ...(decision ? { decision, decisionRecorded } : {}),
+            ...(executionId ? { executionId } : {}),
+            ...(executorIdentity ? { executorIdentity } : {}),
+        }),
+    });
+}
+async function executePreparedNormalInvocation(params) {
+    const resultBudget = createRegisteredToolResultBudget({
+        call: params.call,
+        definition: params.target.registration.definition,
+        selectedReferences: params.selectedReferences,
+    });
+    assertRegisteredToolResultMetadataFits(resultBudget);
+    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 effectExecutionId = params.executionId ?? randomUUID();
+    const identity = (binding) => ({
+        toolName: binding.registration.toolName,
+        operationId: binding.operation.operationId,
+        contractVersion: binding.registration.contract.version,
+    });
+    const effectAdmission = await params.executor.effectPersistence?.beforeEffect({
+        executionId: effectExecutionId,
+        actionFingerprint: params.actionFingerprint,
+        source: identity(params.source),
+        target: identity(params.target),
+        effect: params.target.operation.effect,
+    });
+    const abortedBeforeDispatch = params.executor.abortSignal.aborted;
+    if (abortedBeforeDispatch) {
+        await params.executor.effectPersistence?.afterEffect({
+            executionId: effectExecutionId,
+            outcome: rejectNormalInvocation("request_aborted", "The operation was stopped before it began."),
+        });
+    }
+    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);
+    let result;
+    try {
+        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,
+                resultBudget,
+                ...(effectAdmission ? { trustedEffectAdmission: effectAdmission } : {}),
+                reportFileOutput: fileOutputPresentation.report,
+                ...(params.executor.sharedState
+                    ? { sharedState: params.executor.sharedState }
+                    : {}),
+            },
+        });
+    }
+    catch (error) {
+        await params.executor.effectPersistence?.afterEffect({
+            executionId: effectExecutionId,
+            outcome: {
+                status: "uncertain",
+                error: error instanceof Error ? error.message : String(error),
+            },
+        });
+        throw error;
+    }
+    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;
+    const settled = Object.freeze({
+        status: "executed",
+        effect: params.target.operation.effect,
+        result,
+        completionActions,
+    });
+    await params.executor.effectPersistence?.afterEffect({
+        executionId: effectExecutionId,
+        outcome: settled,
+    });
+    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 settled;
+}

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