@easynet/agent-tool 1.0.99 → 1.0.101

package/README.md

@@ -2,46 +2,47 @@
 
 ## Introduction
 
-`@easynet/agent-tool` loads tool definitions from `tool.yaml`, creates LangChain-compatible tools, and registers them into the default `AgentContext`.
+`@easynet/agent-tool` loads `tool.yaml`, resolves tool extensions into LangChain-compatible tools, and registers them into the default `AgentContext`.
 
-## API Reference
+## Exposed SDK
 
-| API | What it does | Minimal usage |
+| Export | Type | Purpose |
 | --- | --- | --- |
-| `createAgentTools` | Load tools and register them into `AgentContext`. | `const tools = createAgentTools({ configFilePath: "./tool.yaml" })` |
+| `createAgentTools` | root function | Loads tools asynchronously from config. Preferred initializer for application bootstrap. |
+| `@easynet/agent-tool/sdk` | subpath | SDK entry for building custom tool extensions. |
+| `ToolRegistry` | sdk export | Registry used to register tool definitions. |
+| `createExtension` | sdk export | Creates an extension package entry. |
+| `registerExtension` | sdk export | Registers an extension into the runtime. |
+| `registerToolsFromManifest` | sdk export | Registers tools from a generated manifest. |
+| `loadToolYaml` | sdk export | Loads and parses `tool.yaml`. |
+| `resolveSandboxedPath` | sdk export | Resolves paths under sandbox constraints. |
+| `validateUrl` | sdk export | Validates outbound URLs for HTTP tools. |
 
 ## Usage
 
-Create `tool.yaml`:
-
-```yaml
-apiVersion: easynet.world/v1
-kind: ToolConfig
-metadata:
-  name: agent-tool-default
-spec:
-  sandboxedPath: .
-  allowedHosts: []
-  blockedHosts: []
-  tools:
-    npm:@easynet/agent-tool-buildin: {}
+```bash
+npm i @easynet/agent-tool
 ```
 
-Load tools:
-
 ```ts
 import { createAgentTools } from "@easynet/agent-tool";
 
-const tools = createAgentTools({
-  configFilePath: "./tool.yaml",
-});
+const tools = await createAgentTools("./config/tool.yaml");
 
 console.log(tools.map((tool) => tool.name));
 ```
 
-### YAML config
+Use `createAgentTools()` as the default application initializer. It matches the other async registration APIs (`createAgentModel`, `createAgentMemory`, `createAgentSkills`) and works cleanly with async extension loading.
 
-Example `tool.yaml`:
+If you are building your own tool extension, use the SDK subpath:
+
+```ts
+import { createExtension } from "@easynet/agent-tool/sdk";
+```
+
+## Configuration
+
+The default config file is `config/tool.yaml`.
 
 ```yaml
 apiVersion: easynet.world/v1
@@ -56,10 +57,11 @@ spec:
     npm:@easynet/agent-tool-buildin: {}
 ```
 
-Explanation:
+Key fields:
+
+- `spec.sandboxedPath`: filesystem root accessible to tools
+- `spec.allowedHosts`: HTTP allowlist
+- `spec.blockedHosts`: HTTP denylist
+- `spec.tools`: extensions to load
 
-- `spec.sandboxedPath`: root directory allowed for filesystem tools.
-- `spec.allowedHosts`: allowlist for outbound HTTP tools.
-- `spec.blockedHosts`: denylist for outbound HTTP tools.
-- `spec.tools`: keyed by tool source descriptor.
-- `npm:@easynet/agent-tool-buildin: {}`: load the built-in tool extension package with default config.
+`npm:@easynet/agent-tool-buildin: {}` loads the built-in tool extension package.

package/dist/api/expose/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Expose the same tools in multiple ways: LangChain, HTTP (OpenAPI), MCP server.
  *
- * - LangChain: createAgentTools() / LangChainToolsHub
+ * - LangChain: await createAgentTools() / LangChainToolsHub
  * - HTTP: createHttpService(runtime) -> { server, openApiSpec, listen() }
  * - MCP: createMCPServer(runtime) -> { server, connectStdio() }
  */

package/dist/api/register-tools.d.ts

@@ -3,16 +3,15 @@ import type { StructuredToolInterface } from "@langchain/core/tools";
 export interface CreateAgentToolsModuleOptions extends CreateAgentToolsOptions {
 }
 /**
- * Initialize LangChain agent tools and register them into the process-level singleton AgentContext.
+ * Preferred async tool initializer for application bootstrap.
  *
  * Sets:
  *  - AgentContextTokens.Tools → StructuredToolInterface[]
  *
  * @example
  * ```ts
- * createAgentTools({ configFilePath: "config/tool.yaml" });
+ * await createAgentTools("config/tool.yaml");
  * ```
  */
-export declare function createAgentTools(options?: CreateAgentToolsModuleOptions): StructuredToolInterface[];
-export declare function createAgentToolsAsync(options?: CreateAgentToolsModuleOptions): Promise<StructuredToolInterface[]>;
+export declare function createAgentTools(configPathOrOptions?: string | CreateAgentToolsModuleOptions): Promise<StructuredToolInterface[]>;
 //# sourceMappingURL=register-tools.d.ts.map

package/dist/api/register-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../../src/api/register-tools.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGrE,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;CAAG;AAEjF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,6BAA6B,GAAG,uBAAuB,EAAE,CAInG;AAED,wBAAsB,qBAAqB,CACzC,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAIpC"}
+{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../../src/api/register-tools.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGrE,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;CAAG;AAEjF;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,mBAAmB,CAAC,EAAE,MAAM,GAAG,6BAA6B,GAC3D,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAQpC"}

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;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAgB3D,OAAO,EAML,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AAIxC;;;;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,wFAAwF;IACxF,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;AAED,KAAK,UAAU,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAsCzH,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAuH9B,uHAAuH;AACvH,wBAAgB,iCAAiC,CAC/C,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAClC,eAAe,EAAE,CAmBnB;AAsID;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAuDnG;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA+C9B"}
+{"version":3,"file":"runtimeFromConfig.d.ts","sourceRoot":"","sources":["../../src/api/runtimeFromConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAgB3D,OAAO,EAML,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AAIxC;;;;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,wFAAwF;IACxF,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;AAED,KAAK,UAAU,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AA4CzH,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAuH9B,uHAAuH;AACvH,wBAAgB,iCAAiC,CAC/C,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAClC,eAAe,EAAE,CAmBnB;AAsID;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAwDnG;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAgD9B"}

package/dist/{chunk-3TT5M7A3.js → chunk-34SBJLFZ.js}

@@ -1,5 +1,5 @@
 import { DirectoryScanner, MCP_KIND } from './chunk-POUTZDWB.js';
-import { ToolRegistry, setSandboxValidationEnabled, createTaggedError, withRetry } from './chunk-IVL4TBFB.js';
+import { setSandboxValidationEnabled, ToolRegistry, createTaggedError, withRetry } from './chunk-IVL4TBFB.js';
 import { normalizeToolName } from './chunk-BDUSB6GT.js';
 import { enrichSpecWithCanonicalSchema } from './chunk-NTWOVFEY.js';
 import { readFileSync, existsSync, statSync, rmSync, mkdirSync, readdirSync, renameSync } from 'fs';
@@ -2044,6 +2044,11 @@ function parseNpmDescriptor(entry) {
 // src/api/runtimeFromConfig.ts
 var requireFromPackage2 = createRequire(import.meta.url);
 var DEFAULT_EXTENSION_PACKAGES = [];
+function resolveEffectiveCoreTools(options) {
+  if (options.coreTools) return options.coreTools;
+  if (options.configFilePath) return {};
+  return void 0;
+}
 function resolveFileDescriptorPath(descriptor, configFilePath) {
   const parsed = parseToolPath(descriptor.trim());
   if (!parsed || parsed.protocol !== "file") return null;
@@ -2299,8 +2304,9 @@ async function loadAllExtensionsFromToolYamlAsync(configFilePath, stepLog) {
 function createRuntimeFromConfigSync(options = {}) {
   const registry = new ToolRegistry();
   const stepLog = options.stepLog;
-  setSandboxValidationEnabled(options.coreTools?.enableSandboxValidation === true);
-  if (options.coreTools !== void 0) {
+  const effectiveCoreTools = resolveEffectiveCoreTools(options);
+  setSandboxValidationEnabled(effectiveCoreTools?.enableSandboxValidation === true);
+  if (effectiveCoreTools !== void 0) {
     if (options.configFilePath) {
       const all = loadAllExtensionsFromToolYamlSync(options.configFilePath, stepLog);
       if (all.length > 0) {
@@ -2310,7 +2316,7 @@ function createRuntimeFromConfigSync(options = {}) {
           const before = new Set(registry.snapshot().map((s) => s.name));
           const prefix = ext.descriptor.startsWith("file:") ? fileDescriptorToRegistryPrefix(ext.descriptor) : npmDescriptorToRegistryPrefix(ext.descriptor, ext.resolvedVersion);
           const reg = createPrefixingRegistry(registry, prefix ?? "");
-          const adapter = ext.register(reg, options.coreTools);
+          const adapter = ext.register(reg, effectiveCoreTools);
           runtime3.registerAdapter(adapter);
           const registeredNow = registry.snapshot().map((s) => s.name).filter((name) => !before.has(name));
           runtime3.registerAdapterForTools(registeredNow, adapter);
@@ -2327,7 +2333,7 @@ function createRuntimeFromConfigSync(options = {}) {
       const before = new Set(registry.snapshot().map((s) => s.name));
       const prefix = npmDescriptorToRegistryPrefix(descriptor, resolvedVersion);
       const reg = createPrefixingRegistry(registry, prefix ?? "");
-      const coreAdapter = extensionNode.register(reg, options.coreTools);
+      const coreAdapter = extensionNode.register(reg, effectiveCoreTools);
       const runtime3 = new PTCRuntime({ registry });
       runtime3.registerAdapter(coreAdapter);
       const registeredNow = registry.snapshot().map((s) => s.name).filter((name) => !before.has(name));
@@ -2341,8 +2347,9 @@ function createRuntimeFromConfigSync(options = {}) {
   return { runtime, registry };
 }
 async function createRuntimeFromConfig(options = {}) {
-  setSandboxValidationEnabled(options.coreTools?.enableSandboxValidation === true);
-  if (options.coreTools !== void 0 && options.configFilePath) {
+  const effectiveCoreTools = resolveEffectiveCoreTools(options);
+  setSandboxValidationEnabled(effectiveCoreTools?.enableSandboxValidation === true);
+  if (effectiveCoreTools !== void 0 && options.configFilePath) {
     const all = await loadAllExtensionsFromToolYamlAsync(options.configFilePath, options.stepLog);
     if (all.length > 0) {
       if (options.stepLog) options.stepLog(`Registered ${all.length} extension(s) from tool.yaml`);
@@ -2353,7 +2360,7 @@ async function createRuntimeFromConfig(options = {}) {
         const prefix = ext.descriptor.startsWith("file:") ? fileDescriptorToRegistryPrefix(ext.descriptor) : npmDescriptorToRegistryPrefix(ext.descriptor, ext.resolvedVersion);
         const reg = createPrefixingRegistry(registry, prefix ?? "");
         if ("register" in ext) {
-          const adapter = ext.register(reg, options.coreTools);
+          const adapter = ext.register(reg, effectiveCoreTools);
           runtime.registerAdapter(adapter);
           const registeredNow = registry.snapshot().map((s) => s.name).filter((name) => !before.has(name));
           runtime.registerAdapterForTools(registeredNow, adapter);
@@ -2935,6 +2942,6 @@ async function createHttpService(runtimeOrConfig, options = {}) {
   };
 }
 
-export { createHttpService, createMCPServerStreamableHttp, createRuntimeFromConfig, createRuntimeFromConfigSync, expandToolDescriptorsToRegistryNames, fileDescriptorToPackagePrefix, findAndLoadToolConfig, getDisplayScope, getToolSourceDescriptors, isBarePackageDescriptor, loadAllExtensionsFromToolYamlSync, loadToolConfig, npmDescriptorToPackagePrefix, resolveSandboxedPath, resolveToolDescriptor, runMCPServerOverStdio, toToolObservationText };
-//# sourceMappingURL=chunk-3TT5M7A3.js.map
-//# sourceMappingURL=chunk-3TT5M7A3.js.map
+export { createHttpService, createMCPServerStreamableHttp, createRuntimeFromConfig, expandToolDescriptorsToRegistryNames, fileDescriptorToPackagePrefix, findAndLoadToolConfig, getDisplayScope, getToolSourceDescriptors, isBarePackageDescriptor, loadToolConfig, npmDescriptorToPackagePrefix, resolveSandboxedPath, resolveToolDescriptor, runMCPServerOverStdio, toToolObservationText };
+//# sourceMappingURL=chunk-34SBJLFZ.js.map
+//# sourceMappingURL=chunk-34SBJLFZ.js.map