@xopcai/xopc 0.0.406 → 0.0.408

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

@@ -12,11 +12,11 @@ import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connect
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { selectConnectorAccount } from "../../connectors/account-selection.js";
 import { cliContextPath } from "../../connectors/cli/process.js";
-import { validateActionInput } from "../../connectors/cli/protocol.js";
 import { getCliAdapter } from "../../connectors/cli/adapterRegistry.js";
 import { evaluateConnectorExecutionPolicy } from "../../connectors/policy.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
 import { cliOwnerId, recoverCliExecutions } from "../../connectors/cli/store.js";
+import { validateActionInput } from "../../connectors/cli/protocol.js";
 import { describeCliAction, executeCliAction } from "../../connectors/cli/runtime.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { join } from "node:path";

package/dist/src/agent/prompt/conversational-configuration-guide.d.ts

@@ -0,0 +1,4 @@
+/** Product guidance selected by the paired compact configuration evaluation. */
+export declare const conversationalConfigurationGuide = "# Conversational xopc use\nAct on clear authorized requests with registered tools; ordinary answers need no product actions.\n\"You\" means the host's current Agent id, not main/default. Other Agents or global defaults\nrequire an explicit request and permission. Never bypass a denial or edit product storage.\nRead the target/revision. For profile-only changes use agent patch_profile\n{id,expectedRevision,patch,idempotencyKey?}; omitted fields are preserved. Inspect product ok\nand saved fields. On conflict re-read, preserve concurrent fields and retry once with a new\nrevision/key; after an uncertain write keep the original key and inspect first.\nWhen workflow or parameters are unclear, read tool_manual({tool:\"xopc_use\",topic:\"agent\"}),\nor topic:\"settings\", \"automation\", \"connections\" as relevant; no need to load a known recipe.\nsettings open is navigation only; voice uses section:\"capabilities/voice\". Saved is not tested.\nMissing connection/device tools mean an honest blocker, never invented links or completed tests.\n";
+/** Tool registration already reflects the host's allowlist and deny policy. */
+export declare function getConversationalConfigurationGuide(toolNames: readonly string[]): string;

package/dist/src/agent/prompt/conversational-configuration-guide.js

@@ -0,0 +1,25 @@
+//#region src/agent/prompt/conversational-configuration-guide.ts
+/** Product guidance selected by the paired compact configuration evaluation. */
+const conversationalConfigurationGuide = `# Conversational xopc use
+Act on clear authorized requests with registered tools; ordinary answers need no product actions.
+"You" means the host's current Agent id, not main/default. Other Agents or global defaults
+require an explicit request and permission. Never bypass a denial or edit product storage.
+Read the target/revision. For profile-only changes use agent patch_profile
+{id,expectedRevision,patch,idempotencyKey?}; omitted fields are preserved. Inspect product ok
+and saved fields. On conflict re-read, preserve concurrent fields and retry once with a new
+revision/key; after an uncertain write keep the original key and inspect first.
+When workflow or parameters are unclear, read tool_manual({tool:"xopc_use",topic:"agent"}),
+or topic:"settings", "automation", "connections" as relevant; no need to load a known recipe.
+settings open is navigation only; voice uses section:"capabilities/voice". Saved is not tested.
+Missing connection/device tools mean an honest blocker, never invented links or completed tests.
+`;
+const manualRouting = `When workflow or parameters are unclear, read tool_manual({tool:"xopc_use",topic:"agent"}),
+or topic:"settings", "automation", "connections" as relevant; no need to load a known recipe.
+`;
+/** Tool registration already reflects the host's allowlist and deny policy. */
+function getConversationalConfigurationGuide(toolNames) {
+	if (!toolNames.includes("xopc_use")) return "";
+	return toolNames.includes("tool_manual") ? conversationalConfigurationGuide : conversationalConfigurationGuide.replace(manualRouting, "No tool_manual is registered. Use documented registered parameters; report a blocker if required details are unavailable.\n");
+}
+//#endregion
+export { conversationalConfigurationGuide, getConversationalConfigurationGuide };

package/dist/src/agent/prompt/service-prompt-builder.js

@@ -14,6 +14,7 @@ import { buildSystemPrompt } from "./system-prompt.js";
 import { resolveResponseLanguageForSession } from "./response-language.js";
 import { buildTtsSystemPromptHint } from "../../voice/tts/directives.js";
 import { mergeTtsConfigFromAppConfig } from "../../voice/tts/merge-config.js";
+import { getConversationalConfigurationGuide } from "./conversational-configuration-guide.js";
 //#region src/agent/prompt/service-prompt-builder.ts
 init_sqlite();
 init_interaction_state();
@@ -53,7 +54,11 @@ var SystemPromptBuilder = class {
 			userTimezone,
 			externalMemoryInstructions: options.externalMemoryInstructions,
 			ttsSystemHint,
-			extraSystemPrompt: [options.extraSystemPrompt, interactionPrompt].filter(Boolean).join("\n\n"),
+			extraSystemPrompt: [
+				options.extraSystemPrompt,
+				getConversationalConfigurationGuide(reg),
+				interactionPrompt
+			].filter(Boolean).join("\n\n"),
 			activeProjectContext: options.activeProjectContext,
 			modelRef: options.modelRef,
 			agentId: options.agentId,

package/dist/src/agent/prompt/system-prompt.js

@@ -1,6 +1,6 @@
 import { buildActionTrustPrompt, init_trust_policy } from "../../user-context/trust-policy.js";
 import { PROMPT_CACHE_BOUNDARY, splitPromptCacheBoundary } from "./cache-boundary.js";
-import { projectPersonalInstructions } from "../../personal-agent/prompts.js";
+import { personalInstructions, projectPersonalInstructions } from "../../personal-agent/prompts.js";
 import { buildAestheticSection, buildExecutionBiasSection, buildHumanCollaborationSection, buildPersonalCoordinationSection, buildProblemSolvingSection, buildSafetySection, buildToolCallStyleSection, buildWorkContinuitySection } from "./sections/behavior.js";
 import { buildExternalMemorySection, buildMemorySection, buildSkillsSection } from "./sections/memory-skills.js";
 import { buildMessagingSection, buildOutputDirectivesSection, buildSilentRepliesSection, buildTimeSection } from "./sections/messaging-runtime.js";
@@ -20,7 +20,7 @@ function joinSections(sections) {
 */
 function buildSystemPrompt(workspaceDir, options = {}) {
 	const { contextFiles = [], promptMode = "full", promptRole = "executor", toolNames = [], toolSummaries, memoryCitationsMode = "on", includeMemorySection, userTimezone, runtime, agentId, channels = [], externalMemoryInstructions, ttsSystemHint, extraSystemPrompt, activeProjectContext, silentReplyPromptMode = "generic", promptContribution, includeProblemSolving = true, includeToneSection = true, actionTrustLevel, responseLanguage = "auto", customInstructions: storedCustomInstructions, agentProfile } = options;
-	const customInstructions = promptRole === "personal" && storedCustomInstructions ? projectPersonalInstructions(storedCustomInstructions, toolNames) : storedCustomInstructions;
+	const customInstructions = promptRole === "personal" ? projectPersonalInstructions(personalInstructions(), toolNames) : storedCustomInstructions;
 	if (promptMode === "none") return joinSections([
 		"You are a personal AI assistant running inside xopc.",
 		customInstructions?.trim() ? `<custom_instructions>\n${customInstructions.trim()}\n</custom_instructions>` : void 0,

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

@@ -0,0 +1,8 @@
+/** Focused product workflows; loaded on demand instead of expanding every turn. */
+export declare const xopcConfigurationTopics: {
+    readonly agent: "# xopc Agent configuration\nThe host's current Agent id is authoritative. \"You / this assistant\" means that Agent,\nnot main or the default Agent. Read agent get {id} (or list for discovery) for revision\nand effective inherited configuration. For identity changes prefer agent patch_profile\n{id,expectedRevision,patch:{name?,description?,style?,language?,...},idempotencyKey?}:\nomitted fields are preserved atomically. Existing agent update {id,expectedRevision,patch}\nremains a full replacement for patch.profile, so include every field to retain when using it.\nSet a chat model with update patch.models.chat={primary:\"provider/model\",fallbacks:[]}.\nChange only the requested Agent. Global defaults and other Agents are separate explicit\nrequests and still require permission. For creation list first, then create\n{id,profile:{name,language?,style?}}; do not invent a Project or custom workspace.\nset_default {id,expectedRevision} uses the catalog revision from list, not an Agent revision.\nAfter a revision conflict re-read the target, preserve concurrent fields and retry the\nrequested change once with the new revision and a new intent key. After an uncertain write,\ninspect first and retain the original idempotency key. A permission denial is not a conflict:\ndo not switch identity, target or tools to bypass it. Inspect returned product ok and saved\nfields before reporting success. A saved model reference does not prove it can be called.";
+    readonly settings: "# xopc settings and capability checks\nsettings open is navigation only; it does not read, apply or verify configuration.\nVoice: {section:\"capabilities/voice\",title:\"语音设置\"}; models: section:\"capabilities/models\";\nbrowser: section:\"agent-browser\". Unknown sections are rejected. There is no generic\nconfig/set, capability inspect or voice mutation in xopc_use. Never edit storage directly.\nFor a capability report read the current Agent's configuration, and use actual dedicated\nstatus/test tools if available. Model names or credentials alone are not proof of readiness.\nReport unknown when no verification tool exists. Saved, runtime-ready and tested differ.\nVoice settings are shared. Microphone permission, recording and playback need actual device\ninteraction. Return the exact product link and state the remaining action; never claim the\npage has opened or the device test passed from a navigation receipt. Do not invent UI buttons\nor promise audio verification unless the active tools can perform it.";
+    readonly automation: "# xopc automations\nUse automation list/get before changing an existing schedule or creating a potentially\nduplicate one. pause/resume takes {automationId,expectedRevision,idempotencyKey}; revision\nis the original updatedAtMs. Pause affects future scheduling, not proof a running job stopped.\nCreate with {name,enabled,trigger:{kind:\"schedule\",schedule:{kind:\"cron\",expr,tz}},\naction:{kind:\"agent\",instruction},delivery:{notificationPolicy:\"attention\",destinations:[]}}.\nUse the user's timezone. For 09:00 Asia/Shanghai use expr:\"0 9 * * *\",tz:\"Asia/Shanghai\".\nDraft / don't enable / don't run means enabled:false and no run call. simulate is not a real\nexecution. A one-off answer does not authorize creating a Task, Project, Agent or Automation.\nCheck returned ok and saved state; handle revision conflicts by re-reading, preserving changes\nand retrying once with the new revision. Keep original keys after uncertain writes.";
+    readonly connections: "# xopc external connections\nExternal services use their dedicated discovery, description, connection and execution tools,\nnot invented xopc_use connector commands or settings sections. When Gmail connection/read\ntools are absent, explain that specific blocker. Do not create or enable an email schedule\nbefore verifying the required account and a real read. Never invent a connection URL,\nconnected-apps/connections settings section, messages, or successful OAuth/reads.\nThe user saying \"connected\" is not evidence of working tools: rediscover and verify the\naccount and read permission before proceeding. Do not promise future execution while those\ntools are absent. Do not request passwords or API keys in ordinary chat.";
+};
+export type XopcConfigurationTopic = keyof typeof xopcConfigurationTopics;

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

@@ -0,0 +1,55 @@
+//#region src/agent/tool-manuals/xopc-configuration.ts
+/** Focused product workflows; loaded on demand instead of expanding every turn. */
+const xopcConfigurationTopics = {
+	agent: `# xopc Agent configuration
+The host's current Agent id is authoritative. "You / this assistant" means that Agent,
+not main or the default Agent. Read agent get {id} (or list for discovery) for revision
+and effective inherited configuration. For identity changes prefer agent patch_profile
+{id,expectedRevision,patch:{name?,description?,style?,language?,...},idempotencyKey?}:
+omitted fields are preserved atomically. Existing agent update {id,expectedRevision,patch}
+remains a full replacement for patch.profile, so include every field to retain when using it.
+Set a chat model with update patch.models.chat={primary:"provider/model",fallbacks:[]}.
+Change only the requested Agent. Global defaults and other Agents are separate explicit
+requests and still require permission. For creation list first, then create
+{id,profile:{name,language?,style?}}; do not invent a Project or custom workspace.
+set_default {id,expectedRevision} uses the catalog revision from list, not an Agent revision.
+After a revision conflict re-read the target, preserve concurrent fields and retry the
+requested change once with the new revision and a new intent key. After an uncertain write,
+inspect first and retain the original idempotency key. A permission denial is not a conflict:
+do not switch identity, target or tools to bypass it. Inspect returned product ok and saved
+fields before reporting success. A saved model reference does not prove it can be called.`,
+	settings: `# xopc settings and capability checks
+settings open is navigation only; it does not read, apply or verify configuration.
+Voice: {section:"capabilities/voice",title:"语音设置"}; models: section:"capabilities/models";
+browser: section:"agent-browser". Unknown sections are rejected. There is no generic
+config/set, capability inspect or voice mutation in xopc_use. Never edit storage directly.
+For a capability report read the current Agent's configuration, and use actual dedicated
+status/test tools if available. Model names or credentials alone are not proof of readiness.
+Report unknown when no verification tool exists. Saved, runtime-ready and tested differ.
+Voice settings are shared. Microphone permission, recording and playback need actual device
+interaction. Return the exact product link and state the remaining action; never claim the
+page has opened or the device test passed from a navigation receipt. Do not invent UI buttons
+or promise audio verification unless the active tools can perform it.`,
+	automation: `# xopc automations
+Use automation list/get before changing an existing schedule or creating a potentially
+duplicate one. pause/resume takes {automationId,expectedRevision,idempotencyKey}; revision
+is the original updatedAtMs. Pause affects future scheduling, not proof a running job stopped.
+Create with {name,enabled,trigger:{kind:"schedule",schedule:{kind:"cron",expr,tz}},
+action:{kind:"agent",instruction},delivery:{notificationPolicy:"attention",destinations:[]}}.
+Use the user's timezone. For 09:00 Asia/Shanghai use expr:"0 9 * * *",tz:"Asia/Shanghai".
+Draft / don't enable / don't run means enabled:false and no run call. simulate is not a real
+execution. A one-off answer does not authorize creating a Task, Project, Agent or Automation.
+Check returned ok and saved state; handle revision conflicts by re-reading, preserving changes
+and retrying once with the new revision. Keep original keys after uncertain writes.`,
+	connections: `# xopc external connections
+External services use their dedicated discovery, description, connection and execution tools,
+not invented xopc_use connector commands or settings sections. When Gmail connection/read
+tools are absent, explain that specific blocker. Do not create or enable an email schedule
+before verifying the required account and a real read. Never invent a connection URL,
+connected-apps/connections settings section, messages, or successful OAuth/reads.
+The user saying "connected" is not evidence of working tools: rediscover and verify the
+account and read permission before proceeding. Do not promise future execution while those
+tools are absent. Do not request passwords or API keys in ordinary chat.`
+};
+//#endregion
+export { xopcConfigurationTopics };

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 | 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## Object routing\n\n| Object | Tool |\n| --- | --- |\n| Agent definition and default Agent | `xopc_use` mode `agent` |\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 stores `name` and optional `description`, `creature`, `style`, `language`,\n`emoji`, and `avatar` identity fields. Use `instructions` for short execution rules.\nPut personality in SOUL.md and ongoing work guidance in AGENTS.md.\n\n```json\n{\n  \"mode\": \"agent\",\n  \"command\": \"create\",\n  \"args\": {\n    \"id\": \"xiaomei\",\n    \"profile\": {\n      \"name\": \"\u5C0F\u7F8E\",\n      \"description\": \"\u5E2E\u52A9\u6574\u7406\u65E5\u5E38\u4E8B\u9879\",\n      \"language\": \"zh-CN\",\n      \"style\": \"\u6E29\u67D4\u3001\u4EB2\u5207\",\n      \"instructions\": \"\u7ED9\u51FA\u64CD\u4F5C\u5EFA\u8BAE\u524D\u5148\u6838\u5BF9\u5173\u952E\u4E8B\u5B9E\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## 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\nTask locale follows the conversation response language, then the user request and profile.\nKeep every user-facing contract field (criteria, expected outputs, constraints, assumptions and risks)\nin that language, even when attached source material is English. Preserve paths, URLs and proper nouns.\nAn explicit locale must reflect the user\u2019s language choice.\n\nCommands: `list`, `get`, `create`, `delegated_tasks`, `collaboration`,\n`collaboration_post`, `update_dependencies`, `add_context`, `remove_context`,\n`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\nFor an immediate delegated task, use the minimal call below. The objective can include the\nworker instructions and constraints; optional lists are unnecessary for a simple delegation.\n\n```json\n{ \"mode\": \"task\", \"command\": \"create\", \"args\": { \"objective\": \"Calculate the requested result and report progress\", \"createMode\": \"start\" } }\n```\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### Main Agent and worker collaboration\n\nThe user-facing Agent can call `delegated_tasks` to list Tasks created from this conversation,\nthen `collaboration` with `{ \"taskId\": \"...\", \"afterSequence\": 0 }` to read the ordered board.\nUse the Task and TaskRun receipt as the final source of execution status.\n\nUse `collaboration_post` with `taskId`, `kind`, `body`, and a stable `idempotencyKey`.\nThe main Agent may write `instruction`, `question`, or `answer`; answers include\n`causationId` of the worker's question. The worker may write `progress`, `question`,\nor `ack`; acknowledgements include `causationId` of the instruction. A worker question\npauses the active TaskRun. After posting it, stop the execution turn and wait for an answer.\nAn instruction is first recorded, then delivered to the worker conversation, and is only\nconfirmed when the worker acknowledges it. Ordinary progress does not interrupt the user.\n\n```json\n{ \"mode\": \"task\", \"command\": \"collaboration_post\", \"args\": { \"taskId\": \"task_id\", \"kind\": \"progress\", \"body\": \"Completed source review\", \"idempotencyKey\": \"stable-key\" } }\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. For focused configuration workflows use\n`tool_manual({tool:\"xopc_use\",topic:\"agent|settings|automation|connections\"})`.\nFor identity-only changes prefer `agent patch_profile {id,expectedRevision,patch,idempotencyKey?}`,\nwhich preserves omitted profile fields. Existing update keeps replacement semantics for profile.\n\n```json\n{\n  \"mode\": \"agent | 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## Object routing\n\n| Object | Tool |\n| --- | --- |\n| Agent definition and default Agent | `xopc_use` mode `agent` |\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 stores `name` and optional `description`, `creature`, `style`, `language`,\n`emoji`, and `avatar` identity fields. Use `instructions` for short execution rules.\nPut personality in SOUL.md and ongoing work guidance in AGENTS.md.\n\n```json\n{\n  \"mode\": \"agent\",\n  \"command\": \"create\",\n  \"args\": {\n    \"id\": \"xiaomei\",\n    \"profile\": {\n      \"name\": \"\u5C0F\u7F8E\",\n      \"description\": \"\u5E2E\u52A9\u6574\u7406\u65E5\u5E38\u4E8B\u9879\",\n      \"language\": \"zh-CN\",\n      \"style\": \"\u6E29\u67D4\u3001\u4EB2\u5207\",\n      \"instructions\": \"\u7ED9\u51FA\u64CD\u4F5C\u5EFA\u8BAE\u524D\u5148\u6838\u5BF9\u5173\u952E\u4E8B\u5B9E\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## 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\nTask locale follows the conversation response language, then the user request and profile.\nKeep every user-facing contract field (criteria, expected outputs, constraints, assumptions and risks)\nin that language, even when attached source material is English. Preserve paths, URLs and proper nouns.\nAn explicit locale must reflect the user\u2019s language choice.\n\nCommands: `list`, `get`, `create`, `delegated_tasks`, `collaboration`,\n`collaboration_post`, `update_dependencies`, `add_context`, `remove_context`,\n`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\nFor an immediate delegated task, use the minimal call below. The objective can include the\nworker instructions and constraints; optional lists are unnecessary for a simple delegation.\n\n```json\n{ \"mode\": \"task\", \"command\": \"create\", \"args\": { \"objective\": \"Calculate the requested result and report progress\", \"createMode\": \"start\" } }\n```\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### Main Agent and worker collaboration\n\nThe user-facing Agent can call `delegated_tasks` to list Tasks created from this conversation,\nthen `collaboration` with `{ \"taskId\": \"...\", \"afterSequence\": 0 }` to read the ordered board.\nUse the Task and TaskRun receipt as the final source of execution status.\n\nUse `collaboration_post` with `taskId`, `kind`, `body`, and a stable `idempotencyKey`.\nThe main Agent may write `instruction`, `question`, or `answer`; answers include\n`causationId` of the worker's question. The worker may write `progress`, `question`,\nor `ack`; acknowledgements include `causationId` of the instruction. A worker question\npauses the active TaskRun. After posting it, stop the execution turn and wait for an answer.\nAn instruction is first recorded, then delivered to the worker conversation, and is only\nconfirmed when the worker acknowledges it. Ordinary progress does not interrupt the user.\n\n```json\n{ \"mode\": \"task\", \"command\": \"collaboration_post\", \"args\": { \"taskId\": \"task_id\", \"kind\": \"progress\", \"body\": \"Completed source review\", \"idempotencyKey\": \"stable-key\" } }\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

@@ -4,7 +4,10 @@ const xopcUseManual = `# XOPC Use Tool Manual
 ## Purpose
 
 \`xopc_use\` operates first-class XOPC product objects without editing SQLite or product files directly.
-Load this manual before a non-trivial mutation.
+Load this manual before a non-trivial mutation. For focused configuration workflows use
+\`tool_manual({tool:"xopc_use",topic:"agent|settings|automation|connections"})\`.
+For identity-only changes prefer \`agent patch_profile {id,expectedRevision,patch,idempotencyKey?}\`,
+which preserves omitted profile fields. Existing update keeps replacement semantics for profile.
 
 \`\`\`json
 {

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

@@ -79,7 +79,6 @@ import { withTaskEvidenceIdentity } from "./task-evidence.js";
 import { withPersonalPerformance } from "./personal-performance.js";
 import { createPersonalRequestTools } from "./personal-request-tool.js";
 import { createPersonalRequestConnectionTool, createPersonalRequestResultTool } from "./personal-request-result-tool.js";
-import { createPersonalPreferenceTool } from "./personal-preference-tool.js";
 import { createBrowserUseTool } from "./browser/tool/browser-use-tool.js";
 import { ComputerRuntime } from "../../computer/runtime.js";
 import { createComputerUseTool } from "./computer-use-tool.js";
@@ -548,10 +547,6 @@ var AgentToolsFactory = class AgentToolsFactory {
 				createPersonalAttentionTool({
 					getConversationId: () => this.deps.getCurrentContext()?.conversationId,
 					getConfig: () => this.deps.getConfig?.()
-				}),
-				createPersonalPreferenceTool({
-					getCurrentConversationId: () => this.deps.getCurrentContext()?.conversationId,
-					onAgentCatalogMutate: this.deps.onAgentCatalogMutate
 				})
 			] : []] : [],
 			...cfg?.computer.enabled && this.deps.endpointTools ? [createComputerUseTool({

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

@@ -1,6 +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">]>>;
 }>;
 export declare function createToolManualTool(): AgentTool<typeof ToolManualSchema, {}>;
 export {};

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

@@ -1,15 +1,40 @@
+import { xopcConfigurationTopics } from "../tool-manuals/xopc-configuration.js";
 import { getToolManual, listToolManuals } from "../tool-manuals/index.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/tool-manual-tool.ts
-const ToolManualSchema = Type.Object({ tool: Type.String({ description: "Built-in tool name, e.g. browser_use" }) });
+const ToolManualSchema = Type.Object({
+	tool: Type.String({ description: "Built-in tool name, e.g. browser_use" }),
+	topic: Type.Optional(Type.Union([
+		Type.Literal("agent"),
+		Type.Literal("settings"),
+		Type.Literal("automation"),
+		Type.Literal("connections")
+	], { description: "Focused xopc_use workflow; omit for the full parameter manual." }))
+});
 function createToolManualTool() {
 	return {
 		name: "tool_manual",
 		label: "📘 Tool Manual",
-		description: "Load built-in usage manuals for complex tools. Use before non-trivial use of tools such as browser_use or xopc_use.",
+		description: "Focused xopc_use workflows are available as topic agent, settings, automation or connections; omit topic for full parameters. Load built-in usage manuals for complex tools. Use before non-trivial use of tools such as browser_use or xopc_use.",
 		parameters: ToolManualSchema,
 		async execute(_toolCallId, params) {
 			const toolName = params.tool.trim();
+			if (params.topic) {
+				if (toolName !== "xopc_use") return {
+					content: [{
+						type: "text",
+						text: "Topics are supported only for xopc_use; omit topic for other manuals."
+					}],
+					details: {}
+				};
+				return {
+					content: [{
+						type: "text",
+						text: xopcConfigurationTopics[params.topic]
+					}],
+					details: {}
+				};
+			}
 			const manual = getToolManual(toolName);
 			if (!manual) return {
 				content: [{

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

@@ -52,7 +52,7 @@ const XopcUseToolSchema = Type.Object({
 		Type.Literal("agent"),
 		Type.Literal("settings")
 	]),
-	command: Type.String({ description: "Context resolve takes an explicit AppContextEnvelope; never guess a current page. Automation draft/repair_draft accept prompt/id, agentId?, language?, idempotencyKey?; simulate explains an automation without running it. Local_app record_acceptance records supplied checks and sourceHash, not proof that checks were executed. Agent commands: list, get {id}, create {id, profile, workspace?, models?, skills?, tools?, workflows?, runtime?, idempotencyKey?}, update {id, expectedRevision, patch, idempotencyKey?}, set_default {id, expectedRevision, idempotencyKey?}, disable/delete/purge {id, expectedRevision, idempotencyKey?}. Purge also removes on-disk data. Project create accepts idempotencyKey; update/pin/unpin/delete accepts {projectId, expectedVersion?, idempotencyKey?}; stable retries require the original expectedVersion. Delete preserves workspace files and does not confirm external execution stopped. Project milestone writes support idempotencyKey; update_milestone/delete_milestone require original expectedRevision for stable retries, and create_update requires original expectedVersion. TaskRun cancel accepts idempotencyKey and expectedVersion, and does not confirm external execution stopped. Automation diagnostics: get_run/run_events {runId}, metrics {}, 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: "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?, workflows?, runtime?, idempotencyKey?}, update {id, expectedRevision, patch, idempotencyKey?}, set_default {id, expectedRevision, idempotencyKey?}, disable/delete/purge {id, expectedRevision, idempotencyKey?}. Purge also removes on-disk data. Project create accepts idempotencyKey; update/pin/unpin/delete accepts {projectId, expectedVersion?, idempotencyKey?}; stable retries require the original expectedVersion. Delete preserves workspace files and does not confirm external execution stopped. Project milestone writes support idempotencyKey; update_milestone/delete_milestone require original expectedRevision for stable retries, and create_update requires original expectedVersion. TaskRun cancel accepts idempotencyKey and expectedVersion, and does not confirm external execution stopped. Automation diagnostics: get_run/run_events {runId}, metrics {}, 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." }))
 });
@@ -433,6 +433,7 @@ async function handleAgent(command, args, dryRun, capabilities, deps, toolCallId
 	const writeCommands = new Set([
 		"create",
 		"update",
+		"patch_profile",
 		"set_default",
 		"disable",
 		"delete",
@@ -1978,12 +1979,16 @@ function createXopcUseTool(deps) {
 					authorize: deps.authorizeCapability ?? (() => true),
 					signal
 				};
-				const result = await capabilities.call("xopc.settings.open", args, caller);
-				return okText({
-					...details,
-					result,
-					delivery: deliveryForXopcResult(mode, command, result, dryRun)
-				});
+				try {
+					const result = await capabilities.call("xopc.settings.open", args, caller);
+					return okText({
+						...details,
+						result,
+						delivery: deliveryForXopcResult(mode, command, result, dryRun)
+					});
+				} catch (error) {
+					return errorText(error instanceof CapabilityError && error.code === "INVALID_INPUT" ? "Invalid settings target. Read tool_manual({tool:\"xopc_use\",topic:\"settings\"}); never invent a settings section." : error instanceof Error ? error.message : String(error), details);
+				}
 			}
 			if (mode === "local_app" && (command === "get" || command === "list" || command === "validate")) {
 				const caller = {

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

@@ -1,4 +1,4 @@
-import { AgentEntrySchema, EffectiveAgentConfigSchema } from "../agent-config/schema.js";
+import { AgentEntrySchema, AgentProfileSchema, EffectiveAgentConfigSchema } from "../agent-config/schema.js";
 import { resolveEffectiveAgentConfig } from "../agent-config/resolver.js";
 import { init_agent_config } from "../agent-config/index.js";
 import { CapabilityError } from "../capabilities/runtime/errors.js";
@@ -165,6 +165,32 @@ function registerAgentCapabilities(dispatcher) {
 		},
 		afterCommit: () => service.resumePendingProvisioning()
 	}));
+	dispatcher.register(defineAtomicCapability({
+		...writePolicy,
+		id: "xopc.agents.patch_profile",
+		description: "Patch selected profile fields at an exact revision, preserving omitted fields.",
+		input: z.strictObject({
+			id: AgentEntrySchema.shape.id,
+			expectedRevision: z.number().int().positive(),
+			patch: AgentProfileSchema.partial().refine((value) => Object.keys(value).length > 0, "Provide at least one profile field")
+		}),
+		output: AgentMutationOutputSchema,
+		execute({ id, expectedRevision, patch }) {
+			const { revision: _revision, provisioningState: _state, provisioningError: _error, createdAt: _created, updatedAt: _updated, deletedAt: _deleted, ...entry } = requireAgent(repository, id);
+			const profile = AgentProfileSchema.parse({
+				...entry.profile,
+				...patch
+			});
+			return {
+				ok: true,
+				...view(repository, translateMutationError(() => repository.update(id, expectedRevision, {
+					...entry,
+					profile
+				}, { reprovision: true })))
+			};
+		},
+		afterCommit: () => service.resumePendingProvisioning()
+	}));
 	dispatcher.register(defineAtomicCapability({
 		...writePolicy,
 		id: "xopc.agents.set_default",

package/dist/src/agent-config/index.js

@@ -1,5 +1,5 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { AgentDefaultsSchema, AgentEntrySchema, AgentIdSchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, ResponsePreferencesSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_schema } from "./schema.js";
+import { AgentDefaultsSchema, AgentEntrySchema, AgentIdSchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_schema } from "./schema.js";
 import { init_resolver, resolveEffectiveAgentConfig } from "./resolver.js";
 //#region src/agent-config/index.ts
 var init_agent_config = __esmMin((() => {
@@ -8,4 +8,4 @@ var init_agent_config = __esmMin((() => {
 }));
 //#endregion
 init_agent_config();
-export { AgentDefaultsSchema, AgentEntrySchema, AgentIdSchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, ResponsePreferencesSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_agent_config, resolveEffectiveAgentConfig };
+export { AgentDefaultsSchema, AgentEntrySchema, AgentIdSchema, AgentModelsDefaultsSchema, AgentModelsOverrideSchema, AgentProfileSchema, ComputerModelRouteSchema, DEFAULT_AGENT_MODEL_REF, DEFAULT_CORE_SKILLS, DEFAULT_SKILL_POLICY, EffectiveAgentConfigSchema, ImageGenerationRouteSchema, ModelIntentSchema, ModelRefSchema, ModelRouteSchema, RuntimePolicySchema, SkillDefaultsSchema, SkillOverrideSchema, ToolModeSchema, ToolPoliciesSchema, ToolPolicySchema, WorkflowPolicySchema, init_agent_config, resolveEffectiveAgentConfig };

package/dist/src/agent-config/schema.d.ts

@@ -287,35 +287,6 @@ export declare const AgentDefaultsSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export declare const ResponsePreferencesSchema: z.ZodObject<{
-    addressAs: z.ZodOptional<z.ZodString>;
-    guidance: z.ZodOptional<z.ZodString>;
-    warmth: z.ZodOptional<z.ZodEnum<{
-        balanced: "balanced";
-        reserved: "reserved";
-        gentle: "gentle";
-    }>>;
-    humor: z.ZodOptional<z.ZodEnum<{
-        none: "none";
-        occasional: "occasional";
-        playful: "playful";
-    }>>;
-    supportMode: z.ZodOptional<z.ZodEnum<{
-        listen: "listen";
-        untangle: "untangle";
-        solutions: "solutions";
-    }>>;
-    detailLevel: z.ZodOptional<z.ZodEnum<{
-        brief: "brief";
-        balanced: "balanced";
-        detailed: "detailed";
-    }>>;
-    proactivity: z.ZodOptional<z.ZodEnum<{
-        open: "open";
-        decisions: "decisions";
-        important: "important";
-    }>>;
-}, z.core.$strict>;
 export declare const AgentProfileSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -332,35 +303,6 @@ export declare const AgentProfileSchema: z.ZodObject<{
     voiceCallPreferences: z.ZodOptional<z.ZodObject<{
         openingGreetingEnabled: z.ZodBoolean;
     }, z.core.$strict>>;
-    responsePreferences: z.ZodOptional<z.ZodObject<{
-        addressAs: z.ZodOptional<z.ZodString>;
-        guidance: z.ZodOptional<z.ZodString>;
-        warmth: z.ZodOptional<z.ZodEnum<{
-            balanced: "balanced";
-            reserved: "reserved";
-            gentle: "gentle";
-        }>>;
-        humor: z.ZodOptional<z.ZodEnum<{
-            none: "none";
-            occasional: "occasional";
-            playful: "playful";
-        }>>;
-        supportMode: z.ZodOptional<z.ZodEnum<{
-            listen: "listen";
-            untangle: "untangle";
-            solutions: "solutions";
-        }>>;
-        detailLevel: z.ZodOptional<z.ZodEnum<{
-            brief: "brief";
-            balanced: "balanced";
-            detailed: "detailed";
-        }>>;
-        proactivity: z.ZodOptional<z.ZodEnum<{
-            open: "open";
-            decisions: "decisions";
-            important: "important";
-        }>>;
-    }, z.core.$strict>>;
     instructions: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const AgentEntrySchema: z.ZodObject<{
@@ -383,35 +325,6 @@ export declare const AgentEntrySchema: z.ZodObject<{
         voiceCallPreferences: z.ZodOptional<z.ZodObject<{
             openingGreetingEnabled: z.ZodBoolean;
         }, z.core.$strict>>;
-        responsePreferences: z.ZodOptional<z.ZodObject<{
-            addressAs: z.ZodOptional<z.ZodString>;
-            guidance: z.ZodOptional<z.ZodString>;
-            warmth: z.ZodOptional<z.ZodEnum<{
-                balanced: "balanced";
-                reserved: "reserved";
-                gentle: "gentle";
-            }>>;
-            humor: z.ZodOptional<z.ZodEnum<{
-                none: "none";
-                occasional: "occasional";
-                playful: "playful";
-            }>>;
-            supportMode: z.ZodOptional<z.ZodEnum<{
-                listen: "listen";
-                untangle: "untangle";
-                solutions: "solutions";
-            }>>;
-            detailLevel: z.ZodOptional<z.ZodEnum<{
-                brief: "brief";
-                balanced: "balanced";
-                detailed: "detailed";
-            }>>;
-            proactivity: z.ZodOptional<z.ZodEnum<{
-                open: "open";
-                decisions: "decisions";
-                important: "important";
-            }>>;
-        }, z.core.$strict>>;
         instructions: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     purpose: z.ZodOptional<z.ZodEnum<{
@@ -553,35 +466,6 @@ export declare const EffectiveAgentConfigSchema: z.ZodObject<{
         voiceCallPreferences: z.ZodOptional<z.ZodObject<{
             openingGreetingEnabled: z.ZodBoolean;
         }, z.core.$strict>>;
-        responsePreferences: z.ZodOptional<z.ZodObject<{
-            addressAs: z.ZodOptional<z.ZodString>;
-            guidance: z.ZodOptional<z.ZodString>;
-            warmth: z.ZodOptional<z.ZodEnum<{
-                balanced: "balanced";
-                reserved: "reserved";
-                gentle: "gentle";
-            }>>;
-            humor: z.ZodOptional<z.ZodEnum<{
-                none: "none";
-                occasional: "occasional";
-                playful: "playful";
-            }>>;
-            supportMode: z.ZodOptional<z.ZodEnum<{
-                listen: "listen";
-                untangle: "untangle";
-                solutions: "solutions";
-            }>>;
-            detailLevel: z.ZodOptional<z.ZodEnum<{
-                brief: "brief";
-                balanced: "balanced";
-                detailed: "detailed";
-            }>>;
-            proactivity: z.ZodOptional<z.ZodEnum<{
-                open: "open";
-                decisions: "decisions";
-                important: "important";
-            }>>;
-        }, z.core.$strict>>;
         instructions: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     purpose: z.ZodOptional<z.ZodEnum<{