@xopcai/xopc 0.0.332 → 0.0.333

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -2,7 +2,7 @@ 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 { AutomationCancelOutputSchema, AutomationDeleteOutputSchema, AutomationMutationOutputSchema, AutomationReadAllInputSchema, AutomationReadAllOutputSchema, AutomationReadOutputSchema, AutomationRecoveryOutputSchema, 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";
 import { TaskRepository } from "../../tasks/task-repository.js";
 import { TaskRunRepository } from "../../tasks/task-run-repository.js";
@@ -42,7 +42,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 {}, product_events {eventType, source?, payloadKey?, payloadValue?, limit?}; payload filters require both key and value. Automation also supports cancel/read {runId, idempotencyKey?} and read_all {projectId?, idempotencyKey?}; omitted projectId means all projects. Cancel acceptance is not confirmation of stopping. Object command. Scene commands: templates, list, get {id}, mail_accounts, mail_search {accountId, query}, mail_sources, read_notes {id}, preflight/start {templateKey, templateVersion, goal, scope, permissions}, configure {id, expectedRevision, goal, scope, permissions}, transition {id, expectedRevision, status: paused|active|completed|archived}, check {id}, notes {id, expectedRevision, content, validUntil?}, work_item {id, subjectId, accountId, dueAt}, update_work_item {workItemId, expectedRevision, dueAt?, status?}, schedule {id, triggerKey, expectedRevision, schedule}, results {id?}, feedback {presentationId, expectedRevision, rating}, mark_read {presentationId, read}, diagnostics, get_preferences, set_preferences {expectedRevision, ...preferences}. Start and check accept a stable requestId for retries. Scenes prepare read-only suggestions and drafts; never send mail. Only create a scene for work explicitly delegated by the user; inspect existing scenes first. Supports project list/get/create/update/resolve_workspace/list_milestones/create_milestone/update_milestone/list_updates/create_update, automation list/get/create/update/delete/run/rerun/pause/resume/history (rerun takes runId; run/rerun accept idempotencyKey), note list/get/project_summaries/history {noteId}/snapshot {noteId, timestamp}/create/append/update/preview_edit/delete, task list/get/create/update_dependencies/add_context/remove_context/command/delete, task_run list/get/cancel, chat_preview create/revise/get, local_app list/get/create/validate, and settings open." }),
+	command: Type.String({ description: "Context resolve takes an explicit AppContextEnvelope; never guess a current page. Automation draft/repair_draft accept prompt/id, agentId?, language?, idempotencyKey?; simulate explains an automation without running it. Local_app record_acceptance records supplied checks and sourceHash, not proof that checks were executed. Agent commands: list, get {id}, create {id, profile, workspace?, models?, skills?, tools?, workflows?, runtime?, idempotencyKey?}, update {id, expectedRevision, patch, idempotencyKey?}, set_default {id, expectedRevision, idempotencyKey?}, disable/delete/purge {id, expectedRevision, idempotencyKey?}. Purge also removes on-disk data. Project create accepts idempotencyKey; update/pin/unpin/delete accepts {projectId, expectedVersion?, idempotencyKey?}; stable retries require the original expectedVersion. Delete preserves workspace files and does not confirm external execution stopped. Project milestone writes support idempotencyKey; update_milestone/delete_milestone require original expectedRevision for stable retries, and create_update requires original expectedVersion. TaskRun cancel accepts idempotencyKey and expectedVersion, and does not confirm external execution stopped. Automation diagnostics: get_run/run_events {runId}, metrics {}, 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. 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." }))
 });
@@ -738,7 +738,7 @@ async function handleAutomation(command, args, deps, dryRun, capabilities) {
 			authorize: deps.authorizeCapability ?? (() => true)
 		};
 		try {
-			return (operation === "xopc.automations.delete" ? AutomationDeleteOutputSchema : operation === "xopc.automations.cancel" ? AutomationCancelOutputSchema : operation === "xopc.automations.read" ? AutomationReadOutputSchema : operation === "xopc.automations.read_all" ? AutomationReadAllOutputSchema : operation === "xopc.automations.run" || operation === "xopc.automations.rerun" ? AutomationRunMutationOutputSchema : AutomationMutationOutputSchema).parse(await capabilities.call(operation, input, caller, {
+			return (operation === "xopc.automations.delete" ? AutomationDeleteOutputSchema : operation === "xopc.automations.cancel" ? AutomationCancelOutputSchema : operation === "xopc.automations.read" ? AutomationReadOutputSchema : operation === "xopc.automations.read_all" ? AutomationReadAllOutputSchema : operation === "xopc.automations.replay_event" || operation === "xopc.automations.retry_delivery" ? AutomationRecoveryOutputSchema : operation === "xopc.automations.run" || operation === "xopc.automations.rerun" ? AutomationRunMutationOutputSchema : AutomationMutationOutputSchema).parse(await capabilities.call(operation, input, caller, {
 				...capabilities.describe(operation, caller),
 				idempotencyKey: trimString(args.idempotencyKey) ?? randomUUID()
 			}));
@@ -761,6 +761,40 @@ async function handleAutomation(command, args, deps, dryRun, capabilities) {
 		};
 		return invoke(`xopc.automations.${command}`, input);
 	}
+	if (command === "replay_event" || command === "retry_delivery") {
+		const reason = trimString(args.reason);
+		if (!reason) return {
+			ok: false,
+			error: "reason is required"
+		};
+		const input = command === "replay_event" ? {
+			id: trimString(args.eventId) ?? trimString(args.id),
+			reason
+		} : {
+			runId: trimString(args.runId) ?? trimString(args.id),
+			destinationKey: trimString(args.destinationKey),
+			reason
+		};
+		if (command === "replay_event" && !input.id) return {
+			ok: false,
+			error: "eventId is required"
+		};
+		if (command === "retry_delivery" && !input.runId) return {
+			ok: false,
+			error: "runId is required"
+		};
+		if (command === "retry_delivery" && !input.destinationKey) return {
+			ok: false,
+			error: "destinationKey is required"
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: command,
+			input
+		};
+		return invoke(`xopc.automations.${command}`, input);
+	}
 	if (command === "create") {
 		const source = automationPayload(args, "automation");
 		const projectId = trimString(args.projectId) ?? trimString(source.projectId) ?? currentProjectId({}, deps);
@@ -781,8 +815,7 @@ async function handleAutomation(command, args, deps, dryRun, capabilities) {
 				"action",
 				"safety",
 				"conversationMode",
-				"notificationPolicy",
-				"completionWebhookUrl",
+				"delivery",
 				"reliability",
 				"state"
 			]),
@@ -817,8 +850,7 @@ async function handleAutomation(command, args, deps, dryRun, capabilities) {
 			"action",
 			"safety",
 			"conversationMode",
-			"notificationPolicy",
-			"completionWebhookUrl",
+			"delivery",
 			"reliability",
 			"state"
 		]));
@@ -1958,9 +1990,18 @@ function createXopcUseTool(deps) {
 				"get_run",
 				"run_events",
 				"metrics",
+				"events",
+				"deliveries",
 				"product_events"
 			].includes(command)) {
-				const projectedInput = command === "metrics" ? {} : command === "product_events" ? {
+				const projectedInput = command === "metrics" ? {} : command === "events" ? {
+					type: args.eventType,
+					source: args.source,
+					limit: args.limit
+				} : command === "deliveries" ? {
+					runId: args.runId,
+					limit: args.limit
+				} : command === "product_events" ? {
 					eventType: args.eventType,
 					source: args.source,
 					payloadKey: args.payloadKey,

package/dist/src/ai-assist/text-assist.js

@@ -2,6 +2,7 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { getDefaultModelSync, init_providers, resolveModel } from "../providers/index.js";
 import { createExtensionAwareStreamFn } from "../providers/extension-stream-bridge.js";
+import { trackAiUsageStream } from "../usage/recorder.js";
 import { isLocalModelBaseUrl, resolveModelCallApiKey, resolveModelCallOptions } from "../providers/model-call.js";
 import { getAssistantMessageErrorReason, stripCodeFences } from "../providers/model-response.js";
 import { normalizeContext } from "@earendil-works/pi-ai";
@@ -245,7 +246,10 @@ async function* streamTextAssist(request, config, signal) {
 		modelId: model.id,
 		scenario: scenario.id
 	};
-	const stream = await createExtensionAwareStreamFn()(model, normalizeContext(prompt), modelCallOptions);
+	const stream = await trackAiUsageStream(model, {
+		operation: "text_assist.generate",
+		trigger: "user"
+	}, () => createExtensionAwareStreamFn()(model, normalizeContext(prompt), modelCallOptions));
 	let streamedText = "";
 	for await (const event of stream) {
 		const streamEvent = event;

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

@@ -101,6 +101,71 @@ function registerAutomationRoutes(authenticated, deps) {
 			return capabilityHttpError(c, error);
 		}
 	});
+	authenticated.get("/api/automation-events", async (c) => {
+		try {
+			const { items } = ProductReadContracts["xopc.automations.events"].output.parse(await capabilities.call("xopc.automations.events", {
+				type: c.req.query("type"),
+				source: c.req.query("source"),
+				limit: c.req.query("limit") === void 0 ? void 0 : Number(c.req.query("limit"))
+			}, capabilityHttpContext(c)));
+			return c.json({ items });
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
+	});
+	authenticated.get("/api/automation-deliveries", async (c) => {
+		try {
+			const { items } = ProductReadContracts["xopc.automations.deliveries"].output.parse(await capabilities.call("xopc.automations.deliveries", {
+				runId: c.req.query("runId"),
+				status: c.req.query("status"),
+				limit: c.req.query("limit") === void 0 ? void 0 : Number(c.req.query("limit"))
+			}, capabilityHttpContext(c)));
+			return c.json({ items });
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
+	});
+	authenticated.post("/api/automation-events/:eventId/replay", async (c) => {
+		try {
+			const idempotencyKey = c.req.header("idempotency-key")?.trim();
+			if (!idempotencyKey) throw new CapabilityError("INVALID_INPUT", "Idempotency-Key is required");
+			const body = await c.req.json().catch(() => {
+				throw new CapabilityError("INVALID_INPUT", "Invalid JSON body");
+			});
+			const caller = capabilityHttpContext(c);
+			const operation = "xopc.automations.replay_event";
+			return c.json(await capabilities.call(operation, {
+				...body,
+				id: c.req.param("eventId")
+			}, caller, {
+				...capabilities.describe(operation, caller),
+				idempotencyKey
+			}), 202);
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
+	});
+	authenticated.post("/api/automation-deliveries/:runId/:destinationKey/retry", async (c) => {
+		try {
+			const idempotencyKey = c.req.header("idempotency-key")?.trim();
+			if (!idempotencyKey) throw new CapabilityError("INVALID_INPUT", "Idempotency-Key is required");
+			const body = await c.req.json().catch(() => {
+				throw new CapabilityError("INVALID_INPUT", "Invalid JSON body");
+			});
+			const caller = capabilityHttpContext(c);
+			const operation = "xopc.automations.retry_delivery";
+			return c.json(await capabilities.call(operation, {
+				...body,
+				runId: c.req.param("runId"),
+				destinationKey: c.req.param("destinationKey")
+			}, caller, {
+				...capabilities.describe(operation, caller),
+				idempotencyKey
+			}), 202);
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
+	});
 	authenticated.get("/api/automation-runs/product-events", async (c) => {
 		try {
 			const { items } = ProductReadContracts["xopc.automations.product_events"].output.parse(await capabilities.call("xopc.automations.product_events", {

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

@@ -57,6 +57,30 @@ function registerAutomationReadCapabilities(dispatcher, service, projects) {
 			};
 		}
 	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.automations.events",
+		description: "Inspect durable trigger events and per-automation delivery state.",
+		...ProductReadContracts["xopc.automations.events"],
+		execute(input) {
+			return {
+				ok: true,
+				items: service.listEventRecords(input)
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		...policy,
+		id: "xopc.automations.deliveries",
+		description: "Inspect durable automation result delivery state.",
+		...ProductReadContracts["xopc.automations.deliveries"],
+		execute(input) {
+			return {
+				ok: true,
+				items: service.listResultDeliveries(input)
+			};
+		}
+	}));
 	dispatcher.register(defineReadCapability({
 		...policy,
 		id: "xopc.automations.product_events",

package/dist/src/automations/capabilities/write.d.ts

@@ -168,15 +168,34 @@ export declare const AutomationCreateCapabilityInputSchema: z.ZodObject<{
         new_session: "new_session";
         continuous: "continuous";
     }>>;
-    notificationPolicy: z.ZodDefault<z.ZodEnum<{
-        attention: "attention";
-        all: "all";
-        none: "none";
-    }>>;
-    completionWebhookUrl: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string>>;
+    delivery: z.ZodDefault<z.ZodObject<{
+        notificationPolicy: z.ZodDefault<z.ZodEnum<{
+            attention: "attention";
+            all: "all";
+            none: "none";
+        }>>;
+        destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"gateway_event">;
+        }, z.core.$strict>, z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"webhook">;
+            endpoint: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            secretId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"file">;
+            targetId: z.ZodString;
+            pathTemplate: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"card">;
+            channelId: z.ZodString;
+            templateId: z.ZodString;
+        }, z.core.$strict>], "kind">>>;
+    }, z.core.$strict>>;
     reliability: z.ZodOptional<z.ZodObject<{
         executionTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
-        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
         retryCount: z.ZodOptional<z.ZodNumber>;
         maxConcurrentRuns: z.ZodOptional<z.ZodNumber>;
         disableAfterConsecutiveFailures: z.ZodOptional<z.ZodNumber>;
@@ -343,10 +362,8 @@ export declare const AutomationUpdatePatchSchema: z.ZodObject<{
             auto_apply: "auto_apply";
         }>;
     }, z.core.$strict>>>;
-    completionWebhookUrl: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string>>>;
     reliability: z.ZodOptional<z.ZodOptional<z.ZodObject<{
         executionTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
-        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
         retryCount: z.ZodOptional<z.ZodNumber>;
         maxConcurrentRuns: z.ZodOptional<z.ZodNumber>;
         disableAfterConsecutiveFailures: z.ZodOptional<z.ZodNumber>;
@@ -355,11 +372,32 @@ export declare const AutomationUpdatePatchSchema: z.ZodObject<{
         new_session: "new_session";
         continuous: "continuous";
     }>>;
-    notificationPolicy: z.ZodOptional<z.ZodEnum<{
-        attention: "attention";
-        all: "all";
-        none: "none";
-    }>>;
+    delivery: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        notificationPolicy: z.ZodDefault<z.ZodEnum<{
+            attention: "attention";
+            all: "all";
+            none: "none";
+        }>>;
+        destinations: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"gateway_event">;
+        }, z.core.$strict>, z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"webhook">;
+            endpoint: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            secretId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"file">;
+            targetId: z.ZodString;
+            pathTemplate: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodLiteral<"card">;
+            channelId: z.ZodString;
+            templateId: z.ZodString;
+        }, z.core.$strict>], "kind">>>;
+    }, z.core.$strict>>>;
     state: z.ZodOptional<z.ZodNever>;
     management: z.ZodOptional<z.ZodNever>;
 }, z.core.$strict>;