@downcity/plugins 1.0.216 → 1.0.236

package/src/task/Action.ts

@@ -8,8 +8,8 @@
 
 import path from "node:path";
 import type { ShipTaskStatus } from "./types/Task.js";
-import type { AgentContext } from "@downcity/agent";
-import type { PluginRunContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
+import type { PluginExecutionContext } from "@downcity/agent";
 import type { JsonValue } from "@downcity/agent";
 import {
   deriveTaskIdFromTitle,
@@ -95,10 +95,10 @@ function buildDefaultTaskBody(): string {
 
 
 export async function listTaskDefinitions(params: {
-  projectRoot: string;
+  project_root: string;
   status?: ShipTaskStatus;
 }): Promise<TaskListResponse> {
-  const root = path.resolve(params.projectRoot);
+  const root = path.resolve(params.project_root);
   const normalizedStatus = normalizeTaskStatus(params.status);
 
   const tasks = await listTasks(root);
@@ -116,7 +116,7 @@ export async function listTaskDefinitions(params: {
         : {}),
       when: task.when,
       status: task.status,
-      sessionId: task.sessionId,
+      session_id: task.session_id,
       kind: task.kind || "agent",
       ...(task.kind === "agent" ? { review: Boolean(task.review) } : {}),
       taskMdPath: task.taskMdPath,
@@ -126,10 +126,10 @@ export async function listTaskDefinitions(params: {
 }
 
 export async function createTaskDefinition(params: {
-  projectRoot: string;
+  project_root: string;
   request: TaskCreateRequest;
 }): Promise<TaskCreateResponse> {
-  const root = path.resolve(params.projectRoot);
+  const root = path.resolve(params.project_root);
   const req = params.request;
 
   const title = String(req.title || "").trim();
@@ -146,12 +146,12 @@ export async function createTaskDefinition(params: {
     };
   }
   const whenNormalized = normalizeTaskWhen(String(req.when || "@manual").trim() || "@manual");
-  const sessionId = String(req.sessionId || "").trim();
+  const session_id = String(req.session_id || "").trim();
   const kind = normalizeTaskKind(req.kind);
 
   if (!title) return { success: false, error: "Missing title" };
   if (!description) return { success: false, error: "Missing description" };
-  if (!sessionId) return { success: false, error: "Missing sessionId" };
+  if (!session_id) return { success: false, error: "Missing session_id" };
   if (!whenNormalized.ok) return { success: false, error: whenNormalized.error };
 
   const status = resolveTaskStatus(req.status, "enabled");
@@ -178,13 +178,13 @@ export async function createTaskDefinition(params: {
   try {
     const written = await writeTask({
       taskId: targetTaskId,
-      projectRoot: root,
+      project_root: root,
       overwrite: Boolean(req.overwrite) || Boolean(duplicated),
       frontmatter: {
         title,
         description,
         when: whenNormalized.value,
-        sessionId,
+        session_id,
         kind,
         ...(kind === "agent" && req.review === true ? { review: true } : {}),
         status,
@@ -206,15 +206,15 @@ export async function createTaskDefinition(params: {
 }
 
 export async function updateTaskDefinition(params: {
-  projectRoot: string;
+  project_root: string;
   request: TaskUpdateRequest;
 }): Promise<TaskUpdateResponse> {
-  const root = path.resolve(params.projectRoot);
+  const root = path.resolve(params.project_root);
   const req = params.request;
   const title = String(req.title || "").trim();
   let taskId = "";
   try {
-    taskId = await resolveTaskIdByTitle({ projectRoot: root, title });
+    taskId = await resolveTaskIdByTitle({ project_root: root, title });
   } catch (error) {
     return { success: false, error: String(error) };
   }
@@ -229,7 +229,7 @@ export async function updateTaskDefinition(params: {
 
   try {
     const current = await readTask({
-      projectRoot: root,
+      project_root: root,
       taskId,
     });
 
@@ -260,9 +260,9 @@ export async function updateTaskDefinition(params: {
     const whenNormalized = normalizeTaskWhen(whenInput);
     if (!whenNormalized.ok) return { success: false, error: whenNormalized.error };
 
-    const sessionId =
-      typeof req.sessionId === "string" ? req.sessionId.trim() : current.frontmatter.sessionId;
-    if (!sessionId) return { success: false, error: "sessionId cannot be empty" };
+    const session_id =
+      typeof req.session_id === "string" ? req.session_id.trim() : current.frontmatter.session_id;
+    if (!session_id) return { success: false, error: "session_id cannot be empty" };
     const kind = normalizeTaskKind(
       req.kind === undefined ? current.frontmatter.kind : req.kind,
     );
@@ -291,14 +291,14 @@ export async function updateTaskDefinition(params: {
         : current.body;
 
     const written = await writeTask({
-      projectRoot: root,
+      project_root: root,
       taskId,
       overwrite: true,
       frontmatter: {
         title: nextTitle,
         description,
         when: whenNormalized.value,
-        sessionId,
+        session_id,
         kind,
         ...(kind === "agent" && review ? { review: true } : {}),
         status,
@@ -320,16 +320,16 @@ export async function updateTaskDefinition(params: {
 }
 
 export async function runTaskDefinition(params: {
-  context: AgentContext;
-  projectRoot: string;
+  context: PluginContext;
+  project_root: string;
   request: TaskRunRequest;
-  run_context?: PluginRunContext;
+  execution_context?: PluginExecutionContext;
 }): Promise<TaskRunResponse> {
-  const root = path.resolve(params.projectRoot);
+  const root = path.resolve(params.project_root);
   const title = String(params.request.title || "").trim();
   let taskId = "";
   try {
-    taskId = await resolveTaskIdByTitle({ projectRoot: root, title });
+    taskId = await resolveTaskIdByTitle({ project_root: root, title });
   } catch (error) {
     return { success: false, error: String(error) };
   }
@@ -343,7 +343,7 @@ export async function runTaskDefinition(params: {
     // 关键点（中文）：run 改为“异步受理”，先做存在性校验，再后台执行。
     await readTask({
       taskId,
-      projectRoot: root,
+      project_root: root,
     });
 
     params.context.logger.info(
@@ -358,15 +358,15 @@ export async function runTaskDefinition(params: {
     const executionId = `${taskId}:${Date.now()}`;
     void runTaskNow({
       context: params.context,
-      projectRoot: root,
+      project_root: root,
       taskId,
       trigger,
       executionId,
-      ...(params.run_context?.agentEnv
-        ? { agent_env: { ...params.run_context.agentEnv } }
+      ...(params.execution_context?.workspace_env
+        ? { workspace_env: { ...params.execution_context.workspace_env } }
         : {}),
-      ...(params.run_context?.agentSystems
-        ? { agent_systems: [...params.run_context.agentSystems] }
+      ...(params.execution_context?.agent_systems
+        ? { agent_systems: [...params.execution_context.agent_systems] }
         : {}),
     })
       .then((result) => {
@@ -417,14 +417,14 @@ export async function runTaskDefinition(params: {
 }
 
 export async function setTaskStatus(params: {
-  projectRoot: string;
+  project_root: string;
   request: TaskSetStatusRequest;
 }): Promise<TaskSetStatusResponse> {
-  const root = path.resolve(params.projectRoot);
+  const root = path.resolve(params.project_root);
   const title = String(params.request.title || "").trim();
   let taskId = "";
   try {
-    taskId = await resolveTaskIdByTitle({ projectRoot: root, title });
+    taskId = await resolveTaskIdByTitle({ project_root: root, title });
   } catch (error) {
     return { success: false, error: String(error) };
   }
@@ -439,12 +439,12 @@ export async function setTaskStatus(params: {
 
   try {
     const task = await readTask({
-      projectRoot: root,
+      project_root: root,
       taskId,
     });
 
     await writeTask({
-      projectRoot: root,
+      project_root: root,
       taskId,
       overwrite: true,
       frontmatter: {
@@ -468,21 +468,21 @@ export async function setTaskStatus(params: {
 }
 
 export async function deleteTaskDefinition(params: {
-  projectRoot: string;
+  project_root: string;
   request: TaskDeleteRequest;
 }): Promise<TaskDeleteResponse> {
-  const root = path.resolve(params.projectRoot);
+  const root = path.resolve(params.project_root);
   const title = String(params.request.title || "").trim();
   let taskId = "";
   try {
-    taskId = await resolveTaskIdByTitle({ projectRoot: root, title });
+    taskId = await resolveTaskIdByTitle({ project_root: root, title });
   } catch (error) {
     return { success: false, error: String(error) };
   }
 
   try {
     const deleted = await deleteTask({
-      projectRoot: root,
+      project_root: root,
       taskId,
     });
     return {

package/src/task/PROMPT.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/task/PROMPT.ts.txt
-const TEXT_MODULE_CONTENT = "# Task Plugin\n\nYou can use the `task` plugin to manage task definitions, execution, scheduling, and status control.\n\n## Task Model\n\nEach task is defined in `./.downcity/task/<title>/task.md` and contains:\n- frontmatter for structured fields\n- body for the task instructions\n\nCore frontmatter fields:\n- `title`: unique task identifier\n- `description`: task description\n- `when`: trigger condition, supporting `@manual`, cron, or `time:<ISO8601-with-timezone>`\n- `sessionId`: task execution session\n- `status`: `enabled|paused|disabled`\n- `kind`: `agent|script`, defaulting to `agent`\n\nEach execution creates a run directory:\n- `./.downcity/task/<title>/<timestamp>/`\n\nCommon artifacts:\n- `input.md`\n- `output.md`: final output body for this run\n- `result.md`: execution summary\n- `run.json`\n- `run-progress.json`\n- `dialogue.md` / `dialogue.json`: multi-turn agent dialogue\n- `error.md`: failure details\n\n## Execution Kinds\n\n1. `kind=agent`\n- Sends the task body to an agent for execution.\n- Completes in a single turn by default. Simulated multi-turn review is enabled only when frontmatter explicitly sets `review: true`.\n- Suitable for research, analysis, and report generation.\n\n2. `kind=script`\n- Treats the body as a shell script.\n- The body must be non-empty and executable as a script.\n\n## Available Actions\n\n- `list`\n- `create`\n- `run`\n- `delete`\n- `update`\n- `status`\n- `enable`\n- `disable`\n\n## Action Examples\n\n- `plugin_call({ plugin: \"task\", action: \"list\", payload: { status } })`\n- `plugin_call({ plugin: \"task\", action: \"create\", payload: { title, description, sessionId, when, kind, status } })`\n- `plugin_call({ plugin: \"task\", action: \"run\", payload: { title, reason } })`\n- `plugin_call({ plugin: \"task\", action: \"update\", payload: { title, description, when, status, sessionId } })`\n- `plugin_call({ plugin: \"task\", action: \"delete\", payload: { title } })`\n\n## Key Constraints\n\n- `title` is unique. `create` deduplicates only by exact `title`.\n- After `when=time:...` triggers, the task is automatically set to `paused` and falls back to `when=@manual`.\n- `run` is accepted asynchronously. It returns `accepted=true`, `message`, and `executionId` immediately. Treat this as \"the task has entered background execution; the result will be sent automatically through the chat plugin runtime, and the current flow does not need to block.\"\n- If `run` returns `accepted=true`:\n  - Do not manually forward task output to the user again.\n  - Do not actively poll the run directory, `run-progress.json`, or `output.md`.\n  - Inspect the run directory only when the user explicitly asks to debug, view artifacts, or confirm execution details.\n- Agent tasks only need to produce valid output by default. They should send to an external channel only when the task body explicitly requires it.\n\n## Designing The Task Body\n\n### Recommended Agent Task Structure\n\nThe body should include at least these headings:\n\n```md\n# Task Goal\n\n- What final result this task must deliver.\n\n# Background And Input\n\n- Data sources, scope, constraints, and reference materials.\n\n# Execution Steps\n\n1. What to do first.\n2. What to do next.\n3. Where key intermediate artifacts should be written.\n\n# Output Requirements\n\n- What format the final result must use.\n- Whether a table, JSON, or Markdown is required.\n- What content must not be included.\n\n# Trigger And Status Recommendation\n\n- Why this task is suitable for `@manual`, cron, or `time:...`.\n- Whether it should currently be `paused` or `enabled`.\n\n# Notes\n\n- Risks, boundaries, and things not to do.\n```\n\n### Agent Task Body Writing Constraints\n\n- The task body must read like a delivery contract, so another executor can run it directly without relying on the current chat context.\n- `# Task Goal` must clearly state the final deliverable. Do not write vague goals such as \"take a look\", \"research this\", or \"handle this\".\n- `# Background And Input` must specify sources, scope, objects, time range, and constraints. Do not assume the executor can see the original chat context.\n- `# Execution Steps` should describe the task workflow, not task-management actions. Do not write \"first check whether a task with the same name exists\", \"then create a task\", or \"then trigger the task\".\n- `# Output Requirements` must clearly specify the final artifact's format, structure, tone, length, and excluded content.\n- Explicitly state that the final assistant message will be written directly to `output.md` and sent to the user. Therefore, the final answer must be exactly the deliverable content.\n- Content-generation tasks such as daily reports, reminders, morning briefings, summaries, and reports must explicitly require \"the final output is the deliverable body itself\". Do not let the executor output process notes.\n- If the task result should be sent to the user, the body should require \"output send-ready message content\" instead of asking the executor to explain what it has sent.\n- Unless truly needed, do not ask the executor to repeat the task title, sessionId, execution time, status, or other metadata in the body.\n- Constraints in the body must be executable and checkable. Avoid weak phrases such as \"appropriately\", \"as much as possible\", or \"depending on the situation\".\n- Do not put task creation, task update, task status lookup, or same-title existence checks into the body. Those belong to the task plugin, not to the task deliverable.\n\n### Forbidden Agent Task Body Patterns\n\n- Do not write the body in chat-reply style, for example:\n  - \"I will help you...\"\n  - \"First, let me...\"\n  - \"I will check first...\"\n  - \"I see there is already a task with the same name...\"\n- Do not write the body as task-management instructions, for example:\n  - \"If the task exists, update it; otherwise create it.\"\n  - \"First list, then run.\"\n  - \"Tell the user that the task has started when done.\"\n- Do not write the body as a status-report template, for example:\n  - \"Task status summary\"\n  - \"Sent / completed / updated\"\n  - \"Current task configuration\"\n- Do not describe only actions without describing the deliverable, for example:\n  - \"Go collect some materials.\"\n  - \"Generate some content and see.\"\n  - \"Report back after finishing.\"\n- Do not use references that depend on the current context, for example:\n  - \"Do what was said above.\"\n  - \"Continue the previous one.\"\n  - \"Send this out.\"\n\n### How To Judge Whether The Body Is Good\n\n- If you can copy the task body alone to another agent and it can still understand the goal, input, steps, and deliverable, the body is valid.\n- If deleting the output section leaves only \"go do something\" style instructions, the body is invalid.\n- If the body looks more like instructions for creating or updating a task than instructions for executing the task, the layering is wrong and the body must be rewritten.\n- If the body naturally encourages the executor to output process notes instead of the final artifact, the `# Output Requirements` section is not strong enough and must add explicit prohibitions.\n\n### Recommended Script Task Structure\n\n- The body must be a pure shell script. Do not mix in explanatory natural language.\n- Start with comments that describe the script's purpose, input dependencies, and failure conditions when possible.\n- Keep output stable so it can be sent directly as the final result.\n- If files need to be generated, write them to the run directory or to an explicit project path.\n\n### Output Design Principles\n\n- When a task completes, the system automatically sends the final result body back to the chat bound to `sessionId` through the chat plugin runtime's `send`.\n- The current implementation uses the simplest rule: the final assistant message is treated directly as the final result body and written to `output.md`.\n- Therefore, the \"Output Requirements\" section must be written for the final user, not only for developers.\n- For user-facing agent tasks, the body should require \"the final assistant message directly outputs the deliverable itself\". Do not let the executor explain how it created, checked, updated, triggered, or sent the task.\n- For content-generation tasks such as daily reports, reminders, morning briefings, and summaries, the final output should be exactly that content. It should not include process language such as \"I will handle this\", \"task sent\", or \"task status summary\".\n- By default, do not ask the executor to call chat plugin send actions again. The system handles final-result delivery.\n- Explicitly require chat plugin actions only for cross-conversation sending, additional CCs, multi-channel notifications, or similar cases.\n\n### Choosing `when` And `status`\n\n- A task is created as `status=enabled` by default. Set `paused` explicitly only when it is still a draft, likely to fail, or needs human confirmation.\n- For verified stable tasks that need automatic execution, use cron with `status=enabled`.\n- For a clear one-time execution, use `time:<ISO time with timezone>`. After execution, the system automatically falls back to `@manual` and `paused`.\n- If the user only wants to save it for later, do not enable scheduling directly.\n\n## Body Templates\n\n### Agent Template\n\n```md\n# Task Goal\n\n- Produce a final result that can be sent directly to the user.\n\n# Background And Input\n\n- Add context, files, links, scope, and assumptions here.\n\n# Execution Steps\n\n1. Understand the task goal and completion criteria.\n2. Collect necessary information and execute the task.\n3. Write key intermediate artifacts to the run directory.\n4. Output the final result body.\n\n# Output Requirements\n\n- The final assistant message is the final result. Do not include long logs.\n- The final assistant message must output the deliverable itself. Do not output task-management process, sending process, or status reports.\n- Do not use meta language such as \"I will help you...\", \"First, let me...\", or \"sent\".\n- By default, do not call the chat plugin send action again.\n\n# Trigger And Status Recommendation\n\n- Enable by default after creation. If this is only a draft or waiting for human confirmation, set it to `paused`.\n\n# Notes\n\n- Call chat plugin send actions only when cross-conversation or additional notifications are explicitly needed.\n```\n\n### Script Template\n\n```bash\n# Task goal: state in one sentence what the script should do\n# Input dependencies: list environment variables, files, and command dependencies\n# Failure conditions: list cases that should exit 1\n\nset -euo pipefail\n\n# 1. Prepare input\n\n# 2. Execute main logic\n\n# 3. Output final result. This output will be sent directly to the user.\n```\n\n## Recommendations\n\n- Run `list` before `create` or `update`.\n- Keep simple content-generation tasks single-turn by default. Set `review: true` only when you truly need \"draft, review, revise\".\n- Keep script task bodies as pure scripts, without redundant natural-language explanation.\n- If the user only wants to save something for later, create it as `paused`; otherwise keep the default enabled state.\n- The task body must describe what the final result should look like, not only say \"go do this and see\".\n- For content-generation tasks, explicitly require \"the final assistant message can only be the finished content body\" so the executor does not mistake process notes for the final result.\n";
+const TEXT_MODULE_CONTENT = "# Task Plugin\n\nYou can use the `task` plugin to manage task definitions, execution, scheduling, and status control.\n\n## Task Model\n\nEach task is defined in `./.downcity/task/<title>/task.md` and contains:\n- frontmatter for structured fields\n- body for the task instructions\n\nCore frontmatter fields:\n- `title`: unique task identifier\n- `description`: task description\n- `when`: trigger condition, supporting `@manual`, cron, or `time:<ISO8601-with-timezone>`\n- `session_id`: task execution session\n- `status`: `enabled|paused|disabled`\n- `kind`: `agent|script`, defaulting to `agent`\n\nEach execution creates a run directory:\n- `./.downcity/task/<title>/<timestamp>/`\n\nCommon artifacts:\n- `input.md`\n- `output.md`: final output body for this run\n- `result.md`: execution summary\n- `run.json`\n- `run-progress.json`\n- `dialogue.md` / `dialogue.json`: multi-turn agent dialogue\n- `error.md`: failure details\n\n## Execution Kinds\n\n1. `kind=agent`\n- Sends the task body to an agent for execution.\n- Completes in a single turn by default. Simulated multi-turn review is enabled only when frontmatter explicitly sets `review: true`.\n- Suitable for research, analysis, and report generation.\n\n2. `kind=script`\n- Treats the body as a shell script.\n- The body must be non-empty and executable as a script.\n\n## Available Actions\n\n- `list`\n- `create`\n- `run`\n- `delete`\n- `update`\n- `status`\n- `enable`\n- `disable`\n\n## Action Examples\n\n- `plugin_call({ plugin: \"task\", action: \"list\", payload: { status } })`\n- `plugin_call({ plugin: \"task\", action: \"create\", payload: { title, description, session_id, when, kind, status } })`\n- `plugin_call({ plugin: \"task\", action: \"run\", payload: { title, reason } })`\n- `plugin_call({ plugin: \"task\", action: \"update\", payload: { title, description, when, status, session_id } })`\n- `plugin_call({ plugin: \"task\", action: \"delete\", payload: { title } })`\n\n## Key Constraints\n\n- `title` is unique. `create` deduplicates only by exact `title`.\n- After `when=time:...` triggers, the task is automatically set to `paused` and falls back to `when=@manual`.\n- `run` is accepted asynchronously. It returns `accepted=true`, `message`, and `executionId` immediately. Treat this as \"the task has entered background execution; the result will be sent automatically through the chat plugin runtime, and the current flow does not need to block.\"\n- If `run` returns `accepted=true`:\n  - Do not manually forward task output to the user again.\n  - Do not actively poll the run directory, `run-progress.json`, or `output.md`.\n  - Inspect the run directory only when the user explicitly asks to debug, view artifacts, or confirm execution details.\n- Agent tasks only need to produce valid output by default. They should send to an external channel only when the task body explicitly requires it.\n\n## Designing The Task Body\n\n### Recommended Agent Task Structure\n\nThe body should include at least these headings:\n\n```md\n# Task Goal\n\n- What final result this task must deliver.\n\n# Background And Input\n\n- Data sources, scope, constraints, and reference materials.\n\n# Execution Steps\n\n1. What to do first.\n2. What to do next.\n3. Where key intermediate artifacts should be written.\n\n# Output Requirements\n\n- What format the final result must use.\n- Whether a table, JSON, or Markdown is required.\n- What content must not be included.\n\n# Trigger And Status Recommendation\n\n- Why this task is suitable for `@manual`, cron, or `time:...`.\n- Whether it should currently be `paused` or `enabled`.\n\n# Notes\n\n- Risks, boundaries, and things not to do.\n```\n\n### Agent Task Body Writing Constraints\n\n- The task body must read like a delivery contract, so another executor can run it directly without relying on the current chat context.\n- `# Task Goal` must clearly state the final deliverable. Do not write vague goals such as \"take a look\", \"research this\", or \"handle this\".\n- `# Background And Input` must specify sources, scope, objects, time range, and constraints. Do not assume the executor can see the original chat context.\n- `# Execution Steps` should describe the task workflow, not task-management actions. Do not write \"first check whether a task with the same name exists\", \"then create a task\", or \"then trigger the task\".\n- `# Output Requirements` must clearly specify the final artifact's format, structure, tone, length, and excluded content.\n- Explicitly state that the final assistant message will be written directly to `output.md` and sent to the user. Therefore, the final answer must be exactly the deliverable content.\n- Content-generation tasks such as daily reports, reminders, morning briefings, summaries, and reports must explicitly require \"the final output is the deliverable body itself\". Do not let the executor output process notes.\n- If the task result should be sent to the user, the body should require \"output send-ready message content\" instead of asking the executor to explain what it has sent.\n- Unless truly needed, do not ask the executor to repeat the task title, session_id, execution time, status, or other metadata in the body.\n- Constraints in the body must be executable and checkable. Avoid weak phrases such as \"appropriately\", \"as much as possible\", or \"depending on the situation\".\n- Do not put task creation, task update, task status lookup, or same-title existence checks into the body. Those belong to the task plugin, not to the task deliverable.\n\n### Forbidden Agent Task Body Patterns\n\n- Do not write the body in chat-reply style, for example:\n  - \"I will help you...\"\n  - \"First, let me...\"\n  - \"I will check first...\"\n  - \"I see there is already a task with the same name...\"\n- Do not write the body as task-management instructions, for example:\n  - \"If the task exists, update it; otherwise create it.\"\n  - \"First list, then run.\"\n  - \"Tell the user that the task has started when done.\"\n- Do not write the body as a status-report template, for example:\n  - \"Task status summary\"\n  - \"Sent / completed / updated\"\n  - \"Current task configuration\"\n- Do not describe only actions without describing the deliverable, for example:\n  - \"Go collect some materials.\"\n  - \"Generate some content and see.\"\n  - \"Report back after finishing.\"\n- Do not use references that depend on the current context, for example:\n  - \"Do what was said above.\"\n  - \"Continue the previous one.\"\n  - \"Send this out.\"\n\n### How To Judge Whether The Body Is Good\n\n- If you can copy the task body alone to another agent and it can still understand the goal, input, steps, and deliverable, the body is valid.\n- If deleting the output section leaves only \"go do something\" style instructions, the body is invalid.\n- If the body looks more like instructions for creating or updating a task than instructions for executing the task, the layering is wrong and the body must be rewritten.\n- If the body naturally encourages the executor to output process notes instead of the final artifact, the `# Output Requirements` section is not strong enough and must add explicit prohibitions.\n\n### Recommended Script Task Structure\n\n- The body must be a pure shell script. Do not mix in explanatory natural language.\n- Start with comments that describe the script's purpose, input dependencies, and failure conditions when possible.\n- Keep output stable so it can be sent directly as the final result.\n- If files need to be generated, write them to the run directory or to an explicit project path.\n\n### Output Design Principles\n\n- When a task completes, the system automatically sends the final result body back to the chat bound to `session_id` through the chat plugin runtime's `send`.\n- The current implementation uses the simplest rule: the final assistant message is treated directly as the final result body and written to `output.md`.\n- Therefore, the \"Output Requirements\" section must be written for the final user, not only for developers.\n- For user-facing agent tasks, the body should require \"the final assistant message directly outputs the deliverable itself\". Do not let the executor explain how it created, checked, updated, triggered, or sent the task.\n- For content-generation tasks such as daily reports, reminders, morning briefings, and summaries, the final output should be exactly that content. It should not include process language such as \"I will handle this\", \"task sent\", or \"task status summary\".\n- By default, do not ask the executor to call chat plugin send actions again. The system handles final-result delivery.\n- Explicitly require chat plugin actions only for cross-conversation sending, additional CCs, multi-channel notifications, or similar cases.\n\n### Choosing `when` And `status`\n\n- A task is created as `status=enabled` by default. Set `paused` explicitly only when it is still a draft, likely to fail, or needs human confirmation.\n- For verified stable tasks that need automatic execution, use cron with `status=enabled`.\n- For a clear one-time execution, use `time:<ISO time with timezone>`. After execution, the system automatically falls back to `@manual` and `paused`.\n- If the user only wants to save it for later, do not enable scheduling directly.\n\n## Body Templates\n\n### Agent Template\n\n```md\n# Task Goal\n\n- Produce a final result that can be sent directly to the user.\n\n# Background And Input\n\n- Add context, files, links, scope, and assumptions here.\n\n# Execution Steps\n\n1. Understand the task goal and completion criteria.\n2. Collect necessary information and execute the task.\n3. Write key intermediate artifacts to the run directory.\n4. Output the final result body.\n\n# Output Requirements\n\n- The final assistant message is the final result. Do not include long logs.\n- The final assistant message must output the deliverable itself. Do not output task-management process, sending process, or status reports.\n- Do not use meta language such as \"I will help you...\", \"First, let me...\", or \"sent\".\n- By default, do not call the chat plugin send action again.\n\n# Trigger And Status Recommendation\n\n- Enable by default after creation. If this is only a draft or waiting for human confirmation, set it to `paused`.\n\n# Notes\n\n- Call chat plugin send actions only when cross-conversation or additional notifications are explicitly needed.\n```\n\n### Script Template\n\n```bash\n# Task goal: state in one sentence what the script should do\n# Input dependencies: list environment variables, files, and command dependencies\n# Failure conditions: list cases that should exit 1\n\nset -euo pipefail\n\n# 1. Prepare input\n\n# 2. Execute main logic\n\n# 3. Output final result. This output will be sent directly to the user.\n```\n\n## Recommendations\n\n- Run `list` before `create` or `update`.\n- Keep simple content-generation tasks single-turn by default. Set `review: true` only when you truly need \"draft, review, revise\".\n- Keep script task bodies as pure scripts, without redundant natural-language explanation.\n- If the user only wants to save something for later, create it as `paused`; otherwise keep the default enabled state.\n- The task body must describe what the final result should look like, not only say \"go do this and see\".\n- For content-generation tasks, explicitly require \"the final assistant message can only be the finished content body\" so the executor does not mistake process notes for the final result.\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/task/Scheduler.ts

@@ -6,7 +6,7 @@
  * - cron 调度执行器由宿主注入，task runtime 不依赖具体实现。
  */
 
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import {
   isTaskWhenManual,
   resolveTaskWhenCronExpression,
@@ -23,7 +23,7 @@ function formatTaskLogMessage(message: string): string {
 }
 
 export async function registerTaskCronJobs(params: {
-  context: AgentContext;
+  context: PluginContext;
   engine: TaskCronEngine;
   /**
    * cron 表达式使用的 IANA 时区。
@@ -36,7 +36,7 @@ export async function registerTaskCronJobs(params: {
 }): Promise<{ tasksFound: number; jobsScheduled: number }> {
   const context = params.context;
   const logger = context.logger;
-  const tasks = await listTasks(context.rootPath);
+  const tasks = await listTasks(context.workspace_path);
   const runtimeTimezone = params.timezone;
 
   let jobsScheduled = 0;
@@ -49,7 +49,7 @@ export async function registerTaskCronJobs(params: {
     try {
       const task = await readTask({
         taskId: item.taskId,
-        projectRoot: context.rootPath,
+        project_root: context.workspace_path,
       });
       latestWhen = task.frontmatter.when;
     } catch {}
@@ -78,7 +78,7 @@ export async function registerTaskCronJobs(params: {
               // 关键点（中文）：触发瞬间复查最新 task.md，避免 status/when 变更后仍沿用旧注册状态。
               const latest = await readTask({
                 taskId,
-                projectRoot: context.rootPath,
+                project_root: context.workspace_path,
               });
               if (String(latest.frontmatter.status).toLowerCase() !== "enabled") {
                 return;
@@ -91,7 +91,7 @@ export async function registerTaskCronJobs(params: {
               const result = await runTaskNow({
                 context,
                 taskId,
-                projectRoot: context.rootPath,
+                project_root: context.workspace_path,
                 trigger: { type: "cron" },
               });
 
@@ -166,7 +166,7 @@ export async function registerTaskCronJobs(params: {
           try {
             const latest = await readTask({
               taskId,
-              projectRoot: context.rootPath,
+              project_root: context.workspace_path,
             });
             if (String(latest.frontmatter.status).toLowerCase() !== "enabled") return;
             const latestPlannedMs = resolveTaskWhenOneShotMs(latest.frontmatter.when);
@@ -177,7 +177,7 @@ export async function registerTaskCronJobs(params: {
             const result = await runTaskNow({
               context,
               taskId,
-              projectRoot: context.rootPath,
+              project_root: context.workspace_path,
               trigger: { type: "time" },
             });
 
@@ -206,10 +206,10 @@ export async function registerTaskCronJobs(params: {
               try {
                 const latest = await readTask({
                   taskId,
-                  projectRoot: context.rootPath,
+                  project_root: context.workspace_path,
                 });
                 await writeTask({
-                  projectRoot: context.rootPath,
+                  project_root: context.workspace_path,
                   taskId,
                   overwrite: true,
                   frontmatter: {

package/src/task/TaskPlugin.ts

@@ -7,9 +7,9 @@
  * - 当前文件只保留实例骨架与 lifecycle，不再依赖旧的模块级单例。
  */
 
-import { BasePlugin } from "@downcity/agent";
+import { BasePlugin, create_action } from "@downcity/agent";
 import type { PluginActions } from "@downcity/agent";
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type {
   TaskCronRegisterResult,
   TaskSchedulerReloadResult,
@@ -24,7 +24,7 @@ import {
   reloadTaskSchedulerAfterMutation,
 } from "@/task/runtime/TaskActionExecution.js";
 import { TASK_PLUGIN_PROMPT } from "@/task/runtime/TaskPluginSystem.js";
-import { resolveRuntimeTimezone } from "@downcity/agent";
+import { resolve_runtime_timezone } from "@downcity/agent";
 
 const TASK_LOG_PREFIX = "[TASK]";
 
@@ -78,10 +78,31 @@ export class TaskPlugin extends BasePlugin {
     super();
     this.options = options || {};
 
-    this.actions = createTaskPluginActions({
-      reloadSchedulerAfterMutation: async (params) =>
-        this.reloadSchedulerAfterMutation(params),
-    });
+    this.actions = {
+      ...createTaskPluginActions({
+        reloadSchedulerAfterMutation: async (params) =>
+          this.reloadSchedulerAfterMutation(params),
+      }),
+      reload: create_action({
+        description: "Reload the task scheduler from persisted tasks.",
+        execute: async ({ context }) => {
+          const result = await this.restartCronRuntime(context);
+          context.logger.info(
+            formatTaskLogMessage(
+              `Task cron trigger reloaded (tasks=${result.tasksFound}, jobs=${result.jobsScheduled})`,
+            ),
+          );
+          return {
+            success: true,
+            message: "task scheduler reloaded",
+            data: {
+              tasks_found: result.tasksFound,
+              jobs_scheduled: result.jobsScheduled,
+            },
+          };
+        },
+      }),
+    };
 
     this.lifecycle = {
       start: async (context) => {
@@ -98,25 +119,6 @@ export class TaskPlugin extends BasePlugin {
         if (!stopped) return;
         context.logger.info(formatTaskLogMessage("Task cron trigger stopped"));
       },
-      command: async ({ context, command }) => {
-        if (command !== "reschedule" && command !== "reload") {
-          return {
-            success: false,
-            message: `Unknown task command: ${command}`,
-          };
-        }
-
-        const result = await this.restartCronRuntime(context);
-        context.logger.info(
-          formatTaskLogMessage(
-            `Task cron trigger reloaded (tasks=${result.tasksFound}, jobs=${result.jobsScheduled})`,
-          ),
-        );
-        return {
-          success: true,
-          message: "task scheduler reloaded",
-        };
-      },
     };
   }
 
@@ -124,7 +126,7 @@ export class TaskPlugin extends BasePlugin {
    * 启动当前实例的 cron runtime。
    */
   async startCronRuntime(
-    context: AgentContext,
+    context: PluginContext,
   ): Promise<TaskCronRegisterResult | null> {
     if (this.cronEngine) return null;
 
@@ -155,7 +157,7 @@ export class TaskPlugin extends BasePlugin {
    * 重启当前实例的 cron runtime。
    */
   async restartCronRuntime(
-    context: AgentContext,
+    context: PluginContext,
   ): Promise<TaskCronRegisterResult> {
     await this.stopCronRuntime();
     const started = await this.startCronRuntime(context);
@@ -171,7 +173,7 @@ export class TaskPlugin extends BasePlugin {
    * 任务定义变更后重载 scheduler。
    */
   private async reloadSchedulerAfterMutation(params: {
-    context: AgentContext;
+    context: PluginContext;
     action: "create" | "update" | "delete" | "status";
     title: string;
   }): Promise<TaskSchedulerReloadResult> {
@@ -187,6 +189,6 @@ export class TaskPlugin extends BasePlugin {
    * 解析当前 task cron 使用的时区。
    */
   private resolveTimezone(): string {
-    return String(this.options.timezone || "").trim() || resolveRuntimeTimezone();
+    return String(this.options.timezone || "").trim() || resolve_runtime_timezone();
   }
 }

package/src/task/runtime/Model.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - `task.md` 使用 YAML frontmatter + markdown 正文
- * - frontmatter 必须包含：title/when/description/sessionId/status
+ * - frontmatter 必须包含：title/when/description/session_id/status
  * - `when` 统一承载触发语义：`@manual` / cron / `time:<ISO8601-with-timezone>`
  */
 
@@ -26,7 +26,7 @@ const REQUIRED_FIELDS: Array<keyof ShipTaskFrontmatterV1> = [
   "title",
   "when",
   "description",
-  "sessionId",
+  "session_id",
   "status",
 ];
 
@@ -213,9 +213,9 @@ export function parseTaskMarkdown(params: {
   taskId: string;
   markdown: string;
   taskMdPath: string;
-  projectRoot: string;
+  project_root: string;
 }): { ok: true; task: ShipTaskDefinitionV1 } | { ok: false; error: string } {
-  const { taskId, markdown, taskMdPath, projectRoot } = params;
+  const { taskId, markdown, taskMdPath, project_root } = params;
   const text = String(markdown ?? "");
   const { frontMatterYaml, body } = parseFrontMatter(text);
 
@@ -277,8 +277,8 @@ export function parseTaskMarkdown(params: {
   }
 
   const kind = normalizeTaskKind(meta.kind);
-  const bodyText = String(body ?? "").trim();
-  if (kind === "script" && !bodyText) {
+  const body_text = String(body ?? "").trim();
+  if (kind === "script" && !body_text) {
     return { ok: false, error: "script task body cannot be empty" };
   }
 
@@ -286,14 +286,14 @@ export function parseTaskMarkdown(params: {
     title: rawTitle,
     when: whenNormalized.value,
     description: String(meta.description).trim(),
-    sessionId: String(meta.sessionId).trim(),
+    session_id: String(meta.session_id).trim(),
     kind,
     ...(kind === "agent" && normalizeTaskReview(meta.review) === true ? { review: true } : {}),
     status,
   };
 
   const relTaskMdPath = path
-    .relative(projectRoot, taskMdPath)
+    .relative(project_root, taskMdPath)
     .split(path.sep)
     .join("/");
 
@@ -322,8 +322,8 @@ export function buildTaskMarkdown(params: {
   }
 
   const kind = normalizeTaskKind(frontmatter.kind);
-  const bodyText = String(body ?? "").trim();
-  if (kind === "script" && !bodyText) {
+  const body_text = String(body ?? "").trim();
+  if (kind === "script" && !body_text) {
     throw new Error("script task body cannot be empty");
   }
 
@@ -331,7 +331,7 @@ export function buildTaskMarkdown(params: {
     title: String(frontmatter.title || "").trim(),
     when: whenNormalized.value,
     description: String(frontmatter.description || "").trim(),
-    sessionId: String(frontmatter.sessionId || "").trim(),
+    session_id: String(frontmatter.session_id || "").trim(),
     kind,
     ...(kind === "agent" ? { review: Boolean(frontmatter.review) } : {}),
     status: String(frontmatter.status || "").trim(),
@@ -342,6 +342,6 @@ export function buildTaskMarkdown(params: {
     noRefs: true,
   });
 
-  const bodyWithTrailingLf = bodyText ? bodyText + "\n" : "";
+  const bodyWithTrailingLf = body_text ? body_text + "\n" : "";
   return `---\n${yamlText}---\n\n${bodyWithTrailingLf}`;
 }

package/src/task/runtime/Paths.ts

@@ -6,7 +6,7 @@
  * - definition: `./.downcity/task/<taskId>/task.md`
  * - run dir: `./.downcity/task/<taskId>/<timestamp>/`
  *
- * 同时定义“task run sessionId”格式，用于把 Agent 的 session 映射到 run 目录：
+ * 同时定义“task run session_id”格式，用于把 Agent 的 session 映射到 run 目录：
  * - `task-run:<taskId>:<timestamp>`
  */
 
@@ -59,16 +59,16 @@ export function normalizeTaskId(input: string): string {
   return id;
 }
 
-export function getTaskRootDir(projectRoot: string): string {
-  return path.join(String(projectRoot || "").trim(), ".downcity", "task");
+export function getTaskRootDir(project_root: string): string {
+  return path.join(String(project_root || "").trim(), ".downcity", "task");
 }
 
-export function getTaskDir(projectRoot: string, taskId: string): string {
-  return path.join(getTaskRootDir(projectRoot), normalizeTaskId(taskId));
+export function getTaskDir(project_root: string, taskId: string): string {
+  return path.join(getTaskRootDir(project_root), normalizeTaskId(taskId));
 }
 
-export function getTaskMdPath(projectRoot: string, taskId: string): string {
-  return path.join(getTaskDir(projectRoot, taskId), "task.md");
+export function getTaskMdPath(project_root: string, taskId: string): string {
+  return path.join(getTaskDir(project_root, taskId), "task.md");
 }
 
 export function formatTaskRunTimestamp(date: Date = new Date()): string {
@@ -85,13 +85,13 @@ export function formatTaskRunTimestamp(date: Date = new Date()): string {
 }
 
 export function getTaskRunDir(
-  projectRoot: string,
+  project_root: string,
   taskId: string,
   timestamp: string,
 ): string {
   const ts = String(timestamp || "").trim();
   if (!ts) throw new Error("timestamp is required");
-  return path.join(getTaskDir(projectRoot, taskId), ts);
+  return path.join(getTaskDir(project_root, taskId), ts);
 }
 
 export function createTaskRunSessionId(taskId: string, timestamp: string): string {
@@ -102,9 +102,9 @@ export function createTaskRunSessionId(taskId: string, timestamp: string): strin
 }
 
 export function parseTaskRunSessionId(
-  sessionId: string,
+  session_id: string,
 ): { taskId: string; timestamp: string } | null {
-  const key = String(sessionId || "").trim();
+  const key = String(session_id || "").trim();
   if (!key) return null;
   const m = key.match(/^task-run:([^:]+):(.+)$/);
   if (!m) return null;