@downcity/agent 1.1.445 → 1.5.0

package/src/session/loop/SessionLoop.ts

@@ -70,7 +70,8 @@ const QUEUED_PROMPT_CANCELLED_MESSAGE =
 export class SessionLoop {
   private readonly session_id: string;
   private readonly session_origin: SessionLoopOptions["session_origin"];
-  private readonly workspace_path: string;
+  /** 当前 Session 的目录解析器。 */
+  private readonly get_workspace_path: SessionLoopOptions["get_workspace_path"];
   private readonly step_input: StepInput | null;
   private readonly session_executor: SessionExecutorPort;
   private readonly maintain_context: SessionLoopOptions["maintain_context"];
@@ -93,7 +94,7 @@ export class SessionLoop {
   constructor(options: SessionLoopOptions) {
     this.session_id = String(options.session_id || "").trim();
     this.session_origin = options.session_origin;
-    this.workspace_path = String(options.workspace_path || "").trim();
+    this.get_workspace_path = options.get_workspace_path;
     this.maintain_context = options.maintain_context;
     this.state = options.state;
     this.messages = options.messages;
@@ -106,9 +107,6 @@ export class SessionLoop {
     if (!this.session_id) {
       throw new Error("SessionLoop requires a non-empty session_id");
     }
-    if (!this.workspace_path) {
-      throw new Error("SessionLoop requires a non-empty workspace_path");
-    }
     this.step_input = options.step_input ?? null;
     this.session_executor = options.executor ??
       new SessionExecutor({
@@ -535,7 +533,7 @@ export class SessionLoop {
     await append_session_turn_file_diff({
       session_id: this.session_id,
       turn_id: input.active_turn.turn_id,
-      workspace_path: this.workspace_path,
+      workspace_path: this.get_workspace_path(),
       turn_context,
       assistant_output,
       logger: this.logger,
@@ -608,7 +606,7 @@ export class SessionLoop {
       turn_id: active_turn.turn_id,
       session_id: this.session_id,
       session_origin: this.session_origin,
-      project_root: this.workspace_path,
+      project_root: this.get_workspace_path(),
       commit_step_input: async () => {
         const had_pending_prompt = this.has_pending_prompt();
         await this.drain_queued_inputs();
@@ -630,7 +628,7 @@ export class SessionLoop {
         publish_session_turn_file_diff({
           session_id: this.session_id,
           turn_id: active_turn.turn_id,
-          workspace_path: this.workspace_path,
+          workspace_path: this.get_workspace_path(),
           effects,
           publish: (mutation) => this.events.publish(mutation),
           logger: this.logger,
@@ -656,7 +654,7 @@ export class SessionLoop {
     message_id?: string,
   ): Promise<SessionUserMessage> {
     const message = await this.messages.append_prompt_message({
-      project_root: this.workspace_path,
+      project_root: this.get_workspace_path(),
       prompt,
       turn_id,
       ...(message_id ? { message_id } : {}),

package/src/session/loop/SessionState.ts

@@ -28,13 +28,21 @@ import type { SessionStateOptions } from "@/types/session/SessionState.js";
 import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import type { SessionApprovalMode } from "@downcity/type";
 import { create_session_model_request_warning } from "@/session/messages/SessionModelRequestWarning.js";
+import type { WorkspaceRuntime } from "@downcity/type";
 
 /** 创建单个 Session 唯一的可变内存状态。 */
-export function create_session_local_state(): SessionLocalState {
+export function create_session_local_state(input: {
+  /** Session 创建时的初始 Workspace；省略表示没有项目上下文。 */
+  workspace?: WorkspaceRuntime;
+  /** 没有 Workspace 时使用的目录回退值。 */
+  fallback_workspace_path: string;
+}): SessionLocalState {
   return {
     session_config: {},
     effective_session_config: {},
     configured_approval_mode: "ask",
+    ...(input.workspace ? { current_workspace: input.workspace } : {}),
+    fallback_workspace_path: input.fallback_workspace_path,
     created_at: Date.now(),
     timezone: resolve_system_timezone(),
     initialize_promise: null,
@@ -129,6 +137,11 @@ export class SessionState {
         });
         this.state.created_at = created_at;
         this.state.timezone = timezone;
+        this.state.updated_at =
+          typeof metadata.updated_at === "number" && metadata.updated_at > 0
+            ? metadata.updated_at
+            : undefined;
+        this.state.title = normalize_session_title(metadata.title);
         this.state.session_config = {
           ...(metadata.model_label ? { model_label: metadata.model_label } : {}),
         };
@@ -188,8 +201,10 @@ export class SessionState {
           ...(next_model_label ? { model_label: next_model_label } : {}),
         });
       });
+      this.state.updated_at = Date.now();
     }
     this.state.session_config = next_config;
+    this.state.updated_at = Date.now();
     return { config: next_config, changed };
   }
 
@@ -226,6 +241,8 @@ export class SessionState {
       return true;
     });
     if (changed) {
+      this.state.title = title;
+      this.state.updated_at = Date.now();
       this.publish_event({
         mutation_id: generate_id(),
         variant: "session",
@@ -238,6 +255,49 @@ export class SessionState {
     return title;
   }
 
+  /**
+   * 写入当前目录，并同步内存实例。
+   *
+   * 关键点（中文）
+   * - 这是 `session.set({ workspace })` 的内部实现，不对 Session 用户单独暴露写入口。
+   * - 以持久化值为比较基准：即使内存已持有同一实例，只要元数据不同就补写，
+   *   保证恢复时传入的目录真的落盘。
+   * - 传空值表示脱离项目上下文。
+   */
+  async apply_workspace(workspace?: WorkspaceRuntime): Promise<boolean> {
+    const next_workspace_id = String(workspace?.id || "").trim() || undefined;
+    const changed = await this.run_metadata_mutation(async () => {
+      const metadata = await this.store.read_metadata();
+      const current_workspace_id = String(metadata.workspace_id || "").trim() || undefined;
+      if (current_workspace_id === next_workspace_id) return false;
+      const { workspace_id: _previous_workspace_id, ...rest } = metadata;
+      await this.store.write_metadata({
+        ...rest,
+        agent_id: this.agent_id,
+        updated_at: Date.now(),
+        ...(next_workspace_id ? { workspace_id: next_workspace_id } : {}),
+      });
+      return true;
+    });
+    if (workspace) {
+      this.state.current_workspace = workspace;
+    } else {
+      delete this.state.current_workspace;
+    }
+    return changed;
+  }
+
+  /** 返回当前 Session 正在使用的 Workspace；没有项目上下文时为空。 */
+  get_workspace_instance(): WorkspaceRuntime | undefined {
+    return this.state.current_workspace;
+  }
+
+  /** 返回当前目录路径；没有 Workspace 时使用回退值。 */
+  get_workspace_path(): string {
+    return String(this.state.current_workspace?.path || "").trim()
+      || this.state.fallback_workspace_path;
+  }
+
   /** 在 Session Step 检查点提交模型配置。 */
   apply_model_config(config: AgentSessionConfigSnapshot): void {
     this.state.effective_session_config = {

package/src/session/storage/Browse.ts

@@ -23,6 +23,7 @@ import {
 import {
   normalize_session_origin_type,
   restore_session_origin,
+  SESSION_ORIGIN_TYPE_WORK,
   type FileSystem,
   type SessionMessage,
 } from "@downcity/type";
@@ -219,7 +220,7 @@ async function list_session_summary_page(input: {
   /** 是否扫描归档目录。 */
   archived: boolean;
 }): Promise<AgentSessionSummaryPage> {
-  const origin_type = normalize_session_origin_type(input.input?.origin_type ?? "chat");
+  const origin_type = normalize_session_origin_type(input.input?.origin_type ?? SESSION_ORIGIN_TYPE_WORK);
   const sessions_path = input.archived
     ? get_agent_archived_sessions_path(input.project_root, origin_type)
     : get_agent_sessions_path(input.project_root, origin_type);

package/src/session/storage/LocalSessionStore.ts

@@ -37,7 +37,7 @@ import {
 import type { FileSystem } from "@downcity/type";
 import type { LocalSessionStoreOptions } from "@/types/store/LocalStore.js";
 import type { SessionOrigin } from "@downcity/type";
-import { normalize_session_origin, normalize_session_origin_type } from "@downcity/type";
+import { normalize_session_origin, normalize_session_origin_type, SESSION_ORIGIN_TYPE_WORK } from "@downcity/type";
 
 /** 解码目录中经过 URL 编码的 Session 标识。 */
 function decode_session_id(input: string): string {
@@ -113,7 +113,7 @@ export class LocalSessionStore implements SessionStore {
   }
 
   /** 打开已有 Session，并以数据库中的完整 origin 作为唯一事实。 */
-  async open_session(session_id: string, origin_type = "chat"): Promise<SessionStorage> {
+  async open_session(session_id: string, origin_type = SESSION_ORIGIN_TYPE_WORK): Promise<SessionStorage> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
       throw new Error("SessionStore.open_session requires a non-empty session_id");
@@ -151,7 +151,7 @@ export class LocalSessionStore implements SessionStore {
   }
 
   /** 判断活动 Session 是否存在。 */
-  async has_session(session_id: string, origin_type = "chat"): Promise<boolean> {
+  async has_session(session_id: string, origin_type = SESSION_ORIGIN_TYPE_WORK): Promise<boolean> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
     const cache_key = this.session_cache_key(session_id, resolved_origin_type);
     if (this.database_location.type === "memory") return this.sessions.has(cache_key);
@@ -166,7 +166,7 @@ export class LocalSessionStore implements SessionStore {
   }
 
   /** 永久删除活动 Session。 */
-  async remove_session(session_id: string, origin_type = "chat"): Promise<boolean> {
+  async remove_session(session_id: string, origin_type = SESSION_ORIGIN_TYPE_WORK): Promise<boolean> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
     const session_path = this.session_path(session_id, resolved_origin_type);
     const cache_key = this.session_cache_key(session_id, resolved_origin_type);
@@ -188,7 +188,7 @@ export class LocalSessionStore implements SessionStore {
   }
 
   /** 清空活动 Session Message 数据。 */
-  async clear_session_messages(session_id: string, origin_type = "chat"): Promise<boolean> {
+  async clear_session_messages(session_id: string, origin_type = SESSION_ORIGIN_TYPE_WORK): Promise<boolean> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
     if (!(await this.has_session(session_id, resolved_origin_type))) return false;
     const storage = await this.open_session(session_id, resolved_origin_type);
@@ -215,7 +215,7 @@ export class LocalSessionStore implements SessionStore {
   }
 
   /** 将活动 Session 迁入归档区。 */
-  async archive_session(session_id: string, origin_type = "chat"): Promise<AgentArchiveSessionResult> {
+  async archive_session(session_id: string, origin_type = SESSION_ORIGIN_TYPE_WORK): Promise<AgentArchiveSessionResult> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
     const cache_key = this.session_cache_key(session_id, resolved_origin_type);
     if (this.database_location.type === "memory") {
@@ -372,7 +372,7 @@ export class LocalSessionStore implements SessionStore {
     executing_session_ids: ReadonlySet<string>,
     storages = this.sessions,
   ): Promise<AgentSessionSummaryPage> {
-    const origin_type = normalize_session_origin_type(input?.origin_type ?? "chat");
+    const origin_type = normalize_session_origin_type(input?.origin_type ?? SESSION_ORIGIN_TYPE_WORK);
     const query = String(input?.query || "").trim().toLowerCase();
     const summaries: AgentSessionSummary[] = [];
     for (const storage of storages.values()) {

package/src/tools/session/SessionToolSchemas.ts

@@ -0,0 +1,61 @@
+/**
+ * Agent 会话可用的 Session 工具输入 Schema。
+ *
+ * 职责说明（中文）
+ * - 四个工具都围绕「Agent 自己手上的会话」：开一条、看状态、代答、收回。
+ * - Schema 在模型输入边界完成校验，非法输入不会变成待处理状态。
+ */
+
+import { z } from "zod";
+
+/** `session_start` 输入：开一条会话并交给它任务。 */
+export const session_start_input = z
+  .object({
+    query: z.string().trim().min(1).describe(
+      "The task handed to the new session. Write it as a complete instruction: the new session only sees this text.",
+    ),
+    title: z.string().trim().min(1).optional().describe(
+      "Optional short title for this piece of work, used when listing sessions.",
+    ),
+  })
+  .strict();
+
+/** `session_check` 输入：列出全部会话，或读取其中一条。 */
+export const session_check_input = z
+  .object({
+    session_id: z.string().trim().min(1).optional().describe(
+      "Read one session in detail. Omit to list every session of this agent and their current state.",
+    ),
+    limit: z.number().int().min(1).max(100).optional().describe(
+      "Maximum sessions or messages to return. Defaults to 20.",
+    ),
+  })
+  .strict();
+
+/** `session_reply` 输入：代答某条会话正在等待的用户响应。 */
+export const session_reply_input = z
+  .object({
+    session_id: z.string().trim().min(1).describe(
+      "The session that raised the pending interaction.",
+    ),
+    interaction_id: z.string().trim().min(1).describe(
+      "Pending interaction id, as returned by session_check.",
+    ),
+    outcome: z.enum(["resolved", "denied"]).describe(
+      "resolved approves or answers; denied rejects the operation.",
+    ),
+    payload: z.record(z.string(), z.unknown()).optional().describe(
+      "Business response body for this interaction type. Question interactions require answers; approval interactions accept a decision.",
+    ),
+    note: z.string().trim().min(1).optional().describe(
+      "Optional human-readable explanation passed along with the response.",
+    ),
+  })
+  .strict();
+
+/** `session_stop` 输入：收回某条会话。 */
+export const session_stop_input = z
+  .object({
+    session_id: z.string().trim().min(1).describe("The session to stop."),
+  })
+  .strict();

package/src/tools/session/SessionTools.ts

@@ -0,0 +1,170 @@
+/**
+ * Agent 会话的 Session 工具。
+ *
+ * 职责说明（中文）
+ * - 把「Agent 手上的会话」变成模型可调用的四个动作：开一条、看状态、代答、收回。
+ * - 工具与 Agent 会话的工作运行时（{@link SessionWork}）解耦：运行时由 Agent 在装配时注入，
+ *   工具只调用协议，不接触 AgentSessions 或 Session 内部结构。
+ * - 工具自带 description 与返回值说明，因此不需要向 instruction 注入额外文本。
+ *
+ * 关键点（中文）
+ * - 这组工具只注册在 `origin.type === "agent"` 的会话上下文里；其他 Session 拿不到，所以不会递归派发。
+ */
+
+import {
+  define_agent_tool,
+  type ActionResult,
+  type JsonValue,
+  type ToolCallContext,
+} from "@downcity/type";
+import type { SessionWorkContract } from "@/types/agent/SessionWork.js";
+import type {
+  SessionCheckToolOutput,
+  SessionReplyToolOutput,
+  SessionStartToolOutput,
+  SessionStopToolOutput,
+} from "@/types/tools/session/SessionTools.js";
+import {
+  session_check_input,
+  session_reply_input,
+  session_start_input,
+  session_stop_input,
+} from "@/tools/session/SessionToolSchemas.js";
+
+/** `session_start` 的输入。 */
+type SessionStartInput = { query: string; title?: string };
+
+/** `session_check` 的输入。 */
+type SessionCheckInput = { session_id?: string; limit?: number };
+
+/** `session_reply` 的输入。 */
+type SessionReplyInput = {
+  session_id: string;
+  interaction_id: string;
+  outcome: "resolved" | "denied";
+  payload?: Record<string, unknown>;
+  note?: string;
+};
+
+/** `session_stop` 的输入。 */
+type SessionStopInput = { session_id: string };
+
+/** 会话工具集；由 Agent 在 Agent 会话上下文中注入。 */
+export type ChatSessionToolSet = ReturnType<typeof create_session_tools>;
+
+/**
+ * 创建 Agent 会话的四个会话工具。
+ *
+ * 关键点（中文）
+ * - 每个工具都没有附加 messages：会话状态通过工具结果返回，不追加到对话 canonical 消息。
+ */
+export function create_session_tools(work: SessionWorkContract) {
+  const session_start = define_agent_tool<SessionStartInput, ActionResult<SessionStartToolOutput>>({
+    description:
+      "Start a new session to carry out one piece of work, then return immediately. Use it when a request is larger than one reply: the user keeps talking with you while the work runs elsewhere. Write the query as a complete instruction, because the new session only sees that text.",
+    input_schema: session_start_input,
+    execute: async (input, context): Promise<ActionResult<SessionStartToolOutput>> => {
+      // 新会话继承当前对话的目录：用户说的「顺便」通常仍指同一个项目。
+      const result = await work.spawn({
+        ...input,
+        ...(context.workspace ? { workspace: context.workspace } : {}),
+      });
+      return {
+        output: { session_id: result.session_id, status: "started" },
+        messages: [],
+      };
+    },
+  });
+
+  const session_check = define_agent_tool<SessionCheckInput, ActionResult<SessionCheckToolOutput>>({
+    description:
+      "List the sessions you have started and what each one is doing, or pass session_id to read one session's recent messages and pending user interactions. Call this before answering questions about progress; never guess a session's state.",
+    input_schema: session_check_input,
+    execute: async (input): Promise<ActionResult<SessionCheckToolOutput>> => {
+      const session_id = String(input.session_id || "").trim();
+      if (!session_id) {
+        return {
+          output: { mode: "list", sessions: await work.list({ limit: input.limit }) },
+          messages: [],
+        };
+      }
+      return {
+        output: await work.read({ session_id, limit: input.limit }),
+        messages: [],
+      };
+    },
+  });
+
+  const session_reply = define_agent_tool<SessionReplyInput, ActionResult<SessionReplyToolOutput>>({
+    description:
+      "Answer a pending interaction on another session without the user leaving this conversation. Call session_check first to get the interaction_id, and translate the user's own words into the response payload. Use it only for interactions that are genuinely waiting.",
+    input_schema: session_reply_input,
+    execute: async (input): Promise<ActionResult<SessionReplyToolOutput>> => {
+      // 响应载荷必须是可以序列化的 JSON，这里逐项收紧类型后再交给 Interaction 协议。
+      const payload: Record<string, JsonValue> = {};
+      for (const [key, value] of Object.entries(input.payload ?? {})) {
+        payload[key] = value as JsonValue;
+      }
+      if (input.note) payload.note = input.note;
+      await work.reply({
+        session_id: input.session_id,
+        interaction_id: input.interaction_id,
+        response: {
+          type: await resolve_interaction_type(work, input.session_id, input.interaction_id),
+          outcome: input.outcome,
+          payload,
+        },
+      });
+      return {
+        output: {
+          status: input.outcome,
+          session_id: input.session_id,
+          interaction_id: input.interaction_id,
+        },
+        messages: [],
+      };
+    },
+  });
+
+  const session_stop = define_agent_tool<SessionStopInput, ActionResult<SessionStopToolOutput>>({
+    description:
+      "Stop the work running on another session, for example when the user changes their mind. The session is recorded as stopped rather than failed.",
+    input_schema: session_stop_input,
+    execute: async (input): Promise<ActionResult<SessionStopToolOutput>> => {
+      await work.stop({ session_id: input.session_id });
+      return {
+        output: { session_id: input.session_id, status: "stopped" },
+        messages: [],
+      };
+    },
+  });
+
+  return { session_start, session_check, session_reply, session_stop };
+}
+
+/**
+ * 读取待响应 Interaction 的业务类型。
+ *
+ * 关键点（中文）：响应必须与原请求 type 一致，这是 Interaction 协议的硬约束；
+ * 由这里从权威状态读出，避免让模型重复转述而写错。
+ */
+async function resolve_interaction_type(
+  work: SessionWorkContract,
+  session_id: string,
+  interaction_id: string,
+): Promise<string> {
+  const detail = await work.read({ session_id, limit: 1 });
+  const pending = detail.pending_interactions.find(
+    (interaction) => interaction.interaction_id === interaction_id,
+  );
+  if (!pending) {
+    throw new Error(`Interaction is not pending on session "${session_id}": ${interaction_id}`);
+  }
+  return pending.type;
+}
+
+/** 供 Agent 装配使用：把工具集暴露为普通 Tool 记录。 */
+export type ChatSessionTools = ReturnType<typeof create_session_tools>;
+
+/** 工具调用上下文类型再导出，便于宿主实现自定义会话工具时对齐。 */
+export type ChatSessionToolContext = ToolCallContext;

package/src/types/agent/AgentOptions.ts

@@ -6,7 +6,8 @@
  * - RemoteAgent 与 Session 数据结构拆到独立类型文件。
  */
 
-import type { ModelClient, AgentTool as Tool, ToolHookSet } from "@downcity/type";
+import type { ModelClient, AgentTool as Tool, ToolHookSet, WorkspaceRuntime } from "@downcity/type";
+
 import type {
   AgentManagedSession,
   SessionOptions,
@@ -88,6 +89,16 @@ export interface AgentOptions {
    */
   model?: ModelClient;
 
+  /**
+   * 新建 Session 时注入的默认目录。
+   *
+   * 关键点（中文）
+   * - 它是宿主在构造 Agent 时声明的默认值，不是绑定；单个 Session 可用 `set({ workspace })` 换掉。
+   * - 它不参与恢复：历史会话的目录由宿主在 `get()` 时注入。
+   * - 省略时新建的 Session 没有项目上下文：没有文件工具与 Shell，纯模型对话仍可用。
+   */
+  workspace?: WorkspaceRuntime;
+
   /**
    * 当前 agent 使用的本地 Session 类。
    *

package/src/types/agent/AgentSessionCollection.ts

@@ -1,7 +1,7 @@
 /**
  * Agent 面向 SDK 用户的 Session 集合类型。
  *
- * Session 归 Agent 所有；Workspace 只在创建时声明本次执行使用的资源环境。
+ * Session 归 Agent 所有；Workspace 是会话的当前目录，不是会话身份。
  */
 
 import type { WorkspaceRuntime } from "@downcity/type";
@@ -20,18 +20,32 @@ import type {
 
 /** 创建 Agent Session 的公开参数。 */
 export interface AgentCreateSessionOptions extends AgentCreateSessionInput {
-  /** 本次 Session 可选使用的 Workspace 资源；未传入时使用内存执行上下文。 */
+  /** 新 Session 的初始目录；省略时使用 Agent 的默认目录，两者都没有则无项目上下文。 */
   workspace?: WorkspaceRuntime;
 }
 
-/** 恢复 Agent Session 时使用的本地执行上下文。 */
+/** 恢复 Agent Session 时使用的当前目录。 */
 export interface AgentGetSessionOptions {
-  /** 当前 Session 使用的 Workspace；必须与持久化 Metadata 一致。 */
+  /**
+   * 恢复后要使用的当前目录。
+   *
+   * 关键点（中文）：这与持久化值不一致时不再报错，而是以该值为准成为该 Session 的当前目录，
+   * 语义等同 `session.set({ workspace })`。省略时由 Agent 的 `resolve_workspace` 按持久化值还原。
+   */
   workspace?: WorkspaceRuntime;
 }
 
 /** Agent 公开的 Session 创建入口。 */
 export interface AgentSessionCollection {
+  /**
+   * 打开 Agent 自己的那段对话；不存在时创建。
+   *
+   * 关键点（中文）：它就是一条普通 Session，角色由 `origin.type = "agent"` 表达；
+   * 一个 Agent 至多一条，被归档或删除后下一次调用自然重建。
+   */
+  /** 返回 Agent 自己的那条会话；不存在时创建。 */
+  self(options?: AgentGetSessionOptions): Promise<AgentSession>;
+
   /** 在指定 Workspace 中创建一个属于当前 Agent 的 Session。 */
   create(options?: AgentCreateSessionOptions): Promise<AgentSession>;
 
@@ -54,9 +68,6 @@ export interface AgentSessionCollection {
   /** 清空已归档 Session。 */
   clean_archive(): Promise<AgentCleanArchiveResult>;
 
-  /** 把 Session 重新绑定到另一个 Workspace，并返回新上下文下的 Session 实例。 */
-  workspace(session_id: string, workspace: WorkspaceRuntime): Promise<AgentSession>;
-
   /** 获取 Session runtime port。 */
   runtime(session_id: string, origin_type?: string): SessionPort;
 

package/src/types/agent/AgentSessionInput.ts

@@ -0,0 +1,15 @@
+/**
+ * 取用 Agent 自己那条会话时的可选参数。
+ *
+ * 关键点（中文）
+ * - Agent 自己那条会话就是普通 Session，因此这里的语义与创建普通 Session 一致。
+ * - 已经存在时该参数被忽略：换目录走 `session.set({ workspace })`，避免静默切目录。
+ */
+
+import type { WorkspaceRuntime } from "@downcity/type";
+
+/** 取用 Agent 自己那条会话的输入。 */
+export interface AgentSessionInput {
+  /** 首次创建时注入的 Workspace 实例；省略时该会话没有项目上下文。 */
+  workspace?: WorkspaceRuntime;
+}

package/src/types/agent/SessionActor.ts

@@ -36,11 +36,18 @@ import type {
 import type {
   ListSessionMessagesInput,
   SessionMessagePage,
+  WorkspaceRuntime,
 } from "@downcity/type";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type { SessionOrigin } from "@downcity/type";
+import type {
+  AgentSessionStateKey,
+  AgentSessionStateValues,
+  RemoteSessionStateKey,
+  RemoteSessionStateValues,
+} from "@/types/agent/SessionState.js";
 
 /**
  * SDK Session 集合入口。
@@ -72,7 +79,7 @@ export interface AgentSessionActor {
   /** 当前 session 稳定标识。 */
   readonly id: string;
 
-  /** 当前 Session 创建时绑定的 Workspace ID；无 Workspace 时为空。 */
+  /** 当前 Session 创建时确定的当前目录；可在会话中切换。 */
   readonly workspace_id?: string;
   /** 当前 Session 的创建来源。 */
   readonly origin: SessionOrigin;
@@ -114,12 +121,16 @@ export interface AgentSession extends AgentSessionActor {
   /** 当前 session 所属 agent_id。 */
   readonly agent_id: string;
 
-  /** 当前 session 配置快照。 */
-  readonly config: AgentSessionConfigSnapshot;
-
-  /** 写入当前 session 默认配置。 */
+  /** 写入持久化配置；`model`、`security`、`workspace` 共用这一个入口。 */
   set(input: AgentSessionSetInput, options?: AgentSessionSetOptions): Promise<void>;
 
+  /**
+   * 读取状态；持久化字段与运行时实例共用这一个入口。
+   *
+   * 关键点（中文）：只读且无副作用，不解析也不落盘。
+   */
+  get<K extends AgentSessionStateKey>(key: K): AgentSessionStateValues[K];
+
   /** 修改当前 Session 的用户可见标题并发布 canonical mutation。 */
   rename(title: string): Promise<string>;
 
@@ -140,6 +151,13 @@ export interface RemoteAgentSession extends AgentSessionActor {
   /** 写入当前远程 Session 的可序列化动态配置。 */
   set(input: RemoteSessionSetInput, options?: AgentSessionSetOptions): Promise<void>;
 
+  /**
+   * 读取当前远程 Session 的可序列化状态。
+   *
+   * 关键点（中文）：远程边界只传递可序列化值，因此进程内实例类键不可用。
+   */
+  get<K extends RemoteSessionStateKey>(key: K): RemoteSessionStateValues[K];
+
   /** 从当前远程 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession>;
 }

package/src/types/agent/SessionContext.ts

@@ -0,0 +1,29 @@
+/**
+ * AgentSessions 解析单个 Session 执行上下文时的输入。
+ *
+ * 职责说明（中文）
+ * - 执行上下文按会话身份解析：Agent 会话比其他 Session 多一组工具。
+ * - 会话身份就是它的完整 `origin`，因此不需要新增会话类型字段。
+ *
+ * 关键点（中文）
+ * - 这里描述「创建/恢复这一个 Session 需要什么」，不是 Agent 全局配置。
+ */
+
+import type { SessionOrigin, WorkspaceRuntime } from "@downcity/type";
+
+/** 单个 Session 的执行上下文解析输入。 */
+export interface SessionContextResolution {
+  /** 本次创建或恢复的 Session 完整来源；`type` 即会话身份。 */
+  readonly origin?: SessionOrigin;
+
+  /** 本次创建或恢复时指定的当前目录；未指定时创建使用 Agent 默认目录。 */
+  readonly workspace?: WorkspaceRuntime;
+
+  /**
+   * 本次解析是否用于创建新会话。
+   *
+   * 关键点（中文）：Agent 的默认目录只在新会话生效；恢复时必须由宿主注入，
+   * 不能用默认值顶替，否则会静默换目录。
+   */
+  readonly creating?: boolean;
+}