@downcity/agent 1.1.199 → 1.1.202

package/src/executor/store/history/SessionHistoryStore.ts

@@ -1,19 +1,19 @@
 /**
- * SessionHistoryStore：会话历史事实源接口。
+ * SessionHistoryStore：会话 record 事实源接口。
  *
  * 关键点（中文）
- * - Store 负责消息、meta、archive、lock 等持久化能力。
- * - Composer 只负责把 Store 中的历史组装成本轮模型输入。
+ * - Store 负责 records、meta、archive、lock 等持久化能力。
+ * - Composer 只负责把 Store 中的模型消息 record 组装成本轮模型输入。
  * - 这个接口刻意独立于 Composer，避免把“落盘事实源”误当成“组装策略”。
  */
 
 import type { LanguageModel } from "ai";
 import type {
-  SessionMessageV1,
+  SessionActionRecordV1,
+  SessionRecordV1,
   SessionMetadataV1,
-} from "@/executor/types/SessionMessages.js";
+} from "@/executor/types/SessionRecords.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
-import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 /**
  * compact 输入参数。
@@ -50,9 +50,9 @@ export type SessionHistoryCompactInput = {
   compactRatio: number;
 
   /**
-   * 可选 operation 发布回调。
+   * 可选 action 发布回调。
    */
-  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
+  onAction?: (action: SessionActionRecordV1) => Promise<void>;
 };
 
 /**
@@ -65,39 +65,43 @@ export interface SessionHistoryStore {
   readonly sessionId: string;
 
   /**
-   * 追加一条消息到历史。
+   * 写入一条 session record。
+   *
+   * 说明（中文）
+   * - 模型消息会追加到 JSONL。
+   * - action record 会按稳定 ID upsert 为同一条 record。
    */
-  append(message: SessionMessageV1): Promise<void>;
+  write_record(message: SessionRecordV1): Promise<void>;
 
   /**
    * 读取当前运行中的 assistant 快照。
    */
-  readInflight(): Promise<SessionMessageV1 | null>;
+  read_inflight(): Promise<SessionRecordV1 | null>;
 
   /**
    * 写入当前运行中的 assistant 快照。
    */
-  writeInflight(message: SessionMessageV1): Promise<void>;
+  write_inflight(message: SessionRecordV1): Promise<void>;
 
   /**
    * 用最终 assistant 收口 inflight 快照。
    */
-  finalizeInflight(message?: SessionMessageV1 | null): Promise<void>;
+  finalize_inflight(message?: SessionRecordV1 | null): Promise<void>;
 
   /**
-   * 读取完整消息历史。
+   * 读取完整 session records。
    */
-  list(): Promise<SessionMessageV1[]>;
+  list_records(): Promise<SessionRecordV1[]>;
 
   /**
-   * 读取消息区间 [start, end)。
+   * 读取 session record 区间 [start, end)。
    */
-  slice(start: number, end: number): Promise<SessionMessageV1[]>;
+  slice_records(start: number, end: number): Promise<SessionRecordV1[]>;
 
   /**
-   * 读取消息总条数。
+   * 读取 session record 总条数。
    */
-  size(): Promise<number>;
+  record_count(): Promise<number>;
 
   /**
    * 读取元信息。
@@ -131,7 +135,7 @@ export interface SessionHistoryStore {
      * 可选消息 ID（默认自动生成）。
      */
     id?: string;
-  }): SessionMessageV1;
+  }): SessionRecordV1;
 
   /**
    * 构造 assistant 文本消息。
@@ -162,26 +166,26 @@ export interface SessionHistoryStore {
      * 消息来源（egress/compact）。
      */
     source?: "egress" | "compact";
-  }): SessionMessageV1;
+  }): SessionRecordV1;
 
   /**
-   * 构造 operation 消息。
+   * 构造 action 消息。
    */
-  operation(input: {
+  action(input: {
     /**
-     * 当前 operation 结构化记录。
+     * 当前 action 结构化记录。
      */
-    operation: AgentSessionOperationRecord;
+    action: SessionActionRecordV1;
 
     /**
-     * 消息元信息（除 schema 字段、kind、source 与 operation 字段）。
+     * 消息元信息（除 schema 字段）。
      */
-    metadata: Omit<SessionMetadataV1, "v" | "ts" | "kind" | "source" | "operation"> &
+    metadata: Pick<SessionMetadataV1, "sessionId"> &
       Partial<Pick<SessionMetadataV1, "ts">>;
 
     /**
      * 可选消息 ID（默认自动生成）。
      */
     id?: string;
-  }): SessionMessageV1;
+  }): SessionActionRecordV1;
 }

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

@@ -1,5 +1,5 @@
 /**
- * JsonlSessionHistoryStore：基于 JSONL 的 session history 事实源。
+ * JsonlSessionHistoryStore：基于 JSONL 的 session records 事实源。
  *
  * 关键点（中文）
  * - 负责 `.downcity/.../messages/messages.jsonl`、`meta.json`、archive 与文件锁。
@@ -18,10 +18,15 @@ import { generateId } from "@/utils/Id.js";
 import { getLogger } from "@/utils/logger/Logger.js";
 import { compactSessionMessagesIfNeeded } from "@executor/composer/compaction/jsonl/JsonlSessionCompactionExecutor.js";
 import type {
-  SessionMessageV1,
+  SessionActionRecordV1,
+  SessionRecordV1,
   SessionMetadataV1,
-} from "@/executor/types/SessionMessages.js";
-import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
+} from "@/executor/types/SessionRecords.js";
+import {
+  is_session_action_record,
+  is_session_message_record,
+  to_session_action_record,
+} from "@/executor/types/SessionRecords.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type { SessionHistoryPathOverrides } from "@/executor/types/SessionHistoryPaths.js";
@@ -214,19 +219,62 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
 
   private normalizePersistedMessage(
     input: unknown,
-  ): SessionMessageV1 | null {
+  ): SessionRecordV1 | null {
     if (!input || typeof input !== "object") return null;
-    const candidate = input as Partial<SessionMessageV1>;
+    if ((input as { type?: unknown }).type === "action") {
+      return this.normalize_action_record(input);
+    }
+    const candidate = input as { role?: unknown; parts?: unknown };
     const role = String(candidate.role || "");
-    if (role !== "user" && role !== "assistant" && role !== "operation") {
+    if (role !== "user" && role !== "assistant") {
       return null;
     }
     if (!Array.isArray(candidate.parts)) return null;
-    return candidate as SessionMessageV1;
+    return input as SessionRecordV1;
   }
 
-  private hasStructuredAssistantParts(message: SessionMessageV1 | null): boolean {
-    if (!message || message.role !== "assistant" || !Array.isArray(message.parts)) {
+  private normalize_action_record(input: unknown): SessionActionRecordV1 | null {
+    if (!input || typeof input !== "object") return null;
+    const candidate = input as Partial<SessionActionRecordV1>;
+    const id = String(candidate.id || "").trim();
+    const title = String(candidate.title || "").trim();
+    const state = String(candidate.state || "").trim();
+    if (!id || !title) return null;
+    if (state !== "running" && state !== "completed" && state !== "failed") {
+      return null;
+    }
+    const metadata_input =
+      candidate.metadata && typeof candidate.metadata === "object"
+        ? candidate.metadata
+        : {};
+    const metadata_candidate = metadata_input as Partial<SessionActionRecordV1["metadata"]>;
+    const session_id =
+      String(metadata_candidate.sessionId || "").trim() || this.sessionId;
+    const description = String(candidate.description || "").trim();
+    return {
+      type: "action",
+      id,
+      title,
+      ...(description ? { description } : {}),
+      state,
+      metadata: {
+        v: 1,
+        ts:
+          typeof metadata_candidate.ts === "number"
+            ? metadata_candidate.ts
+            : Date.now(),
+        sessionId: session_id,
+        ...(metadata_candidate.turnId ? { turnId: metadata_candidate.turnId } : {}),
+      },
+    };
+  }
+
+  private hasStructuredAssistantParts(message: SessionRecordV1 | null): boolean {
+    if (
+      !is_session_message_record(message) ||
+      message.role !== "assistant" ||
+      !Array.isArray(message.parts)
+    ) {
       return false;
     }
     return message.parts.some((part) => {
@@ -237,9 +285,11 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
   }
 
   private mergeInflightWithFinal(
-    inflight: SessionMessageV1,
-    finalMessage: SessionMessageV1,
-  ): SessionMessageV1 {
+    inflight: SessionRecordV1,
+    finalMessage: SessionRecordV1,
+  ): SessionRecordV1 {
+    if (!is_session_message_record(finalMessage)) return inflight;
+    if (!is_session_message_record(inflight)) return finalMessage;
     const final_parts = Array.isArray(finalMessage.parts)
       ? finalMessage.parts.filter((part) => part && typeof part === "object")
       : [];
@@ -345,7 +395,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     await fs.writeJson(this.getMetaFilePath(), normalized, { spaces: 2 });
   }
 
-  private async readInflightUnsafe(): Promise<SessionMessageV1 | null> {
+  private async read_inflight_unsafe(): Promise<SessionRecordV1 | null> {
     const file = this.getInflightFilePath();
     try {
       const raw = await fs.readJson(file);
@@ -355,9 +405,12 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     }
   }
 
-  private async writeInflightUnsafe(message: SessionMessageV1): Promise<void> {
+  private async write_inflight_unsafe(message: SessionRecordV1): Promise<void> {
     const normalized = this.normalizePersistedMessage(message);
-    if (!normalized || normalized.role !== "assistant") {
+    if (
+      !is_session_message_record(normalized) ||
+      normalized.role !== "assistant"
+    ) {
       throw new Error("inflight assistant must be an assistant UIMessage");
     }
     const file = this.getInflightFilePath();
@@ -371,7 +424,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     await fs.remove(this.getInflightFilePath());
   }
 
-  private async appendMessageUnsafe(message: SessionMessageV1): Promise<void> {
+  private async appendMessageUnsafe(message: SessionRecordV1): Promise<void> {
     await fs.appendFile(
       this.getMessagesFilePath(),
       JSON.stringify(message) + "\n",
@@ -379,6 +432,44 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     );
   }
 
+  private async rewriteMessagesUnsafe(messages: SessionRecordV1[]): Promise<void> {
+    const file = this.getMessagesFilePath();
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    const payload =
+      messages.length > 0
+        ? messages.map((message) => JSON.stringify(message)).join("\n") + "\n"
+        : "";
+    await fs.writeFile(temp, payload, "utf8");
+    await fs.move(temp, file, { overwrite: true });
+  }
+
+  private async upsert_action_record_unsafe(
+    message: SessionActionRecordV1,
+  ): Promise<void> {
+    const file = this.getMessagesFilePath();
+    const raw = await fs.readFile(file, "utf8").catch(() => "");
+    const messages: SessionRecordV1[] = [];
+    let replaced = false;
+
+    for (const line of raw.split("\n").filter(Boolean)) {
+      try {
+        const current = this.normalizePersistedMessage(JSON.parse(line));
+        if (!current) continue;
+        if (is_session_action_record(current) && current.id === message.id) {
+          messages.push(message);
+          replaced = true;
+          continue;
+        }
+        messages.push(current);
+      } catch {
+        // 关键点（中文）：重写 action 时顺手跳过损坏行，避免坏 JSON 阻断状态更新。
+      }
+    }
+
+    if (!replaced) messages.push(message);
+    await this.rewriteMessagesUnsafe(messages);
+  }
+
   private async withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
     await this.ensureLayout();
     const lockPath = this.getLockFilePath();
@@ -438,44 +529,6 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     return system.filter((item) => item && typeof item === "object");
   }
 
-  private normalizeOperation(
-    operation: AgentSessionOperationRecord,
-  ): AgentSessionOperationRecord {
-    const operation_id = String(operation.operationId || "").trim() || generateId();
-    const name = String(operation.name || "").trim() || "operation";
-    const status = String(operation.status || "").trim();
-    const normalized_status: AgentSessionOperationRecord["status"] =
-      status === "started" ||
-      status === "progress" ||
-      status === "finished" ||
-      status === "skipped" ||
-      status === "failed"
-        ? status
-        : "progress";
-    return {
-      operationId: operation_id,
-      name,
-      status: normalized_status,
-      ...(typeof operation.turnId === "string" && operation.turnId.trim()
-        ? { turnId: operation.turnId.trim() }
-        : {}),
-      ...(typeof operation.label === "string" && operation.label.trim()
-        ? { label: operation.label.trim() }
-        : {}),
-      ...(typeof operation.reason === "string" && operation.reason.trim()
-        ? { reason: operation.reason.trim() }
-        : {}),
-      ...(typeof operation.progress === "number" && Number.isFinite(operation.progress)
-        ? { progress: Math.max(0, Math.min(1, operation.progress)) }
-        : {}),
-      ...(operation.result !== undefined ? { result: operation.result } : {}),
-      ...(typeof operation.error === "string" && operation.error.trim()
-        ? { error: operation.error.trim() }
-        : {}),
-      ...(operation.visible === false ? { visible: false } : {}),
-    };
-  }
-
   async compact(input: SessionHistoryCompactInput): Promise<{
     compacted: boolean;
     reason?: string;
@@ -485,7 +538,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         rootPath: this.rootPath,
         sessionId: this.sessionId,
         withWriteLock: (fn) => this.withWriteLock(fn),
-        loadAll: () => this.list(),
+        loadAll: () => this.list_records(),
         createSummaryMessage: ({ text, archiveId, sourceRange }) => ({
           id: `a:${this.sessionId}:${generateId()}`,
           role: "assistant",
@@ -512,20 +565,24 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         maxInputTokensApprox: input.maxInputTokensApprox,
         archiveOnCompact: input.archiveOnCompact,
         compactRatio: input.compactRatio,
-        ...(input.onOperation ? { onOperation: input.onOperation } : {}),
+        ...(input.onAction ? { onAction: input.onAction } : {}),
       },
     );
   }
 
-  async append(message: SessionMessageV1): Promise<void> {
+  async write_record(message: SessionRecordV1): Promise<void> {
     await this.withWriteLock(async () => {
       const normalized = this.normalizePersistedMessage(message);
       if (!normalized) return;
+      if (is_session_action_record(normalized)) {
+        await this.upsert_action_record_unsafe(normalized);
+        return;
+      }
 
       // 关键点（中文）：若上一次 assistant 在运行中中断，新的 user 到来前先把残留快照收口到正式历史，
-      // 避免 `list()` 时旧 inflight 跑到新 user 后面，打乱时序。
-      if (normalized.role === "user") {
-        const current_inflight = await this.readInflightUnsafe();
+      // 避免 `list_records()` 时旧 inflight 跑到新 user 后面，打乱时序。
+      if (is_session_message_record(normalized) && normalized.role === "user") {
+        const current_inflight = await this.read_inflight_unsafe();
         if (current_inflight) {
           await this.appendMessageUnsafe(current_inflight);
           await this.removeInflightUnsafe();
@@ -543,11 +600,11 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
    * - 一次锁、一次 IO，适合 fork 等需要拷贝整段历史的场景。
    * - 不处理 inflight，调用方需自行确保历史已经收口。
    */
-  async appendMany(messages: SessionMessageV1[]): Promise<void> {
+  async write_records(messages: SessionRecordV1[]): Promise<void> {
     if (!Array.isArray(messages) || messages.length === 0) return;
     const normalized_list = messages
       .map((message) => this.normalizePersistedMessage(message))
-      .filter((message): message is SessionMessageV1 => message !== null);
+      .filter((message): message is SessionRecordV1 => message !== null);
     if (normalized_list.length === 0) return;
 
     const payload = normalized_list
@@ -558,20 +615,20 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     });
   }
 
-  async readInflight(): Promise<SessionMessageV1 | null> {
+  async read_inflight(): Promise<SessionRecordV1 | null> {
     await this.ensureLayout();
-    return this.readInflightUnsafe();
+    return this.read_inflight_unsafe();
   }
 
-  async writeInflight(message: SessionMessageV1): Promise<void> {
+  async write_inflight(message: SessionRecordV1): Promise<void> {
     await this.withWriteLock(async () => {
-      await this.writeInflightUnsafe(message);
+      await this.write_inflight_unsafe(message);
     });
   }
 
-  async finalizeInflight(message?: SessionMessageV1 | null): Promise<void> {
+  async finalize_inflight(message?: SessionRecordV1 | null): Promise<void> {
     await this.withWriteLock(async () => {
-      const current_inflight = await this.readInflightUnsafe();
+      const current_inflight = await this.read_inflight_unsafe();
       const normalized_message = this.normalizePersistedMessage(message);
       const final_message =
         current_inflight && normalized_message
@@ -586,12 +643,12 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     });
   }
 
-  async list(): Promise<SessionMessageV1[]> {
+  async list_records(): Promise<SessionRecordV1[]> {
     await this.ensureLayout();
     const file = this.getMessagesFilePath();
     const raw = await fs.readFile(file, "utf8");
     const lines = raw.split("\n").filter(Boolean);
-    const out: SessionMessageV1[] = [];
+    const out: SessionRecordV1[] = [];
     for (const line of lines) {
       try {
         const obj = this.normalizePersistedMessage(JSON.parse(line));
@@ -601,22 +658,22 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         // ignore invalid lines
       }
     }
-    const current_inflight = await this.readInflightUnsafe();
+    const current_inflight = await this.read_inflight_unsafe();
     if (current_inflight) {
       out.push(current_inflight);
     }
     return out;
   }
 
-  async slice(start: number, end: number): Promise<SessionMessageV1[]> {
-    const msgs = await this.list();
+  async slice_records(start: number, end: number): Promise<SessionRecordV1[]> {
+    const msgs = await this.list_records();
     const startIndex = Math.max(0, Math.floor(start));
     const endIndex = Math.max(startIndex, Math.floor(end));
     return msgs.slice(startIndex, endIndex);
   }
 
-  async size(): Promise<number> {
-    const msgs = await this.list();
+  async record_count(): Promise<number> {
+    const msgs = await this.list_records();
     return msgs.length;
   }
 
@@ -633,7 +690,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     metadata: Omit<SessionMetadataV1, "v" | "ts"> &
       Partial<Pick<SessionMetadataV1, "ts">>;
     id?: string;
-  }): SessionMessageV1 {
+  }): SessionRecordV1 {
     const { ts, ...metadata } = input.metadata;
     const md: SessionMetadataV1 = {
       v: 1,
@@ -658,7 +715,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     id?: string;
     kind?: "normal" | "summary";
     source?: "egress" | "compact";
-  }): SessionMessageV1 {
+  }): SessionRecordV1 {
     const { ts, ...metadata } = input.metadata;
     const md: SessionMetadataV1 = {
       v: 1,
@@ -676,29 +733,23 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     };
   }
 
-  operation(input: {
-    operation: AgentSessionOperationRecord;
-    metadata: Omit<SessionMetadataV1, "v" | "ts" | "kind" | "source" | "operation"> &
+  action(input: {
+    action: SessionActionRecordV1;
+    metadata: Pick<SessionMetadataV1, "sessionId"> &
       Partial<Pick<SessionMetadataV1, "ts">>;
     id?: string;
-  }): SessionMessageV1 {
-    const operation = this.normalizeOperation(input.operation);
-    const label = String(
-      operation.label || `${operation.name}: ${operation.status}`,
-    ).trim();
+  }): SessionActionRecordV1 {
     const { ts, ...metadata } = input.metadata;
+    const message = to_session_action_record(
+      input.id ? { ...input.action, id: input.id } : input.action,
+      metadata.sessionId || this.sessionId,
+    );
     return {
-      id: input.id || `op:${this.sessionId}:${operation.operationId}:${generateId()}`,
-      role: "operation",
+      ...message,
       metadata: {
-        v: 1,
-        ts: typeof ts === "number" ? ts : Date.now(),
-        ...metadata,
-        source: "operation",
-        kind: "operation",
-        operation,
+        ...message.metadata,
+        ts: typeof ts === "number" ? ts : message.metadata.ts,
       },
-      parts: [{ type: "text", text: label }],
     };
   }
 }

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

@@ -3,20 +3,34 @@
  *
  * 关键点（中文）
  * - plugin_call 是 agent 内置的最低层 plugin action 桥。
- * - schema 只描述模型需要提交的目标 plugin、action 与 JSON payload。
+ * - plugin_call.payload 是透传给具体 plugin action 的 JSON object。
+ * - 这里不用 Zod 表达 payload 的开放对象语义，避免 AI SDK zodSchema
+ *   转换后把 additionalProperties 收窄为 false。
  */
 
+import { jsonSchema } from "ai";
 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 image_create."),
-  payload: z
-    .object({})
-    .passthrough()
-    .optional()
-    .default({})
-    .describe("JSON payload passed to the plugin action."),
+export const plugin_call_input_schema = jsonSchema({
+  type: "object",
+  required: ["plugin", "action"],
+  additionalProperties: false,
+  properties: {
+    plugin: {
+      type: "string",
+      description: "Registered plugin name to call, for example image.",
+    },
+    action: {
+      type: "string",
+      description: "Plugin action name to execute, for example image_create.",
+    },
+    payload: {
+      type: "object",
+      additionalProperties: true,
+      default: {},
+      description: "JSON payload passed to the plugin action.",
+    },
+  },
 });
 
 export const plugin_read_input_schema = z.object({