@downcity/agent 1.1.277 → 1.1.279

package/src/session/Session.ts

@@ -74,6 +74,10 @@ import { nanoid } from "nanoid";
 import { buildSessionInfo } from "@/session/browse/Browse.js";
 import { ensureSessionTitle } from "@/session/SessionTitle.js";
 import { readSessionMetadata } from "@/session/storage/Metadata.js";
+import {
+  read_session_instruction,
+  write_session_instruction,
+} from "@/session/storage/Instruction.js";
 import { to_executor_history } from "@/session/messages/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.js";
 import type {
@@ -91,7 +95,6 @@ export class Session implements AgentSession {
   private readonly project_root: string;
   private readonly tools: Record<string, Tool>;
   private readonly logger: SessionOptions["logger"];
-  private readonly get_instruction_system_blocks: SessionOptions["getInstructionSystemBlocks"];
   private readonly get_managed_plugin_system_blocks: SessionOptions["getManagedPluginSystemBlocks"];
   private readonly ensure_configured_hook?: SessionOptions["ensureConfigured"];
   private readonly composer: SessionComposer;
@@ -105,6 +108,7 @@ export class Session implements AgentSession {
   private readonly get_agent_model: SessionOptions["getAgentModel"];
   private readonly get_agent_plugins: SessionOptions["get_agent_plugins"];
   private effective_instruction_system_blocks: AgentSessionSystemBlock[];
+  private instruction_initialize_promise: Promise<void> | null = null;
   private effective_agent_env: Record<string, string>;
   private effective_agent_plugins: AgentPluginExecutionRuntime;
   private readonly state: SessionState;
@@ -117,12 +121,11 @@ export class Session implements AgentSession {
     this.project_root = String(options.projectRoot || "").trim();
     this.tools = options.tools;
     this.logger = options.logger;
-    this.get_instruction_system_blocks = options.getInstructionSystemBlocks;
     this.get_agent_env = options.getAgentEnv;
     this.get_agent_model = options.getAgentModel;
     this.get_agent_plugins = options.get_agent_plugins;
     this.effective_instruction_system_blocks = options
-      .getInstructionSystemBlocks()
+      .instruction_system_blocks
       .map((block) => ({ ...block }));
     this.effective_agent_env = { ...options.getAgentEnv() };
     this.effective_agent_plugins = options.get_agent_plugins();
@@ -188,11 +191,35 @@ export class Session implements AgentSession {
    * 初始化当前 session。
    */
   async initialize(): Promise<this> {
-    await this.session_messages.initialize();
-    await this.state.initialize();
+    await Promise.all([
+      this.initialize_instruction(),
+      this.session_messages.initialize(),
+      this.state.initialize(),
+    ]);
     return this;
   }
 
+  /**
+   * 把当前 Session 生效的自定义 instruction 显式固化到 instruction.md。
+   *
+   * 关键点（中文）
+   * - 只写入 `instruction` 来源的 block，不包含 SDK core 与 plugin system。
+   * - 多个 instruction block 按原顺序合并为一个 Markdown 文档。
+   */
+  async snapshot(): Promise<void> {
+    await this.initialize_instruction();
+    const instruction = this.effective_instruction_system_blocks
+      .filter((block) => block.source === "instruction")
+      .map((block) => block.content)
+      .join("\n\n");
+    await write_session_instruction({
+      project_root: this.project_root,
+      agent_id: this.agentId,
+      session_id: this.id,
+      instruction,
+    });
+  }
+
   /**
    * 读取当前 session 配置快照。
    */
@@ -214,6 +241,7 @@ export class Session implements AgentSession {
    * 追加一条新的 Session prompt。
    */
   async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
+    await this.initialize_instruction();
     return await this.session_turn.prompt(input);
   }
 
@@ -236,14 +264,6 @@ export class Session implements AgentSession {
    * 把 Agent configured state command 加入当前 Session 的统一输入队列。
    */
   enqueue_agent_command(command: AgentSessionCommand): void {
-    if (command.type === "instruction") {
-      this.session_turn.enqueue_command({
-        type: "agent_instruction",
-        command_id: command.command_id,
-        instruction_blocks: command.instruction_blocks,
-      });
-      return;
-    }
     if (command.type === "env") {
       this.session_turn.enqueue_command({
         type: "agent_env",
@@ -277,18 +297,6 @@ export class Session implements AgentSession {
       }
       return;
     }
-    if (command.type === "agent_instruction") {
-      this.effective_instruction_system_blocks = command.instruction_blocks.map(
-        (block) => ({ ...block }),
-      );
-      await this.emit_config_action_event({
-        id: `agent-instruction:${this.id}:${command.command_id}`,
-        title: "Agent instruction updated",
-        state: "completed",
-        turnId: turn_id,
-      });
-      return;
-    }
     if (command.type === "agent_env") {
       this.effective_agent_env = { ...command.env };
       await this.emit_config_action_event({
@@ -406,6 +414,7 @@ export class Session implements AgentSession {
    * 读取当前 session 生效的 system 快照。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
+    await this.initialize_instruction();
     const composed = await this.compose_for_view();
     const blocks = resolve_composed_system_blocks(composed);
     return {
@@ -533,6 +542,7 @@ export class Session implements AgentSession {
    * 在执行前确保 session 已完成初始化与宿主装配。
    */
   async ensureReadyForExecution(): Promise<void> {
+    await this.initialize_instruction();
     await this.state.ensure_ready_for_execution();
   }
 
@@ -543,7 +553,9 @@ export class Session implements AgentSession {
       sessionId: session_id,
       tools: this.tools,
       logger: this.logger,
-      getInstructionSystemBlocks: this.get_instruction_system_blocks,
+      instruction_system_blocks: this.effective_instruction_system_blocks.map(
+        (block) => ({ ...block }),
+      ),
       getAgentEnv: this.get_agent_env,
       get_agent_plugins: this.get_agent_plugins,
       getManagedPluginSystemBlocks: this.get_managed_plugin_system_blocks,
@@ -567,6 +579,36 @@ export class Session implements AgentSession {
     return new SessionClass(options) as this;
   }
 
+  /** 恢复显式固化的 instruction.md；文件不存在时保留创建时 instruction。 */
+  private async initialize_instruction(): Promise<void> {
+    if (!this.instruction_initialize_promise) {
+      this.instruction_initialize_promise = (async () => {
+        const persisted_instruction = await read_session_instruction({
+          project_root: this.project_root,
+          agent_id: this.agentId,
+          session_id: this.id,
+        });
+        if (persisted_instruction === null) return;
+
+        const instruction = persisted_instruction.trim();
+        const stable_system_blocks = this.effective_instruction_system_blocks
+          .filter((block) => block.source !== "instruction")
+          .map((block) => ({ ...block }));
+        this.effective_instruction_system_blocks = [
+          ...(instruction
+            ? [{
+                source: "instruction" as const,
+                name: "agent",
+                content: instruction,
+              }]
+            : []),
+          ...stable_system_blocks,
+        ];
+      })();
+    }
+    await this.instruction_initialize_promise;
+  }
+
   private create_message_store(): JsonlSessionMessageStore {
     const session_dir_path = getSdkAgentSessionDirPath(
       this.project_root,

package/src/session/storage/Instruction.ts

@@ -0,0 +1,59 @@
+/**
+ * Session instruction 显式快照存储。
+ *
+ * 关键点（中文）
+ * - instruction.md 是可选文件，不存在时由 Session 使用 Agent 当前 instruction。
+ * - 空文件也是有效快照，用于显式固化没有自定义 instruction 的状态。
+ * - 写入使用同目录临时文件替换，避免进程中断留下半份内容。
+ */
+
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import fs from "fs-extra";
+import { getSdkAgentSessionInstructionPath } from "@/session/storage/Paths.js";
+import type {
+  SessionInstructionStorageLocation,
+  WriteSessionInstructionInput,
+} from "@/types/session/SessionInstruction.js";
+
+/** 读取 Session 显式固化的 instruction；文件不存在时返回 null。 */
+export async function read_session_instruction(
+  input: SessionInstructionStorageLocation,
+): Promise<string | null> {
+  const instruction_path = getSdkAgentSessionInstructionPath(
+    input.project_root,
+    input.agent_id,
+    input.session_id,
+  );
+  try {
+    return await fs.readFile(instruction_path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** 原子覆盖当前 Session 的 instruction.md。 */
+export async function write_session_instruction(
+  input: WriteSessionInstructionInput,
+): Promise<void> {
+  const instruction_path = getSdkAgentSessionInstructionPath(
+    input.project_root,
+    input.agent_id,
+    input.session_id,
+  );
+  const temporary_path = [
+    instruction_path,
+    process.pid,
+    Date.now(),
+    randomUUID(),
+    "tmp",
+  ].join(".");
+  await fs.ensureDir(path.dirname(instruction_path));
+  try {
+    await fs.writeFile(temporary_path, input.instruction, "utf8");
+    await fs.move(temporary_path, instruction_path, { overwrite: true });
+  } finally {
+    await fs.remove(temporary_path);
+  }
+}

package/src/session/storage/Paths.ts

@@ -129,6 +129,24 @@ export function getSdkAgentSessionDirPath(
   );
 }
 
+/**
+ * 单个 session 显式固化的 instruction.md 路径。
+ *
+ * 关键点（中文）
+ * - 文件不存在表示 Session 恢复时继续采用 Agent 当前 instruction。
+ * - 空文件表示调用方显式固化了空 instruction。
+ */
+export function getSdkAgentSessionInstructionPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionDirPath(projectRoot, agentId, sessionId),
+    "instruction.md",
+  );
+}
+
 /**
  * 单个 session 的消息目录路径。
  */

package/src/types/agent/SessionActor.ts

@@ -125,6 +125,9 @@ export interface AgentSession extends AgentSessionActor {
   /** 写入当前 session 默认配置。 */
   set(input: AgentSessionSetInput): Promise<void>;
 
+  /** 把当前 Session 生效的自定义 instruction 显式固化到 instruction.md。 */
+  snapshot(): Promise<void>;
+
   /** 从当前 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<AgentSession>;
 }

package/src/types/session/SessionInstruction.ts

@@ -0,0 +1,24 @@
+/**
+ * Session instruction 显式快照存储类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 instruction.md 的定位与写入输入。
+ * - 文件存在性本身用于表达 Session 是否启用显式 instruction 快照。
+ */
+
+/** Session instruction.md 的稳定定位信息。 */
+export interface SessionInstructionStorageLocation {
+  /** 当前项目根目录。 */
+  project_root: string;
+  /** 当前 Agent 稳定标识。 */
+  agent_id: string;
+  /** 当前 Session 稳定标识。 */
+  session_id: string;
+}
+
+/** 原子写入 Session instruction.md 使用的完整输入。 */
+export interface WriteSessionInstructionInput
+  extends SessionInstructionStorageLocation {
+  /** 当前 Session 生效的自定义 instruction Markdown。 */
+  instruction: string;
+}

package/src/types/session/SessionOptions.ts

@@ -74,9 +74,13 @@ export interface SessionOptions {
   logger: Logger;
 
   /**
-   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   * 当前 Session 创建时绑定的 instruction system blocks。
+   *
+   * 关键点（中文）
+   * - Session 创建后不再动态读取 Agent instruction。
+   * - `session.snapshot()` 只会把其中 `instruction` 来源的内容显式写入本地文件。
    */
-  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+  instruction_system_blocks: AgentSessionSystemBlock[];
 
   /**
    * 读取当前 Agent configured env。

package/src/types/session/SessionQueue.ts

@@ -4,7 +4,7 @@
  * 队列只保存明确的输入事实，不保存可执行闭包。SessionTurn 是这些输入的唯一解释者。
  */
 
-import type { AgentSessionConfigSnapshot, AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
@@ -23,16 +23,6 @@ export interface SessionModelQueueCommand {
   action_title?: string;
 }
 
-/** Agent instruction 在 Session Step 检查点生效的命令。 */
-export interface SessionInstructionQueueCommand {
-  /** 命令种类固定为 Agent instruction 更新。 */
-  type: "agent_instruction";
-  /** 当前命令的稳定唯一标识。 */
-  command_id: string;
-  /** 下一 Step 使用的完整 instruction blocks。 */
-  instruction_blocks: AgentSessionSystemBlock[];
-}
-
 /** Agent env 在 Session Step 检查点生效的命令。 */
 export interface SessionEnvQueueCommand {
   /** 命令种类固定为 Agent env 更新。 */
@@ -66,29 +56,19 @@ export interface SessionCompactQueueCommand {
 /** Session FIFO 中允许出现的领域命令。 */
 export type SessionQueueCommand =
   | SessionModelQueueCommand
-  | SessionInstructionQueueCommand
   | SessionEnvQueueCommand
   | SessionPluginsQueueCommand
   | SessionCompactQueueCommand;
 
 /** Agent configured state 广播给既有 Session 的输入。 */
-export type AgentSessionCommand =
-  | {
-      /** 当前修改固定为 instruction。 */
-      type: "instruction";
-      /** 当前命令唯一标识。 */
-      command_id: string;
-      /** 下一 Session Step 使用的 instruction blocks。 */
-      instruction_blocks: AgentSessionSystemBlock[];
-    }
-  | {
-      /** 当前修改固定为 env。 */
-      type: "env";
-      /** 当前命令唯一标识。 */
-      command_id: string;
-      /** 下一 Session Step 使用的完整 Agent env。 */
-      env: Record<string, string>;
-    }
+export type AgentSessionCommand = {
+    /** 当前修改固定为 env。 */
+    type: "env";
+    /** 当前命令唯一标识。 */
+    command_id: string;
+    /** 下一 Session Step 使用的完整 Agent env。 */
+    env: Record<string, string>;
+  }
   | {
       /** 当前修改固定为 plugins。 */
       type: "plugins";