@xopcai/xopc 0.0.332 → 0.0.334

package/dist/src/agent/external-tools/gateway-tools.js

@@ -1,6 +1,7 @@
 import { init_connector_repository, listConnectorConnections } from "../../storage/sqlite/connector-repository.js";
 import { connectionBindings, getActiveConnectionWait, init_connection_wait_repository, publishConnectionWait, requireSessionConnection, reviseCurrentConnectionObjective } from "../../storage/sqlite/connection-wait-repository.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
+import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
 import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
 import { parsePluginMcpCandidateRef, resolvePluginMcpConnectionCandidate } from "../../extensions/agent-plugins/connection.js";
 import { ExternalToolService } from "./service.js";
@@ -48,21 +49,32 @@ function textResult(value, details = {}) {
 		details
 	};
 }
-function createExternalToolGatewayTools(providers, getContext) {
+function createExternalToolGatewayTools(providers, getContext, getConfig) {
 	const service = new ExternalToolService(providers);
 	const searchTool = {
 		name: EXTERNAL_TOOL_NAMES.search,
 		label: "🔎 External Tool Search",
-		description: `Search external tools from these sources: ${EXTERNAL_TOOL_SOURCES.join(", ")}. CLI connectors include Feishu/Lark, WeCom and WPS 365. Omit sources unless intentionally restricting the search; do not guess a source list. Use concise English capability keywords, e.g. "wecom doc.search". Returns compact references only; call xopc_tool_describe before execution. If a source-filtered search finds no relevant tools, retry without sources before concluding a capability is unavailable or requesting a connection.`,
+		description: `Search external tools from these sources: ${EXTERNAL_TOOL_SOURCES.join(", ")}. CLI connectors include Feishu/Lark, WeCom and WPS 365. Omit sources unless intentionally restricting the search; do not guess a source list. Use concise English capability keywords, e.g. "wecom doc.search". Returns executable tools, connection candidates, or reviewed Store install candidates. Call xopc_tool_describe before executing a tool. When no executable tool exists but a connection or install candidate is returned, use xopc_require_connection instead of falling back to browser automation. If a source-filtered search finds no relevant tools, retry without sources before concluding a capability is unavailable.`,
 		parameters: ToolSearchSchema,
 		async execute(_toolCallId, params) {
 			const selectedSources = new Set(params.sources ?? []);
 			const excludedSources = selectedSources.size ? EXTERNAL_TOOL_SOURCES.filter((source) => !selectedSources.has(source)) : [];
 			const result = await service.search(params);
 			const candidates = [...result.connectionCandidates, ...connectionCandidates(params.query)].filter((candidate, index, all) => all.findIndex((item) => item.candidateRef === candidate.candidateRef) === index);
+			let installCandidates = [];
+			let installCatalogError;
+			const config = getConfig?.();
+			if (!params.sources?.length && result.tools.length === 0 && candidates.length === 0 && config) try {
+				installCandidates = await searchStoreConnectorInstallCandidates(config, params.query, params.limit ?? 5);
+			} catch (error) {
+				installCatalogError = error instanceof Error ? error.message : String(error);
+			}
 			return textResult({
 				...result,
 				connectionCandidates: candidates,
+				installCandidates,
+				...result.tools.length === 0 && (candidates.length > 0 || installCandidates.length > 0) ? { instruction: "The requested app is available but is not connected. Explain that connection is required, then call xopc_require_connection with an exact candidateRef from this result. Do not fall back to browser automation unless the user explicitly asked for browser use or skips the connection." } : {},
+				...installCatalogError ? { installCatalogError } : {},
 				...excludedSources.length ? { searchScope: {
 					excludedSources,
 					instruction: "This search excluded these sources. Results from other apps do not establish that the requested app is unavailable. Retry without sources before declaring a capability unavailable or requesting authorization. Feishu/Lark, WeCom and WPS 365 connectors use cli."
@@ -140,7 +152,7 @@ function createExternalToolGatewayTools(providers, getContext) {
 		name: EXTERNAL_TOOL_NAMES.requireConnection,
 		label: "Connect app",
 		parameters: requireSchema,
-		description: "Request the connections returned as connectionCandidates by xopc_tool_search. Explain the need once before calling. This pauses the current objective and displays one action area above the input. Never return OAuth URLs or repeat a skipped request. If another objective is waiting, ask the user to continue or cancel it first.",
+		description: "Request a connectionCandidates or installCandidates entry returned by xopc_tool_search. Explain the need once before calling. This pauses the current objective and displays one action area above the input. Never invent a candidate reference, return OAuth URLs, or repeat a skipped request. If another objective is waiting, ask the user to continue or cancel it first.",
 		async execute(_id, params) {
 			const context = getContext?.();
 			if (!context) throw new Error("No active conversation.");
@@ -152,10 +164,15 @@ function createExternalToolGatewayTools(providers, getContext) {
 			const selected = connectionBindings(context.conversationId);
 			if (params.requirements.every((item) => {
 				const pluginTarget = parsePluginMcpCandidateRef(item.candidateRef);
-				return selected.some((need) => need.target.type === "connector" ? need.target.connectorId === item.candidateRef && Boolean(need.connectionId) && (!item.accountId || item.accountId === need.accountId) && (!item.accountSelector || item.accountSelector === need.accountSelector) && listConnectorConnections({
-					principalId: principal.principalId,
-					connectorId: need.target.connectorId
-				}).some((connection) => connection.id === need.connectionId && connection.status === "active") : Boolean(pluginTarget && need.target.pluginId === pluginTarget.pluginId && need.target.serverName === pluginTarget.serverName && need.connectionId === need.target.serverId));
+				return selected.some((need) => {
+					if (need.target.type === "connector") return need.target.connectorId === item.candidateRef && Boolean(need.connectionId) && (!item.accountId || item.accountId === need.accountId) && (!item.accountSelector || item.accountSelector === need.accountSelector) && listConnectorConnections({
+						principalId: principal.principalId,
+						connectorId: need.target.connectorId
+					}).some((connection) => connection.id === need.connectionId && connection.status === "active");
+					if (need.target.type === "plugin-mcp") return Boolean(pluginTarget && need.target.pluginId === pluginTarget.pluginId && need.target.serverName === pluginTarget.serverName && need.connectionId === need.target.serverId);
+					const storeTarget = parseStoreConnectorCandidateRef(item.candidateRef);
+					return Boolean(storeTarget && need.target.packageName === storeTarget.packageName && need.target.version === storeTarget.version && need.connectionId);
+				});
 			})) return textResult({
 				status: "already_connected",
 				selectedConnections: selected,
@@ -167,9 +184,26 @@ function createExternalToolGatewayTools(providers, getContext) {
 				agentId: principal.agentId ?? "main",
 				summary: params.purpose,
 				checkpoint: params.checkpoint,
-				needs: params.requirements.map((item) => {
-					const need = resolvePluginMcpConnectionCandidate(item.candidateRef) ?? resolveConnectionCandidate(item.candidateRef);
-					if (item.accountId && need.target.type !== "connector") throw new Error("Plugin MCP connections do not support account selection.");
+				needs: await Promise.all(params.requirements.map(async (item) => {
+					const storeRef = parseStoreConnectorCandidateRef(item.candidateRef);
+					const config = getConfig?.();
+					const plan = storeRef && config ? await getStoreConnectorInstallPlan(config, storeRef.packageName, storeRef.version) : void 0;
+					if (plan && !plan.definition.provenance) throw new Error("Store Connector provenance is unavailable.");
+					const need = plan ? {
+						key: item.candidateRef,
+						target: {
+							type: "store-connector",
+							packageName: plan.packageName,
+							connectorId: plan.definition.id,
+							version: plan.version,
+							sha256: plan.definition.provenance.sha256,
+							reviewHash: plan.reviewHash,
+							description: plan.definition.description
+						},
+						label: plan.definition.displayName,
+						capabilities: plan.definition.capabilities
+					} : resolvePluginMcpConnectionCandidate(item.candidateRef) ?? resolveConnectionCandidate(item.candidateRef);
+					if (item.accountId && need.target.type !== "connector") throw new Error("This install candidate does not support account selection.");
 					if (item.accountId && need.target.type === "connector" && !listConnectorConnections({
 						principalId: principal.principalId,
 						connectorId: need.target.connectorId
@@ -180,7 +214,7 @@ function createExternalToolGatewayTools(providers, getContext) {
 						accountSelector: item.accountSelector,
 						key: need.target.type === "connector" ? `${need.target.connectorId}:${item.accountId ?? item.accountSelector ?? "default"}` : need.key
 					};
-				})
+				}))
 			});
 			publishConnectionWait(context.conversationId);
 			return textResult(result);

package/dist/src/agent/external-tools/index.js

@@ -53,7 +53,7 @@ function createDefaultExternalToolGatewayTools(deps) {
 		if (!deps.getConfig()) return void 0;
 		const conversationId = deps.getCurrentContext()?.conversationId;
 		return (conversationId ? resolveEffectiveAgentConfigForSession(conversationId) : deps.agentId ? resolveEffectiveAgentConfigForAgent(deps.agentId) : resolveEffectiveAgentConfigForSession(void 0)).config.tools[toolRef];
-	})), deps.getCurrentContext);
+	})), deps.getCurrentContext, deps.getConfig);
 }
 //#endregion
 export { EXTERNAL_TOOL_NAMES, ExternalToolService, createDefaultExternalToolGatewayTools };

package/dist/src/agent/image/tool-model-config.js

@@ -1,7 +1,7 @@
-import { getAgentDefaultImageModelConfig, getAgentDefaultModelRef, init_schema, parseModelRef } from "../../config/schema.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
-import { resolveEffectiveAgentConfigForAgent } from "../../config/agent-profile.js";
+import { getAgentDefaultImageModelConfig, getAgentDefaultModelRef, init_schema, parseModelRef } from "../../config/schema.js";
 import { getDefaultModelSync, getModelsByProvider, init_providers, isProviderConfiguredSync, resolveModel } from "../../providers/index.js";
+import { resolveEffectiveAgentConfigForAgent } from "../../config/agent-profile.js";
 import { resolveAgentModelFallbackValues, resolveAgentModelPrimaryValue } from "../../config/model-input.js";
 import { buildCapabilityPlansForConfig } from "../../capabilities/readiness/from-config.js";
 import "../../capabilities/readiness/index.js";

package/dist/src/agent/image/understanding/pi-ai-provider.js

@@ -50,7 +50,7 @@ function buildPiAiImageUnderstandingProvider(providerId) {
 							setTimeout(() => controller.abort(), timeoutMs);
 							return controller.signal;
 						})()
-					}),
+					}, void 0, { operation: "media.understand_image" }),
 					provider: providerId,
 					model: modelId
 				}),

package/dist/src/agent/memory/compaction.js

@@ -518,6 +518,10 @@ Return a JSON delta containing only missing facts, using {"upserts":[]}. Include
 						onPayload: compactionPayloadGuard(requestedMaxTokens, (actual) => {
 							actualMaxTokens = actual;
 						})
+					}, void 0, {
+						operation: "session.compact",
+						conversationId: callContext.conversationId,
+						trigger: attempt === 0 && modelIndex === 0 ? "system" : "retry"
 					});
 					parentSignal?.throwIfAborted();
 					if (linked.timedOut()) throw new CompactionRequestError("timeout", "Compaction handover timed out");

package/dist/src/agent/service/btw-query.js

@@ -108,7 +108,10 @@ async function runBtwQuery(opts) {
 		};
 		let streamedText = "";
 		const response = opts.onTextDelta ? await (async () => {
-			const stream = await createResolvedModelStream(model, { messages: [userMessage] }, modelCallOptions, opts.credentialOptions);
+			const stream = await createResolvedModelStream(model, { messages: [userMessage] }, modelCallOptions, opts.credentialOptions, {
+				operation: "agent.answer",
+				conversationId: opts.conversationId
+			});
 			for await (const event of stream) {
 				const streamEvent = event;
 				if (streamEvent.type === "text_delta" && typeof streamEvent.delta === "string") {
@@ -123,7 +126,10 @@ async function runBtwQuery(opts) {
 				}
 			}
 			return await stream.result();
-		})() : await completeWithResolvedCredentials(model, { messages: [userMessage] }, modelCallOptions, opts.credentialOptions);
+		})() : await completeWithResolvedCredentials(model, { messages: [userMessage] }, modelCallOptions, opts.credentialOptions, {
+			operation: "agent.answer",
+			conversationId: opts.conversationId
+		});
 		const text = (streamedText || textFromCompleteContent(response.content)).trim();
 		if (text) return { text };
 		const stopReason = typeof response.stopReason === "string" ? response.stopReason : void 0;

package/dist/src/agent/service/process-direct-streaming.js

@@ -13,6 +13,7 @@ import { formatAgentRunErrorForClient } from "../client-error-format.js";
 import { resolveConfiguredActivityDetailDefault, resolveEffectiveReasoningLevel } from "../../session/thinking-resolve.js";
 import { initSessionTurn } from "../../session/init-session-turn.js";
 import "../../session/index.js";
+import { stripEnvelopeTimestampPrefix } from "../../channels/envelope-timestamp.js";
 import { isVoiceLikeAttachment, mergeVoiceTranscriptsIntoUserText, requestsOriginalVoiceInspection } from "../../channels/attachments/voice-stt-webchat.js";
 import { applyReasoningVisibility } from "../streaming/reasoning-visibility.js";
 import { isSessionSourceBinding, summarizeSourceContext } from "../source-context/types.js";
@@ -248,8 +249,9 @@ async function* runProcessDirectStreaming(deps, input) {
 					if (sourceContext && !sourceContexts.some((context) => context.kind === sourceContext.kind && context.sourceId === sourceContext.sourceId)) sourceContexts.push(sourceContext);
 				}
 			}
-			const userTurnDocument = parseUserTurnDocument(mergedUserText);
-			const authoredText = userTurnDocument ? renderUserTurnDocument(userTurnDocument, (refId) => sourceContexts.find((context) => context.refId === refId)?.title ?? null) : mergedUserText;
+			const modelUserTurnDocument = parseUserTurnDocument(mergedUserText);
+			const userTurnDocument = parseUserTurnDocument(stripEnvelopeTimestampPrefix(mergedUserText));
+			const authoredText = modelUserTurnDocument ? renderUserTurnDocument(modelUserTurnDocument, (refId) => sourceContexts.find((context) => context.refId === refId)?.title ?? null) : mergedUserText;
 			const slash = await tryRunSlashCommand(deps, {
 				conversationId,
 				channel,

package/dist/src/agent/service.js

@@ -1,19 +1,19 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { init_attachment_ref, parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
-import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
-import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
+import { extractTextContent } from "./context/workspace.js";
+import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
-import { extractProfileAgentId } from "../config/agent-profile.js";
 import { init_providers, resolveModel } from "../providers/index.js";
-import { extractTextContent } from "./context/workspace.js";
+import { applyConfigOverrides } from "../config/runtime-overrides.js";
+import { extractProfileAgentId } from "../config/agent-profile.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
 import { getProjectForSession } from "../projects/workspace.js";
 import { runWithEmbeddedExecutionSession } from "./embedded/execution-context.js";
-import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "./skills/workspace-skills-dir.js";
 import { removeSkillsLockEntry } from "./skills/hub-lock.js";
 import { installSkillFromZip } from "./skills/managed-store.js";
+import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "./skills/workspace-skills-dir.js";
 import { pullSkillFromSource } from "./skills/hub-pull.js";
 import { getUserTimezone } from "../user-model/repository.js";
 import "../user-model/index.js";

package/dist/src/agent/session/session-inspector.js

@@ -1,8 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_workspace_defaults, resolveDefaultAgentWorkspaceDir } from "../../config/workspace-defaults.js";
-import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { init_providers, resolveModel } from "../../providers/index.js";
+import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { getExecutionEnvironmentForSession } from "../../execution-environments/subject.js";
 import { effectiveWorkspacePathForSession, projectWorkspacePath } from "../../session/session-workspace.js";
 import { getProjectForSession } from "../../projects/workspace.js";

package/dist/src/agent/skills/filesystem-watcher.js

@@ -2,10 +2,10 @@ import { resolveStateDir } from "../../config/paths-state.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_paths, resolveSkillsDir } from "../../config/paths.js";
+import { isManagedSkillTransientDirName } from "./managed-store.js";
 import { createSkillConfigManager } from "./config.js";
 import { resolveWorkspaceSkillsDir } from "./workspace-skills-dir.js";
 import { resolveAgentsSkillsDir, resolveWorkspaceAgentsSkillsDir } from "./skill-sources.js";
-import { isManagedSkillTransientDirName } from "./managed-store.js";
 import path from "node:path";
 import chokidar from "chokidar";
 //#region src/agent/skills/filesystem-watcher.ts

package/dist/src/agent/skills/hub-pull.js

@@ -1,8 +1,8 @@
 import { parseFrontmatter } from "../../markdown/frontmatter.js";
-import { formatScanSummary, scanSkillDirectory } from "./scanner.js";
-import { computeSkillTreeHashSync } from "./hub-hash.js";
 import { getSkillsLockEntry, recordSkillsHubInstall } from "./hub-lock.js";
 import { installSkillFromZip, isIgnorableZipEntry, isValidSkillId, prepareManagedSkillTempDir, promoteManagedSkillTempDir } from "./managed-store.js";
+import { formatScanSummary, scanSkillDirectory } from "./scanner.js";
+import { computeSkillTreeHashSync } from "./hub-hash.js";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, normalize, resolve, sep } from "node:path";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";

package/dist/src/agent/skills/marketplace/adapters/store/adapter.js

@@ -1,6 +1,6 @@
+import { downloadSkillZipBuffer, fetchMarketplacePackageDetail, listSkillCategories, listSkillPackages, resolveSkillZipDownloadUrl, resolveSkillsStoreBaseUrl, skillIdForMarketplaceInstall, verifyStoreArtifactSha256 } from "./store-api-client.js";
 import { registerMarketplaceAdapter } from "../../registry.js";
 import { buildSkillMarkdownPreviewFromRaw } from "../../../skill-markdown-preview-from-raw.js";
-import { downloadSkillZipBuffer, fetchMarketplacePackageDetail, listSkillCategories, listSkillPackages, resolveSkillZipDownloadUrl, resolveSkillsStoreBaseUrl, skillIdForMarketplaceInstall, verifyStoreArtifactSha256 } from "./store-api-client.js";
 //#region src/agent/skills/marketplace/adapters/store/adapter.ts
 const storeMarketplaceAdapter = {
 	id: "store",

package/dist/src/agent/skills/marketplace/adapters/store/store-api-client.js

@@ -1,6 +1,6 @@
 import { init_resolution, resolveConnectedPlatformEndpoint } from "../../../../../platform/resolution.js";
-import { MAX_SKILL_ZIP_BYTES, isValidSkillId } from "../../../managed-store.js";
 import { MAX_EXTENSION_STORE_ZIP_BYTES } from "../../../../../extensions/store-zip-limits.js";
+import { MAX_SKILL_ZIP_BYTES, isValidSkillId } from "../../../managed-store.js";
 import { createHash } from "node:crypto";
 //#region src/agent/skills/marketplace/adapters/store/store-api-client.ts
 /**

package/dist/src/agent/tasks/task-judge-service.js

@@ -2,13 +2,13 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { TaskRepository, init_task_repository } from "../../tasks/task-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "../../tasks/task-run-repository.js";
+import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../../providers/model-response.js";
 import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
-import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { getApiKey, init_providers, resolveModel } from "../../providers/index.js";
+import { completeWithResolvedCredentials } from "../../providers/model-call.js";
+import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 import { readWorkspaceRevision } from "../coding/workspace-revision.js";
-import { completeWithResolvedCredentials } from "../../providers/model-call.js";
-import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../../providers/model-response.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
 //#region src/agent/tasks/task-judge-service.ts
 init_schema();
@@ -136,6 +136,10 @@ var TaskJudgeService = class {
 				apiKey,
 				maxTokens: 900,
 				temperature: 0
+			}, void 0, {
+				operation: "task.judge_result",
+				conversationId: payload.conversationId,
+				runId: run.id
 			});
 			const modelError = getAssistantMessageErrorReason(response);
 			if (modelError) throw new Error(modelError);

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

@@ -1 +1 @@
-export declare const xopcUseManual = "# XOPC Use Tool Manual\n\n## Purpose\n\n`xopc_use` operates first-class XOPC product objects without editing SQLite or product files directly.\nLoad this manual before a non-trivial mutation.\n\n```json\n{\n  \"mode\": \"agent | scene | project | automation | note | task | task_run | chat_preview | local_app | settings\",\n  \"command\": \"...\",\n  \"args\": {},\n  \"dryRun\": false\n}\n```\n\nSend one object command per call. Inspect the returned JSON `ok` field; a tool call can\ncomplete successfully while the product command returns `ok: false`.\n\n## Scene delegation\n\nUse mode `scene` only after the user explicitly delegates recurring or future work. Inspect\n`list` before `start`; configure an existing matching scene instead of creating a duplicate.\nConfirm the goal, source scope, timing, promised result, and read-only action boundary in ordinary\nlanguage. A scene prepares suggestions or drafts and never sends mail or performs external writes.\n\n## Object routing\n\n| Object | Tool |\n| --- | --- |\n| Agent definition and default Agent | `xopc_use` mode `agent` |\n| Scene and scene result | `xopc_use` mode `scene` |\n| Project, milestone, project update | `xopc_use` mode `project` |\n| Automation | `xopc_use` mode `automation` |\n| Task intent and lifecycle | `xopc_use` mode `task` |\n| Task execution attempt, receipt, events and waits | `xopc_use` mode `task_run` |\n| Note | `xopc_use` mode `note` |\n| Lightweight UI preview | `xopc_use` mode `chat_preview` |\n| Local app | `xopc_use` mode `local_app` |\n| Settings jump target | `xopc_use` mode `settings` |\n| Workflow run | dedicated `workflow` tool; pass `taskId` to link it to a Task |\n| Session, memory, skill, connected app or workspace file | its dedicated tool |\n\nDo not emulate Workflow APIs through `xopc_use`. A Task is durable intent;\na TaskRun is one execution attempt; a WorkflowRun is a procedure execution and may belong\nto a TaskRun. Never treat these three objects as interchangeable.\n\n## Agents\n\nCommands: `list`, `get`, `create`, `update`, `set_default`, `disable`,\n`delete`, and `purge`.\n\nAn Agent profile accepts only `name` and optional `instructions`. Put personality,\nlanguage, role, and behavioral guidance in `profile.instructions`; do not invent profile\nfields such as `description`, `language`, `emoji`, or `creature`.\n\n```json\n{\n  \"mode\": \"agent\",\n  \"command\": \"create\",\n  \"args\": {\n    \"id\": \"xiaomei\",\n    \"profile\": {\n      \"name\": \"\u5C0F\u7F8E\",\n      \"instructions\": \"\u4F7F\u7528\u4E2D\u6587\u4EA4\u6D41\uFF0C\u8BED\u6C14\u6E29\u67D4\u3001\u4EB2\u5207\u3001\u53EF\u7231\uFF0C\u540C\u65F6\u4FDD\u6301\u56DE\u7B54\u6E05\u6670\u53EF\u9760\u3002\"\n    },\n    \"idempotencyKey\": \"create-agent-xiaomei\"\n  }\n}\n```\n\nUse `list` before creating an Agent so an existing id is updated rather than duplicated.\nMutations other than `create` require the current `expectedRevision`; `set_default` uses\nthe catalog revision returned by `list`. `delete` preserves on-disk data, while `purge`\nalso removes it. Use `dryRun: true` to validate the exact same input contract without writing.\n\n## Reliable protocol\n\n1. Use `list` then `get` when an id is unknown.\n2. Read the current `version` before a Task mutation.\n3. Use `dryRun: true` for broad Project changes or uncertain mutations.\n4. Mutate once with the exact id and current concurrency token.\n5. Verify the returned object and preserve any \u201COpen in xopc\u201D delivery link.\n6. On a conflict, read again and reconsider the operation; do not blindly retry.\n\nTimestamps are Unix epoch milliseconds. Array fields are arrays of strings. Omission\npreserves a patchable field; an empty array intentionally clears it. Prefer explicit\n`projectId`, `taskId`, `runId`, `noteId`, and `localAppId` fields over `id`.\n\n## Scenes\n\nCommands: `templates`, `list`, `get`, `mail_accounts`, `mail_search`,\n`mail_sources`, `read_notes`, `preflight`, `start`, `configure`, `transition`,\n`check`, `notes`, `work_item`, `update_work_item`, `schedule`, `results`,\n`feedback`, `mark_read`, `diagnostics`, `get_preferences`, and `set_preferences`.\n\nThe built-in templates are `weekly-family-plan` and `mail-follow-up`, currently version\n`1.0.0`. Discover templates instead of guessing keys or versions. Timestamps are Unix epoch\nmilliseconds. Use `preflight` or `dryRun: true` before `start` when account or model readiness\nis uncertain.\n\n### Safe start protocol\n\n1. Call `list` and reuse a matching activation when one exists.\n2. Call `templates`; for mail, call `mail_accounts` and `mail_search` with the exact account.\n3. Explain the selected source and timing to the user before creating the scene.\n4. Call `preflight` with the complete start input.\n5. Call `start` with the same input and a stable `requestId` for retry safety.\n6. Add notes, a work item, or a schedule as required; then call `get` to verify the state.\n\nFamily plans use scope `{ \"kind\": \"personal\" }` and permissions with only\n`user_notes`. Mail follow-up uses one selected mail source in an objects scope and exactly one\nauthorized account. Never broaden either scope to make preflight pass.\n\n### Mutations and results\n\nRead the current activation `revision` before `configure` or `transition`. Read the current\nnotes, schedule, work-item, or feedback revision before changing that object. On a conflict,\nread again and reconsider; do not retry with a guessed revision.\n\n`check` queues work and does not mean a result already exists. Use a stable `requestId` and\ninspect `results` later. `no_change` intentionally creates no user-facing draft. A returned\ndraft is not a sent message. Use `diagnostics` for source, model, queue, or notification failures.\n\nScene preferences control checks and reminders globally for the current principal. Read them\nwith `get_preferences` before `set_preferences`; preserve fields the user did not ask to change.\n\n## Projects\n\nCommands: `list`, `get`, `create`, `update`, `resolve_workspace`,\n`list_milestones`, `create_milestone`, `update_milestone`, `list_updates`,\nand `create_update`.\n\nProject statuses: `planned`, `active`, `paused`, `completed`, `cancelled`,\n`archived`. Health values: `unknown`, `on_track`, `at_risk`, `off_track`.\n\nA Project defines bounded shared context for related work. Its durable planning fields are `outcome`,\n`successCriteria`, `scope`, `nonGoals`, `ownerId`, `targetAt`, and `health`.\nUse `brief` for a concise description and `instructions` for durable operating guidance.\n\n### Create\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"AI Product Research\",\n    \"outcome\": \"Choose a validated product direction\",\n    \"successCriteria\": [\"Ten customer interviews\", \"Decision recorded\"],\n    \"scope\": { \"market\": \"developer tools\" },\n    \"nonGoals\": [\"Build the production product\"],\n    \"health\": \"on_track\",\n    \"targetAt\": 1760000000000,\n    \"workspaceRoot\": \"/path/to/repo\"\n  }\n}\n```\n\n### Update\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"status\": \"active\",\n    \"health\": \"at_risk\",\n    \"successCriteria\": [\"Ten interviews\", \"Evidence-backed decision\"]\n  }\n}\n```\n\n### Resolve a workspace\n\nUse `autoCreate: false` for lookup. Set it to true only when creating a Project is authorized.\n\n```json\n{ \"mode\": \"project\", \"command\": \"resolve_workspace\", \"args\": { \"workspacePath\": \"/path/to/repo\", \"autoCreate\": false } }\n```\n\n### Milestones\n\nMilestone statuses: `planned`, `active`, `completed`, `cancelled`.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_milestone\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"title\": \"Finish discovery\",\n    \"status\": \"active\",\n    \"targetAt\": 1760000000000,\n    \"sortOrder\": 10\n  }\n}\n```\n\nUse `list_milestones` with `projectId`. Use `update_milestone` with both\n`projectId` and `milestoneId`. Milestone deletion is intentionally not exposed.\n\n### Immutable project updates\n\nProject updates are append-only progress snapshots. They also update Project health.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"health\": \"on_track\",\n    \"summary\": \"Discovery is complete\",\n    \"progress\": [\"Interviewed ten users\"],\n    \"risks\": [\"Pricing remains unvalidated\"],\n    \"nextSteps\": [\"Run pricing tests\"]\n  }\n}\n```\n\nUse `list_updates` with `projectId` and optional `limit`. Updates cannot be edited.\n\n## Automations\n\nCommands: `list`, `get`, `create`, `update`, `delete`, `run`, `pause`,\n`resume`, and `history`.\n\nAutomation `create` automatically uses the current session Project when `projectId` is\nomitted. An explicit `projectId` takes precedence and is validated before mutation. Use an\nexplicit id when creating for a Project other than the current session Project.\n\n### Create in the current Project\n\n`trigger` and `action` use the same shapes as the Automation product API.\n\n```json\n{\n  \"mode\": \"automation\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"Daily project review\",\n    \"trigger\": { \"kind\": \"schedule\", \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 9 * * 1-5\", \"tz\": \"Asia/Shanghai\" } },\n    \"action\": { \"kind\": \"agent\", \"instruction\": \"Review the current project and summarize risks.\" }\n  }\n}\n```\n\nTo override the inherited Project, add `\"projectId\": \"project_id\"` to `args`.\nThe create payload may also be nested under `args.automation`; top-level `args.projectId`\nhas precedence.\n\n### List and history\n\n`list` and unqualified `history` inherit the current session Project. Pass an explicit\n`projectId` to query another Project. Pass `automationId` to `history` for one Automation.\n\n### Update and operate\n\nUse `automationId` for `get`, `update`, `delete`, `run`, `pause`, and `resume`.\nFor `update`, patch fields may be direct args or nested under `args.patch`. Supplying a new\n`projectId` reassigns the Automation after validating the target Project.\n\n## Tasks\n\nCommands: `list`, `get`, `create`, `update_dependencies`, `add_context`,\n`remove_context`, `command`, and `delete`.\n\nTask phases are `backlog`, `ready`, `active`, `review`, and `closed`.\nOperational state is projected separately as `idle`, `queued`, `running`, `waiting`,\n`verifying`, `succeeded`, `failed`, or `cancelled`. Never send either value as a\nfree-form status update.\n\n`task.get` returns the Task, its projected `model`, dependencies, dependents, context,\nauthority grants, TaskRuns, receipts, and waits.\nThe projected model is the correct source for current operational state and attention items.\n\n`delete` permanently removes the Task and its contracts, waits, context links, TaskRuns,\nreceipts, and Task-owned execution records. It does not delete linked Sessions, workspace files,\nor external artifacts. Cancel an active TaskRun before deletion, and use `dryRun: true` when\nthe user's intent is ambiguous.\n\n```json\n{ \"mode\": \"task\", \"command\": \"delete\", \"args\": { \"taskId\": \"task_id\" }, \"dryRun\": true }\n```\n\n### Capture or start\n\n`createMode` defaults to `capture`, which creates a backlog Task without executing it.\nUse `start` only when immediate execution is intended.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"create\",\n  \"args\": {\n    \"objective\": \"Complete the customer research report\",\n    \"projectId\": \"project_id\",\n    \"createMode\": \"capture\",\n    \"priority\": \"high\",\n    \"expectedOutputs\": [\"Research report\"],\n    \"acceptanceCriteria\": [\"Sources are cited\"],\n    \"constraints\": [\"Do not contact customers without approval\"],\n    \"dependsOnTaskIds\": []\n  }\n}\n```\n\n### Dependencies\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"update_dependencies\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"dependsOnTaskIds\": [\"dependency_task_id\"]\n  }\n}\n```\n\n### Context links\n\nUse `add_context` to link a document, file, URL, session, memory, Task, artifact, or source\nas `input`, `reference`, `constraint`, `deliverable`, or `evidence` context.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"add_context\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"targetKind\": \"file\",\n    \"targetId\": \"/path/to/spec.md\",\n    \"role\": \"input\",\n    \"title\": \"Product specification\",\n    \"pinned\": true,\n    \"retrievalPolicy\": {},\n    \"metadata\": {}\n  }\n}\n```\n\nUse `remove_context` with `taskId` and the exact `edgeId` returned by `task.get`.\nDo not add authority grants through this tool; an Agent must not authorize itself.\n\n### Typed lifecycle commands\n\nEvery command requires `taskId`, the Task's current `expectedVersion`, a `type`, and\ntype-specific fields inside `commandArgs`.\n\nSupported command types:\n\n- `mark_ready`\n- `start`: `{ \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" } }`\n- `request_review`\n- `close`: `{ \"resolution\": \"done | cancelled | duplicate | wont_do\" }`\n- `reopen`: `{ \"phase\": \"ready | active\" }`\n- `add_wait`: `{ \"wait\": { \"kind\": \"dependency | approval | input | schedule | external | paused\", \"reason\": \"...\", \"condition\": {} } }`\n- `resolve_wait`: `{ \"waitId\": \"wait_id\", \"resolution\": {} }`\n- `delegate`: `{ \"agentId\": \"agent_id\" }`\n- `revise_contract`: `{ \"contract\": { ...complete contract... } }`\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"command\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"type\": \"start\",\n    \"commandArgs\": {\n      \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" }\n    }\n  }\n}\n```\n\nContract revision is replacement, not a patch. Read the Task and preserve all contract fields\nthe user did not ask to change. Resolve a wait through `resolve_wait`; do not directly mutate\na TaskRun or manufacture a phase transition.\n\n## TaskRuns\n\nTaskRun inspection is read-only except for explicit cancellation. Other execution state is\ncontrolled by Task commands and the runtime coordinator.\n\n### List attempts for a Task\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"list\", \"args\": { \"taskId\": \"task_id\", \"limit\": 20 } }\n```\n\nThe result contains run attempts, finalized receipts, and active waits.\n\n### Inspect one attempt\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"get\", \"args\": { \"runId\": \"run_id\" } }\n```\n\nThe result contains the TaskRun, its receipt when terminal, ordered events, and active Task waits.\n\n### Cancel an attempt\n\nRead the run first, then pass its current version. Cancellation creates a terminal receipt.\n\n```json\n{\n  \"mode\": \"task_run\",\n  \"command\": \"cancel\",\n  \"args\": { \"runId\": \"run_id\", \"expectedVersion\": 2, \"reason\": \"User cancelled execution\" }\n}\n```\n\nDo not guess commands such as retry, force-complete, heartbeat, or transition; they are not Agent APIs.\n\n## Notes\n\nCommands: `list`, `get`, `create`, `append`, `preview_edit`, `update`, and `delete`.\nUse Notes for durable prose and reference material, not as a Task substitute. Prefer `append`\nwhen preserving user content. Use `preview_edit` before a canonical rewrite.\n\n```json\n{ \"mode\": \"note\", \"command\": \"create\", \"args\": { \"title\": \"Decision\", \"markdown\": \"...\", \"projectId\": \"project_id\" } }\n```\n\n```json\n{ \"mode\": \"note\", \"command\": \"append\", \"args\": { \"noteId\": \"note_id\", \"heading\": \"AI synthesis\", \"content\": \"...\" } }\n```\n\nUse `update` with `status: \"trashed\"` for a recoverable removal. `delete` permanently\nremoves the Note and its stored snapshots and media; use `dryRun: true` first when the\nuser's intent is ambiguous.\n\n```json\n{ \"mode\": \"note\", \"command\": \"delete\", \"args\": { \"noteId\": \"note_id\" }, \"dryRun\": true }\n```\n\n## Chat previews, local apps, and settings\n\nUse `chat_preview` by default when the user asks to design, mock up, or quickly show a UI in\nthe current conversation. It creates no Project and no Local App. Commands are `create`,\n`get`, and `revise`. Source consists of `markup`, `styles`, and optional `script`;\ndo not include a full HTML document or remote dependencies. Revision requires the exact\n`baseRevision` returned by the prior call.\n\nUse `local_app` only when the user explicitly asks for a durable, installable app or chooses\n\u201CSave as app\u201D on a chat preview. Do not create a Local App merely to render a UI draft.\n\nLocal app commands are `list`, `get`, `create`, and `validate`. Installation,\nactivation, rollback, and uninstall remain product runtime operations.\n\nSettings supports only `open` and returns an exact product jump target without changing config.\n\n## Error recovery\n\n| Result | Recovery |\n| --- | --- |\n| service unavailable | Stop retrying and report the unavailable capability. |\n| not found | Re-list in the intended scope; do not invent another id. |\n| conflict | Read the current object and reassess using its latest version. |\n| waiting | Inspect the Task projection and TaskRun waits; resolve only the real blocker. |\n| invalid command or state | Read the object and use only a documented transition. |\n| unsupported operation | Use the dedicated tool or product UI; never write storage directly. |\n\n## Deliberate boundaries\n\n- Project deletion and milestone deletion are not Agent APIs.\n- TaskRun mutation is internal to execution coordination except for optimistic cancellation.\n- Project updates are immutable.\n- Workflow and Automation operations remain in their dedicated tools.\n- Only the documented Task and TaskRun commands are valid; do not infer hidden aliases.\n";
+export declare const xopcUseManual = "# XOPC Use Tool Manual\n\n## Purpose\n\n`xopc_use` operates first-class XOPC product objects without editing SQLite or product files directly.\nLoad this manual before a non-trivial mutation.\n\n```json\n{\n  \"mode\": \"agent | scene | project | automation | note | task | task_run | chat_preview | local_app | settings\",\n  \"command\": \"...\",\n  \"args\": {},\n  \"dryRun\": false\n}\n```\n\nSend one object command per call. Inspect the returned JSON `ok` field; a tool call can\ncomplete successfully while the product command returns `ok: false`.\n\n## Scene delegation\n\nUse mode `scene` only after the user explicitly delegates recurring or future work. Inspect\n`list` before `start`; configure an existing matching scene instead of creating a duplicate.\nConfirm the goal, source scope, timing, promised result, and read-only action boundary in ordinary\nlanguage. A scene prepares suggestions or drafts and never sends mail or performs external writes.\n\n## Object routing\n\n| Object | Tool |\n| --- | --- |\n| Agent definition and default Agent | `xopc_use` mode `agent` |\n| Scene and scene result | `xopc_use` mode `scene` |\n| Project, milestone, project update | `xopc_use` mode `project` |\n| Automation | `xopc_use` mode `automation` |\n| Task intent and lifecycle | `xopc_use` mode `task` |\n| Task execution attempt, receipt, events and waits | `xopc_use` mode `task_run` |\n| Note | `xopc_use` mode `note` |\n| Lightweight UI preview | `xopc_use` mode `chat_preview` |\n| Local app | `xopc_use` mode `local_app` |\n| Settings jump target | `xopc_use` mode `settings` |\n| Workflow run | dedicated `workflow` tool; pass `taskId` to link it to a Task |\n| Session, memory, skill, connected app or workspace file | its dedicated tool |\n\nDo not emulate Workflow APIs through `xopc_use`. A Task is durable intent;\na TaskRun is one execution attempt; a WorkflowRun is a procedure execution and may belong\nto a TaskRun. Never treat these three objects as interchangeable.\n\n## Agents\n\nCommands: `list`, `get`, `create`, `update`, `set_default`, `disable`,\n`delete`, and `purge`.\n\nAn Agent profile accepts only `name` and optional `instructions`. Put personality,\nlanguage, role, and behavioral guidance in `profile.instructions`; do not invent profile\nfields such as `description`, `language`, `emoji`, or `creature`.\n\n```json\n{\n  \"mode\": \"agent\",\n  \"command\": \"create\",\n  \"args\": {\n    \"id\": \"xiaomei\",\n    \"profile\": {\n      \"name\": \"\u5C0F\u7F8E\",\n      \"instructions\": \"\u4F7F\u7528\u4E2D\u6587\u4EA4\u6D41\uFF0C\u8BED\u6C14\u6E29\u67D4\u3001\u4EB2\u5207\u3001\u53EF\u7231\uFF0C\u540C\u65F6\u4FDD\u6301\u56DE\u7B54\u6E05\u6670\u53EF\u9760\u3002\"\n    },\n    \"idempotencyKey\": \"create-agent-xiaomei\"\n  }\n}\n```\n\nUse `list` before creating an Agent so an existing id is updated rather than duplicated.\nMutations other than `create` require the current `expectedRevision`; `set_default` uses\nthe catalog revision returned by `list`. `delete` preserves on-disk data, while `purge`\nalso removes it. Use `dryRun: true` to validate the exact same input contract without writing.\n\n## Reliable protocol\n\n1. Use `list` then `get` when an id is unknown.\n2. Read the current `version` before a Task mutation.\n3. Use `dryRun: true` for broad Project changes or uncertain mutations.\n4. Mutate once with the exact id and current concurrency token.\n5. Verify the returned object and preserve any \u201COpen in xopc\u201D delivery link.\n6. On a conflict, read again and reconsider the operation; do not blindly retry.\n\nTimestamps are Unix epoch milliseconds. Array fields are arrays of strings. Omission\npreserves a patchable field; an empty array intentionally clears it. Prefer explicit\n`projectId`, `taskId`, `runId`, `noteId`, and `localAppId` fields over `id`.\n\n## Scenes\n\nCommands: `templates`, `list`, `get`, `mail_accounts`, `mail_search`,\n`mail_sources`, `read_notes`, `preflight`, `start`, `configure`, `transition`,\n`check`, `notes`, `work_item`, `update_work_item`, `schedule`, `results`,\n`feedback`, `mark_read`, `diagnostics`, `get_preferences`, and `set_preferences`.\n\nTemplates are installed capabilities, not a fixed scenario list. Discover them instead of guessing\nkeys, versions, context providers, or execution adapters. The core read-only start protocol applies\nto templates whose execution kind is `agent`; adapter-backed templates expose their own setup in\nthe Monitors UI. Timestamps are Unix epoch milliseconds. Use `preflight` or `dryRun: true` before\n`start` when account or model readiness is uncertain.\n\n### Safe start protocol\n\n1. Call `list` and reuse a matching activation when one exists.\n2. Call `templates`; for mail, call `mail_accounts` and `mail_search` with the exact account.\n3. Explain the selected source and timing to the user before creating the scene.\n4. Call `preflight` with the complete start input.\n5. Call `start` with the same input and a stable `requestId` for retry safety.\n6. Add notes, a work item, or a schedule as required; then call `get` to verify the state.\n\nFamily plans use scope `{ \"kind\": \"personal\" }` and permissions with only\n`user_notes`. Mail follow-up uses one selected mail source in an objects scope and exactly one\nauthorized account. Never broaden either scope to make preflight pass.\n\n### Mutations and results\n\nRead the current activation `revision` before `configure` or `transition`. Read the current\nnotes, schedule, work-item, or feedback revision before changing that object. On a conflict,\nread again and reconsider; do not retry with a guessed revision.\n\n`check` queues work and does not mean a result already exists. Use a stable `requestId` and\ninspect `results` later. `no_change` intentionally creates no user-facing draft. A returned\ndraft is not a sent message. Use `diagnostics` for source, model, queue, or notification failures.\n\nScene preferences control checks and reminders globally for the current principal. Read them\nwith `get_preferences` before `set_preferences`; preserve fields the user did not ask to change.\n\n## Projects\n\nCommands: `list`, `get`, `create`, `update`, `resolve_workspace`,\n`list_milestones`, `create_milestone`, `update_milestone`, `list_updates`,\nand `create_update`.\n\nProject statuses: `planned`, `active`, `paused`, `completed`, `cancelled`,\n`archived`. Health values: `unknown`, `on_track`, `at_risk`, `off_track`.\n\nA Project defines bounded shared context for related work. Its durable planning fields are `outcome`,\n`successCriteria`, `scope`, `nonGoals`, `ownerId`, `targetAt`, and `health`.\nUse `brief` for a concise description and `instructions` for durable operating guidance.\n\n### Create\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"AI Product Research\",\n    \"outcome\": \"Choose a validated product direction\",\n    \"successCriteria\": [\"Ten customer interviews\", \"Decision recorded\"],\n    \"scope\": { \"market\": \"developer tools\" },\n    \"nonGoals\": [\"Build the production product\"],\n    \"health\": \"on_track\",\n    \"targetAt\": 1760000000000,\n    \"workspaceRoot\": \"/path/to/repo\"\n  }\n}\n```\n\n### Update\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"status\": \"active\",\n    \"health\": \"at_risk\",\n    \"successCriteria\": [\"Ten interviews\", \"Evidence-backed decision\"]\n  }\n}\n```\n\n### Resolve a workspace\n\nUse `autoCreate: false` for lookup. Set it to true only when creating a Project is authorized.\n\n```json\n{ \"mode\": \"project\", \"command\": \"resolve_workspace\", \"args\": { \"workspacePath\": \"/path/to/repo\", \"autoCreate\": false } }\n```\n\n### Milestones\n\nMilestone statuses: `planned`, `active`, `completed`, `cancelled`.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_milestone\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"title\": \"Finish discovery\",\n    \"status\": \"active\",\n    \"targetAt\": 1760000000000,\n    \"sortOrder\": 10\n  }\n}\n```\n\nUse `list_milestones` with `projectId`. Use `update_milestone` with both\n`projectId` and `milestoneId`. Milestone deletion is intentionally not exposed.\n\n### Immutable project updates\n\nProject updates are append-only progress snapshots. They also update Project health.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create_update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"health\": \"on_track\",\n    \"summary\": \"Discovery is complete\",\n    \"progress\": [\"Interviewed ten users\"],\n    \"risks\": [\"Pricing remains unvalidated\"],\n    \"nextSteps\": [\"Run pricing tests\"]\n  }\n}\n```\n\nUse `list_updates` with `projectId` and optional `limit`. Updates cannot be edited.\n\n## Automations\n\nCommands: `list`, `get`, `create`, `update`, `delete`, `run`, `pause`,\n`resume`, and `history`.\n\nAutomation `create` automatically uses the current session Project when `projectId` is\nomitted. An explicit `projectId` takes precedence and is validated before mutation. Use an\nexplicit id when creating for a Project other than the current session Project.\n\n### Create in the current Project\n\n`trigger` and `action` use the same shapes as the Automation product API.\n\n```json\n{\n  \"mode\": \"automation\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"Daily project review\",\n    \"trigger\": { \"kind\": \"schedule\", \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 9 * * 1-5\", \"tz\": \"Asia/Shanghai\" } },\n    \"action\": { \"kind\": \"agent\", \"instruction\": \"Review the current project and summarize risks.\" }\n  }\n}\n```\n\nTo override the inherited Project, add `\"projectId\": \"project_id\"` to `args`.\nThe create payload may also be nested under `args.automation`; top-level `args.projectId`\nhas precedence.\n\n### List and history\n\n`list` and unqualified `history` inherit the current session Project. Pass an explicit\n`projectId` to query another Project. Pass `automationId` to `history` for one Automation.\n\n### Update and operate\n\nUse `automationId` for `get`, `update`, `delete`, `run`, `pause`, and `resume`.\nFor `update`, patch fields may be direct args or nested under `args.patch`. Supplying a new\n`projectId` reassigns the Automation after validating the target Project.\n\n## Tasks\n\nCommands: `list`, `get`, `create`, `update_dependencies`, `add_context`,\n`remove_context`, `command`, and `delete`.\n\nTask phases are `backlog`, `ready`, `active`, `review`, and `closed`.\nOperational state is projected separately as `idle`, `queued`, `running`, `waiting`,\n`verifying`, `succeeded`, `failed`, or `cancelled`. Never send either value as a\nfree-form status update.\n\n`task.get` returns the Task, its projected `model`, dependencies, dependents, context,\nauthority grants, TaskRuns, receipts, and waits.\nThe projected model is the correct source for current operational state and attention items.\n\n`delete` permanently removes the Task and its contracts, waits, context links, TaskRuns,\nreceipts, and Task-owned execution records. It does not delete linked Sessions, workspace files,\nor external artifacts. Cancel an active TaskRun before deletion, and use `dryRun: true` when\nthe user's intent is ambiguous.\n\n```json\n{ \"mode\": \"task\", \"command\": \"delete\", \"args\": { \"taskId\": \"task_id\" }, \"dryRun\": true }\n```\n\n### Capture or start\n\n`createMode` defaults to `capture`, which creates a backlog Task without executing it.\nUse `start` only when immediate execution is intended.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"create\",\n  \"args\": {\n    \"objective\": \"Complete the customer research report\",\n    \"projectId\": \"project_id\",\n    \"createMode\": \"capture\",\n    \"priority\": \"high\",\n    \"expectedOutputs\": [\"Research report\"],\n    \"acceptanceCriteria\": [\"Sources are cited\"],\n    \"constraints\": [\"Do not contact customers without approval\"],\n    \"dependsOnTaskIds\": []\n  }\n}\n```\n\n### Dependencies\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"update_dependencies\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"dependsOnTaskIds\": [\"dependency_task_id\"]\n  }\n}\n```\n\n### Context links\n\nUse `add_context` to link a document, file, URL, session, memory, Task, artifact, or source\nas `input`, `reference`, `constraint`, `deliverable`, or `evidence` context.\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"add_context\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"targetKind\": \"file\",\n    \"targetId\": \"/path/to/spec.md\",\n    \"role\": \"input\",\n    \"title\": \"Product specification\",\n    \"pinned\": true,\n    \"retrievalPolicy\": {},\n    \"metadata\": {}\n  }\n}\n```\n\nUse `remove_context` with `taskId` and the exact `edgeId` returned by `task.get`.\nDo not add authority grants through this tool; an Agent must not authorize itself.\n\n### Typed lifecycle commands\n\nEvery command requires `taskId`, the Task's current `expectedVersion`, a `type`, and\ntype-specific fields inside `commandArgs`.\n\nSupported command types:\n\n- `mark_ready`\n- `start`: `{ \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" } }`\n- `request_review`\n- `close`: `{ \"resolution\": \"done | cancelled | duplicate | wont_do\" }`\n- `reopen`: `{ \"phase\": \"ready | active\" }`\n- `add_wait`: `{ \"wait\": { \"kind\": \"dependency | approval | input | schedule | external | paused\", \"reason\": \"...\", \"condition\": {} } }`\n- `resolve_wait`: `{ \"waitId\": \"wait_id\", \"resolution\": {} }`\n- `delegate`: `{ \"agentId\": \"agent_id\" }`\n- `revise_contract`: `{ \"contract\": { ...complete contract... } }`\n\n```json\n{\n  \"mode\": \"task\",\n  \"command\": \"command\",\n  \"args\": {\n    \"taskId\": \"task_id\",\n    \"expectedVersion\": 3,\n    \"type\": \"start\",\n    \"commandArgs\": {\n      \"executor\": { \"kind\": \"agent\", \"agentId\": \"main\" }\n    }\n  }\n}\n```\n\nContract revision is replacement, not a patch. Read the Task and preserve all contract fields\nthe user did not ask to change. Resolve a wait through `resolve_wait`; do not directly mutate\na TaskRun or manufacture a phase transition.\n\n## TaskRuns\n\nTaskRun inspection is read-only except for explicit cancellation. Other execution state is\ncontrolled by Task commands and the runtime coordinator.\n\n### List attempts for a Task\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"list\", \"args\": { \"taskId\": \"task_id\", \"limit\": 20 } }\n```\n\nThe result contains run attempts, finalized receipts, and active waits.\n\n### Inspect one attempt\n\n```json\n{ \"mode\": \"task_run\", \"command\": \"get\", \"args\": { \"runId\": \"run_id\" } }\n```\n\nThe result contains the TaskRun, its receipt when terminal, ordered events, and active Task waits.\n\n### Cancel an attempt\n\nRead the run first, then pass its current version. Cancellation creates a terminal receipt.\n\n```json\n{\n  \"mode\": \"task_run\",\n  \"command\": \"cancel\",\n  \"args\": { \"runId\": \"run_id\", \"expectedVersion\": 2, \"reason\": \"User cancelled execution\" }\n}\n```\n\nDo not guess commands such as retry, force-complete, heartbeat, or transition; they are not Agent APIs.\n\n## Notes\n\nCommands: `list`, `get`, `create`, `append`, `preview_edit`, `update`, and `delete`.\nUse Notes for durable prose and reference material, not as a Task substitute. Prefer `append`\nwhen preserving user content. Use `preview_edit` before a canonical rewrite.\n\n```json\n{ \"mode\": \"note\", \"command\": \"create\", \"args\": { \"title\": \"Decision\", \"markdown\": \"...\", \"projectId\": \"project_id\" } }\n```\n\n```json\n{ \"mode\": \"note\", \"command\": \"append\", \"args\": { \"noteId\": \"note_id\", \"heading\": \"AI synthesis\", \"content\": \"...\" } }\n```\n\nUse `update` with `status: \"trashed\"` for a recoverable removal. `delete` permanently\nremoves the Note and its stored snapshots and media; use `dryRun: true` first when the\nuser's intent is ambiguous.\n\n```json\n{ \"mode\": \"note\", \"command\": \"delete\", \"args\": { \"noteId\": \"note_id\" }, \"dryRun\": true }\n```\n\n## Chat previews, local apps, and settings\n\nUse `chat_preview` by default when the user asks to design, mock up, or quickly show a UI in\nthe current conversation. It creates no Project and no Local App. Commands are `create`,\n`get`, and `revise`. Source consists of `markup`, `styles`, and optional `script`;\ndo not include a full HTML document or remote dependencies. Revision requires the exact\n`baseRevision` returned by the prior call.\n\nUse `local_app` only when the user explicitly asks for a durable, installable app or chooses\n\u201CSave as app\u201D on a chat preview. Do not create a Local App merely to render a UI draft.\n\nLocal app commands are `list`, `get`, `create`, and `validate`. Installation,\nactivation, rollback, and uninstall remain product runtime operations.\n\nSettings supports only `open` and returns an exact product jump target without changing config.\n\n## Error recovery\n\n| Result | Recovery |\n| --- | --- |\n| service unavailable | Stop retrying and report the unavailable capability. |\n| not found | Re-list in the intended scope; do not invent another id. |\n| conflict | Read the current object and reassess using its latest version. |\n| waiting | Inspect the Task projection and TaskRun waits; resolve only the real blocker. |\n| invalid command or state | Read the object and use only a documented transition. |\n| unsupported operation | Use the dedicated tool or product UI; never write storage directly. |\n\n## Deliberate boundaries\n\n- Project deletion and milestone deletion are not Agent APIs.\n- TaskRun mutation is internal to execution coordination except for optimistic cancellation.\n- Project updates are immutable.\n- Workflow and Automation operations remain in their dedicated tools.\n- Only the documented Task and TaskRun commands are valid; do not infer hidden aliases.\n";

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

@@ -95,10 +95,11 @@ Commands: \`templates\`, \`list\`, \`get\`, \`mail_accounts\`, \`mail_search\`,
 \`check\`, \`notes\`, \`work_item\`, \`update_work_item\`, \`schedule\`, \`results\`,
 \`feedback\`, \`mark_read\`, \`diagnostics\`, \`get_preferences\`, and \`set_preferences\`.
 
-The built-in templates are \`weekly-family-plan\` and \`mail-follow-up\`, currently version
-\`1.0.0\`. Discover templates instead of guessing keys or versions. Timestamps are Unix epoch
-milliseconds. Use \`preflight\` or \`dryRun: true\` before \`start\` when account or model readiness
-is uncertain.
+Templates are installed capabilities, not a fixed scenario list. Discover them instead of guessing
+keys, versions, context providers, or execution adapters. The core read-only start protocol applies
+to templates whose execution kind is \`agent\`; adapter-backed templates expose their own setup in
+the Monitors UI. Timestamps are Unix epoch milliseconds. Use \`preflight\` or \`dryRun: true\` before
+\`start\` when account or model readiness is uncertain.
 
 ### Safe start protocol
 

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

@@ -2,7 +2,7 @@ import type { AgentTool } from '@earendil-works/pi-agent-core';
 import type { AutomationService } from '../../automations/index.js';
 import type { ProjectService } from '../../projects/project-service.js';
 declare const AutomationToolSchema: import("@sinclair/typebox").TObject<{
-    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"list">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"delete">, import("@sinclair/typebox").TLiteral<"run">, import("@sinclair/typebox").TLiteral<"rerun">, import("@sinclair/typebox").TLiteral<"cancel">, import("@sinclair/typebox").TLiteral<"read">, import("@sinclair/typebox").TLiteral<"read_all">, import("@sinclair/typebox").TLiteral<"pause">, import("@sinclair/typebox").TLiteral<"resume">, import("@sinclair/typebox").TLiteral<"history">, import("@sinclair/typebox").TLiteral<"get_run">, import("@sinclair/typebox").TLiteral<"run_events">, import("@sinclair/typebox").TLiteral<"metrics">, import("@sinclair/typebox").TLiteral<"product_events">]>;
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"list">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"delete">, import("@sinclair/typebox").TLiteral<"run">, import("@sinclair/typebox").TLiteral<"rerun">, import("@sinclair/typebox").TLiteral<"cancel">, import("@sinclair/typebox").TLiteral<"read">, import("@sinclair/typebox").TLiteral<"read_all">, import("@sinclair/typebox").TLiteral<"pause">, import("@sinclair/typebox").TLiteral<"resume">, import("@sinclair/typebox").TLiteral<"history">, import("@sinclair/typebox").TLiteral<"get_run">, import("@sinclair/typebox").TLiteral<"run_events">, import("@sinclair/typebox").TLiteral<"metrics">, import("@sinclair/typebox").TLiteral<"events">, import("@sinclair/typebox").TLiteral<"deliveries">, import("@sinclair/typebox").TLiteral<"product_events">, import("@sinclair/typebox").TLiteral<"replay_event">, import("@sinclair/typebox").TLiteral<"retry_delivery">]>;
     automationId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     runId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     projectId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -10,6 +10,9 @@ declare const AutomationToolSchema: import("@sinclair/typebox").TObject<{
     patch: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     eventType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    eventId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    destinationKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    reason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     source: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     payloadKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     payloadValue: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

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

@@ -1,5 +1,5 @@
 import { appendProductDeliveryText } from "../../../packages/gateway-contract/src/product-delivery.js";
-import { AutomationCancelOutputSchema, AutomationDeleteOutputSchema, AutomationMutationOutputSchema, AutomationReadAllOutputSchema, AutomationReadOutputSchema, AutomationRunMutationOutputSchema, ProductReadContracts } from "../../../packages/gateway-contract/src/capabilities.js";
+import { AutomationCancelOutputSchema, AutomationDeleteOutputSchema, AutomationMutationOutputSchema, AutomationReadAllOutputSchema, AutomationReadOutputSchema, AutomationRecoveryOutputSchema, AutomationRunMutationOutputSchema, ProductReadContracts } from "../../../packages/gateway-contract/src/capabilities.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { createProductDispatcher } from "../../capabilities/runtime/product.js";
 import { randomUUID } from "node:crypto";
@@ -23,7 +23,11 @@ const AutomationToolSchema = Type.Object({
 		Type.Literal("get_run"),
 		Type.Literal("run_events"),
 		Type.Literal("metrics"),
-		Type.Literal("product_events")
+		Type.Literal("events"),
+		Type.Literal("deliveries"),
+		Type.Literal("product_events"),
+		Type.Literal("replay_event"),
+		Type.Literal("retry_delivery")
 	]),
 	automationId: Type.Optional(Type.String({ description: "Automation id for update/delete/run/pause/resume/history" })),
 	runId: Type.Optional(Type.String({ description: "Run id for rerun/cancel/read" })),
@@ -32,6 +36,9 @@ const AutomationToolSchema = Type.Object({
 	patch: Type.Optional(Type.Any({ description: "Automation update patch" })),
 	limit: Type.Optional(Type.Number({ description: "History limit, default 5" })),
 	eventType: Type.Optional(Type.String()),
+	eventId: Type.Optional(Type.String({ description: "Dead-letter event id for replay_event" })),
+	destinationKey: Type.Optional(Type.String({ description: "Dead-letter result destination key for retry_delivery" })),
+	reason: Type.Optional(Type.String({ description: "Operator reason recorded for an explicit recovery action" })),
 	source: Type.Optional(Type.String()),
 	payloadKey: Type.Optional(Type.String()),
 	payloadValue: Type.Optional(Type.String()),
@@ -39,7 +46,7 @@ const AutomationToolSchema = Type.Object({
 	idempotencyKey: Type.Optional(Type.String({
 		minLength: 1,
 		maxLength: 200,
-		description: "Stable write retry key, including cancel/read/read_all; only edits and deletion require expectedRevision"
+		description: "Stable write retry key, including cancel/read/read_all/recovery; only edits and deletion require expectedRevision"
 	}))
 });
 function textResult(text, details = {}) {
@@ -156,6 +163,28 @@ function createAutomationTool(deps) {
 					const result = AutomationReadAllOutputSchema.parse(await call("xopc.automations.read_all", { projectId: params.projectId }));
 					return textResult(`Marked ${result.count} completed runs read.`, result);
 				}
+				case "replay_event": {
+					const eventId = params.eventId?.trim();
+					const reason = params.reason?.trim();
+					if (!eventId || !reason) return textResult("eventId and reason are required for replay_event.", { ok: false });
+					const result = AutomationRecoveryOutputSchema.parse(await call("xopc.automations.replay_event", {
+						id: eventId,
+						reason
+					}));
+					return textResult(`Accepted replay for automation event ${eventId}.`, result);
+				}
+				case "retry_delivery": {
+					const runId = params.runId?.trim();
+					const destinationKey = params.destinationKey?.trim();
+					const reason = params.reason?.trim();
+					if (!runId || !destinationKey || !reason) return textResult("runId, destinationKey, and reason are required for retry_delivery.", { ok: false });
+					const result = AutomationRecoveryOutputSchema.parse(await call("xopc.automations.retry_delivery", {
+						runId,
+						destinationKey,
+						reason
+					}));
+					return textResult(`Accepted retry for automation delivery ${runId}:${destinationKey}.`, result);
+				}
 				case "run":
 				case "rerun": {
 					const id = params.action === "run" ? params.automationId?.trim() : params.runId?.trim();
@@ -195,9 +224,18 @@ function createAutomationTool(deps) {
 				case "get_run":
 				case "run_events":
 				case "metrics":
+				case "events":
+				case "deliveries":
 				case "product_events": {
 					const operation = `xopc.automations.${params.action}`;
-					const input = params.action === "metrics" ? {} : params.action === "product_events" ? {
+					const input = params.action === "metrics" ? {} : params.action === "events" ? {
+						type: params.eventType,
+						source: params.source,
+						limit: params.limit
+					} : params.action === "deliveries" ? {
+						runId: params.runId,
+						limit: params.limit
+					} : params.action === "product_events" ? {
 						eventType: params.eventType,
 						source: params.source,
 						payloadKey: params.payloadKey,

package/dist/src/agent/tools/session-search-tool.js

@@ -55,7 +55,7 @@ ${formatMessagesForSummary(messages)}`,
 			maxTokens: 400,
 			temperature: .15,
 			signal
-		});
+		}, void 0, { operation: "tool.session_search_summarize" });
 		let text = "";
 		if (Array.isArray(result.content)) {
 			for (const c of result.content) if (c && typeof c === "object" && c.type === "text") text += String(c.text || "");

package/dist/src/agent/tools/web-extract.js

@@ -84,7 +84,7 @@ async function callExtractionLlm(systemPrompt, userPrompt, maxTokens, config, si
 		maxTokens,
 		temperature: .2,
 		signal: buildTimeoutSignal(signal)
-	}));
+	}, void 0, { operation: "tool.web_extract" }));
 }
 async function extractWithLlm(rawContent, url, instruction, maxLength, config, signal) {
 	const contentLength = rawContent.length;