@xopcai/xopc 0.0.321 → 0.0.324

package/dist/src/agent/tools/xopc-use-tool.js

@@ -1,16 +1,17 @@
 import { runWithActivityContext } from "../../activity/context.js";
 import { TaskCommandSchema, TaskContextInputSchema } from "../../../packages/gateway-contract/src/tasks.js";
+import { ChatPreviewCreateInputSchema, ChatPreviewReviseInputSchema } from "../../../packages/gateway-contract/src/chat-previews.js";
 import { appendProductDeliveryText } from "../../../packages/gateway-contract/src/product-delivery.js";
 import { AutomationCancelOutputSchema, AutomationDeleteOutputSchema, AutomationMutationOutputSchema, AutomationReadAllInputSchema, AutomationReadAllOutputSchema, AutomationReadOutputSchema, AutomationRunMutationOutputSchema, CapabilityCallSchema, CapabilityResourceInputSchema, NoteDeleteOutputSchema, NoteGetOutputSchema, ProjectCreateInputSchema, ProjectDeleteInputSchema, ProjectDeleteOutputSchema, ProjectEditInputSchema, ProjectMilestoneCreateInputSchema, ProjectMilestoneDeleteInputSchema, ProjectMilestoneDeleteOutputSchema, ProjectMilestoneOutputSchema, ProjectMilestoneUpdateInputSchema, ProjectMutationOutputSchema, ProjectResolveWorkspaceInputSchema, ProjectResolveWorkspaceOutputSchema, ProjectSetPinnedInputSchema, ProjectUpdateCreateInputSchema, ProjectUpdateOutputSchema, SceneWriteContracts, TaskRunCancelInputSchema, TaskRunCancelOutputSchema, TaskRunFeedbackInputSchema, TaskRunFeedbackOutputSchema } from "../../../packages/gateway-contract/src/capabilities.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { TaskRepository } from "../../tasks/task-repository.js";
 import { TaskRunRepository } from "../../tasks/task-run-repository.js";
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
-import "../../storage/sqlite/index.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
 import "../../activity/index.js";
-import { getDefaultAgentId, init_resolve_route } from "../../routing/resolve-route.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import "../../capabilities/runtime/dispatcher.js";
+import { getDefaultAgentId, init_resolve_route } from "../../routing/resolve-route.js";
 import { resolveProjectAgentId } from "../../projects/project-agent.js";
 import "../../projects/index.js";
 import { TaskDeletionService } from "../../tasks/task-deletion-service.js";
@@ -26,6 +27,7 @@ import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/xopc-use-tool.ts
 init_src();
 init_resolve_route();
+init_sqlite();
 const XopcUseToolSchema = Type.Object({
 	mode: Type.Union([
 		Type.Literal("context"),
@@ -36,9 +38,11 @@ const XopcUseToolSchema = Type.Object({
 		Type.Literal("task"),
 		Type.Literal("task_run"),
 		Type.Literal("local_app"),
+		Type.Literal("chat_preview"),
+		Type.Literal("agent"),
 		Type.Literal("settings")
 	]),
-	command: Type.String({ description: "Context resolve takes an explicit AppContextEnvelope; never guess a current page. Automation draft/repair_draft accept prompt/id, agentId?, language?, idempotencyKey?; simulate explains an automation without running it. Local_app record_acceptance records supplied checks and sourceHash, not proof that checks were executed. Project create accepts idempotencyKey; update/pin/unpin/delete accepts {projectId, expectedVersion?, idempotencyKey?}; stable retries require the original expectedVersion. Delete preserves workspace files and does not confirm external execution stopped. Project milestone writes support idempotencyKey; update_milestone/delete_milestone require original expectedRevision for stable retries, and create_update requires original expectedVersion. TaskRun cancel accepts idempotencyKey and expectedVersion, and does not confirm external execution stopped. Automation diagnostics: get_run/run_events {runId}, metrics {}, product_events {eventType, source?, payloadKey?, payloadValue?, limit?}; payload filters require both key and value. Automation also supports cancel/read {runId, idempotencyKey?} and read_all {projectId?, idempotencyKey?}; omitted projectId means all projects. Cancel acceptance is not confirmation of stopping. Object command. Scene commands: templates, list, get {id}, mail_accounts, mail_search {accountId, query}, mail_sources, read_notes {id}, preflight/start {templateKey, templateVersion, goal, scope, permissions}, configure {id, expectedRevision, goal, scope, permissions}, transition {id, expectedRevision, status: paused|active|completed|archived}, check {id}, notes {id, expectedRevision, content, validUntil?}, work_item {id, subjectId, accountId, dueAt}, update_work_item {workItemId, expectedRevision, dueAt?, status?}, schedule {id, triggerKey, expectedRevision, schedule}, results {id?}, feedback {presentationId, expectedRevision, rating}, mark_read {presentationId, read}, diagnostics, get_preferences, set_preferences {expectedRevision, ...preferences}. Start and check accept a stable requestId for retries. Scenes prepare read-only suggestions and drafts; never send mail. Only create a scene for work explicitly delegated by the user; inspect existing scenes first. Supports project list/get/create/update/resolve_workspace/list_milestones/create_milestone/update_milestone/list_updates/create_update, automation list/get/create/update/delete/run/rerun/pause/resume/history (rerun takes runId; run/rerun accept idempotencyKey), note list/get/project_summaries/history {noteId}/snapshot {noteId, timestamp}/create/append/update/preview_edit/delete, task list/get/create/update_dependencies/add_context/remove_context/command/delete, task_run list/get/cancel, local_app list/get/create/validate, and settings open." }),
+	command: Type.String({ description: "Context resolve takes an explicit AppContextEnvelope; never guess a current page. Automation draft/repair_draft accept prompt/id, agentId?, language?, idempotencyKey?; simulate explains an automation without running it. Local_app record_acceptance records supplied checks and sourceHash, not proof that checks were executed. Agent commands: list, get {id}, create {id, profile, workspace?, models?, skills?, tools?, workflows?, runtime?, idempotencyKey?}, update {id, expectedRevision, patch, idempotencyKey?}, set_default {id, expectedRevision, idempotencyKey?}, disable/delete/purge {id, expectedRevision, idempotencyKey?}. Purge also removes on-disk data. Project create accepts idempotencyKey; update/pin/unpin/delete accepts {projectId, expectedVersion?, idempotencyKey?}; stable retries require the original expectedVersion. Delete preserves workspace files and does not confirm external execution stopped. Project milestone writes support idempotencyKey; update_milestone/delete_milestone require original expectedRevision for stable retries, and create_update requires original expectedVersion. TaskRun cancel accepts idempotencyKey and expectedVersion, and does not confirm external execution stopped. Automation diagnostics: get_run/run_events {runId}, metrics {}, product_events {eventType, source?, payloadKey?, payloadValue?, limit?}; payload filters require both key and value. Automation also supports cancel/read {runId, idempotencyKey?} and read_all {projectId?, idempotencyKey?}; omitted projectId means all projects. Cancel acceptance is not confirmation of stopping. Object command. Scene commands: templates, list, get {id}, mail_accounts, mail_search {accountId, query}, mail_sources, read_notes {id}, preflight/start {templateKey, templateVersion, goal, scope, permissions}, configure {id, expectedRevision, goal, scope, permissions}, transition {id, expectedRevision, status: paused|active|completed|archived}, check {id}, notes {id, expectedRevision, content, validUntil?}, work_item {id, subjectId, accountId, dueAt}, update_work_item {workItemId, expectedRevision, dueAt?, status?}, schedule {id, triggerKey, expectedRevision, schedule}, results {id?}, feedback {presentationId, expectedRevision, rating}, mark_read {presentationId, read}, diagnostics, get_preferences, set_preferences {expectedRevision, ...preferences}. Start and check accept a stable requestId for retries. Scenes prepare read-only suggestions and drafts; never send mail. Only create a scene for work explicitly delegated by the user; inspect existing scenes first. Supports project list/get/create/update/resolve_workspace/list_milestones/create_milestone/update_milestone/list_updates/create_update, automation list/get/create/update/delete/run/rerun/pause/resume/history (rerun takes runId; run/rerun accept idempotencyKey), note list/get/project_summaries/history {noteId}/snapshot {noteId, timestamp}/create/append/update/preview_edit/delete, task list/get/create/update_dependencies/add_context/remove_context/command/delete, task_run list/get/cancel, chat_preview create/revise/get, local_app list/get/create/validate, and settings open." }),
 	args: Type.Optional(Type.Record(Type.String(), Type.Any())),
 	dryRun: Type.Optional(Type.Boolean({ description: "Validate and preview the action without mutating xopc state." }))
 });
@@ -160,7 +164,7 @@ function deliveryForXopcResult(mode, command, result, dryRun) {
 			}] : [];
 		});
 		return {
-			version: 1,
+			version: 2,
 			operation: "opened",
 			presentation: {
 				kind: "table",
@@ -187,7 +191,7 @@ function deliveryForXopcResult(mode, command, result, dryRun) {
 			}];
 		});
 		return {
-			version: 1,
+			version: 2,
 			operation: "opened",
 			presentation: {
 				kind: "diff",
@@ -309,6 +313,7 @@ function deliveryForXopcResult(mode, command, result, dryRun) {
 		};
 	} else if (mode === "local_app") {
 		source = record(resultRecord.app);
+		const snapshot = record(resultRecord.snapshot);
 		const id = deliveryText(source?.id);
 		if (id) primary = {
 			kind: "local_app",
@@ -316,16 +321,35 @@ function deliveryForXopcResult(mode, command, result, dryRun) {
 			title: deliveryText(source?.name) ?? "Local app",
 			summary: deliverySummary(source?.description, source?.idea),
 			status: deliveryText(source?.installationState) ?? deliveryText(source?.status),
-			revision: deliveryRevision(source?.updatedAt),
+			revision: deliveryText(snapshot?.sourceHash),
 			projectId: deliveryText(source?.projectId),
 			capabilities: [
 				"open",
 				"preview",
 				"edit",
 				"continue_in_chat",
+				"fix",
 				"run"
 			]
 		};
+	} else if (mode === "chat_preview") {
+		source = record(resultRecord.preview);
+		const revision = record(resultRecord.revision);
+		const id = deliveryText(source?.id);
+		const sourceHash = deliveryText(revision?.sourceHash) ?? deliveryText(source?.latestRevision);
+		if (id && sourceHash) primary = {
+			kind: "chat_preview",
+			id,
+			title: deliveryText(source?.title) ?? "Preview",
+			status: "preview_ready",
+			revision: sourceHash,
+			capabilities: [
+				"preview",
+				"edit",
+				"continue_in_chat",
+				"fix"
+			]
+		};
 	} else if (mode === "settings") {
 		source = record(resultRecord.settings);
 		const id = deliveryText(source?.section);
@@ -342,10 +366,26 @@ function deliveryForXopcResult(mode, command, result, dryRun) {
 		};
 	}
 	if (!primary) return void 0;
+	const localAppSnapshotHash = mode === "local_app" ? deliveryText(record(resultRecord.snapshot)?.sourceHash) : void 0;
+	if (mode === "local_app" && !localAppSnapshotHash) return void 0;
+	const chatPreviewSourceHash = mode === "chat_preview" ? deliveryText(record(resultRecord.revision)?.sourceHash) ?? deliveryText(record(resultRecord.preview)?.latestRevision) : void 0;
+	if (mode === "chat_preview" && !chatPreviewSourceHash) return void 0;
 	return {
-		version: 1,
+		version: 2,
 		operation: mode === "task" && deliveryText(resultRecord.runId) || mode === "automation" && (command === "run" || command === "rerun") || mode === "scene" && command === "check" ? "started" : command === "create" || mode === "scene" && command === "start" ? "created" : command === "get" || command === "resolve_workspace" || mode === "settings" ? "opened" : command === "validate" ? "completed" : "updated",
-		primary
+		primary,
+		...mode === "local_app" ? { presentation: {
+			kind: "inline_app",
+			reference: primary,
+			snapshot: { sourceHash: localAppSnapshotHash },
+			preferredHeight: 480
+		} } : {},
+		...mode === "chat_preview" ? { presentation: {
+			kind: "inline_preview",
+			reference: primary,
+			sourceHash: chatPreviewSourceHash,
+			preferredHeight: Number(source?.preferredHeight) || 480
+		} } : {}
 	};
 }
 function currentProjectId(args, deps) {
@@ -374,6 +414,52 @@ function optionalProjectWorkspaceRootArg(args) {
 	if (args.workspacePath !== void 0) return optionalString(args.workspacePath);
 	if (args.path !== void 0) return optionalString(args.path);
 }
+async function handleAgent(command, args, dryRun, capabilities, deps, toolCallId, signal) {
+	const readCommands = new Set(["list", "get"]);
+	const writeCommands = new Set([
+		"create",
+		"update",
+		"set_default",
+		"disable",
+		"delete",
+		"purge"
+	]);
+	if (!readCommands.has(command) && !writeCommands.has(command)) return {
+		ok: false,
+		error: `Unsupported agent command: ${command}`
+	};
+	const operation = `xopc.agents.${command}`;
+	const { idempotencyKey, ...fields } = args;
+	if (idempotencyKey !== void 0 && !trimString(idempotencyKey)) return {
+		ok: false,
+		error: "idempotencyKey must be a non-empty string"
+	};
+	const input = command === "list" ? {} : fields;
+	const caller = {
+		principalId: `agent:${deps.getCurrentAgentId?.() ?? "main"}`,
+		surface: "agent",
+		scopes: writeCommands.has(command) ? ["gateway.admin"] : ["agents.read"],
+		actor: {
+			kind: "agent",
+			id: deps.getCurrentAgentId?.() ?? "main"
+		},
+		authorize: deps.authorizeCapability ?? (() => true),
+		signal
+	};
+	if (dryRun && writeCommands.has(command)) return {
+		ok: true,
+		dryRun: true,
+		action: command,
+		input: await capabilities.validateInput(operation, input, caller)
+	};
+	const expected = writeCommands.has(command) ? {
+		...capabilities.describe(operation, caller),
+		idempotencyKey: trimString(idempotencyKey) ?? toolCallId
+	} : void 0;
+	const result = await capabilities.call(operation, input, caller, expected);
+	if (writeCommands.has(command)) deps.onAgentCatalogMutate?.();
+	return result;
+}
 async function handleProject(command, args, deps, dryRun, capabilities) {
 	const projects = deps.getProjectService?.();
 	if (!projects) return {
@@ -1173,7 +1259,7 @@ async function handleTask(command, args, deps, dryRun, capabilities) {
 			projects: projectService,
 			explicitAgentId,
 			projectId
-		}) : explicitAgentId ?? (config ? getDefaultAgentId(config) : deps.getCurrentAgentId?.() ?? "main");
+		}) : explicitAgentId ?? (config ? getDefaultAgentId() : deps.getCurrentAgentId?.() ?? "main");
 		const input = {
 			idempotencyKey: trimString(args.idempotencyKey) ?? randomUUID(),
 			title: trimString(args.title) ?? objective,
@@ -1530,6 +1616,63 @@ async function handleLocalApp(command, args, deps, dryRun) {
 		error: `Unsupported local_app command: ${command}`
 	};
 }
+async function handleChatPreview(command, args, deps, dryRun) {
+	const previews = deps.getChatPreviewService?.();
+	if (!previews) return {
+		ok: false,
+		error: "Chat preview service is unavailable"
+	};
+	const id = trimString(args.previewId) ?? trimString(args.id);
+	if (command === "create") {
+		const conversationId = deps.getCurrentConversationId?.();
+		if (!conversationId) return {
+			ok: false,
+			error: "A current conversation is required"
+		};
+		const input = ChatPreviewCreateInputSchema.parse(args);
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "create_chat_preview",
+			input
+		};
+		return {
+			ok: true,
+			...previews.create(conversationId, input)
+		};
+	}
+	if (!id) return {
+		ok: false,
+		error: "previewId is required"
+	};
+	if (command === "get") {
+		const preview = previews.get(id);
+		return {
+			ok: true,
+			preview,
+			revision: previews.getRevision(id, trimString(args.sourceHash) ?? preview.latestRevision)
+		};
+	}
+	if (command === "revise") {
+		const { previewId: _previewId, id: _id, ...rawInput } = args;
+		const input = ChatPreviewReviseInputSchema.parse(rawInput);
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "revise_chat_preview",
+			previewId: id,
+			input
+		};
+		return {
+			ok: true,
+			...previews.revise(id, input)
+		};
+	}
+	return {
+		ok: false,
+		error: `Unsupported chat_preview command: ${command}`
+	};
+}
 function createXopcUseTool(deps) {
 	const capabilities = createProductDispatcher(deps.getNotesService, {
 		getConfig: deps.getConfig,
@@ -1543,7 +1686,7 @@ function createXopcUseTool(deps) {
 	return {
 		name: "xopc_use",
 		label: "XOPC Use",
-		description: "Operate first-class xopc objects through one safe entry point. Local App capabilities takes extensionId and discovers already granted bindings. Local App invoke requires extensionId, the discovered manifestDigest, capabilityId and a pinned call {majorVersion, descriptorDigest, input, idempotencyKey for writes}. Never manufacture grants or change a retry key after an uncertain write. Use for scenes, projects, automations, notes, tasks, TaskRuns, local apps, and exact settings jump targets instead of editing storage files directly. For non-trivial object changes, load the built-in manual first with tool_manual({ tool: \"xopc_use\" }).",
+		description: "Operate first-class xopc objects through one safe entry point. Use chat_preview for lightweight UI mockups in the current conversation; do not create a Local App unless the user asks for a durable app. Local App capabilities takes extensionId and discovers already granted bindings. Local App invoke requires extensionId, the discovered manifestDigest, capabilityId and a pinned call {majorVersion, descriptorDigest, input, idempotencyKey for writes}. Never manufacture grants or change a retry key after an uncertain write. Use for Agents, scenes, projects, automations, notes, tasks, TaskRuns, chat previews, local apps, and exact settings jump targets instead of editing storage files directly. For non-trivial object changes, load the built-in manual first with tool_manual({ tool: \"xopc_use\" }).",
 		parameters: XopcUseToolSchema,
 		mutatesWorkspace: true,
 		mutationScope: "external",
@@ -1719,15 +1862,22 @@ function createXopcUseTool(deps) {
 					authorize: deps.authorizeCapability ?? (() => true),
 					signal
 				};
-				const result = await capabilities.call(`xopc.local_apps.${command}`, command === "list" ? {} : { id: args.localAppId ?? args.id }, caller);
-				if (command === "validate") Object.assign(result, await capabilities.call("xopc.local_apps.get", { id: args.localAppId ?? args.id }, caller));
+				const id = args.localAppId ?? args.id;
+				const result = await capabilities.call(`xopc.local_apps.${command}`, command === "list" ? {} : { id }, caller);
+				if (command === "validate") Object.assign(result, await capabilities.call("xopc.local_apps.get", { id }, caller));
+				const appId = deliveryText(record(result.app)?.id);
+				const snapshot = appId && command !== "list" ? deps.getLocalAppService?.()?.materializeSnapshot(appId) : void 0;
+				const deliveryResult = snapshot ? {
+					...result,
+					snapshot
+				} : result;
 				return okText({
 					...details,
 					result: {
 						ok: true,
 						...result
 					},
-					delivery: deliveryForXopcResult(mode, command, result, dryRun)
+					delivery: deliveryForXopcResult(mode, command, deliveryResult, dryRun)
 				});
 			}
 			if (mode === "task" && command === "metrics") {
@@ -1976,14 +2126,20 @@ function createXopcUseTool(deps) {
 						kind: "xopc_use",
 						toolCallId
 					}
-				}, async () => mode === "scene" ? await handleScene(command, args, deps, dryRun) : mode === "project" ? await handleProject(command, args, deps, dryRun, capabilities) : mode === "automation" ? await handleAutomation(command, args, deps, dryRun, capabilities) : mode === "note" ? await handleNote(command, args, deps, dryRun, capabilities) : mode === "task" ? await handleTask(command, args, deps, dryRun, capabilities) : mode === "task_run" ? await handleTaskRun(command, args, dryRun, deps, capabilities) : mode === "local_app" ? await handleLocalApp(command, args, deps, dryRun) : {
+				}, async () => mode === "scene" ? await handleScene(command, args, deps, dryRun) : mode === "agent" ? await handleAgent(command, args, dryRun, capabilities, deps, toolCallId, signal) : mode === "project" ? await handleProject(command, args, deps, dryRun, capabilities) : mode === "automation" ? await handleAutomation(command, args, deps, dryRun, capabilities) : mode === "note" ? await handleNote(command, args, deps, dryRun, capabilities) : mode === "task" ? await handleTask(command, args, deps, dryRun, capabilities) : mode === "task_run" ? await handleTaskRun(command, args, dryRun, deps, capabilities) : mode === "local_app" ? await handleLocalApp(command, args, deps, dryRun) : mode === "chat_preview" ? await handleChatPreview(command, args, deps, dryRun) : {
 					ok: false,
 					error: `Unsupported mode: ${String(mode)}`
 				});
+				const resultRecord = record(result);
+				const createdAppId = deliveryText((mode === "local_app" && command === "create" ? record(resultRecord.app) : void 0)?.id);
+				const deliveryResult = createdAppId ? {
+					...resultRecord,
+					snapshot: deps.getLocalAppService?.()?.materializeSnapshot(createdAppId)
+				} : result;
 				return okText({
 					...details,
 					result,
-					delivery: deliveryForXopcResult(mode, command, result, dryRun)
+					delivery: deliveryForXopcResult(mode, command, deliveryResult, dryRun)
 				});
 			} catch (err) {
 				return errorText(err instanceof Error ? err.message : String(err), details);

package/dist/src/agent/workflow/workflow-child-tools.js

@@ -3,8 +3,7 @@ import { AgentToolsFactory } from "../tools/factory.js";
 //#region src/agent/workflow/workflow-child-tools.ts
 /** Builds the tool set for workflow child agents (wired from gateway to avoid cycles). */
 function buildWorkflowChildTools(childOptions) {
-	const config = childOptions.getConfig();
-	const profile = config ? childOptions.browserConversationId ? resolveEffectiveAgentProfileForSession(config, childOptions.browserConversationId) : childOptions.agentId ? resolveEffectiveAgentProfile(config, childOptions.agentId) : resolveEffectiveAgentProfileForSession(config, void 0) : void 0;
+	const profile = childOptions.getConfig() ? childOptions.browserConversationId ? resolveEffectiveAgentProfileForSession(childOptions.browserConversationId) : childOptions.agentId ? resolveEffectiveAgentProfile(childOptions.agentId) : resolveEffectiveAgentProfileForSession(void 0) : void 0;
 	return new AgentToolsFactory({
 		workspace: childOptions.workspace,
 		bus: childOptions.bus,

package/dist/src/agent/workspace-runtime/registry.d.ts

@@ -48,7 +48,7 @@ export declare class WorkspaceRuntimeRegistry {
     values(): IterableIterator<WorkspaceRuntime>;
     /**
      * Tear down every runtime (shutdown memory providers) and forget the cache.
-     * Used by `AgentManager.updateAgentDefaults` and `AgentManager.dispose`.
+     * Used by `AgentManager.updateRuntimeConfiguration` and `AgentManager.dispose`.
      */
     clearAll(): Promise<void>;
 }

package/dist/src/agent/workspace-runtime/registry.js

@@ -23,7 +23,7 @@ var WorkspaceRuntimeRegistry = class {
 	/** Lazily construct and cache an agent-scoped runtime for a workspace. */
 	getOrCreate(resolvedPath, requestedAgentId) {
 		const cfg = this.getConfig();
-		const runtimeKey = `${normalizeAgentId(requestedAgentId?.trim() || resolveAgentIdForWorkspacePath(cfg, resolvedPath))}\u0000${resolvedPath}`;
+		const runtimeKey = `${normalizeAgentId(requestedAgentId?.trim() || resolveAgentIdForWorkspacePath(resolvedPath))}\u0000${resolvedPath}`;
 		const existing = this.runtimes.get(runtimeKey);
 		if (existing) return existing;
 		const { memoryManager } = this.userContextRuntimes.getOrCreate(cfg);
@@ -50,7 +50,7 @@ var WorkspaceRuntimeRegistry = class {
 	}
 	/**
 	* Tear down every runtime (shutdown memory providers) and forget the cache.
-	* Used by `AgentManager.updateAgentDefaults` and `AgentManager.dispose`.
+	* Used by `AgentManager.updateRuntimeConfiguration` and `AgentManager.dispose`.
 	*/
 	async clearAll() {
 		this.runtimes.clear();

package/dist/src/agent-catalog/capabilities.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDispatcher } from '../capabilities/runtime/dispatcher.js';
+/** Register Agent catalog operations for UI, HTTP, CLI, and conversational tools. */
+export declare function registerAgentCapabilities(dispatcher: CapabilityDispatcher): void;

package/dist/src/agent-catalog/capabilities.js

@@ -0,0 +1,238 @@
+import { AgentEntrySchema, EffectiveAgentConfigSchema } from "../agent-config/schema.js";
+import { resolveEffectiveAgentConfig } from "../agent-config/resolver.js";
+import { init_agent_config } from "../agent-config/index.js";
+import { CapabilityError } from "../capabilities/runtime/errors.js";
+import { defineAtomicCapability, defineReadCapability } from "../capabilities/runtime/dispatcher.js";
+import { AgentCatalogRepository, init_repository } from "./repository.js";
+import { init_agent_scope, resolveAgentWorkspaceDir } from "../agent/agent-scope.js";
+import { AgentCatalogService } from "./service.js";
+import { z } from "zod";
+//#region src/agent-catalog/capabilities.ts
+init_agent_config();
+init_agent_scope();
+init_repository();
+const AgentIdInputSchema = z.strictObject({ id: AgentEntrySchema.shape.id });
+const EmptyInputSchema = z.strictObject({});
+const StoredAgentSchema = AgentEntrySchema.extend({
+	revision: z.number().int().positive(),
+	provisioningState: z.enum([
+		"pending",
+		"ready",
+		"error"
+	]),
+	provisioningError: z.string().optional(),
+	createdAt: z.number().int().nonnegative(),
+	updatedAt: z.number().int().nonnegative(),
+	deletedAt: z.number().int().nonnegative().optional()
+});
+const AgentViewSchema = z.object({
+	agent: StoredAgentSchema,
+	effective: EffectiveAgentConfigSchema
+});
+const AgentMutationOutputSchema = AgentViewSchema.extend({ ok: z.literal(true) });
+const AgentListOutputSchema = z.object({
+	ok: z.literal(true),
+	defaultAgentId: AgentEntrySchema.shape.id,
+	catalogRevision: z.number().int().positive(),
+	agents: z.array(AgentViewSchema)
+});
+const AgentUpdateInputSchema = z.strictObject({
+	id: AgentEntrySchema.shape.id,
+	expectedRevision: z.number().int().positive(),
+	patch: AgentEntrySchema.omit({ id: true }).partial()
+});
+const AgentSetDefaultInputSchema = z.strictObject({
+	id: AgentEntrySchema.shape.id,
+	expectedRevision: z.number().int().positive()
+});
+const AgentDeleteOutputSchema = z.object({
+	ok: z.literal(true),
+	deleted: z.literal(true),
+	agent: StoredAgentSchema,
+	removedBindings: z.number().int().nonnegative()
+});
+function effective(repository, agent) {
+	const { revision: _revision, provisioningState: _state, provisioningError: _error, createdAt: _created, updatedAt: _updated, deletedAt: _deleted, ...entry } = agent;
+	return resolveEffectiveAgentConfig({
+		defaults: repository.getSettings().defaults,
+		agent: entry,
+		defaultWorkspace: resolveAgentWorkspaceDir
+	}).config;
+}
+function view(repository, agent) {
+	return {
+		agent,
+		effective: effective(repository, agent)
+	};
+}
+function requireAgent(repository, id) {
+	const agent = repository.get(id);
+	if (!agent) throw new CapabilityError("NOT_FOUND", `Agent "${id}" not found`);
+	return agent;
+}
+function translateMutationError(execute) {
+	try {
+		return execute();
+	} catch (error) {
+		if (error instanceof CapabilityError) throw error;
+		const message = error instanceof Error ? error.message : String(error);
+		throw new CapabilityError(/not found/i.test(message) ? "NOT_FOUND" : /conflict|already exists|default Agent|cannot be disabled|not available/i.test(message) ? "REVISION_CONFLICT" : "INVALID_INPUT", message);
+	}
+}
+/** Register Agent catalog operations for UI, HTTP, CLI, and conversational tools. */
+function registerAgentCapabilities(dispatcher) {
+	const repository = new AgentCatalogRepository();
+	const service = new AgentCatalogService(repository);
+	const readPolicy = {
+		majorVersion: 1,
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli"
+		],
+		scopes: ["agents.read"]
+	};
+	const writePolicy = {
+		majorVersion: 1,
+		effect: "local-write",
+		surfaces: [
+			"http",
+			"agent",
+			"cli"
+		],
+		scopes: ["gateway.admin"]
+	};
+	dispatcher.register(defineReadCapability({
+		...readPolicy,
+		id: "xopc.agents.list",
+		description: "List Agent definitions with their effective inherited configuration.",
+		input: EmptyInputSchema,
+		output: AgentListOutputSchema,
+		execute() {
+			const settings = repository.getSettings();
+			return {
+				ok: true,
+				defaultAgentId: settings.defaultAgentId,
+				catalogRevision: settings.revision,
+				agents: repository.list().map((agent) => view(repository, agent))
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...readPolicy,
+		id: "xopc.agents.get",
+		description: "Read one Agent definition and its effective inherited configuration.",
+		input: AgentIdInputSchema,
+		output: AgentMutationOutputSchema,
+		execute({ id }) {
+			return {
+				ok: true,
+				...view(repository, requireAgent(repository, id))
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...writePolicy,
+		id: "xopc.agents.create",
+		description: "Create a complete Agent definition and queue recoverable directory provisioning.",
+		input: AgentEntrySchema,
+		output: AgentMutationOutputSchema,
+		execute(input) {
+			return {
+				ok: true,
+				...view(repository, translateMutationError(() => repository.create(input)))
+			};
+		},
+		afterCommit: () => service.resumePendingProvisioning()
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...writePolicy,
+		id: "xopc.agents.update",
+		description: "Update an Agent at an exact revision.",
+		input: AgentUpdateInputSchema,
+		output: AgentMutationOutputSchema,
+		execute({ id, expectedRevision, patch }) {
+			const { revision: _revision, provisioningState: _state, provisioningError: _error, createdAt: _created, updatedAt: _updated, deletedAt: _deleted, ...entry } = requireAgent(repository, id);
+			return {
+				ok: true,
+				...view(repository, translateMutationError(() => repository.update(id, expectedRevision, {
+					...entry,
+					...patch,
+					id
+				}, { reprovision: true })))
+			};
+		},
+		afterCommit: () => service.resumePendingProvisioning()
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...writePolicy,
+		id: "xopc.agents.set_default",
+		description: "Select the global default Agent at an exact catalog revision.",
+		input: AgentSetDefaultInputSchema,
+		output: z.object({
+			ok: z.literal(true),
+			defaultAgentId: AgentEntrySchema.shape.id,
+			catalogRevision: z.number().int().positive()
+		}),
+		execute({ id, expectedRevision }) {
+			const settings = translateMutationError(() => repository.setDefault(id, expectedRevision));
+			return {
+				ok: true,
+				defaultAgentId: settings.defaultAgentId,
+				catalogRevision: settings.revision
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...writePolicy,
+		id: "xopc.agents.disable",
+		description: "Disable a non-default Agent at an exact revision.",
+		input: z.strictObject({
+			id: AgentEntrySchema.shape.id,
+			expectedRevision: z.number().int().positive()
+		}),
+		output: AgentMutationOutputSchema,
+		execute({ id, expectedRevision }) {
+			const { revision: _revision, provisioningState: _state, provisioningError: _error, createdAt: _created, updatedAt: _updated, deletedAt: _deleted, ...entry } = requireAgent(repository, id);
+			return {
+				ok: true,
+				...view(repository, translateMutationError(() => repository.update(id, expectedRevision, {
+					...entry,
+					enabled: false,
+					id
+				})))
+			};
+		}
+	}));
+	for (const purge of [false, true]) dispatcher.register(defineAtomicCapability({
+		...writePolicy,
+		id: purge ? "xopc.agents.purge" : "xopc.agents.delete",
+		description: purge ? "Delete an Agent and remove its state and workspace after commit." : "Delete an Agent definition without removing workspace files.",
+		input: z.strictObject({
+			id: AgentEntrySchema.shape.id,
+			expectedRevision: z.number().int().positive()
+		}),
+		output: AgentDeleteOutputSchema,
+		...purge ? { prepare: ({ id, expectedRevision }) => {
+			const current = requireAgent(repository, id);
+			if (current.revision !== expectedRevision) throw new CapabilityError("REVISION_CONFLICT", "Agent changed");
+			service.validatePurgeEntry(current, repository.getSettings().defaultAgentId);
+		} } : {},
+		execute({ id, expectedRevision }) {
+			if (requireAgent(repository, id).revision !== expectedRevision) throw new CapabilityError("REVISION_CONFLICT", "Agent changed");
+			const result = translateMutationError(() => repository.delete(id, { purge }));
+			return {
+				ok: true,
+				deleted: true,
+				agent: result.agent,
+				removedBindings: result.removedBindings
+			};
+		},
+		...purge ? { afterCommit: async () => {
+			if ((await service.resumePendingPurge()).length) throw new CapabilityError("UNAVAILABLE", "Agent was deleted; data purge is pending retry");
+		} } : {}
+	}));
+}
+//#endregion
+export { registerAgentCapabilities };

package/dist/src/agent-catalog/id.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULT_AGENT_ID = "main";
+/** Normalized id segment safe for directory names under `agents/<id>/`. */
+export declare const STRICT_AGENT_ID_RE: RegExp;
+/** Path-safe agent id. */
+export declare function normalizeAgentId(value: string | undefined | null): string;
+/** Derive a folder-safe id, including for display names with no ASCII characters. */
+export declare function deriveAgentIdFromDisplayName(displayName: string): string;
+/** Validate a new Agent id before it becomes a filesystem path segment. */
+export declare function validateAgentIdForNewAgent(explicitId: string | undefined | null, displayNameForDerivation: string): {
+    ok: true;
+    agentId: string;
+} | {
+    ok: false;
+    error: string;
+};