@easynet/agent-tool 1.0.0

package/dist/types/ToolResult.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Evidence attached to a tool result for audit trail.
+ */
+export interface Evidence {
+    type: "tool" | "file" | "url" | "text" | "metric";
+    ref: string;
+    summary: string;
+    createdAt: string;
+}
+/**
+ * Error information in a tool result.
+ */
+export interface ToolError {
+    kind?: "TOOL_NOT_FOUND" | "INPUT_SCHEMA_INVALID" | "POLICY_DENIED" | "BUDGET_EXCEEDED" | "TIMEOUT" | "UPSTREAM_ERROR" | "OUTPUT_SCHEMA_INVALID" | "PATH_OUTSIDE_SANDBOX" | "FILE_TOO_LARGE" | "HTTP_DISALLOWED_HOST" | "HTTP_TIMEOUT" | "HTTP_TOO_LARGE";
+    message: string;
+    details?: unknown;
+}
+/**
+ * Unified tool result returned to agent-orchestra.
+ * Always structured, never throws raw exceptions.
+ */
+export interface ToolResult {
+    ok: boolean;
+    result?: unknown;
+    evidence: Evidence[];
+    error?: ToolError;
+    /** Raw response for debugging (can be disabled in production) */
+    raw?: unknown;
+}
+//# sourceMappingURL=ToolResult.d.ts.map

package/dist/types/ToolResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolResult.d.ts","sourceRoot":"","sources":["../../src/types/ToolResult.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EACD,gBAAgB,GAChB,sBAAsB,GACtB,eAAe,GACf,iBAAiB,GACjB,SAAS,GACT,gBAAgB,GAChB,uBAAuB,GACvB,sBAAsB,GACtB,gBAAgB,GAChB,sBAAsB,GACtB,cAAc,GACd,gBAAgB,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,iEAAiE;IACjE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf"}

package/dist/types/ToolSpec.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Unified tool kinds supported by the tools package.
+ */
+export type ToolKind = "mcp" | "langchain" | "n8n" | "comfyui" | "skill" | "core" | "example";
+/**
+ * Capability declarations for tools.
+ * Used by PolicyEngine for permission gating.
+ */
+export type Capability = "read:web" | "read:fs" | "write:fs" | "read:db" | "write:db" | "network" | "gpu" | "workflow" | "danger:destructive" | "exec";
+/**
+ * HITL (Human-in-the-Loop) side-effect classification.
+ * Used to gate execution: external_write / destructive require human approval when onApprovalRequired is set.
+ */
+export type HitlSideEffect = "none" | "local_write" | "external_write" | "destructive";
+/**
+ * Cost hints for tools, used by Budget and routing.
+ */
+export interface CostHints {
+    latencyMsP50?: number;
+    latencyMsP95?: number;
+    isAsync?: boolean;
+}
+/**
+ * Unified tool specification.
+ * All tool types (MCP, LangChain, n8n, SKILL) are described by this interface.
+ */
+export interface ToolSpec {
+    /** Globally unique name, recommended format: namespace/name */
+    name: string;
+    /** Semver version */
+    version: string;
+    /** Tool kind determines which adapter handles execution */
+    kind: ToolKind;
+    description?: string;
+    tags?: string[];
+    /** JSON Schema for input validation */
+    inputSchema: object;
+    /** JSON Schema for output validation */
+    outputSchema: object;
+    /** Required capabilities for this tool */
+    capabilities: Capability[];
+    costHints?: CostHints;
+    /** HITL: side-effect level; when external_write/destructive, runtime may require human approval before execute */
+    _meta?: {
+        hitl?: {
+            sideEffect?: HitlSideEffect;
+        };
+    };
+    /** Adapter-specific: endpoint URL (MCP/n8n) */
+    endpoint?: string;
+    /** Adapter-specific: resource identifier (workflowId, promptId, etc.) */
+    resourceId?: string;
+    /** Adapter-specific: implementation reference (LangChain Tool instance, skill handler) */
+    impl?: unknown;
+}
+/** Default permissive input schema when not provided (framework supports auto-derived schema). */
+export declare const DEFAULT_INPUT_SCHEMA: object;
+/** Default permissive output schema when not provided (framework supports auto-derived schema). */
+export declare const DEFAULT_OUTPUT_SCHEMA: object;
+/**
+ * Minimal options to build a ToolSpec. Use with @effect in JSDoc for HITL sideEffect.
+ * Framework fills _meta.hitl.sideEffect from the sideEffect parameter (matches @effect annotation).
+ * inputSchema/outputSchema are optional: when omitted, permissive defaults are used (framework supports auto-derived schema at build time in codegen).
+ */
+export interface CreateToolSpecOptions {
+    name: string;
+    version?: string;
+    kind: ToolKind;
+    description?: string;
+    tags?: string[];
+    /** Optional: when omitted, DEFAULT_INPUT_SCHEMA is used. Codegen can derive from handler params. */
+    inputSchema?: object;
+    /** Optional: when omitted, DEFAULT_OUTPUT_SCHEMA is used. Codegen can derive from handler return type. */
+    outputSchema?: object;
+    capabilities: Capability[];
+    costHints?: CostHints;
+    /** HITL: from @effect annotation (none | local_write | external_write | destructive). Default "none". */
+    sideEffect?: HitlSideEffect;
+}
+/**
+ * Build a ToolSpec from minimal options. Use @effect in handler JSDoc as annotation; pass same value as sideEffect.
+ * When inputSchema/outputSchema are omitted, permissive defaults are used (schema can be auto-derived at build time).
+ */
+export declare function createToolSpec(opts: CreateToolSpecOptions): ToolSpec;
+/**
+ * Unified adapter interface.
+ * Each protocol adapter (MCP, LangChain, n8n, SKILL) implements this.
+ */
+export interface ToolAdapter {
+    kind: ToolKind;
+    /** Optional: supports dynamic tool discovery */
+    listTools?(): Promise<ToolSpec[]>;
+    /** Execute the tool with validated args */
+    invoke(spec: ToolSpec, args: unknown, ctx: import("./ToolIntent.js").ExecContext): Promise<{
+        result: unknown;
+        raw?: unknown;
+    }>;
+}
+//# sourceMappingURL=ToolSpec.d.ts.map

package/dist/types/ToolSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolSpec.d.ts","sourceRoot":"","sources":["../../src/types/ToolSpec.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9F;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,KAAK,GACL,UAAU,GACV,oBAAoB,GACpB,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,aAAa,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,IAAI,EAAE,QAAQ,CAAC;IAEf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IAErB,0CAA0C;IAC1C,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,kHAAkH;IAClH,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE;YAAE,UAAU,CAAC,EAAE,cAAc,CAAA;SAAE,CAAA;KAAE,CAAC;IAEnD,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,EAAE,MAGlC,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,qBAAqB,EAAE,MAGnC,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0GAA0G;IAC1G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,yGAAyG;IACzG,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,QAAQ,CAcpE;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,gDAAgD;IAChD,SAAS,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClC,2CAA2C;IAC3C,MAAM,CACJ,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,OAAO,iBAAiB,EAAE,WAAW,GACzC,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAChD"}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export type { ToolKind, Capability, CostHints, ToolSpec, ToolAdapter, HitlSideEffect, CreateToolSpecOptions, } from "./ToolSpec.js";
+export { createToolSpec, DEFAULT_INPUT_SCHEMA, DEFAULT_OUTPUT_SCHEMA, } from "./ToolSpec.js";
+export type { BudgetConfig, ExecContext, ToolIntent, } from "./ToolIntent.js";
+export type { Evidence, ToolError, ToolResult, } from "./ToolResult.js";
+export type { ToolEventType, ToolEvent, ToolCalledEvent, ToolResultEvent, PolicyDeniedEvent, RetryEvent, JobSubmittedEvent, JobCompletedEvent, JobFailedEvent, AnyToolEvent, } from "./Events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,cAAc,EACd,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,QAAQ,EACR,SAAS,EACT,UAAU,GACX,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,aAAa,EACb,SAAS,EACT,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC"}

package/extensions/examples/README.md

@@ -0,0 +1,40 @@
+# Examples
+
+Examples for **agent-tool** are organized under `extensions/` and use the **new way**: core-style tools (TypeScript, `ToolSpec` + handler, JSON Schema).
+
+## Layout
+
+| Path | Purpose |
+|------|--------|
+| **extensions/example-tools/** | Example tools extension: Yahoo Finance (quote + chart). Same pattern as `builtin-tools`. FS and HTTP are in builtin-tools. |
+| **extensions/examples/scripts/** | Runnable demo scripts (e.g. ReAct + stock report). |
+| **extensions/examples/tools/** | Reference content for discovery: instruction-only skill, MCP configs. |
+| **extensions/builtin-tools/** | Built-in core tools: FS, HTTP, util, security. |
+
+## New way (core-style)
+
+- **TypeScript** with `ToolSpec` (name, description, inputSchema, outputSchema) and a handler function.
+- Handlers return `{ result, evidence }`; context (config, execCtx) is injected via adapter.
+- Tools are registered with a `ToolRegistry` and an adapter (e.g. `CoreAdapter`, `ExampleAdapter`).
+
+Example tools (domain examples only; FS and HTTP use builtin-tools):
+
+- **example/finance.yahoo.quote** — Yahoo Finance quote summary by symbol.
+- **example/finance.yahoo.chart** — Yahoo Finance chart/OHLCV by symbol.
+
+## Run the ReAct stock demo
+
+From the repo root (after `npm run build` and `npm run build:ext` if needed):
+
+```bash
+npm run build && node extensions/examples/scripts/agent-tool-react-stock.mjs AAPL
+```
+
+Uses `registerCoreTools` and `registerExampleTools` with PTCRuntime + LangChainToolsHub; no `toolhub.yaml` required.
+
+## Reference content (discovery)
+
+- **tools/instruction-only/skill/SKILL.md** — Instruction-only skill (no handler); agent follows written steps.
+- **tools/web-search/mcp/mcp.json** — MCP config for web search (e.g. open-websearch).
+
+Discovery roots can point at `extensions/examples/tools` to load these skills and MCP configs.

package/extensions/examples/scripts/agent-tool-react-stock.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Stock research example: runs agent-tool run with a stock task and report path.
+ *
+ * Usage (from project root, after npm run build):
+ *   node extensions/examples/scripts/agent-tool-react-stock.mjs [SYMBOL]
+ *   node extensions/examples/scripts/agent-tool-react-stock.mjs AAPL
+ *
+ * Or: agent-tool run "Your task" --report out.html
+ */
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, "..", "..", "..");
+const CLI = join(PROJECT_ROOT, "dist", "cli.js");
+
+const SYMBOL = (process.argv[2] || "AAPL").toUpperCase();
+const SYSTEM_PROMPT = `You are an expert doing research. Please do deep research for the company from Wikipedia, and then produce a detailed Markdown report (≥2000 words) and confirm.`;
+const USER_TASK = `Perform deep research on stock/company "${SYMBOL}": investigate, analyze, speculate. Produce a detailed Markdown report (≥2000 words) and confirm.`;
+const REPORT_PATH = `${SYMBOL}-research-report.html`;
+
+const child = spawn(process.execPath, [CLI, "run", USER_TASK, "--report", REPORT_PATH], {
+  cwd: PROJECT_ROOT,
+  stdio: "inherit",
+  env: { ...process.env, AGENT_SYSTEM: SYSTEM_PROMPT },
+});
+
+child.on("exit", (code) => process.exit(code ?? 0));

package/extensions/examples/tools/instruction-only/skill/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: instruction-only-skill
+description: Instruction-only skill with no handler. Returns SKILL.md content for the agent to consume; use when the agent should follow written instructions instead of calling code.
+license: MIT
+---
+
+# Instruction-Only Skill (Level 2)
+
+This skill has **no handler** — it demonstrates **instruction-only mode**. When invoked, the agent receives this body and the resource list; no programmatic code runs.
+
+## When to use
+
+- The task is best done by the agent following written steps.
+- No bundled script is needed; instructions are sufficient.
+
+## Steps (example)
+
+1. Read the user request.
+2. Follow the instructions in this SKILL.md.
+3. Return a structured response.
+
+## Progressive disclosure
+
+- **Level 1**: name + description (loaded at startup).
+- **Level 2**: This body (loaded when skill is activated).
+- **Level 3**: No bundled files in this example; handlers can use `readResource(relativePath)` and `getResourcesByType(type)` when present.

package/extensions/examples/tools/web-search/mcp/mcp.json

@@ -0,0 +1,8 @@
+{
+  "command": "npx",
+  "args": ["-y", "open-websearch@latest"],
+  "env": {
+    "MODE": "stdio",
+    "DEFAULT_SEARCH_ENGINE": "duckduckgo"
+  }
+}

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "@easynet/agent-tool",
+  "version": "1.0.0",
+  "description": "MCP build: init → build → run. Turn your project (@tool, SKILL, n8n) into a standalone MCP npm server (no framework embedding, no package conflict).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agent-tool": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "extensions/examples"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "npx tsup && npx tsc -p tsconfig.dts.json && mkdir -p dist/report && cp src/report/agent-report-template.html dist/report/ && mkdir -p dist/templates && cp src/codegen/templates/*.js dist/templates/",
+    "build:ext": "cd extensions/builtin-tools && npm install && npm run build && cd ../example-tools && npm install && npm run build",
+    "dev": "npx tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "lint:lines": "./scripts/check-line-count.sh",
+    "lint:functions": "python3 scripts/check-function-length.py",
+    "deps:tree": "npm ls --all",
+    "deps:size": "du -sh node_modules/* 2>/dev/null | sort -hr | head -40",
+    "agent": "echo 'Use: npx @easynet/agent-orchestra run \"task\" -c agent.yaml'",
+    "agent:stock": "node extensions/examples/scripts/agent-tool-react-stock.mjs"
+  },
+  "dependencies": {
+    "@easynet/agent-llm": "^1.0.0",
+    "@easynet/agent-tool-builtin-tools": "file:extensions/builtin-tools",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@easynet/agent-tool-example-tools": "file:extensions/example-tools",
+    "@langchain/core": ">=0.3.0",
+    "@langchain/openai": "^1.2.3",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "cockatiel": "^3.2.1",
+    "eventemitter3": "^5.0.1",
+    "jmespath": "^0.16.0",
+    "js-yaml": "^4.1.1",
+    "langchain": ">=1.0.0",
+    "mustache": "^4.2.0",
+    "p-retry": "^6.2.1",
+    "p-timeout": "^6.1.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.2",
+    "uuid": "^11.0.5"
+  },
+  "devDependencies": {
+    "@langchain/core": "1.1.17",
+    "@langchain/openai": "1.2.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/jmespath": "^0.15.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mustache": "^4.2.5",
+    "@types/node": "^22.10.0",
+    "@types/uuid": "^10.0.0",
+    "deepagents": "1.6.1",
+    "langchain": "1.2.7",
+    "semantic-release": "^24.2.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
+    "@modelcontextprotocol/sdk": ">=1.25.0",
+    "langchain": ">=1.0.0",
+    "zod": ">=3.23.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    },
+    "langchain": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "@langchain/core": "1.1.17",
+    "deepagents": "1.6.1",
+    "langchain": "1.2.7"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/easynet-world/agent-tool.git"
+  },
+  "homepage": "https://github.com/easynet-world/agent-tool#readme",
+  "bugs": {
+    "url": "https://github.com/easynet-world/agent-tool/issues"
+  }
+}