@xopcai/xopc 0.0.205 → 0.0.207

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\": \"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## Object routing\n\n| Object | Tool |\n| --- | --- |\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## 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 a bounded goal. 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`, and `command`.\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### 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`, and `update`.\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\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\": \"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## Object routing\n\n| Object | Tool |\n| --- | --- |\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## 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`, and `command`.\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### 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`, and `update`.\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\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";

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

@@ -58,7 +58,7 @@ and \`create_update\`.
 Project statuses: \`planned\`, \`active\`, \`paused\`, \`completed\`, \`cancelled\`,
 \`archived\`. Health values: \`unknown\`, \`on_track\`, \`at_risk\`, \`off_track\`.
 
-A Project defines a bounded goal. Its durable planning fields are \`outcome\`,
+A Project defines bounded shared context for related work. Its durable planning fields are \`outcome\`,
 \`successCriteria\`, \`scope\`, \`nonGoals\`, \`ownerId\`, \`targetAt\`, and \`health\`.
 Use \`brief\` for a concise description and \`instructions\` for durable operating guidance.
 

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

@@ -15,6 +15,7 @@ import { createExecCommandTool } from "./exec-command.js";
 import { createApplyPatchTool } from "./apply-patch.js";
 import { createMemoryGetTool, createMemorySearchTool } from "./memory-tool.js";
 import { createSessionSearchTool } from "./session-search-tool.js";
+import { createSessionRecallTool } from "./session-recall-tool.js";
 import { createGrepTool } from "./grep.js";
 import { createFindTool } from "./find.js";
 import { createWebFetchTool, createWebSearchTool } from "./web.js";
@@ -299,6 +300,10 @@ var AgentToolsFactory = class {
 					...this.deps.getCurrentContext?.()?.sessionKey ? { sessionKey: this.deps.getCurrentContext().sessionKey } : {}
 				})
 			})] : [],
+			...this.deps.getSessionStore ? [createSessionRecallTool({
+				getSessionStore: this.deps.getSessionStore,
+				getCurrentSessionKey: () => this.deps.getCurrentContext()?.sessionKey
+			})] : [],
 			...this.deps.getSessionStore && getPrimary ? [createSessionSearchTool({
 				getSessionStore: this.deps.getSessionStore,
 				getPrimaryModel: getPrimary,

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

@@ -7,6 +7,7 @@ export { createExecCommandTool, type ExecCommandDetails, type ExecCommandUpdateD
 export { createApplyPatchTool, type AppliedPatchChange, type ApplyPatchDetails, } from './apply-patch.js';
 export { createMemorySearchTool, createMemoryGetTool, type MemoryToolOptions, } from './memory-tool.js';
 export { createSessionSearchTool } from './session-search-tool.js';
+export { createSessionRecallTool, type SessionRecallToolDeps } from './session-recall-tool.js';
 export { grepTool, createGrepTool, type GrepToolInput, type GrepToolDetails, } from './grep.js';
 export { findTool, createFindTool, type FindToolInput, type FindToolDetails, } from './find.js';
 export { createWebSearchTool, createWebFetchTool } from './web.js';

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

@@ -9,6 +9,7 @@ import { fuzzyFindText, generateDiffString, normalizeForFuzzyMatch, normalizeToL
 import { createApplyPatchTool } from "./apply-patch.js";
 import { createMemoryGetTool, createMemorySearchTool } from "./memory-tool.js";
 import { createSessionSearchTool } from "./session-search-tool.js";
+import { createSessionRecallTool } from "./session-recall-tool.js";
 import { createGrepTool, grepTool } from "./grep.js";
 import { createFindTool, findTool } from "./find.js";
 import { createWebFetchTool, createWebSearchTool } from "./web.js";
@@ -41,4 +42,4 @@ import { createManagedJobTool } from "./managed-job-tool.js";
 import { resolveImageModelConfigForTool } from "../image/tool-model-config.js";
 import { createImageTool } from "./image-tool.js";
 import { createImageGenerateTool, resolveImageGenerationModelConfigForTool } from "./image-generate-tool.js";
-export { BrowserManager, DEFAULT_DELEGATE_TOOLS, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_TOOL_METADATA, DEFAULT_WEB_EXTRACT_MAX_LENGTH, DELEGATE_BLOCKED_TOOLS, GREP_MAX_LINE_LENGTH, MAX_RAW_HTML_CHARS_FOR_WEB_EXTRACT, SANDBOX_ALLOWED_TOOLS, TodoStore, ToolConcurrencyController, assertBrowserUrlAllowed, buildSandboxToolMap, createApplyPatchTool, createAutomationTool, createBrowserRecipeTool, createClarifyTool, createCreateShareTool, createDelegateTool, createDesktopPetTool, createDreamingTool, createExecCommandTool, createExecuteCodeTool, createFindTool, createGrepTool, createImageGenerateTool, createImageTool, createListDirTool, createManagedJobTool, createMemoryGetTool, createMemorySearchTool, createMessageTool, createReadFileTool, createReadMediaTool, createSendMediaTool, createSessionSearchTool, createSessionStatusTool, createSkillInstallTool, createSkillManageTool, createSkillViewTool, createSkillsListTool, createSkillsMarketplaceSearchTool, createTodoTool, createToolManualTool, createUpdatePlanTool, createWebExtractTool, createWebFetchTool, createWebSearchTool, createWorkflowTool, createWriteFileTool, createXopcUseTool, findTool, formatSize, fuzzyFindText, generateDiffString, getToolMetadata, grepTool, isShareToolAvailable, listDirTool, normalizeForFuzzyMatch, normalizeToLF, resolveImageGenerationModelConfigForTool, resolveImageModelConfigForTool, resolveToolLockMode, restoreLineEndings, stripBom, stripHtmlBoilerplate, truncateHead, truncateLine, truncateTail, writeFileTool };
+export { BrowserManager, DEFAULT_DELEGATE_TOOLS, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_TOOL_METADATA, DEFAULT_WEB_EXTRACT_MAX_LENGTH, DELEGATE_BLOCKED_TOOLS, GREP_MAX_LINE_LENGTH, MAX_RAW_HTML_CHARS_FOR_WEB_EXTRACT, SANDBOX_ALLOWED_TOOLS, TodoStore, ToolConcurrencyController, assertBrowserUrlAllowed, buildSandboxToolMap, createApplyPatchTool, createAutomationTool, createBrowserRecipeTool, createClarifyTool, createCreateShareTool, createDelegateTool, createDesktopPetTool, createDreamingTool, createExecCommandTool, createExecuteCodeTool, createFindTool, createGrepTool, createImageGenerateTool, createImageTool, createListDirTool, createManagedJobTool, createMemoryGetTool, createMemorySearchTool, createMessageTool, createReadFileTool, createReadMediaTool, createSendMediaTool, createSessionRecallTool, createSessionSearchTool, createSessionStatusTool, createSkillInstallTool, createSkillManageTool, createSkillViewTool, createSkillsListTool, createSkillsMarketplaceSearchTool, createTodoTool, createToolManualTool, createUpdatePlanTool, createWebExtractTool, createWebFetchTool, createWebSearchTool, createWorkflowTool, createWriteFileTool, createXopcUseTool, findTool, formatSize, fuzzyFindText, generateDiffString, getToolMetadata, grepTool, isShareToolAvailable, listDirTool, normalizeForFuzzyMatch, normalizeToLF, resolveImageGenerationModelConfigForTool, resolveImageModelConfigForTool, resolveToolLockMode, restoreLineEndings, stripBom, stripHtmlBoilerplate, truncateHead, truncateLine, truncateTail, writeFileTool };

package/dist/src/agent/tools/session-recall-tool.d.ts

@@ -0,0 +1,7 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { SessionStore } from '../../session/store.js';
+export interface SessionRecallToolDeps {
+    getSessionStore: () => SessionStore;
+    getCurrentSessionKey: () => string | undefined;
+}
+export declare function createSessionRecallTool(deps: SessionRecallToolDeps): AgentTool;

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

@@ -0,0 +1,82 @@
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/session-recall-tool.ts
+const SessionRecallSchema = Type.Object({
+	query: Type.String({
+		minLength: 1,
+		maxLength: 500,
+		description: "Keywords, an exact phrase, path, URL, ID, date, or name to find in this session."
+	}),
+	limit: Type.Optional(Type.Integer({
+		minimum: 1,
+		maximum: 20,
+		default: 8
+	})),
+	beforeSeq: Type.Optional(Type.Integer({
+		minimum: 1,
+		description: "Return matches older than this transcript sequence number."
+	})),
+	maxCharsPerResult: Type.Optional(Type.Integer({
+		minimum: 500,
+		maximum: 2e4,
+		default: 6e3
+	}))
+});
+function excerpt(content, query, maxChars) {
+	if (content.length <= maxChars) return content;
+	const matchAt = content.toLowerCase().indexOf(query.toLowerCase());
+	const center = matchAt >= 0 ? matchAt + Math.floor(query.length / 2) : Math.floor(content.length / 2);
+	const start = Math.max(0, Math.min(content.length - maxChars, center - Math.floor(maxChars / 2)));
+	const end = Math.min(content.length, start + maxChars);
+	return `${start > 0 ? "…\n" : ""}${content.slice(start, end)}${end < content.length ? "\n…" : ""}`;
+}
+function createSessionRecallTool(deps) {
+	return {
+		name: "session_recall",
+		label: "Session recall",
+		description: "Search the authoritative raw transcript of the current session, including turns older than context compaction. Use when a continuation summary lacks an exact fact, quote, path, URL, ID, date, decision, or tool outcome. This tool cannot access other sessions.",
+		parameters: SessionRecallSchema,
+		supportsParallel: true,
+		idempotent: true,
+		async execute(_toolCallId, params) {
+			const input = params;
+			const sessionKey = deps.getCurrentSessionKey();
+			if (!sessionKey) return {
+				content: [{
+					type: "text",
+					text: "session_recall is unavailable outside an active session."
+				}],
+				details: { error: "missing_session" }
+			};
+			const query = input.query.trim();
+			const limit = Math.min(20, Math.max(1, input.limit ?? 8));
+			const maxChars = Math.min(2e4, Math.max(500, input.maxCharsPerResult ?? 6e3));
+			const results = deps.getSessionStore().recallSession(sessionKey, query, {
+				limit,
+				...input.beforeSeq ? { beforeSeq: input.beforeSeq } : {}
+			}).map((match) => ({
+				seq: match.seq,
+				entryId: match.entryId,
+				role: match.role,
+				createdAt: new Date(match.createdAt).toISOString(),
+				content: excerpt(match.content, query, maxChars)
+			}));
+			const nextBeforeSeq = results.length === limit ? Math.min(...results.map((result) => result.seq)) : void 0;
+			const payload = {
+				success: true,
+				query,
+				results,
+				count: results.length,
+				...nextBeforeSeq ? { nextBeforeSeq } : {}
+			};
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(payload, null, 2)
+				}],
+				details: payload
+			};
+		}
+	};
+}
+//#endregion
+export { createSessionRecallTool };

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

@@ -747,7 +747,9 @@ async function handleAutomation(command, args, deps, dryRun) {
 				"trigger",
 				"action",
 				"safety",
-				"afterRun",
+				"conversationMode",
+				"notificationPolicy",
+				"completionWebhookUrl",
 				"reliability",
 				"state"
 			]),
@@ -781,7 +783,9 @@ async function handleAutomation(command, args, deps, dryRun) {
 			"trigger",
 			"action",
 			"safety",
-			"afterRun",
+			"conversationMode",
+			"notificationPolicy",
+			"completionWebhookUrl",
 			"reliability",
 			"state"
 		]));

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

@@ -115,6 +115,14 @@ function registerAutomationRoutes(authenticated, deps) {
 		const events = await service.automationServiceInstance.listRunEvents(runId);
 		return c.json({ events });
 	});
+	authenticated.post("/api/automation-runs/:runId/read", async (c) => {
+		if (!await service.automationServiceInstance.markRunRead(c.req.param("runId"))) return c.json({ error: "Run not found" }, 404);
+		return c.json({ marked: true });
+	});
+	authenticated.post("/api/automation-runs/read-all", async (c) => {
+		const count = await service.automationServiceInstance.markAllRunsRead({ projectId: c.req.query("projectId") });
+		return c.json({ count });
+	});
 	authenticated.post("/api/automation-runs/:runId/rerun", async (c) => {
 		try {
 			const run = await service.automationServiceInstance.rerunFromRun(c.req.param("runId"));

package/dist/src/automations/domain/index.js

@@ -1,4 +1,4 @@
 import { DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds } from "./defaults.js";
 import { computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, timerDelayUntil } from "./schedule.js";
-import { AutomationActionSchema, AutomationAfterRunSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema } from "./validation.js";
-export { AutomationActionSchema, AutomationAfterRunSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, UpdateAutomationSchema, computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds, timerDelayUntil };
+import { AutomationActionSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema } from "./validation.js";
+export { AutomationActionSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, UpdateAutomationSchema, computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds, timerDelayUntil };

package/dist/src/automations/domain/types.d.ts

@@ -55,14 +55,8 @@ export type AutomationAction = {
     taskId: string;
     command: TaskCommand;
 };
-export type AutomationAfterRun = {
-    kind: 'none';
-} | {
-    kind: 'saveToSession';
-} | {
-    kind: 'webhook';
-    url: string;
-};
+export type AutomationConversationMode = 'new_session' | 'continuous';
+export type AutomationNotificationPolicy = 'attention' | 'all' | 'none';
 export interface AutomationReliability {
     /** Overall run deadline. `timeoutSeconds` remains a read-only legacy fallback. */
     executionTimeoutSeconds?: number;
@@ -71,7 +65,7 @@ export interface AutomationReliability {
     maxConcurrentRuns?: number;
     disableAfterConsecutiveFailures?: number;
 }
-export type AutomationRunPhase = 'queued' | 'action' | 'after_run' | 'cancelling' | 'completed';
+export type AutomationRunPhase = 'queued' | 'action' | 'completion_hook' | 'cancelling' | 'completed';
 export interface AutomationRunTermination {
     reason: 'completed' | 'failed' | 'user_cancelled' | 'deadline_exceeded';
     component?: 'automation' | 'agent_turn' | 'tool' | 'mcp' | 'process';
@@ -99,7 +93,9 @@ export interface Automation {
     trigger: AutomationTrigger;
     action: AutomationAction;
     safety?: AutomationSafetyPolicy;
-    afterRun?: AutomationAfterRun;
+    conversationMode: AutomationConversationMode;
+    notificationPolicy: AutomationNotificationPolicy;
+    completionWebhookUrl?: string;
     reliability?: AutomationReliability;
     state: AutomationState;
     createdAtMs: number;
@@ -133,8 +129,9 @@ export interface AutomationRun {
     leaseExpiresAtMs?: number;
     attemptNumber?: number;
     rootRunId?: string;
+    readAtMs?: number;
 }
-export type AutomationRunEventType = 'run.queued' | 'run.started' | 'run.deadline_resolved' | 'run.cancel_requested' | 'run.cancel_confirmed' | 'run.cancellation_unconfirmed' | 'run.recovered' | 'action.started' | 'action.retry_scheduled' | 'action.completed' | 'action.failed' | 'after_run.started' | 'after_run.completed' | 'after_run.failed' | 'run.completed';
+export type AutomationRunEventType = 'run.queued' | 'run.started' | 'run.deadline_resolved' | 'run.cancel_requested' | 'run.cancel_confirmed' | 'run.cancellation_unconfirmed' | 'run.recovered' | 'action.started' | 'action.retry_scheduled' | 'action.completed' | 'action.failed' | 'completion_hook.started' | 'completion_hook.completed' | 'completion_hook.failed' | 'run.completed';
 export interface AutomationRunEvent {
     id: string;
     runId: string;
@@ -165,6 +162,14 @@ export interface AutomationMetrics {
         runAtMs: number;
     };
 }
+export interface PrepareAutomationAgentSessionInput {
+    sessionKey: string;
+    projectId?: string;
+    agentId: string;
+    peerId: string;
+    automationId: string;
+    runId: string;
+}
 export interface AutomationDeps {
     agentService?: {
         sessionConfig?: {
@@ -181,7 +186,7 @@ export interface AutomationDeps {
         getModelForSession?: (sessionKey: string) => string | undefined;
     };
     getDefaultAgentId?: () => string;
-    getProjectWorkspaceRoot?: (projectId: string) => string | undefined;
+    prepareAgentSession?: (input: PrepareAutomationAgentSessionInput) => Promise<void>;
     workflowRunService?: WorkflowRunServiceLike;
     browserRecipeService?: {
         runAndWait(recipeId: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<{

package/dist/src/automations/domain/validation.d.ts

@@ -152,14 +152,6 @@ export declare const AutomationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
         }, z.core.$strip>;
     }, z.core.$strip>], "type">;
 }, z.core.$strict>], "kind">;
-export declare const AutomationAfterRunSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    kind: z.ZodLiteral<"none">;
-}, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"saveToSession">;
-}, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"webhook">;
-    url: z.ZodString;
-}, z.core.$strict>], "kind">;
 export declare const AutomationReliabilitySchema: z.ZodObject<{
     executionTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
     timeoutSeconds: z.ZodOptional<z.ZodNumber>;
@@ -344,14 +336,16 @@ export declare const AutomationSchema: z.ZodObject<{
             auto_apply: "auto_apply";
         }>;
     }, z.core.$strict>>;
-    afterRun: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"none">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"saveToSession">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"webhook">;
-        url: z.ZodString;
-    }, z.core.$strict>], "kind">>;
+    conversationMode: z.ZodDefault<z.ZodEnum<{
+        new_session: "new_session";
+        continuous: "continuous";
+    }>>;
+    notificationPolicy: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        all: "all";
+        attention: "attention";
+    }>>;
+    completionWebhookUrl: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
     reliability: z.ZodOptional<z.ZodObject<{
         executionTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
         timeoutSeconds: z.ZodOptional<z.ZodNumber>;
@@ -530,14 +524,6 @@ export declare const CreateAutomationSchema: z.ZodObject<{
         source: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
         payloadMatch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
     }, z.core.$strict>], "kind">;
-    afterRun: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"none">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"saveToSession">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"webhook">;
-        url: z.ZodString;
-    }, z.core.$strict>], "kind">>;
     reliability: z.ZodOptional<z.ZodObject<{
         executionTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
         timeoutSeconds: z.ZodOptional<z.ZodNumber>;
@@ -545,6 +531,16 @@ export declare const CreateAutomationSchema: z.ZodObject<{
         maxConcurrentRuns: z.ZodOptional<z.ZodNumber>;
         disableAfterConsecutiveFailures: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    conversationMode: z.ZodDefault<z.ZodEnum<{
+        new_session: "new_session";
+        continuous: "continuous";
+    }>>;
+    notificationPolicy: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        all: "all";
+        attention: "attention";
+    }>>;
+    completionWebhookUrl: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
     id: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
     enabled: z.ZodOptional<z.ZodBoolean>;
     state: z.ZodOptional<z.ZodObject<{
@@ -733,14 +729,6 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
         lastError: z.ZodOptional<z.ZodString>;
         consecutiveFailures: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
-    afterRun: z.ZodOptional<z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"none">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"saveToSession">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"webhook">;
-        url: z.ZodString;
-    }, z.core.$strict>], "kind">>>;
     reliability: z.ZodOptional<z.ZodOptional<z.ZodObject<{
         executionTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
         timeoutSeconds: z.ZodOptional<z.ZodNumber>;
@@ -748,6 +736,16 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
         maxConcurrentRuns: z.ZodOptional<z.ZodNumber>;
         disableAfterConsecutiveFailures: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
+    conversationMode: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        new_session: "new_session";
+        continuous: "continuous";
+    }>>>;
+    notificationPolicy: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        all: "all";
+        attention: "attention";
+    }>>>;
+    completionWebhookUrl: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>>>;
 }, z.core.$strict>;
 export type CreateAutomationInput = z.infer<typeof CreateAutomationSchema>;
 export type UpdateAutomationInput = z.infer<typeof UpdateAutomationSchema>;

package/dist/src/automations/domain/validation.js

@@ -94,14 +94,6 @@ const AutomationActionSchema = z.discriminatedUnion("kind", [
 		command: TaskCommandSchema
 	}).strict()
 ]);
-const AutomationAfterRunSchema = z.discriminatedUnion("kind", [
-	z.object({ kind: z.literal("none") }).strict(),
-	z.object({ kind: z.literal("saveToSession") }).strict(),
-	z.object({
-		kind: z.literal("webhook"),
-		url: nonEmptyString.max(2e3)
-	}).strict()
-]);
 const AutomationReliabilitySchema = z.object({
 	executionTimeoutSeconds: z.number().int().min(1).max(86400).optional(),
 	timeoutSeconds: z.number().int().min(1).max(86400).optional(),
@@ -139,7 +131,13 @@ const AutomationSchema = z.object({
 	trigger: AutomationTriggerSchema,
 	action: AutomationActionSchema,
 	safety: AutomationSafetyPolicySchema.optional(),
-	afterRun: AutomationAfterRunSchema.optional(),
+	conversationMode: z.enum(["new_session", "continuous"]).default("new_session"),
+	notificationPolicy: z.enum([
+		"attention",
+		"all",
+		"none"
+	]).default("attention"),
+	completionWebhookUrl: optionalTrimmedString(2e3),
 	reliability: AutomationReliabilitySchema.optional(),
 	state: AutomationStateSchema.default({}),
 	createdAtMs: z.number().int().nonnegative(),
@@ -162,4 +160,4 @@ const UpdateAutomationSchema = AutomationSchema.omit({
 	updatedAtMs: true
 }).partial().refine((data) => Object.keys(data).length > 0, { message: "At least one field must be provided" });
 //#endregion
-export { AutomationActionSchema, AutomationAfterRunSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema };
+export { AutomationActionSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema };

package/dist/src/automations/draft/automation-draft-prompt.js

@@ -10,8 +10,9 @@ JSON shape:
     "trigger": { "kind": "manual" },
     "action": { "kind": "agent", "instruction": "clear instruction for the agent" },
     "safety": { "mode": "suggest_only" },
-    "afterRun": { "kind": "none" },
-    "reliability": { "timeoutSeconds": 300, "disableAfterConsecutiveFailures": 3 }
+    "conversationMode": "new_session",
+    "notificationPolicy": "attention",
+    "reliability": { "executionTimeoutSeconds": 300, "disableAfterConsecutiveFailures": 3 }
   },
   "explanation": "Short explanation",
   "assumptions": ["..."],
@@ -49,8 +50,9 @@ Rules:
 - Default to safety { "mode": "suggest_only" } unless the user explicitly asks for fully automatic execution.
 - Do not invent destructive actions. For deletion, external sending, or irreversible changes, include a risk and make the instruction ask for confirmation.
 - Use cron for daily/weekly schedules. Use standard 5-field cron.
-- Keep timeoutSeconds between 60 and 1800.
-- afterRun should usually be { "kind": "none" }.
+- Keep executionTimeoutSeconds between 60 and 1800.
+- Use conversationMode "new_session" unless the user explicitly wants each run to continue the same conversation.
+- Use notificationPolicy "attention" unless the user explicitly requests every-run notifications or no notifications.
 - Language for user-facing copy: ${params.language ?? "en"}.
 
 User request:
@@ -82,7 +84,9 @@ JSON shape:
     "trigger": "optional complete trigger object",
     "action": "optional complete action object",
     "safety": "optional complete safety object",
-    "afterRun": "optional complete afterRun object",
+    "conversationMode": "optional new_session or continuous",
+    "notificationPolicy": "optional attention, all, or none",
+    "completionWebhookUrl": "optional HTTPS URL",
     "reliability": "optional complete reliability object",
     "enabled": true
   },

package/dist/src/automations/draft/automation-draft-validator.d.ts

@@ -11,6 +11,8 @@ export declare function buildAutomationDraftResponse(draft: GeneratedAutomationD
     draftId: `${string}-${string}-${string}-${string}-${string}`;
     automation: {
         name: string;
+        conversationMode: "new_session" | "continuous";
+        notificationPolicy: "none" | "all" | "attention";
         projectId?: string;
         action?: {
             kind: "agent";
@@ -130,14 +132,6 @@ export declare function buildAutomationDraftResponse(draft: GeneratedAutomationD
             source?: string;
             payloadMatch?: Record<string, string | number | boolean>;
         };
-        afterRun?: {
-            kind: "none";
-        } | {
-            kind: "saveToSession";
-        } | {
-            kind: "webhook";
-            url: string;
-        };
         reliability?: {
             executionTimeoutSeconds?: number;
             timeoutSeconds?: number;
@@ -145,6 +139,7 @@ export declare function buildAutomationDraftResponse(draft: GeneratedAutomationD
             maxConcurrentRuns?: number;
             disableAfterConsecutiveFailures?: number;
         };
+        completionWebhookUrl?: string;
         id?: string;
         enabled?: boolean;
         state?: {

package/dist/src/automations/draft/automation-draft-validator.js

@@ -54,8 +54,8 @@ function simulateAutomation(input) {
 	const triggerSummary = summarizeTrigger(automation.trigger);
 	const actionSummary = summarizeAction(automation.action);
 	if (automation.action.kind === "agent" && /delete|remove|send|post|publish|付款|删除|发送|发布/i.test(automation.action.instruction)) requiredConfirmations.push("Agent instruction may perform an external or destructive action.");
-	if (automation.afterRun?.kind === "webhook") {
-		safetyNotes.push("After-run webhook will call an external URL after each run.");
+	if (automation.completionWebhookUrl) {
+		safetyNotes.push("The completion webhook will call an external URL after each run.");
 		requiredConfirmations.push("External webhook call should be reviewed before publishing.");
 	}
 	const safetyMode = automation.safety?.mode ?? "auto_apply";
@@ -96,7 +96,7 @@ function summarizeAction(action) {
 }
 function repairPatchNeedsApproval(patch) {
 	if (patch.safety?.mode === "auto_apply") return true;
-	if (patch.afterRun?.kind === "webhook") return true;
+	if (patch.completionWebhookUrl) return true;
 	if (patch.trigger?.kind === "webhook") return true;
 	if (patch.action?.kind === "agent") return /delete|remove|send|post|publish|付款|删除|发送|发布/i.test(patch.action.instruction);
 	return false;

package/dist/src/automations/index.js

@@ -1,9 +1,9 @@
 import { DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds } from "./domain/defaults.js";
 import { computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, timerDelayUntil } from "./domain/schedule.js";
-import { AutomationActionSchema, AutomationAfterRunSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema } from "./domain/validation.js";
+import { AutomationActionSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema } from "./domain/validation.js";
 import "./domain/index.js";
 import { AutomationActionExecutor } from "./service/action-executor.js";
 import { AutomationAlreadyRunningError, AutomationService } from "./service/automation-service.js";
 import "./service/index.js";
 import { onAutomationProductEvent, publishAutomationProductEvent } from "./product-events.js";
-export { AutomationActionExecutor, AutomationActionSchema, AutomationAfterRunSchema, AutomationAlreadyRunningError, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationService, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, UpdateAutomationSchema, computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, defaultAutomationTimeoutSeconds, onAutomationProductEvent, publishAutomationProductEvent, resolveAutomationTimeoutSeconds, timerDelayUntil };
+export { AutomationActionExecutor, AutomationActionSchema, AutomationAlreadyRunningError, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationService, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, UpdateAutomationSchema, computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, defaultAutomationTimeoutSeconds, onAutomationProductEvent, publishAutomationProductEvent, resolveAutomationTimeoutSeconds, timerDelayUntil };

package/dist/src/automations/service/action-executor.js

@@ -157,19 +157,28 @@ var AutomationActionExecutor = class {
 			status: "failed",
 			error: "Agent service is not available"
 		};
+		const agentId = normalizeAgentId(action.agentId || this.deps.getDefaultAgentId?.() || "main");
+		const peerId = automation.conversationMode === "continuous" ? automation.id : `${automation.id}-${crypto.randomUUID().slice(0, 8)}`;
 		const sessionKey = buildSessionKey({
-			agentId: normalizeAgentId(action.agentId || this.deps.getDefaultAgentId?.() || "main"),
+			agentId,
 			source: "automation",
 			accountId: "default",
 			peerKind: "dm",
-			peerId: `${automation.id}-${crypto.randomUUID().slice(0, 8)}`
+			peerId
 		});
-		const effectiveWorkingDirectory = action.workingDirectory ?? (automation.projectId ? this.deps.getProjectWorkspaceRoot?.(automation.projectId) : void 0);
 		await hooks.onRunPatch?.({
 			sessionKey,
 			currentPhase: "action"
 		});
-		await agentService.sessionConfig?.applyAutomationWorkingDirectory?.(sessionKey, effectiveWorkingDirectory);
+		await this.deps.prepareAgentSession?.({
+			sessionKey,
+			projectId: automation.projectId,
+			agentId,
+			peerId,
+			automationId: automation.id,
+			runId: run.id
+		});
+		await agentService.sessionConfig?.applyAutomationWorkingDirectory?.(sessionKey, automation.projectId ? void 0 : action.workingDirectory);
 		if (agentService.sessionConfig?.applyAutomationModelOverride) {
 			if (!await agentService.sessionConfig.applyAutomationModelOverride(sessionKey, action.model) && action.model) log.warn({
 				automationId: automation.id,