@xopcai/xopc 0.0.312 → 0.0.314

package/dist/src/capabilities/adapters/http.js

@@ -0,0 +1,44 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { CapabilityError } from "../runtime/errors.js";
+import "../runtime/dispatcher.js";
+import { getGatewayPrincipal } from "../../gateway/security/gateway-principal.js";
+//#region src/capabilities/adapters/http.ts
+init_logger();
+const log = createLogger("Capabilities:Http");
+function capabilityHttpContext(c) {
+	const principal = getGatewayPrincipal(c);
+	return {
+		principalId: principal.principalId,
+		surface: "http",
+		scopes: principal.scopes,
+		actor: {
+			kind: "user",
+			id: principal.principalId
+		},
+		authorize: () => true,
+		signal: c.req.raw.signal
+	};
+}
+function capabilityHttpError(c, error) {
+	const code = error instanceof CapabilityError ? error.code : "INTERNAL";
+	if (code === "INTERNAL") log.error({
+		err: error,
+		path: c.req.path,
+		phase: "invoke"
+	}, "Capability execution failed");
+	const status = code === "INVALID_INPUT" ? 400 : code === "FORBIDDEN" ? 403 : code === "NOT_FOUND" ? 404 : [
+		"CONTRACT_CHANGED",
+		"REVISION_CONFLICT",
+		"IN_PROGRESS",
+		"OUTCOME_UNKNOWN"
+	].includes(code) ? 409 : code === "UNAVAILABLE" ? 503 : code === "CANCELLED" ? 409 : 500;
+	return c.json({
+		ok: false,
+		code,
+		error: error instanceof CapabilityError ? error.message : "Capability execution failed",
+		...error instanceof CapabilityError && error.operationId ? { operationId: error.operationId } : {}
+	}, status);
+}
+//#endregion
+export { capabilityHttpContext, capabilityHttpError };

package/dist/src/capabilities/readiness/from-config.js

@@ -1,15 +1,15 @@
 import { getAgentDefaultImageGenerationModelConfig, getAgentDefaultImageModelConfig, init_schema, parseModelRef } from "../../config/schema.js";
-import { init_model_policy, isComputerModel } from "../../computer/model-policy.js";
+import { init_model_policy, isComputerModel, isDedicatedComputerProfile } from "../../computer/model-policy.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../../providers/model-catalog-store.js";
 import { init_providers, isProviderConfiguredSync, resolveModel } from "../../providers/index.js";
 import { compareCatalogModels } from "../../providers/model-catalog-ranking.js";
 import { DEFAULT_LOCAL_VOICE_MODEL_ID, hasInstalledLocalVoiceModel } from "../../voice/local/models.js";
 import { planCapabilities } from "./planner.js";
 //#region src/capabilities/readiness/from-config.ts
+init_model_policy();
 init_schema();
 init_model_catalog_store();
 init_providers();
-init_model_policy();
 function buildCapabilityPlansForConfig(config, options = {}) {
 	const catalog = options.catalog ?? getModelCatalogStore().load();
 	const cloud = catalog.sources["xopc-cloud"];
@@ -114,11 +114,15 @@ function cloudCandidates(capability, models, authorized, basePriority = 0, recom
 function matchesCapability(model, capability) {
 	if (model.availability !== "available") return false;
 	switch (capability) {
-		case "vision": return model.kind === "language" && model.input.includes("image") && !model.computerUse;
-		case "computer-use": return model.operations.includes("chat.completions") && isComputerModel({
-			...model,
-			api: "openai-completions"
-		});
+		case "vision": return model.kind === "language" && model.input.includes("image") && !isDedicatedComputerProfile(model.computerUse?.profile);
+		case "computer-use":
+			if (!model.computerUse) return false;
+			if (model.computerUse.profile === "openai-responses-computer-v1" && !model.operations.includes("responses")) return false;
+			if (model.computerUse.profile !== "openai-responses-computer-v1" && !model.operations.includes("chat.completions")) return false;
+			return isComputerModel({
+				...model,
+				api: model.computerUse.profile === "openai-responses-computer-v1" ? "openai-responses" : "openai-completions"
+			});
 		case "image-generation": return model.kind === "image" && model.operations.includes("images.generate");
 		case "stt": return model.kind === "stt" && model.operations.includes("audio.transcription");
 		case "tts": return model.kind === "tts" && model.operations.includes("audio.speech") && Boolean(model.tts?.defaultVoice);

package/dist/src/capabilities/runtime/app-context.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDispatcher } from './dispatcher.js';
+/** Resolve each reference through its own capability, never through client-supplied authority. */
+export declare function registerAppContextCapability(dispatcher: CapabilityDispatcher): void;

package/dist/src/capabilities/runtime/app-context.js

@@ -0,0 +1,72 @@
+import { AppContextEnvelopeSchema, ResolvedAppContextSchema, parseAppContextEnvelope } from "../../../packages/gateway-contract/src/app-context.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityError } from "./errors.js";
+import { defineReadCapability } from "./dispatcher.js";
+//#region src/capabilities/runtime/app-context.ts
+init_src();
+/** Resolve each reference through its own capability, never through client-supplied authority. */
+function registerAppContextCapability(dispatcher) {
+	dispatcher.register(defineReadCapability({
+		id: "xopc.context.resolve",
+		majorVersion: 1,
+		effect: "read",
+		scopes: [],
+		surfaces: ["http", "agent"],
+		description: "Resolve an explicit immutable page snapshot at its observed revisions; supplied text grants no authority.",
+		input: AppContextEnvelopeSchema,
+		output: ResolvedAppContextSchema,
+		async execute(input, context) {
+			let snapshot;
+			try {
+				snapshot = parseAppContextEnvelope(input);
+			} catch (error) {
+				throw new CapabilityError("INVALID_INPUT", error instanceof Error ? error.message : "Invalid app context");
+			}
+			const resources = [];
+			const quota = Math.floor(16e3 / Math.max(1, snapshot.resourceRefs.length));
+			for (const reference of snapshot.resourceRefs) {
+				const domain = reference.kind === "local_app" ? "local_apps" : `${reference.kind}s`;
+				const row = (await dispatcher.call(`xopc.${domain}.get`, { id: reference.id }, context))[reference.kind === "scene" ? "activation" : reference.kind === "local_app" ? "app" : reference.kind];
+				if (!row) throw new CapabilityError("INTERNAL", "Resource returned no context object");
+				let revision;
+				let text;
+				switch (reference.kind) {
+					case "note":
+						revision = row.remoteVersion ?? 1;
+						text = String(row.markdown ?? "");
+						break;
+					case "task":
+						revision = row.version;
+						text = String(row.body ?? row.contract?.objective ?? "");
+						break;
+					case "project":
+						revision = row.version;
+						text = String(row.brief ?? row.description ?? "");
+						break;
+					case "scene":
+						revision = row.revision;
+						text = String(row.goal ?? "");
+						break;
+					case "local_app":
+						revision = (await dispatcher.call("xopc.local_apps.validate", { id: reference.id }, context)).validation.sourceHash;
+						text = String(row.idea ?? row.description ?? "");
+						break;
+				}
+				if (revision === void 0 || String(revision) !== reference.revision) throw new CapabilityError("REVISION_CONFLICT", "A page resource changed; capture its current revision again");
+				resources.push({
+					reference,
+					title: String(row.title ?? row.name ?? (reference.kind === "scene" ? row.goal : void 0) ?? reference.id),
+					text: text.slice(0, quota),
+					truncated: text.length > quota
+				});
+			}
+			return {
+				snapshot,
+				resources,
+				selectionTrust: "user-supplied"
+			};
+		}
+	}));
+}
+//#endregion
+export { registerAppContextCapability };

package/dist/src/capabilities/runtime/atomic-operations.d.ts

@@ -0,0 +1,11 @@
+export declare class OperationConflictError extends Error {
+}
+/** Only synchronous, same-database effects belong here. No leases or retries are needed under SQLite's write lock. */
+export declare function executeAtomicOperation(input: {
+    principalId: string;
+    capabilityId: string;
+    idempotencyKey: string;
+    requestDigest: string;
+    descriptorDigest: string;
+    surface: string;
+}, execute: (operationId: string) => unknown): unknown;

package/dist/src/capabilities/runtime/atomic-operations.js

@@ -0,0 +1,34 @@
+import { init_operation_context, withOperation } from "../../infra/operation-context.js";
+import { init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { randomUUID } from "node:crypto";
+//#region src/capabilities/runtime/atomic-operations.ts
+init_transaction();
+init_operation_context();
+var OperationConflictError = class extends Error {};
+/** Only synchronous, same-database effects belong here. No leases or retries are needed under SQLite's write lock. */
+function executeAtomicOperation(input, execute) {
+	return runSqliteWriteTransaction((db) => {
+		const existing = db.prepare(`SELECT operation_id, request_digest, descriptor_digest, result_json, state, recovery_mode
+      FROM capability_operations WHERE principal_id = ? AND capability_id = ? AND idempotency_key = ?`).get(input.principalId, input.capabilityId, input.idempotencyKey);
+		if (existing && (existing.request_digest !== input.requestDigest || existing.descriptor_digest !== input.descriptorDigest || existing.state !== "succeeded" || existing.recovery_mode !== "atomic")) throw new OperationConflictError("Idempotency key already identifies a different operation");
+		const operationId = existing?.operation_id ?? randomUUID();
+		const now = Date.now();
+		let result;
+		if (existing) result = JSON.parse(existing.result_json);
+		else {
+			result = withOperation(operationId, () => execute(operationId));
+			if (result && typeof result.then === "function") throw new Error("Atomic capability handlers must be synchronous");
+			const serialized = JSON.stringify(result);
+			if (serialized === void 0) throw new Error("Atomic capability result must be JSON");
+			db.prepare(`INSERT INTO capability_operations
+        (operation_id, principal_id, capability_id, idempotency_key, request_digest, descriptor_digest, result_json, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(operationId, input.principalId, input.capabilityId, input.idempotencyKey, input.requestDigest, input.descriptorDigest, serialized, now);
+			result = JSON.parse(serialized);
+		}
+		db.prepare(`INSERT INTO capability_invocations (invocation_id, operation_id, surface, replayed, created_at)
+      VALUES (?, ?, ?, ?, ?)`).run(randomUUID(), operationId, input.surface, existing ? 1 : 0, now);
+		return result;
+	});
+}
+//#endregion
+export { OperationConflictError, executeAtomicOperation };

package/dist/src/capabilities/runtime/dispatcher.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import type { ActorRef, CapabilityDescriptor, CapabilitySurface, GatewayScope } from '@xopcai/gateway-contract';
+export { CapabilityError } from './errors.js';
+/** Constructed by a trusted entry point, never parsed from tool or HTTP input. */
+export interface CapabilityContext {
+    principalId: string;
+    surface: CapabilitySurface;
+    scopes: readonly GatewayScope[];
+    allowedCapabilities?: readonly string[];
+    authorize: (id: string, input: unknown) => boolean | Promise<boolean>;
+    signal?: AbortSignal;
+    /** Synchronous lease/grant guard immediately before domain execution or receipt replay. */
+    assertCurrent?: () => void;
+    actor?: ActorRef;
+}
+export interface ReadCapability<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
+    id: string;
+    majorVersion: number;
+    description: string;
+    effect: 'read';
+    surfaces: readonly CapabilitySurface[];
+    scopes: readonly GatewayScope[];
+    input: I;
+    output: O;
+    execute: (input: z.output<I>, context: CapabilityContext) => z.input<O> | Promise<z.input<O>>;
+}
+export declare function defineReadCapability<I extends z.ZodType, O extends z.ZodType>(definition: ReadCapability<I, O>): ReadCapability<I, O>;
+export interface AtomicCapability<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> extends Omit<ReadCapability<I, O>, 'effect' | 'execute'> {
+    effect: 'local-write';
+    /** Bind receipts to trusted domain ownership that is not supplied in the public input. */
+    requestScope?: (context: CapabilityContext) => string;
+    /** Read-only asynchronous validation, skipped for committed receipt replay. Never perform effects here. */
+    prepare?: (input: z.output<I>, context: CapabilityContext) => void | Promise<void>;
+    execute: (input: z.output<I>, context: CapabilityContext & {
+        operationId: string;
+        idempotencyKey: string;
+    }) => z.input<O>;
+    afterCommit?: (result: z.output<O>, input: z.output<I>) => void | Promise<void>;
+}
+export declare function defineAtomicCapability<I extends z.ZodType, O extends z.ZodType>(definition: AtomicCapability<I, O>): AtomicCapability<I, O>;
+export interface ExternalCapability<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> extends Omit<ReadCapability<I, O>, 'effect' | 'execute'> {
+    effect: 'external-write';
+    recovery: 'manual' | 'provider-idempotent';
+    requestScope?: (context: CapabilityContext) => string;
+    /** Provider-idempotent implementations must send operationId as the provider key. */
+    execute: (input: z.output<I>, context: CapabilityContext & {
+        operationId: string;
+        idempotencyKey: string;
+    }) => Promise<z.input<O>>;
+}
+export declare function defineExternalCapability<I extends z.ZodType, O extends z.ZodType>(definition: ExternalCapability<I, O>): ExternalCapability<I, O>;
+type CapabilityDefinition<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> = ReadCapability<I, O> | AtomicCapability<I, O> | ExternalCapability<I, O>;
+/** Stable JSON encoding for contract digests; rejects non-JSON values. */
+export declare function canonicalCapabilityJson(value: unknown): string;
+export declare class CapabilityDispatcher {
+    private readonly entries;
+    register<I extends z.ZodType, O extends z.ZodType>(definition: CapabilityDefinition<I, O>): void;
+    private visible;
+    list(context: CapabilityContext): CapabilityDescriptor[];
+    describe(id: string, context: CapabilityContext): CapabilityDescriptor;
+    call(id: string, input: unknown, context: CapabilityContext, expected?: {
+        majorVersion: number;
+        descriptorDigest: string;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+    private validateResult;
+}

package/dist/src/capabilities/runtime/dispatcher.js

@@ -0,0 +1,170 @@
+import { SqliteCommitEffectError, init_transaction } from "../../storage/sqlite/transaction.js";
+import { CapabilityError } from "./errors.js";
+import { executeExternalOperation } from "./external-operations.js";
+import { OperationConflictError, executeAtomicOperation } from "./atomic-operations.js";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+//#region src/capabilities/runtime/dispatcher.ts
+init_transaction();
+function defineReadCapability(definition) {
+	return definition;
+}
+function defineAtomicCapability(definition) {
+	return definition;
+}
+function defineExternalCapability(definition) {
+	return definition;
+}
+/** Stable JSON encoding for contract digests; rejects non-JSON values. */
+function canonicalCapabilityJson(value) {
+	const parsed = z.json().parse(value);
+	const encode = (item) => {
+		if (Array.isArray(item)) return `[${item.map(encode).join(",")}]`;
+		if (item && typeof item === "object") return `{${Object.keys(item).sort().map((key) => `${JSON.stringify(key)}:${encode(item[key])}`).join(",")}}`;
+		return JSON.stringify(item);
+	};
+	return encode(parsed);
+}
+var CapabilityDispatcher = class {
+	entries = /* @__PURE__ */ new Map();
+	register(definition) {
+		if (!/^(xopc|extension)\.[a-zA-Z0-9_.-]+$/.test(definition.id) || !Number.isSafeInteger(definition.majorVersion) || definition.majorVersion < 1) throw new Error("Invalid capability identity");
+		if (this.entries.has(definition.id)) throw new Error(`Duplicate capability: ${definition.id}`);
+		const descriptor = {
+			id: definition.id,
+			majorVersion: definition.majorVersion,
+			description: definition.description,
+			effect: definition.effect,
+			surfaces: [...definition.surfaces],
+			inputSchema: z.toJSONSchema(definition.input, { io: "input" }),
+			outputSchema: z.toJSONSchema(definition.output, { io: "output" })
+		};
+		const descriptorDigest = createHash("sha256").update(canonicalCapabilityJson({
+			...descriptor,
+			scopes: definition.scopes,
+			...definition.effect === "external-write" ? { recovery: definition.recovery } : {}
+		})).digest("hex");
+		this.entries.set(definition.id, {
+			definition: {
+				...definition,
+				scopes: [...definition.scopes],
+				surfaces: [...definition.surfaces]
+			},
+			descriptor: {
+				...descriptor,
+				descriptorDigest
+			}
+		});
+	}
+	visible(definition, context) {
+		return Boolean(context.principalId) && definition.surfaces.includes(context.surface) && (!context.allowedCapabilities || context.allowedCapabilities.includes(definition.id)) && definition.scopes.every((scope) => context.scopes.includes("gateway.admin") || context.scopes.includes(scope));
+	}
+	list(context) {
+		return [...this.entries.values()].filter((entry) => this.visible(entry.definition, context)).map((entry) => structuredClone(entry.descriptor));
+	}
+	describe(id, context) {
+		const entry = this.entries.get(id);
+		if (!entry || !this.visible(entry.definition, context)) throw new CapabilityError("NOT_FOUND", "Capability not available");
+		return structuredClone(entry.descriptor);
+	}
+	async call(id, input, context, expected) {
+		const descriptor = this.describe(id, context);
+		if (expected && (expected.majorVersion !== descriptor.majorVersion || expected.descriptorDigest !== descriptor.descriptorDigest)) throw new CapabilityError("CONTRACT_CHANGED", "Capability contract changed; describe it again");
+		const { definition } = this.entries.get(id);
+		const parsed = definition.input.safeParse(input);
+		if (!parsed.success) throw new CapabilityError("INVALID_INPUT", parsed.error.message);
+		if (!await context.authorize(id, parsed.data)) throw new CapabilityError("FORBIDDEN", "Capability resource access denied");
+		context.assertCurrent?.();
+		if (context.signal?.aborted) throw new CapabilityError("CANCELLED", "Capability call cancelled");
+		if (definition.effect === "external-write") {
+			const key = expected?.idempotencyKey;
+			if (!key?.trim() || key.length > 200) throw new CapabilityError("INVALID_INPUT", "A stable idempotencyKey is required");
+			const normalizedInput = JSON.parse(JSON.stringify(parsed.data));
+			const identity = definition.requestScope ? {
+				input: normalizedInput,
+				scope: definition.requestScope(context)
+			} : normalizedInput;
+			return executeExternalOperation({
+				principalId: context.principalId,
+				capabilityId: id,
+				idempotencyKey: key,
+				requestDigest: createHash("sha256").update(canonicalCapabilityJson(identity)).digest("hex"),
+				descriptorDigest: descriptor.descriptorDigest,
+				surface: context.surface,
+				recovery: definition.recovery
+			}, (operationId) => definition.execute(parsed.data, {
+				...context,
+				operationId,
+				idempotencyKey: key
+			}), (result) => this.validateResult(definition, result));
+		}
+		if (definition.effect === "local-write") {
+			const key = expected?.idempotencyKey;
+			if (!key?.trim() || key.length > 200) throw new CapabilityError("INVALID_INPUT", "A stable idempotencyKey is required");
+			try {
+				const normalizedInput = JSON.parse(JSON.stringify(parsed.data));
+				const scope = definition.requestScope?.(context);
+				const requestIdentity = definition.requestScope ? {
+					input: normalizedInput,
+					scope
+				} : normalizedInput;
+				const preparationRequired = Symbol("preparationRequired");
+				let prepared = !definition.prepare;
+				const execute = () => {
+					context.assertCurrent?.();
+					return executeAtomicOperation({
+						principalId: context.principalId,
+						capabilityId: id,
+						idempotencyKey: key,
+						requestDigest: createHash("sha256").update(canonicalCapabilityJson(requestIdentity)).digest("hex"),
+						descriptorDigest: descriptor.descriptorDigest,
+						surface: context.surface
+					}, (operationId) => {
+						if (!prepared) throw preparationRequired;
+						const output = definition.execute(parsed.data, {
+							...context,
+							operationId,
+							idempotencyKey: key
+						});
+						if (output && typeof output.then === "function") throw new Error("Atomic capability handlers must be synchronous");
+						return this.validateResult(definition, output);
+					});
+				};
+				let result;
+				try {
+					result = execute();
+				} catch (error) {
+					if (error !== preparationRequired) throw error;
+					await definition.prepare(parsed.data, context);
+					if (!await context.authorize(id, parsed.data)) throw new CapabilityError("FORBIDDEN", "Capability resource access denied");
+					if (context.signal?.aborted) throw new CapabilityError("CANCELLED", "Capability call cancelled");
+					if (definition.requestScope?.(context) !== scope) throw new CapabilityError("REVISION_CONFLICT", "Capability ownership changed during preparation");
+					prepared = true;
+					result = execute();
+				}
+				await definition.afterCommit?.(result, parsed.data);
+				return result;
+			} catch (error) {
+				if (error instanceof OperationConflictError) throw new CapabilityError("REVISION_CONFLICT", error.message);
+				if (error instanceof SqliteCommitEffectError) {
+					const pending = new CapabilityError("UNAVAILABLE", "Operation committed; post-commit work is pending. Retry the same idempotencyKey.");
+					pending.cause = error;
+					throw pending;
+				}
+				throw error;
+			}
+		}
+		return this.validateResult(definition, await definition.execute(parsed.data, context));
+	}
+	validateResult(definition, result) {
+		const validated = definition.output.safeParse(result);
+		if (!validated.success) {
+			const error = new CapabilityError("INTERNAL", "Capability returned an invalid result");
+			error.cause = validated.error;
+			throw error;
+		}
+		return validated.data;
+	}
+};
+//#endregion
+export { CapabilityDispatcher, CapabilityError, canonicalCapabilityJson, defineAtomicCapability, defineExternalCapability, defineReadCapability };

package/dist/src/capabilities/runtime/errors.d.ts

@@ -0,0 +1,6 @@
+import type { CapabilityErrorCode } from '@xopcai/gateway-contract';
+export declare class CapabilityError extends Error {
+    readonly code: CapabilityErrorCode;
+    readonly operationId?: string;
+    constructor(code: CapabilityErrorCode, message: string, operationId?: string);
+}

package/dist/src/capabilities/runtime/errors.js

@@ -0,0 +1,11 @@
+//#region src/capabilities/runtime/errors.ts
+var CapabilityError = class extends Error {
+	constructor(code, message, operationId) {
+		super(message);
+		this.code = code;
+		this.operationId = operationId;
+		this.name = "CapabilityError";
+	}
+};
+//#endregion
+export { CapabilityError };

package/dist/src/capabilities/runtime/external-operations.d.ts

@@ -0,0 +1,16 @@
+/** Use only when the provider can prove that no effect was applied. Network errors are not proof. */
+export declare class ExternalEffectNotAppliedError extends Error {
+}
+export interface ExternalOperationInput {
+    principalId: string;
+    capabilityId: string;
+    idempotencyKey: string;
+    requestDigest: string;
+    descriptorDigest: string;
+    surface: string;
+    recovery: 'manual' | 'provider-idempotent';
+    leaseMs?: number;
+    now?: () => number;
+}
+/** The callback must use operationId as the provider key when declaring provider-idempotent recovery. */
+export declare function executeExternalOperation<T>(input: ExternalOperationInput, execute: (operationId: string) => Promise<T>, validate?: (result: T) => T): Promise<T>;

package/dist/src/capabilities/runtime/external-operations.js

@@ -0,0 +1,92 @@
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { CapabilityError } from "./errors.js";
+import { randomUUID } from "node:crypto";
+//#region src/capabilities/runtime/external-operations.ts
+init_transaction();
+/** Use only when the provider can prove that no effect was applied. Network errors are not proof. */
+var ExternalEffectNotAppliedError = class extends Error {};
+/** The callback must use operationId as the provider key when declaring provider-idempotent recovery. */
+async function executeExternalOperation(input, execute, validate) {
+	if (!input.principalId || !input.idempotencyKey.trim() || input.idempotencyKey.length > 200) throw new CapabilityError("INVALID_INPUT", "External operation identity is required");
+	if (input.leaseMs !== void 0 && !Number.isFinite(input.leaseMs)) throw new CapabilityError("INVALID_INPUT", "Lease duration must be finite");
+	const now = input.now ?? Date.now;
+	const invocationId = randomUUID();
+	const claim = runSqliteWriteTransaction((db) => {
+		const row = db.prepare(`SELECT operation_id, request_digest, descriptor_digest, state, result_json, generation, lease_expires_at, recovery_mode
+      FROM capability_operations WHERE principal_id = ? AND capability_id = ? AND idempotency_key = ?`).get(input.principalId, input.capabilityId, input.idempotencyKey);
+		if (row && (row.request_digest !== input.requestDigest || row.descriptor_digest !== input.descriptorDigest || row.recovery_mode !== input.recovery)) throw new CapabilityError("REVISION_CONFLICT", "Operation parameters or contract changed", row.operation_id);
+		if (row?.state === "succeeded") {
+			db.prepare(`INSERT INTO capability_invocations
+        (invocation_id, operation_id, surface, replayed, created_at, finished_at) VALUES (?, ?, ?, 1, ?, ?)`).run(invocationId, row.operation_id, input.surface, now(), now());
+			return {
+				replay: true,
+				result: JSON.parse(row.result_json),
+				operationId: row.operation_id,
+				generation: row.generation
+			};
+		}
+		if (row?.state === "failed") throw new CapabilityError("UNAVAILABLE", "Previous attempt was rejected without applying an effect; use a new intent to retry", row.operation_id);
+		if (row?.state === "running" && (row.lease_expires_at ?? 0) > now()) throw new CapabilityError("IN_PROGRESS", "The same external operation is still running", row.operation_id);
+		if (row && input.recovery === "manual") return {
+			unknown: true,
+			operationId: row.operation_id,
+			generation: row.generation
+		};
+		const operationId = row?.operation_id ?? randomUUID();
+		const generation = (row?.generation ?? 0) + 1;
+		const expires = now() + Math.max(1e3, Math.min(input.leaseMs ?? 12e4, 36e5));
+		if (row) {
+			db.prepare(`UPDATE capability_operations SET state = 'running', generation = ?, lease_expires_at = ?
+        WHERE operation_id = ?`).run(generation, expires, operationId);
+			db.prepare(`UPDATE capability_invocations SET state = 'unknown', finished_at = ?
+        WHERE operation_id = ? AND state = 'running'`).run(now(), operationId);
+		} else db.prepare(`INSERT INTO capability_operations
+        (operation_id, principal_id, capability_id, idempotency_key, request_digest, descriptor_digest,
+          result_json, created_at, state, generation, lease_expires_at, recovery_mode) VALUES (?, ?, ?, ?, ?, ?, 'null', ?, 'running', ?, ?, ?)`).run(operationId, input.principalId, input.capabilityId, input.idempotencyKey, input.requestDigest, input.descriptorDigest, now(), generation, expires, input.recovery);
+		db.prepare(`INSERT INTO capability_invocations
+      (invocation_id, operation_id, surface, replayed, created_at, state) VALUES (?, ?, ?, 0, ?, 'running')`).run(invocationId, operationId, input.surface, now());
+		return {
+			operationId,
+			generation
+		};
+	});
+	if ("replay" in claim) return claim.result;
+	if ("unknown" in claim) {
+		runSqliteWriteTransaction((db) => {
+			db.prepare(`UPDATE capability_operations SET state = 'unknown'
+        WHERE operation_id = ? AND generation = ? AND state = 'running'`).run(claim.operationId, claim.generation);
+			db.prepare(`UPDATE capability_invocations SET state = 'unknown', finished_at = ?
+        WHERE operation_id = ? AND state = 'running'`).run(now(), claim.operationId);
+		});
+		throw new CapabilityError("OUTCOME_UNKNOWN", "External outcome is unknown; verify it before issuing another write", claim.operationId);
+	}
+	try {
+		const raw = await execute(claim.operationId);
+		const evidence = JSON.stringify(raw);
+		if (evidence !== void 0) getSqliteDatabase().prepare(`UPDATE capability_operations SET evidence_json = ?
+      WHERE operation_id = ? AND generation = ?`).run(evidence, claim.operationId, claim.generation);
+		const result = validate ? validate(raw) : raw;
+		const json = JSON.stringify(result);
+		if (json === void 0) throw new Error("External result must be JSON");
+		if (!runSqliteWriteTransaction((db) => {
+			const changed = db.prepare(`UPDATE capability_operations SET state = 'succeeded', result_json = ?, lease_expires_at = NULL
+        WHERE operation_id = ? AND generation = ? AND state IN ('running', 'unknown')`).run(json, claim.operationId, claim.generation).changes;
+			if (changed) db.prepare(`UPDATE capability_invocations SET state = 'succeeded', finished_at = ? WHERE invocation_id = ?`).run(now(), invocationId);
+			return changed;
+		})) throw new CapabilityError("OUTCOME_UNKNOWN", "A newer recovery attempt owns this operation", claim.operationId);
+		return JSON.parse(json);
+	} catch (error) {
+		const state = error instanceof ExternalEffectNotAppliedError ? "failed" : "unknown";
+		runSqliteWriteTransaction((db) => {
+			db.prepare(`UPDATE capability_operations SET state = ?, lease_expires_at = NULL
+        WHERE operation_id = ? AND generation = ? AND state = 'running'`).run(state, claim.operationId, claim.generation);
+			db.prepare(`UPDATE capability_invocations SET state = ?, finished_at = ? WHERE invocation_id = ? AND state = 'running'`).run(state, now(), invocationId);
+		});
+		const rejection = error instanceof ExternalEffectNotAppliedError && error.cause instanceof CapabilityError ? error.cause : void 0;
+		const failure = new CapabilityError(rejection?.code ?? (state === "failed" ? "UNAVAILABLE" : "OUTCOME_UNKNOWN"), rejection?.message ?? (state === "failed" ? "Provider confirmed no effect was applied" : "External outcome is unknown; do not resend with a new key without verification"), claim.operationId);
+		failure.cause = error;
+		throw failure;
+	}
+}
+//#endregion
+export { ExternalEffectNotAppliedError, executeExternalOperation };

package/dist/src/capabilities/runtime/product.d.ts

@@ -0,0 +1,12 @@
+import type { NotesService } from '../../notes/service.js';
+import type { LocalAppService } from '../../local-apps/service.js';
+import { type ProjectWriteCapabilityDeps } from '../../projects/capabilities/write.js';
+import type { AutomationService } from '../../automations/service/automation-service.js';
+import { type TaskWriteCapabilityDeps } from '../../tasks/capabilities/write.js';
+import { CapabilityDispatcher, type CapabilityContext } from './dispatcher.js';
+import type { SceneAccess } from '../../scenes/httpServices.js';
+export declare function createProductDispatcher(getNotes?: () => NotesService | undefined, taskWrites?: TaskWriteCapabilityDeps & ProjectWriteCapabilityDeps & {
+    getAutomations?: () => AutomationService | undefined;
+    getLocalApps?: () => LocalAppService | undefined;
+    getSceneAccess?: (context: CapabilityContext) => SceneAccess | undefined;
+}): CapabilityDispatcher;