@downcity/agent 1.1.277 → 1.1.278

package/bin/types/agent/SessionActor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SessionActor.d.ts","sourceRoot":"","sources":["../../../src/types/agent/SessionActor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SessionActor.d.ts","sourceRoot":"","sources":["../../../src/types/agent/SessionActor.ts"],"names":[],"mappings":"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"}

package/bin/types/session/SessionInstruction.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=SessionInstruction.d.ts.map

package/bin/types/session/SessionInstruction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionInstruction.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionInstruction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,sCAAsC;AACtC,MAAM,WAAW,iCAAiC;IAChD,eAAe;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,4BACf,SAAQ,iCAAiC;IACzC,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/bin/types/session/SessionInstruction.js

@@ -0,0 +1,9 @@
+/**
+ * Session instruction 显式快照存储类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 instruction.md 的定位与写入输入。
+ * - 文件存在性本身用于表达 Session 是否启用显式 instruction 快照。
+ */
+export {};
+//# sourceMappingURL=SessionInstruction.js.map

package/bin/types/session/SessionInstruction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionInstruction.js","sourceRoot":"","sources":["../../../src/types/session/SessionInstruction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/session/SessionOptions.d.ts

@@ -61,9 +61,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/bin/types/session/SessionOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SessionOptions.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AACnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,cAAc,IAAI,WAAW,CAAC;IAE9B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,qBAAqB,CACnB,OAAO,EAAE,mBAAmB,GAC3B,IAAI,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,0BAA0B,EAAE,MAAM,uBAAuB,EAAE,CAAC;IAE5D;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;IAErD;;OAEG;IACH,4BAA4B,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEvE;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,6BAA6B;IAC7B,aAAa,EAAE,MAAM,UAAU,GAAG,SAAS,CAAC;IAE5C,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B"}
+{"version":3,"file":"SessionOptions.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AACnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,cAAc,IAAI,WAAW,CAAC;IAE9B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,qBAAqB,CACnB,OAAO,EAAE,mBAAmB,GAC3B,IAAI,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,yBAAyB,EAAE,uBAAuB,EAAE,CAAC;IAErD;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;IAErD;;OAEG;IACH,4BAA4B,EAAE,MAAM,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAEvE;;OAEG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,6BAA6B;IAC7B,aAAa,EAAE,MAAM,UAAU,GAAG,SAAS,CAAC;IAE5C,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B"}

package/bin/types/session/SessionQueue.d.ts

@@ -3,7 +3,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";
@@ -20,15 +20,6 @@ export interface SessionModelQueueCommand {
     /** 配置生效后需要写入的可选 Action 标题。 */
     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 更新。 */
@@ -57,16 +48,9 @@ export interface SessionCompactQueueCommand {
     command_id: string;
 }
 /** Session FIFO 中允许出现的领域命令。 */
-export type SessionQueueCommand = SessionModelQueueCommand | SessionInstructionQueueCommand | SessionEnvQueueCommand | SessionPluginsQueueCommand | SessionCompactQueueCommand;
+export type SessionQueueCommand = SessionModelQueueCommand | 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";
     /** 当前命令唯一标识。 */

package/bin/types/session/SessionQueue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SessionQueue.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionQueue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SessionQueue.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionQueue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AACnF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E,mCAAmC;AACnC,MAAM,WAAW,wBAAwB;IACvC,4BAA4B;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,0BAA0B,CAAC;IACnC,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,0BAA0B;IACzC,+BAA+B;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,OAAO,EAAE,2BAA2B,CAAC;CACtC;AAED,mBAAmB;AACnB,MAAM,WAAW,0BAA0B;IACzC,uBAAuB;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,+BAA+B;AAC/B,MAAM,MAAM,mBAAmB,GAC3B,wBAAwB,GACxB,sBAAsB,GACtB,0BAA0B,GAC1B,0BAA0B,CAAC;AAE/B,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,mBAAmB;IACnB,IAAI,EAAE,KAAK,CAAC;IACZ,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,GACC;IACE,uBAAuB;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,2BAA2B,CAAC;CACtC,CAAC;AAEN,wBAAwB;AACxB,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,oBAAoB;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B;AAED,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IAClC,uBAAuB;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,wBAAwB;IACxB,KAAK,EAAE,uBAAuB,CAAC;IAC/B,0CAA0C;IAC1C,eAAe,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;CAC/D;AAED,6BAA6B;AAC7B,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.277",
+  "version": "1.1.278",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",

package/scripts/session-config-turn-boundary.test.mjs

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 第一次 provider 请求保持阻塞，用来制造真实的运行中配置修改窗口。
- * - instruction、env 与 plugin registry 修改不能改变已经开始的请求。
+ * - Agent instruction 修改不能改变已有 Session；env 与 plugin registry 修改在 step 检查点生效。
  * - config 与 steer 在同一个 Session step 检查点提交，并继续使用同一个 turn id。
  */
 
@@ -58,7 +58,7 @@ function create_stream_text_result(text) {
   };
 }
 
-test("running Agent config changes and steer apply at the same Session step checkpoint", async () => {
+test("Agent instruction changes only affect newly created Sessions", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-config-turn-boundary-"),
   );
@@ -133,8 +133,8 @@ test("running Agent config changes and steer apply at the same Session step chec
     assert.equal((await steer_turn.finished).success, true);
     assert.equal(plugin_stop_count, 1);
     assert.equal(provider_prompts.length, 2);
-    assert.match(provider_prompts[1], /instruction:new/);
-    assert.doesNotMatch(provider_prompts[1], /instruction:old/);
+    assert.match(provider_prompts[1], /instruction:old/);
+    assert.doesNotMatch(provider_prompts[1], /instruction:new/);
     assert.doesNotMatch(provider_prompts[1], /plugin-env:old/);
 
     const messages = await session.messages();
@@ -142,16 +142,167 @@ test("running Agent config changes and steer apply at the same Session step chec
       .filter((message) => message.type === "action" && message.status === "completed")
       .map((message) => message.title);
     assert.deepEqual(completed_actions, [
-      "Agent instruction updated",
       "Agent environment updated",
       "Agent plugin runtime-config unregistered",
     ]);
+
+    // 未显式 snapshot 的 Session 重新装载时使用 Agent 当前 instruction。
+    await agent.sessions.clear_messages(session.id);
+    const restored_session = await agent.sessions.get(session.id);
+    const restored_system = await restored_session.system();
+    const restored_system_text = restored_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(restored_system_text, /instruction:new/);
+    assert.doesNotMatch(restored_system_text, /instruction:old/);
+
+    const new_session = await agent.sessions.create({
+      sessionId: "config_turn_boundary_new_session",
+    });
+    const new_system = await new_session.system();
+    const new_system_text = new_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(new_system_text, /instruction:new/);
+    assert.doesNotMatch(new_system_text, /instruction:old/);
   } finally {
     release_first_provider_request.resolve();
     await agent.dispose();
   }
 });
 
+test("Session snapshot explicitly persists instruction.md", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-instruction-restart-"),
+  );
+  const model = new MockLanguageModelV3({ modelId: "instruction-restart-model" });
+  const first_agent = new Agent({
+    id: "instruction_restart_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:old"],
+  });
+
+  try {
+    const session = await first_agent.sessions.create({
+      sessionId: "instruction_restart_session",
+    });
+    const first_system = await session.system();
+    assert.match(
+      first_system.blocks.map((block) => block.content).join("\n"),
+      /instruction:old/,
+    );
+    await session.snapshot();
+
+    const instruction_path = path.join(
+      agent_path,
+      ".downcity",
+      "agents",
+      "instruction_restart_agent",
+      "sessions",
+      "instruction_restart_session",
+      "instruction.md",
+    );
+    assert.equal(await fs.readFile(instruction_path, "utf8"), "instruction:old");
+
+    await fs.writeFile(instruction_path, "instruction:manual", "utf8");
+    await session.snapshot();
+    assert.equal(await fs.readFile(instruction_path, "utf8"), "instruction:old");
+  } finally {
+    await first_agent.dispose();
+  }
+
+  const restarted_agent = new Agent({
+    id: "instruction_restart_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:new"],
+  });
+  try {
+    const restored_session = await restarted_agent.sessions.get(
+      "instruction_restart_session",
+    );
+    const restored_system = await restored_session.system();
+    const restored_system_text = restored_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(restored_system_text, /instruction:old/);
+    assert.doesNotMatch(restored_system_text, /instruction:new/);
+  } finally {
+    await restarted_agent.dispose();
+  }
+
+  const instruction_path = path.join(
+    agent_path,
+    ".downcity",
+    "agents",
+    "instruction_restart_agent",
+    "sessions",
+    "instruction_restart_session",
+    "instruction.md",
+  );
+  await fs.rm(instruction_path);
+
+  const fallback_agent = new Agent({
+    id: "instruction_restart_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:new"],
+  });
+  try {
+    const fallback_session = await fallback_agent.sessions.get(
+      "instruction_restart_session",
+    );
+    const fallback_system = await fallback_session.system();
+    const fallback_system_text = fallback_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(fallback_system_text, /instruction:new/);
+    assert.doesNotMatch(fallback_system_text, /instruction:old/);
+  } finally {
+    await fallback_agent.dispose();
+    await fs.rm(agent_path, { recursive: true, force: true });
+  }
+});
+
+test("empty Session snapshot suppresses Agent instruction after restart", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-empty-instruction-snapshot-"),
+  );
+  const model = new MockLanguageModelV3({ modelId: "empty-snapshot-model" });
+  const first_agent = new Agent({
+    id: "empty_snapshot_agent",
+    path: agent_path,
+    model,
+  });
+  try {
+    const session = await first_agent.sessions.create({
+      sessionId: "empty_snapshot_session",
+    });
+    await session.snapshot();
+  } finally {
+    await first_agent.dispose();
+  }
+
+  const restarted_agent = new Agent({
+    id: "empty_snapshot_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:must-not-appear"],
+  });
+  try {
+    const session = await restarted_agent.sessions.get("empty_snapshot_session");
+    const system = await session.system();
+    assert.doesNotMatch(
+      system.blocks.map((block) => block.content).join("\n"),
+      /instruction:must-not-appear/,
+    );
+  } finally {
+    await restarted_agent.dispose();
+    await fs.rm(agent_path, { recursive: true, force: true });
+  }
+});
+
 test("running session model changes apply with steer at the next Session step", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-session-step-boundary-"),

package/src/agent/Agent.ts

@@ -159,7 +159,6 @@ export class Agent {
   setInstruction(input: string | string[]): void {
     const next_instruction = normalizeInstructionInput(input);
     this.instruction.splice(0, this.instruction.length, ...next_instruction);
-    this.sessions.broadcast_instruction(this.instruction, generateId());
   }
 
   /**

package/src/agent/AgentSessions.ts

@@ -146,23 +146,6 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return this.list_executing_session_ids().length;
   }
 
-  /**
-   * 把 Agent instruction 修改广播到已有 Session 的统一输入队列。
-   */
-  broadcast_instruction(instruction: string[], command_id: string): void {
-    const instruction_blocks = createInstructionSystemBlocks(
-      instruction,
-      this.project_root,
-    );
-    for (const session of this.sessions_by_id.values()) {
-      session.enqueue_agent_command({
-        type: "instruction",
-        command_id,
-        instruction_blocks,
-      });
-    }
-  }
-
   /**
    * 把 Agent env 修改广播到已有 Session 的统一输入队列。
    */
@@ -198,9 +181,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    * 获取或创建一个 session runtime port。
    */
   runtime(session_id: string): SessionPort {
-    return this.get_or_create_session({
-      session_id,
-    }).getRuntimePort();
+    return this.get_or_create_session({ session_id }).getRuntimePort();
   }
 
   /**
@@ -436,7 +417,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       sessionId: resolved_session_id,
       tools: this.tools,
       logger: this.logger,
-      getInstructionSystemBlocks: () => this.load_instruction_system_blocks(),
+      instruction_system_blocks: this.load_instruction_system_blocks(),
       getAgentEnv: () => this.get_agent_env(),
       getAgentModel: () => this.get_agent_model(),
       get_agent_plugins: () => this.get_agent_plugins(),

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 的消息目录路径。
  */