@xopcai/xopc 0.0.312 → 0.0.314

package/dist/src/gateway/service/task-conversation-query-service.js

@@ -1,5 +1,8 @@
 import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 //#region src/gateway/service/task-conversation-query-service.ts
+function displayMessageCount(items) {
+	return items.reduce((count, item) => item.displayIndex === void 0 ? count : Math.max(count, item.displayIndex + 1), 0);
+}
 var TaskConversationQueryService = class {
 	constructor(sessions, conversations = new TaskConversationRepository()) {
 		this.sessions = sessions;
@@ -53,8 +56,8 @@ var TaskConversationQueryService = class {
 		let displayOffset = 0;
 		let turnOffset = 0;
 		for (const [index, link] of links.entries()) {
-			const [items, page] = await Promise.all([this.sessions.getTimeline(link.conversationId), this.sessions.getMessagePage(link.conversationId, { limit: 1 })]);
-			if (!items || !page) return null;
+			const items = await this.sessions.getTimeline(link.conversationId);
+			if (!items) return null;
 			if (index > 0) output.push({
 				id: `assignment:${link.id}`,
 				kind: "branch",
@@ -70,12 +73,38 @@ var TaskConversationQueryService = class {
 				turn: item.turn + turnOffset,
 				...item.displayIndex === void 0 ? {} : { displayIndex: item.displayIndex + displayOffset }
 			})));
-			displayOffset += page.pagination.total;
+			displayOffset += displayMessageCount(items);
 			const highestTurn = items.reduce((max, item) => Math.max(max, item.turn), -1);
 			turnOffset += highestTurn + 1;
 		}
 		return output;
 	}
+	async findMessages(taskId, query, limit = 1e3) {
+		const links = this.#executionSessions(taskId);
+		if (links.length === 0) return null;
+		const matches = [];
+		let displayOffset = 0;
+		let total = 0;
+		for (const link of links) {
+			const [result, items] = await Promise.all([this.sessions.findMessages(link.conversationId, query, limit), this.sessions.getTimeline(link.conversationId)]);
+			if (!result || !items) return null;
+			total += result.total;
+			for (const match of result.matches) {
+				if (matches.length >= limit) break;
+				matches.push({
+					...match,
+					displayIndex: match.displayIndex + displayOffset
+				});
+			}
+			displayOffset += displayMessageCount(items);
+		}
+		return {
+			query: query.trim(),
+			total,
+			truncated: total > matches.length,
+			matches
+		};
+	}
 	#executionSessions(taskId) {
 		return this.conversations.listSessions(taskId).filter((link) => link.role === "execution").sort((a, b) => a.assignmentEpoch - b.assignmentEpoch || a.startedAt - b.startedAt);
 	}

package/dist/src/gateway/service.d.ts

@@ -25,6 +25,7 @@ import type { GatewayServiceConfig } from './service/types.js';
 import { type GatewayReadinessSnapshot } from './startup-readiness.js';
 import { type ConnectorLearningCoordinator } from '../connectors/learning-coordinator.js';
 import type { SceneAccess } from '../scenes/httpServices.js';
+import type { GatewayPrincipal } from './security/gateway-principal.js';
 import { type ProductLanguage } from '../voice/language-profile.js';
 import { EndpointToolRuntime } from '../endpoint-tools/index.js';
 export type { GatewayChannelStartupPhase1Metrics, GatewayChannelStartupPhase2Metrics, GatewayServiceConfig, } from './service/types.js';
@@ -137,6 +138,8 @@ export declare class GatewayService {
         ok: false;
         code: "BAD_REQUEST" | "QUEUE_FULL" | "CONTEXT_UNAVAILABLE" | "SESSION_CHANGED";
     }>;
+    private appContextDispatcher;
+    prepareSessionAppContext(input: unknown, principal: GatewayPrincipal, conversationId: string, clientMessageId: string): Promise<import("../agent/source-context/types.js").AgentSourceContext>;
     replaceLatestSessionTurn(...args: Parameters<GatewayAgentRunner['replaceLatestSessionTurn']>): Promise<{
         ok: true;
         effectiveDelivery: "next";

package/dist/src/gateway/service.js

@@ -8,6 +8,8 @@ import { init_logger } from "../utils/logger.js";
 import { closeXopcDatabase, openXopcDatabase } from "../storage/sqlite/connection.js";
 import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transaction.js";
 import { findSessionInput, init_session_input_repository, insertSessionInput } from "../storage/sqlite/session-input-repository.js";
+import { TaskRepository } from "../tasks/task-repository.js";
+import { TaskRunRepository, init_task_run_repository } from "../tasks/task-run-repository.js";
 import { init_changes, notifyUserContextChange } from "../user-context/changes.js";
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_session_repository, patchSessionMetadata } from "../storage/sqlite/session-repository.js";
@@ -26,22 +28,26 @@ import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, init_cha
 import { loadConfig, saveConfig } from "../config/loader.js";
 import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_providers, providers_exports } from "../providers/index.js";
-import { TaskRepository } from "../tasks/task-repository.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { getEmbeddedExecutionSession } from "../agent/embedded/execution-context.js";
 import { disposeAllSessionMcpRuntimes } from "../agent/mcp/bundle-mcp-runtime.js";
+import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
+import { onAutomationProductEvent, publishAutomationProductEvent } from "../automations/product-events.js";
 import { ProjectService } from "../projects/project-service.js";
 import { resolveProjectAgentId } from "../projects/project-agent.js";
 import "../projects/index.js";
 import { resolveEffectiveGatewayPort } from "./host.js";
 import { onSessionTranscriptUpdate } from "../session/transcript-events.js";
+import { buildNoteAgentContext } from "../notes/agent-context.js";
+import { NotesStore } from "../notes/store.js";
+import { NotesService } from "../notes/service.js";
+import { LocalAppService } from "../local-apps/service.js";
+import { TaskApplicationService } from "../tasks/task-application-service.js";
 import { AutomationService } from "../automations/service/automation-service.js";
-import { onAutomationProductEvent, publishAutomationProductEvent } from "../automations/product-events.js";
+import { TaskSignalService } from "../tasks/task-signal-service.js";
+import { createProductDispatcher } from "../capabilities/runtime/product.js";
 import "../automations/index.js";
-import { TaskApplicationService } from "../tasks/task-application-service.js";
-import { TaskOutboxDispatcher } from "../tasks/task-outbox-dispatcher.js";
 import { TaskRunDispatcher } from "../tasks/task-run-dispatcher.js";
-import { TaskSignalService } from "../tasks/task-signal-service.js";
 import "../tasks/index.js";
 import "../agent/mcp/bundle-mcp-tools.js";
 import { SessionIndex } from "../session/manager.js";
@@ -53,9 +59,6 @@ import "../infra/bus/index.js";
 import { collectMediaUrisFromMessages, deleteMediaUris } from "../media/session-references.js";
 import { AgentService } from "../agent/service.js";
 import { ensureStarterAgentsInitialized } from "../agent/starter-agents.js";
-import { setPairingBroadcastSink } from "../channels/pairing/pairing-events.js";
-import { registerClarificationChannelRuntime } from "./clarify-runtime.js";
-import { ChannelManager } from "../channels/manager.js";
 import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import "../config/index.js";
 import { ManagedComposioEventPoller } from "../connectors/composio-managed-events.js";
@@ -74,6 +77,7 @@ import { EndpointToolRuntime } from "../endpoint-tools/runtime.js";
 import "../endpoint-tools/index.js";
 import { assertGatewayAuthConfigured, extractToken, resolveGatewayAuth, validateToken } from "./auth.js";
 import { prepareAutomationAgentSession } from "./automation-agent-session.js";
+import { registerClarificationChannelRuntime } from "./clarify-runtime.js";
 import { stopTailscaleExposure } from "./tailscale-lifecycle.js";
 import { createBackgroundTask } from "../infra/background-task.js";
 import { buildTaskAgentContext } from "../agent/source-context/task-context.js";
@@ -81,9 +85,8 @@ import { WorkDiscoveryService } from "../work-discovery/service.js";
 import { buildVoiceMemoryContext } from "../voice/realtime/memory-context.js";
 import { buildVoicePersonaContext } from "../voice/realtime/persona-context.js";
 import { voiceMemoryBudget, voicePersonaBudget } from "../voice/realtime/conversation-context.js";
-import { NotesStore } from "../notes/store.js";
-import { buildNoteAgentContext } from "../notes/agent-context.js";
-import { NotesService } from "../notes/service.js";
+import { setPairingBroadcastSink } from "../channels/pairing/pairing-events.js";
+import { ChannelManager } from "../channels/manager.js";
 import "../notes/index.js";
 import { buildWorkflowChildTools } from "../agent/workflow/workflow-child-tools.js";
 import { WorkflowRunService } from "../workflows/service/workflow-run-service.js";
@@ -104,7 +107,6 @@ import { getXopcCloudCatalogCoordinator } from "../providers/xopc-cloud-catalog-
 import { ModelCatalogSyncService } from "../providers/model-catalog-sync-service.js";
 import { runBootstrapMigrationsSync } from "../migrations/runner.js";
 import { NotificationService } from "../notifications/service.js";
-import { LocalAppService } from "../local-apps/service.js";
 import "../local-apps/index.js";
 import { createRuntimeBrowserAutomationService } from "../browser/automations/runtime-service.js";
 import "../browser/automations/index.js";
@@ -123,6 +125,7 @@ import { reconcileMemoryMaintenanceAutomations } from "./memory-maintenance-auto
 import { GatewayReadiness } from "./startup-readiness.js";
 import { createGatewayStartupTrace } from "./startup-trace.js";
 import { GatewaySceneHost } from "./scenes/host.js";
+import { checkAppContextAccess, prepareAppContext } from "./service/app-context-access.js";
 import { applyAutomaticVoiceLanguage, inferProductLanguageFromEnvironment, initializeVoiceDefaults } from "../voice/language-profile.js";
 import crypto from "node:crypto";
 //#region src/gateway/service.ts
@@ -140,6 +143,7 @@ init_paths();
 init_package_version();
 init_resolve_route();
 init_session_key();
+init_task_run_repository();
 init_transaction();
 const log = createLogger("Gateway:Service");
 var GatewayService = class {
@@ -457,7 +461,10 @@ var GatewayService = class {
 			emit: (type, payload) => this.emit(type, payload)
 		});
 		this.agentRunner = new GatewayAgentRunner({
-			validateConnectionResume: (input) => this.connectionRecovery.preflight(input),
+			validateConnectionResume: async (input) => {
+				for (const source of input.contextSnapshots ?? []) if (source.kind === "app_context") await checkAppContextAccess(source, this.appContextDispatcher(), this.auth);
+				return this.connectionRecovery.preflight(input);
+			},
 			bus: this.bus,
 			sessionIndex: this.sessionIndex,
 			getAgentService: () => this.ensureAgentService(),
@@ -581,6 +588,7 @@ var GatewayService = class {
 			emitBrowserEvent: (type, payload) => this.emit(type, payload),
 			getNotesService: () => this.notesService,
 			getProjectService: () => this.projects,
+			getWorkDiscovery: () => this._workDiscovery ?? void 0,
 			getLocalAppService: () => this.localApps,
 			dispatchTaskEvents: () => this.dispatchTaskEvents(),
 			dispatchTaskRuns: () => this.dispatchTaskRuns(),
@@ -661,6 +669,13 @@ var GatewayService = class {
 				})).conversationId;
 			},
 			runAgent: async (runId, conversationId, message) => {
+				const taskRun = new TaskRunRepository().require(runId);
+				if (getSqliteDatabase().prepare("SELECT 1 FROM scene_task_bindings WHERE task_id = ?").get(taskRun.taskId)) {
+					if (!this.sceneHost?.http.followUps) throw new Error("Task follow-up runtime is disabled");
+					this.ensureAgentService();
+					await this.sceneHost.http.followUps.executeTask(runId, conversationId);
+					return;
+				}
 				const clientMessageId = `task:${runId}`;
 				const session = await this.sessionIndex.getSessionMetadata(conversationId);
 				if (!session) throw new Error("Task session is unavailable");
@@ -686,11 +701,17 @@ var GatewayService = class {
 		return this.taskRunDispatcher;
 	}
 	createNotificationService() {
-		if (!this.notificationService) this.notificationService = new NotificationService({ publish: (type, payload) => this.realtime.broker.publish("gateway", type, payload) });
+		if (!this.notificationService) this.notificationService = new NotificationService({
+			publish: (type, payload) => this.realtime.broker.publish("gateway", type, payload),
+			allowsNotification: (notification) => notification.target.kind !== "task" || this.sceneHost?.http.followUps?.allowsTaskNotification(notification.target.taskId) !== false
+		});
 		return this.notificationService;
 	}
 	taskRunDispatch = createBackgroundTask(async () => {
 		new TaskSignalService().tick();
+		this.notesService.flushCommittedEffects();
+		this.projects.flushCommittedEffects();
+		this._workDiscovery?.dispatchProjectUnderstanding();
 		this.dispatchTaskEvents();
 		this.createTaskRunDispatcher().dispatch();
 		await this.createWorkflowRunService().dispatchTaskRuns();
@@ -770,7 +791,10 @@ var GatewayService = class {
 		};
 	}
 	dispatchTaskEvents() {
-		new TaskOutboxDispatcher(publishAutomationProductEvent).drain();
+		new DomainOutboxDispatcher((event) => {
+			if (event.source === "local_apps") this.emit(event.type, event.payload);
+			else publishAutomationProductEvent(event);
+		}).drain();
 	}
 	runAgent(...args) {
 		return this.agentRunner.runAgent(...args);
@@ -785,6 +809,17 @@ var GatewayService = class {
 	submitSessionInput(...args) {
 		return this.agentRunner.submitSessionInput(...args);
 	}
+	appContextDispatcher() {
+		return createProductDispatcher(() => this.notesService, {
+			getProjects: () => this.projects,
+			getLocalApps: () => this.localApps,
+			getSceneAccess: () => this.sceneAccess
+		});
+	}
+	prepareSessionAppContext(input, principal, conversationId, clientMessageId) {
+		const previous = findSessionInput(conversationId, clientMessageId)?.contextSnapshots?.find((source) => source.kind === "app_context");
+		return prepareAppContext(input, principal, this.auth, this.appContextDispatcher(), previous);
+	}
 	replaceLatestSessionTurn(...args) {
 		return this.agentRunner.replaceLatestSessionTurn(...args);
 	}
@@ -949,6 +984,7 @@ var GatewayService = class {
 		});
 		log.debug("Starting gateway service...");
 		openXopcDatabase();
+		await this.localApps.recoverPendingReleases();
 		const { recoverCapabilityImports } = await import("../imports/runtime.js");
 		await recoverCapabilityImports();
 		this.createNotificationService().start();
@@ -1628,6 +1664,24 @@ var GatewayService = class {
 		this.stopAutomationProductEventBridge?.();
 		this.stopSessionTranscriptAutomationEvents?.();
 		this.stopAutomationProductEventBridge = onAutomationProductEvent((event) => {
+			if (event.type === "project.deleted" && typeof event.payload.projectId === "string") {
+				const runIds = event.payload.deletedUnderstandingRunIds;
+				if (Array.isArray(runIds) && runIds.every((id) => typeof id === "string")) this._workDiscovery?.abortDeletedProjectRuns(event.payload.projectId, runIds);
+			}
+			if (event.type === "note.created" || event.type === "note.updated" || event.type === "note.deleted" || event.type === "task.changed.v2" || event.type === "task.deleted.v1" || event.type === "project.changed" || event.type === "project.created" || event.type === "project.deleted" || event.type === "scene.changed" || event.type === "scene.created" || event.type === "scene.deleted") {
+				const note = event.type.startsWith("note.");
+				const project = event.type.startsWith("project.");
+				const scene = event.type.startsWith("scene.");
+				const payload = event.payload;
+				if (typeof payload.sourceEventId === "string") this.realtime.broker.publish(note ? "resources:notes" : project ? "resources:projects" : scene ? "resources:scenes" : "resources:tasks", "resource.changed", {
+					eventId: payload.sourceEventId,
+					kind: note ? "note" : project ? "project" : scene ? "scene" : "task",
+					id: note ? payload.noteId : project ? payload.projectId : scene ? payload.sceneId : payload.taskId,
+					revision: note || scene ? payload.revision : payload.version,
+					operation: event.type === "task.deleted.v1" || event.type.endsWith(".deleted") ? "deleted" : event.type.endsWith(".created") ? "created" : "updated",
+					...typeof payload.operationId === "string" ? { operationId: payload.operationId } : {}
+				});
+			}
 			if (event.type.startsWith("task.")) this.emit(event.type, event.payload);
 			this.automationService.triggerEvent(event).catch((err) => {
 				const em = err instanceof Error ? err.message : String(err);

package/dist/src/gateway/session-context-summary.js

@@ -2,10 +2,10 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transaction.js";
 import { hasGatewayScope } from "./security/gateway-scopes.js";
+import { TaskRepository, init_task_repository } from "../tasks/task-repository.js";
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_session_repository } from "../storage/sqlite/session-repository.js";
 import { getSessionConfig } from "../storage/sqlite/config-repository.js";
-import { TaskRepository } from "../tasks/task-repository.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { getExecutionEnvironmentForSession } from "../execution-environments/subject.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
@@ -16,6 +16,7 @@ import { realpath, stat } from "node:fs/promises";
 //#region src/gateway/session-context-summary.ts
 init_session_repository();
 init_transaction();
+init_task_repository();
 init_logger();
 const log = createLogger("SessionContextSummary");
 const SOURCE_LIMIT = 20;

package/dist/src/{tasks/task-outbox-dispatcher.d.ts → infra/domain-outbox-dispatcher.d.ts}

@@ -1,6 +1,6 @@
 import type { AutomationEvent } from '../automations/domain/types.js';
-export declare class TaskOutboxDispatcher {
+export declare class DomainOutboxDispatcher {
     private readonly publish;
     constructor(publish: (event: AutomationEvent) => void);
-    drain(limit?: number): number;
+    drain(limit?: number, subjectKind?: string): number;
 }

package/dist/src/{tasks/task-outbox-dispatcher.js → infra/domain-outbox-dispatcher.js}

@@ -1,23 +1,24 @@
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
-//#region src/tasks/task-outbox-dispatcher.ts
+//#region src/infra/domain-outbox-dispatcher.ts
 init_transaction();
-var TaskOutboxDispatcher = class {
+var DomainOutboxDispatcher = class {
 	constructor(publish) {
 		this.publish = publish;
 	}
-	drain(limit = 100) {
-		const rows = getSqliteDatabase().prepare(`SELECT event_id, event_type, payload_json, created_at
-       FROM domain_outbox WHERE published_at IS NULL
-       ORDER BY created_at, event_id LIMIT ?`).all(Math.max(1, Math.min(500, Math.floor(limit))));
+	drain(limit = 100, subjectKind) {
+		const rows = getSqliteDatabase().prepare(`SELECT event_id, event_type, payload_json, created_at, subject_kind, operation_id
+       FROM domain_outbox WHERE published_at IS NULL AND (? IS NULL OR subject_kind = ?)
+       ORDER BY created_at, event_id LIMIT ?`).all(subjectKind ?? null, subjectKind ?? null, Math.max(1, Math.min(500, Math.floor(limit))));
 		let published = 0;
 		for (const row of rows) try {
 			const payload = JSON.parse(row.payload_json);
 			this.publish({
 				type: row.event_type,
-				source: "tasks",
+				source: row.subject_kind === "note" ? "notes" : row.subject_kind === "project" ? "projects" : row.subject_kind === "scene" ? "scenes" : row.subject_kind === "local_app" ? "local_apps" : "tasks",
 				payload: {
 					...payload,
-					sourceEventId: row.event_id
+					sourceEventId: row.event_id,
+					...row.operation_id ? { operationId: row.operation_id } : {}
 				},
 				occurredAtMs: row.created_at
 			});
@@ -33,4 +34,4 @@ var TaskOutboxDispatcher = class {
 	}
 };
 //#endregion
-export { TaskOutboxDispatcher };
+export { DomainOutboxDispatcher };

package/dist/src/infra/operation-context.d.ts

@@ -0,0 +1,2 @@
+export declare function currentOperationId(): string | undefined;
+export declare function withOperation<T>(operationId: string, run: () => T): T;

package/dist/src/infra/operation-context.js

@@ -0,0 +1,16 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/infra/operation-context.ts
+function currentOperationId() {
+	return operations.getStore();
+}
+function withOperation(operationId, run) {
+	return operations.run(operationId, run);
+}
+var operations;
+var init_operation_context = __esmMin((() => {
+	operations = new AsyncLocalStorage();
+}));
+//#endregion
+init_operation_context();
+export { currentOperationId, init_operation_context, withOperation };

package/dist/src/local-apps/capabilities/contracts.d.ts

@@ -0,0 +1,2 @@
+/** Validate release bindings against the same production definitions without executing a domain service. */
+export declare function validateLocalAppCapabilityContracts(value: unknown): void;

package/dist/src/local-apps/capabilities/contracts.js

@@ -0,0 +1,32 @@
+import { ExtensionCapabilityBindingsSchema } from "../../../packages/gateway-contract/src/extension-capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityDispatcher } from "../../capabilities/runtime/dispatcher.js";
+import { registerNoteReadCapabilities } from "../../notes/capabilities/read.js";
+import { registerNoteWriteCapabilities } from "../../notes/capabilities/write.js";
+import { registerTaskReadCapabilities } from "../../tasks/capabilities/read.js";
+//#region src/local-apps/capabilities/contracts.ts
+init_src();
+/** Validate release bindings against the same production definitions without executing a domain service. */
+function validateLocalAppCapabilityContracts(value) {
+	const bindings = ExtensionCapabilityBindingsSchema.parse(value ?? []);
+	if (!bindings.length) return;
+	const dispatcher = new CapabilityDispatcher();
+	const unavailable = () => {
+		throw new Error("Contract validation must not execute a domain service");
+	};
+	registerNoteReadCapabilities(dispatcher, unavailable);
+	registerNoteWriteCapabilities(dispatcher, { getNotes: unavailable });
+	registerTaskReadCapabilities(dispatcher);
+	const context = {
+		principalId: "release-validator",
+		surface: "extension",
+		scopes: ["gateway.admin"],
+		authorize: () => false
+	};
+	for (const binding of bindings) {
+		const descriptor = dispatcher.describe(binding.id, context);
+		if (descriptor.majorVersion !== binding.majorVersion || descriptor.descriptorDigest !== binding.descriptorDigest) throw new Error(`Capability contract changed: ${binding.id}; update the binding and rerun acceptance`);
+	}
+}
+//#endregion
+export { validateLocalAppCapabilityContracts };

package/dist/src/local-apps/capabilities/read.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import type { LocalAppService } from '../service.js';
+export declare function registerLocalAppReadCapabilities(dispatcher: CapabilityDispatcher, service: LocalAppService): void;

package/dist/src/local-apps/capabilities/read.js

@@ -0,0 +1,48 @@
+import { ProductReadContracts } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineReadCapability } from "../../capabilities/runtime/dispatcher.js";
+//#region src/local-apps/capabilities/read.ts
+init_src();
+function registerLocalAppReadCapabilities(dispatcher, service) {
+	const policy = {
+		majorVersion: 1,
+		effect: "read",
+		surfaces: ["http", "agent"],
+		scopes: ["gateway.admin"]
+	};
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.local_apps.validate",
+		description: "Inspect local application files and validation issues without modifying the package or acceptance records.",
+		...ProductReadContracts["xopc.local_apps.validate"],
+		execute({ id }) {
+			if (!service.get(id)) throw new CapabilityError("NOT_FOUND", "Local app not found");
+			return { validation: service.validate(id) };
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.local_apps.list",
+		description: "List managed local applications.",
+		...ProductReadContracts["xopc.local_apps.list"],
+		execute: () => ({ apps: service.list().map((app) => ({ ...app })) })
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.local_apps.get",
+		description: "Read a local application, its preview and release history.",
+		...ProductReadContracts["xopc.local_apps.get"],
+		execute({ id }) {
+			const app = service.get(id);
+			if (!app) throw new CapabilityError("NOT_FOUND", "Local app not found");
+			return { app: {
+				...app,
+				releases: app.releases.map((release) => ({ ...release })),
+				acceptanceRuns: app.acceptanceRuns.map((run) => ({ ...run }))
+			} };
+		}
+	}));
+}
+//#endregion
+export { registerLocalAppReadCapabilities };

package/dist/src/local-apps/capabilities/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { CapabilityCall } from '@xopcai/gateway-contract';
+import { type CapabilityContext, type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import type { LocalAppService } from '../service.js';
+/** Shared UI/Agent execution boundary; callers cannot manufacture grants or release identity. */
+export declare function localAppCapabilities(apps: Pick<LocalAppService, 'getCapabilityAccess'>, dispatcher: CapabilityDispatcher, extensionId: string, manifestDigest: string, caller: CapabilityContext): {
+    list(): {
+        releaseId: string;
+        manifestDigest: string;
+        capabilities: import("@xopcai/gateway-contract").CapabilityDescriptor[];
+    };
+    call(id: string, call: CapabilityCall): Promise<{
+        status: "succeeded";
+        releaseId: string;
+        data: unknown;
+    }>;
+};

package/dist/src/local-apps/capabilities/runtime.js

@@ -0,0 +1,66 @@
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import "../../capabilities/runtime/dispatcher.js";
+import { createHash } from "node:crypto";
+//#region src/local-apps/capabilities/runtime.ts
+/** Shared UI/Agent execution boundary; callers cannot manufacture grants or release identity. */
+function localAppCapabilities(apps, dispatcher, extensionId, manifestDigest, caller) {
+	const access = apps.getCapabilityAccess(extensionId, manifestDigest);
+	const current = () => {
+		if (apps.getCapabilityAccess(extensionId, manifestDigest).releaseId !== access.releaseId) throw new CapabilityError("CONTRACT_CHANGED", "Local app release changed");
+	};
+	const context = {
+		...caller,
+		surface: "extension",
+		allowedCapabilities: access.bindings.map((binding) => binding.id).filter((id) => !caller.allowedCapabilities || caller.allowedCapabilities.includes(id)),
+		assertCurrent: () => {
+			caller.assertCurrent?.();
+			current();
+		},
+		authorize: async (id, input) => {
+			const allowed = await caller.authorize(id, input);
+			current();
+			return allowed;
+		}
+	};
+	return {
+		list() {
+			current();
+			return {
+				releaseId: access.releaseId,
+				manifestDigest,
+				capabilities: dispatcher.list(context).filter((item) => access.bindings.some((binding) => binding.id === item.id && binding.majorVersion === item.majorVersion && binding.descriptorDigest === item.descriptorDigest))
+			};
+		},
+		async call(id, call) {
+			current();
+			const binding = access.bindings.find((item) => item.id === id);
+			if (!binding) throw new CapabilityError("FORBIDDEN", "Capability is not declared by this release");
+			if (binding.majorVersion !== call.majorVersion || binding.descriptorDigest !== call.descriptorDigest) throw new CapabilityError("CONTRACT_CHANGED", "Capability differs from the installed binding");
+			const write = dispatcher.describe(id, context).effect !== "read";
+			if (write && !call.idempotencyKey?.trim()) throw new CapabilityError("INVALID_INPUT", "A stable idempotencyKey is required");
+			const key = call.idempotencyKey ? createHash("sha256").update(JSON.stringify([
+				caller.principalId,
+				extensionId,
+				access.releaseId,
+				call.idempotencyKey
+			])).digest("hex") : void 0;
+			const result = await dispatcher.call(id, call.input, context, {
+				...call,
+				idempotencyKey: key
+			});
+			try {
+				current();
+			} catch (error) {
+				if (write) throw new CapabilityError("OUTCOME_UNKNOWN", "Write may have committed; retain the original idempotencyKey and reconcile after restoring access");
+				throw error;
+			}
+			return {
+				status: "succeeded",
+				releaseId: access.releaseId,
+				data: result
+			};
+		}
+	};
+}
+//#endregion
+export { localAppCapabilities };

package/dist/src/local-apps/capabilities/write.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+import { type LocalAppService } from '../service.js';
+export declare function registerLocalAppWriteCapabilities(dispatcher: CapabilityDispatcher, service: LocalAppService): void;

package/dist/src/local-apps/capabilities/write.js

@@ -0,0 +1,35 @@
+import { LocalAppAcceptanceInputSchema, LocalAppAcceptanceOutputSchema } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineAtomicCapability } from "../../capabilities/runtime/dispatcher.js";
+import { LocalAppAcceptanceValidationError, LocalAppRevisionConflictError } from "../service.js";
+import { z } from "zod";
+//#region src/local-apps/capabilities/write.ts
+init_src();
+function registerLocalAppWriteCapabilities(dispatcher, service) {
+	dispatcher.register(defineAtomicCapability({
+		id: "xopc.local_apps.record_acceptance",
+		majorVersion: 1,
+		effect: "local-write",
+		description: "Record supplied acceptance checks against the exact local source digest; this does not execute the checks.",
+		surfaces: ["http", "agent"],
+		scopes: ["gateway.admin"],
+		input: LocalAppAcceptanceInputSchema.extend({ id: z.string().min(1).max(512) }),
+		output: z.object({ acceptance: LocalAppAcceptanceOutputSchema }),
+		execute({ id, ...input }) {
+			if (!service.get(id)) throw new CapabilityError("NOT_FOUND", "Local app not found");
+			try {
+				return { acceptance: service.recordAcceptance(id, input) };
+			} catch (error) {
+				if (error instanceof LocalAppRevisionConflictError) throw new CapabilityError("REVISION_CONFLICT", error.message);
+				if (error instanceof LocalAppAcceptanceValidationError) throw new CapabilityError("INVALID_INPUT", error.message);
+				throw error;
+			}
+		},
+		afterCommit() {
+			service.flushAcceptanceEvents();
+		}
+	}));
+}
+//#endregion
+export { registerLocalAppWriteCapabilities };

package/dist/src/local-apps/release-lock.d.ts

@@ -0,0 +1,2 @@
+/** Serialize release mutations sharing an extension directory, including across service instances. */
+export declare function withLocalAppReleaseLock<T>(root: string, action: () => Promise<T>): Promise<T>;

package/dist/src/local-apps/release-lock.js

@@ -0,0 +1,20 @@
+//#region src/local-apps/release-lock.ts
+const pending = /* @__PURE__ */ new Map();
+/** Serialize release mutations sharing an extension directory, including across service instances. */
+async function withLocalAppReleaseLock(root, action) {
+	const previous = pending.get(root) ?? Promise.resolve();
+	let release;
+	const next = new Promise((resolve) => {
+		release = resolve;
+	});
+	pending.set(root, next);
+	await previous;
+	try {
+		return await action();
+	} finally {
+		release();
+		if (pending.get(root) === next) pending.delete(root);
+	}
+}
+//#endregion
+export { withLocalAppReleaseLock };

package/dist/src/local-apps/runtime-entry.d.ts

@@ -4,5 +4,3 @@ export declare const LOCAL_APP_RUNTIME_ENTRY = ".xopc/runtime/local-ui.js";
  * arbitrary Node.js in the gateway process through the extension `main` entry.
  */
 export declare const LOCAL_APP_RUNTIME_SOURCE = "export default Object.freeze({});\n";
-/** Exact legacy scaffold bytes accepted only to keep existing Phase 1 drafts upgradeable. */
-export declare function legacyLocalAppRuntimeSource(extensionId: string, name: string): string;

package/dist/src/local-apps/runtime-entry.js

@@ -6,18 +6,5 @@ const LOCAL_APP_RUNTIME_ENTRY = ".xopc/runtime/local-ui.js";
 */
 const LOCAL_APP_RUNTIME_SOURCE = `export default Object.freeze({});
 `;
-/** Exact legacy scaffold bytes accepted only to keep existing Phase 1 drafts upgradeable. */
-function legacyLocalAppRuntimeSource(extensionId, name) {
-	return `export default {
-  id: ${JSON.stringify(extensionId)},
-  name: ${JSON.stringify(name)},
-  version: '0.1.0',
-  kind: 'utility',
-  register(api) {
-    api.logger.info('Local app registered');
-  },
-};
-`;
-}
 //#endregion
-export { LOCAL_APP_RUNTIME_ENTRY, LOCAL_APP_RUNTIME_SOURCE, legacyLocalAppRuntimeSource };
+export { LOCAL_APP_RUNTIME_ENTRY, LOCAL_APP_RUNTIME_SOURCE };