@downcity/agent 1.1.217 → 1.1.222

package/bin/session/recorder/SessionRecorder.d.ts

@@ -0,0 +1,177 @@
+/**
+ * SessionRecorder：Session Message 的唯一持久化与发布入口。
+ *
+ * Mutation 先写入单一 messages.jsonl，成功后更新内存 snapshot，最后发布同一个对象。
+ */
+import type { UIMessage, UIMessageChunk } from "ai";
+import { JsonlSessionMessageStore } from "../../session/recorder/JsonlSessionMessageStore.js";
+import type { JsonObject } from "../../types/common/Json.js";
+import type { ListSessionMessagesInput, SessionActionMessage, SessionAssistantMessage, SessionAssistantMessagePart, SessionErrorMessage, SessionMessage, SessionMessagePage, SessionUserMessage, SessionUserMessagePart } from "../../types/session/SessionMessage.js";
+import type { ListSessionMessageChangesInput, SessionMessageMutation, SessionMessageMutationPage, SessionMessageMutationSubscriber, SessionMessageMutationUnsubscribe } from "../../types/session/SessionMessageMutation.js";
+/** SessionRecorder 构造参数。 */
+export interface SessionRecorderOptions {
+    /** 当前 Session 标识。 */
+    session_id: string;
+    /** 单一 JSONL Mutation store。 */
+    store: JsonlSessionMessageStore;
+    /** Mutation 成功提交后的发布函数。 */
+    publish: (mutation: SessionMessageMutation) => void;
+}
+/** User Message 创建参数。 */
+export interface AppendSessionUserMessageInput {
+    /** 当前输入所属 turn。 */
+    turn_id: string;
+    /** 普通 prompt 或 steering 输入。 */
+    input_type: "prompt" | "steer";
+    /** User 结构化 parts。 */
+    parts: SessionUserMessagePart[];
+    /** 可选指定 Message ID，通常由 Recorder 生成。 */
+    message_id?: string;
+    /** 默认展示范围。 */
+    visibility?: "visible" | "internal";
+}
+/** Assistant Message 创建参数。 */
+export interface OpenSessionAssistantMessageInput {
+    /** 当前 assistant 所属 turn。 */
+    turn_id: string;
+    /** 当前 assistant 在 turn 内的 segment 序号。 */
+    segment_index: number;
+    /** 普通 assistant 或 compact summary。 */
+    kind?: "normal" | "summary";
+    /** 默认展示范围。 */
+    visibility?: "visible" | "internal";
+    /** 可选指定 Message ID。 */
+    message_id?: string;
+    /** Summary 已覆盖到的来源 Message。 */
+    summary_through_message_id?: string;
+}
+/** 已完成 Assistant Message 直接写入参数。 */
+export interface AppendCompletedAssistantMessageInput {
+    /** Assistant 所属 turn。 */
+    turn_id?: string;
+    /** Assistant 完整 parts。 */
+    parts: SessionAssistantMessagePart[];
+    /** 普通 assistant 或 compact summary。 */
+    kind?: "normal" | "summary";
+    /** 默认展示范围。 */
+    visibility?: "visible" | "internal";
+    /** Summary 已覆盖到的来源 Message。 */
+    summary_through_message_id?: string;
+}
+/** Action Message 创建参数。 */
+export interface OpenSessionActionMessageInput {
+    /** 可选稳定 Message ID；业务 action 生命周期使用该值定位。 */
+    message_id?: string;
+    /** Action 所属 turn。 */
+    turn_id?: string;
+    /** Action 业务类型。 */
+    action_type: string;
+    /** Action 标题。 */
+    title: string;
+    /** Action 描述。 */
+    description?: string;
+    /** Action 附加数据。 */
+    data?: JsonObject;
+}
+/** Error Message 创建参数。 */
+export interface AppendSessionErrorMessageInput {
+    /** 错误影响范围。 */
+    scope: "session" | "turn";
+    /** 错误所属 turn。 */
+    turn_id?: string;
+    /** 稳定错误码。 */
+    code: string;
+    /** 用户可见错误文本。 */
+    message: string;
+    /** 是否允许恢复。 */
+    recoverable: boolean;
+}
+/** 唯一 Session Message 写入服务。 */
+export declare class SessionRecorder {
+    readonly session_id: string;
+    private readonly store;
+    private readonly publish;
+    private readonly subscribers;
+    private readonly messages_by_id;
+    private initialized;
+    constructor(options: SessionRecorderOptions);
+    /** 重放已有 Mutation，并收口进程中断遗留的运行状态。 */
+    initialize(): Promise<void>;
+    /** 同步读取当前内存 Message。 */
+    get_message(message_id: string): SessionMessage | undefined;
+    /** 追加普通 prompt 或 steering User Message。 */
+    append_user_message(input: AppendSessionUserMessageInput): Promise<SessionUserMessage>;
+    /** 创建可持续接收 chunk 的 Assistant segment。 */
+    open_assistant_message(input: OpenSessionAssistantMessageInput): Promise<SessionAssistantMessageWriter>;
+    /** 直接写入一条已完成 Assistant Message。 */
+    append_completed_assistant_message(input: AppendCompletedAssistantMessageInput): Promise<SessionAssistantMessage>;
+    /** 创建 running Action Message。 */
+    open_action_message(input: OpenSessionActionMessageInput): Promise<SessionActionMessageWriter>;
+    /** 更新 Action 状态，同时保持 message_id 与 sequence 不变。 */
+    update_action_message(message_id: string, status: "running" | "completed" | "failed", changes?: {
+        title?: string;
+        description?: string;
+        data?: JsonObject;
+    }): Promise<SessionActionMessage>;
+    /** 创建用户可见 Error Message。 */
+    append_error_message(input: AppendSessionErrorMessageInput): Promise<SessionErrorMessage>;
+    /** 读取折叠后的 Message snapshot。 */
+    list_messages(input?: ListSessionMessagesInput): Promise<SessionMessagePage>;
+    /** 从指定 commit_sequence 增量读取 Mutation。 */
+    list_message_changes(input: ListSessionMessageChangesInput): Promise<SessionMessageMutationPage>;
+    /** 订阅已成功持久化的未来 Mutation。 */
+    subscribe(subscriber: SessionMessageMutationSubscriber): SessionMessageMutationUnsubscribe;
+    /** 向当前 Session 导入 fork 来源 Message，并重新分配全部身份和顺序。 */
+    import_messages(messages: SessionMessage[]): Promise<void>;
+    /** @internal 写入 Assistant 原始文本 delta。 */
+    append_assistant_delta(message_id: string, part_id: string, type: "text" | "reasoning", delta: string): Promise<void>;
+    /** @internal 写入 Assistant 完整 part。 */
+    update_assistant_part(message_id: string, part: SessionAssistantMessagePart): Promise<void>;
+    /** @internal 收口 Assistant Message。 */
+    complete_assistant_message(message_id: string, status: "completed" | "stopped" | "failed"): Promise<void>;
+    private create_message;
+    private build_message_mutation;
+    private accept_mutation;
+    private ensure_initialized;
+}
+/** 单个 Assistant segment 的流式 writer。 */
+export declare class SessionAssistantMessageWriter {
+    readonly message_id: string;
+    private readonly recorder;
+    private closed;
+    constructor(recorder: SessionRecorder, message_id: string);
+    /** 应用一个原始 AI SDK UI chunk。 */
+    apply_chunk(chunk: UIMessageChunk): Promise<void>;
+    /** 写入一个完整 Assistant part。 */
+    upsert_part(part: SessionAssistantMessagePart): Promise<void>;
+    /** 当前实现逐 chunk 等待落盘，因此 flush 在返回时天然完成。 */
+    flush(): Promise<void>;
+    /** 正常完成当前 assistant segment。 */
+    complete(): Promise<void>;
+    /** 停止当前 assistant segment，并保留已有 parts。 */
+    stop(): Promise<void>;
+    /** 以失败状态关闭当前 assistant segment。 */
+    fail(_error: unknown): Promise<void>;
+    private current_message;
+    private find_tool;
+    private upsert_tool;
+    private close;
+}
+/** 单个 Action Message 的生命周期 writer。 */
+export declare class SessionActionMessageWriter {
+    readonly message_id: string;
+    private readonly recorder;
+    private closed;
+    constructor(recorder: SessionRecorder, message_id: string);
+    /** 把 Action 更新为 completed。 */
+    complete(input?: {
+        title?: string;
+        description?: string;
+        data?: JsonObject;
+    }): Promise<void>;
+    /** 把 Action 更新为 failed。 */
+    fail(error: unknown): Promise<void>;
+}
+/** 把 AI SDK User parts 归一为 canonical User parts。 */
+export declare function normalize_session_user_parts(parts: UIMessage["parts"] | null | undefined): SessionUserMessagePart[];
+//# sourceMappingURL=SessionRecorder.d.ts.map

package/bin/session/recorder/SessionRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRecorder.d.ts","sourceRoot":"","sources":["../../../src/session/recorder/SessionRecorder.ts"],"names":[],"mappings":"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"}