@downcity/agent 1.1.189 → 1.1.196

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/Executor.ts

@@ -22,11 +22,13 @@ import type { SessionContextComposer } from "@executor/composer/context/SessionC
 import type { SessionSystemComposer } from "@executor/composer/system/SessionSystemComposer.js";
 import { ExecutorInflightService } from "@executor/services/ExecutorInflightService.js";
 import { ExecutorRecoveryPolicy } from "@executor/services/ExecutorRecoveryPolicy.js";
+import { generateId } from "@/utils/Id.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { SessionExecutor } from "@/executor/types/SessionExecutor.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 import type {
   SessionExecuteInput,
   SessionRunResult,
@@ -360,6 +362,7 @@ export class Executor implements SessionExecutor {
     const composed_context = await this.contextComposer.compose(run_context);
     const tools = this.bind_run_scope_to_tools(composed_context.tools, run_context);
     const system = await this.systemComposer.resolve(run_context);
+    let compaction_operation_id = "";
 
     try {
       if (retry_count > 0) {
@@ -368,13 +371,33 @@ export class Executor implements SessionExecutor {
         });
       }
 
+      const emit_compaction_operation = async (
+        operation: AgentSessionOperationRecord,
+      ): Promise<void> => {
+        if (operation.status === "started") {
+          compaction_operation_id = operation.operationId;
+        }
+        await this.emitOperation(run_context, operation);
+      };
+
       await this.compactionComposer.run({
         historyStore: this.historyStore,
         model,
         system,
         retryCount: retry_count,
+        onOperation: emit_compaction_operation,
+      });
+    } catch (error) {
+      await this.emitOperation(run_context, {
+        operationId:
+          compaction_operation_id ||
+          `compacting:${this.sessionId}:failed:${Date.now()}:${generateId()}`,
+        name: "compacting",
+        status: "failed",
+        label: "Session history compact failed",
+        error: error instanceof Error ? error.message : String(error),
+        visible: false,
       });
-    } catch {
       // 压缩失败不阻断主流程，继续使用当前历史消息执行。
     }
 
@@ -469,6 +492,9 @@ export class Executor implements SessionExecutor {
       ...(typeof input?.onUiMessageChunkCallback === "function"
         ? { onUiMessageChunkCallback: input.onUiMessageChunkCallback }
         : {}),
+      ...(typeof input?.onOperationCallback === "function"
+        ? { onOperationCallback: input.onOperationCallback }
+        : {}),
       ...(input?.abortSignal ? { abortSignal: input.abortSignal } : {}),
       injectedUserMessages: Array.isArray(input?.injectedUserMessages)
         ? [...input.injectedUserMessages]
@@ -484,6 +510,28 @@ export class Executor implements SessionExecutor {
     };
   }
 
+  /**
+   * 发布一次 session operation。
+   */
+  private async emitOperation(
+    run_context: SessionRunContext,
+    operation: AgentSessionOperationRecord,
+  ): Promise<void> {
+    if (typeof run_context.onOperationCallback !== "function") return;
+    const operation_id =
+      String(operation.operationId || "").trim() ||
+      `operation:${this.sessionId}:${Date.now()}:${generateId()}`;
+    await run_context.onOperationCallback({
+      type: "operation",
+      sessionId: run_context.sessionId || this.sessionId,
+      ...operation,
+      operationId: operation_id,
+      ...(run_context.turnId && !operation.turnId
+        ? { turnId: run_context.turnId }
+        : {}),
+    });
+  }
+
   /**
    * 读取当前 session 模型。
    */

package/src/executor/composer/compaction/SessionCompactionComposer.ts

@@ -8,6 +8,7 @@
 
 import type { LanguageModel, SystemModelMessage } from "ai";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 /**
  * compaction Composer 执行输入。
@@ -32,6 +33,15 @@ export type SessionCompactionInput = {
    * 当前重试次数（由 Executor 递增）。
    */
   retryCount: number;
+
+  /**
+   * 可选 operation 发布回调。
+   *
+   * 说明（中文）
+   * - 默认 compaction Composer 可在真正开始压缩时发布 `compacting`。
+   * - 回调由上层 Session 负责转成订阅事件与 operation message。
+   */
+  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
 };
 
 /**

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.ts

@@ -79,6 +79,7 @@ export class JsonlSessionCompactionComposer implements SessionCompactionComposer
       maxInputTokensApprox: policy.maxInputTokensApprox,
       archiveOnCompact: policy.archiveOnCompact,
       compactRatio: policy.compactRatio,
+      ...(input.onOperation ? { onOperation: input.onOperation } : {}),
     });
   }
 

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionExecutor.ts

@@ -21,7 +21,9 @@ import type {
   SessionMessageV1,
   SessionMetadataV1,
 } from "@/executor/types/SessionMessages.js";
+import { isSessionOperationMessage } from "@/executor/types/SessionMessages.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 export type SessionCompactParams = {
   model: LanguageModel;
@@ -30,6 +32,7 @@ export type SessionCompactParams = {
   maxInputTokensApprox: number;
   archiveOnCompact: boolean;
   compactRatio: number;
+  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
 };
 
 type SessionCompactDeps = {
@@ -60,6 +63,19 @@ export async function compactSessionMessagesIfNeeded(
   params: SessionCompactParams,
 ): Promise<{ compacted: boolean; reason?: string }> {
   const logger = getLogger(deps.rootPath, "info");
+  const operation_id = `compacting:${deps.sessionId}:${Date.now()}:${generateId()}`;
+  let operation_started = false;
+
+  const publish_operation = async (
+    operation: Omit<AgentSessionOperationRecord, "operationId" | "name">,
+  ): Promise<void> => {
+    if (typeof params.onOperation !== "function") return;
+    await params.onOperation({
+      operationId: operation_id,
+      name: "compacting",
+      ...operation,
+    });
+  };
 
   // 算法阶段（中文）
   // phase 1：snapshot（短锁）
@@ -68,7 +84,9 @@ export async function compactSessionMessagesIfNeeded(
   let snapshot: SessionMessageV1[] = [];
   let snapshotTailId = "";
   await deps.withWriteLock(async () => {
-    snapshot = await deps.loadAll();
+    snapshot = (await deps.loadAll()).filter(
+      (message) => !isSessionOperationMessage(message),
+    );
     snapshotTailId =
       snapshot.length > 0
         ? String(snapshot[snapshot.length - 1].id || "")
@@ -100,6 +118,13 @@ export async function compactSessionMessagesIfNeeded(
   const older = snapshot.slice(0, compactCount);
   if (older.length === 0) return { compacted: false, reason: "nothing_to_compact" };
 
+  operation_started = true;
+  await publish_operation({
+    status: "started",
+    label: "Compacting session history",
+    progress: 0,
+  });
+
   const olderTextAll = extractPlainTextFromMessages(older);
   const maxOlderChars = 24_000;
   const olderText =
@@ -138,6 +163,12 @@ export async function compactSessionMessagesIfNeeded(
       },
     );
     summary = "（系统自动压缩：摘要生成失败，已丢弃更早历史，仅保留最近对话。）";
+    await publish_operation({
+      status: "progress",
+      label: "Compacting session history",
+      reason: "summary_fallback",
+      progress: 0.5,
+    });
   }
 
   const fromId = String(older[0]?.id || "");
@@ -159,10 +190,20 @@ export async function compactSessionMessagesIfNeeded(
     // snapshotTailId 用于 debug，不作为强一致性依赖。
     void snapshotTailId;
 
-    const currentCompactCount = resolveCompactCount(current.length, compactRatio);
-    const currentOlder = current.slice(0, currentCompactCount);
-    const currentKept = current.slice(currentCompactCount);
+    const current_model_messages = current.filter(
+      (message) => !isSessionOperationMessage(message),
+    );
+    const currentCompactCount = resolveCompactCount(
+      current_model_messages.length,
+      compactRatio,
+    );
+    const currentOlder = current_model_messages.slice(0, currentCompactCount);
     if (currentOlder.length === 0) return;
+    const compacted_ids = new Set(
+      currentOlder
+        .map((message) => String(message.id || "").trim())
+        .filter(Boolean),
+    );
 
     if (params.archiveOnCompact) {
       const archivePath = path.join(
@@ -181,7 +222,13 @@ export async function compactSessionMessagesIfNeeded(
       );
     }
 
-    const next = [summaryMsg, ...currentKept];
+    const next = [
+      summaryMsg,
+      ...current.filter((message) => {
+        const id = String(message.id || "").trim();
+        return !id || !compacted_ids.has(id);
+      }),
+    ];
 
     const messagesPath = deps.getMessagesFilePath();
     const tmp = messagesPath + ".tmp";
@@ -195,6 +242,18 @@ export async function compactSessionMessagesIfNeeded(
     });
   });
 
+  if (operation_started) {
+    await publish_operation({
+      status: "finished",
+      label: "Session history compacted",
+      progress: 1,
+      result: {
+        archiveId,
+        compactedCount: older.length,
+      },
+    });
+  }
+
   return { compacted: true };
 }
 

package/src/executor/composer/history/jsonl/JsonlSessionHistoryComposer.ts

@@ -8,7 +8,10 @@
  */
 
 import type { Tool } from "ai";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import {
+  isSessionOperationMessage,
+  type SessionMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type {
   SessionHistoryComposer,
@@ -91,6 +94,7 @@ export class JsonlSessionHistoryComposer implements SessionHistoryComposer {
           parts,
         };
       })
+      .filter((message) => !isSessionOperationMessage(message))
       .filter((message) => Array.isArray(message.parts) && message.parts.length > 0);
   }
 

package/src/executor/messages/SessionMessageCodec.ts

@@ -14,7 +14,10 @@ import {
   type Tool,
   type ToolSet,
 } from "ai";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import {
+  isSessionOperationMessage,
+  type SessionMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import {
   hydrateFileUrlPartsForModel,
   injectFilePartsFromAttachments,
@@ -77,9 +80,15 @@ export async function toModelMessages(
   // 空输入快速返回，避免调用转换器的额外开销。
   if (!Array.isArray(messages) || messages.length === 0) return [];
 
+  // operation message 只服务前端时间线，不能传入模型。
+  const model_messages = messages.filter(
+    (message) => !isSessionOperationMessage(message),
+  );
+  if (model_messages.length === 0) return [];
+
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。
   const enrichedMessages = await injectFilePartsFromAttachments(
-    messages,
+    model_messages,
     projectRoot,
   );
 

package/src/executor/store/history/SessionHistoryStore.ts

@@ -13,6 +13,7 @@ import type {
   SessionMetadataV1,
 } from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 /**
  * compact 输入参数。
@@ -47,6 +48,11 @@ export type SessionHistoryCompactInput = {
    * 前段压缩比例（0-1）。
    */
   compactRatio: number;
+
+  /**
+   * 可选 operation 发布回调。
+   */
+  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
 };
 
 /**
@@ -157,4 +163,25 @@ export interface SessionHistoryStore {
      */
     source?: "egress" | "compact";
   }): SessionMessageV1;
+
+  /**
+   * 构造 operation 消息。
+   */
+  operation(input: {
+    /**
+     * 当前 operation 结构化记录。
+     */
+    operation: AgentSessionOperationRecord;
+
+    /**
+     * 消息元信息（除 schema 字段、kind、source 与 operation 字段）。
+     */
+    metadata: Omit<SessionMetadataV1, "v" | "ts" | "kind" | "source" | "operation"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+
+    /**
+     * 可选消息 ID（默认自动生成）。
+     */
+    id?: string;
+  }): SessionMessageV1;
 }

package/src/executor/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -21,6 +21,7 @@ import type {
   SessionMessageV1,
   SessionMetadataV1,
 } from "@/executor/types/SessionMessages.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type { SessionHistoryPathOverrides } from "@/executor/types/SessionHistoryPaths.js";
@@ -435,6 +436,44 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     return system.filter((item) => item && typeof item === "object");
   }
 
+  private normalizeOperation(
+    operation: AgentSessionOperationRecord,
+  ): AgentSessionOperationRecord {
+    const operation_id = String(operation.operationId || "").trim() || generateId();
+    const name = String(operation.name || "").trim() || "operation";
+    const status = String(operation.status || "").trim();
+    const normalized_status: AgentSessionOperationRecord["status"] =
+      status === "started" ||
+      status === "progress" ||
+      status === "finished" ||
+      status === "skipped" ||
+      status === "failed"
+        ? status
+        : "progress";
+    return {
+      operationId: operation_id,
+      name,
+      status: normalized_status,
+      ...(typeof operation.turnId === "string" && operation.turnId.trim()
+        ? { turnId: operation.turnId.trim() }
+        : {}),
+      ...(typeof operation.label === "string" && operation.label.trim()
+        ? { label: operation.label.trim() }
+        : {}),
+      ...(typeof operation.reason === "string" && operation.reason.trim()
+        ? { reason: operation.reason.trim() }
+        : {}),
+      ...(typeof operation.progress === "number" && Number.isFinite(operation.progress)
+        ? { progress: Math.max(0, Math.min(1, operation.progress)) }
+        : {}),
+      ...(operation.result !== undefined ? { result: operation.result } : {}),
+      ...(typeof operation.error === "string" && operation.error.trim()
+        ? { error: operation.error.trim() }
+        : {}),
+      ...(operation.visible === false ? { visible: false } : {}),
+    };
+  }
+
   async compact(input: SessionHistoryCompactInput): Promise<{
     compacted: boolean;
     reason?: string;
@@ -471,6 +510,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         maxInputTokensApprox: input.maxInputTokensApprox,
         archiveOnCompact: input.archiveOnCompact,
         compactRatio: input.compactRatio,
+        ...(input.onOperation ? { onOperation: input.onOperation } : {}),
       },
     );
   }
@@ -633,4 +673,30 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
       parts: [{ type: "text", text: String(input.text ?? "") }],
     };
   }
+
+  operation(input: {
+    operation: AgentSessionOperationRecord;
+    metadata: Omit<SessionMetadataV1, "v" | "ts" | "kind" | "source" | "operation"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+    id?: string;
+  }): SessionMessageV1 {
+    const operation = this.normalizeOperation(input.operation);
+    const label = String(
+      operation.label || `${operation.name}: ${operation.status}`,
+    ).trim();
+    const { ts, ...metadata } = input.metadata;
+    return {
+      id: input.id || `op:${this.sessionId}:${operation.operationId}:${generateId()}`,
+      role: "assistant",
+      metadata: {
+        v: 1,
+        ts: typeof ts === "number" ? ts : Date.now(),
+        ...metadata,
+        source: "operation",
+        kind: "operation",
+        operation,
+      },
+      parts: [{ type: "text", text: label }],
+    };
+  }
 }

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,
     });

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

@@ -12,42 +12,59 @@ import type {
   PluginCallInput,
   PluginReadInput,
 } from "@/executor/tools/plugin/types/PluginTool.js";
+import type {
+  AgentPluginTools,
+  CreatePluginToolsOptions,
+} from "@/types/plugin/PluginToolRuntime.js";
 import {
   invokePluginCallTool,
   invokePluginReadTool,
-  setPluginToolRuntime,
 } from "./PluginToolBridge.js";
 import {
   plugin_call_input_schema,
   plugin_read_input_schema,
 } from "./PluginToolSchemas.js";
 
-export { setPluginToolRuntime } from "./PluginToolBridge.js";
-
 /**
- * `plugin_call`：调用已注册 plugin action。
+ * 创建 `plugin_call`：调用当前 Agent 已注册 plugin action。
  */
-export const plugin_call = tool({
-  description:
-    "Call a registered agent plugin action. Use plugin_read first when you need the action list, input schema, or examples. Generated files may be attached to the final assistant message automatically.",
-  inputSchema: plugin_call_input_schema,
-  execute: async (input) => await invokePluginCallTool(input as PluginCallInput),
-});
+export function createPluginCallTool(options: CreatePluginToolsOptions) {
+  return tool({
+    description:
+      "Call a registered agent plugin action. Use plugin_read first when you need the action list, input schema, or examples. Generated files may be attached to the final assistant message automatically.",
+    inputSchema: plugin_call_input_schema,
+    execute: async (input) =>
+      await invokePluginCallTool({
+        plugins: options.plugins,
+        input: input as PluginCallInput,
+      }),
+  });
+}
 
 /**
- * `plugin_read`：读取已注册 plugin / action metadata。
+ * 创建 `plugin_read`：读取当前 Agent 已注册 plugin / action metadata。
  */
-export const plugin_read = tool({
-  description:
-    "Read registered agent plugin metadata, including action names, descriptions, input schemas, and examples. Use this before plugin_call when the payload shape is unclear.",
-  inputSchema: plugin_read_input_schema,
-  execute: async (input) => await invokePluginReadTool(input as PluginReadInput),
-});
+export function createPluginReadTool(options: CreatePluginToolsOptions) {
+  return tool({
+    description:
+      "Read registered agent plugin metadata, including action names, descriptions, input schemas, and examples. Use this before plugin_call when the payload shape is unclear.",
+    inputSchema: plugin_read_input_schema,
+    execute: async (input) =>
+      await invokePluginReadTool({
+        plugins: options.plugins,
+        input: input as PluginReadInput,
+      }),
+  });
+}
 
 /**
- * Plugin 工具导出集合。
+ * 创建当前 Agent 专属 Plugin 工具集合。
  */
-export const plugin_tools = {
-  plugin_call,
-  plugin_read,
-};
+export function createPluginTools(
+  options: CreatePluginToolsOptions,
+): AgentPluginTools {
+  return {
+    plugin_call: createPluginCallTool(options),
+    plugin_read: createPluginReadTool(options),
+  };
+}