@downcity/agent 1.1.217 → 1.1.224

package/bin/types/session/SessionMessage.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Session canonical 消息类型。
+ *
+ * Session 只维护一条由 sequence 排序的消息序列；assistant 的 text、reasoning、tool、file
+ * 均为内部 part，不提升为顶层消息。
+ */
+import type { JsonObject, JsonValue } from "../../types/common/Json.js";
+/** Message 默认展示范围。 */
+export type SessionMessageVisibility = "visible" | "internal";
+/** 从其他 Session 导入时保留的来源身份。 */
+export interface SessionMessageOrigin {
+    /** 来源 Session 标识。 */
+    session_id: string;
+    /** 来源 Message 标识。 */
+    message_id: string;
+    /** 来源 turn 标识。 */
+    turn_id?: string;
+}
+/** Session Message 公共字段。 */
+export interface SessionMessageBase {
+    /** 当前 Message 在 Session 内的稳定唯一标识。 */
+    message_id: string;
+    /** 当前 Message 所属 Session 标识。 */
+    session_id: string;
+    /** 当前 Message 所属 turn；独立 action 可以省略。 */
+    turn_id?: string;
+    /** Message 的线性位置；创建后永远不变。 */
+    sequence: number;
+    /** Message 版本号；每次对外发布的消息变化后递增。 */
+    revision: number;
+    /** 当前 Message 是否默认对用户可见。 */
+    visibility: SessionMessageVisibility;
+    /** Message 首次创建时间戳（ms）。 */
+    created_at: number;
+    /** Message 最近更新时间戳（ms）。 */
+    updated_at: number;
+    /** 从其他 Session 导入时的来源信息。 */
+    origin?: SessionMessageOrigin;
+}
+/** User 文本 part。 */
+export interface SessionUserTextPart {
+    /** User Message 内稳定的 part 标识。 */
+    part_id: string;
+    /** part 类型固定为 text。 */
+    type: "text";
+    /** 用户输入文本。 */
+    text: string;
+    /** User 文本已经完整，不参与流式更新。 */
+    state: "done";
+}
+/** User 文件 part。 */
+export interface SessionUserFilePart {
+    /** User Message 内稳定的 part 标识。 */
+    part_id: string;
+    /** part 类型固定为 file。 */
+    type: "file";
+    /** 文件可读取地址或 data URL。 */
+    url: string;
+    /** 文件 MIME 类型。 */
+    media_type: string;
+    /** 可选原始文件名。 */
+    filename?: string;
+}
+/** User 结构化数据 part。 */
+export interface SessionUserDataPart {
+    /** User Message 内稳定的 part 标识。 */
+    part_id: string;
+    /** part 类型固定为 data。 */
+    type: "data";
+    /** 对应 AI SDK 的 data-* 类型名称。 */
+    data_type: `data-${string}` | string;
+    /** 可 JSON 序列化的数据。 */
+    data: JsonValue;
+}
+/** User Message part。 */
+export type SessionUserMessagePart = SessionUserTextPart | SessionUserFilePart | SessionUserDataPart;
+/** User 顶层 Message。 */
+export interface SessionUserMessage extends SessionMessageBase {
+    /** Message 类型固定为 user。 */
+    type: "user";
+    /** 普通 prompt 或当前 turn 中的 steering 输入。 */
+    input_type: "prompt" | "steer";
+    /** 用户消息的结构化 parts。 */
+    parts: SessionUserMessagePart[];
+}
+/** Assistant 文本或推理 part。 */
+export interface SessionAssistantTextPart {
+    /** Assistant Message 内稳定的 part 标识。 */
+    part_id: string;
+    /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+    sequence: number;
+    /** part 是可见文本或推理文本。 */
+    type: "text" | "reasoning";
+    /** 当前已经累计的完整文本。 */
+    text: string;
+    /** 文本 part 是否已经结束。 */
+    state: "streaming" | "done";
+}
+/** Assistant 工具 part。 */
+export interface SessionAssistantToolPart {
+    /** Assistant Message 内稳定的 part 标识。 */
+    part_id: string;
+    /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+    sequence: number;
+    /** part 类型固定为 tool。 */
+    type: "tool";
+    /** 模型工具调用稳定标识。 */
+    tool_call_id: string;
+    /** 工具注册名称。 */
+    tool_name: string;
+    /** 工具当前生命周期状态。 */
+    state: "input-streaming" | "ready" | "approval-required" | "running" | "completed" | "failed";
+    /** 流式接收中的参数原文。 */
+    input_text?: string;
+    /** 收敛后的结构化输入。 */
+    input?: JsonValue;
+    /** 工具成功输出。 */
+    output?: JsonValue;
+    /** 工具失败信息。 */
+    error?: string;
+    /** 工具审批请求标识。 */
+    approval_id?: string;
+}
+/** Assistant 文件 part。 */
+export interface SessionAssistantFilePart {
+    /** Assistant Message 内稳定的 part 标识。 */
+    part_id: string;
+    /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+    sequence: number;
+    /** part 类型固定为 file。 */
+    type: "file";
+    /** 文件 MIME 类型。 */
+    media_type: string;
+    /** 文件可读取地址或 data URL。 */
+    url: string;
+    /** 可选原始文件名。 */
+    filename?: string;
+}
+/** Assistant 结构化数据 part。 */
+export interface SessionAssistantDataPart {
+    /** Assistant Message 内稳定的 part 标识。 */
+    part_id: string;
+    /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+    sequence: number;
+    /** part 类型固定为 data。 */
+    type: "data";
+    /** 对应 AI SDK 的 data-* 类型名称。 */
+    data_type: `data-${string}` | string;
+    /** 可 JSON 序列化的数据。 */
+    data: JsonValue;
+}
+/** Assistant Message part。 */
+export type SessionAssistantMessagePart = SessionAssistantTextPart | SessionAssistantToolPart | SessionAssistantFilePart | SessionAssistantDataPart;
+/** Assistant 顶层 Message。 */
+export interface SessionAssistantMessage extends SessionMessageBase {
+    /** Message 类型固定为 assistant。 */
+    type: "assistant";
+    /** 普通 assistant segment 或内部 compact summary。 */
+    kind: "normal" | "summary";
+    /** Assistant 在所属 turn 内的 segment 序号，从一开始。 */
+    segment_index: number;
+    /** Assistant 当前执行状态。 */
+    status: "streaming" | "completed" | "stopped" | "failed";
+    /** Assistant 内按真实生成顺序保存的 parts。 */
+    parts: SessionAssistantMessagePart[];
+    /** Summary 已覆盖到的来源 Message 标识。 */
+    summary_through_message_id?: string;
+}
+/** Action 顶层 Message。 */
+export interface SessionActionMessage extends SessionMessageBase {
+    /** Message 类型固定为 action。 */
+    type: "action";
+    /** Action 业务类型。 */
+    action_type: string;
+    /** Action 当前状态。 */
+    status: "running" | "completed" | "failed";
+    /** Action 展示标题。 */
+    title: string;
+    /** Action 展示描述。 */
+    description?: string;
+    /** Action 附加结构化信息。 */
+    data?: JsonObject;
+}
+/** Error 顶层 Message。 */
+export interface SessionErrorMessage extends SessionMessageBase {
+    /** Message 类型固定为 error。 */
+    type: "error";
+    /** 错误影响范围。 */
+    scope: "session" | "turn";
+    /** 稳定错误码。 */
+    code: string;
+    /** 用户可见错误信息。 */
+    message: string;
+    /** 当前错误是否允许重试恢复。 */
+    recoverable: boolean;
+}
+/** Session 唯一顶层 Message 联合类型。 */
+export type SessionMessage = SessionUserMessage | SessionAssistantMessage | SessionActionMessage | SessionErrorMessage;
+/** 读取 Session Message snapshot 的分页输入。 */
+export interface ListSessionMessagesInput {
+    /** 单页数量上限。 */
+    limit?: number;
+    /** 上一页返回的透明游标。 */
+    cursor?: string;
+    /** 只返回 sequence 严格小于该值的 Message，供向前翻页。 */
+    before_sequence?: number;
+    /** 是否包含 internal Message。 */
+    include_internal?: boolean;
+    /** 只返回不大于该 sequence 的 Message。 */
+    through_sequence?: number;
+}
+/** Session Message snapshot 分页结果。 */
+export interface SessionMessagePage {
+    /** 当前页按 sequence 升序排列的 Message。 */
+    items: SessionMessage[];
+    /** 当前过滤条件下的 Message 总数。 */
+    total: number;
+    /** 下一页透明游标。 */
+    next_cursor?: string;
+    /** 是否仍有更多 Message。 */
+    has_more: boolean;
+}
+//# sourceMappingURL=SessionMessage.d.ts.map

package/bin/types/session/SessionMessage.d.ts.map

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

package/bin/types/session/SessionMessage.js

@@ -0,0 +1,8 @@
+/**
+ * Session canonical 消息类型。
+ *
+ * Session 只维护一条由 sequence 排序的消息序列；assistant 的 text、reasoning、tool、file
+ * 均为内部 part，不提升为顶层消息。
+ */
+export {};
+//# sourceMappingURL=SessionMessage.js.map

package/bin/types/session/SessionMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionMessage.js","sourceRoot":"","sources":["../../../src/types/session/SessionMessage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/bin/types/session/SessionMutation.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Session 的统一实时 Mutation 协议。
+ *
+ * Mutation 描述订阅之后发生的状态变化，不等同于 messages.jsonl 持久化格式。
+ */
+import type { SessionAssistantMessagePart, SessionMessage } from "../../types/session/SessionMessage.js";
+import type { ResolveSessionApprovalInput, SessionApprovalResult } from "../../types/session/SessionApproval.js";
+/** 所有 Session Mutation 的公共字段。 */
+export interface SessionMutationBase {
+    /** 当前 Mutation 的稳定唯一标识。 */
+    mutation_id: string;
+    /** 当前 Mutation 所属 Session 标识。 */
+    session_id: string;
+    /** 当前 Mutation 创建时间戳（ms）。 */
+    created_at: number;
+}
+/** Message 创建或完整快照更新 Mutation。 */
+export type SessionMessageMutation = {
+    [TType in SessionMessage["type"]]: SessionMutationBase & {
+        /** Mutation 层级固定为 message。 */
+        variant: "message";
+        /** 当前完整 Message 类型。 */
+        type: TType;
+        /** 当前 Mutation 目标 Message 标识。 */
+        message_id: string;
+        /** 当前 Mutation 所属 Turn 标识。 */
+        turn_id?: string;
+        /** 当前 Message 在线性 Session 中的不可变顺序。 */
+        sequence: number;
+        /** 应用当前 Mutation 后的 Message revision。 */
+        revision: number;
+        /** 创建或更新后的完整 Message 快照。 */
+        message: Extract<SessionMessage, {
+            type: TType;
+        }>;
+    };
+}[SessionMessage["type"]];
+/** Assistant Part 创建或完整快照更新 Mutation。 */
+export type SessionPartMutation = {
+    [TType in SessionAssistantMessagePart["type"]]: SessionMutationBase & {
+        /** Mutation 层级固定为 part。 */
+        variant: "part";
+        /** 当前完整 Part 类型。 */
+        type: TType;
+        /** 当前 Part 所属 Message 标识。 */
+        message_id: string;
+        /** 当前 Mutation 所属 Turn 标识。 */
+        turn_id?: string;
+        /** 应用当前 Mutation 后的 Message revision。 */
+        revision: number;
+        /** 当前被创建或更新的 Part 标识。 */
+        part_id: string;
+        /** 创建或更新后的完整 Part 快照。 */
+        part: SessionAssistantMessagePart & {
+            type: TType;
+        };
+    };
+}[SessionAssistantMessagePart["type"]];
+/** Assistant 文本或推理的原始增量 Mutation。 */
+export interface SessionDeltaMutation extends SessionMutationBase {
+    /** Mutation 层级固定为 delta。 */
+    variant: "delta";
+    /** Delta 只允许可见文本或推理文本。 */
+    type: "text" | "reasoning";
+    /** 当前 Delta 所属 Message 标识。 */
+    message_id: string;
+    /** 当前 Mutation 所属 Turn 标识。 */
+    turn_id?: string;
+    /** 应用当前 Mutation 后的 Message revision。 */
+    revision: number;
+    /** 当前 Delta 所属 Part 标识。 */
+    part_id: string;
+    /** 本次新增的原始文本，不是累计全文。 */
+    delta: string;
+}
+/** Turn 生命周期 Mutation。 */
+export type SessionTurnMutation = SessionMutationBase & {
+    /** Mutation 层级固定为 turn。 */
+    variant: "turn";
+    /** 当前 Turn 是开始还是完成。 */
+    type: "start" | "finish";
+    /** 当前 Turn 的稳定唯一标识。 */
+    turn_id: string;
+    /** 当前 Turn 的执行状态。 */
+    status: "running" | "completed" | "failed" | "stopped";
+    /** Turn 完成时的最终可见文本。 */
+    text?: string;
+    /** Turn 失败或停止时的错误文本。 */
+    error?: string;
+};
+/** Session 自身属性变化 Mutation。 */
+export type SessionStateMutation = SessionMutationBase & {
+    /** Mutation 层级固定为 session。 */
+    variant: "session";
+    /** 当前 Session 属性变化类型。 */
+    type: "title";
+    /** 当前 Session 最新标题。 */
+    title: string;
+};
+/** Session 对外唯一实时 Mutation 联合类型。 */
+export type SessionMutation = SessionMessageMutation | SessionPartMutation | SessionDeltaMutation | SessionTurnMutation | SessionStateMutation;
+/** 当前 Mutation 可用的命令回复入口。 */
+export interface SessionMutationReply {
+    /**
+     * 回复当前 Tool Part 的审批请求。
+     * 只有 approval-required Tool Part Mutation 可以成功调用。
+     */
+    approval(input: Pick<ResolveSessionApprovalInput, "decision">): Promise<SessionApprovalResult>;
+}
+/** Session Mutation 订阅回调。 */
+export type SessionMutationSubscriber = (mutation: SessionMutation, reply: SessionMutationReply) => void | Promise<void>;
+/** 取消 Session Mutation 订阅的函数。 */
+export type SessionMutationUnsubscribe = () => void;
+/** 判断未知事件是否为 Session Mutation。 */
+export declare function is_session_mutation(input: unknown): input is SessionMutation;
+//# sourceMappingURL=SessionMutation.d.ts.map

package/bin/types/session/SessionMutation.d.ts.map

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

package/bin/types/session/SessionMutation.js

@@ -0,0 +1,19 @@
+/**
+ * Session 的统一实时 Mutation 协议。
+ *
+ * Mutation 描述订阅之后发生的状态变化，不等同于 messages.jsonl 持久化格式。
+ */
+/** 判断未知事件是否为 Session Mutation。 */
+export function is_session_mutation(input) {
+    if (!input || typeof input !== "object")
+        return false;
+    const candidate = input;
+    if (typeof candidate.mutation_id !== "string" || typeof candidate.type !== "string")
+        return false;
+    return (candidate.variant === "message" ||
+        candidate.variant === "part" ||
+        candidate.variant === "delta" ||
+        candidate.variant === "turn" ||
+        candidate.variant === "session");
+}
+//# sourceMappingURL=SessionMutation.js.map

package/bin/types/session/SessionMutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionMutation.js","sourceRoot":"","sources":["../../../src/types/session/SessionMutation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4HH,kCAAkC;AAClC,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,SAAS,GAAG,KAAqE,CAAC;IACxF,IAAI,OAAO,SAAS,CAAC,WAAW,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClG,OAAO,CACL,SAAS,CAAC,OAAO,KAAK,SAAS;QAC/B,SAAS,CAAC,OAAO,KAAK,MAAM;QAC5B,SAAS,CAAC,OAAO,KAAK,OAAO;QAC7B,SAAS,CAAC,OAAO,KAAK,MAAM;QAC5B,SAAS,CAAC,OAAO,KAAK,SAAS,CAChC,CAAC;AACJ,CAAC"}

package/bin/types/session/SessionOptions.d.ts

@@ -13,6 +13,7 @@ import type { AgentSessionSystemBlock } from "../../types/agent/SessionTypes.js"
 import type { SessionComposerOptions } from "../../types/session/SessionComposerOptions.js";
 import type { Logger } from "../../utils/logger/Logger.js";
 import type { AgentModel } from "../../model/CityModelAdapter.js";
+import type { ResolveSessionApprovalInput, SessionApproval, SessionApprovalModeSnapshot, SessionApprovalResult, SetSessionApprovalModeInput } from "../../types/session/SessionApproval.js";
 /**
  * Agent 可管理的本地 Session 实例。
  */
@@ -72,6 +73,14 @@ export interface SessionOptions {
     ensureConfigured?: (session: AgentManagedSession) => Promise<void>;
     /** 按稳定模型 ID 解析当前 Session 的运行时模型。 */
     resolve_model?: (model_id: string) => Promise<AgentModel>;
+    /** 列出当前 Session 的 pending 工具审批。 */
+    list_approvals: (session_id: string) => Promise<SessionApproval[]>;
+    /** 读取当前 Session 的工具审批模式。 */
+    get_approval_mode: (session_id: string) => Promise<SessionApprovalModeSnapshot>;
+    /** 更新当前 Session 的工具审批模式。 */
+    set_approval_mode: (session_id: string, input: SetSessionApprovalModeInput) => Promise<SessionApprovalModeSnapshot>;
+    /** 处理当前 Session 的 pending 工具审批。 */
+    resolve_approval: (session_id: string, input: ResolveSessionApprovalInput) => Promise<SessionApprovalResult>;
     /**
      * 当前 session 的 Composer 覆盖项。
      */

package/bin/types/session/SessionOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SessionOptions.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AACzE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACxF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,cAAc,IAAI,WAAW,CAAC;IAE9B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,0BAA0B,EAAE,MAAM,uBAAuB,EAAE,CAAC;IAE5D;;OAEG;IACH,4BAA4B,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEvE;;OAEG;IACH,qBAAqB,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEhE;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,oCAAoC;IACpC,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAE1D;;OAEG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC"}
+{"version":3,"file":"SessionOptions.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AACzE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACxF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EACV,2BAA2B,EAC3B,eAAe,EACf,2BAA2B,EAC3B,qBAAqB,EACrB,2BAA2B,EAC5B,MAAM,oCAAoC,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,cAAc,IAAI,WAAW,CAAC;IAE9B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,0BAA0B,EAAE,MAAM,uBAAuB,EAAE,CAAC;IAE5D;;OAEG;IACH,4BAA4B,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEvE;;OAEG;IACH,qBAAqB,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEhE;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,oCAAoC;IACpC,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAE1D,mCAAmC;IACnC,cAAc,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAEnE,4BAA4B;IAC5B,iBAAiB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAEhF,4BAA4B;IAC5B,iBAAiB,EAAE,CACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,2BAA2B,KAC/B,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAE1C,mCAAmC;IACnC,gBAAgB,EAAE,CAChB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,2BAA2B,KAC/B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAEpC;;OAEG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.217",
+  "version": "1.1.224",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -13,8 +13,8 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.48",
-    "@downcity/shell": "^0.1.81",
-    "@downcity/type": "0.1.114",
+    "@downcity/shell": "^0.1.87",
+    "@downcity/type": "0.1.120",
     "ai": "^6.0.193",
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",

package/scripts/agent-env.test.mjs

@@ -33,7 +33,7 @@ test("项目 .env 覆盖宿主环境且不修改 process.env", () => {
     assert.equal(env.PROJECT_ONLY, "value");
     assert.equal(process.env.DOWNCITY_ENV_TEST, original_value);
   } finally {
-    fs.rmSync(project_root, { recursive: true, force: true });
+    fs.rmSync(project_root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   }
 });
 
@@ -50,7 +50,7 @@ test("SDK 未传 config 时不读取 downcity.json", async () => {
     await agent.ready();
     await agent.dispose();
   } finally {
-    fs.rmSync(project_root, { recursive: true, force: true });
+    fs.rmSync(project_root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   }
 });
 
@@ -65,7 +65,7 @@ test("SDK 未注入 plugin_config 时明确拒绝持久化", async () => {
     await agent.ready();
     await agent.dispose();
   } finally {
-    fs.rmSync(project_root, { recursive: true, force: true });
+    fs.rmSync(project_root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   }
 });
 
@@ -96,6 +96,6 @@ test("项目初始化只创建 .env、Skills 和运行目录并返回真实结
     assert.equal(second.skippedFiles.includes(".agents/skills/"), true);
     assert.equal(second.skippedFiles.includes(".downcity/"), true);
   } finally {
-    fs.rmSync(project_root, { recursive: true, force: true });
+    fs.rmSync(project_root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   }
 });

package/scripts/remote-session-reconnect.test.mjs

@@ -58,10 +58,14 @@ test("RemoteSession reconnects the event pump after transport close", async () =
   const second_turn = await session.prompt({ query: "second" });
   assert.equal(subscriptions.length, 2);
   subscriptions[1].on_event({
-    type: "turn-finish",
-    turnId: second_turn.id,
+    mutation_id: "turn-finish-2",
+    variant: "turn",
+    type: "finish",
+    session_id: "session_test",
+    turn_id: second_turn.id,
+    status: "completed",
+    created_at: Date.now(),
     text: "done",
-    success: true,
   });
   assert.equal((await second_turn.finished).text, "done");
 });