@downcity/agent 1.1.287 → 1.1.310

package/scripts/session-queue.test.mjs

@@ -1,64 +1,99 @@
 /**
- * @file 验证 SessionQueue 只维护 Prompt/Command 的确定 FIFO 顺序。
+ * @file 验证 SessionQueue 只保存具体 Command 对象并维护确定的 FIFO 顺序。
  */
 
 import assert from "node:assert/strict";
 import test from "node:test";
 import { SessionQueue } from "../bin/session/SessionQueue.js";
+import { SessionCommand } from "../bin/session/SessionCommand.js";
 
-function model_command(command_id) {
-  return {
-    type: "session_model",
-    command_id,
-    config: {},
-  };
+function create_command(name, executed, cancel) {
+  return new SessionCommand({
+    execute: async () => {
+      executed.push(name);
+    },
+    ...(cancel ? { cancel } : {}),
+  });
 }
 
-test("SessionQueue 返回首个 Prompt 及其之前的命令", () => {
+test("SessionQueue 按 FIFO 返回具体 Command 对象", async () => {
   const queue = new SessionQueue();
-  queue.enqueue_command(model_command("command-1"));
-  const handle = queue.enqueue_prompt({ query: "first" });
-  queue.enqueue_command({ type: "compact", command_id: "compact-1" });
+  const executed = [];
+  const first = create_command("first", executed);
+  const second = create_command("second", executed);
+
+  queue.enqueue_command(first);
+  queue.enqueue_command(second);
 
-  const next = queue.take_next_prompt();
-  assert.deepEqual(next.commands.map((item) => item.command_id), ["command-1"]);
-  assert.equal(next.prompt.input.query, "first");
-  assert.equal(handle instanceof Promise, true);
-  assert.equal(queue.has_command(), true);
-  assert.equal(queue.has_prompt(), false);
+  assert.equal(queue.take_next(), first);
+  assert.equal(queue.take_next(), second);
+  assert.equal(queue.take_next(), undefined);
+  assert.equal(queue.has_command(), false);
+
+  await first.execute();
+  await second.execute();
+  assert.deepEqual(executed, ["first", "second"]);
 });
 
-test("SessionQueue drain 保留 Prompt 和 Command 的原始顺序", () => {
+test("SessionQueue drain 保留 Command 对象的原始顺序", async () => {
   const queue = new SessionQueue();
-  queue.enqueue_prompt({ query: "steer-1" });
-  queue.enqueue_command(model_command("command-1"));
-  queue.enqueue_prompt({ query: "steer-2" });
+  const executed = [];
+  queue.enqueue_command(create_command("first", executed));
+  queue.enqueue_command(create_command("second", executed));
+  queue.enqueue_command(create_command("third", executed));
 
-  assert.deepEqual(
-    queue.drain().map((item) => item.type),
-    ["prompt", "session_model", "prompt"],
-  );
-  assert.equal(queue.has_prompt(), false);
+  const commands = queue.drain();
+  assert.equal(queue.has_command(), false);
+  for (const command of commands) await command.execute();
+  assert.deepEqual(executed, ["first", "second", "third"]);
 });
 
-test("SessionQueue cancel_prompts 取消 Prompt 但保留命令", () => {
+test("SessionQueue cancel 只移除拥有取消行为的 Command", async () => {
   const queue = new SessionQueue();
-  queue.enqueue_prompt({ query: "queued" });
-  queue.enqueue_command({ type: "compact", command_id: "compact-1" });
+  const executed = [];
+  const cancelled = [];
+  queue.enqueue_command(create_command("prompt", executed, () => {
+    cancelled.push("prompt");
+  }));
+  queue.enqueue_command(create_command("action", executed));
+
+  assert.equal(queue.cancel(), 1);
+  assert.deepEqual(cancelled, ["prompt"]);
 
-  assert.equal(queue.cancel_prompts().length, 1);
-  assert.deepEqual(queue.drain(), [
-    { type: "compact", command_id: "compact-1" },
-  ]);
+  const retained = queue.drain();
+  assert.equal(retained.length, 1);
+  await retained[0].execute();
+  assert.deepEqual(executed, ["action"]);
 });
 
-test("SessionQueue 可以把未处理输入恢复到队列头部", () => {
+test("SessionQueue 可以把未处理 Command 恢复到队列头部", async () => {
   const queue = new SessionQueue();
-  queue.enqueue_command({ type: "compact", command_id: "tail" });
-  queue.restore_front([model_command("head")]);
+  const executed = [];
+  const head = create_command("head", executed);
+  const middle = create_command("middle", executed);
+  const tail = create_command("tail", executed);
+  queue.enqueue_command(tail);
+  queue.restore_front([head, middle]);
+
+  for (const command of queue.drain()) await command.execute();
+  assert.deepEqual(executed, ["head", "middle", "tail"]);
+});
+
+test("SessionCommand 成功执行后返回可选的持久化完成信息", async () => {
+  const completion = {
+    type: "action",
+    id: "config-completed",
+    title: "Configuration updated",
+    description: "The next step uses the new configuration.",
+  };
+  const command = new SessionCommand({
+    execute: async () => {},
+    completion,
+  });
+  const silent_command = new SessionCommand({
+    execute: async () => {},
+  });
 
-  assert.deepEqual(
-    queue.drain().map((item) => item.command_id),
-    ["head", "tail"],
-  );
+  assert.deepEqual(await command.execute(), completion);
+  assert.equal(await silent_command.execute(), undefined);
 });

package/scripts/session-shell-approval.test.mjs

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 通过真实 Agent、Executor 与 Shell tool loop 发起 unrestricted 请求。
- * - approval-required Mutation 必须携带当前 Session、Turn 与 Tool Call 标识。
+ * - approval Interaction 必须携带当前 Turn 与 Tool Call 标识。
  * - 用户批准后命令才执行，最终 Tool Part 收口为 completed。
  */
 
@@ -13,7 +13,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { MockLanguageModelV3 } from "ai/test";
-import { Agent } from "@downcity/agent";
+import { Agent, Workspace } from "@downcity/agent";
 import { Shell } from "@downcity/shell";
 import { create_platform_sandbox } from "./PlatformSandbox.mjs";
 
@@ -120,28 +120,32 @@ test("unrestricted Shell 审批保留当前 Turn 并等待用户决定", async (
   });
   const agent = new Agent({
     id: "session_shell_approval_agent",
-    path: project_root,
+    workspace: new Workspace({
+      path: project_root,
+      shell: new Shell({ sandbox }),
+    }),
     model,
-    shell: new Shell({ sandbox }),
   });
 
   try {
     const session = await agent.sessions.create({
-      sessionId: "session_shell_approval",
+      session_id: "session_shell_approval",
     });
-    let approval_snapshot;
-    let approval_result;
+    let interaction_snapshot;
+    let interaction_result;
     const unsubscribe = session.subscribe((mutation) => {
       if (
         mutation.variant !== "part" ||
-        mutation.type !== "tool" ||
-        mutation.part.state !== "approval-required" ||
-        !mutation.part.approval
+        mutation.type !== "interaction" ||
+        mutation.part.interaction_type !== "approval" ||
+        mutation.part.status !== "pending" ||
+        mutation.part.request.kind !== "approval" ||
+        mutation.part.request.source.type !== "tool"
       ) return;
-      approval_snapshot = mutation.part.approval;
-      approval_result = session.resolve_approval({
-        approval_id: mutation.part.approval.approval_id,
-        decision: "approved",
+      interaction_snapshot = mutation.part;
+      interaction_result = session.respond({
+        interaction_id: mutation.part.interaction_id,
+        response: { kind: "approval", decision: "approved" },
       });
     });
 
@@ -155,14 +159,13 @@ test("unrestricted Shell 审批保留当前 Turn 并等待用户决定", async (
     const tool_part = messages.items
       .flatMap((message) => message.type === "assistant" ? message.parts : [])
       .find((part) => part.type === "tool" && part.tool_call_id === "call_unrestricted");
-    assert.ok(approval_snapshot, JSON.stringify(messages.items));
-    assert.equal(approval_snapshot.request.session_id, session.id);
-    assert.equal(approval_snapshot.request.turn_id, turn.id);
-    assert.equal(approval_snapshot.request.tool_call_id, "call_unrestricted");
-    assert.deepEqual(await approval_result, {
-      success: true,
-      approval_id: approval_snapshot.approval_id,
-      decision: "approved",
+    assert.ok(interaction_snapshot, JSON.stringify(messages.items));
+    assert.equal(interaction_snapshot.request.turn_id, turn.id);
+    assert.equal(interaction_snapshot.request.source.tool_call_id, "call_unrestricted");
+    assert.deepEqual(await interaction_result, {
+      status: "resolved",
+      interaction_id: interaction_snapshot.interaction_id,
+      response: { kind: "approval", decision: "approved" },
     });
     assert.equal(tool_part?.state, "completed");
     assert.equal(tool_part?.output?.output, "approval-ok");

package/scripts/session-system-blocks.test.mjs

@@ -9,11 +9,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { createInstructionSystemBlocks } from "../bin/agent/AgentInstructions.js";
+import { create_instruction_system_blocks } from "../bin/agent/AgentInstructions.js";
 import { build_session_system_blocks } from "../bin/session/SessionSystem.js";
 
 test("instruction blocks keep Downcity core after custom instruction", () => {
-  const blocks = createInstructionSystemBlocks(
+  const blocks = create_instruction_system_blocks(
     ["你是这个项目的工程 agent。"],
     "/tmp/downcity-project",
   );
@@ -44,7 +44,7 @@ test("session system blocks are ordered as instruction, core, plugin, session",
     created_at: Date.UTC(2026, 6, 9, 8, 0, 0),
     timezone: "Asia/Shanghai",
     get_instruction_system_blocks: () =>
-      createInstructionSystemBlocks(
+      create_instruction_system_blocks(
         ["使用中文回复。"],
         "/tmp/downcity-project",
       ),

package/scripts/session-title-event.test.mjs

@@ -14,7 +14,7 @@ import path from "node:path";
 import fs from "node:fs/promises";
 
 import { MockLanguageModelV3 } from "ai/test";
-import { Agent } from "../bin/index.js";
+import { Agent, Workspace } from "../bin/index.js";
 
 function create_stream_text_result(text) {
   return {
@@ -97,7 +97,7 @@ test("Session keeps title empty when no model is available", async () => {
   );
   const agent = new Agent({
     id: "title_agent",
-    path: agent_path,
+    workspace: new Workspace({ path: agent_path }),
   });
   const session = await agent.sessions.create();
   const events = [];
@@ -129,7 +129,7 @@ test("Session logs title generation failure without blocking the session", async
   );
   const agent = new Agent({
     id: "title_log_agent",
-    path: agent_path,
+    workspace: new Workspace({ path: agent_path }),
     model: create_failing_title_model(),
   });
   const session = await agent.sessions.create();
@@ -142,7 +142,7 @@ test("Session logs title generation failure without blocking the session", async
 
     assert.equal((await session.get_info()).title, undefined);
 
-    await agent.getLogger().saveAllLogs();
+    await agent.get_logger().save_all_logs();
     const log_lines = await read_log_lines(agent_path);
     const title_failure_log = log_lines
       .map((line) => JSON.parse(line))
@@ -150,9 +150,9 @@ test("Session logs title generation failure without blocking the session", async
 
     assert.ok(title_failure_log);
     assert.equal(title_failure_log.type, "warn");
-    assert.equal(title_failure_log.details.sessionId, session.id);
+    assert.equal(title_failure_log.details.session_id, session.id);
     assert.equal(
-      title_failure_log.details.modelLabel,
+      title_failure_log.details.model_label,
       "mock-session-title-failing-model",
     );
     assert.equal(
@@ -174,7 +174,7 @@ test("Session retries title generation after model becomes available", async ()
   );
   const agent = new Agent({
     id: "title_retry_agent",
-    path: agent_path,
+    workspace: new Workspace({ path: agent_path }),
   });
   const session = await agent.sessions.create();
   const events = [];

package/scripts/session-turn-context.test.mjs

@@ -0,0 +1,99 @@
+/**
+ * @file 验证 SessionTurnContext 的状态边界与生命周期所有权。
+ *
+ * 关键点（中文）
+ * - 动态输入和输出只能通过领域行为读写。
+ * - Step 切换和 Context dispose 都会闭合 Plugin lease。
+ * - Plugin 只获得独立的只读快照，不能访问根上下文能力。
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { create_session_turn_context } from "../bin/session/runtime/SessionTurnContext.js";
+
+test("SessionTurnContext 在检查点消费输入并封装输出缓冲", async () => {
+  const context = create_session_turn_context({
+    session_id: "session-context-test",
+    turn_id: "turn-context-test",
+    project_root: "/workspace",
+    merge_step_input: async () => [{
+      id: "queued-message",
+      role: "user",
+      metadata: {
+        v: 1,
+        ts: 2,
+        session_id: "session-context-test",
+        source: "ingress",
+        kind: "normal",
+      },
+      parts: [{ type: "text", text: "queued" }],
+    }],
+  });
+  context.input.inject_user_message({
+    id: "injected-message",
+    role: "user",
+    metadata: {
+      v: 1,
+      ts: 1,
+      session_id: "session-context-test",
+      source: "ingress",
+      kind: "normal",
+    },
+    parts: [{ type: "text", text: "injected" }],
+  });
+  context.output.enqueue_assistant_parts([{
+    type: "file",
+    mediaType: "text/plain",
+    url: "/workspace/result.txt",
+  }]);
+
+  assert.deepEqual(
+    (await context.input.checkpoint()).map((message) => message.id),
+    ["injected-message", "queued-message"],
+  );
+  assert.deepEqual(
+    (await context.input.checkpoint()).map((message) => message.id),
+    ["queued-message"],
+  );
+  assert.equal(context.output.take_assistant_parts().length, 1);
+  assert.equal(context.output.take_assistant_parts().length, 0);
+});
+
+test("SessionTurnContext 负责 Plugin lease 与只读投影生命周期", async () => {
+  const released = [];
+  const create_lease = (name) => ({
+    read: () => ({ plugins: [] }),
+    run_action: async () => ({ success: true }),
+    system_blocks: async () => [],
+    release: async () => released.push(name),
+  });
+  const context = create_session_turn_context({
+    session_id: "session-context-test",
+    turn_id: "turn-context-test",
+    project_root: "/workspace",
+  });
+  context.step.commit({
+    workspace_env: { REGION: "cn" },
+    agent_systems: ["system"],
+  });
+  await context.step.replace_plugins(create_lease("first"));
+  await context.step.replace_plugins(create_lease("second"));
+
+  const plugin_execution_context = context.step.plugin_execution_context();
+  assert.deepEqual(Object.keys(plugin_execution_context).sort(), [
+    "abort_signal",
+    "agent_systems",
+    "project_root",
+    "session_id",
+    "turn_id",
+    "workspace_env",
+  ]);
+  assert.equal(Object.isFrozen(plugin_execution_context), true);
+  assert.deepEqual(plugin_execution_context.workspace_env, { REGION: "cn" });
+  assert.deepEqual(released, ["first"]);
+
+  await context.lifecycle.dispose();
+  await context.lifecycle.dispose();
+  assert.deepEqual(released, ["first", "second"]);
+});