@downcity/agent 1.1.337 → 1.1.399

package/src/types/session/SessionPort.ts

@@ -6,11 +6,11 @@
  * - 不暴露具体 Session class，也不包含 Session 集合管理能力。
  */
 
-import type { LanguageModel } from "ai";
+import type { ModelClient } from "@downcity/type";
 import type {
-  SessionMetadataV1,
-  SessionRecordV1,
-} from "@/executor/types/SessionRecords.js";
+  SessionAssistantResultPart,
+  SessionPromptPart,
+} from "@/types/session/SessionContent.js";
 import type { SessionExecutor } from "@/types/session/SessionExecution.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -29,7 +29,7 @@ export interface SessionPort {
   readonly session_id: string;
 
   /** 获取当前 Session 优先解析后的运行时模型实例。 */
-  get_model(): LanguageModel | undefined;
+  get_model(): ModelClient | undefined;
 
   /** 获取当前 Session 的执行端口。 */
   get_executor(): SessionExecutor;
@@ -50,28 +50,20 @@ export interface SessionPort {
    * 追加一条 user 消息。
    */
   append_user_message(params: {
-    /** 已构造好的完整消息。 */
-    message?: SessionRecordV1 | null;
-
-    /** 未传入完整消息时使用的兜底文本。 */
+    /** 已构造好的 User 内容。 */
+    parts?: SessionPromptPart[];
+    /** 未传入结构化内容时使用的文本。 */
     text?: string;
-
-    /** 当前消息附加元数据。 */
-    extra?: SessionMetadataV1["extra"];
   }): Promise<void>;
 
   /**
    * 追加一条 assistant 消息。
    */
   append_assistant_message(params: {
-    /** 已构造好的完整消息。 */
-    message?: SessionRecordV1 | null;
-
-    /** 未传入完整消息时使用的兜底文本。 */
-    fallback_text?: string;
-
-    /** 当前消息附加元数据。 */
-    extra?: SessionMetadataV1["extra"];
+    /** 已构造好的 Assistant 内容。 */
+    parts?: SessionAssistantResultPart[];
+    /** 未传入结构化内容时使用的文本。 */
+    text?: string;
   }): Promise<void>;
 
   /** 返回当前 Session 是否正在执行。 */

package/src/types/session/SessionState.ts

@@ -4,12 +4,13 @@
  * 这些类型只描述 Session 配置和 Metadata 状态，不承载 Message 行为。
  */
 
-import type { LanguageModel } from "ai";
+import type { ModelClient } from "@downcity/type";
 import type { SessionMessages } from "@/session/SessionMessages.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import type { SessionMutation } from "@/types/session/SessionMutation.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionStore } from "@/types/store/SessionStore.js";
+import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
 
 /** SessionState 构造参数。 */
 export interface SessionStateOptions {
@@ -17,8 +18,10 @@ export interface SessionStateOptions {
   agent_id: string;
   /** 当前 Session 的稳定标识。 */
   session_id: string;
+  /** 当前 Session 的创建来源。 */
+  origin?: SessionOrigin;
   /** 当前 Session 独享的领域持久化视图。 */
-  store: SessionStore;
+  store: SessionDataStore;
   /** 当前 Session 的 canonical Message 入口。 */
   messages: SessionMessages;
   /** 当前 Session 的可变内存状态。 */
@@ -28,7 +31,7 @@ export interface SessionStateOptions {
   /** 在执行前补齐宿主级配置的异步钩子。 */
   ensure_configured_hook?: () => Promise<void>;
   /** 按 Session 优先、Agent 兜底规则读取当前模型。 */
-  get_model: () => LanguageModel | undefined;
+  get_model: () => ModelClient | undefined;
   /** 发布 Session Mutation 的函数。 */
   publish_event: (mutation: SessionMutation) => void;
 }

package/src/types/session/SessionTool.ts

@@ -24,6 +24,18 @@ export interface SessionToolInputReady {
   input: unknown;
 }
 
+/** Tool 执行终态输入。 */
+export interface SessionToolExecutionResult {
+  /** 对应模型 Tool Call 标识。 */
+  tool_call_id: string;
+  /** 对应工具注册名称。 */
+  tool_name: string;
+  /** Tool 是否成功执行。 */
+  succeeded: boolean;
+  /** Tool 返回的可序列化结果。 */
+  output: unknown;
+}
+
 /** 等待单个 canonical Tool Part 到达的异步句柄。 */
 export interface SessionToolPartWaiter {
   /** Tool Part 成功持久化后完成，异常结束时拒绝。 */

package/src/types/store/LocalStore.ts

@@ -2,33 +2,41 @@
  * 本地 Workspace Store 实现的构造类型。
  *
  * 关键点（中文）
- * - 本地 Store 只接收 Workspace 已创建的 FileSystem，不单独接收存储根目录。
- * - AgentStore 与 SessionStore 因而始终和 WorkspaceTools 使用同一资源容器。
+ * - 本地 Store 接收 AgentStorage 创建的私有 FileSystem 与存储根目录。
+ * - SessionStore 与 SessionDataStore 不复用项目 WorkspaceTools 的 FileSystem。
  */
 
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { FileSystem } from "@downcity/workspace";
 
-/** LocalAgentStore 构造参数。 */
-export interface LocalAgentStoreOptions {
-  /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
+/** LocalSessionStore 构造参数。 */
+export interface LocalSessionStoreOptions {
+  /** 当前 Agent 内部数据文件能力。 */
   files: FileSystem;
-  /** 当前 Agent 的稳定标识，用于划分 `.downcity/agents` 子目录。 */
+  /** 当前 Agent 内部数据的绝对根路径。 */
+  storage_root_path: string;
+  /** 当前 Session 查询视图所属 Agent 的稳定标识。 */
   agent_id: string;
+  /** 当前 Workspace 的稳定标识。 */
+  workspace_id?: string;
 }
 
-/** LocalSessionStore 构造参数。 */
-export interface LocalSessionStoreOptions {
-  /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
+/** LocalSessionDataStore 构造参数。 */
+export interface LocalSessionDataStoreOptions {
+  /** 当前 Agent 私有数据文件能力。 */
   files: FileSystem;
+  /** 当前 Agent 内部数据的绝对根路径。 */
+  storage_root_path: string;
   /** 当前 Session 所属 Agent 的稳定标识。 */
   agent_id: string;
+  /** 当前 Session 所属 Workspace 的稳定标识。 */
+  workspace_id?: string;
   /** 当前 Session 的稳定标识。 */
   session_id: string;
 }
 
 /** JsonlSessionMessageStore 构造参数。 */
 export interface JsonlSessionMessageStoreOptions {
-  /** 当前 Message Store 与 Session 共用的 Workspace 文件能力。 */
+  /** 当前 Message Store 使用的 Agent 私有文件能力。 */
   files: FileSystem;
   /** 当前 Session 的稳定标识。 */
   session_id: string;

package/src/types/store/SessionAttachmentStore.ts

@@ -4,9 +4,9 @@
  * Session Message 只保存附件引用，附件内容由该 Store 在 Session 生命周期内持有。
  *
  * 数据边界（中文）：
- * - 输入边界：`session.prompt()` 接收 `type: "file"`、`mediaType` 和 Data URL。
- * - 存储边界：Store 解码 Data URL，写入 `.downcity/.../attachments/att_<id>.<ext>`。
- * - Message 边界：Session Message 只记录相对 Workspace 根目录的附件路径。
+ * - 输入边界：`session.prompt()` 接收 `type: "file"`、`media_type` 和 Data URL。
+ * - 存储边界：Store 解码 Data URL，写入 Agent 私有附件目录。
+ * - Message 边界：Session Message 只记录附件的稳定绝对路径。
  * - 模型边界：模型转换器读取该路径，在内存中恢复成模型需要的文件内容。
  *
  * 因此，Data URL 不会直接进入 JSONL Message；Session Message 是附件路径的唯一引用。
@@ -15,7 +15,7 @@
 /** 可持久化的 Data URL 附件。 */
 export interface SessionAttachmentStore {
   /**
-   * 保存 Data URL，并返回相对 Workspace 根目录的稳定文件路径。
+   * 保存 Data URL，并返回 Agent 私有目录中的稳定绝对路径。
    * 调用成功后，返回路径对应的附件文件必须已经完整落盘。
    */
   persist_data_url(input: {

package/src/types/store/SessionDataStore.ts

@@ -0,0 +1,109 @@
+/**
+ * 单个 Session 数据存储类型。
+ *
+ * 关键点（中文）
+ * - Session 领域只依赖这些持久化能力，不感知 JSONL、目录或文件名。
+ * - Message、Metadata 与 Instruction 共享同一个 Session 生命周期边界。
+ */
+
+import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
+import type {
+  SessionAssistantMessage,
+  SessionMessage,
+} from "@/types/session/SessionMessage.js";
+import type {
+  SessionMessageStorageStats,
+  SessionSegmentRange,
+  SessionSegmentSnapshot,
+  SessionSegmentSummary,
+} from "@/types/session/SessionSegment.js";
+import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
+
+/** 在 Message Store 写事务中创建新消息所需的稳定状态。 */
+export interface SessionMessageCommitState {
+  /** 下一条真实 Message 应使用的全局线性顺序。 */
+  message_sequence: number;
+  /** 当前 Active 与 Assistant 草稿组成的运行态 Message。 */
+  messages: SessionMessage[];
+}
+
+/** Active Message 压缩提交参数。 */
+export interface CompactActiveMessagesInput {
+  /** 移入新 Segment 的最后一条真实 Message sequence。 */
+  through_sequence: number;
+  /** 写入新 Segment 末尾的累计上下文摘要。 */
+  summary: SessionSegmentSummary;
+}
+
+/** Active Message 压缩提交结果。 */
+export interface CompactActiveMessagesResult {
+  /** 本次创建的不可变历史分段。 */
+  segment: SessionSegmentSnapshot;
+  /** 压缩后继续保留在 Active 区域的 Message。 */
+  active_messages: SessionMessage[];
+}
+
+/** Session Message 持久化能力。 */
+export interface SessionMessageStore {
+  /** 初始化消息存储，并修复可恢复的中断状态。 */
+  initialize(): Promise<void>;
+  /** 读取当前 Active Message 与运行中的 Assistant 草稿。 */
+  list_messages(): Promise<SessionMessage[]>;
+  /** 读取指定 sequence 之前最近的完整历史分段。 */
+  read_segment_before(before_sequence: number): Promise<SessionSegmentSnapshot | null>;
+  /** 读取最新历史分段的累计摘要。 */
+  read_latest_summary(): Promise<SessionSegmentSummary | null>;
+  /** 读取当前 Session 的全部真实历史消息。 */
+  list_history_messages(): Promise<SessionMessage[]>;
+  /** 读取消息数量、存储大小与最新消息统计。 */
+  stats(): Promise<SessionMessageStorageStats>;
+  /** 判断指定 sequence 之前是否存在历史分段。 */
+  has_segment_before(before_sequence: number): Promise<boolean>;
+  /** 计算当前 Active Message 之前的读取边界。 */
+  active_before_sequence(messages: SessionMessage[]): Promise<number | undefined>;
+  /** 读取当前运行中的 Assistant 草稿。 */
+  read_assistant_message(): Promise<SessionAssistantMessage | null>;
+  /** 原子覆盖当前运行中的 Assistant 草稿。 */
+  write_assistant_message(message: SessionAssistantMessage): Promise<void>;
+  /** 在存储事务中创建唯一 Assistant 草稿。 */
+  create_assistant_message(
+    build_message: (state: SessionMessageCommitState) => SessionAssistantMessage,
+  ): Promise<SessionAssistantMessage>;
+  /** 在存储事务中追加一条 Message。 */
+  append_message(
+    build_message: (state: SessionMessageCommitState) => SessionMessage,
+  ): Promise<SessionMessage>;
+  /** 提交最终 Assistant Message 并删除运行中草稿。 */
+  finalize_assistant_message(message: SessionAssistantMessage): Promise<void>;
+  /** 将 Active 前缀压缩为不可变历史分段。 */
+  compact_active(input: CompactActiveMessagesInput): Promise<CompactActiveMessagesResult>;
+  /** 读取全部历史分段的 sequence 索引。 */
+  list_segment_ranges(): Promise<SessionSegmentRange[]>;
+}
+
+/** 单个 Session 的领域持久化视图。 */
+export interface SessionDataStore {
+  /** 当前 Session 的稳定标识。 */
+  readonly session_id: string;
+
+  /** 当前 Session 的 Message 持久化能力。 */
+  readonly messages: SessionMessageStore;
+
+  /** 当前 Session 的附件持久化能力。 */
+  readonly attachments: SessionAttachmentStore;
+
+  /** 读取 Session Metadata；不存在时返回规范化的初始值。 */
+  read_metadata(): Promise<SessionHistoryMetaV1>;
+
+  /** 原子写入完整 Session Metadata。 */
+  write_metadata(metadata: SessionHistoryMetaV1): Promise<void>;
+
+  /** 判断 Session 是否存在显式固化的完整 system。 */
+  has_instruction(): Promise<boolean>;
+
+  /** 读取显式固化的完整 system；不存在时返回 null。 */
+  read_instruction(): Promise<string | null>;
+
+  /** 原子写入显式固化的完整 system。 */
+  write_instruction(instruction: string): Promise<void>;
+}

package/src/types/store/SessionStore.ts

@@ -1,109 +1,52 @@
 /**
- * Session Store 类型。
+ * Session 集合存储类型。
  *
  * 关键点（中文）
- * - Session 领域只依赖这些持久化能力，不感知 JSONL、目录或文件名。
- * - Message、Metadata 与 Instruction 共享同一个 Session 生命周期边界。
+ * - AgentSessions 只通过该接口管理 Session 生命周期和索引。
+ * - 接口不暴露物理目录，避免 Session 领域重新依赖路径约定。
  */
 
-import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type {
-  SessionAssistantMessage,
-  SessionMessage,
-} from "@/types/session/SessionMessage.js";
-import type {
-  SessionMessageStorageStats,
-  SessionSegmentRange,
-  SessionSegmentSnapshot,
-  SessionSegmentSummary,
-} from "@/types/session/SessionSegment.js";
-import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
-
-/** 在 Message Store 写事务中创建新消息所需的稳定状态。 */
-export interface SessionMessageCommitState {
-  /** 下一条真实 Message 应使用的全局线性顺序。 */
-  message_sequence: number;
-  /** 当前 Active 与 Assistant 草稿组成的运行态 Message。 */
-  messages: SessionMessage[];
-}
-
-/** Active Message 压缩提交参数。 */
-export interface CompactActiveMessagesInput {
-  /** 移入新 Segment 的最后一条真实 Message sequence。 */
-  through_sequence: number;
-  /** 写入新 Segment 末尾的累计上下文摘要。 */
-  summary: SessionSegmentSummary;
-}
-
-/** Active Message 压缩提交结果。 */
-export interface CompactActiveMessagesResult {
-  /** 本次创建的不可变历史分段。 */
-  segment: SessionSegmentSnapshot;
-  /** 压缩后继续保留在 Active 区域的 Message。 */
-  active_messages: SessionMessage[];
-}
-
-/** Session Message 持久化能力。 */
-export interface SessionMessageStore {
-  /** 初始化消息存储，并修复可恢复的中断状态。 */
-  initialize(): Promise<void>;
-  /** 读取当前 Active Message 与运行中的 Assistant 草稿。 */
-  list_messages(): Promise<SessionMessage[]>;
-  /** 读取指定 sequence 之前最近的完整历史分段。 */
-  read_segment_before(before_sequence: number): Promise<SessionSegmentSnapshot | null>;
-  /** 读取最新历史分段的累计摘要。 */
-  read_latest_summary(): Promise<SessionSegmentSummary | null>;
-  /** 读取当前 Session 的全部真实历史消息。 */
-  list_history_messages(): Promise<SessionMessage[]>;
-  /** 读取消息数量、存储大小与最新消息统计。 */
-  stats(): Promise<SessionMessageStorageStats>;
-  /** 判断指定 sequence 之前是否存在历史分段。 */
-  has_segment_before(before_sequence: number): Promise<boolean>;
-  /** 计算当前 Active Message 之前的读取边界。 */
-  active_before_sequence(messages: SessionMessage[]): Promise<number | undefined>;
-  /** 读取当前运行中的 Assistant 草稿。 */
-  read_assistant_message(): Promise<SessionAssistantMessage | null>;
-  /** 原子覆盖当前运行中的 Assistant 草稿。 */
-  write_assistant_message(message: SessionAssistantMessage): Promise<void>;
-  /** 在存储事务中创建唯一 Assistant 草稿。 */
-  create_assistant_message(
-    build_message: (state: SessionMessageCommitState) => SessionAssistantMessage,
-  ): Promise<SessionAssistantMessage>;
-  /** 在存储事务中追加一条 Message。 */
-  append_message(
-    build_message: (state: SessionMessageCommitState) => SessionMessage,
-  ): Promise<SessionMessage>;
-  /** 提交最终 Assistant Message 并删除运行中草稿。 */
-  finalize_assistant_message(message: SessionAssistantMessage): Promise<void>;
-  /** 将 Active 前缀压缩为不可变历史分段。 */
-  compact_active(input: CompactActiveMessagesInput): Promise<CompactActiveMessagesResult>;
-  /** 读取全部历史分段的 sequence 索引。 */
-  list_segment_ranges(): Promise<SessionSegmentRange[]>;
-}
-
-/** 单个 Session 的领域持久化视图。 */
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+} from "@/types/agent/SessionTypes.js";
+import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+
+/** 一个 Agent 所属全部 Session 的持久化入口。 */
 export interface SessionStore {
-  /** 当前 Session 的稳定标识。 */
-  readonly session_id: string;
+  /** 返回指定 Session 的稳定持久化视图。 */
+  session(session_id: string, workspace_id?: string): SessionDataStore;
+
+  /** 判断活动 Session 是否存在。 */
+  has_session(session_id: string): Promise<boolean>;
 
-  /** 当前 Session 的 Message 持久化能力。 */
-  readonly messages: SessionMessageStore;
+  /** 永久删除活动 Session 的全部领域数据。 */
+  remove_session(session_id: string): Promise<boolean>;
 
-  /** 当前 Session 的附件持久化能力。 */
-  readonly attachments: SessionAttachmentStore;
+  /** 清空活动 Session 的 Message 数据。 */
+  clear_session_messages(session_id: string): Promise<boolean>;
 
-  /** 读取 Session Metadata；不存在时返回规范化的初始值。 */
-  read_metadata(): Promise<SessionHistoryMetaV1>;
+  /** 返回活动 Session 摘要页。 */
+  list_sessions(
+    input: AgentListSessionsInput | undefined,
+    executing_session_ids: ReadonlySet<string>,
+  ): Promise<AgentSessionSummaryPage>;
 
-  /** 原子写入完整 Session Metadata。 */
-  write_metadata(metadata: SessionHistoryMetaV1): Promise<void>;
+  /** 将活动 Session 原子迁入归档区。 */
+  archive_session(session_id: string): Promise<AgentArchiveSessionResult>;
 
-  /** 判断 Session 是否存在显式固化的完整 system。 */
-  has_instruction(): Promise<boolean>;
+  /** 返回已归档 Session 摘要页。 */
+  list_archived_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult>;
 
-  /** 读取显式固化的完整 system；不存在时返回 null。 */
-  read_instruction(): Promise<string | null>;
+  /** 永久删除全部归档 Session。 */
+  clean_archive(): Promise<AgentCleanArchiveResult>;
 
-  /** 原子写入显式固化的完整 system。 */
-  write_instruction(instruction: string): Promise<void>;
+  /** 刷新并释放当前 Store 持有的资源。 */
+  dispose(): Promise<void>;
 }

package/src/types/tools/ToolActionExecutionContext.ts

@@ -0,0 +1,32 @@
+/**
+ * 普通 Tool 一次调用获得的最小执行上下文。
+ *
+ * 该类型只暴露业务 Tool 需要的调用身份、取消、Workspace 快照和可选
+ * Session Interaction，不暴露 SessionTurnContext、消息写入器或 Plugin lease。
+ */
+
+import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
+
+/** 普通 Tool 所属的 Session 范围。 */
+export interface ToolSessionExecutionScope {
+  /** 当前 Session 标识。 */
+  readonly session_id: string;
+  /** 当前 Turn 标识。 */
+  readonly turn_id: string;
+  /** 当前 Session 的用户交互端口；未启用 Interaction 时为空。 */
+  readonly interactions?: SessionInteractionPort;
+}
+
+/** 普通 Tool 的单次调用上下文。 */
+export interface ToolActionExecutionContext {
+  /** 当前 Tool Call 标识。 */
+  readonly call_id: string;
+  /** 当前 Tool 调用的取消信号。 */
+  readonly abort_signal: AbortSignal;
+  /** 当前 Tool 所属 Session 范围。 */
+  readonly session: ToolSessionExecutionScope;
+  /** 当前 Workspace 项目根目录。 */
+  readonly workspace_path?: string;
+  /** 当前 Step 已提交生效的 Workspace env。 */
+  readonly workspace_env?: Readonly<Record<string, string>>;
+}

package/src/utils/logger/Logger.ts

@@ -9,8 +9,8 @@
 import { get_logs_dir_path } from "@/workspace/WorkspacePaths.js";
 import { get_timestamp } from "@/utils/Time.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
-import { LocalFileSystem } from "@/workspace/LocalFileSystem.js";
+import type { FileSystem } from "@downcity/workspace";
+import { LocalFileSystem } from "@downcity/workspace";
 
 type LogDetails = {
   [key: string]: JsonObject[keyof JsonObject] | undefined;
@@ -164,7 +164,8 @@ function normalizeToAllowedMessageLabels(message: string): string {
  * - Provide a single logger interface usable by both:
  *   - system/runtime components (server, scheduler, tool executor, etc.)
  *   - agent/LLM execution (LLM request/response logging expects `logger.log(...)`)
- * - Persist logs as JSONL to `.downcity/logs/<YYYY-MM-DD>.jsonl` (one line per entry).
+ * - Persist logs as JSONL to the current Agent storage directory
+ *   (`logs/<YYYY-MM-DD>.jsonl`, one line per entry).
  * - Keep console output human-friendly, but make disk logs machine-friendly.
  *
  * Notes:
@@ -174,13 +175,15 @@ function normalizeToAllowedMessageLabels(message: string): string {
  */
 export interface LogEntry {
   id: string;
+  /** 产生日志的 Agent 稳定标识。 */
+  agent_id?: string;
+  /** 产生日志的 Workspace 稳定标识。 */
+  workspace_id?: string;
   timestamp: string;
   type: "info" | "warn" | "error" | "debug" | "action";
   message: string;
   details?: JsonObject;
   duration?: number;
-  /** Back-compat: kept for older code that expects a `level` field. */
-  level?: string;
 }
 
 /**
@@ -196,6 +199,9 @@ export class Logger {
   private writeChain: Promise<void> = Promise.resolve();
   private readonly maxInMemoryEntries = 2000;
   private workspace_files: FileSystem | null = null;
+  private storage_root_path = "";
+  private agent_id = "";
+  private workspace_id = "";
 
   constructor(logLevel: string = "info") {
     this.logLevel = logLevel;
@@ -207,16 +213,29 @@ export class Logger {
    * 关键点（中文）
    * - 每个 Agent / workspace 持有独立 Logger，绑定只影响当前实例。
    * - 落盘目录必须在实例初始化后明确指定。
-   * - 未绑定 project_root 时，只打印到 console，不写入 `.downcity/logs/*`。
+   * - 未绑定存储时，只打印到 console，不写入本地文件。
    */
   bind_project_root(project_root: string): void {
     const root = String(project_root || "").trim();
     this.workspace_files = root ? new LocalFileSystem(root) : null;
+    this.storage_root_path = root;
   }
 
-  /** 绑定现有 Workspace FileSystem，避免创建第二套文件入口。 */
-  bind_workspace(files: FileSystem): void {
+  /** 绑定 Agent 内部存储，避免日志写入项目目录。 */
+  bind_storage(
+    files: FileSystem,
+    storage_root_path: string,
+    owner?: {
+      /** 当前 Agent 的稳定标识。 */
+      agent_id: string;
+      /** 当前 Workspace 的稳定标识。 */
+      workspace_id: string;
+    },
+  ): void {
     this.workspace_files = files;
+    this.storage_root_path = String(storage_root_path || "").trim();
+    this.agent_id = String(owner?.agent_id || "").trim();
+    this.workspace_id = String(owner?.workspace_id || "").trim();
   }
 
   /**
@@ -274,11 +293,12 @@ export class Logger {
   ): Promise<void> {
     const entry: LogEntry = {
       id: this.generate_id(),
+      ...(this.agent_id ? { agent_id: this.agent_id } : {}),
+      ...(this.workspace_id ? { workspace_id: this.workspace_id } : {}),
       timestamp: get_timestamp(),
       type,
       message: normalizeToAllowedMessageLabels(message),
       details: normalizeLogDetails(details),
-      level: type,
     };
 
     this.logs.push(entry);
@@ -323,12 +343,12 @@ export class Logger {
 
   /**
    * 落盘算法（中文）
-   * - 日志按自然日分片：`.downcity/logs/YYYY-MM-DD.jsonl`。
+   * - 日志按自然日分片：`<workspace-data>/logs/YYYY-MM-DD.jsonl`。
    * - 每条日志一行 JSON，便于 grep / 流式消费。
    */
   private async saveToFile(entry: LogEntry): Promise<void> {
     if (!this.workspace_files) return;
-    const logsDir = get_logs_dir_path(this.workspace_files.root_path);
+    const logsDir = get_logs_dir_path(this.storage_root_path);
     const date = String(entry.timestamp || "").slice(0, 10) || new Date().toISOString().slice(0, 10);
     const logFile = this.workspace_files.resolve_path(logsDir, `${date}.jsonl`);
 
@@ -366,7 +386,8 @@ export class Logger {
  *
  * 说明（中文）
  * - 每次调用都返回独立实例，避免不同 Agent / workspace 互相覆盖落盘目录。
- * - 提供 project_root 时立即绑定日志目录；未提供时仅输出到 console。
+ * - 提供 project_root 时绑定项目目录（独立 Logger 用法）；Session
+ *   运行时应使用 `bind_storage` 将日志写入私有数据目录。
  */
 export function get_logger(project_root?: string, log_level?: string): Logger {
   const logger = new Logger(log_level);