@downcity/agent 1.1.267 → 1.1.270

package/src/executor/services/ExecutorRecoveryPolicy.ts

@@ -107,16 +107,15 @@ interface ExecutorRecoveryRunInput {
  * 执行恢复与重试策略服务。
  */
 export class ExecutorRecoveryPolicy {
-  private readonly session_id: string;
   private readonly should_compact: ExecutorRecoveryPolicyOptions["should_compact"];
   private readonly logger: Logger;
   private retry_count = 0;
 
   constructor(options: ExecutorRecoveryPolicyOptions) {
-    this.session_id = String(options.session_id || "").trim();
+    const session_id = String(options.session_id || "").trim();
     this.should_compact = options.should_compact;
     this.logger = options.logger;
-    if (!this.session_id) {
+    if (!session_id) {
       throw new Error("ExecutorRecoveryPolicy requires a non-empty session_id");
     }
   }
@@ -161,8 +160,6 @@ export class ExecutorRecoveryPolicy {
         return this.build_failure_result({
           error_text:
             "Context length exceeded and retries failed. Please resend your question.",
-          fallback_text:
-            "Context length exceeded and retries failed. Please resend your question.",
           run_context: input.run_context,
         });
       }
@@ -173,7 +170,6 @@ export class ExecutorRecoveryPolicy {
       });
       return this.build_failure_result({
         error_text,
-        fallback_text: `Execution failed: ${error_text}`,
         run_context: input.run_context,
       });
     }
@@ -185,11 +181,6 @@ export class ExecutorRecoveryPolicy {
      */
     error_text: string;
 
-    /**
-     * fallback assistant 消息文本。
-     */
-    fallback_text: string;
-
     /**
      * 当前显式运行上下文。
      */
@@ -198,18 +189,6 @@ export class ExecutorRecoveryPolicy {
     return {
       success: false,
       error: input.error_text,
-      assistantMessage: {
-        id: `a:${this.session_id}:${Date.now()}`,
-        role: "assistant",
-        metadata: {
-          v: 1,
-          ts: Date.now(),
-          sessionId: this.session_id,
-          source: "egress",
-          kind: "normal",
-        },
-        parts: [{ type: "text", text: input.fallback_text }],
-      },
       deferredPersistedUserMessages: [
         ...input.run_context.deferredPersistedUserMessages,
       ],

package/src/executor/types/SessionRecords.ts

@@ -2,10 +2,9 @@
  * SessionRecord 类型定义。
  *
  * 关键点（中文）
- * - 这里统一描述 session JSONL 中的持久化 record 结构。
- * - record 是 session 内部事实源；其中 message record 继续使用 AI SDK `UIMessage`。
- * - action record 是 UI record，不属于 LLM 输入。
- * - 这些类型会被 Store、Composer、compact、control UI、task runtime 共同复用。
+ * - SessionMessage 是唯一持久化事实，record 只作为 Executor、Composer 和旧 UI 的内部投影。
+ * - message record 继续使用 AI SDK `UIMessage`，action record 不属于 LLM 输入。
+ * - 这些类型不定义 canonical Session 存储结构。
  */
 
 import type { UIMessage } from "ai";
@@ -15,9 +14,8 @@ import type { JsonObject } from "@/types/common/Json.js";
  * Session message record 类别。
  *
  * 关键点（中文）
- * - 持久化存储在 `.downcity/agents/<encodedAgentId>/sessions/<encodedSessionId>/messages/messages.jsonl`
- * - record 文件默认包含 message record，或 `type=action` 的 UI 状态记录。
- * - compact 会把更早 message record 压缩为一条 `assistant` 摘要 record。
+ * - User / Assistant SessionMessage 会在执行边界临时投影为 message record。
+ * - Compact Summary 同样投影为一条内部 `assistant` record。
  * - action 只用于 UI timeline，不进入 LLM 输入
  */
 export type SessionMessageKind = "normal" | "summary";

package/src/index.ts

@@ -40,14 +40,25 @@ export type {
 export type {
   ListSessionMessagesInput,
   SessionActionMessage,
+  SessionAssistantDataPart,
+  SessionAssistantDocumentSourcePart,
+  SessionAssistantFilePart,
   SessionAssistantMessage,
   SessionAssistantMessagePart,
+  SessionAssistantSourcePart,
+  SessionAssistantStepPart,
+  SessionAssistantTextPart,
   SessionAssistantToolPart,
+  SessionAssistantUrlSourcePart,
   SessionErrorMessage,
   SessionMessage,
   SessionMessagePage,
+  SessionUserDataPart,
+  SessionUserFilePart,
   SessionUserMessage,
   SessionUserMessagePart,
+  SessionUserTextPart,
+  SessionToolApprovalSnapshot,
 } from "./types/session/SessionMessage.js";
 export type {
   SessionContextSnapshot,

package/src/session/SessionMessages.ts

@@ -695,7 +695,10 @@ export class SessionMessages {
       await this.update_assistant_part_serialized(message_id, {
         ...tool.part,
         state: "approval-required",
-        approval,
+        approval: {
+          approval_id: approval.approval_id,
+          request: approval,
+        },
       });
     });
   }
@@ -721,6 +724,16 @@ export class SessionMessages {
       await this.update_assistant_part_serialized(message_id, {
         ...tool.part,
         state: input.decision === "approved" ? "running" : "failed",
+        approval: {
+          ...tool.part.approval,
+          approval_id: input.approval_id,
+          approved: input.decision === "approved",
+          ...(input.decision === "expired"
+            ? { reason: "Approval expired" }
+            : input.decision === "denied"
+              ? { reason: "Approval denied" }
+              : {}),
+        },
         ...(input.decision === "approved"
           ? {}
           : {

package/src/session/SessionSystem.ts

@@ -59,12 +59,12 @@ function create_session_system_block(
   session: AgentSessionSystemSessionInfo,
 ): AgentSessionSystemBlock {
   const content = [
-    "当前会话上下文：",
-    `你正在服务 agent "${session.agentId}" 的 session "${session.sessionId}"。`,
-    `当前项目根目录是 "${session.projectRoot}"。`,
-    `本会话创建于 ${session.createdAt}，参考时区是 ${session.timezone}。`,
-    "这个创建时间是当前会话的稳定参考时间，不代表每轮运行时的当前时间。",
-    "如果用户消息中提供了新的当前时间、相对时间或其他动态上下文，应优先使用用户消息中的动态信息。",
+    "Current session context:",
+    `You are serving agent "${session.agentId}" in session "${session.sessionId}".`,
+    `The current project root is "${session.projectRoot}".`,
+    `This session was created at ${session.createdAt}, with ${session.timezone} as its reference timezone.`,
+    "This creation time is a stable reference for the session and does not represent the current time for every run.",
+    "If the user message provides a newer current time, a relative time, or other dynamic context, prioritize the dynamic information from the user message.",
   ].join("\n");
   return {
     source: "session",

package/src/session/SessionTitle.ts

@@ -215,12 +215,6 @@ async function generateSessionTitle(input: {
         "",
         input.firstUserText,
       ].join("\n"),
-      // 标题生成是一次性调用，不参与 Responses continuation。
-      providerOptions: {
-        openai: {
-          store: false,
-        },
-      },
       onError: ({ error }) => {
         observedStreamError = error;
       },

package/src/session/SessionTurn.ts

@@ -241,10 +241,6 @@ export class SessionTurn {
           turnId: turn_id,
           text: "",
           success: false,
-          assistantMessage: build_prompt_runtime_error_assistant_message({
-            session_id: this.session_id,
-            message,
-          }),
           error: message,
         };
         active_turn.result = final_result;
@@ -291,10 +287,6 @@ export class SessionTurn {
         turnId: turn_id,
         text: "",
         success: false,
-        assistantMessage: build_prompt_runtime_error_assistant_message({
-          session_id: this.session_id,
-          message: QUEUED_PROMPT_CANCELLED_MESSAGE,
-        }),
         error: QUEUED_PROMPT_CANCELLED_MESSAGE,
       };
       cancelled_turn.result = final_result;
@@ -630,27 +622,6 @@ function is_assistant_content_chunk(type: string): boolean {
   );
 }
 
-function build_prompt_runtime_error_assistant_message(input: {
-  session_id: string;
-  message: string;
-}): SessionMessageRecordV1 {
-  return {
-    id: `a:${input.session_id}:${Date.now()}:${nanoid(6)}`,
-    role: "assistant",
-    metadata: {
-      v: 1,
-      ts: Date.now(),
-      sessionId: input.session_id,
-      source: "egress",
-      kind: "normal",
-      extra: {
-        note: "session_prompt_runtime_error",
-      },
-    },
-    parts: [{ type: "text", text: input.message }],
-  };
-}
-
 function create_deferred<T>(): SessionDeferred<T> {
   let resolve!: (value: T) => void;
   const promise = new Promise<T>((inner_resolve) => {

package/src/session/messages/SessionAssistantMessageWriter.ts

@@ -8,6 +8,7 @@
 import type { UIMessageChunk } from "ai";
 import type { SessionMessages } from "@/session/SessionMessages.js";
 import {
+  to_session_json_object,
   to_session_json_value,
   to_session_provider_metadata,
 } from "@/session/messages/SessionJsonValue.js";
@@ -15,6 +16,7 @@ import type {
   SessionAssistantFilePart,
   SessionAssistantMessage,
   SessionAssistantMessagePart,
+  SessionAssistantTextPart,
   SessionAssistantToolPart,
 } from "@/types/session/SessionMessage.js";
 import type { SessionToolInputReady } from "@/types/session/SessionTool.js";
@@ -24,7 +26,10 @@ import { generateId } from "@/utils/Id.js";
 export class SessionAssistantMessageWriter {
   readonly message_id: string;
   private readonly recorder: SessionMessages;
-  private readonly pending_text_parts = new Map<string, "text" | "reasoning">();
+  private readonly pending_text_parts = new Map<
+    string,
+    Pick<SessionAssistantTextPart, "type" | "provider_metadata">
+  >();
   private readonly active_text_part_ids = new Map<string, string>();
   private write_chain: Promise<void> = Promise.resolve();
   private closed = false;
@@ -51,7 +56,10 @@ export class SessionAssistantMessageWriter {
         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);
+          this.pending_text_parts.set(part_id, {
+            type,
+            provider_metadata: to_session_provider_metadata(chunk.providerMetadata),
+          });
         }
         return;
       }
@@ -59,7 +67,11 @@ export class SessionAssistantMessageWriter {
       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.ensure_text_part(
+          part_id,
+          type,
+          to_session_provider_metadata(chunk.providerMetadata),
+        );
         await this.recorder.append_assistant_delta(
           this.message_id,
           part_id,
@@ -76,7 +88,12 @@ export class SessionAssistantMessageWriter {
         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" });
+          const provider_metadata = to_session_provider_metadata(chunk.providerMetadata);
+          await this.upsert_part({
+            ...part,
+            state: "done",
+            ...(provider_metadata !== undefined ? { provider_metadata } : {}),
+          });
         } else {
           this.pending_text_parts.delete(part_id);
         }
@@ -88,10 +105,14 @@ export class SessionAssistantMessageWriter {
         const call_provider_metadata = to_session_provider_metadata(
           chunk.providerMetadata,
         );
+        const tool_metadata = to_session_json_object(chunk.toolMetadata);
         if (tool) {
           if (
             call_provider_metadata === undefined &&
-            chunk.providerExecuted === undefined
+            chunk.providerExecuted === undefined &&
+            chunk.title === undefined &&
+            tool_metadata === undefined &&
+            chunk.dynamic === undefined
           ) return;
           await this.upsert_tool(chunk.toolCallId, {
             tool_name: tool.tool_name,
@@ -102,6 +123,9 @@ export class SessionAssistantMessageWriter {
             ...(chunk.providerExecuted !== undefined
               ? { provider_executed: chunk.providerExecuted }
               : {}),
+            ...(chunk.title !== undefined ? { title: chunk.title } : {}),
+            ...(tool_metadata !== undefined ? { tool_metadata } : {}),
+            ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
           });
           return;
         }
@@ -115,6 +139,9 @@ export class SessionAssistantMessageWriter {
           ...(chunk.providerExecuted !== undefined
             ? { provider_executed: chunk.providerExecuted }
             : {}),
+          ...(chunk.title !== undefined ? { title: chunk.title } : {}),
+          ...(tool_metadata !== undefined ? { tool_metadata } : {}),
+          ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
         });
         return;
       }
@@ -133,10 +160,14 @@ export class SessionAssistantMessageWriter {
         const call_provider_metadata = to_session_provider_metadata(
           chunk.providerMetadata,
         );
+        const tool_metadata = to_session_json_object(chunk.toolMetadata);
         if (tool && tool.state !== "input-streaming") {
           if (
             call_provider_metadata === undefined &&
-            chunk.providerExecuted === undefined
+            chunk.providerExecuted === undefined &&
+            chunk.title === undefined &&
+            tool_metadata === undefined &&
+            chunk.dynamic === undefined
           ) return;
           await this.upsert_tool(chunk.toolCallId, {
             tool_name: tool.tool_name,
@@ -147,6 +178,9 @@ export class SessionAssistantMessageWriter {
             ...(chunk.providerExecuted !== undefined
               ? { provider_executed: chunk.providerExecuted }
               : {}),
+            ...(chunk.title !== undefined ? { title: chunk.title } : {}),
+            ...(tool_metadata !== undefined ? { tool_metadata } : {}),
+            ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
           });
           return;
         }
@@ -160,6 +194,9 @@ export class SessionAssistantMessageWriter {
           ...(chunk.providerExecuted !== undefined
             ? { provider_executed: chunk.providerExecuted }
             : {}),
+          ...(chunk.title !== undefined ? { title: chunk.title } : {}),
+          ...(tool_metadata !== undefined ? { tool_metadata } : {}),
+          ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
         });
         return;
       }
@@ -167,17 +204,33 @@ export class SessionAssistantMessageWriter {
         const call_provider_metadata = to_session_provider_metadata(
           chunk.providerMetadata,
         );
+        const tool_metadata = to_session_json_object(chunk.toolMetadata);
         await this.upsert_tool(chunk.toolCallId, {
           tool_name: chunk.toolName,
           state: "failed",
           input: to_session_json_value(chunk.input),
           error: chunk.errorText,
+          ...(chunk.input === undefined && "rawInput" in chunk && chunk.rawInput !== undefined
+            ? { raw_input: to_session_json_value(chunk.rawInput) }
+            : {}),
           ...(call_provider_metadata !== undefined
             ? { call_provider_metadata }
             : {}),
           ...(chunk.providerExecuted !== undefined
             ? { provider_executed: chunk.providerExecuted }
             : {}),
+          ...(chunk.title !== undefined ? { title: chunk.title } : {}),
+          ...(tool_metadata !== undefined ? { tool_metadata } : {}),
+          ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
+        });
+        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: { approval_id: chunk.approvalId },
         });
         return;
       }
@@ -190,6 +243,7 @@ export class SessionAssistantMessageWriter {
         const result_provider_metadata = to_session_provider_metadata(
           chunk.providerMetadata,
         );
+        const tool_metadata = to_session_json_object(chunk.toolMetadata);
         await this.upsert_tool(chunk.toolCallId, {
           tool_name: tool?.tool_name || "unknown",
           state: "completed",
@@ -200,6 +254,11 @@ export class SessionAssistantMessageWriter {
           ...(chunk.providerExecuted !== undefined
             ? { provider_executed: chunk.providerExecuted }
             : {}),
+          ...(tool_metadata !== undefined ? { tool_metadata } : {}),
+          ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
+          ...(chunk.preliminary !== undefined
+            ? { preliminary: chunk.preliminary }
+            : {}),
         });
         return;
       }
@@ -208,6 +267,7 @@ export class SessionAssistantMessageWriter {
         const result_provider_metadata = to_session_provider_metadata(
           chunk.providerMetadata,
         );
+        const tool_metadata = to_session_json_object(chunk.toolMetadata);
         await this.upsert_tool(chunk.toolCallId, {
           tool_name: tool?.tool_name || "unknown",
           state: "failed",
@@ -218,6 +278,8 @@ export class SessionAssistantMessageWriter {
           ...(chunk.providerExecuted !== undefined
             ? { provider_executed: chunk.providerExecuted }
             : {}),
+          ...(tool_metadata !== undefined ? { tool_metadata } : {}),
+          ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
         });
         return;
       }
@@ -227,6 +289,12 @@ export class SessionAssistantMessageWriter {
           tool_name: tool?.tool_name || "unknown",
           state: "failed",
           error: "Tool output denied",
+          approval: {
+            ...(tool?.approval || {}),
+            approval_id:
+              tool?.approval?.approval_id || `approval:${chunk.toolCallId}`,
+            approved: false,
+          },
         });
         return;
       }
@@ -234,10 +302,73 @@ export class SessionAssistantMessageWriter {
         await this.append_file_part({
           media_type: chunk.mediaType,
           url: chunk.url,
+          provider_metadata: to_session_provider_metadata(chunk.providerMetadata),
         });
         return;
-      default:
+      case "source-url": {
+        const part_id = `source:${chunk.sourceId}`;
+        const current_part = current.parts.find((part) => part.part_id === part_id);
+        const provider_metadata = to_session_provider_metadata(chunk.providerMetadata);
+        await this.upsert_part({
+          part_id,
+          sequence: current_part?.sequence || this.next_part_sequence(),
+          type: "source",
+          source_type: "url",
+          source_id: chunk.sourceId,
+          url: chunk.url,
+          ...(chunk.title !== undefined ? { title: chunk.title } : {}),
+          ...(provider_metadata !== undefined
+            ? { provider_metadata }
+            : {}),
+        });
         return;
+      }
+      case "source-document": {
+        const part_id = `source:${chunk.sourceId}`;
+        const current_part = current.parts.find((part) => part.part_id === part_id);
+        const provider_metadata = to_session_provider_metadata(chunk.providerMetadata);
+        await this.upsert_part({
+          part_id,
+          sequence: current_part?.sequence || this.next_part_sequence(),
+          type: "source",
+          source_type: "document",
+          source_id: chunk.sourceId,
+          media_type: chunk.mediaType,
+          title: chunk.title,
+          ...(chunk.filename !== undefined ? { filename: chunk.filename } : {}),
+          ...(provider_metadata !== undefined
+            ? { provider_metadata }
+            : {}),
+        });
+        return;
+      }
+      case "start-step":
+        await this.upsert_part({
+          part_id: `step:${generateId()}`,
+          sequence: this.next_part_sequence(),
+          type: "step-start",
+        });
+        return;
+      default: {
+        if (chunk.type.startsWith("data-")) {
+          const data_chunk = chunk as unknown as Record<string, unknown>;
+          if (data_chunk.transient === true) return;
+          const data_id = typeof data_chunk.id === "string"
+            ? data_chunk.id
+            : undefined;
+          const part_id = `data:${data_id ?? generateId()}`;
+          const current_part = current.parts.find((part) => part.part_id === part_id);
+          await this.upsert_part({
+            part_id,
+            sequence: current_part?.sequence || this.next_part_sequence(),
+            type: "data",
+            data_type: chunk.type,
+            data: to_session_json_value(data_chunk.data),
+            ...(data_id !== undefined ? { data_id } : {}),
+          });
+        }
+        return;
+      }
     }
   }
 
@@ -285,7 +416,10 @@ export class SessionAssistantMessageWriter {
 
   /** 把最终结果中的文件补入当前 Assistant，并对流式已写入文件去重。 */
   async append_file_part(
-    input: Pick<SessionAssistantFilePart, "filename" | "media_type" | "url">,
+    input: Pick<
+      SessionAssistantFilePart,
+      "filename" | "media_type" | "provider_metadata" | "url"
+    >,
   ): Promise<void> {
     const filename = String(input.filename || "").trim();
     const current = this.current_message();
@@ -296,8 +430,17 @@ export class SessionAssistantMessageWriter {
         part.media_type === input.media_type,
     );
     if (existing?.type === "file") {
-      if (filename && String(existing.filename || "").trim() !== filename) {
-        await this.upsert_part({ ...existing, filename });
+      if (
+        (filename && String(existing.filename || "").trim() !== filename) ||
+        input.provider_metadata !== undefined
+      ) {
+        await this.upsert_part({
+          ...existing,
+          ...(filename ? { filename } : {}),
+          ...(input.provider_metadata !== undefined
+            ? { provider_metadata: input.provider_metadata }
+            : {}),
+        });
       }
       return;
     }
@@ -308,6 +451,9 @@ export class SessionAssistantMessageWriter {
       media_type: input.media_type,
       url: input.url,
       ...(filename ? { filename } : {}),
+      ...(input.provider_metadata !== undefined
+        ? { provider_metadata: input.provider_metadata }
+        : {}),
     });
   }
 
@@ -392,6 +538,7 @@ export class SessionAssistantMessageWriter {
   private async ensure_text_part(
     part_id: string,
     type: "text" | "reasoning",
+    provider_metadata?: SessionAssistantTextPart["provider_metadata"],
   ): Promise<void> {
     const existing = this.current_message().parts.find(
       (part) => part.part_id === part_id,
@@ -400,10 +547,16 @@ export class SessionAssistantMessageWriter {
       if (existing.type !== type) {
         throw new Error(`Assistant Part type changed: ${part_id}`);
       }
+      if (
+        (existing.type === "text" || existing.type === "reasoning") &&
+        provider_metadata !== undefined
+      ) {
+        await this.upsert_part({ ...existing, provider_metadata });
+      }
       return;
     }
-    const pending_type = this.pending_text_parts.get(part_id);
-    if (pending_type && pending_type !== type) {
+    const pending = this.pending_text_parts.get(part_id);
+    if (pending && pending.type !== type) {
       throw new Error(`Assistant pending Part type changed: ${part_id}`);
     }
     await this.upsert_part({
@@ -412,6 +565,11 @@ export class SessionAssistantMessageWriter {
       type,
       text: "",
       state: "streaming",
+      ...(provider_metadata !== undefined
+        ? { provider_metadata }
+        : pending?.provider_metadata !== undefined
+          ? { provider_metadata: pending.provider_metadata }
+          : {}),
     });
     this.pending_text_parts.delete(part_id);
   }

package/src/session/messages/SessionJsonValue.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ProviderMetadata } from "ai";
-import type { JsonValue } from "@/types/common/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 
 /** 把任意运行时输入转换为可持久化的 JSON 值。 */
 export function to_session_json_value(input: unknown): JsonValue {
@@ -25,6 +25,17 @@ export function to_session_json_value(input: unknown): JsonValue {
   }
 }
 
+/** 把任意运行时输入转换为可持久化 JSON 对象，非对象输入返回 undefined。 */
+export function to_session_json_object(input: unknown): JsonObject | undefined {
+  if (!is_plain_object(input)) return undefined;
+  try {
+    const value = JSON.parse(JSON.stringify(input)) as unknown;
+    return is_plain_object(value) ? value as JsonObject : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * 把 AI SDK Provider metadata 规整为可持久化快照。
  *