@downcity/agent 1.1.74 → 1.1.81

package/src/executor/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -106,6 +106,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
   private readonly overrideMessagesFilePath?: string;
   private readonly overrideMetaFilePath?: string;
   private readonly overrideArchiveDirPath?: string;
+  private readonly overrideInflightFilePath?: string;
 
   constructor(options: JsonlSessionHistoryStoreOptions) {
     const rootPath = String(options.rootPath || "").trim();
@@ -135,6 +136,9 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     this.overrideArchiveDirPath = this.readOptionalPath(
       options.paths?.archiveDirPath,
     );
+    this.overrideInflightFilePath = this.readOptionalPath(
+      options.paths?.inflightFilePath,
+    );
   }
 
   private readOptionalPath(value: string | undefined): string | undefined {
@@ -183,6 +187,14 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     return path.join(this.getMessagesDirPath(), "archive");
   }
 
+  private getInflightFilePath(): string {
+    if (this.overrideInflightFilePath) return this.overrideInflightFilePath;
+    if (this.overrideMessagesDirPath) {
+      return path.join(this.overrideMessagesDirPath, "inflight.json");
+    }
+    return path.join(this.getMessagesDirPath(), "inflight.json");
+  }
+
   private getLockFilePath(): string {
     return path.join(this.getMessagesDirPath(), ".session.lock");
   }
@@ -199,6 +211,75 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     return value || undefined;
   }
 
+  private normalizePersistedMessage(
+    input: unknown,
+  ): SessionMessageV1 | null {
+    if (!input || typeof input !== "object") return null;
+    const candidate = input as Partial<SessionMessageV1>;
+    const role = String(candidate.role || "");
+    if (role !== "user" && role !== "assistant") return null;
+    if (!Array.isArray(candidate.parts)) return null;
+    return candidate as SessionMessageV1;
+  }
+
+  private hasStructuredAssistantParts(message: SessionMessageV1 | null): boolean {
+    if (!message || message.role !== "assistant" || !Array.isArray(message.parts)) {
+      return false;
+    }
+    return message.parts.some((part) => {
+      if (!part || typeof part !== "object") return false;
+      const type = typeof part.type === "string" ? part.type.trim() : "";
+      return Boolean(type) && type !== "text";
+    });
+  }
+
+  private mergeInflightWithFinal(
+    inflight: SessionMessageV1,
+    finalMessage: SessionMessageV1,
+  ): SessionMessageV1 {
+    const final_parts = Array.isArray(finalMessage.parts)
+      ? finalMessage.parts.filter((part) => part && typeof part === "object")
+      : [];
+    if (this.hasStructuredAssistantParts(finalMessage)) {
+      return finalMessage;
+    }
+    if (final_parts.length === 0) return inflight;
+
+    const inflight_parts = Array.isArray(inflight.parts)
+      ? inflight.parts
+      : [];
+    const last_inflight_part =
+      inflight_parts.length > 0 ? inflight_parts[inflight_parts.length - 1] : undefined;
+    const last_inflight_text =
+      last_inflight_part &&
+      typeof last_inflight_part === "object" &&
+      last_inflight_part.type === "text" &&
+      typeof last_inflight_part.text === "string"
+        ? last_inflight_part.text.trim()
+        : "";
+    const append_parts = final_parts.filter((part, index) => {
+      if (index > 0) return true;
+      if (!part || typeof part !== "object" || part.type !== "text") return true;
+      const next_text = typeof part.text === "string" ? part.text.trim() : "";
+      if (!next_text) return false;
+      return next_text !== last_inflight_text;
+    });
+
+    return {
+      ...inflight,
+      id: finalMessage.id,
+      metadata: {
+        ...(inflight.metadata || {
+          v: 1 as const,
+          ts: Date.now(),
+          sessionId: this.sessionId,
+        }),
+        ...(finalMessage.metadata || {}),
+      },
+      parts: [...inflight_parts, ...append_parts],
+    };
+  }
+
   private async readMetaUnsafe(): Promise<SessionHistoryMetaV1> {
     const file = this.getMetaFilePath();
     try {
@@ -261,6 +342,40 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     await fs.writeJson(this.getMetaFilePath(), normalized, { spaces: 2 });
   }
 
+  private async readInflightUnsafe(): Promise<SessionMessageV1 | null> {
+    const file = this.getInflightFilePath();
+    try {
+      const raw = await fs.readJson(file);
+      return this.normalizePersistedMessage(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  private async writeInflightUnsafe(message: SessionMessageV1): Promise<void> {
+    const normalized = this.normalizePersistedMessage(message);
+    if (!normalized || normalized.role !== "assistant") {
+      throw new Error("inflight assistant must be an assistant UIMessage");
+    }
+    const file = this.getInflightFilePath();
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeJson(temp, normalized, { spaces: 2 });
+    await fs.move(temp, file, { overwrite: true });
+  }
+
+  private async removeInflightUnsafe(): Promise<void> {
+    await fs.remove(this.getInflightFilePath());
+  }
+
+  private async appendMessageUnsafe(message: SessionMessageV1): Promise<void> {
+    await fs.appendFile(
+      this.getMessagesFilePath(),
+      JSON.stringify(message) + "\n",
+      "utf8",
+    );
+  }
+
   private async withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
     await this.ensureLayout();
     const lockPath = this.getLockFilePath();
@@ -361,11 +476,48 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
 
   async append(message: SessionMessageV1): Promise<void> {
     await this.withWriteLock(async () => {
-      await fs.appendFile(
-        this.getMessagesFilePath(),
-        JSON.stringify(message) + "\n",
-        "utf8",
-      );
+      const normalized = this.normalizePersistedMessage(message);
+      if (!normalized) return;
+
+      // 关键点（中文）：若上一次 assistant 在运行中中断，新的 user 到来前先把残留快照收口到正式历史，
+      // 避免 `list()` 时旧 inflight 跑到新 user 后面，打乱时序。
+      if (normalized.role === "user") {
+        const current_inflight = await this.readInflightUnsafe();
+        if (current_inflight) {
+          await this.appendMessageUnsafe(current_inflight);
+          await this.removeInflightUnsafe();
+        }
+      }
+
+      await this.appendMessageUnsafe(normalized);
+    });
+  }
+
+  async readInflight(): Promise<SessionMessageV1 | null> {
+    await this.ensureLayout();
+    return this.readInflightUnsafe();
+  }
+
+  async writeInflight(message: SessionMessageV1): Promise<void> {
+    await this.withWriteLock(async () => {
+      await this.writeInflightUnsafe(message);
+    });
+  }
+
+  async finalizeInflight(message?: SessionMessageV1 | null): Promise<void> {
+    await this.withWriteLock(async () => {
+      const current_inflight = await this.readInflightUnsafe();
+      const normalized_message = this.normalizePersistedMessage(message);
+      const final_message =
+        current_inflight && normalized_message
+          ? this.mergeInflightWithFinal(current_inflight, normalized_message)
+          : normalized_message || current_inflight;
+      if (final_message) {
+        await this.appendMessageUnsafe(final_message);
+      }
+      if (current_inflight) {
+        await this.removeInflightUnsafe();
+      }
     });
   }
 
@@ -377,16 +529,17 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     const out: SessionMessageV1[] = [];
     for (const line of lines) {
       try {
-        const obj = JSON.parse(line) as Partial<SessionMessageV1>;
-        if (!obj || typeof obj !== "object") continue;
-        const role = String(obj.role || "");
-        if (role !== "user" && role !== "assistant") continue;
-        if (!Array.isArray(obj.parts)) continue;
-        out.push(obj as SessionMessageV1);
+        const obj = this.normalizePersistedMessage(JSON.parse(line));
+        if (!obj) continue;
+        out.push(obj);
       } catch {
         // ignore invalid lines
       }
     }
+    const current_inflight = await this.readInflightUnsafe();
+    if (current_inflight) {
+      out.push(current_inflight);
+    }
     return out;
   }
 

package/src/executor/tools/plugin/PluginToolBridge.ts

@@ -0,0 +1,161 @@
+/**
+ * Plugin tool 运行时桥接。
+ *
+ * 关键点（中文）
+ * - tool 层不直接持有 agent 或 plugin registry，只通过装配期注入的 PluginPort 调用 action。
+ * - 如果 action 返回 AI SDK UIMessage，则抽取 file parts 并入最终 assistant 消息。
+ * - 返回给模型的 tool result 只保留短摘要，避免 data URL 等大内容污染上下文。
+ */
+
+import type { FileUIPart } from "ai";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { PluginPort } from "@/plugin/types/Plugin.js";
+import type {
+  PluginCallInput,
+  PluginCallToolResult,
+} from "@/executor/tools/plugin/types/PluginTool.js";
+import { enqueueAssistantFileParts } from "@executor/SessionRunScope.js";
+
+let plugin_tool_runtime: PluginPort | null = null;
+
+/**
+ * 注入 plugin tool 运行时。
+ */
+export function setPluginToolRuntime(next: PluginPort): void {
+  plugin_tool_runtime = next;
+}
+
+/**
+ * 读取已注入的 plugin tool 运行时。
+ */
+function require_plugin_tool_runtime(): PluginPort {
+  if (plugin_tool_runtime) return plugin_tool_runtime;
+  throw new Error(
+    "Plugin tool runtime is not initialized. Ensure agent assembly completed before using plugin_call.",
+  );
+}
+
+/**
+ * 判断值是否为普通对象。
+ */
+function to_json_object(value: unknown): JsonObject | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as JsonObject;
+}
+
+/**
+ * 判断 UI part 是否为 file part。
+ */
+function is_file_part(value: unknown): value is FileUIPart {
+  const record = to_json_object(value);
+  if (!record) return false;
+  return (
+    record.type === "file" &&
+    typeof record.mediaType === "string" &&
+    typeof record.url === "string"
+  );
+}
+
+/**
+ * 从 action data 中抽取可落盘的 assistant file parts。
+ */
+function extract_assistant_file_parts(data: JsonValue | undefined): FileUIPart[] {
+  const message = to_json_object(data);
+  const parts: unknown[] = Array.isArray(message?.parts) ? message.parts : [];
+  return parts.filter(is_file_part);
+}
+
+/**
+ * 生成给模型读取的短摘要。
+ */
+function summarize_action_data(data: JsonValue | undefined): JsonObject {
+  const message = to_json_object(data);
+  const parts: unknown[] = Array.isArray(message?.parts) ? message.parts : [];
+  const file_parts = parts.filter(is_file_part);
+  if (parts.length > 0) {
+    return {
+      kind: "ui_message",
+      role: typeof message?.role === "string" ? message.role : "assistant",
+      part_count: parts.length,
+      file_count: file_parts.length,
+      files: file_parts.map((part, index) => ({
+        index,
+        mediaType: part.mediaType,
+        filename: typeof part.filename === "string" ? part.filename : "",
+        // 关键点（中文）：不把 data URL 或长 URL 原样返回给模型，完整内容只进入 assistant file part。
+        has_url: Boolean(part.url),
+      })),
+    };
+  }
+  if (data === undefined) return {};
+  return {
+    kind: "json",
+    value: data,
+  };
+}
+
+/**
+ * 调用 plugin action 并桥接最终 assistant file parts。
+ */
+export async function invokePluginCallTool(
+  input: PluginCallInput,
+): Promise<PluginCallToolResult> {
+  const plugin = String(input.plugin || "").trim();
+  const action = String(input.action || "").trim();
+  const payload = to_json_object(input.payload ?? {}) ?? {};
+  if (!plugin) {
+    return {
+      success: false,
+      plugin,
+      action,
+      assistant_file_count: 0,
+      message: "plugin is required",
+      error: "plugin is required",
+    };
+  }
+  if (!action) {
+    return {
+      success: false,
+      plugin,
+      action,
+      assistant_file_count: 0,
+      message: "action is required",
+      error: "action is required",
+    };
+  }
+
+  try {
+    const runtime = require_plugin_tool_runtime();
+    const result = await runtime.runAction({
+      plugin,
+      action,
+      payload,
+    });
+    const file_parts = result.success
+      ? extract_assistant_file_parts(result.data)
+      : [];
+    if (file_parts.length > 0) {
+      enqueueAssistantFileParts(file_parts);
+    }
+    return {
+      success: result.success,
+      plugin,
+      action,
+      assistant_file_count: file_parts.length,
+      message:
+        String(result.message || result.error || "").trim() ||
+        (result.success ? "plugin action completed" : "plugin action failed"),
+      ...(result.error ? { error: result.error } : {}),
+      data: summarize_action_data(result.data),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      plugin,
+      action,
+      assistant_file_count: 0,
+      message: String(error),
+      error: String(error),
+    };
+  }
+}

package/src/executor/tools/plugin/PluginToolDefinition.ts

@@ -0,0 +1,32 @@
+/**
+ * Plugin tools。
+ *
+ * 设计目标（中文）
+ * - plugin_call 是 agent 内置 plugin action 桥，类似 shell tool 的底层能力入口。
+ * - tool 只负责 AI SDK 工具协议适配，不理解具体 plugin 的业务语义。
+ * - 插件业务输出若包含 UIMessage file parts，会由 bridge 并入最终 assistant 消息。
+ */
+
+import { tool } from "ai";
+import type { PluginCallInput } from "@/executor/tools/plugin/types/PluginTool.js";
+import { invokePluginCallTool, setPluginToolRuntime } from "./PluginToolBridge.js";
+import { plugin_call_input_schema } from "./PluginToolSchemas.js";
+
+export { setPluginToolRuntime } from "./PluginToolBridge.js";
+
+/**
+ * `plugin_call`：调用已注册 plugin action。
+ */
+export const plugin_call = tool({
+  description:
+    "Call a registered agent plugin action. Use this for plugin capabilities such as image generation. Generated files may be attached to the final assistant message automatically.",
+  inputSchema: plugin_call_input_schema,
+  execute: async (input) => await invokePluginCallTool(input as PluginCallInput),
+});
+
+/**
+ * Plugin 工具导出集合。
+ */
+export const plugin_tools = {
+  plugin_call,
+};

package/src/executor/tools/plugin/PluginToolSchemas.ts

@@ -0,0 +1,20 @@
+/**
+ * Plugin tool 输入 schema。
+ *
+ * 关键点（中文）
+ * - plugin_call 是 agent 内置的最低层 plugin action 桥。
+ * - schema 只描述模型需要提交的目标 plugin、action 与 JSON payload。
+ */
+
+import { z } from "zod";
+
+export const plugin_call_input_schema = z.object({
+  plugin: z.string().describe("Registered plugin name to call, for example image."),
+  action: z.string().describe("Plugin action name to execute, for example generate."),
+  payload: z
+    .object({})
+    .passthrough()
+    .optional()
+    .default({})
+    .describe("JSON payload passed to the plugin action."),
+});

package/src/executor/tools/plugin/types/PluginTool.ts

@@ -0,0 +1,41 @@
+/**
+ * Plugin tool 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里描述模型通过 plugin_call 提交的最低层调用协议。
+ * - payload 保持 JSON 对象，避免 tool 层理解具体 plugin 的业务字段。
+ */
+
+import type { JsonObject } from "@/types/common/Json.js";
+
+/**
+ * plugin_call 输入。
+ */
+export interface PluginCallInput {
+  /** 目标 plugin 名称。 */
+  plugin: string;
+  /** 目标 action 名称。 */
+  action: string;
+  /** 传给 plugin action 的 JSON payload。 */
+  payload?: JsonObject;
+}
+
+/**
+ * plugin_call 返回给模型的摘要结果。
+ */
+export interface PluginCallToolResult {
+  /** 调用是否成功。 */
+  success: boolean;
+  /** 目标 plugin 名称。 */
+  plugin: string;
+  /** 目标 action 名称。 */
+  action: string;
+  /** 本次 action 产生并写入 assistant 消息的 file part 数量。 */
+  assistant_file_count: number;
+  /** 人类可读消息。 */
+  message: string;
+  /** 错误信息。 */
+  error?: string;
+  /** 返回给模型读取的短摘要数据。 */
+  data?: JsonObject;
+}

package/src/executor/tools/shell/ShellToolBridge.ts

@@ -16,7 +16,7 @@ import type { ShellActionResponse } from "@/executor/tools/shell/types/ShellPlug
 import {
   enqueueDeferredPersistedUserMessage,
   enqueueInjectedUserMessage,
-  getSessionRunScope,
+  getSessionRunContext,
 } from "@executor/SessionRunScope.js";
 
 /**
@@ -88,8 +88,8 @@ async function injectUserTextMessage(params: {
    */
   note?: string;
 }): Promise<boolean> {
-  const store = getSessionRunScope();
-  const sessionId = String(store?.sessionId || "").trim();
+  const run_context = getSessionRunContext();
+  const sessionId = String(run_context?.sessionId || "").trim();
   const text = String(params.text || "").trim();
   if (!sessionId || !text) return false;
   const note = String(params.note || "runtime_injected_user_message");

package/src/executor/tools/shell/ShellToolFormatting.ts

@@ -3,35 +3,9 @@
  *
  * 关键点（中文）
  * - shell 会话生命周期已经统一收敛到 shell plugin runtime。
- * - 这里仅保留当前仍被 tool 与测试复用的最小能力：命令安全校验与 env 注入。
+ * - 这里仅保留当前仍被 tool 与测试复用的最小能力：命令安全校验。
  */
 
-import { stripInvocationAuthEnv } from "@/runtime/auth/AuthEnv.js";
-import { getSessionRunScope } from "@executor/SessionRunScope.js";
-
-function setEnvString(
-  env: NodeJS.ProcessEnv,
-  key: string,
-  value: string | undefined,
-): void {
-  if (typeof value !== "string") return;
-  const trimmed = value.trim();
-  if (!trimmed) return;
-  env[key] = trimmed;
-}
-
-function applyEnvMap(
-  env: NodeJS.ProcessEnv,
-  entries?: Record<string, string>,
-): void {
-  if (!entries) return;
-  for (const [rawKey, rawValue] of Object.entries(entries)) {
-    const key = String(rawKey || "").trim();
-    if (!key) continue;
-    setEnvString(env, key, rawValue);
-  }
-}
-
 /**
  * 对 `town chat send` 命令做前置安全校验。
  *
@@ -58,26 +32,3 @@ export function validateChatSendCommand(cmd: string): string | null {
     "If your message is multi-line, use `town chat send --stdin` (with heredoc/pipe), `--text-file`, or explicit `--text`.",
   ].join(" ");
 }
-
-/**
- * 构建 shell 子进程环境变量。
- *
- * 关键点（中文）
- * - 当前仍用于 shell tool / shell runtime 与相关测试。
- * - 优先级：显式注入 > 当前请求上下文变量 > 宿主进程环境。
- * - 默认剥离 Bearer Token，避免通用 shell 隐式走本地 HTTP。
- */
-export function buildShellContextEnv(
-  injected?: Record<string, string>,
-): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = { ...process.env };
-  const contextCtx = getSessionRunScope();
-
-  applyEnvMap(env, injected);
-  setEnvString(env, "DC_SESSION_ID", contextCtx?.sessionId);
-  setEnvString(env, "DC_CITY_HOST", process.env.DC_CITY_HOST);
-  setEnvString(env, "DC_CITY_PORT", process.env.DC_CITY_PORT);
-  stripInvocationAuthEnv(env);
-
-  return env;
-}

package/src/executor/types/SessionHistoryPaths.ts

@@ -30,4 +30,9 @@ export type SessionHistoryPathOverrides = {
    * 历史归档目录（通常是 `.../messages/archive`）。
    */
   archiveDirPath?: string;
+
+  /**
+   * 运行中 assistant 快照路径（通常是 `.../messages/inflight.json`）。
+   */
+  inflightFilePath?: string;
 };

package/src/executor/types/SessionRun.ts

@@ -9,7 +9,9 @@
 
 import type { Tool, UIMessageChunk } from "ai";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**
  * Assistant step 可见性。
@@ -94,6 +96,15 @@ export interface SessionRunResult {
    * 最终 assistant 消息。
    */
   assistantMessage: SessionMessageV1;
+
+  /**
+   * 本轮执行结束后待写入长期历史的 user 消息。
+   *
+   * 关键点（中文）
+   * - 这些消息通常由 tool 运行时在执行过程中动态注入。
+   * - 为保证消息顺序稳定，统一在 assistant 结果落盘后再由外层 Session 持久化。
+   */
+  deferredPersistedUserMessages?: SessionUserMessageV1[];
 }
 
 /**
@@ -104,6 +115,15 @@ export interface SessionRunInput {
    * 本轮用户输入查询文本。
    */
   query: string;
+
+  /**
+   * 本轮显式运行上下文。
+   *
+   * 关键点（中文）
+   * - 这里承载 step 合并、UI chunk 回调等跨组件运行期数据。
+   * - 若未传入，则由执行器按最小默认值兜底创建。
+   */
+  runContext?: SessionRunContext;
 }
 
 /**