@downcity/agent 1.1.238 → 1.1.259

package/bin/session/{recorder/SessionRecorder.js → SessionMessages.js}

@@ -1,22 +1,32 @@
 /**
- * SessionRecorder：Session Message 的唯一持久化与发布入口。
+ * SessionMessages：Session Message 的唯一领域入口。
  *
  * 完整 Message 与 Assistant 草稿先持久化，成功后再发布实时 Mutation。
+ * 同一 Assistant Message 的流式、审批与关闭操作共享一条写队列，保证 revision
+ * 从最新快照严格递增。
  */
-import { generateId } from "../../utils/Id.js";
+import { generateId } from "../utils/Id.js";
+import { SessionAssistantMessageWriter } from "../session/messages/SessionAssistantMessageWriter.js";
+import { to_session_json_value } from "../session/messages/SessionJsonValue.js";
+import { is_session_action_record } from "../executor/types/SessionRecords.js";
+import { from_ui_assistant_parts, from_ui_user_parts, to_executor_ui_message, } from "../session/messages/SessionMessageCodec.js";
+import { hydrateUserPromptFileParts } from "../executor/messages/SessionAttachmentMapper.js";
+export { SessionAssistantMessageWriter } from "../session/messages/SessionAssistantMessageWriter.js";
 /** 唯一 Session Message 写入服务。 */
-export class SessionRecorder {
+export class SessionMessages {
     session_id;
     store;
     publish;
     messages_by_id = new Map();
+    /** 按 Assistant Message 隔离的完整写事务链。 */
+    assistant_write_chains = new Map();
     initialized = false;
     constructor(options) {
         this.session_id = String(options.session_id || "").trim();
         this.store = options.store;
         this.publish = options.publish;
         if (!this.session_id)
-            throw new Error("SessionRecorder requires session_id");
+            throw new Error("SessionMessages requires session_id");
     }
     /** 恢复已有 Message，并收口进程中断遗留的运行状态。 */
     async initialize() {
@@ -101,6 +111,140 @@ export class SessionRecorder {
         await writer.complete();
         return this.get_message(writer.message_id);
     }
+    /** 把内部 Executor Record 收口为 canonical Session Message。 */
+    async append_record(record) {
+        if (is_session_action_record(record)) {
+            const action = record;
+            const existing = this.get_message(action.id);
+            if (existing?.type === "action") {
+                if (action.state !== "running") {
+                    await this.update_action_message(action.id, action.state, {
+                        title: action.title,
+                        description: action.description,
+                    });
+                }
+                return;
+            }
+            const writer = await this.open_action_message({
+                message_id: action.id,
+                turn_id: action.metadata.turnId,
+                action_type: String(action.id || "").split(":")[0] || "action",
+                title: action.title,
+                description: action.description,
+            });
+            if (action.state === "completed")
+                await writer.complete();
+            if (action.state === "failed") {
+                await writer.fail(action.description || action.title);
+            }
+            return;
+        }
+        const turn_id = String(record.metadata?.turnId || `external:${this.session_id}:${generateId()}`);
+        if (record.role === "user") {
+            await this.append_user_message({
+                turn_id,
+                input_type: record.metadata?.extra?.inputType === "steer" ? "steer" : "prompt",
+                parts: from_ui_user_parts(record.parts),
+            });
+            return;
+        }
+        await this.append_completed_assistant_message({
+            turn_id,
+            parts: from_ui_assistant_parts(record.parts),
+            visibility: record.metadata?.extra?.visibility === "internal"
+                ? "internal"
+                : "visible",
+            kind: record.metadata?.kind === "summary" ? "summary" : "normal",
+        });
+    }
+    /** 把公开 Session API 的 User 输入转换为 canonical Message 并持久化。 */
+    async append_external_user_message(input) {
+        const parts = input.message && "role" in input.message
+            ? from_ui_user_parts(input.message.parts)
+            : [{
+                    part_id: `external-user-text:${Date.now()}`,
+                    type: "text",
+                    text: String(input.text || "").trim(),
+                    state: "done",
+                }];
+        if (parts.length === 0)
+            return false;
+        await this.append_user_message({
+            turn_id: `external:${this.session_id}:${Date.now()}`,
+            input_type: "prompt",
+            parts,
+        });
+        return true;
+    }
+    /** 把公开 Session API 的 Assistant 输入转换为 canonical Message 并持久化。 */
+    async append_external_assistant_message(input) {
+        const parts = input.message && "role" in input.message
+            ? from_ui_assistant_parts(input.message.parts)
+            : [{
+                    part_id: `external-assistant-text:${Date.now()}`,
+                    sequence: 1,
+                    type: "text",
+                    text: String(input.fallback_text || "").trim(),
+                    state: "done",
+                }];
+        if (parts.length === 0)
+            return false;
+        await this.append_completed_assistant_message({ parts });
+        return true;
+    }
+    /** 把 Session prompt 转换为 canonical User Message 并持久化。 */
+    async append_prompt_message(input) {
+        const query = input.prompt.query;
+        const ui_parts = typeof query === "string"
+            ? [{ type: "text", text: query.trim() }]
+            : await hydrateUserPromptFileParts(Array.isArray(query) ? query : [], input.project_root);
+        const canonical = await this.append_user_message({
+            turn_id: input.turn_id,
+            input_type: input.input_type,
+            parts: normalize_session_user_parts(ui_parts),
+        });
+        return to_executor_ui_message(canonical);
+    }
+    /** 持久化 Executor 在本轮延迟产生的 User Message。 */
+    async append_deferred_user_messages(deferred_messages) {
+        const messages = Array.isArray(deferred_messages)
+            ? deferred_messages
+            : [];
+        for (const message of messages) {
+            await this.append_user_message({
+                turn_id: String(message.metadata?.turnId ||
+                    `deferred:${this.session_id}:${Date.now()}`),
+                input_type: "steer",
+                parts: from_ui_user_parts(message.parts),
+            });
+        }
+        return messages.length;
+    }
+    /** 按稳定 Action ID 创建或更新 canonical Action Message。 */
+    async persist_action_record(event) {
+        const existing = this.get_message(event.id);
+        if (!existing) {
+            const writer = await this.open_action_message({
+                message_id: event.id,
+                turn_id: event.metadata.turnId,
+                action_type: infer_action_type(event.id),
+                title: event.title,
+                description: event.description,
+            });
+            if (event.state === "completed")
+                await writer.complete();
+            if (event.state === "failed") {
+                await writer.fail(event.description || event.title);
+            }
+            return;
+        }
+        if (existing.type === "action" && event.state !== "running") {
+            await this.update_action_message(event.id, event.state, {
+                title: event.title,
+                description: event.description,
+            });
+        }
+    }
     /** 创建 running Action Message。 */
     async open_action_message(input) {
         const message = (await this.create_message((sequence, created_at) => ({
@@ -258,6 +402,12 @@ export class SessionRecorder {
     async append_assistant_delta(message_id, part_id, type, delta) {
         if (!delta)
             return;
+        await this.enqueue_assistant_write(message_id, async () => {
+            await this.append_assistant_delta_serialized(message_id, part_id, type, delta);
+        });
+    }
+    /** 在 Assistant 写队列内追加文本 delta。 */
+    async append_assistant_delta_serialized(message_id, part_id, type, delta) {
         const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
         require_streaming_assistant(current);
         const part = current.parts.find((item) => item.part_id === part_id);
@@ -291,6 +441,12 @@ export class SessionRecorder {
     }
     /** @internal 写入 Assistant 完整 part。 */
     async update_assistant_part(message_id, part) {
+        await this.enqueue_assistant_write(message_id, async () => {
+            await this.update_assistant_part_serialized(message_id, part);
+        });
+    }
+    /** 在 Assistant 写队列内提交完整 Part 快照。 */
+    async update_assistant_part_serialized(message_id, part) {
         const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
         require_streaming_assistant(current);
         const existing = current.parts.find((item) => item.part_id === part.part_id);
@@ -323,6 +479,12 @@ export class SessionRecorder {
     }
     /** @internal 收口 Assistant Message。 */
     async complete_assistant_message(message_id, status) {
+        await this.enqueue_assistant_write(message_id, async () => {
+            await this.complete_assistant_message_serialized(message_id, status);
+        });
+    }
+    /** 在 Assistant 写队列内关闭草稿并写入 Active。 */
+    async complete_assistant_message_serialized(message_id, status) {
         const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
         require_streaming_assistant(current);
         const created_at = Date.now();
@@ -338,30 +500,8 @@ export class SessionRecorder {
         await this.store.finalize_assistant_message(message);
         this.accept_message(message);
     }
-    /** @internal 将 Shell Runtime 审批请求更新到当前 Tool Part。 */
-    async require_tool_approval(input) {
-        const tool = this.find_streaming_tool(input.tool_call_id);
-        await this.update_assistant_part(tool.message_id, {
-            ...tool.part,
-            state: "approval-required",
-            approval_id: input.approval_id,
-        });
-    }
-    /** @internal 将审批结果更新到当前 Tool Part。 */
-    async resolve_tool_approval(input) {
-        const tool = this.find_streaming_tool(input.tool_call_id);
-        if (tool.part.approval_id && tool.part.approval_id !== input.approval_id) {
-            throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
-        }
-        await this.update_assistant_part(tool.message_id, {
-            ...tool.part,
-            state: input.decision === "approved" ? "running" : "failed",
-            ...(input.decision === "approved"
-                ? {}
-                : { error: input.decision === "expired" ? "Approval expired" : "Approval denied" }),
-        });
-    }
     async create_message(factory, draft = false) {
+        await this.ensure_initialized();
         if (draft) {
             const message = await this.store.create_assistant_message((state) => {
                 const candidate = factory(state.message_sequence, Date.now());
@@ -377,6 +517,7 @@ export class SessionRecorder {
         this.accept_message(message);
         return message;
     }
+    /** 读取当前流式 Assistant 中的指定 Tool Part。 */
     find_streaming_tool(tool_call_id) {
         for (const message of this.messages_by_id.values()) {
             if (message.type !== "assistant" || message.status !== "streaming")
@@ -385,6 +526,74 @@ export class SessionRecorder {
             if (part)
                 return { message_id: message.message_id, part };
         }
+        return undefined;
+    }
+    /** 把完整审批请求写入对应的流式 Tool Part。 */
+    async request_tool_approval(approval) {
+        const { message_id } = this.require_streaming_tool(approval.tool_call_id);
+        await this.enqueue_assistant_write(message_id, async () => {
+            const tool = this.require_streaming_tool(approval.tool_call_id);
+            if (tool.message_id !== message_id) {
+                throw new Error(`Tool Assistant Message changed: ${approval.tool_call_id}`);
+            }
+            if (tool.part.state !== "ready") {
+                throw new Error(`Tool approval requires ready input: ${approval.tool_call_id} (${tool.part.state})`);
+            }
+            await this.update_assistant_part_serialized(message_id, {
+                ...tool.part,
+                state: "approval-required",
+                approval,
+            });
+        });
+    }
+    /** 在 Tool 恢复执行前提交审批决定对应的 Part 状态。 */
+    async resolve_tool_approval(input) {
+        const { message_id } = this.require_streaming_tool(input.tool_call_id);
+        await this.enqueue_assistant_write(message_id, async () => {
+            const tool = this.require_streaming_tool(input.tool_call_id);
+            if (tool.message_id !== message_id) {
+                throw new Error(`Tool Assistant Message changed: ${input.tool_call_id}`);
+            }
+            if (tool.part.approval?.approval_id !== input.approval_id) {
+                throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
+            }
+            await this.update_assistant_part_serialized(message_id, {
+                ...tool.part,
+                state: input.decision === "approved" ? "running" : "failed",
+                ...(input.decision === "approved"
+                    ? {}
+                    : {
+                        error: input.decision === "expired"
+                            ? "Approval expired"
+                            : "Approval denied",
+                    }),
+            });
+        });
+    }
+    /**
+     * 串行执行同一 Assistant Message 的完整写事务。
+     *
+     * 失败事务不会阻塞后续写入；链尾仅用于排序，真实错误仍返回给调用方。
+     */
+    async enqueue_assistant_write(message_id, operation) {
+        const previous = this.assistant_write_chains.get(message_id) || Promise.resolve();
+        const result = previous.then(operation, operation);
+        const chain = result.then(() => undefined, () => undefined);
+        this.assistant_write_chains.set(message_id, chain);
+        try {
+            return await result;
+        }
+        finally {
+            if (this.assistant_write_chains.get(message_id) === chain) {
+                this.assistant_write_chains.delete(message_id);
+            }
+        }
+    }
+    /** 查找当前流式 Assistant 中的 Tool Part，否则抛出明确错误。 */
+    require_streaming_tool(tool_call_id) {
+        const tool = this.find_streaming_tool(tool_call_id);
+        if (tool)
+            return tool;
         throw new Error(`Streaming Tool Part not found: ${tool_call_id}`);
     }
     build_message_mutation(message) {
@@ -413,265 +622,27 @@ export class SessionRecorder {
             await this.initialize();
     }
 }
-/** 单个 Assistant segment 的流式 writer。 */
-export class SessionAssistantMessageWriter {
-    message_id;
-    recorder;
-    pending_text_parts = new Map();
-    active_text_part_ids = new Map();
-    closed = false;
-    constructor(recorder, message_id) {
-        this.recorder = recorder;
-        this.message_id = message_id;
-    }
-    /** 应用一个原始 AI SDK UI chunk。 */
-    async apply_chunk(chunk) {
-        if (this.closed)
-            throw new Error("Assistant Message writer is closed");
-        const current = this.current_message();
-        switch (chunk.type) {
-            case "text-start":
-            case "reasoning-start": {
-                const type = chunk.type === "text-start" ? "text" : "reasoning";
-                const part_id = this.resolve_text_part_id(type, chunk.id);
-                if (!current.parts.some((part) => part.part_id === part_id)) {
-                    this.pending_text_parts.set(part_id, type);
-                }
-                return;
-            }
-            case "text-delta":
-            case "reasoning-delta": {
-                const type = chunk.type === "text-delta" ? "text" : "reasoning";
-                const part_id = this.resolve_text_part_id(type, chunk.id);
-                await this.ensure_text_part(part_id, type);
-                await this.recorder.append_assistant_delta(this.message_id, part_id, type, chunk.delta);
-                return;
-            }
-            case "text-end":
-            case "reasoning-end": {
-                const type = chunk.type === "text-end" ? "text" : "reasoning";
-                const source_part_id = this.source_text_part_id(type, chunk.id);
-                const part_id = this.active_text_part_ids.get(source_part_id);
-                if (!part_id)
-                    return;
-                const part = current.parts.find((item) => item.part_id === part_id);
-                if (part?.type === "text" || part?.type === "reasoning") {
-                    await this.upsert_part({ ...part, state: "done" });
-                }
-                else {
-                    this.pending_text_parts.delete(part_id);
-                }
-                this.active_text_part_ids.delete(source_part_id);
-                return;
-            }
-            case "tool-input-start":
-                await this.upsert_tool(chunk.toolCallId, {
-                    tool_name: chunk.toolName,
-                    state: "input-streaming",
-                    input_text: "",
-                });
-                return;
-            case "tool-input-delta": {
-                const tool = this.find_tool(chunk.toolCallId);
-                await this.upsert_tool(chunk.toolCallId, {
-                    tool_name: tool?.tool_name || "unknown",
-                    state: "input-streaming",
-                    input_text: `${tool?.input_text || ""}${chunk.inputTextDelta}`,
-                });
-                return;
-            }
-            case "tool-input-available":
-                await this.upsert_tool(chunk.toolCallId, {
-                    tool_name: chunk.toolName,
-                    state: "ready",
-                    input: to_json_value(chunk.input),
-                });
-                return;
-            case "tool-input-error":
-                await this.upsert_tool(chunk.toolCallId, {
-                    tool_name: chunk.toolName,
-                    state: "failed",
-                    input: to_json_value(chunk.input),
-                    error: chunk.errorText,
-                });
-                return;
-            case "tool-approval-request": {
-                const tool = this.find_tool(chunk.toolCallId);
-                await this.upsert_tool(chunk.toolCallId, {
-                    tool_name: tool?.tool_name || "unknown",
-                    state: "approval-required",
-                    approval_id: chunk.approvalId,
-                });
-                return;
-            }
-            case "tool-output-available": {
-                const tool = this.find_tool(chunk.toolCallId);
-                await this.upsert_tool(chunk.toolCallId, {
-                    tool_name: tool?.tool_name || "unknown",
-                    state: "completed",
-                    output: to_json_value(chunk.output),
-                });
-                return;
-            }
-            case "tool-output-error":
-            case "tool-output-denied": {
-                const tool = this.find_tool(chunk.toolCallId);
-                await this.upsert_tool(chunk.toolCallId, {
-                    tool_name: tool?.tool_name || "unknown",
-                    state: "failed",
-                    error: chunk.type === "tool-output-error"
-                        ? chunk.errorText
-                        : "Tool output denied",
-                });
-                return;
-            }
-            case "file":
-                await this.append_file_part({
-                    media_type: chunk.mediaType,
-                    url: chunk.url,
-                });
-                return;
-            default:
-                return;
-        }
-    }
-    /** 写入一个完整 Assistant part。 */
-    async upsert_part(part) {
-        await this.recorder.update_assistant_part(this.message_id, part);
-    }
-    /**
-     * 把最终结果中的文件补入当前 Assistant，并对流式已写入文件去重。
-     */
-    async append_file_part(input) {
-        const filename = String(input.filename || "").trim();
-        const current = this.current_message();
-        const existing = current.parts.find((part) => part.type === "file" &&
-            part.url === input.url &&
-            part.media_type === input.media_type);
-        if (existing?.type === "file") {
-            if (filename && String(existing.filename || "").trim() !== filename) {
-                await this.upsert_part({ ...existing, filename });
-            }
-            return;
-        }
-        await this.upsert_part({
-            part_id: `file:${generateId()}`,
-            sequence: this.next_part_sequence(),
-            type: "file",
-            media_type: input.media_type,
-            url: input.url,
-            ...(filename ? { filename } : {}),
-        });
-    }
-    /** 当前实现逐 chunk 等待落盘，因此 flush 在返回时天然完成。 */
-    async flush() { }
-    /** 正常完成当前 assistant segment。 */
-    async complete() {
-        await this.close("completed");
-    }
-    /** 停止当前 assistant segment，并保留已有 parts。 */
-    async stop() {
-        await this.close("stopped");
-    }
-    /** 以失败状态关闭当前 assistant segment。 */
-    async fail(_error) {
-        await this.close("failed");
-    }
-    current_message() {
-        const message = this.recorder.get_message(this.message_id);
-        if (!message || message.type !== "assistant") {
-            throw new Error(`Assistant Message not found: ${this.message_id}`);
-        }
-        return message;
-    }
-    find_tool(tool_call_id) {
-        return this.current_message().parts.find((part) => part.type === "tool" && part.tool_call_id === tool_call_id);
-    }
-    next_part_sequence() {
-        return this.current_message().parts.reduce((value, part) => Math.max(value, part.sequence + 1), 1);
-    }
-    /**
-     * 把 AI SDK 当前 stream 内的临时 chunk ID 映射为 Message 内唯一 Part ID。
-     *
-     * AI SDK 会在不同 `streamText()` 调用中重复使用 `txt-0`、`reasoning-0`
-     * 等 ID，因此这些 ID 只能用于关联当前尚未结束的文本片段。
-     */
-    resolve_text_part_id(type, chunk_id) {
-        const source_part_id = this.source_text_part_id(type, chunk_id);
-        const active_part_id = this.active_text_part_ids.get(source_part_id);
-        if (active_part_id)
-            return active_part_id;
-        const part_id = `${type}:${generateId()}`;
-        this.active_text_part_ids.set(source_part_id, part_id);
-        return part_id;
-    }
-    /** 构造当前流片段使用的临时关联键。 */
-    source_text_part_id(type, chunk_id) {
-        return `${type}:${chunk_id}`;
-    }
-    /** 在首个有效 Delta 到达时才固定文本 Part 的真实顺序。 */
-    async ensure_text_part(part_id, type) {
-        const existing = this.current_message().parts.find((part) => part.part_id === part_id);
-        if (existing) {
-            if (existing.type !== type) {
-                throw new Error(`Assistant Part type changed: ${part_id}`);
-            }
-            return;
-        }
-        const pending_type = this.pending_text_parts.get(part_id);
-        if (pending_type && pending_type !== type) {
-            throw new Error(`Assistant pending Part type changed: ${part_id}`);
-        }
-        await this.upsert_part({
-            part_id,
-            sequence: this.next_part_sequence(),
-            type,
-            text: "",
-            state: "streaming",
-        });
-        this.pending_text_parts.delete(part_id);
-    }
-    async upsert_tool(tool_call_id, changes) {
-        const current = this.find_tool(tool_call_id);
-        await this.upsert_part({
-            ...(current || {}),
-            part_id: `tool:${tool_call_id}`,
-            sequence: current?.sequence || this.next_part_sequence(),
-            type: "tool",
-            tool_call_id,
-            ...changes,
-        });
-    }
-    async close(status) {
-        if (this.closed)
-            return;
-        this.pending_text_parts.clear();
-        this.active_text_part_ids.clear();
-        await this.recorder.complete_assistant_message(this.message_id, status);
-        this.closed = true;
-    }
-}
 /** 单个 Action Message 的生命周期 writer。 */
 export class SessionActionMessageWriter {
     message_id;
-    recorder;
+    messages;
     closed = false;
-    constructor(recorder, message_id) {
-        this.recorder = recorder;
+    constructor(messages, message_id) {
+        this.messages = messages;
         this.message_id = message_id;
     }
     /** 把 Action 更新为 completed。 */
     async complete(input) {
         if (this.closed)
             return;
-        await this.recorder.update_action_message(this.message_id, "completed", input);
+        await this.messages.update_action_message(this.message_id, "completed", input);
         this.closed = true;
     }
     /** 把 Action 更新为 failed。 */
     async fail(error) {
         if (this.closed)
             return;
-        await this.recorder.update_action_message(this.message_id, "failed", {
+        await this.messages.update_action_message(this.message_id, "failed", {
             description: error instanceof Error ? error.message : String(error),
         });
         this.closed = true;
@@ -707,7 +678,7 @@ export function normalize_session_user_parts(parts) {
                     part_id: `user-data:${index + 1}`,
                     type: "data",
                     data_type: String(candidate.type),
-                    data: to_json_value(candidate.data),
+                    data: to_session_json_value(candidate.data),
                 }];
         }
         return [];
@@ -729,18 +700,6 @@ function require_streaming_assistant(message) {
     }
     return message;
 }
-function to_json_value(input) {
-    if (input === undefined || input === null)
-        return null;
-    if (typeof input === "string" || typeof input === "number" || typeof input === "boolean")
-        return input;
-    try {
-        return JSON.parse(JSON.stringify(input));
-    }
-    catch {
-        return String(input);
-    }
-}
 function resolve_import_id(map, source_id, prefix) {
     const existing = map.get(source_id);
     if (existing)
@@ -749,8 +708,12 @@ function resolve_import_id(map, source_id, prefix) {
     map.set(source_id, created);
     return created;
 }
+/** 从 Action Message ID 提取稳定业务类型。 */
+function infer_action_type(message_id) {
+    return String(message_id || "").split(":")[0] || "action";
+}
 /** 按真实 Message sequence 升序排序。 */
 function compare_message_sequence(left, right) {
     return left.sequence - right.sequence;
 }
-//# sourceMappingURL=SessionRecorder.js.map
+//# sourceMappingURL=SessionMessages.js.map