@downcity/agent 1.1.287 → 1.1.310

package/src/types/session/SessionInteraction.ts

@@ -0,0 +1,209 @@
+/**
+ * Session 用户异步交互协议。
+ *
+ * Interaction 表示当前 Turn 在执行过程中需要用户参与。执行方发起请求后等待，
+ * Session 先持久化请求并通知客户端；客户端响应完成持久化后，原执行才会恢复。
+ */
+
+/** Interaction 当前生命周期状态。 */
+export type SessionInteractionStatus =
+  | "pending"
+  | "resolved"
+  | "expired"
+  | "cancelled";
+
+/** 高风险操作请求是否需要用户逐次确认。 */
+export type SessionApprovalMode = "ask" | "always-allow";
+
+/** Interaction 的执行来源。 */
+export type SessionInteractionSource =
+  | {
+      /** 来源固定为 Tool Call。 */
+      type: "tool";
+      /** 发起 Interaction 的稳定 Tool Call 标识。 */
+      tool_call_id: string;
+      /** 发起 Interaction 的工具注册名称。 */
+      tool_name: string;
+    }
+  | {
+      /** 来源为不绑定具体 Tool 的 Session 执行过程。 */
+      type: "execution";
+    };
+
+/** Interaction 请求公共字段。 */
+export interface SessionInteractionRequestBase {
+  /** 当前 Interaction 的稳定唯一标识。 */
+  interaction_id: string;
+  /** 当前 Interaction 所属 Turn 标识。 */
+  turn_id: string;
+  /** 当前 Interaction 的执行来源。 */
+  source: SessionInteractionSource;
+  /** 当前 Interaction 创建时间戳，单位为毫秒。 */
+  created_at: number;
+  /** 当前 Interaction 自动过期时间戳，省略表示不自动过期。 */
+  expires_at?: number;
+}
+
+/** 高风险操作审批请求。 */
+export interface SessionApprovalInteractionRequest
+  extends SessionInteractionRequestBase {
+  /** Interaction 类型固定为 approval。 */
+  kind: "approval";
+  /** 审批界面展示标题。 */
+  title: string;
+  /** 审批界面展示的可选补充说明。 */
+  description?: string;
+  /** 请求执行的命令或输入文本。 */
+  command: string;
+  /** 请求执行时使用的工作目录。 */
+  cwd: string;
+  /** 请求高权限操作的明确原因。 */
+  reason: string;
+  /** 当前审批对应的操作类别。 */
+  operation: "exec" | "start" | "write";
+}
+
+/** Question 支持的回答形式。 */
+export type SessionInteractionQuestionResponseType =
+  | "text"
+  | "single_select"
+  | "multi_select";
+
+/** Question 选择项。 */
+export interface SessionInteractionOption {
+  /** 当前选项在问题内的稳定值。 */
+  value: string;
+  /** 当前选项向用户展示的标签。 */
+  label: string;
+  /** 当前选项的可选解释。 */
+  description?: string;
+}
+
+/** 一条等待用户回答的问题。 */
+export interface SessionInteractionQuestion {
+  /** 当前问题在 Interaction 内的稳定标识。 */
+  question_id: string;
+  /** 向用户展示的完整问题文本。 */
+  prompt: string;
+  /** 当前问题要求的回答形式。 */
+  response_type: SessionInteractionQuestionResponseType;
+  /** 单选或多选问题允许选择的候选项。 */
+  options?: SessionInteractionOption[];
+}
+
+/** 向用户提问的 Interaction 请求。 */
+export interface SessionQuestionInteractionRequest
+  extends SessionInteractionRequestBase {
+  /** Interaction 类型固定为 question。 */
+  kind: "question";
+  /** 问题界面展示标题。 */
+  title: string;
+  /** 当前 Interaction 包含的一到多条问题。 */
+  questions: SessionInteractionQuestion[];
+}
+
+/** Session 支持的全部 Interaction 请求。 */
+export type SessionInteractionRequest =
+  | SessionApprovalInteractionRequest
+  | SessionQuestionInteractionRequest;
+
+/** Approval Interaction 的用户响应。 */
+export interface SessionApprovalInteractionResponse {
+  /** 响应类型固定为 approval。 */
+  kind: "approval";
+  /** 用户对高风险操作作出的最终决定。 */
+  decision: "approved" | "denied";
+}
+
+/** 单条 Question 回答。 */
+export interface SessionInteractionAnswer {
+  /** 当前回答对应的问题标识。 */
+  question_id: string;
+  /** 文本或单选回答值；多选回答使用字符串数组。 */
+  value: string | string[];
+}
+
+/** Question Interaction 的用户响应。 */
+export interface SessionQuestionInteractionResponse {
+  /** 响应类型固定为 question。 */
+  kind: "question";
+  /** 按 question_id 关联的完整回答集合。 */
+  answers: SessionInteractionAnswer[];
+}
+
+/** Session 支持的全部 Interaction 用户响应。 */
+export type SessionInteractionResponse =
+  | SessionApprovalInteractionResponse
+  | SessionQuestionInteractionResponse;
+
+/** 用户提交一次 Interaction 响应的公开输入。 */
+export interface RespondSessionInteractionInput {
+  /** 需要响应的 pending Interaction 标识。 */
+  interaction_id: string;
+  /** 与原请求 kind 一致的结构化响应。 */
+  response: SessionInteractionResponse;
+}
+
+/** Interaction 已成功收到用户响应。 */
+export interface SessionResolvedInteractionResult {
+  /** 终态固定为 resolved。 */
+  status: "resolved";
+  /** 已完成的 Interaction 标识。 */
+  interaction_id: string;
+  /** 已持久化的结构化用户响应。 */
+  response: SessionInteractionResponse;
+}
+
+/** Interaction 因等待超时结束。 */
+export interface SessionExpiredInteractionResult {
+  /** 终态固定为 expired。 */
+  status: "expired";
+  /** 已过期的 Interaction 标识。 */
+  interaction_id: string;
+}
+
+/** Interaction 因 Session 生命周期变化被取消。 */
+export interface SessionCancelledInteractionResult {
+  /** 终态固定为 cancelled。 */
+  status: "cancelled";
+  /** 已取消的 Interaction 标识。 */
+  interaction_id: string;
+  /** Interaction 被取消的稳定原因。 */
+  reason: "turn_stopped" | "session_disposed" | "runtime_interrupted";
+}
+
+/** Interaction 等待方最终收到的领域结果。 */
+export type SessionInteractionResult =
+  | SessionResolvedInteractionResult
+  | SessionExpiredInteractionResult
+  | SessionCancelledInteractionResult;
+
+/** 当前 Session 中一条 pending Interaction 的公开快照。 */
+export interface SessionPendingInteraction {
+  /** 已持久化的完整 Interaction 请求。 */
+  request: SessionInteractionRequest;
+}
+
+/** 执行方等待一次 Interaction 的运行时句柄。 */
+export interface SessionInteractionHandle {
+  /** 已成功持久化并等待响应的 Interaction 标识。 */
+  interaction_id: string;
+  /** Interaction 进入终态后兑现的领域结果。 */
+  result: Promise<SessionInteractionResult>;
+}
+
+/** 执行面请求用户异步参与的最小端口。 */
+export interface SessionInteractionPort {
+  /** 创建并持久化一次 Interaction，返回等待终态结果的句柄。 */
+  request(
+    request: SessionInteractionRequest,
+  ): Promise<SessionInteractionHandle>;
+}
+
+/** 控制面结束 Turn 时使用的 Interaction 生命周期端口。 */
+export interface SessionInteractionLifecycle {
+  /** 取消当前 Session 中全部 pending Interaction。 */
+  cancel_all(
+    reason: "turn_stopped" | "session_disposed" | "runtime_interrupted",
+  ): Promise<void>;
+}

package/src/types/session/SessionInteractions.ts

@@ -0,0 +1,21 @@
+/**
+ * SessionInteractions 运行时状态类型。
+ *
+ * 这里只描述内存中的等待句柄；Interaction 的权威状态始终保存在
+ * SessionMessages 的 Assistant Interaction Part 中。
+ */
+
+import type {
+  SessionInteractionRequest,
+  SessionInteractionResult,
+} from "@/types/session/SessionInteraction.js";
+
+/** 单个等待用户响应的运行时 Interaction。 */
+export interface SessionPendingInteractionRuntime {
+  /** 已经持久化的完整 Interaction 请求。 */
+  request: SessionInteractionRequest;
+  /** 兑现原执行等待 Promise 的回调。 */
+  resolve: (result: SessionInteractionResult) => void;
+  /** 自动过期计时器；没有 expires_at 时省略。 */
+  timer?: ReturnType<typeof setTimeout>;
+}

package/src/types/session/SessionLocalState.ts

@@ -43,7 +43,7 @@ export interface SessionLocalState {
   initialize_promise: Promise<void> | null;
 
   /**
-   * ensureReadyForExecution() 过程中的并发复用 Promise。
+   * ensure_ready_for_execution() 过程中的并发复用 Promise。
    */
   ensure_configured_promise: Promise<void> | null;
 }

package/src/types/session/SessionLoop.ts

@@ -0,0 +1,72 @@
+/**
+ * SessionLoop 构造参数与内部 Turn 状态类型。
+ *
+ * 这些类型描述 Turn 编排所依赖的领域对象，不实现任何调度行为。
+ */
+
+import type { ShellApprovalGateway } from "@downcity/shell";
+import type { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
+import type { SessionMessages } from "@/session/SessionMessages.js";
+import type { SessionState } from "@/session/SessionState.js";
+import type { AgentSessionTurnResult } from "@/types/sdk/AgentSessionTurn.js";
+import type {
+  SessionInteractionLifecycle,
+  SessionInteractionPort,
+} from "@/types/session/SessionInteraction.js";
+import type {
+  SessionCompactHistory,
+  SessionExecutor,
+} from "@/types/session/SessionExecution.js";
+import type { SessionQueue } from "@/session/SessionQueue.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+
+/** Promise 延迟控制器。 */
+export interface SessionDeferred<T> {
+  /** 等待兑现的 Promise。 */
+  promise: Promise<T>;
+  /** 兑现 Promise 的函数。 */
+  resolve: (value: T) => void;
+}
+
+/** 当前活跃 Turn 的内存状态。 */
+export interface ActiveSessionTurnState {
+  /** 当前 Turn 的稳定标识。 */
+  turn_id: string;
+  /** 当前 Turn 的最终结果快照。 */
+  result: AgentSessionTurnResult | null;
+  /** 当前 Turn 完成状态的延迟控制器。 */
+  deferred_finished: SessionDeferred<AgentSessionTurnResult>;
+  /** 当前 Turn 进入执行阶段后拥有的唯一上下文。 */
+  turn_context: SessionTurnContext | null;
+  /** 下一 Step 是否需要重新读取 canonical history。 */
+  history_reload_requested: boolean;
+  /** 当前 Turn 是否已经接收并持久化首条 Prompt。 */
+  prompt_started: boolean;
+}
+
+/** SessionLoop 构造参数。 */
+export interface SessionLoopOptions {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Session 所属 Workspace 的绝对根目录。 */
+  workspace_path: string;
+  /** 当前 Session 的模型执行器。 */
+  executor: SessionExecutor;
+  /** 由 Session 领域提供的 canonical 历史压缩入口。 */
+  compact_history: SessionCompactHistory;
+  /** 当前 Session 的配置与 Metadata 状态。 */
+  state: SessionState;
+  /** 当前 Session 的 canonical Message 入口。 */
+  messages: SessionMessages;
+  /** 当前 Session 的 Mutation 总线。 */
+  events: SessionEventHub;
+  /** 当前 Session 的统一日志器。 */
+  logger: Logger;
+  /** 当前 Session 拥有的有序 Command 队列。 */
+  queue: SessionQueue;
+  /** 当前 Session 的用户异步交互运行时。 */
+  interactions: SessionInteractionLifecycle & SessionInteractionPort;
+  /** Shell 高风险操作使用的协议适配器。 */
+  shell_approval_gateway: ShellApprovalGateway;
+}

package/src/types/session/SessionMessage.ts

@@ -5,9 +5,15 @@
  * 均为内部 part，不提升为顶层消息。
  */
 
-import type { ProviderMetadata } from "ai";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { SessionApproval } from "@/types/session/SessionApproval.js";
+import type {
+  SessionInteractionRequest,
+  SessionInteractionResponse,
+  SessionInteractionStatus,
+} from "@/types/session/SessionInteraction.js";
+
+/** Session 持久化的 Provider metadata 映射。 */
+export type SessionProviderMetadata = Record<string, JsonObject>;
 
 /** Message 默认展示范围。 */
 export type SessionMessageVisibility = "visible" | "internal";
@@ -55,7 +61,7 @@ export interface SessionUserTextPart {
   /** User 文本已经完整，不参与流式更新。 */
   state: "done";
   /** AI SDK User text part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: ProviderMetadata;
+  provider_metadata?: SessionProviderMetadata;
 }
 
 /** User 文件 part。 */
@@ -71,7 +77,7 @@ export interface SessionUserFilePart {
   /** 可选原始文件名。 */
   filename?: string;
   /** AI SDK User file part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: ProviderMetadata;
+  provider_metadata?: SessionProviderMetadata;
 }
 
 /** User 结构化数据 part。 */
@@ -117,19 +123,7 @@ export interface SessionAssistantTextPart {
   /** 文本 part 是否已经结束。 */
   state: "streaming" | "done";
   /** AI SDK text / reasoning part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: ProviderMetadata;
-}
-
-/** Tool approval 在 UIMessage 中的完整语义快照。 */
-export interface SessionToolApprovalSnapshot {
-  /** AI SDK approval request 的稳定标识。 */
-  approval_id: string;
-  /** 已经作出决定时记录是否批准；等待决定时省略。 */
-  approved?: boolean;
-  /** Provider 或用户给出的可选决定原因。 */
-  reason?: string;
-  /** Downcity 本地审批运行时的完整请求；仅本地工具审批存在。 */
-  request?: SessionApproval;
+  provider_metadata?: SessionProviderMetadata;
 }
 
 /** Assistant 工具 part。 */
@@ -145,7 +139,7 @@ export interface SessionAssistantToolPart {
   /** 工具注册名称。 */
   tool_name: string;
   /** 工具当前生命周期状态。 */
-  state: "input-streaming" | "ready" | "approval-required" | "running" | "completed" | "failed";
+  state: "input-streaming" | "ready" | "waiting-user" | "running" | "completed" | "failed";
   /** 流式接收中的参数原文。 */
   input_text?: string;
   /** 收敛后的结构化输入。 */
@@ -165,13 +159,35 @@ export interface SessionAssistantToolPart {
   /** 当前工具结果是否只是后续会被替换的临时结果。 */
   preliminary?: boolean;
   /** 工具调用阶段由 AI SDK Provider 返回的可序列化 metadata。 */
-  call_provider_metadata?: ProviderMetadata;
+  call_provider_metadata?: SessionProviderMetadata;
   /** 工具结果阶段由 AI SDK Provider 返回的可序列化 metadata。 */
-  result_provider_metadata?: ProviderMetadata;
+  result_provider_metadata?: SessionProviderMetadata;
   /** 当前工具是否由模型 Provider 直接执行。 */
   provider_executed?: boolean;
-  /** 当前 Tool 等待或已经处理过的完整审批语义。 */
-  approval?: SessionToolApprovalSnapshot;
+}
+
+/** Assistant 用户异步交互 part。 */
+export interface SessionAssistantInteractionPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** Assistant Part 在当前 Message 中的不可变线性顺序，从 1 开始。 */
+  sequence: number;
+  /** part 类型固定为 interaction。 */
+  type: "interaction";
+  /** 当前 Interaction 的稳定唯一标识。 */
+  interaction_id: string;
+  /** 当前 Interaction 的具体业务类型。 */
+  interaction_type: "approval" | "question";
+  /** 当前 Interaction 的生命周期状态。 */
+  status: SessionInteractionStatus;
+  /** 已持久化的完整 Interaction 请求。 */
+  request: SessionInteractionRequest;
+  /** 用户已响应时保存的结构化响应。 */
+  response?: SessionInteractionResponse;
+  /** Interaction 进入终态的时间戳，单位为毫秒。 */
+  resolved_at?: number;
+  /** Interaction 被取消时保存的稳定原因。 */
+  cancel_reason?: "turn_stopped" | "session_disposed" | "runtime_interrupted";
 }
 
 /** Assistant 文件 part。 */
@@ -189,7 +205,7 @@ export interface SessionAssistantFilePart {
   /** 可选原始文件名。 */
   filename?: string;
   /** AI SDK Assistant file part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: ProviderMetadata;
+  provider_metadata?: SessionProviderMetadata;
 }
 
 /** Assistant 结构化数据 part。 */
@@ -225,7 +241,7 @@ export interface SessionAssistantUrlSourcePart {
   /** source 的可选展示标题。 */
   title?: string;
   /** AI SDK source part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: ProviderMetadata;
+  provider_metadata?: SessionProviderMetadata;
 }
 
 /** Assistant document source part。 */
@@ -247,7 +263,7 @@ export interface SessionAssistantDocumentSourcePart {
   /** document source 的可选文件名。 */
   filename?: string;
   /** AI SDK source part 携带的可序列化 Provider metadata。 */
-  provider_metadata?: ProviderMetadata;
+  provider_metadata?: SessionProviderMetadata;
 }
 
 /** Assistant source part。 */
@@ -269,6 +285,7 @@ export interface SessionAssistantStepPart {
 export type SessionAssistantMessagePart =
   | SessionAssistantTextPart
   | SessionAssistantToolPart
+  | SessionAssistantInteractionPart
   | SessionAssistantFilePart
   | SessionAssistantDataPart
   | SessionAssistantSourcePart
@@ -278,10 +295,8 @@ export type SessionAssistantMessagePart =
 export interface SessionAssistantMessage extends SessionMessageBase {
   /** Message 类型固定为 assistant。 */
   type: "assistant";
-  /** 普通 assistant segment 或内部 compact summary。 */
+  /** 普通 Assistant 回复或内部 compact summary。 */
   kind: "normal" | "summary";
-  /** Assistant 在所属 turn 内的 segment 序号，从一开始。 */
-  segment_index: number;
   /** Assistant 当前执行状态。 */
   status: "streaming" | "completed" | "stopped" | "failed";
   /** Assistant 内按真实生成顺序保存的 parts。 */

package/src/types/session/SessionMessages.ts

@@ -6,7 +6,7 @@
 
 import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
-import type { JsonlSessionMessageStore } from "@/session/messages/JsonlSessionMessageStore.js";
+import type { SessionMessageStore } from "@/types/store/SessionStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   SessionAssistantMessagePart,
@@ -19,7 +19,7 @@ export interface SessionMessagesOptions {
   /** 当前 Session 标识。 */
   session_id: string;
   /** Message 快照持久化 Store。 */
-  store: JsonlSessionMessageStore;
+  store: SessionMessageStore;
   /** 持久化成功后的实时 Mutation 发布函数。 */
   publish: (mutation: SessionMutation) => void;
 }
@@ -42,8 +42,6 @@ export interface AppendSessionUserMessageInput {
 export interface OpenSessionAssistantMessageInput {
   /** 当前 Assistant 所属 Turn。 */
   turn_id: string;
-  /** 当前 Assistant 在 Turn 内的 Segment 序号。 */
-  segment_index: number;
   /** 当前 Assistant 是普通回复还是压缩 Summary。 */
   kind?: "normal" | "summary";
   /** 当前 Message 的默认展示范围。 */

package/src/types/session/SessionMutation.ts

@@ -5,6 +5,7 @@
  */
 
 import type { SessionAssistantMessagePart, SessionMessage } from "@/types/session/SessionMessage.js";
+import type { AgentSessionCompactReason } from "@/types/sdk/AgentSessionCompact.js";
 
 /** 所有 Session Mutation 的公共字段。 */
 export interface SessionMutationBase {
@@ -89,6 +90,24 @@ export type SessionTurnMutation = SessionMutationBase & {
   error?: string;
 };
 
+/** 显式 Session 压缩请求的生命周期 Mutation。 */
+export type SessionCompactMutation = SessionMutationBase & {
+  /** Mutation 层级固定为 compact。 */
+  variant: "compact";
+  /** 当前压缩请求是进入队列还是已经结束。 */
+  type: "start" | "finish";
+  /** 当前显式压缩请求的稳定标识。 */
+  compact_id: string;
+  /** 当前压缩请求的生命周期状态。 */
+  status: "queued" | "completed" | "failed";
+  /** 完成时是否实际提交了压缩计划。 */
+  compacted?: boolean;
+  /** 完成时的稳定结束原因。 */
+  reason?: AgentSessionCompactReason;
+  /** 压缩失败时的错误文本。 */
+  error?: string;
+};
+
 /** Session 自身属性变化 Mutation。 */
 export type SessionStateMutation = SessionMutationBase & {
   /** Mutation 层级固定为 session。 */
@@ -105,6 +124,7 @@ export type SessionMutation =
   | SessionPartMutation
   | SessionDeltaMutation
   | SessionTurnMutation
+  | SessionCompactMutation
   | SessionStateMutation;
 
 /** Session Mutation 订阅回调。 */
@@ -125,6 +145,7 @@ export function is_session_mutation(input: unknown): input is SessionMutation {
     candidate.variant === "part" ||
     candidate.variant === "delta" ||
     candidate.variant === "turn" ||
+    candidate.variant === "compact" ||
     candidate.variant === "session"
   );
 }

package/src/types/session/SessionOptions.ts

@@ -13,9 +13,9 @@ import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
-import type { AgentSessionCommand } from "@/types/session/SessionQueue.js";
 import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import type { Logger } from "@/utils/logger/Logger.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
 
 /**
  * Agent 可管理的本地 Session 实例。
@@ -29,19 +29,30 @@ export interface AgentManagedSession extends AgentSession {
   /**
    * 返回供 plugin/runtime 使用的 session 端口。
    */
-  getRuntimePort(): SessionPort;
+  get_runtime_port(): SessionPort;
 
   /**
    * 返回当前 session 是否正在执行。
    */
-  isExecuting(): boolean;
-
-  /**
-   * 把 Agent configured state command 加入当前 Session 的统一输入队列。
-   */
-  enqueue_agent_command(
-    command: AgentSessionCommand,
-  ): void;
+  is_executing(): boolean;
+
+  /** 把 Workspace env 快照加入当前 Session 的有序输入队列。 */
+  enqueue_workspace_env(input: {
+    /** 当前 Workspace env 修改的稳定标识。 */
+    command_id: string;
+    /** 下一 Session Step 使用的完整环境变量快照。 */
+    env: Record<string, string>;
+  }): void;
+
+  /** 把 Agent Plugin 执行视图加入当前 Session 的有序输入队列。 */
+  enqueue_agent_plugins(input: {
+    /** 当前 Plugin 修改的稳定标识。 */
+    command_id: string;
+    /** 当前 Plugin 修改的用户可读标题。 */
+    title: string;
+    /** 下一 Session Step 使用的 Plugin 执行视图。 */
+    plugins: AgentPluginExecutionRuntime;
+  }): void;
 }
 
 /**
@@ -51,17 +62,21 @@ export interface SessionOptions {
   /**
    * 当前 agent 稳定标识。
    */
-  agentId: string;
+  agent_id: string;
 
-  /**
-   * 当前项目根目录。
-   */
-  projectRoot: string;
+  /** 当前 Session 所属 Workspace 的绝对根目录。 */
+  workspace_path: string;
+
+  /** 当前 Session 独享的领域持久化视图。 */
+  store: SessionStore;
+
+  /** 为 fork 创建另一个 Session 的领域持久化视图。 */
+  get_session_store: (session_id: string) => SessionStore;
 
   /**
-   * 当前 sessionId。
+   * 当前 session_id。
    */
-  sessionId: string;
+  session_id: string;
 
   /**
    * 当前 agent 默认工具集合。
@@ -92,13 +107,13 @@ export interface SessionOptions {
   get_instruction_system_blocks: () => AgentSessionSystemBlock[];
 
   /**
-   * 读取当前 Agent configured env。
+   * 读取当前 Workspace configured env。
    *
    * 关键点（中文）
    * - Session 创建时用它建立初始 effective env。
-   * - 后续 Agent env 修改通过 Session command 在 step 检查点执行。
+   * - 后续 Workspace env 修改通过 Session command 在 step 检查点执行。
    */
-  getAgentEnv: () => Record<string, string>;
+  get_workspace_env: () => Record<string, string>;
 
   /** 创建当前 Agent configured plugin 的 Session step 执行视图。 */
   get_agent_plugins: () => AgentPluginExecutionRuntime;
@@ -106,15 +121,15 @@ export interface SessionOptions {
   /**
    * 读取当前 agent 显式注入的受托管 plugin system blocks。
    */
-  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+  get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
    * 在执行前确保当前 session 已完成宿主侧默认配置。
    */
-  ensureConfigured?: (session: AgentManagedSession) => Promise<void>;
+  ensure_configured?: (session: AgentManagedSession) => Promise<void>;
 
   /** 读取 Agent 当前持有的运行时模型实例。 */
-  getAgentModel: () => AgentModel | undefined;
+  get_agent_model: () => AgentModel | undefined;
 
   /** 当前 Session 使用的统一执行策略；省略时使用默认 Composer。 */
   composer?: SessionComposer;