@downcity/agent 1.1.287 → 1.1.310

package/scripts/{plugin-tool-bridge.test.mjs → plugin-tools.test.mjs}

@@ -1,40 +1,35 @@
 /**
- * @file 验证 plugin tool bridge 会把生成文件摘要为可打开路径。
+ * @file 验证 Plugin Tool 的 ActionResult 转换与 Agent 绑定。
  *
  * 关键点（中文）
- * - assistant message 使用 Agent 根目录相对路径，避免历史暴露本机路径。
- * - tool result 同时返回相对路径与本机绝对路径，便于模型与用户明确知道文件位置。
+ * - Plugin Action 自己产生本地 File Part，Tool 运行时不处理文件。
+ * - output 与 messages 分开返回，由 Executor 的统一边界分流。
  */
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import os from "node:os";
-import path from "node:path";
-import fs from "node:fs/promises";
-
 import {
-  invokePluginCallTool,
-  invokePluginReadTool,
-} from "../bin/executor/tools/plugin/PluginToolBridge.js";
-import { createPluginTools } from "../bin/executor/tools/plugin/PluginToolDefinition.js";
-import { plugin_call_input_schema } from "../bin/executor/tools/plugin/PluginToolSchemas.js";
-import { createAction, createPlugin } from "../bin/plugin/core/PluginActionFactory.js";
+  invoke_plugin_call_tool,
+  invoke_plugin_read_tool,
+} from "../bin/plugin/tool/PluginToolRuntime.js";
+import { create_plugin_tools } from "../bin/plugin/tool/PluginTools.js";
+import { plugin_call_input_schema } from "../bin/plugin/tool/PluginToolSchemas.js";
+import { create_action, create_plugin } from "../bin/plugin/core/PluginActionFactory.js";
 import { PluginRegistry } from "../bin/plugin/core/PluginRegistry.js";
+import { create_session_turn_context } from "../bin/session/runtime/SessionTurnContext.js";
 import { z } from "zod";
 
-function create_run_context(project_root) {
-  return {
-    sessionId: "session_test",
-    projectRoot: project_root,
-    injectedUserMessages: [],
-    deferredPersistedUserMessages: [],
-    pendingAssistantFileParts: [],
-  };
+function create_turn_context(project_root) {
+  return create_session_turn_context({
+    session_id: "session_test",
+    turn_id: "turn_test",
+    project_root: project_root,
+  });
 }
 
 function create_registry(plugin) {
   const registry = new PluginRegistry([plugin]);
-  registry.bind_context({ rootPath: process.cwd() });
+  registry.bind_context({ workspace_path: process.cwd() });
   return registry;
 }
 
@@ -50,31 +45,26 @@ test("plugin_call payload schema allows arbitrary object properties", async () =
   assert.deepEqual(payload_schema.default, {});
 });
 
-test("invokePluginCallTool returns absolute paths for materialized file parts", async () => {
-  const project_root = await fs.mkdtemp(
-    path.join(os.tmpdir(), "downcity-agent-plugin-tool-files-"),
-  );
-  const bytes = Buffer.from("png-bytes-for-plugin-tool", "utf8");
-
+test("invoke_plugin_call_tool preserves Action output and messages", async () => {
   const plugins = {
     list: () => [],
     read: () => ({ plugins: [] }),
     availability: async () => ({ enabled: true, available: true, reasons: [] }),
-    runAction: async () => ({
+    run_action: async () => ({
       success: true,
       message: "image generated",
-      data: {
-        id: "msg_image_test",
+      data: { job_id: "img_1" },
+      messages: [{
         role: "assistant",
         parts: [
           {
             type: "file",
             mediaType: "image/png",
             filename: "image.png",
-            url: `data:image/png;base64,${bytes.toString("base64")}`,
+            url: "/workspace/image.png",
           },
         ],
-      },
+      }],
     }),
     pipeline: async (_, value) => value,
     guard: async () => {},
@@ -84,10 +74,10 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
     },
   };
 
-  const run_context = create_run_context(project_root);
-  const result = await invokePluginCallTool({
+  const turn_context = create_turn_context("/workspace");
+  const result = await invoke_plugin_call_tool({
     plugins,
-    run_context,
+    turn_context,
     input: {
       plugin: "image",
       action: "image_result",
@@ -95,24 +85,26 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
     },
   });
 
-  assert.equal(result.success, true);
-  assert.equal(result.assistant_file_count, 1);
-  assert.equal(result.files?.length, 1);
-  assert.match(result.files[0].relative_path, /^\.downcity\/resources\//);
-  assert.equal(path.isAbsolute(result.files[0].path), true);
-  assert.equal(
-    path.dirname(result.files[0].path),
-    path.join(project_root, ".downcity", "resources"),
-  );
-  assert.deepEqual(await fs.readFile(result.files[0].path), bytes);
-  assert.equal("data" in result, false);
-
-  const pending_parts = run_context.pendingAssistantFileParts;
-  assert.equal(pending_parts.length, 1);
-  assert.equal(pending_parts[0].url, result.files[0].relative_path);
+  assert.deepEqual(result.output, {
+    success: true,
+    plugin: "image",
+    action: "image_result",
+    message: "image generated",
+    data: { job_id: "img_1" },
+  });
+  assert.deepEqual(result.messages, [{
+    role: "assistant",
+    parts: [{
+      type: "file",
+      mediaType: "image/png",
+      filename: "image.png",
+      url: "/workspace/image.png",
+    }],
+  }]);
+  assert.equal(turn_context.output.take_assistant_parts().length, 0);
 });
 
-test("invokePluginReadTool returns plugin action metadata", async () => {
+test("invoke_plugin_read_tool returns plugin action metadata", async () => {
   const plugins = {
     list: () => [],
     read: () => ({
@@ -142,7 +134,7 @@ test("invokePluginReadTool returns plugin action metadata", async () => {
       ],
     }),
     availability: async () => ({ enabled: true, available: true, reasons: [] }),
-    runAction: async () => ({ success: false, error: "not used" }),
+    run_action: async () => ({ success: false, error: "not used" }),
     pipeline: async (_, value) => value,
     guard: async () => {},
     effect: async () => {},
@@ -151,25 +143,26 @@ test("invokePluginReadTool returns plugin action metadata", async () => {
     },
   };
 
-  const result = await invokePluginReadTool({
+  const result = await invoke_plugin_read_tool({
     plugins,
-    run_context: create_run_context(process.cwd()),
+    turn_context: create_turn_context(process.cwd()),
     input: {
       plugin: "image",
       action: "image_create",
     },
   });
 
-  assert.equal(result.success, true);
-  assert.equal(result.data.name, "image");
-  assert.equal(result.data.actions[0].name, "image_create");
-  assert.equal(result.data.actions[0].has_input_schema, true);
-  assert.equal(result.data.actions[0].examples[0].payload.prompt, "draw");
+  assert.equal(result.output.success, true);
+  assert.equal(result.output.data.name, "image");
+  assert.equal(result.output.data.actions[0].name, "image_create");
+  assert.equal(result.output.data.actions[0].has_input_schema, true);
+  assert.equal(result.output.data.actions[0].examples[0].payload.prompt, "draw");
+  assert.deepEqual(result.messages, []);
 });
 
-test("invokePluginReadTool rejects unregistered plugins", async () => {
+test("invoke_plugin_read_tool rejects unregistered plugins", async () => {
   const registry = create_registry(
-    createPlugin({
+    create_plugin({
       name: "skill",
       title: "Skill",
       description: "Manage skills",
@@ -177,20 +170,20 @@ test("invokePluginReadTool rejects unregistered plugins", async () => {
     }),
   );
 
-  const result = await invokePluginReadTool({
+  const result = await invoke_plugin_read_tool({
     plugins: registry,
-    run_context: create_run_context(process.cwd()),
+    turn_context: create_turn_context(process.cwd()),
     input: { plugin: "task" },
   });
 
-  assert.equal(result.success, false);
-  assert.match(result.message, /Unknown plugin: task/);
-  assert.match(result.data.error, /Unknown plugin: task/);
+  assert.equal(result.output.success, false);
+  assert.match(result.output.message, /Unknown plugin: task/);
+  assert.match(result.output.data.error, /Unknown plugin: task/);
 });
 
-test("invokePluginReadTool rejects unknown plugin actions", async () => {
+test("invoke_plugin_read_tool rejects unknown plugin actions", async () => {
   const registry = create_registry(
-    createPlugin({
+    create_plugin({
       name: "skill",
       title: "Skill",
       description: "Manage skills",
@@ -198,24 +191,24 @@ test("invokePluginReadTool rejects unknown plugin actions", async () => {
     }),
   );
 
-  const result = await invokePluginReadTool({
+  const result = await invoke_plugin_read_tool({
     plugins: registry,
-    run_context: create_run_context(process.cwd()),
+    turn_context: create_turn_context(process.cwd()),
     input: { plugin: "skill", action: "missing" },
   });
 
-  assert.equal(result.success, false);
-  assert.match(result.message, /Unknown action: skill\.missing/);
-  assert.match(result.data.error, /Unknown action: skill\.missing/);
+  assert.equal(result.output.success, false);
+  assert.match(result.output.message, /Unknown action: skill\.missing/);
+  assert.match(result.output.data.error, /Unknown action: skill\.missing/);
 });
 
 test("PluginRegistry validates action payload with metadata schema", async () => {
-  const plugin = createPlugin({
+  const plugin = create_plugin({
     name: "demo",
     title: "Demo",
     description: "Demo plugin",
     actions: {
-      echo: createAction({
+      echo: create_action({
         description: "Echo text",
         input_schema: {
           zod: z.object({
@@ -243,7 +236,7 @@ test("PluginRegistry validates action payload with metadata schema", async () =>
   assert.equal(metadata.actions[0].description, "Echo text");
   assert.equal(metadata.actions[0].has_input_schema, true);
 
-  const invalid = await registry.runAction({
+  const invalid = await registry.run_action({
     plugin: "demo",
     action: "echo",
     payload: {},
@@ -251,7 +244,7 @@ test("PluginRegistry validates action payload with metadata schema", async () =>
   assert.equal(invalid.success, false);
   assert.match(invalid.error, /Invalid payload/);
 
-  const valid = await registry.runAction({
+  const valid = await registry.run_action({
     plugin: "demo",
     action: "echo",
     payload: { text: "hello" },
@@ -260,20 +253,21 @@ test("PluginRegistry validates action payload with metadata schema", async () =>
   assert.equal(valid.data.text, "hello");
 });
 
-test("createPluginTools binds plugin_call to the current registry", async () => {
+test("create_plugin_tools binds plugin_call to the current registry", async () => {
   function create_owner_registry(owner) {
-    const plugin = createPlugin({
+    const plugin = create_plugin({
       name: "skill",
       title: `Skill ${owner}`,
       description: "Owner scoped skill plugin",
       actions: {
-        lookup: createAction({
+        lookup: create_action({
           description: "Return registry owner",
-          execute: async ({ run_context }) => ({
+          execute: async ({ execution_context }) => ({
             success: true,
             data: {
               owner,
-              session_id: run_context?.sessionId,
+              session_id: execution_context?.session_id,
+              context_keys: Object.keys(execution_context || {}).sort(),
             },
             message: owner,
           }),
@@ -285,16 +279,19 @@ test("createPluginTools binds plugin_call to the current registry", async () =>
 
   const registry_a = create_owner_registry("agent_a");
   const registry_b = create_owner_registry("agent_b");
-  const tools_a = createPluginTools({ plugins: registry_a });
-  const tools_b = createPluginTools({ plugins: registry_b });
+  const tools_a = create_plugin_tools({ plugins: registry_a });
+  const tools_b = create_plugin_tools({ plugins: registry_b });
   const create_execution_options = (session_id) => {
-    const run_context = create_run_context(process.cwd());
-    run_context.sessionId = session_id;
+    const turn_context = create_session_turn_context({
+      session_id,
+      turn_id: `turn_${session_id}`,
+      project_root: process.cwd(),
+    });
     return {
       toolCallId: `call_${session_id}`,
       messages: [],
       experimental_context: {
-        session_run_context: run_context,
+        session_turn_context: turn_context,
         shell_run_context: {
           ownerContextId: session_id,
         },
@@ -313,22 +310,29 @@ test("createPluginTools binds plugin_call to the current registry", async () =>
     payload: { name: "anything" },
   }, create_execution_options("session_b"));
 
-  assert.equal(result_a.success, true);
-  assert.equal(result_a.data.value.owner, "agent_a");
-  assert.equal(result_a.data.value.session_id, "session_a");
-  assert.equal(result_b.success, true);
-  assert.equal(result_b.data.value.owner, "agent_b");
-  assert.equal(result_b.data.value.session_id, "session_b");
+  assert.equal(result_a.output.success, true);
+  assert.equal(result_a.output.data.owner, "agent_a");
+  assert.equal(result_a.output.data.session_id, "session_a");
+  assert.deepEqual(result_a.output.data.context_keys, [
+    "abort_signal",
+    "agent_systems",
+    "project_root",
+    "session_id",
+    "turn_id",
+  ]);
+  assert.equal(result_b.output.success, true);
+  assert.equal(result_b.output.data.owner, "agent_b");
+  assert.equal(result_b.output.data.session_id, "session_b");
 });
 
 test("PluginRegistry keeps plugin ready after action business failure", async () => {
   let call_count = 0;
-  const plugin = createPlugin({
+  const plugin = create_plugin({
     name: "skill",
     title: "Skill",
     description: "Retryable skill plugin",
     actions: {
-      lookup: createAction({
+      lookup: create_action({
         description: "Fail once then succeed",
         execute: async () => {
           call_count += 1;
@@ -350,7 +354,7 @@ test("PluginRegistry keeps plugin ready after action business failure", async ()
   });
   const registry = create_registry(plugin);
 
-  const failed = await registry.runAction({
+  const failed = await registry.run_action({
     plugin: "skill",
     action: "lookup",
     payload: { name: "missing" },
@@ -358,7 +362,7 @@ test("PluginRegistry keeps plugin ready after action business failure", async ()
   assert.equal(failed.success, false);
   assert.equal(registry.status("skill").status, "ready");
 
-  const retry = await registry.runAction({
+  const retry = await registry.run_action({
     plugin: "skill",
     action: "lookup",
     payload: { name: "exists" },
@@ -371,7 +375,7 @@ test("PluginRegistry keeps plugin ready after action business failure", async ()
 test("PluginRegistry delays lifecycle stop until the active execution lease is released", async () => {
   let lifecycle_active = false;
   let stop_count = 0;
-  const plugin = createPlugin({
+  const plugin = create_plugin({
     name: "leased-plugin",
     title: "Leased Plugin",
     description: "Keeps runtime resources alive for an active Session step",
@@ -385,7 +389,7 @@ test("PluginRegistry delays lifecycle stop until the active execution lease is r
       },
     },
     actions: {
-      status: createAction({
+      status: create_action({
         description: "Read lifecycle state",
         execute: async () => ({
           success: lifecycle_active,
@@ -395,7 +399,7 @@ test("PluginRegistry delays lifecycle stop until the active execution lease is r
     },
   });
   const registry = create_registry(plugin);
-  await registry.startAll();
+  await registry.start_all();
   const lease = registry.execution_view().acquire();
 
   assert.equal(await registry.unregister("leased-plugin"), true);
@@ -403,7 +407,7 @@ test("PluginRegistry delays lifecycle stop until the active execution lease is r
   assert.equal(lifecycle_active, true);
   assert.equal(stop_count, 0);
 
-  const result = await lease.runAction({
+  const result = await lease.run_action({
     plugin: "leased-plugin",
     action: "status",
   });

package/scripts/public-api-naming.test.mjs

@@ -0,0 +1,108 @@
+/**
+ * Agent SDK 公开命名约束测试。
+ *
+ * 关键点（中文）
+ * - 类型名保持 PascalCase。
+ * - Downcity 自有公开函数、方法和字段统一使用 snake_case。
+ * - 第三方 AI SDK 原始结构不纳入本检查。
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const package_root = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+const public_declaration_files = [
+  "agent/Agent.d.ts",
+  "agent/AgentSessions.d.ts",
+  "remote/RemoteAgent.d.ts",
+  "remote/RemoteSession.d.ts",
+  "session/Session.d.ts",
+  "workspace/Workspace.d.ts",
+  "plugin/core/PluginRegistry.d.ts",
+  "types/agent/AgentOptions.d.ts",
+  "types/agent/SessionActor.d.ts",
+  "types/agent/SessionTypes.d.ts",
+  "types/agent/RemoteAgentOptions.d.ts",
+  "types/agent/RemoteAgentPluginAction.d.ts",
+  "types/sdk/AgentSessionPrompt.d.ts",
+  "types/sdk/AgentSessionStop.d.ts",
+  "types/sdk/AgentSessionTurn.d.ts",
+  "types/session/SessionOptions.d.ts",
+  "types/session/SessionPort.d.ts",
+  "types/plugin/PluginContext.d.ts",
+  "types/plugin/PluginRuntime.d.ts",
+  "types/plugin/PluginAction.d.ts",
+  "types/plugin/PluginCommand.d.ts",
+  "types/plugin/PluginHttp.d.ts",
+  "types/plugin/PluginExecutionContext.d.ts",
+  "plugin/types/ActionSchedule.d.ts",
+  "types/rpc/RpcProtocol.d.ts",
+];
+
+/** 删除声明文件注释，避免示例文本参与标识符检查。 */
+function strip_comments(input) {
+  return input
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\/\/.*$/gm, "");
+}
+
+test("Agent SDK public members use snake_case", () => {
+  const failures = [];
+  const camel_member_pattern =
+    /^\s+(?:readonly\s+)?([a-z][A-Za-z0-9_]*[A-Z][A-Za-z0-9_]*)(?:\??:|\??\()/gm;
+
+  for (const relative_path of public_declaration_files) {
+    const file_path = path.join(package_root, "bin", relative_path);
+    const content = strip_comments(fs.readFileSync(file_path, "utf8"));
+    for (const match of content.matchAll(camel_member_pattern)) {
+      failures.push(`${relative_path}: ${match[1]}`);
+    }
+  }
+
+  assert.deepEqual(failures, []);
+});
+
+test("Agent SDK root exports do not expose camelCase functions", () => {
+  const file_path = path.join(package_root, "bin", "index.d.ts");
+  const content = strip_comments(fs.readFileSync(file_path, "utf8"))
+    .replace(/from\s+["'][^"']+["']/g, "")
+    .replace(/export\s+\*\s+["'][^"']+["']/g, "");
+  const camel_function_exports = [
+    ...content.matchAll(/\b([a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*)\b/g),
+  ].map((match) => match[1]);
+
+  assert.deepEqual([...new Set(camel_function_exports)], []);
+});
+
+test("Agent internal module exports use snake_case function names", () => {
+  const source_root = path.join(package_root, "src");
+  const failures = [];
+  const camel_export_pattern =
+    /^export\s+(?:async\s+)?function\s+([a-z][A-Za-z0-9_]*[A-Z][A-Za-z0-9_]*)\b/gm;
+
+  /** 递归扫描 Agent 源码，覆盖未从根入口暴露的内部模块 API。 */
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute_path = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(absolute_path);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
+      const content = strip_comments(fs.readFileSync(absolute_path, "utf8"));
+      for (const match of content.matchAll(camel_export_pattern)) {
+        failures.push(`${path.relative(source_root, absolute_path)}: ${match[1]}`);
+      }
+    }
+  }
+
+  visit(source_root);
+  assert.deepEqual(failures, []);
+});

package/scripts/remote-session-reconnect.test.mjs

@@ -28,7 +28,7 @@ test("RemoteSession reconnects the event pump after transport close", async () =
       throw new Error("unused");
     },
     async stop() {
-      return { stopped: false, cancelledQueuedPrompts: 0, reason: "idle" };
+      return { stopped: false, cancelled_queued_prompts: 0, reason: "idle" };
     },
     async records() {
       throw new Error("unused");
@@ -41,15 +41,15 @@ test("RemoteSession reconnects the event pump after transport close", async () =
     },
   };
   const session = new RemoteSession(transport, {
-    agentId: "agent_test",
-    sessionId: "session_test",
-    messageCount: 0,
+    agent_id: "agent_test",
+    session_id: "session_test",
+    message_count: 0,
   });
 
   const first_turn = await session.prompt({ query: "first" });
   subscriptions[0].on_close(new Error("stream dropped"));
   assert.deepEqual(await first_turn.finished, {
-    turnId: "turn_1",
+    turn_id: "turn_1",
     text: "",
     success: false,
     error: "stream dropped",
@@ -72,18 +72,87 @@ test("RemoteSession reconnects the event pump after transport close", async () =
 
 test("RemoteSession queues compact through its transport", async () => {
   const compacted_session_ids = [];
+  let subscription;
   const transport = {
+    async subscribe(input) {
+      subscription = input;
+      input.on_ready();
+      return { close: async () => {} };
+    },
     async compact(session_id) {
       compacted_session_ids.push(session_id);
+      return { id: "compact_test" };
     },
   };
   const session = new RemoteSession(transport, {
-    agentId: "agent_test",
-    sessionId: "session_test",
-    messageCount: 0,
+    agent_id: "agent_test",
+    session_id: "session_test",
+    message_count: 0,
   });
 
-  await session.compact();
+  const handle = await session.compact();
 
   assert.deepEqual(compacted_session_ids, ["session_test"]);
+  assert.equal(handle.id, "compact_test");
+  assert.equal(handle.result, null);
+
+  subscription.on_event({
+    mutation_id: "compact-finish",
+    variant: "compact",
+    type: "finish",
+    session_id: "session_test",
+    compact_id: handle.id,
+    status: "completed",
+    compacted: false,
+    reason: "nothing_to_compact",
+    created_at: Date.now(),
+  });
+
+  assert.deepEqual(await handle.finished, {
+    compact_id: "compact_test",
+    success: true,
+    compacted: false,
+    reason: "nothing_to_compact",
+  });
+  assert.deepEqual(handle.result, await handle.finished);
+});
+
+test("RemoteSession preserves an early compact finish until transport returns", async () => {
+  let subscription;
+  const transport = {
+    async subscribe(input) {
+      subscription = input;
+      input.on_ready();
+      return { close: async () => {} };
+    },
+    async compact() {
+      subscription.on_event({
+        mutation_id: "compact-early-finish",
+        variant: "compact",
+        type: "finish",
+        session_id: "session_test",
+        compact_id: "compact_early",
+        status: "completed",
+        compacted: true,
+        reason: "compacted",
+        created_at: Date.now(),
+      });
+      return { id: "compact_early" };
+    },
+  };
+  const session = new RemoteSession(transport, {
+    agent_id: "agent_test",
+    session_id: "session_test",
+    message_count: 0,
+  });
+
+  const handle = await session.compact();
+
+  assert.deepEqual(handle.result, {
+    compact_id: "compact_early",
+    success: true,
+    compacted: true,
+    reason: "compacted",
+  });
+  assert.deepEqual(await handle.finished, handle.result);
 });