@easynet/agent-tool 1.0.46 → 1.0.47

package/README.md

@@ -1,127 +1,53 @@
 # @easynet/agent-tool
 
-Agent tool runtime: unified registration, policy, budget, and observability. Multiple tool sources; expose as LangChain tools, MCP service, or OpenAPI HTTP.
+工具运行时包。最小目标：从 `tool.yaml` 生成可给 LangChain 使用的 tools。
 
-## Capabilities
+## 最小接口
 
-| Category | Name | Description |
-|----------|------|-------------|
-| **Tool sources** | `@tool` functions | Annotated tool functions in TS/JS |
-| | SKILL | Skills described in SKILL.md |
-| | n8n workflows | Workflow nodes as tools |
-| | MCP service | Remote tools via MCP protocol |
-| | LangChain directory | LangChain-format tool directory |
-| **Runtime** | PTCRuntime | Tool invocation execution |
-| | Policy engine | Pre-execution policy checks |
-| | Schema validation | Input/output validation |
-| | Budget | Call quotas and limits |
-| | Retry | Automatic retry for retryable errors |
-| | Evidence | Call logging and audit |
-| **Exposure** | LangChain tools | For createReactAgent / AgentExecutor |
-| | MCP service (stdio) | For Cursor / Claude etc. MCP clients |
-| | MCP service (Streamable HTTP) | HTTP + SSE, MCP Streamable HTTP (stateless) |
-| | OpenAPI HTTP (GET /tools, POST /invoke) | REST API for any HTTP client |
-
-## Install
-
-```bash
-npm i @easynet/agent-tool
-```
-
-## Usage
-
-### 1. CLI
-
-```bash
-# List tools from current project config
-npx agent-tool ls
-
-# Show tool details
-npx agent-tool describe <scope/name>
-
-# Run a tool locally
-npx agent-tool run <scope/name> '<{"key":"value"}>'
+```ts
+import { createAgentTools } from "@easynet/agent-tool/api";
 
-# MCP standalone package: init → build → serve
-npx agent-tool init
-npx agent-tool build --path . --out dist
-npx agent-tool serve --path dist
+const tools = createAgentTools({ configFilePath: "./tool.yaml", coreTools: {} });
+console.log(tools.map((t) => t.name));
 ```
 
-### 2. Configure tool.yaml
-
-Place `tool.yaml` at project root to list tools (used by `createAgentTools` and `agent-tool ls`). You can set **sandbox** and **HTTP host security** under `tools`. Host rule: allow iff (host in `allowedHosts`) AND (host not in `blockedHosts`). Lists are merged with programmatic config (union).
-
-**When nothing is set** (no allowedHosts/blockedHosts/sandboxedPath in tool.yaml and no `coreTools` passed in code), it is equivalent to: `allowedHosts: []`, `blockedHosts: []`, `sandboxRoot: process.cwd()`. That means **no HTTP access is allowed** (all HTTP tools will error), and FS tools use the current directory as sandbox. To enable HTTP tools, configure `allowedHosts` (e.g. `["*"]` or specific hostnames).
+## 最小 `tool.yaml`
 
 ```yaml
 tools:
-  sandboxedPath: ~/.agent/sandbox   # fs tools only access this dir
-  allowedHosts: ["*"]              # allow all; or ["api.github.com", "api.duckduckgo.com"]
-  blockedHosts: []                 # optional; block these even if allowed (e.g. ["*.internal"])
-  blockedCidrs: []                  # optional; CIDR blocklist for resolved IPs
-  list:
-    - npm:@easynet/agent-tool-builtin#fs.readText
-    - npm:@easynet/agent-tool-builtin#fs.writeText
-    # ...
-```
+  # FS 工具沙箱根目录（相对路径按当前项目解析）
+  sandboxedPath: .
 
-### 3. Programmatic: LangChain tools
+  # HTTP 允许列表。先给空数组，表示默认禁用外网请求（更安全）
+  allowedHosts: []
+  blockedHosts: []
 
-```ts
-import { createAgentTools } from "@easynet/agent-tool/api";
-
-const tools = createAgentTools({ configFilePath: "tool.yaml", coreTools: {} });
-// Use with createReactAgent / AgentExecutor
-```
-
-### 4. Programmatic: MCP service (stdio)
-
-```ts
-import { createMCPServer, createRuntimeFromConfigSync } from "@easynet/agent-tool/api";
-
-const { runtime } = createRuntimeFromConfigSync({ coreTools: {} });
-const server = createMCPServer(runtime);
-// runMCPServerOverStdio(server) or attach to stdio
+  # 最小起步：直接加载内置工具包（全部工具）
+  list:
+    - npm:@easynet/agent-tool-buildin
 ```
 
-### 5. Programmatic: MCP service (Streamable HTTP)
+## 最简单示例（带注释）
 
 ```ts
-import { createMCPStreamableHttpHandler, createMCPServerStreamableHttp, createRuntimeFromConfigSync } from "@easynet/agent-tool/api";
-
-const { runtime } = createRuntimeFromConfigSync({ coreTools: {} });
-
-// Option A: handler only, mount on your HTTP server (use express.json() for body)
-const handler = createMCPStreamableHttpHandler(runtime);
-// app.use(express.json()); app.post("/mcp", handler);
+import { createAgentTools } from "@easynet/agent-tool/api";
 
-// Option B: get Express app and start
-const { app, path, listen } = await createMCPServerStreamableHttp(runtime, { path: "/mcp", port: 3000 });
-const { url } = await listen(3000);
-// Client: POST http://127.0.0.1:3000/mcp (MCP Streamable HTTP: SSE + direct response)
-```
+async function main() {
+  // 1) 从 tool.yaml 创建 LangChain tools
+  const tools = createAgentTools({
+    configFilePath: "./tool.yaml",
+    coreTools: {},
+  });
 
-### 6. Programmatic: OpenAPI HTTP
+  // 2) 打印工具名，确认加载成功
+  console.log("loaded tools:", tools.map((t) => t.name));
+}
 
-```ts
-import { createOpenAPIServer, createRuntimeFromConfigSync } from "@easynet/agent-tool/api";
-
-const { runtime } = createRuntimeFromConfigSync({ coreTools: {} });
-const { app } = createOpenAPIServer(runtime, { basePath: "/api" });
-// Express-compatible app: GET /api/tools, POST /api/invoke
+main().catch(console.error);
 ```
 
-## Entrypoints
-
-| Entry | Purpose |
-|-------|---------|
-| `@easynet/agent-tool` | Core types, Runtime, Registry, discovery, MCP client, extensions |
-| `@easynet/agent-tool/api` | createAgentTools, createMCPServer, createMCPStreamableHttpHandler, createMCPServerStreamableHttp, createOpenAPIServer, createRuntimeFromConfig |
-| `@easynet/agent-tool/core` | PTCRuntime, PolicyEngine, SchemaValidator, ToolSpec, etc. |
-| `@easynet/agent-tool/runtime` | Same as core runtime subpath |
-
-## Requirements
+## 进阶能力
 
-- Node.js >= 18
-- For LangChain: install `langchain`, `@langchain/core`, `zod`. For MCP: install `@modelcontextprotocol/sdk` (see package peerDependencies).
+- MCP 服务：`createMCPServer(...)`
+- OpenAPI HTTP：`createOpenAPIServer(...)`
+- 扩展开发：`createExtension(...)`、`generateManifest(...)`

package/dist/api/extension/groupPrefix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"groupPrefix.d.ts","sourceRoot":"","sources":["../../../src/api/extension/groupPrefix.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,mFAAmF;IACnF,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,wBAAwB,CAS1F"}
+{"version":3,"file":"groupPrefix.d.ts","sourceRoot":"","sources":["../../../src/api/extension/groupPrefix.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,mFAAmF;IACnF,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,wBAAwB,CAW1F"}

package/dist/api/main.cjs

@@ -1,8 +1,7 @@
 'use strict';
 
-var chunkQW27JAFS_cjs = require('../chunk-QW27JAFS.cjs');
-var chunkO4XXNLNE_cjs = require('../chunk-O4XXNLNE.cjs');
-var chunkXC7KPJLZ_cjs = require('../chunk-XC7KPJLZ.cjs');
+var chunkIAEVDXWS_cjs = require('../chunk-IAEVDXWS.cjs');
+var chunkA5B6Q6EG_cjs = require('../chunk-A5B6Q6EG.cjs');
 require('../chunk-TOSPHMYU.cjs');
 require('../chunk-DYDNPIV2.cjs');
 require('../chunk-UUNG3GL3.cjs');
@@ -11,47 +10,47 @@ require('../chunk-UUNG3GL3.cjs');
 
 Object.defineProperty(exports, "createAgentTools", {
   enumerable: true,
-  get: function () { return chunkQW27JAFS_cjs.createAgentTools; }
+  get: function () { return chunkIAEVDXWS_cjs.createAgentTools; }
 });
 Object.defineProperty(exports, "createLangChainToolsAsync", {
   enumerable: true,
-  get: function () { return chunkQW27JAFS_cjs.createLangChainToolsAsync; }
+  get: function () { return chunkIAEVDXWS_cjs.createLangChainToolsAsync; }
+});
+Object.defineProperty(exports, "PTCRuntime", {
+  enumerable: true,
+  get: function () { return chunkA5B6Q6EG_cjs.PTCRuntime; }
 });
 Object.defineProperty(exports, "createHttpService", {
   enumerable: true,
-  get: function () { return chunkO4XXNLNE_cjs.createHttpService; }
+  get: function () { return chunkA5B6Q6EG_cjs.createHttpService; }
 });
 Object.defineProperty(exports, "createMCPServer", {
   enumerable: true,
-  get: function () { return chunkO4XXNLNE_cjs.createMCPServer; }
+  get: function () { return chunkA5B6Q6EG_cjs.createMCPServer; }
 });
 Object.defineProperty(exports, "createMCPServerStreamableHttp", {
   enumerable: true,
-  get: function () { return chunkO4XXNLNE_cjs.createMCPServerStreamableHttp; }
+  get: function () { return chunkA5B6Q6EG_cjs.createMCPServerStreamableHttp; }
 });
 Object.defineProperty(exports, "createMCPStreamableHttpHandler", {
   enumerable: true,
-  get: function () { return chunkO4XXNLNE_cjs.createMCPStreamableHttpHandler; }
+  get: function () { return chunkA5B6Q6EG_cjs.createMCPStreamableHttpHandler; }
 });
 Object.defineProperty(exports, "createOpenAPIServer", {
   enumerable: true,
-  get: function () { return chunkO4XXNLNE_cjs.createHttpService; }
-});
-Object.defineProperty(exports, "runMCPServerOverStdio", {
-  enumerable: true,
-  get: function () { return chunkO4XXNLNE_cjs.runMCPServerOverStdio; }
-});
-Object.defineProperty(exports, "PTCRuntime", {
-  enumerable: true,
-  get: function () { return chunkXC7KPJLZ_cjs.PTCRuntime; }
+  get: function () { return chunkA5B6Q6EG_cjs.createHttpService; }
 });
 Object.defineProperty(exports, "createRuntimeFromConfig", {
   enumerable: true,
-  get: function () { return chunkXC7KPJLZ_cjs.createRuntimeFromConfig; }
+  get: function () { return chunkA5B6Q6EG_cjs.createRuntimeFromConfig; }
 });
 Object.defineProperty(exports, "createRuntimeFromConfigSync", {
   enumerable: true,
-  get: function () { return chunkXC7KPJLZ_cjs.createRuntimeFromConfigSync; }
+  get: function () { return chunkA5B6Q6EG_cjs.createRuntimeFromConfigSync; }
+});
+Object.defineProperty(exports, "runMCPServerOverStdio", {
+  enumerable: true,
+  get: function () { return chunkA5B6Q6EG_cjs.runMCPServerOverStdio; }
 });
 //# sourceMappingURL=main.cjs.map
 //# sourceMappingURL=main.cjs.map

package/dist/api/main.js

@@ -1,6 +1,5 @@
-export { createAgentTools, createLangChainToolsAsync } from '../chunk-H66TKSG4.js';
-export { createHttpService, createMCPServer, createMCPServerStreamableHttp, createMCPStreamableHttpHandler, createHttpService as createOpenAPIServer, runMCPServerOverStdio } from '../chunk-YDYG4HF5.js';
-export { PTCRuntime, createRuntimeFromConfig, createRuntimeFromConfigSync } from '../chunk-5GFSI7ZJ.js';
+export { createAgentTools, createLangChainToolsAsync } from '../chunk-KYBIKD5R.js';
+export { PTCRuntime, createHttpService, createMCPServer, createMCPServerStreamableHttp, createMCPStreamableHttpHandler, createHttpService as createOpenAPIServer, createRuntimeFromConfig, createRuntimeFromConfigSync, runMCPServerOverStdio } from '../chunk-2ZPDD7ZO.js';
 import '../chunk-ZRHPGW7W.js';
 import '../chunk-KDB3MY2H.js';
 import '../chunk-NTWOVFEY.js';

package/dist/api/runtimeFromConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeFromConfig.d.ts","sourceRoot":"","sources":["../../src/api/runtimeFromConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AA0B3D;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,EAAO,CAAC;AAEvD,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,8PAA8P;IAC9P,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,qKAAqK;IACrK,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,oEAAoE;IACpE,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAqFD,qKAAqK;AACrK,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQjG;AAiMD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CA2CnG;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAoB9B"}
+{"version":3,"file":"runtimeFromConfig.d.ts","sourceRoot":"","sources":["../../src/api/runtimeFromConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AA0B3D;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,EAAO,CAAC;AAEvD,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,8PAA8P;IAC9P,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,qKAAqK;IACrK,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,oEAAoE;IACpE,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAqFD,qKAAqK;AACrK,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQjG;AAkMD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CA2CnG;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAoB9B"}