@downcity/agent 1.1.195 → 1.1.196

package/bin/types/plugin/PluginToolRuntime.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Plugin tool runtime 绑定类型。
+ *
+ * 关键点（中文）
+ * - plugin_call / plugin_read 必须绑定当前 Agent 自己的 plugin registry。
+ * - 这些类型描述 tool 工厂与 bridge 调用时需要的显式 runtime 依赖。
+ */
+import type { Tool } from "ai";
+import type { AgentPlugins } from "../../types/plugin/PluginRuntime.js";
+import type { PluginCallInput, PluginReadInput } from "../../executor/tools/plugin/types/PluginTool.js";
+/**
+ * 创建 plugin tools 的参数。
+ */
+export interface CreatePluginToolsOptions {
+    /**
+     * 当前 Agent 自己的 plugin 调用面。
+     *
+     * 关键点（中文）
+     * - 该引用必须来自当前 Agent 装配出的 plugin registry。
+     * - tool 执行时只能通过它访问 plugin，避免跨 Agent 读到其他 registry。
+     */
+    plugins: AgentPlugins;
+}
+/**
+ * 当前 Agent 专属 plugin tools。
+ */
+export interface AgentPluginTools {
+    /**
+     * 读取 plugin metadata 的模型工具。
+     *
+     * 关键点（中文）
+     * - 该 tool 通过闭包绑定当前 Agent 的 `plugins`。
+     * - 不读取任何模块级全局 runtime。
+     */
+    plugin_read: Tool;
+    /**
+     * 执行 plugin action 的模型工具。
+     *
+     * 关键点（中文）
+     * - 该 tool 通过闭包绑定当前 Agent 的 `plugins`。
+     * - 多 Agent 并发时，每个 Agent 都有自己的 tool 实例。
+     */
+    plugin_call: Tool;
+}
+/**
+ * 调用 plugin_call bridge 的参数。
+ */
+export interface InvokePluginCallToolOptions {
+    /**
+     * 当前 Agent 自己的 plugin 调用面。
+     *
+     * 关键点（中文）
+     * - 由 Agent 级 tool 工厂注入。
+     * - 不能在 bridge 内通过全局变量读取。
+     */
+    plugins: AgentPlugins;
+    /**
+     * 模型提交给 plugin_call 的结构化输入。
+     */
+    input: PluginCallInput;
+}
+/**
+ * 调用 plugin_read bridge 的参数。
+ */
+export interface InvokePluginReadToolOptions {
+    /**
+     * 当前 Agent 自己的 plugin 调用面。
+     */
+    plugins: AgentPlugins;
+    /**
+     * 模型提交给 plugin_read 的结构化输入。
+     */
+    input: PluginReadInput;
+}
+//# sourceMappingURL=PluginToolRuntime.d.ts.map

package/bin/types/plugin/PluginToolRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginToolRuntime.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/PluginToolRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAChB,MAAM,6CAA6C,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,WAAW,EAAE,IAAI,CAAC;IAElB;;;;;;OAMG;IACH,WAAW,EAAE,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;OAMG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,KAAK,EAAE,eAAe,CAAC;CACxB"}

package/bin/types/plugin/PluginToolRuntime.js

@@ -0,0 +1,9 @@
+/**
+ * Plugin tool runtime 绑定类型。
+ *
+ * 关键点（中文）
+ * - plugin_call / plugin_read 必须绑定当前 Agent 自己的 plugin registry。
+ * - 这些类型描述 tool 工厂与 bridge 调用时需要的显式 runtime 依赖。
+ */
+export {};
+//# sourceMappingURL=PluginToolRuntime.js.map

package/bin/types/plugin/PluginToolRuntime.js.map

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

package/package.json

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

package/scripts/agent-ready.test.mjs

@@ -0,0 +1,168 @@
+/**
+ * @file 验证 session.prompt 会等待当前 Agent 后台能力 ready。
+ *
+ * 关键点（中文）
+ * - 这里走编译后的公开 SDK，覆盖宿主真实入口。
+ * - plugin lifecycle 未完成前，session.prompt 不应进入模型执行。
+ */
+
+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 { MockLanguageModelV3 } from "ai/test";
+import { Agent } from "../bin/index.js";
+import { createPlugin } from "../bin/plugin/core/PluginActionFactory.js";
+
+function create_deferred() {
+  let resolve;
+  const promise = new Promise((inner_resolve) => {
+    resolve = inner_resolve;
+  });
+  return {
+    promise,
+    resolve,
+  };
+}
+
+async function is_settled(promise) {
+  const marker = {};
+  const result = await Promise.race([
+    promise.then(
+      () => true,
+      () => true,
+    ),
+    new Promise((resolve) => setTimeout(() => resolve(marker), 0)),
+  ]);
+  return result !== marker;
+}
+
+function create_stream_text_result(text) {
+  return {
+    stream: new ReadableStream({
+      start(controller) {
+        controller.enqueue({
+          type: "stream-start",
+          warnings: [],
+        });
+        controller.enqueue({
+          type: "text-start",
+          id: "text_1",
+        });
+        controller.enqueue({
+          type: "text-delta",
+          id: "text_1",
+          delta: text,
+        });
+        controller.enqueue({
+          type: "text-end",
+          id: "text_1",
+        });
+        controller.enqueue({
+          type: "finish",
+          finishReason: {
+            unified: "stop",
+            raw: "stop",
+          },
+          usage: {
+            inputTokens: {
+              total: 0,
+              noCache: 0,
+              cacheRead: 0,
+              cacheWrite: 0,
+            },
+            outputTokens: {
+              total: 0,
+              text: 0,
+              reasoning: 0,
+            },
+          },
+        });
+        controller.close();
+      },
+    }),
+  };
+}
+
+test("session.prompt waits for agent background ready before model execution", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-ready-"),
+  );
+  const lifecycle_ready = create_deferred();
+  let model_stream_calls = 0;
+
+  const blocking_plugin = createPlugin({
+    name: "blocking",
+    title: "Blocking",
+    description: "Blocks lifecycle start until the test releases it",
+    lifecycle: {
+      start: async () => {
+        await lifecycle_ready.promise;
+      },
+    },
+  });
+  const model = new MockLanguageModelV3({
+    modelId: "agent-ready-model",
+    doStream: async () => {
+      model_stream_calls += 1;
+      return create_stream_text_result("ready");
+    },
+    doGenerate: async () => ({
+      content: [
+        {
+          type: "text",
+          text: "Ready title",
+        },
+      ],
+      finishReason: {
+        unified: "stop",
+        raw: "stop",
+      },
+      usage: {
+        inputTokens: {
+          total: 0,
+          noCache: 0,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+        outputTokens: {
+          total: 0,
+          text: 0,
+          reasoning: 0,
+        },
+      },
+      warnings: [],
+    }),
+  });
+  const agent = new Agent({
+    id: "ready_agent",
+    path: agent_path,
+    plugins: [blocking_plugin],
+    model,
+  });
+
+  try {
+    const session = await agent.session_collection().create_session({
+      sessionId: "ready_session",
+    });
+    const prompt_promise = session.prompt({
+      query: "hello",
+    });
+
+    assert.equal(await is_settled(prompt_promise), false);
+    assert.equal(model_stream_calls, 0);
+
+    lifecycle_ready.resolve();
+    const turn = await prompt_promise;
+    const result = await turn.finished;
+
+    assert.equal(result.success, true);
+    assert.equal(model_stream_calls, 1);
+  } finally {
+    lifecycle_ready.resolve();
+    await agent.dispose();
+  }
+});
+

package/scripts/plugin-tool-bridge.test.mjs

@@ -15,8 +15,8 @@ import fs from "node:fs/promises";
 import {
   invokePluginCallTool,
   invokePluginReadTool,
-  setPluginToolRuntime,
 } from "../bin/executor/tools/plugin/PluginToolBridge.js";
+import { createPluginTools } from "../bin/executor/tools/plugin/PluginToolDefinition.js";
 import { withSessionRunScope } from "../bin/executor/SessionRunScope.js";
 import { createAction, createPlugin } from "../bin/plugin/core/PluginActionFactory.js";
 import { createAgentPluginRegistry } from "../bin/agent/local/AgentPluginFactory.js";
@@ -38,7 +38,7 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
   );
   const bytes = Buffer.from("png-bytes-for-plugin-tool", "utf8");
 
-  setPluginToolRuntime({
+  const plugins = {
     list: () => [],
     read: () => ({ plugins: [] }),
     availability: async () => ({ enabled: true, available: true, reasons: [] }),
@@ -64,14 +64,17 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
     resolve: async () => {
       throw new Error("not implemented");
     },
-  });
+  };
 
   const run_context = create_run_context(project_root);
   const result = await withSessionRunScope({ runContext: run_context }, () =>
     invokePluginCallTool({
-      plugin: "image",
-      action: "image_result",
-      payload: { job_id: "img_1" },
+      plugins,
+      input: {
+        plugin: "image",
+        action: "image_result",
+        payload: { job_id: "img_1" },
+      },
     }),
   );
 
@@ -93,7 +96,7 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
 });
 
 test("invokePluginReadTool returns plugin action metadata", async () => {
-  setPluginToolRuntime({
+  const plugins = {
     list: () => [],
     read: () => ({
       name: "image",
@@ -130,11 +133,14 @@ test("invokePluginReadTool returns plugin action metadata", async () => {
     resolve: async () => {
       throw new Error("not implemented");
     },
-  });
+  };
 
   const result = await invokePluginReadTool({
-    plugin: "image",
-    action: "image_create",
+    plugins,
+    input: {
+      plugin: "image",
+      action: "image_create",
+    },
   });
 
   assert.equal(result.success, true);
@@ -174,6 +180,7 @@ test("PluginRegistry validates action payload with metadata schema", async () =>
   });
   const registry = createAgentPluginRegistry({
     plugins: [plugin],
+    plugin_instances: new Map(),
     get_context: () => ({ rootPath: process.cwd() }),
   });
 
@@ -197,3 +204,100 @@ test("PluginRegistry validates action payload with metadata schema", async () =>
   assert.equal(valid.success, true);
   assert.equal(valid.data.text, "hello");
 });
+
+test("createPluginTools binds plugin_call to the current registry", async () => {
+  function create_owner_registry(owner) {
+    const plugin = createPlugin({
+      name: "skill",
+      title: `Skill ${owner}`,
+      description: "Owner scoped skill plugin",
+      actions: {
+        lookup: createAction({
+          description: "Return registry owner",
+          execute: async () => ({
+            success: true,
+            data: { owner },
+            message: owner,
+          }),
+        }),
+      },
+    });
+    return createAgentPluginRegistry({
+      plugins: [plugin],
+      plugin_instances: new Map(),
+      get_context: () => ({ rootPath: process.cwd() }),
+    });
+  }
+
+  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 result_a = await tools_a.plugin_call.execute({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "anything" },
+  });
+  const result_b = await tools_b.plugin_call.execute({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "anything" },
+  });
+
+  assert.equal(result_a.success, true);
+  assert.equal(result_a.data.value.owner, "agent_a");
+  assert.equal(result_b.success, true);
+  assert.equal(result_b.data.value.owner, "agent_b");
+});
+
+test("PluginRegistry keeps plugin ready after action business failure", async () => {
+  let call_count = 0;
+  const plugin = createPlugin({
+    name: "skill",
+    title: "Skill",
+    description: "Retryable skill plugin",
+    actions: {
+      lookup: createAction({
+        description: "Fail once then succeed",
+        execute: async () => {
+          call_count += 1;
+          if (call_count === 1) {
+            return {
+              success: false,
+              error: "Skill not found: missing",
+              message: "Skill not found: missing",
+            };
+          }
+          return {
+            success: true,
+            data: { loaded: true },
+            message: "loaded",
+          };
+        },
+      }),
+    },
+  });
+  const registry = createAgentPluginRegistry({
+    plugins: [plugin],
+    plugin_instances: new Map(),
+    get_context: () => ({ rootPath: process.cwd() }),
+  });
+
+  const failed = await registry.runAction({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "missing" },
+  });
+  assert.equal(failed.success, false);
+  assert.equal(registry.status("skill").state, "ready");
+
+  const retry = await registry.runAction({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "exists" },
+  });
+  assert.equal(retry.success, true);
+  assert.equal(retry.data.loaded, true);
+  assert.equal(registry.status("skill").state, "ready");
+});

package/src/agent/local/Agent.ts

@@ -90,14 +90,14 @@ export class Agent {
     this.instruction = assembly.instruction;
     this.shell = assembly.shell;
 
-    this.sessionManager = this.create_session_manager(assembly);
-    session_manager_ref = this.sessionManager;
     // 关键点（中文）：构造完成即触发后台能力启动；调用方可 `await agent.ready()` 等待。
     this.backgroundService = new AgentBackgroundService({
       logger: this.logger,
       agent_context: this.agentContext,
       get_shell: () => this.shell,
     });
+    this.sessionManager = this.create_session_manager(assembly);
+    session_manager_ref = this.sessionManager;
   }
 
   /**
@@ -269,6 +269,9 @@ export class Agent {
       get_agent_context: () => this.agentContext ?? assembly.agent_context,
       get_instruction: () => this.instruction,
       plugin_instances: assembly.plugin_instances,
+      ensure_agent_ready: async () => {
+        await this.backgroundService.ready();
+      },
       default_model: this.defaultModel,
       SessionClass: this.SessionClass,
     });

package/src/agent/local/services/AgentAssemblyService.ts

@@ -28,8 +28,7 @@ import {
   createAgentPluginConfigRuntime,
 } from "@/agent/local/AgentRuntimeAssembly.js";
 import {
-  plugin_tools,
-  setPluginToolRuntime,
+  createPluginTools,
 } from "@executor/tools/plugin/PluginToolDefinition.js";
 import type { AgentManagedSession } from "@/types/agent/AgentTypes.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
@@ -183,6 +182,7 @@ export class AgentAssemblyService {
     });
     const plugins = plugin_registry;
     if (this.should_register_plugin_call_tool(plugin_instances)) {
+      const plugin_tools = createPluginTools({ plugins });
       tools.plugin_read = tools.plugin_read || plugin_tools.plugin_read;
       tools.plugin_call = tools.plugin_call || plugin_tools.plugin_call;
     }
@@ -228,7 +228,6 @@ export class AgentAssemblyService {
       });
       Object.assign(tools, shell.tools);
     }
-    setPluginToolRuntime(plugins);
 
     return {
       id,

package/src/agent/local/services/AgentSessionManager.ts

@@ -87,6 +87,11 @@ type AgentSessionManagerOptions = {
    */
   plugin_instances: Map<string, Plugin>;
 
+  /**
+   * 等待当前 Agent 后台能力启动完成。
+   */
+  ensure_agent_ready: () => Promise<void>;
+
   /**
    * 当前默认模型实例。
    */
@@ -109,6 +114,7 @@ export class AgentSessionManager {
   private readonly get_agent_context: AgentSessionManagerOptions["get_agent_context"];
   private readonly get_instruction: AgentSessionManagerOptions["get_instruction"];
   private readonly plugin_instances: Map<string, Plugin>;
+  private readonly ensure_agent_ready: AgentSessionManagerOptions["ensure_agent_ready"];
   private readonly default_model?: AgentModel;
   private readonly SessionClass: AgentSessionConstructor;
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
@@ -123,6 +129,7 @@ export class AgentSessionManager {
     this.get_agent_context = options.get_agent_context;
     this.get_instruction = options.get_instruction;
     this.plugin_instances = options.plugin_instances;
+    this.ensure_agent_ready = options.ensure_agent_ready;
     this.default_model = options.default_model;
     this.SessionClass = options.SessionClass || Session;
     this.session_collection = {
@@ -350,6 +357,7 @@ export class AgentSessionManager {
       getManagedPluginSystemBlocks: async () => [],
       getPluginSystemBlocks: async () => await this.load_plugin_system_blocks(),
       ensureConfigured: async (session) => {
+        await this.ensure_agent_ready();
         await this.apply_session_defaults(session);
       },
     });

package/src/executor/tools/plugin/PluginToolBridge.ts

@@ -10,7 +10,6 @@
 import path from "node:path";
 import type { FileUIPart } from "ai";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
   PluginCallInput,
   PluginCallToolFileResult,
@@ -18,6 +17,10 @@ import type {
   PluginReadInput,
   PluginReadToolResult,
 } from "@/executor/tools/plugin/types/PluginTool.js";
+import type {
+  InvokePluginCallToolOptions,
+  InvokePluginReadToolOptions,
+} from "@/types/plugin/PluginToolRuntime.js";
 import {
   materializeAssistantFileParts,
   resolveAgentFilePath,
@@ -27,25 +30,6 @@ import {
   getSessionRunContext,
 } from "@executor/SessionRunScope.js";
 
-let plugin_tool_runtime: AgentPlugins | null = null;
-
-/**
- * 注入 plugin tool 运行时。
- */
-export function setPluginToolRuntime(next: AgentPlugins): void {
-  plugin_tool_runtime = next;
-}
-
-/**
- * 读取已注入的 plugin tool 运行时。
- */
-function require_plugin_tool_runtime(): AgentPlugins {
-  if (plugin_tool_runtime) return plugin_tool_runtime;
-  throw new Error(
-    "Plugin tool runtime is not initialized. Ensure agent assembly completed before using plugin_call.",
-  );
-}
-
 /**
  * 判断值是否为普通对象。
  */
@@ -126,8 +110,9 @@ function summarize_action_data(data: JsonValue | undefined): JsonObject | undefi
  * 调用 plugin action 并桥接最终 assistant file parts。
  */
 export async function invokePluginCallTool(
-  input: PluginCallInput,
+  params: InvokePluginCallToolOptions,
 ): Promise<PluginCallToolResult> {
+  const input: PluginCallInput = params.input;
   const plugin = String(input.plugin || "").trim();
   const action = String(input.action || "").trim();
   const payload = to_json_object(input.payload ?? {}) ?? {};
@@ -153,8 +138,7 @@ export async function invokePluginCallTool(
   }
 
   try {
-    const runtime = require_plugin_tool_runtime();
-    const result = await runtime.runAction({
+    const result = await params.plugins.runAction({
       plugin,
       action,
       payload,
@@ -203,11 +187,11 @@ export async function invokePluginCallTool(
  * 读取 plugin / action metadata。
  */
 export async function invokePluginReadTool(
-  input: PluginReadInput,
+  params: InvokePluginReadToolOptions,
 ): Promise<PluginReadToolResult> {
+  const input: PluginReadInput = params.input;
   try {
-    const runtime = require_plugin_tool_runtime();
-    const data = runtime.read({
+    const data = params.plugins.read({
       plugin: typeof input.plugin === "string" ? input.plugin : undefined,
       action: typeof input.action === "string" ? input.action : undefined,
     });