@downcity/agent 1.1.217 → 1.1.224

package/bin/session/recorder/SessionRecorder.js

@@ -0,0 +1,655 @@
+/**
+ * SessionRecorder：Session Message 的唯一持久化与发布入口。
+ *
+ * 完整 Message 与 Assistant 草稿先持久化，成功后再发布实时 Mutation。
+ */
+import { generateId } from "../../utils/Id.js";
+/** 唯一 Session Message 写入服务。 */
+export class SessionRecorder {
+    session_id;
+    store;
+    publish;
+    messages_by_id = 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");
+    }
+    /** 恢复已有 Message，并收口进程中断遗留的运行状态。 */
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.store.initialize();
+        for (const message of await this.store.list_messages()) {
+            this.messages_by_id.set(message.message_id, message);
+        }
+        this.initialized = true;
+        const unfinished = [...this.messages_by_id.values()];
+        for (const message of unfinished) {
+            if (message.type === "assistant" && message.status === "streaming") {
+                await this.complete_assistant_message(message.message_id, "stopped");
+            }
+            if (message.type === "action" && message.status === "running") {
+                await this.update_action_message(message.message_id, "failed", {
+                    description: message.description || "Action interrupted before completion.",
+                });
+            }
+        }
+    }
+    /** 同步读取当前内存 Message。 */
+    get_message(message_id) {
+        return this.messages_by_id.get(message_id);
+    }
+    /** 追加普通 prompt 或 steering User Message。 */
+    async append_user_message(input) {
+        const message = await this.create_message((sequence, created_at) => ({
+            message_id: String(input.message_id || "").trim() ||
+                `user:${this.session_id}:${generateId()}`,
+            session_id: this.session_id,
+            turn_id: input.turn_id,
+            sequence,
+            revision: 1,
+            visibility: input.visibility || "visible",
+            created_at,
+            updated_at: created_at,
+            type: "user",
+            input_type: input.input_type,
+            parts: structuredClone(input.parts),
+        }));
+        return message;
+    }
+    /** 创建可持续接收 chunk 的 Assistant segment。 */
+    async open_assistant_message(input) {
+        const message = (await this.create_message((sequence, created_at) => ({
+            message_id: String(input.message_id || "").trim() ||
+                `assistant:${this.session_id}:${generateId()}`,
+            session_id: this.session_id,
+            turn_id: input.turn_id,
+            sequence,
+            revision: 1,
+            visibility: input.visibility || "visible",
+            created_at,
+            updated_at: created_at,
+            type: "assistant",
+            kind: input.kind || "normal",
+            segment_index: input.segment_index,
+            status: "streaming",
+            parts: [],
+            ...(input.summary_through_message_id
+                ? { summary_through_message_id: input.summary_through_message_id }
+                : {}),
+        }), true));
+        return new SessionAssistantMessageWriter(this, message.message_id);
+    }
+    /** 直接写入一条已完成 Assistant Message。 */
+    async append_completed_assistant_message(input) {
+        const turn_id = input.turn_id || `external:${this.session_id}:${generateId()}`;
+        const writer = await this.open_assistant_message({
+            turn_id,
+            segment_index: 1,
+            kind: input.kind || "normal",
+            visibility: input.visibility || "visible",
+            ...(input.summary_through_message_id
+                ? { summary_through_message_id: input.summary_through_message_id }
+                : {}),
+        });
+        for (const part of input.parts)
+            await writer.upsert_part(part);
+        await writer.complete();
+        return this.get_message(writer.message_id);
+    }
+    /** 创建 running Action Message。 */
+    async open_action_message(input) {
+        const message = (await this.create_message((sequence, created_at) => ({
+            message_id: String(input.message_id || "").trim() ||
+                `action:${this.session_id}:${generateId()}`,
+            session_id: this.session_id,
+            ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+            sequence,
+            revision: 1,
+            visibility: "visible",
+            created_at,
+            updated_at: created_at,
+            type: "action",
+            action_type: input.action_type,
+            status: "running",
+            title: input.title,
+            ...(input.description ? { description: input.description } : {}),
+            ...(input.data ? { data: structuredClone(input.data) } : {}),
+        })));
+        return new SessionActionMessageWriter(this, message.message_id);
+    }
+    /** 更新 Action 状态，同时保持 message_id 与 sequence 不变。 */
+    async update_action_message(message_id, status, changes) {
+        const message = await this.store.append_message((state) => {
+            const current = require_message(state.messages, message_id, "action");
+            const created_at = Date.now();
+            return {
+                ...current,
+                status,
+                ...(changes?.title ? { title: changes.title } : {}),
+                ...(changes?.description !== undefined
+                    ? { description: changes.description }
+                    : {}),
+                ...(changes?.data ? { data: structuredClone(changes.data) } : {}),
+                revision: current.revision + 1,
+                updated_at: created_at,
+            };
+        });
+        this.accept_message(message);
+        return message;
+    }
+    /** 创建用户可见 Error Message。 */
+    async append_error_message(input) {
+        return (await this.create_message((sequence, created_at) => ({
+            message_id: `error:${this.session_id}:${generateId()}`,
+            session_id: this.session_id,
+            ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+            sequence,
+            revision: 1,
+            visibility: "visible",
+            created_at,
+            updated_at: created_at,
+            type: "error",
+            scope: input.scope,
+            code: input.code,
+            message: input.message,
+            recoverable: input.recoverable,
+        })));
+    }
+    /** 读取折叠后的 Message snapshot。 */
+    async list_messages(input) {
+        await this.ensure_initialized();
+        const include_internal = input?.include_internal === true;
+        const through_sequence = Number.isFinite(input?.through_sequence)
+            ? Number(input?.through_sequence)
+            : Number.POSITIVE_INFINITY;
+        const before_sequence = Number.isFinite(input?.before_sequence)
+            ? Number(input?.before_sequence)
+            : Number.POSITIVE_INFINITY;
+        const all = [...this.messages_by_id.values()]
+            .filter((message) => (include_internal || message.visibility === "visible") &&
+            message.sequence <= through_sequence &&
+            message.sequence < before_sequence)
+            .sort((left, right) => left.sequence - right.sequence);
+        const offset = decode_cursor(input?.cursor);
+        const limit = normalize_limit(input?.limit, 100, 500);
+        const items = all.slice(offset, offset + limit).map((item) => structuredClone(item));
+        const next_offset = offset + items.length;
+        return {
+            items,
+            total: all.length,
+            ...(next_offset < all.length ? { next_cursor: encode_cursor(next_offset) } : {}),
+            has_more: next_offset < all.length,
+        };
+    }
+    /** 向当前 Session 导入 fork 来源 Message，并重新分配全部身份和顺序。 */
+    async import_messages(messages) {
+        const turn_ids = new Map();
+        const message_ids = new Map();
+        for (const source of [...messages].sort((a, b) => a.sequence - b.sequence)) {
+            const turn_id = source.turn_id
+                ? resolve_import_id(turn_ids, source.turn_id, "turn")
+                : undefined;
+            const message_id = resolve_import_id(message_ids, source.message_id, source.type);
+            await this.create_message((sequence, created_at) => ({
+                ...structuredClone(source),
+                message_id,
+                session_id: this.session_id,
+                ...(turn_id ? { turn_id } : {}),
+                sequence,
+                revision: 1,
+                created_at,
+                updated_at: created_at,
+                origin: {
+                    session_id: source.session_id,
+                    message_id: source.message_id,
+                    ...(source.turn_id ? { turn_id: source.turn_id } : {}),
+                },
+            }));
+        }
+    }
+    /** @internal 写入 Assistant 原始文本 delta。 */
+    async append_assistant_delta(message_id, part_id, type, delta) {
+        if (!delta)
+            return;
+        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);
+        if (!part || (part.type !== "text" && part.type !== "reasoning")) {
+            throw new Error(`Delta target Part does not exist: ${part_id}`);
+        }
+        if (part.type !== type)
+            throw new Error(`Delta type changed for Part: ${part_id}`);
+        const created_at = Date.now();
+        const message = {
+            ...current,
+            revision: current.revision + 1,
+            updated_at: created_at,
+            parts: current.parts.map((item) => item.part_id === part_id && (item.type === "text" || item.type === "reasoning")
+                ? { ...item, text: item.text + delta }
+                : item),
+        };
+        await this.store.write_assistant_message(message);
+        this.accept_mutation({
+            mutation_id: generateId(),
+            variant: "delta",
+            type,
+            message_id,
+            revision: message.revision,
+            session_id: this.session_id,
+            turn_id: message.turn_id,
+            created_at,
+            part_id,
+            delta,
+        }, message);
+    }
+    /** @internal 写入 Assistant 完整 part。 */
+    async update_assistant_part(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);
+        if (existing && existing.sequence !== part.sequence) {
+            throw new Error(`Assistant Part sequence changed: ${part.part_id}`);
+        }
+        const created_at = Date.now();
+        const next_part = structuredClone(part);
+        const message = {
+            ...current,
+            revision: current.revision + 1,
+            updated_at: created_at,
+            parts: (existing
+                ? current.parts.map((item) => item.part_id === part.part_id ? next_part : item)
+                : [...current.parts, next_part]).sort((left, right) => left.sequence - right.sequence),
+        };
+        await this.store.write_assistant_message(message);
+        this.accept_mutation({
+            mutation_id: generateId(),
+            variant: "part",
+            type: next_part.type,
+            message_id,
+            revision: message.revision,
+            session_id: this.session_id,
+            turn_id: message.turn_id,
+            created_at,
+            part_id: next_part.part_id,
+            part: next_part,
+        }, message);
+    }
+    /** @internal 收口 Assistant Message。 */
+    async complete_assistant_message(message_id, status) {
+        const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
+        require_streaming_assistant(current);
+        const created_at = Date.now();
+        const message = {
+            ...current,
+            revision: current.revision + 1,
+            status,
+            updated_at: created_at,
+            parts: current.parts.map((part) => part.type === "text" || part.type === "reasoning"
+                ? { ...part, state: "done" }
+                : part),
+        };
+        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) {
+        if (draft) {
+            const message = await this.store.create_assistant_message((state) => {
+                const candidate = factory(state.message_sequence, Date.now());
+                if (candidate.type !== "assistant" || candidate.status !== "streaming") {
+                    throw new Error("Draft Message must be a streaming Assistant");
+                }
+                return candidate;
+            });
+            this.accept_message(message);
+            return message;
+        }
+        const message = await this.store.append_message((state) => factory(state.message_sequence, Date.now()));
+        this.accept_message(message);
+        return message;
+    }
+    find_streaming_tool(tool_call_id) {
+        for (const message of this.messages_by_id.values()) {
+            if (message.type !== "assistant" || message.status !== "streaming")
+                continue;
+            const part = message.parts.find((item) => item.type === "tool" && item.tool_call_id === tool_call_id);
+            if (part)
+                return { message_id: message.message_id, part };
+        }
+        throw new Error(`Streaming Tool Part not found: ${tool_call_id}`);
+    }
+    build_message_mutation(message) {
+        return {
+            mutation_id: generateId(),
+            variant: "message",
+            type: message.type,
+            message_id: message.message_id,
+            sequence: message.sequence,
+            revision: message.revision,
+            session_id: this.session_id,
+            ...(message.turn_id ? { turn_id: message.turn_id } : {}),
+            created_at: message.updated_at,
+            message,
+        };
+    }
+    accept_message(message) {
+        this.accept_mutation(this.build_message_mutation(message), message);
+    }
+    accept_mutation(mutation, message) {
+        this.messages_by_id.set(message.message_id, structuredClone(message));
+        this.publish(mutation);
+    }
+    async ensure_initialized() {
+        if (!this.initialized)
+            await this.initialize();
+    }
+}
+/** 单个 Assistant segment 的流式 writer。 */
+export class SessionAssistantMessageWriter {
+    message_id;
+    recorder;
+    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":
+                await this.upsert_part({
+                    part_id: `${chunk.type === "text-start" ? "text" : "reasoning"}:${chunk.id}`,
+                    sequence: this.next_part_sequence(),
+                    type: chunk.type === "text-start" ? "text" : "reasoning",
+                    text: "",
+                    state: "streaming",
+                });
+                return;
+            case "text-delta":
+            case "reasoning-delta":
+                await this.recorder.append_assistant_delta(this.message_id, `${chunk.type === "text-delta" ? "text" : "reasoning"}:${chunk.id}`, chunk.type === "text-delta" ? "text" : "reasoning", chunk.delta);
+                return;
+            case "text-end":
+            case "reasoning-end": {
+                const part_id = `${chunk.type === "text-end" ? "text" : "reasoning"}:${chunk.id}`;
+                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" });
+                }
+                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.upsert_part({
+                    part_id: `file:${generateId()}`,
+                    sequence: this.next_part_sequence(),
+                    type: "file",
+                    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);
+    }
+    /** 当前实现逐 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);
+    }
+    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;
+        await this.recorder.complete_assistant_message(this.message_id, status);
+        this.closed = true;
+    }
+}
+/** 单个 Action Message 的生命周期 writer。 */
+export class SessionActionMessageWriter {
+    message_id;
+    recorder;
+    closed = false;
+    constructor(recorder, message_id) {
+        this.recorder = recorder;
+        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);
+        this.closed = true;
+    }
+    /** 把 Action 更新为 failed。 */
+    async fail(error) {
+        if (this.closed)
+            return;
+        await this.recorder.update_action_message(this.message_id, "failed", {
+            description: error instanceof Error ? error.message : String(error),
+        });
+        this.closed = true;
+    }
+}
+/** 把 AI SDK User parts 归一为 canonical User parts。 */
+export function normalize_session_user_parts(parts) {
+    if (!Array.isArray(parts))
+        return [];
+    return parts.flatMap((part, index) => {
+        if (!part || typeof part !== "object")
+            return [];
+        const candidate = part;
+        if (candidate.type === "text") {
+            return [{
+                    part_id: `user-text:${index + 1}`,
+                    type: "text",
+                    text: String(candidate.text || ""),
+                    state: "done",
+                }];
+        }
+        if (candidate.type === "file") {
+            return [{
+                    part_id: `user-file:${index + 1}`,
+                    type: "file",
+                    url: String(candidate.url || ""),
+                    media_type: String(candidate.mediaType || "application/octet-stream"),
+                    ...(candidate.filename ? { filename: String(candidate.filename) } : {}),
+                }];
+        }
+        if (String(candidate.type || "").startsWith("data-")) {
+            return [{
+                    part_id: `user-data:${index + 1}`,
+                    type: "data",
+                    data_type: String(candidate.type),
+                    data: to_json_value(candidate.data),
+                }];
+        }
+        return [];
+    });
+}
+function require_message(messages, message_id, type) {
+    const message = messages.find((item) => item.message_id === message_id);
+    if (!message || message.type !== type) {
+        throw new Error(`Session ${type} Message not found: ${message_id}`);
+    }
+    return message;
+}
+function require_streaming_assistant(message) {
+    if (message.type !== "assistant") {
+        throw new Error(`Session Message is not assistant: ${message.message_id}`);
+    }
+    if (message.status !== "streaming") {
+        throw new Error(`Assistant Message is already closed: ${message.message_id}`);
+    }
+    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 normalize_limit(value, fallback, maximum) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(maximum, Math.max(1, Math.floor(Number(value))));
+}
+function encode_cursor(offset) {
+    return Buffer.from(JSON.stringify({ offset }), "utf8").toString("base64url");
+}
+function decode_cursor(cursor) {
+    const value = String(cursor || "").trim();
+    if (!value)
+        return 0;
+    try {
+        const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+        return typeof parsed.offset === "number" && parsed.offset >= 0
+            ? Math.floor(parsed.offset)
+            : 0;
+    }
+    catch {
+        throw new Error("Invalid Session Message cursor");
+    }
+}
+function resolve_import_id(map, source_id, prefix) {
+    const existing = map.get(source_id);
+    if (existing)
+        return existing;
+    const created = `${prefix}:${generateId()}`;
+    map.set(source_id, created);
+    return created;
+}
+//# sourceMappingURL=SessionRecorder.js.map