@xopcai/xopc 0.0.321 → 0.0.323

package/dist/src/agent/source-context/types.d.ts

@@ -12,11 +12,13 @@ export interface SessionSourceBinding {
     attachedAt: number;
 }
 export interface TurnContextRef {
+    refId?: string;
     kind: 'note' | 'task' | 'file' | 'session' | 'browser_tab' | 'mcp_resource';
     sourceId: string;
     expectedVersion?: string;
 }
 export interface SourceContextRefSummary {
+    refId?: string;
     kind: AgentSourceContext['kind'];
     sourceId: string;
     version: string;
@@ -29,6 +31,7 @@ export interface SourceContextRefSummary {
     fileKind?: 'file' | 'directory';
 }
 export interface AgentSourceContext {
+    refId?: string;
     kind: SessionSourceBinding['kind'] | 'task' | 'file' | 'session' | 'mcp_resource' | 'browser_tab' | 'browser_page' | 'app_context';
     sourceId: string;
     version: string;

package/dist/src/agent/source-context/types.js

@@ -1,6 +1,7 @@
 //#region src/agent/source-context/types.ts
 function summarizeSourceContext(context) {
 	return {
+		refId: context.refId,
 		kind: context.kind,
 		sourceId: context.sourceId,
 		version: context.version,
@@ -16,16 +17,21 @@ function summarizeSourceContext(context) {
 function isTurnContextRef(value) {
 	if (!value || typeof value !== "object") return false;
 	const row = value;
-	return (row.kind === "note" || row.kind === "task" || row.kind === "file" || row.kind === "session" || row.kind === "browser_tab" || row.kind === "mcp_resource") && typeof row.sourceId === "string" && row.sourceId.trim().length > 0 && (row.expectedVersion === void 0 || typeof row.expectedVersion === "string");
+	return (row.kind === "note" || row.kind === "task" || row.kind === "file" || row.kind === "session" || row.kind === "browser_tab" || row.kind === "mcp_resource") && typeof row.sourceId === "string" && row.sourceId.trim().length > 0 && (row.refId === void 0 || typeof row.refId === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(row.refId)) && (row.expectedVersion === void 0 || typeof row.expectedVersion === "string");
 }
 function parseTurnContextRefs(value, max = 5) {
 	if (value === void 0) return [];
 	if (!Array.isArray(value) || value.length > max || !value.every(isTurnContextRef)) return null;
-	return value.map((ref) => ({
+	const refs = value.map((ref) => ({
+		...ref.refId ? { refId: ref.refId } : {},
 		kind: ref.kind,
 		sourceId: ref.sourceId.trim(),
 		...ref.expectedVersion ? { expectedVersion: ref.expectedVersion } : {}
 	}));
+	const refIds = refs.flatMap((ref) => ref.refId ? [ref.refId] : []);
+	const sources = refs.map((ref) => `${ref.kind}:${ref.sourceId}`);
+	if (new Set(refIds).size !== refIds.length || new Set(sources).size !== sources.length) return null;
+	return refs;
 }
 function isSessionSourceBinding(value) {
 	if (!value || typeof value !== "object") return false;

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\": \"scene | project | automation | note | task | task_run | 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| 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| 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## 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## Local apps and settings\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\": \"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| 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## 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";

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

@@ -8,7 +8,7 @@ Load this manual before a non-trivial mutation.
 
 \`\`\`json
 {
-  "mode": "scene | project | automation | note | task | task_run | local_app | settings",
+  "mode": "scene | project | automation | note | task | task_run | chat_preview | local_app | settings",
   "command": "...",
   "args": {},
   "dryRun": false
@@ -35,6 +35,7 @@ language. A scene prepares suggestions or drafts and never sends mail or perform
 | Task intent and lifecycle | \`xopc_use\` mode \`task\` |
 | Task execution attempt, receipt, events and waits | \`xopc_use\` mode \`task_run\` |
 | Note | \`xopc_use\` mode \`note\` |
+| Lightweight UI preview | \`xopc_use\` mode \`chat_preview\` |
 | Local app | \`xopc_use\` mode \`local_app\` |
 | Settings jump target | \`xopc_use\` mode \`settings\` |
 | Workflow run | dedicated \`workflow\` tool; pass \`taskId\` to link it to a Task |
@@ -409,7 +410,16 @@ user's intent is ambiguous.
 { "mode": "note", "command": "delete", "args": { "noteId": "note_id" }, "dryRun": true }
 \`\`\`
 
-## Local apps and settings
+## Chat previews, local apps, and settings
+
+Use \`chat_preview\` by default when the user asks to design, mock up, or quickly show a UI in
+the current conversation. It creates no Project and no Local App. Commands are \`create\`,
+\`get\`, and \`revise\`. Source consists of \`markup\`, \`styles\`, and optional \`script\`;
+do not include a full HTML document or remote dependencies. Revision requires the exact
+\`baseRevision\` returned by the prior call.
+
+Use \`local_app\` only when the user explicitly asks for a durable, installable app or chooses
+“Save as app” on a chat preview. Do not create a Local App merely to render a UI draft.
 
 Local app commands are \`list\`, \`get\`, \`create\`, and \`validate\`. Installation,
 activation, rollback, and uninstall remain product runtime operations.

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

@@ -59,7 +59,7 @@ function formatAutomation(item) {
 }
 function automationDelivery(automation, operation) {
 	return {
-		version: 1,
+		version: 2,
 		operation,
 		primary: {
 			kind: "automation",

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

@@ -63,6 +63,7 @@ export interface ToolFactoryDeps {
     getProjectService?: () => ProjectService | undefined;
     getWorkDiscovery?: () => import('../../work-discovery/service.js').WorkDiscoveryService | undefined;
     getLocalAppService?: () => LocalAppService | undefined;
+    getChatPreviewService?: () => import('../../chat-previews/index.js').ChatPreviewService | undefined;
     /** Gateway: publishes durable Task change notifications. */
     dispatchTaskEvents?: () => void;
     /** Gateway: queues Task execution for xopc_use task start/resume/verify actions. */

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

@@ -429,7 +429,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 				getProjectService: this.deps.getProjectService
 			})] : [],
 			...browserEnabled && this.deps.getBrowserAutomationService ? [createBrowserAutomationTool({ getBrowserAutomationService: this.deps.getBrowserAutomationService })] : [],
-			...this.deps.getAutomationService || this.deps.getSceneAccess || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool({
+			...this.deps.getAutomationService || this.deps.getSceneAccess || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.getChatPreviewService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool({
 				getWorkspace: () => this.deps.workspace,
 				getConfig: () => this.deps.getConfig?.(),
 				getCurrentAgentId: () => options.agentId,
@@ -440,6 +440,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 				getProjectService: this.deps.getProjectService,
 				getWorkDiscovery: this.deps.getWorkDiscovery,
 				getLocalAppService: this.deps.getLocalAppService,
+				getChatPreviewService: this.deps.getChatPreviewService,
 				dispatchTaskEvents: this.deps.dispatchTaskEvents,
 				dispatchTaskRuns: this.deps.dispatchTaskRuns
 			})] : [],

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

@@ -82,7 +82,7 @@ function createWorkflowTool(deps) {
 				};
 				const summary = goal ? `Started workflow \`${definitionId}\` (run ${result.runId}). Open chat session to track progress and continue.` : `Started workflow \`${definitionId}\` (run ${result.runId}). Open the workflow chat session to track progress.`;
 				const delivery = {
-					version: 1,
+					version: 2,
 					operation: "started",
 					primary: {
 						kind: "workflow_run",

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

@@ -50,7 +50,7 @@ function createWriteFileTool(workspace, options) {
 				const target = writesProfileFile ? resolveProfileMarkdownPathIfBareName(p.path, options.profileMarkdownRoot) : resolvePathUnderWorkspace(p.path, workspace);
 				writeWorkspaceFile(workspaceRoot, target, p.content);
 				const delivery = writesProfileFile ? void 0 : await Promise.all([realpath(workspace), realpath(target)]).then(([root, canonicalTarget]) => ({
-					version: 1,
+					version: 2,
 					operation: "updated",
 					primary: {
 						kind: "file",

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

@@ -7,13 +7,14 @@ import type { Config } from '../../config/schema.js';
 import type { NotesService } from '../../notes/index.js';
 import { type ProjectService } from '../../projects/index.js';
 import type { LocalAppService } from '../../local-apps/index.js';
+import type { ChatPreviewService } from '../../chat-previews/index.js';
 declare const XopcUseToolSchema: import("@sinclair/typebox").TObject<{
-    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, import("@sinclair/typebox").TLiteral<"scene">, import("@sinclair/typebox").TLiteral<"project">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"note">, import("@sinclair/typebox").TLiteral<"task">, import("@sinclair/typebox").TLiteral<"task_run">, import("@sinclair/typebox").TLiteral<"local_app">, import("@sinclair/typebox").TLiteral<"settings">]>;
+    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"context">, import("@sinclair/typebox").TLiteral<"scene">, import("@sinclair/typebox").TLiteral<"project">, import("@sinclair/typebox").TLiteral<"automation">, import("@sinclair/typebox").TLiteral<"note">, import("@sinclair/typebox").TLiteral<"task">, import("@sinclair/typebox").TLiteral<"task_run">, import("@sinclair/typebox").TLiteral<"local_app">, import("@sinclair/typebox").TLiteral<"chat_preview">, import("@sinclair/typebox").TLiteral<"settings">]>;
     command: import("@sinclair/typebox").TString;
     args: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TAny>>;
     dryRun: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
-export type XopcUseMode = 'context' | 'scene' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'local_app' | 'settings';
+export type XopcUseMode = 'context' | 'scene' | 'project' | 'automation' | 'note' | 'task' | 'task_run' | 'chat_preview' | 'local_app' | 'settings';
 export interface XopcUseToolInput {
     mode: XopcUseMode;
     command: string;
@@ -32,6 +33,7 @@ export interface XopcUseToolDeps {
     getProjectService?: () => ProjectService | undefined;
     getWorkDiscovery?: () => import('../../work-discovery/service.js').WorkDiscoveryService | undefined;
     getLocalAppService?: () => LocalAppService | undefined;
+    getChatPreviewService?: () => ChatPreviewService | undefined;
     dispatchTaskEvents?: () => void;
     dispatchTaskRuns?: () => void;
 }

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

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

package/dist/src/chat-previews/index.d.ts

@@ -0,0 +1,2 @@
+export * from './service.js';
+export * from './store.js';

package/dist/src/chat-previews/index.js

@@ -0,0 +1,3 @@
+import { ChatPreviewStore } from "./store.js";
+import { ChatPreviewNotFoundError, ChatPreviewRevisionConflictError, ChatPreviewService } from "./service.js";
+export { ChatPreviewNotFoundError, ChatPreviewRevisionConflictError, ChatPreviewService, ChatPreviewStore };

package/dist/src/chat-previews/service.d.ts

@@ -0,0 +1,27 @@
+import { type ChatPreviewCreateInput, type ChatPreviewRecord, type ChatPreviewRevision, type ChatPreviewReviseInput, type ChatPreviewDiagnostic, type ChatPreviewFixGuidance, type LocalAppDetail } from '@xopcai/gateway-contract';
+import type { LocalAppService } from '../local-apps/index.js';
+import { ChatPreviewStore } from './store.js';
+export declare class ChatPreviewNotFoundError extends Error {
+}
+export declare class ChatPreviewRevisionConflictError extends Error {
+}
+export declare class ChatPreviewService {
+    private readonly store;
+    private readonly localApps?;
+    constructor(options?: {
+        store?: ChatPreviewStore;
+        localApps?: LocalAppService;
+    });
+    create(conversationId: string, rawInput: ChatPreviewCreateInput): {
+        preview: ChatPreviewRecord;
+        revision: ChatPreviewRevision;
+    };
+    get(id: string): ChatPreviewRecord;
+    getRevision(id: string, revision: string): ChatPreviewRevision;
+    revise(id: string, rawInput: ChatPreviewReviseInput): {
+        preview: ChatPreviewRecord;
+        revision: ChatPreviewRevision;
+    };
+    getFixGuidance(id: string, sourceHashValue: string, diagnostics: ChatPreviewDiagnostic[], locale: 'en' | 'zh'): ChatPreviewFixGuidance;
+    promote(id: string, sourceHashValue: string): LocalAppDetail;
+}