@xopcai/xopc 0.0.426 → 0.0.428

package/dist/src/agent/tools/skill-install-tool.js

@@ -1,7 +1,16 @@
+import { init_connection, isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
+import { DurableState } from "../../storage/sqlite/durable-state.js";
 import { isSkillInstallTarget } from "../skills/install-target.js";
+import { createHash } from "node:crypto";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/skill-install-tool.ts
+init_connection();
 const SkillInstallSchema = Type.Object({
+	idempotencyKey: Type.Optional(Type.String({
+		minLength: 1,
+		maxLength: 200,
+		description: "Stable installation intent key. Keep the same key after a timeout; use a new key for a new install/update request."
+	})),
 	source: Type.Optional(Type.String({ description: "Explicit source install: Git URL, GitHub repository URL, https .zip/.tar.gz URL, file:// URL, or local archive/path." })),
 	provider: Type.Optional(Type.Union([
 		Type.Literal("store"),
@@ -21,7 +30,7 @@ function clean(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 function createSkillInstallTool(deps) {
-	return {
+	const tool = {
 		name: "skill_install",
 		label: "Install skill",
 		description: "Install an xopc skill from a Store/SkillHub/ClawHub marketplace result or an explicit source. Use only when the user clearly asks to install or update a skill; never treat search or a pasted URL as installation consent.",
@@ -146,6 +155,52 @@ function createSkillInstallTool(deps) {
 		idempotent: false,
 		finalGuardRelevant: true
 	};
+	const execute = tool.execute.bind(tool);
+	tool.execute = async (callId, params, signal, update) => {
+		if (!isXopcDatabaseOpen() || !deps.getConversationId?.()) return execute(callId, params, signal, update);
+		const key = clean(params.idempotencyKey) ?? callId;
+		const input = {
+			source: clean(params.source),
+			provider: clean(params.provider),
+			name: clean(params.name),
+			version: clean(params.version),
+			ref: clean(params.ref),
+			path: clean(params.path),
+			skillId: clean(params.skillId),
+			target: isSkillInstallTarget(params.target) ? params.target : "global",
+			force: params.force === true,
+			strictScan: params.strictScan === true
+		};
+		const fingerprint = createHash("sha256").update(JSON.stringify(input)).digest("hex");
+		const receipts = new DurableState("skills.install", deps.getConversationId());
+		const previous = receipts.update(key, (value) => ({
+			value: value ?? { fingerprint },
+			result: value
+		}));
+		if (previous) {
+			if (previous.fingerprint !== fingerprint) return {
+				content: [{
+					type: "text",
+					text: "Installation intent key was already used with different parameters."
+				}],
+				details: { errorCode: "intent_conflict" }
+			};
+			return previous.result ?? {
+				content: [{
+					type: "text",
+					text: "Installation result is not yet known. Inspect skill_manage status before taking further action; do not blindly reinstall or overwrite."
+				}],
+				details: { errorCode: "install_unknown" }
+			};
+		}
+		const result = await execute(callId, params, signal, update);
+		receipts.set(key, {
+			fingerprint,
+			result
+		});
+		return result;
+	};
+	return tool;
 }
 //#endregion
 export { createSkillInstallTool };

package/dist/src/agent/tools/skill-manage-tool.d.ts

@@ -4,5 +4,9 @@ export interface SkillManageToolDeps {
     getSkillManager: () => SkillManager | undefined;
     getWorkspace: () => string;
     onSkillsFilesystemMutate?: () => void;
+    getSkillIndexingContext?: () => {
+        registeredToolNames: string[];
+        skillAllowlist?: string[];
+    } | undefined;
 }
 export declare function createSkillManageTool(deps: SkillManageToolDeps): AgentTool;

package/dist/src/agent/tools/skill-manage-tool.js

@@ -1,6 +1,9 @@
 import { resolveStateDir } from "../../config/paths-state.js";
 import { init_paths } from "../../config/paths.js";
-import { createSkillConfigManager } from "../skills/config.js";
+import { removeSkillsLockEntry } from "../skills/hub-lock.js";
+import { hasBinary } from "../skills/installer.js";
+import { createSkillConfigManager, getSkillEnvironment, isSkillEnabled, resolveSkillConfig } from "../skills/config.js";
+import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "../skills/workspace-skills-dir.js";
 import { applyPatchToContent, atomicWriteUtf8, effectiveAgentWritePolicy, ensureCategorySegment, isPathInsideDir, maxSkillMdChars, maxSupportFileBytes, mutatableSkillOrNull, resolveCreateSkillDir, scanSkillDirOrError, validateSkillMdContent, validateSkillNameSegment, validateSupportingRelativePath } from "../skills/skill-manage-ops.js";
 import { join } from "path";
 import { existsSync, rmSync } from "fs";
@@ -10,6 +13,9 @@ import { Type } from "@sinclair/typebox";
 init_paths();
 const SkillManageSchema = Type.Object({
 	action: Type.Union([
+		Type.Literal("status"),
+		Type.Literal("enable"),
+		Type.Literal("disable"),
 		Type.Literal("create"),
 		Type.Literal("edit"),
 		Type.Literal("patch"),
@@ -40,7 +46,7 @@ function createSkillManageTool(deps) {
 	return {
 		name: "skill_manage",
 		label: "🛠️ Skill",
-		description: "Create, edit, patch, or delete user skills under ~/.xopc/skills and/or workspace .xopc/skills/ (see skills.agentWritePolicy). Also write_file / remove_file under references/, templates/, scripts/, assets/. Bundled and extra-dir skills cannot be modified. Runs a security scan after writes.",
+		description: "Inspect installed skills with status (including disabled skills and current Agent availability); enable or disable by name. Create, edit, patch, or delete/uninstall user skills under ~/.xopc/skills and/or workspace .xopc/skills/ (see skills.agentWritePolicy). Also write_file / remove_file under references/, templates/, scripts/, assets/. Bundled and extra-dir skills cannot be modified. Runs a security scan after writes.",
 		parameters: SkillManageSchema,
 		async execute(_toolCallId, params) {
 			const mgr = deps.getSkillManager();
@@ -56,6 +62,71 @@ function createSkillManageTool(deps) {
 			const notify = () => deps.onSkillsFilesystemMutate?.();
 			try {
 				switch (params.action) {
+					case "status":
+					case "enable":
+					case "disable": {
+						const requested = params.name?.trim();
+						if (params.action !== "status" && !requested) return jsonResult({
+							success: false,
+							error: "name is required."
+						});
+						const skill = requested ? mgr.findSkill(requested) : void 0;
+						if (requested && !skill) return jsonResult({
+							success: false,
+							error: "Skill is not installed.",
+							errorCode: "skill_not_found"
+						});
+						if (params.action !== "status") {
+							const enabled = params.action === "enable";
+							const manager = createSkillConfigManager(resolveStateDir());
+							manager.setSkillEnabled(requested, enabled);
+							if (manager.load().entries?.[requested]?.enabled !== enabled) return jsonResult({
+								success: false,
+								error: "Skill enabled state could not be saved."
+							});
+							mgr.refreshPromptFromConfig();
+							notify();
+						}
+						const config = createSkillConfigManager(resolveStateDir()).load();
+						const indexing = deps.getSkillIndexingContext?.();
+						const canLoad = !indexing || indexing.registeredToolNames.includes("skill_view");
+						const visible = new Set(canLoad ? mgr.getEnabledSkillsForAgentSession(indexing).map((item) => item.name) : []);
+						return jsonResult({
+							success: true,
+							skills: (skill ? [skill] : mgr.getSkills()).map((item) => {
+								const enabled = resolveSkillConfig(item, config).enabled !== false;
+								const requires = item.metadata.xopc?.requires ?? item.metadata.requires;
+								const environment = getSkillEnvironment(item, config);
+								const missingEnv = requires?.env?.filter((name) => !environment[name]) ?? [];
+								const anyBinsMissing = Boolean(requires?.anyBins?.length && !requires.anyBins.some(hasBinary));
+								const requirementsMet = !missingEnv.length && !anyBinsMissing && isSkillEnabled(item, {
+									...config,
+									entries: {
+										...config.entries,
+										[item.name]: {
+											...config.entries?.[item.name],
+											enabled: true
+										}
+									}
+								});
+								return {
+									name: item.name,
+									description: item.description,
+									source: item.source,
+									managed: item.origin?.managed === true,
+									writable: Boolean(mutatableSkillOrNull(item, workspace, policy)),
+									enabled,
+									requirementsMet,
+									missingEnv,
+									availableToCurrentAgent: requirementsMet && visible.has(item.name),
+									state: !enabled ? "disabled" : !requirementsMet ? "requirements_unmet" : !visible.has(item.name) ? "agent_unavailable" : "ready",
+									verified: false
+								};
+							}),
+							managementPath: "/capabilities/skills?tab=installed",
+							guidance: "Ready means the current Agent can load the skill, not that a task has been tested. After installation, load skill_view and complete the requested task; explain relevant examples and any remaining requirements. Enabling is shared by skill name."
+						});
+					}
 					case "create": {
 						const nameErr = validateSkillNameSegment(params.name ?? "", "name");
 						if (nameErr) return jsonResult({
@@ -246,6 +317,7 @@ function createSkillManageTool(deps) {
 							recursive: true,
 							force: true
 						});
+						removeSkillsLockEntry(name, isPathInsideDir(resolveWorkspaceSkillsDir(workspace), sk.baseDir) ? resolveWorkspaceSkillsLockPath(workspace) : void 0);
 						notify();
 						return jsonResult({
 							success: true,

package/dist/src/agent/tools/skills-tools.js

@@ -1,7 +1,7 @@
 import { resolveStateDir } from "../../config/paths-state.js";
 import { init_paths } from "../../config/paths.js";
-import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from "./truncate.js";
 import { createSkillConfigManager, isSkillEnabled, resolveSkillConfig } from "../skills/config.js";
+import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from "./truncate.js";
 import { resolveSkillReadablePath } from "../skills/skill-view-path.js";
 import { readFileSync, statSync } from "fs";
 import { Type } from "@sinclair/typebox";

package/dist/src/agent/tools/task-collaboration-tool.js

@@ -8,9 +8,9 @@ import { init_session_repository } from "../../storage/sqlite/session-repository
 import { TaskReadModelProjector } from "../../tasks/task-read-model-projector.js";
 import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 import { getEmbeddedExecutionSession } from "../embedded/execution-context.js";
+import { assertTaskHandoffAccess, assertTaskHandoffExecutorAccess, getTaskHandoff, materializeTaskHandoffFile, readTaskHandoffSource } from "../../tasks/task-handoff.js";
 import { TaskCollaborationRepository } from "../../tasks/task-collaboration-repository.js";
 import { taskResearchEvidence } from "../../tasks/task-research-result.js";
-import { assertTaskHandoffAccess, assertTaskHandoffExecutorAccess, getTaskHandoff, materializeTaskHandoffFile, readTaskHandoffSource } from "../../tasks/task-handoff.js";
 import { createXopcUseTool } from "./xopc-use-tool.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/task-collaboration-tool.ts

package/dist/src/agent/tools/tool-manual-tool.d.ts

@@ -1,7 +1,7 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
 declare const ToolManualSchema: import("@sinclair/typebox").TObject<{
     tool: import("@sinclair/typebox").TString;
-    topic: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"settings">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"connections">, import("@sinclair/typebox").TLiteral<"browser_setup">, import("@sinclair/typebox").TLiteral<"phone_setup">]>>;
+    topic: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"mcp">, import("@sinclair/typebox").TLiteral<"skills">, import("@sinclair/typebox").TLiteral<"agent">, import("@sinclair/typebox").TLiteral<"settings">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"connections">, import("@sinclair/typebox").TLiteral<"browser_setup">, import("@sinclair/typebox").TLiteral<"phone_setup">]>>;
 }>;
 export declare function createToolManualTool(): AgentTool<typeof ToolManualSchema, {}>;
 export {};

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

@@ -5,13 +5,15 @@ import { Type } from "@sinclair/typebox";
 const ToolManualSchema = Type.Object({
 	tool: Type.String({ description: "Built-in tool name, e.g. browser_use" }),
 	topic: Type.Optional(Type.Union([
+		Type.Literal("mcp"),
+		Type.Literal("skills"),
 		Type.Literal("agent"),
 		Type.Literal("settings"),
 		Type.Literal("automation"),
 		Type.Literal("connections"),
 		Type.Literal("browser_setup"),
 		Type.Literal("phone_setup")
-	], { description: "Focused xopc_use workflow; omit for the full parameter manual." }))
+	], { description: "Focused product workflow; omit for the full parameter manual." }))
 });
 function createToolManualTool() {
 	return {

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

@@ -12,6 +12,8 @@ const EAGER_CORE_TOOLS = new Set([
 	"skill_view",
 	"skills_list",
 	"tool_manual",
+	"mcp_setup",
+	"automation",
 	"publish_artifacts",
 	"task_collaboration",
 	"publish_task_result"

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

@@ -1,9 +1,9 @@
 import { appendProductDeliveryText } from "../../../packages/gateway-contract/src/product-delivery.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { fileResourceId, fileSpaceId } from "../../files/file-service.js";
 import { writeWorkspaceFile } from "../sandbox/fileAccess.js";
 import { checkFileSafety } from "../prompt/safety.js";
 import { isBareProfileMarkdownFileName, resolvePathUnderWorkspace, resolveProfileMarkdownPathIfBareName } from "./tool-paths.js";
-import { fileResourceId, fileSpaceId } from "../../files/file-service.js";
 import { basename, relative, sep } from "path";
 import { realpath } from "fs/promises";
 import { Type } from "@sinclair/typebox";

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

@@ -9,12 +9,12 @@ import type { LocalAppService } from '../../local-apps/index.js';
 import type { ChatPreviewService } from '../../chat-previews/index.js';
 import { TaskApplicationService } from '../../tasks/task-application-service.js';
 declare const XopcUseToolSchema: import("@sinclair/typebox").TObject<{
-    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, 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">, import("@sinclair/typebox").TLiteral<"browser_setup">, import("@sinclair/typebox").TLiteral<"phone_setup">]>;
+    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, 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">, import("@sinclair/typebox").TLiteral<"browser_setup">, import("@sinclair/typebox").TLiteral<"phone_setup">, import("@sinclair/typebox").TLiteral<"mcp_setup">]>;
     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' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'chat_preview' | 'local_app' | 'agent' | 'settings' | 'browser_setup' | 'phone_setup';
+export type XopcUseMode = 'context' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'chat_preview' | 'local_app' | 'agent' | 'settings' | 'browser_setup' | 'phone_setup' | 'mcp_setup';
 export interface XopcUseToolInput {
     mode: XopcUseMode;
     command: string;
@@ -22,9 +22,12 @@ export interface XopcUseToolInput {
     dryRun?: boolean;
 }
 export interface XopcUseToolDeps {
+    getAgentToolAvailability?: (agentId: string, tool: string) => import('../../agent-matching/service.js').AvailabilityCheck;
     canConfigureFromConversation?: () => boolean;
+    canRequestWeixinMcpSetup?: () => boolean;
     getPhoneSetupService?: () => import('../../phone/setup/service.js').PhoneSetupService | undefined;
     getBrowserSetupService?: () => import('../../browser/setup/service.js').BrowserSetupService | undefined;
+    getMcpSetupService?: () => import('../mcp/conversation-setup.js').McpConversationSetup | undefined;
     authorizeCapability?: CapabilityContext['authorize'];
     getWorkspace?: () => string;
     getConfig?: () => Config | undefined;

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

@@ -20,19 +20,21 @@ import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import { getAutomationSetup } from "../../automations/configuration-conversation.js";
 import { getEmbeddedExecutionRunId } from "../embedded/execution-context.js";
 import "../../capabilities/runtime/dispatcher.js";
+import { AutomationMcpSourceInput, prepareAutomationMcpSource } from "../../automations/mcp-source.js";
 import { resolveProjectAgentId } from "../../projects/project-agent.js";
-import "../../projects/index.js";
-import { TaskCollaborationRepository } from "../../tasks/task-collaboration-repository.js";
-import { defineTaskContract } from "../../tasks/task-contract-definition.js";
-import { resolveResponseLanguageForSession } from "../prompt/response-language.js";
 import { TaskDeletionService } from "../../tasks/task-deletion-service.js";
 import { TaskDeleteOutputSchema } from "../../tasks/capabilities/management.js";
+import "../../projects/index.js";
 import { parseTaskHandoffReferences } from "../../tasks/task-handoff.js";
+import { TaskCollaborationRepository } from "../../tasks/task-collaboration-repository.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
 import { AutomationCreateCapabilityInputSchema, AutomationUpdatePatchSchema } from "../../automations/capabilities/write.js";
+import { resolveResponseLanguageForSession } from "../prompt/response-language.js";
 import { TaskMutationOutputSchema } from "../../tasks/capabilities/write.js";
 import { createProductDispatcher } from "../../capabilities/runtime/product.js";
 import { localAppCapabilities } from "../../local-apps/capabilities/runtime.js";
+import { getDelegationScope } from "../orchestration/delegation-scope.js";
+import { defineTaskContract } from "../../tasks/task-contract-definition.js";
 import "../../tasks/index.js";
 import { randomUUID } from "node:crypto";
 import { Type } from "@sinclair/typebox";
@@ -53,9 +55,10 @@ const XopcUseToolSchema = Type.Object({
 		Type.Literal("agent"),
 		Type.Literal("settings"),
 		Type.Literal("browser_setup"),
-		Type.Literal("phone_setup")
+		Type.Literal("phone_setup"),
+		Type.Literal("mcp_setup")
 	]),
-	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 profile-only changes: patch_profile {id, expectedRevision, patch:{name?,description?,style?,language?,...}, idempotencyKey?} preserves omitted fields. Agent commands: list, get {id}, create {id, profile, workspace?, models?, skills?, tools?, 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 {}, events {eventType?, source?, limit?}, deliveries {runId?, limit?}, product_events {eventType, source?, payloadKey?, payloadValue?, limit?}; payload filters require both key and value. Recovery commands: replay_event {eventId, reason, idempotencyKey}, retry_delivery {runId, destinationKey, reason, idempotencyKey}. 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. 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: "HTTP MCP configuration: mode mcp_setup inspect/start/get/advance/cancel/set_enabled/remove; load tool_manual topic mcp. Never pass credentials or OAuth callbacks as tool arguments. 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 profile-only changes: patch_profile {id, expectedRevision, patch:{name?,description?,style?,language?,...}, idempotencyKey?} preserves omitted fields. Agent commands: list, get {id}, create {id, profile, workspace?, models?, skills?, tools?, 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 {}, events {eventType?, source?, limit?}, deliveries {runId?, limit?}, product_events {eventType, source?, payloadKey?, payloadValue?, limit?}; payload filters require both key and value. Recovery commands: replay_event {eventId, reason, idempotencyKey}, retry_delivery {runId, destinationKey, reason, idempotencyKey}. 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. 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." }))
 });
@@ -743,7 +746,7 @@ async function handleProject(command, args, deps, dryRun, capabilities) {
 		error: `Unsupported project command: ${command}`
 	};
 }
-async function handleAutomation(command, args, deps, dryRun, capabilities) {
+async function handleAutomation(command, args, deps, dryRun, capabilities, toolCallId) {
 	const automations = deps.getAutomationService?.();
 	if (!automations) return {
 		ok: false,
@@ -760,7 +763,7 @@ async function handleAutomation(command, args, deps, dryRun, capabilities) {
 		try {
 			return (operation === "xopc.automations.delete" ? AutomationDeleteOutputSchema : operation === "xopc.automations.cancel" ? AutomationCancelOutputSchema : operation === "xopc.automations.read" ? AutomationReadOutputSchema : operation === "xopc.automations.read_all" ? AutomationReadAllOutputSchema : operation === "xopc.automations.replay_event" || operation === "xopc.automations.retry_delivery" ? AutomationRecoveryOutputSchema : operation === "xopc.automations.run" || operation === "xopc.automations.rerun" ? AutomationRunMutationOutputSchema : AutomationMutationOutputSchema).parse(await capabilities.call(operation, input, caller, {
 				...capabilities.describe(operation, caller),
-				idempotencyKey: trimString(args.idempotencyKey) ?? randomUUID()
+				idempotencyKey: trimString(args.idempotencyKey) ?? toolCallId
 			}));
 		} catch (error) {
 			if (error instanceof CapabilityError) return {
@@ -1937,6 +1940,70 @@ function createXopcUseTool(deps) {
 				dryRun
 			};
 			if (!command) return errorText("command is required", details);
+			if (mode === "mcp_setup") {
+				const service = deps.getMcpSetupService?.();
+				const conversationId = deps.getCurrentConversationId?.();
+				const agentId = deps.getCurrentAgentId?.();
+				if (!service || !conversationId || !agentId) return errorText("MCP setup requires a Gateway conversation.", details);
+				if (deps.authorizeCapability && !await deps.authorizeCapability(`xopc.mcp_setup.${command}`, args)) return errorText("MCP setup access denied", details);
+				try {
+					return okText({
+						...details,
+						result: await service.command(command, args, {
+							conversationId,
+							agentId,
+							signal,
+							authorizeResearch: async (tool, params) => {
+								if (deps.getAgentToolAvailability?.(agentId, tool).state !== "verified") return false;
+								const scope = getDelegationScope(), current = scope?.getToolContext?.();
+								if (scope && !scope.tools.some((item) => item.name === tool)) return false;
+								if (scope?.authorizeToolCall) {
+									if (!current) return false;
+									if ((await scope.authorizeToolCall({
+										...current,
+										toolCall: {
+											type: "toolCall",
+											id: `${toolCallId}/research/${crypto.randomUUID()}`,
+											name: tool,
+											arguments: params
+										},
+										args: params
+									}, signal))?.block) return false;
+								}
+								return !deps.authorizeCapability || await deps.authorizeCapability(tool, params);
+							},
+							canConfigure: deps.canConfigureFromConversation?.() === true,
+							canRequestWeixinSetup: deps.canRequestWeixinMcpSetup?.() === true
+						}, dryRun)
+					});
+				} catch (error) {
+					return errorText(error instanceof Error ? error.message : String(error), details);
+				}
+			}
+			if (mode === "automation" && command === "prepare_source") {
+				const config = deps.getConfig?.();
+				if (!config || !deps.getWorkspace) return errorText("MCP source preparation is unavailable in this runtime.", details);
+				if (deps.authorizeCapability && !await deps.authorizeCapability("xopc.automations.prepare_source", args)) return errorText("Source preparation denied", details);
+				const input = AutomationMcpSourceInput.parse(args);
+				if (dryRun) return okText({
+					...details,
+					result: {
+						dryRun: true,
+						...input
+					}
+				});
+				return okText({
+					...details,
+					result: await prepareAutomationMcpSource(input, {
+						conversationId: deps.getCurrentConversationId?.(),
+						agentId: deps.getCurrentAgentId?.(),
+						canConfigure: deps.canConfigureFromConversation?.() === true,
+						workspaceDir: deps.getWorkspace(),
+						readConfig: () => deps.getConfig?.() ?? config,
+						signal
+					})
+				});
+			}
 			if (mode === "phone_setup") {
 				const service = deps.getPhoneSetupService?.();
 				const conversationId = deps.getCurrentConversationId?.();
@@ -1950,6 +2017,7 @@ function createXopcUseTool(deps) {
 							conversationId,
 							agentId,
 							canConfigure: deps.canConfigureFromConversation?.() === true,
+							isAuthorized: deps.canConfigureFromConversation,
 							runId: getEmbeddedExecutionRunId()
 						}, dryRun)
 					});
@@ -2155,7 +2223,10 @@ function createXopcUseTool(deps) {
 					payloadKey: args.payloadKey,
 					payloadValue: args.payloadValue,
 					limit: args.limit
-				} : { id: args.runId ?? args.id };
+				} : {
+					id: args.runId ?? args.id,
+					...command === "get_run" && args.waitMs !== void 0 ? { waitMs: args.waitMs } : {}
+				};
 				const caller = {
 					principalId: `agent:${deps.getCurrentAgentId?.() ?? "main"}`,
 					surface: "agent",
@@ -2315,7 +2386,7 @@ function createXopcUseTool(deps) {
 						kind: "xopc_use",
 						toolCallId
 					}
-				}, async () => 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) : {
+				}, async () => 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, toolCallId) : 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-catalog/service.d.ts

@@ -9,7 +9,7 @@ export declare class AgentCatalogService {
     resumePendingProvisioning(): Promise<void>;
     /** Startup recovery for catalog rows committed before their directories were provisioned. */
     resumePendingProvisioningSync(): void;
-    update(agentIdRaw: string, patch: Partial<Omit<AgentEntry, 'id'>>, expectedRevision?: number): Promise<StoredAgent>;
+    update(agentIdRaw: string, patch: Partial<Omit<AgentEntry, 'id'>>, expectedRevision?: number, beforeCommit?: () => void): Promise<StoredAgent>;
     /** Remove data for an Agent that has already been deleted from the catalog. */
     purgeEntryData(entry: AgentEntry, defaultAgentId: string): Promise<void>;
     validatePurgeEntry(entry: AgentEntry, defaultAgentId: string): void;

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

@@ -59,7 +59,7 @@ var AgentCatalogService = class {
 		}
 		this.resumePendingPurgeSync();
 	}
-	async update(agentIdRaw, patch, expectedRevision) {
+	async update(agentIdRaw, patch, expectedRevision, beforeCommit) {
 		const agentId = normalizeAgentId(agentIdRaw);
 		const current = this.repository.get(agentId);
 		if (!current) throw new Error(`Agent "${agentId}" not found`);
@@ -71,6 +71,7 @@ var AgentCatalogService = class {
 			id: agentId
 		};
 		await this.provision(next);
+		beforeCommit?.();
 		return this.repository.update(agentId, revision, next);
 	}
 	/** Remove data for an Agent that has already been deleted from the catalog. */

package/dist/src/automations/api/routes.js

@@ -70,8 +70,11 @@ function registerAutomationRoutes(authenticated, deps) {
 	});
 	authenticated.get("/api/automations", async (c) => {
 		try {
-			const { items } = ProductReadContracts["xopc.automations.list"].output.parse(await capabilities.call("xopc.automations.list", { projectId: parseProjectId(c.req.query("projectId")) }, capabilityHttpContext(c)));
-			return c.json({ automations: items });
+			const { items, executionSummaries } = ProductReadContracts["xopc.automations.list"].output.parse(await capabilities.call("xopc.automations.list", { projectId: parseProjectId(c.req.query("projectId")) }, capabilityHttpContext(c)));
+			return c.json({
+				automations: items,
+				executionSummaries
+			});
 		} catch (error) {
 			return capabilityHttpError(c, error);
 		}
@@ -129,12 +132,17 @@ function registerAutomationRoutes(authenticated, deps) {
 		const automationId = c.req.query("automationId")?.trim();
 		const projectId = parseProjectId(c.req.query("projectId"));
 		try {
-			const { items } = ProductReadContracts["xopc.automations.history"].output.parse(await capabilities.call("xopc.automations.history", {
+			const { items, nextCursor, hasMore } = ProductReadContracts["xopc.automations.history"].output.parse(await capabilities.call("xopc.automations.history", {
 				automationId: automationId || void 0,
-				projectId: automationId ? void 0 : projectId,
+				projectId,
+				cursor: c.req.query("cursor"),
 				limit: c.req.query("limit") === void 0 ? void 0 : Number(c.req.query("limit"))
 			}, capabilityHttpContext(c)));
-			return c.json({ runs: items });
+			return c.json({
+				runs: items,
+				nextCursor,
+				hasMore
+			});
 		} catch (error) {
 			return capabilityHttpError(c, error);
 		}

package/dist/src/automations/capabilities/drafts.js

@@ -7,7 +7,7 @@ import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import { ExternalEffectNotAppliedError } from "../../capabilities/runtime/external-operations.js";
 import { defineExternalCapability, defineReadCapability } from "../../capabilities/runtime/dispatcher.js";
-import { AutomationCreateCapabilityInputSchema } from "./write.js";
+import { AutomationCreateCapabilityInputSchema, materializeAutomationTrigger } from "./write.js";
 import { simulateAutomation } from "../draft/automation-draft-validator.js";
 import { AutomationDraftService } from "../draft/automation-draft-service.js";
 import "../draft/index.js";
@@ -39,7 +39,10 @@ function registerAutomationDraftCapabilities(dispatcher, service, getConfig) {
 		output: z.object({ simulation: AutomationSimulationSchema }),
 		execute(input) {
 			try {
-				return { simulation: simulateAutomation(input) };
+				return { simulation: simulateAutomation({
+					...input,
+					trigger: materializeAutomationTrigger(input.trigger)
+				}) };
 			} catch (error) {
 				throw new CapabilityError("INVALID_INPUT", error instanceof Error ? error.message : "Invalid automation");
 			}