@downcity/plugins 1.0.174 → 1.0.194

package/src/sound/types/SoundPlugin.ts

@@ -0,0 +1,163 @@
+/**
+ * SoundPlugin 类型定义。
+ *
+ * 关键点（中文）
+ * - SoundPlugin 统一承载 ASR 与 TTS，不绑定本地模型、Python 或具体 provider。
+ * - ASR 结果字段与 AI SDK `TranscriptionResult` 的可序列化核心字段保持一致。
+ * - TTS 结果直接使用 AI SDK `UIMessage`，由 agent 统一处理音频 file part。
+ */
+
+import type { UIMessage } from "ai";
+import type { JsonObject, JsonValue } from "@downcity/agent";
+
+/**
+ * SoundPlugin 支持的语音能力。
+ */
+export type SoundPluginCapability = "asr" | "tts";
+
+/**
+ * SoundPlugin 可见的 FED 模型信息。
+ */
+export interface SoundPluginModel {
+  /** FED 模型唯一 ID，同时也是调用 ASR/TTS 时传入的模型引用。 */
+  id: string;
+  /** 面向用户和 Agent 展示的模型名称。 */
+  name: string;
+  /** 模型用途、语言或质量说明。 */
+  description?: string;
+  /** 模型支持的能力列表，至少包含 `asr` 或 `tts`。 */
+  modalities: string[];
+  /** FED 为模型提供的筛选标签。 */
+  tags?: string[];
+  /** FED 返回的 JSON 可序列化扩展元数据。 */
+  meta?: JsonObject;
+}
+
+/**
+ * SoundPlugin 模型列表结果。
+ */
+export interface SoundPluginModelsResult {
+  /** 满足当前能力筛选条件的模型列表。 */
+  items: SoundPluginModel[];
+}
+
+/**
+ * ASR 转写分段。
+ *
+ * 字段命名与 AI SDK `TranscriptionResult.segments` 保持一致。
+ */
+export interface SoundPluginAsrSegment {
+  /** 当前时间片段识别得到的文本。 */
+  text: string;
+  /** 当前片段在音频中的开始时间，单位为秒。 */
+  startSecond: number;
+  /** 当前片段在音频中的结束时间，单位为秒。 */
+  endSecond: number;
+}
+
+/**
+ * ASR 输入。
+ */
+export interface SoundPluginAsrInput {
+  /** 支持 ASR 的 FED 模型 ID；未提供时使用 `default_asr_model`。 */
+  model?: string;
+  /** 本地音频文件的绝对路径或相对 Agent 项目根目录的路径。 */
+  audio_path?: string;
+  /** 可由 FED 直接读取的远程音频 URL。 */
+  url?: string;
+  /** data URL 形式的音频内容。 */
+  data_url?: string;
+  /** 语言提示，例如 `auto`、`zh` 或 `en`。 */
+  language?: string;
+  /** 音频 MIME 类型，例如 `audio/ogg`。 */
+  media_type?: string;
+  /** 原始文件名，供 provider 推断音频格式。 */
+  filename?: string;
+  /** Provider 私有参数，例如 `{ openai: {...}, groq: {...} }`。 */
+  provider_options?: JsonObject;
+  /** 允许 FED ASR action 接收其他 JSON 可序列化参数。 */
+  [key: string]: JsonValue | undefined;
+}
+
+/**
+ * ASR 输出。
+ *
+ * 说明（中文）
+ * - 只保留 AI SDK `TranscriptionResult` 中适合 JSON 传输的核心字段。
+ * - warnings、responses 与 providerMetadata 属于运行期诊断信息，不进入 plugin action 协议。
+ */
+export interface SoundPluginAsrResult {
+  /** 完整转写文本。 */
+  text: string;
+  /** 带开始和结束时间的转写分段。 */
+  segments?: SoundPluginAsrSegment[];
+  /** 检测到的 ISO-639-1 语言代码。 */
+  language?: string;
+  /** 音频总时长，单位为秒。 */
+  durationInSeconds?: number;
+}
+
+/**
+ * TTS 输入。
+ */
+export interface SoundPluginTtsInput {
+  /** 支持 TTS 的 FED 模型 ID；未提供时使用 `default_tts_model`。 */
+  model?: string;
+  /** 需要合成为语音的文本。 */
+  text: string;
+  /** 语言提示，例如 `auto`、`zh` 或 `en`。 */
+  language?: string;
+  /** 音色名称或上游 provider 的 voice ID。 */
+  voice?: string;
+  /** 输出音频格式，例如 `mp3`、`wav` 或 `opus`。 */
+  format?: string;
+  /** 语速倍率。 */
+  speed?: number;
+  /** 对语气、风格或发音方式的额外说明。 */
+  instructions?: string;
+  /** Provider 私有参数，例如 `{ openai: {...}, elevenlabs: {...} }`。 */
+  provider_options?: JsonObject;
+  /** 允许 FED TTS action 接收其他 JSON 可序列化参数。 */
+  [key: string]: JsonValue | undefined;
+}
+
+/**
+ * TTS 输出。
+ *
+ * 音频通过 AI SDK `UIMessage` 的 file part 返回。
+ */
+export type SoundPluginTtsResult = UIMessage;
+
+/**
+ * SoundPlugin 构造参数。
+ */
+export interface SoundPluginOptions {
+  /** Plugin 稳定名称，默认 `sound`。 */
+  name?: string;
+  /** Plugin 展示标题，默认 `Sound`。 */
+  title?: string;
+  /** Plugin 用途说明。 */
+  description?: string;
+  /** 未显式传入 ASR 模型时使用的 FED 模型 ID。 */
+  default_asr_model?: string;
+  /** 未显式传入 TTS 模型时使用的 FED 模型 ID。 */
+  default_tts_model?: string;
+  /** 是否自动转写 chat 入站的 voice/audio 附件，默认 `false`。 */
+  auto_asr?: boolean;
+  /** ASR 与 TTS 共用的默认语言提示。 */
+  language?: string;
+  /** TTS 默认音色。 */
+  voice?: string;
+  /** TTS 默认输出格式。 */
+  format?: string;
+  /** 调用 FED ASR action 的函数，通常传入 `(input) => city.ai.asr(input)`。 */
+  asr: (
+    input: SoundPluginAsrInput,
+  ) => Promise<SoundPluginAsrResult> | SoundPluginAsrResult;
+  /** 调用 FED TTS action 的函数，通常传入 `(input) => city.ai.tts(input)`。 */
+  tts: (
+    input: SoundPluginTtsInput,
+  ) => Promise<SoundPluginTtsResult> | SoundPluginTtsResult;
+  /** 列出 FED 中支持 ASR 或 TTS 的模型。 */
+  list_models?: () => Promise<SoundPluginModel[]> | SoundPluginModel[];
+}

package/src/task/Action.ts

@@ -9,6 +9,7 @@
 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 { JsonValue } from "@downcity/agent";
 import {
   deriveTaskIdFromTitle,
@@ -322,6 +323,7 @@ export async function runTaskDefinition(params: {
   context: AgentContext;
   projectRoot: string;
   request: TaskRunRequest;
+  run_context?: PluginRunContext;
 }): Promise<TaskRunResponse> {
   const root = path.resolve(params.projectRoot);
   const title = String(params.request.title || "").trim();
@@ -360,6 +362,12 @@ export async function runTaskDefinition(params: {
       taskId,
       trigger,
       executionId,
+      ...(params.run_context?.agentEnv
+        ? { agent_env: { ...params.run_context.agentEnv } }
+        : {}),
+      ...(params.run_context?.agentSystems
+        ? { agent_systems: [...params.run_context.agentSystems] }
+        : {}),
     })
       .then((result) => {
         params.context.logger.info(

package/src/task/runtime/Runner.ts

@@ -80,6 +80,10 @@ export async function runTaskNow(params: {
   trigger: ShipTaskRunTriggerV1;
   executionId?: string;
   projectRoot?: string;
+  /** 发起该任务的 Session step 已提交生效的 env 快照。 */
+  agent_env?: Readonly<Record<string, string>>;
+  /** 发起该任务的 Session step 已提交生效的 instruction 快照。 */
+  agent_systems?: readonly string[];
 }): Promise<{
   ok: boolean;
   status: ShipTaskRunStatusV1;
@@ -148,19 +152,6 @@ export async function runTaskNow(params: {
 
   const runSessionId = createTaskRunSessionId(task.taskId, timestamp);
   const userSimulatorSessionId = `task-user-sim:${task.taskId}:${timestamp}`;
-  const taskModel = await context.session.resolveModel(task.frontmatter.sessionId);
-  if (!taskModel) {
-    throw new Error(
-      `Task "${task.taskId}" requires a configured model on session "${task.frontmatter.sessionId}"`,
-    );
-  }
-  const taskSessionRuntime = createTaskSessionRuntimePort({
-    context,
-    model: taskModel,
-    runDirAbs,
-    runSessionId,
-    userSimulatorSessionId,
-  });
 
   let ok = false;
   let status: ShipTaskRunStatusV1 = "failure";
@@ -194,6 +185,21 @@ export async function runTaskNow(params: {
     outputText = scriptResult.outputText;
     errorText = scriptResult.errorText;
   } else {
+    const task_model = context.sessions
+      .runtime(task.frontmatter.sessionId)
+      .getModel();
+    if (!task_model) {
+      throw new Error(`Task "${task.taskId}" requires a configured model`);
+    }
+    const taskSessionRuntime = createTaskSessionRuntimePort({
+      context,
+      model: task_model,
+      runDirAbs,
+      runSessionId,
+      userSimulatorSessionId,
+      ...(params.agent_env ? { agent_env: params.agent_env } : {}),
+      ...(params.agent_systems ? { agent_systems: params.agent_systems } : {}),
+    });
     let lastRoundRuleErrors: string[] = [];
     let lastRoundDecision: UserSimulatorDecision | null = null;
     let lastFeedback = "";

package/src/task/runtime/TaskActionExecution.ts

@@ -7,6 +7,7 @@
  */
 
 import type { AgentContext } from "@downcity/agent";
+import type { PluginRunContext } from "@downcity/agent";
 import type {
   TaskCronRegisterResult,
   TaskListActionPayload,
@@ -158,11 +159,13 @@ export async function executeTaskCreateAction(params: {
 export async function executeTaskRunAction(params: {
   context: AgentContext;
   payload: TaskRunRequest;
+  run_context?: PluginRunContext;
 }) {
   const result = await runTaskDefinition({
     context: params.context,
     projectRoot: params.context.rootPath,
     request: params.payload,
+    run_context: params.run_context,
   });
   if (!result.success) {
     return {

package/src/task/runtime/TaskPluginActionRegistry.ts

@@ -222,6 +222,7 @@ export function createTaskPluginActions(params: {
         return executeTaskRunAction({
           context: actionParams.context,
           payload: actionParams.input as TaskRunRequest,
+          run_context: actionParams.run_context,
         });
       },
     }),

package/src/task/runtime/TaskRunChatDispatch.ts

@@ -53,7 +53,7 @@ export async function dispatchTaskRunCompletionToChat(params: {
   if (!finalText) return;
 
   try {
-    const sent = await params.context.invoke.invoke({
+    const sent = await params.context.plugins.runAction({
       plugin: "chat",
       action: "send",
       payload: {

package/src/task/runtime/TaskRunnerRound.ts

@@ -11,7 +11,6 @@ import fs from "fs-extra";
 import type { AgentContext } from "@downcity/agent";
 import { runSandboxCommand } from "@downcity/shell/sandbox/SandboxRunner.js";
 import type { ShellHostContext } from "@downcity/shell/types/ShellHostContext.js";
-import { withShellRunScope } from "@downcity/shell";
 import type { SessionRunResult } from "@downcity/agent";
 import type { SessionRunContext } from "@downcity/agent";
 import type { JsonObject } from "@downcity/agent";
@@ -22,7 +21,6 @@ import type {
   TaskSessionRuntimePort,
   UserSimulatorDecision,
 } from "@/task/runtime/TaskRunnerTypes.js";
-import { withSessionRunScope } from "@downcity/agent";
 import { appendTaskRoundUserMessage } from "./TaskRunnerSession.js";
 
 function stripTaskSecretEnv(env: NodeJS.ProcessEnv): void {
@@ -246,23 +244,12 @@ export async function runAgentRound(params: {
     // ignore
   }
 
-  const result = await withSessionRunScope(
-    {
+  const result = await params.taskSessionRuntime
+    .getExecutor(params.sessionId)
+    .run({
+      query: params.query,
       runContext: create_task_run_context(params.sessionId),
-    },
-    () =>
-      withShellRunScope(
-        {
-          run_context: {
-            session_id: params.sessionId,
-          },
-        },
-        () =>
-          params.taskSessionRuntime.getExecutor(params.sessionId).run({
-            query: params.query,
-          }),
-      ),
-  );
+    });
   const outputPick = pickAgentOutput(result.assistantMessage);
 
   if (!result.success) {
@@ -296,26 +283,21 @@ export async function runScriptTask(params: {
   const scriptAbs = path.join(params.runDirAbs, "task-script.sh");
   await fs.writeFile(scriptAbs, body.endsWith("\n") ? body : `${body}\n`, "utf-8");
 
-  const execResult = await withSessionRunScope(
-    { runContext: create_task_run_context(params.sessionId) },
-    () => {
-      const childEnv: NodeJS.ProcessEnv = {
-        ...process.env,
-        DC_SESSION_ID: params.sessionId,
-      };
-      stripTaskSecretEnv(childEnv);
-      return runSandboxCommand({
-        context: params.context as unknown as ShellHostContext,
-        executionId: `task-script:${params.sessionId}`,
-        executionDir: params.runDirAbs,
-        cmd: `sh "${scriptAbs.replace(/(["\\$`])/g, "\\$1")}"`,
-        cwd: params.runDirAbs,
-        shellPath: "/bin/sh",
-        login: false,
-        baseEnv: childEnv,
-      });
-    }
-  );
+  const childEnv: NodeJS.ProcessEnv = {
+    ...process.env,
+    DC_SESSION_ID: params.sessionId,
+  };
+  stripTaskSecretEnv(childEnv);
+  const execResult = await runSandboxCommand({
+    context: params.context as unknown as ShellHostContext,
+    executionId: `task-script:${params.sessionId}`,
+    executionDir: params.runDirAbs,
+    cmd: `sh "${scriptAbs.replace(/(["\\$`])/g, "\\$1")}"`,
+    cwd: params.runDirAbs,
+    shellPath: "/bin/sh",
+    login: false,
+    baseEnv: childEnv,
+  });
 
   const stdout = String(execResult.stdout || "").trim();
   const stderr = String(execResult.stderr || "").trim();

package/src/task/runtime/TaskRunnerSession.ts

@@ -2,8 +2,8 @@
  * TaskRunnerSession：task runner 的 session 装配模块。
  *
  * 关键点（中文）
- * - 负责构建 task 专用 Executor / JsonlSessionHistoryStore 运行时。
- * - 负责把每轮 user/assistant 消息写入 run 目录对应的 messages.jsonl。
+ * - 负责构建 task 专用 Executor / SessionMessages 运行时。
+ * - 负责把每轮 user/assistant 消息写入 run 目录对应的 canonical Message Store。
  * - 这些能力与任务编排逻辑解耦后，task 主流程会更聚焦于状态流转。
  * - 当前只有 api 执行模式。
  */
@@ -14,14 +14,18 @@ import type { AgentContext } from "@downcity/agent";
 import { Executor } from "@downcity/agent";
 import type { SessionRunResult } from "@downcity/agent";
 import type { TaskSessionRuntimePort } from "@/task/runtime/TaskRunnerTypes.js";
-import { drainDeferredPersistedUserMessages } from "@downcity/agent";
-import { JsonlSessionHistoryComposer } from "@downcity/agent";
-import { JsonlSessionHistoryStore } from "@downcity/agent";
-import { JsonlSessionCompactionComposer } from "@downcity/agent";
-import { LocalSessionContextComposer } from "@downcity/agent";
+import {
+  DefaultSessionComposer,
+  JsonlSessionMessageStore,
+  SessionMessages,
+} from "@downcity/agent";
 import { DefaultSessionSystemComposer } from "@downcity/agent";
 import { Shell } from "@downcity/shell";
 import type { SessionExecutor } from "@downcity/agent";
+import type {
+  SessionComposeInput,
+  SessionStepInput,
+} from "@downcity/agent";
 
 /**
  * 把 task round 的 user query 落盘到对应 run context。
@@ -36,20 +40,18 @@ export async function appendTaskRoundUserMessage(params: {
 }): Promise<void> {
   const text = String(params.query || "").trim();
   if (!text) return;
-  const historyStore = params.taskSessionRuntime.getHistoryStore(params.sessionId);
-  await historyStore.write_record(
-    historyStore.userText({
+  const messages = params.taskSessionRuntime.get_messages(params.sessionId);
+  await messages.append_user_message({
+    turn_id:
+      `task:${params.taskId}:${params.actorId}:${Date.now()}`,
+    input_type: "prompt",
+    parts: [{
+      part_id: `task-user:${Date.now()}`,
+      type: "text",
       text,
-      metadata: {
-        sessionId: params.sessionId,
-        extra: {
-          taskId: params.taskId,
-          actorId: params.actorId,
-          actorName: params.actorName,
-        },
-      },
-    }),
-  );
+      state: "done",
+    }],
+  });
 }
 
 /**
@@ -65,6 +67,10 @@ export function createTaskSessionRuntimePort(params: {
   runDirAbs: string;
   runSessionId: string;
   userSimulatorSessionId: string;
+  /** 当前 task 显式继承的 Agent env 快照。 */
+  agent_env?: Readonly<Record<string, string>>;
+  /** 当前 task 显式继承的 Agent instruction 快照。 */
+  agent_systems?: readonly string[];
 }): TaskSessionRuntimePort {
   const {
     context,
@@ -73,28 +79,33 @@ export function createTaskSessionRuntimePort(params: {
     runSessionId,
     userSimulatorSessionId,
   } = params;
-  const compactionComposer = new JsonlSessionCompactionComposer();
+  const effective_env = params.agent_env
+    ? { ...params.agent_env }
+    : { ...context.env };
+  const effective_systems = params.agent_systems
+    ? [...params.agent_systems]
+    : [...context.systems];
   const systemComposer = new DefaultSessionSystemComposer({
     projectRoot: context.rootPath,
-    getStaticSystemPrompts: () => context.systems,
+    getStaticSystemPrompts: () => [...effective_systems],
     getContext: () => context,
     profile: "task",
   });
-  const historyStoresBySessionId = new Map<string, JsonlSessionHistoryStore>();
-  const historyComposersBySessionId = new Map<string, JsonlSessionHistoryComposer>();
+  const messages_by_session_id = new Map<string, SessionMessages>();
+  const created_at_by_session_id = new Map<string, number>();
   const runtimesBySessionId = new Map<string, SessionExecutor>();
   const shell = new Shell({
     root_path: context.rootPath,
-    env: context.env,
+    env: effective_env,
     logger: context.logger,
   });
   const shell_tools = shell.tools as unknown as Record<string, Tool>;
 
-  const resolveTaskHistoryStore = (sessionId: string): JsonlSessionHistoryStore => {
-    const existing = historyStoresBySessionId.get(sessionId);
+  const resolve_task_messages = (session_id: string): SessionMessages => {
+    const existing = messages_by_session_id.get(session_id);
     if (existing) return existing;
 
-    const key = String(sessionId || "").trim();
+    const key = String(session_id || "").trim();
     if (!key) {
       throw new Error("TaskSessionRuntimePort requires a non-empty sessionId");
     }
@@ -105,39 +116,45 @@ export function createTaskSessionRuntimePort(params: {
           ? path.join(runDirAbs, "user-simulator")
           : undefined;
 
-    const created = new JsonlSessionHistoryStore({
-      rootPath: context.rootPath,
-      sessionId: key,
-      ...(runMessagesDirPath
-        ? {
-            paths: {
-              sessionDirPath: runMessagesDirPath,
-              messagesDirPath: runMessagesDirPath,
-              messagesFilePath: path.join(runMessagesDirPath, "messages.jsonl"),
-              metaFilePath: path.join(runMessagesDirPath, "meta.json"),
-              archiveDirPath: path.join(runMessagesDirPath, "archive"),
-            },
-          }
-        : {}),
+    const messages_dir_path = runMessagesDirPath || path.join(runDirAbs, key);
+    const created = new SessionMessages({
+      session_id: key,
+      store: new JsonlSessionMessageStore({
+        session_id: key,
+        file_path: path.join(messages_dir_path, "active.jsonl"),
+        assistant_message_file_path: path.join(
+          messages_dir_path,
+          "assistant_message.json",
+        ),
+      }),
+      publish: () => {},
     });
-    historyStoresBySessionId.set(key, created);
+    messages_by_session_id.set(key, created);
+    created_at_by_session_id.set(key, Date.now());
     return created;
   };
 
-  const resolveTaskHistoryComposer = (sessionId: string): JsonlSessionHistoryComposer => {
-    const key = String(sessionId || "").trim();
-    const existing = historyComposersBySessionId.get(key);
-    if (existing) return existing;
-    const created = new JsonlSessionHistoryComposer({
-      store: resolveTaskHistoryStore(key),
-    });
-    historyComposersBySessionId.set(key, created);
-    return created;
-  };
+  class TaskSessionComposer extends DefaultSessionComposer {
+    override async compose(input: SessionComposeInput): Promise<SessionStepInput> {
+      const composed = await super.compose(input);
+      return {
+        ...composed,
+        system: await systemComposer.resolve({
+          sessionId: input.session.session_id,
+          agentEnv: input.state.env,
+          agentSystems: input.state.systems,
+          injectedUserMessages: [],
+          deferredPersistedUserMessages: [],
+          pendingAssistantFileParts: [],
+        }),
+        system_blocks: undefined,
+      };
+    }
+  }
 
   return {
-    getHistoryStore(sessionId: string): JsonlSessionHistoryStore {
-      return resolveTaskHistoryStore(sessionId);
+    get_messages(session_id: string): SessionMessages {
+      return resolve_task_messages(session_id);
     },
     getExecutor(sessionId: string): SessionExecutor {
       const key = String(sessionId || "").trim();
@@ -147,23 +164,42 @@ export function createTaskSessionRuntimePort(params: {
       const existing = runtimesBySessionId.get(key);
       if (existing) return existing;
 
-      const historyStore = resolveTaskHistoryStore(key);
-      const historyComposer = resolveTaskHistoryComposer(key);
-      const contextComposer = new LocalSessionContextComposer({
-        sessionId: key,
-        getTools: () => shell_tools,
-      });
+      const messages = resolve_task_messages(key);
+      const composer = new TaskSessionComposer();
       const created = new Executor({
         sessionId: key,
+        composer,
+        get_compose_input: async (run_context, retry_count) => ({
+          session: {
+            agent_id: "task",
+            session_id: key,
+            project_root: context.rootPath,
+            created_at: created_at_by_session_id.get(key) || Date.now(),
+            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+          },
+          state: {
+            model,
+            env: effective_env,
+            systems: effective_systems,
+            tools: shell_tools,
+            instruction_system_blocks: [],
+            managed_plugin_system_blocks: [],
+            plugin_system_blocks: [],
+          },
+          history: await messages.context_snapshot(),
+          turn: {
+            ...(run_context.turnId ? { turn_id: run_context.turnId } : {}),
+            retry_count,
+          },
+        }),
+        commit_compaction: async (plan) => {
+          await messages.compact_active({
+            through_sequence: plan.through_sequence,
+            summary: plan.summary,
+          });
+        },
         getModel: () => model,
         logger: context.logger,
-        historyStore,
-        historyComposer,
-        compactionComposer,
-        contextComposer,
-        systemComposer,
-        getTools: () => shell_tools,
-        getEnv: () => ({ ...context.env }),
       });
       runtimesBySessionId.set(key, created);
       return created;
@@ -181,12 +217,12 @@ export async function appendTaskAssistantMessage(params: {
   rawResult: SessionRunResult;
 }): Promise<void> {
   const { taskSessionRuntime, sessionId, rawResult } = params;
-  const historyStore = taskSessionRuntime.getHistoryStore(sessionId);
+  const messages = taskSessionRuntime.get_messages(sessionId);
   if (rawResult.assistantMessage) {
-    await historyStore.write_record(rawResult.assistantMessage);
+    await messages.append_record(rawResult.assistantMessage);
   }
-  const deferredUserMessages = drainDeferredPersistedUserMessages(sessionId);
+  const deferredUserMessages = rawResult.deferredPersistedUserMessages || [];
   for (const deferred of deferredUserMessages) {
-    await historyStore.write_record(deferred);
+    await messages.append_record(deferred);
   }
 }

package/src/task/runtime/TaskRunnerTypes.ts

@@ -6,7 +6,7 @@
  * - 这些类型服务于 task 运行链路，统一归档到 `src/types/task/`。
  */
 
-import type { JsonlSessionHistoryStore } from "@downcity/agent";
+import type { SessionMessages } from "@downcity/agent";
 import type { SessionExecutor } from "@downcity/agent";
 import type {
   ShipTaskRunExecutionStatusV1,
@@ -171,7 +171,7 @@ export type ScriptExecutionResult = {
  *
  * 关键点（中文）
  * - task runner 不直接依赖具体 SDK `Session` 实现。
- * - 这里暴露的是 task 场景最小可用端口：执行器 + history Store。
+ * - 这里暴露的是 task 场景最小可用端口：执行器 + canonical Messages。
  */
 export type TaskSessionRuntimePort = {
   /**
@@ -179,9 +179,9 @@ export type TaskSessionRuntimePort = {
    */
   getExecutor(sessionId: string): SessionExecutor;
   /**
-   * 获取指定 sessionId 对应的 JsonlSessionHistoryStore。
+   * 获取指定 sessionId 对应的 canonical Session Messages。
    */
-  getHistoryStore(sessionId: string): JsonlSessionHistoryStore;
+  get_messages(session_id: string): SessionMessages;
 };
 
 /**

package/src/task/types/TaskPluginOptions.ts

@@ -19,4 +19,5 @@ export interface TaskPluginOptions {
    * - `time:<ISO8601-with-timezone>` 一次性任务以 ISO 字符串自身的 offset 为准，这里的时区主要影响 cron 表达式。
    */
   timezone?: string;
+
 }