@xopcai/xopc 0.0.323 → 0.0.324

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

@@ -8,7 +8,7 @@ Load this manual before a non-trivial mutation.
 
 \`\`\`json
 {
-  "mode": "scene | project | automation | note | task | task_run | chat_preview | local_app | settings",
+  "mode": "agent | scene | project | automation | note | task | task_run | chat_preview | local_app | settings",
   "command": "...",
   "args": {},
   "dryRun": false
@@ -29,6 +29,7 @@ language. A scene prepares suggestions or drafts and never sends mail or perform
 
 | Object | Tool |
 | --- | --- |
+| Agent definition and default Agent | \`xopc_use\` mode \`agent\` |
 | Scene and scene result | \`xopc_use\` mode \`scene\` |
 | Project, milestone, project update | \`xopc_use\` mode \`project\` |
 | Automation | \`xopc_use\` mode \`automation\` |
@@ -45,6 +46,35 @@ Do not emulate Workflow APIs through \`xopc_use\`. A Task is durable intent;
 a TaskRun is one execution attempt; a WorkflowRun is a procedure execution and may belong
 to a TaskRun. Never treat these three objects as interchangeable.
 
+## Agents
+
+Commands: \`list\`, \`get\`, \`create\`, \`update\`, \`set_default\`, \`disable\`,
+\`delete\`, and \`purge\`.
+
+An Agent profile accepts only \`name\` and optional \`instructions\`. Put personality,
+language, role, and behavioral guidance in \`profile.instructions\`; do not invent profile
+fields such as \`description\`, \`language\`, \`emoji\`, or \`creature\`.
+
+\`\`\`json
+{
+  "mode": "agent",
+  "command": "create",
+  "args": {
+    "id": "xiaomei",
+    "profile": {
+      "name": "小美",
+      "instructions": "使用中文交流，语气温柔、亲切、可爱，同时保持回答清晰可靠。"
+    },
+    "idempotencyKey": "create-agent-xiaomei"
+  }
+}
+\`\`\`
+
+Use \`list\` before creating an Agent so an existing id is updated rather than duplicated.
+Mutations other than \`create\` require the current \`expectedRevision\`; \`set_default\` uses
+the catalog revision returned by \`list\`. \`delete\` preserves on-disk data, while \`purge\`
+also removes it. Use \`dryRun: true\` to validate the exact same input contract without writing.
+
 ## Reliable protocol
 
 1. Use \`list\` then \`get\` when an id is unknown.

package/dist/src/agent/tools/delegation-parent-policy.js

@@ -6,9 +6,8 @@ import { createAgentTurnPolicy } from "../orchestration/agent-turn-policy.js";
 /** Noninteractive callers cannot silently turn an ask policy into an allow. */
 function createDelegationParentPolicy(options) {
 	const policies = (name, args) => {
-		const config = options.getConfig();
-		if (!config) return [];
-		const resolved = options.conversationId ? resolveEffectiveAgentConfigForSession(config, options.conversationId) : options.agentId ? resolveEffectiveAgentConfigForAgent(config, options.agentId) : resolveEffectiveAgentConfigForSession(config, void 0);
+		if (!options.getConfig()) return [];
+		const resolved = options.conversationId ? resolveEffectiveAgentConfigForSession(options.conversationId) : options.agentId ? resolveEffectiveAgentConfigForAgent(options.agentId) : resolveEffectiveAgentConfigForSession(void 0);
 		const names = [name];
 		if (name === "xopc_tool_execute") {
 			const parsed = parseExternalToolRef(String(args?.toolRef ?? ""), "mcp");

package/dist/src/agent/tools/factory.d.ts

@@ -68,6 +68,8 @@ export interface ToolFactoryDeps {
     dispatchTaskEvents?: () => void;
     /** Gateway: queues Task execution for xopc_use task start/resume/verify actions. */
     dispatchTaskRuns?: () => void;
+    /** Gateway: refreshes Agent runtime state after xopc_use mutates the catalog. */
+    onAgentCatalogMutate?: () => void;
     /** Gateway: starts persisted workflow runs (dedicated chat session per run). */
     getWorkflowRunService?: () => WorkflowRunServiceLike | undefined;
     /** Current session skill indexing (tool gating + allowlist); used by skills_list / skill_view. */

package/dist/src/agent/tools/factory.js

@@ -2,10 +2,10 @@ import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
-import { getBrowserTabBinding } from "../../storage/sqlite/browser-tab-binding-repository.js";
+import { getBrowserTabBinding, init_browser_tab_binding_repository } from "../../storage/sqlite/browser-tab-binding-repository.js";
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { getSessionTaskPlan, setSessionTaskPlan } from "../../storage/sqlite/session-task-plan-repository.js";
-import "../../storage/sqlite/index.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
 import { resolveEffectiveAgentConfigForAgent, resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
 import "../../../packages/browser-control-contract/src/index.js";
@@ -74,7 +74,9 @@ import "../capabilities/index.js";
 import { sortToolsForPromptCache } from "./cache-stability.js";
 //#region src/agent/tools/factory.ts
 init_agent_scope();
+init_browser_tab_binding_repository();
 init_logger();
+init_sqlite();
 init_paths_state();
 const log = createLogger("AgentToolsFactory");
 /** Channels where `clarify` can block for a user answer (web UI, Telegram, CLI readline). */
@@ -219,10 +221,10 @@ var AgentToolsFactory = class AgentToolsFactory {
 		const imageGenerateTool = createImageGenerateTool({
 			config: cfg,
 			workspace,
-			agentId: options?.agentId ?? (cfg ? resolveDefaultAgentId(cfg) : "main")
+			agentId: options?.agentId ?? (cfg ? resolveDefaultAgentId() : "main")
 		});
 		const agentId = options?.agentId;
-		const resolvedAgentId = agentId ?? (cfg ? resolveDefaultAgentId(cfg) : "main");
+		const resolvedAgentId = agentId ?? (cfg ? resolveDefaultAgentId() : "main");
 		const currentConversationId = () => options?.conversationId ?? this.deps.getCurrentContext?.()?.conversationId;
 		const deliveryContext = () => {
 			if (currentConversationId() && getSessionMetadata(currentConversationId())?.sessionType === "heartbeat") throw new Error("Heartbeat notifications must be returned in the final response for policy-controlled delivery.");
@@ -235,8 +237,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 			return key ? getSessionMetadata(key)?.projectId : void 0;
 		};
 		const getCommandIsolation = () => {
-			const config = this.deps.getConfig?.();
-			return config ? (currentConversationId() ? resolveEffectiveAgentConfigForSession(config, currentConversationId()) : resolveEffectiveAgentConfigForAgent(config, resolvedAgentId)).config.runtime.commandIsolation : void 0;
+			return this.deps.getConfig?.() ? (currentConversationId() ? resolveEffectiveAgentConfigForSession(currentConversationId()) : resolveEffectiveAgentConfigForAgent(resolvedAgentId)).config.runtime.commandIsolation : void 0;
 		};
 		const externalTools = createDefaultExternalToolGatewayTools({
 			workspace,
@@ -442,7 +443,8 @@ var AgentToolsFactory = class AgentToolsFactory {
 				getLocalAppService: this.deps.getLocalAppService,
 				getChatPreviewService: this.deps.getChatPreviewService,
 				dispatchTaskEvents: this.deps.dispatchTaskEvents,
-				dispatchTaskRuns: this.deps.dispatchTaskRuns
+				dispatchTaskRuns: this.deps.dispatchTaskRuns,
+				onAgentCatalogMutate: this.deps.onAgentCatalogMutate
 			})] : [],
 			...cfg?.computer.enabled && this.deps.endpointTools && this.deps.gatewayClarify ? [createComputerUseTool({
 				runtime: this.ensureComputerRuntime(),
@@ -530,8 +532,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 			"xopc_tool_execute"
 		].some((name) => !disabled?.has(name))) {
 			const dataTools = () => {
-				const config = this.deps.getConfig?.();
-				const policies = config ? (currentConversationId() ? resolveEffectiveAgentConfigForSession(config, currentConversationId()) : resolveEffectiveAgentConfigForAgent(config, resolvedAgentId)).config.tools : void 0;
+				const policies = this.deps.getConfig?.() ? (currentConversationId() ? resolveEffectiveAgentConfigForSession(currentConversationId()) : resolveEffectiveAgentConfigForAgent(resolvedAgentId)).config.tools : void 0;
 				if (policies?.data_batch?.mode === "deny") return [];
 				return filterToolsByDisabledSet(core, disabled).filter((tool) => policies?.[tool.name]?.mode !== "deny");
 			};

package/dist/src/agent/tools/image-generate-tool.js

@@ -128,7 +128,7 @@ async function loadInputImages(params) {
 	return out;
 }
 function resolveImageGenerationModelConfigForTool(params) {
-	const explicit = params.cfg ? getAgentDefaultImageGenerationModelConfig(params.cfg, params.agentId) : void 0;
+	const explicit = params.cfg ? getAgentDefaultImageGenerationModelConfig(params.agentId) : void 0;
 	if (explicit?.primary?.trim()) {
 		const plan = buildCapabilityPlansForConfig(params.cfg)["image-generation"];
 		const primarySlash = explicit.primary.indexOf("/");

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

@@ -49,9 +49,8 @@ function createWorkflowTool(deps) {
 					details: { error: message }
 				};
 			}
-			const config = deps.getConfig();
 			const parentConversationId = deps.getCurrentConversationId?.()?.trim();
-			const agentId = extractProfileAgentId(parentConversationId, config);
+			const agentId = extractProfileAgentId(parentConversationId);
 			const goal = params.goal?.trim() || "";
 			const taskRunId = params.taskRunId?.trim();
 			const source = parentConversationId ? {
@@ -145,7 +144,7 @@ function resolveDefinitionId(params, catalog, config, conversationId) {
 		catalog.load(name);
 		return name;
 	}
-	const configuredDefault = config ? resolveEffectiveAgentProfileForSession(config, conversationId).config.workflows.default : void 0;
+	const configuredDefault = config ? resolveEffectiveAgentProfileForSession(conversationId).config.workflows.default : void 0;
 	if (configuredDefault) {
 		catalog.load(configuredDefault);
 		return configuredDefault;

package/dist/src/agent/tools/xopc-use-tool.d.ts

@@ -9,12 +9,12 @@ import { type ProjectService } from '../../projects/index.js';
 import type { LocalAppService } from '../../local-apps/index.js';
 import type { ChatPreviewService } from '../../chat-previews/index.js';
 declare const XopcUseToolSchema: import("@sinclair/typebox").TObject<{
-    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, import("@sinclair/typebox").TLiteral<"scene">, import("@sinclair/typebox").TLiteral<"project">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"note">, import("@sinclair/typebox").TLiteral<"task">, import("@sinclair/typebox").TLiteral<"task_run">, import("@sinclair/typebox").TLiteral<"local_app">, import("@sinclair/typebox").TLiteral<"chat_preview">, import("@sinclair/typebox").TLiteral<"settings">]>;
+    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, import("@sinclair/typebox").TLiteral<"scene">, import("@sinclair/typebox").TLiteral<"project">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"note">, import("@sinclair/typebox").TLiteral<"task">, import("@sinclair/typebox").TLiteral<"task_run">, import("@sinclair/typebox").TLiteral<"local_app">, import("@sinclair/typebox").TLiteral<"chat_preview">, import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"settings">]>;
     command: import("@sinclair/typebox").TString;
     args: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TAny>>;
     dryRun: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
-export type XopcUseMode = 'context' | 'scene' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'chat_preview' | 'local_app' | 'settings';
+export type XopcUseMode = 'context' | 'scene' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'chat_preview' | 'local_app' | 'agent' | 'settings';
 export interface XopcUseToolInput {
     mode: XopcUseMode;
     command: string;
@@ -36,6 +36,7 @@ export interface XopcUseToolDeps {
     getChatPreviewService?: () => ChatPreviewService | undefined;
     dispatchTaskEvents?: () => void;
     dispatchTaskRuns?: () => void;
+    onAgentCatalogMutate?: () => void;
 }
 type XopcUseDetails = {
     mode: XopcUseMode;

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

@@ -7,11 +7,11 @@ 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";
@@ -27,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"),
@@ -38,9 +39,10 @@ const XopcUseToolSchema = Type.Object({
 		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, chat_preview create/revise/get, 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." }))
 });
@@ -412,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 {
@@ -1211,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,
@@ -1638,7 +1686,7 @@ function createXopcUseTool(deps) {
 	return {
 		name: "xopc_use",
 		label: "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 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\" }).",
+		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",
@@ -2078,7 +2126,7 @@ 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) : mode === "chat_preview" ? await handleChatPreview(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)}`
 				});

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