{
  "markdown": "# wasmagent-js\n\n[![npm version](https://img.shields.io/npm/v/@wasmagent/core.svg?label=%40wasmagent%2Fcore)](https://www.npmjs.com/package/@wasmagent/core)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)\n[![CI](https://github.com/WasmAgent/wasmagent-js/actions/workflows/ci.yml/badge.svg)](https://github.com/WasmAgent/wasmagent-js/actions/workflows/ci.yml)\n[![Quick Start](https://github.com/WasmAgent/wasmagent-js/actions/workflows/quickstart-check.yml/badge.svg)](https://github.com/WasmAgent/wasmagent-js/actions/workflows/quickstart-check.yml)\n[![Docs](https://img.shields.io/badge/docs-vitepress-brightgreen.svg)](https://WasmAgent.github.io/wasmagent-js/)\n\n> **WasmAgent adds a verifiable evidence layer to agent tool use: protect tool calls, record what happened, audit the result, and admit trusted traces into downstream systems.**\n\n**Protect → Record → Audit → Admit**  ·  **Sync** — agent↔UI shared state\n\n---\n\n## Start in 30 seconds\n\nPick your entry point:\n\n| Goal | Install |\n|---|---|\n| **Protect tools** — runtime firewall, policy enforcement, taint tracking | `npm add @wasmagent/mcp-firewall` |\n| **Record evidence** — signed AEP records after every agent run | `npm add @wasmagent/aep` |\n| **Admit from traces** — compliance scoring produces `ComplianceEvalRecord`s for downstream training | `npm add @wasmagent/aep @wasmagent/compliance` |\n| **Sync state** — reducer-backed agent↔UI shared state, agent reads projections + writes intent | `npm add @wasmagent/core` (`/shared-state` subpath) |\n\n**Trust Pack — 30-minute end-to-end: [docs/quickstarts/trust-pack-30min.md](./docs/quickstarts/trust-pack-30min.md)**\n\n---\n\n## Quickstart\n\nThree paths — pick the one that fits your use case:\n\n### Path 1 — Protect: MCP runtime firewall\n\nWrap any MCP server: vet tools before execution, enforce policy per call, track taint across results.\n\n```bash\nnpm install @wasmagent/mcp-firewall\n```\n\n```ts\nimport { evaluatePolicy, snapshotTool, taintObservation, vetTool } from \"@wasmagent/mcp-firewall\";\n\nconst entry = {\n  name: \"read_file\",\n  description: \"Read a file from disk\",\n  inputSchema: { type: \"object\", properties: { path: { type: \"string\" } } },\n};\nconst args = { path: \"/tmp/report.txt\" };\nconst consentRecords = [];\n\n// Before calling a tool\nconst snap     = snapshotTool(entry, \"my-server\");   // hash descriptor at registration\nconst vetting  = vetTool(entry);                     // static scan: injection / exfil / rug-pull\nconst decision = evaluatePolicy(entry.name, args, vetting, consentRecords);\n\nif (decision.decision === \"deny\")   throw new Error(`Blocked: ${decision.reasons.join(\"; \")}`);\nif (decision.decision === \"ask_user\") {\n  // surface consent UI, then call recordConsent(...)\n}\n\n// After receiving result\nconst rawResult = \"example report contents\";\nconst obs = taintObservation(entry.name, rawResult);  // boundary-tagged, safe to assemble into prompt\n```\n\n→ [Security pack](./docs/security-governance-pack/README.md) · [OWASP Agentic Top 10](./docs/security/capability-manifest-owasp.md) · [Attack demos](./docs/security/mcp-firewall-attack-demos.md)\n\n### Path 2 — Record: AEP evidence export\n\nEmit a signed evidence record after every agent run — consumable by trace-pipeline for audit and training.\n\n```bash\nnpm install @wasmagent/aep\n```\n\n```ts\nimport { AEPEmitter } from \"@wasmagent/aep\";\n\nconst emitter = new AEPEmitter({ run_id: \"run-001\", model_id: \"claude-sonnet-4-6\" });\n\n// During the run — add tool call evidence\nemitter.addAction({ tool_name: \"bash\", outcome: \"pass\", exit_code: 0 });\n\n// At the end — emit the record\nconst record = emitter.build();\n// record satisfies aep/v0.1 JSON Schema — ready for evomerge validate-aep\n```\n\n→ [AEP schema](./packages/aep/) · [trace-pipeline 10-min tutorial](https://github.com/WasmAgent/trace-pipeline/blob/main/docs/TRACE_TO_TRAINING_10MIN.md)\n\n### Path 3 — Execute: Sandboxed code execution\n\nRun agent-generated code in an isolated WASM kernel — no host-process access.\n\n```bash\nnpm install @wasmagent/aisdk @wasmagent/kernel-quickjs\n```\n\n```ts\nimport { sandboxedJsTool } from \"@wasmagent/aisdk\";\nimport { QuickJSKernel } from \"@wasmagent/kernel-quickjs\";\n\n// Drop into any AI SDK / LangChain / OpenAI Agents setup\nconst codeTool = sandboxedJsTool({ kernel: new QuickJSKernel() });\n```\n\n→ [Kernel comparison](./docs/kernels/comparison.md) · [Getting started](./docs/guides/getting-started.md)\n\n### Path 4 — Sync: Human-agent shared state\n\nReducer-backed collaborative state where the LLM reads projections, dispatches semantic actions, and respects affordances — all through standard tools.\n\n```bash\nnpm install @wasmagent/core\n```\n\n```ts\nimport { defineStateModel, SharedStateStore, stateTools } from \"@wasmagent/core/shared-state\";\n\n// 1. One reducer, shared by both UI and agent.\nconst model = defineStateModel({\n  initial: () => ({ page: \"list\", selectedId: null as string | null }),\n  reduce: (s, a) => {\n    if (a.type === \"SELECT\") return { ...s, page: \"detail\", selectedId: a.id };\n    if (a.type === \"BACK\")   return { ...s, page: \"list\", selectedId: null };\n    return s;\n  },\n  project: (s) => ({ page: s.page, selectedId: s.selectedId }),\n  affordances: (s) => s.page === \"list\" ? [\"SELECT\"] : [\"BACK\"],\n});\n\n// 2. Server-side store keyed by session.\nconst store = new SharedStateStore(model);\n\n// 3. Give the agent read_state + dispatch_action tools.\nconst tools = stateTools(store, \"session-001\");\n// Pass `tools` to any ToolCallingAgent — the LLM reads state and dispatches intent.\n```\n\nThe semantic action stream doubles as AEP evidence — every dispatch is a provenance-ready record (see [#141](../../issues/141) for the full confluence design).\n\n---\n\n📚 **[Docs](https://WasmAgent.github.io/wasmagent-js/)** · [Getting started](./docs/guides/getting-started.md) · [Kernels](./docs/kernels/comparison.md) · [OWASP governance](./docs/security/capability-manifest-owasp.md) · [Security pack](./docs/security-governance-pack/README.md) · [Changelog](./CHANGELOG.md)\n\n---\n\n## What is shipped vs alpha\n\nWasmAgent uses a five-tier maturity scale to prevent \"shipped\" from becoming a vague claim:\n\n| Tier | Meaning | Semver guarantee | Production use |\n|---|---|---|---|\n| **stable** | Public API locked; breaking changes require major-version bump | Yes | Yes |\n| **beta** | Functional and used in production, but a specific limitation is documented (e.g. first-line filter only, contract still evolving) | Minor/patch only | Yes, with caveats documented |\n| **alpha** | Schema versioned; fields may be added without a breaking-change bump | No | Informed use |\n| **demo** | Demonstration or example code; not hardened for production | No | No |\n| **research** | Research-grade prototype; interfaces may change without notice | No | No |\n\nPackages not listed here (model adapters, UI cards, etc.) follow the same scale — see each package's README or `package.json` `wasmagent.stability` field.\n\n---\n\n## Package maturity\n\n| Package | Maturity | Notes |\n|---|---|---|\n| `@wasmagent/core` | **stable** | Public API; semver guaranteed |\n| `@wasmagent/kernel-quickjs` | **stable** | |\n| `@wasmagent/kernel-remote` | **stable** | |\n| `@wasmagent/mcp-gateway` | **stable** | Published 0.1.0; gateway composes all firewall layers |\n| `@wasmagent/mcp-firewall` | **beta** | First-line filter, not adversarial-grade — keyword bag + lightweight n-gram classifier; use defence-in-depth |\n| `@wasmagent/aep` | **beta** | v0.2 signature contract (Ed25519) shipped; schema versioned |\n| `@wasmagent/otel-exporter` | **alpha** | GENAI_SEMCONV, AEP↔OTel bridge |\n| `@wasmagent/aisdk` / `@wasmagent/mastra-sandbox` | **alpha** | API stable, may add fields |\n| `@wasmagent/compliance` | **alpha** | Schema versioned; may add fields without breaking |\n| `@wasmagent/mcp-policy` | **alpha — private** | Not yet published to npm |\n| `@wasmagent/mcp-attestation` | **alpha — private** | Not yet published to npm |\n| `@wasmagent/evals-runner` | **alpha** | |\n| `@wasmagent/devtools` | **alpha** | |\n\n---\n\n## WasmAgent Ecosystem\n\nWasmAgent is a portable, governable agent runtime for safe code execution, verifiable rollouts, and post-training data loops.\n\n| Repo | Role |\n|---|---|\n| **wasmagent-js** (this repo) | Embedded Agent Runtime / WASM Kernel / policy / verifier / adapters |\n| [bscode](https://github.com/WasmAgent/bscode) | Cloudflare flagship demo and deploy template for safe coding agents |\n| [trace-pipeline](https://github.com/WasmAgent/trace-pipeline) | Public datafactory and eval-trust backend for rollout data |\n\n```text\nTask → Safe Runtime → Verifiable Rollout → Trajectory Export → DPO/PPO Data → Better Models\n```\n\n---\n\n## What makes wasmagent different\n\nThree wedges where wasmagent stands apart from generic agent frameworks:\n\n| Wedge | What it means |\n|---|---|\n| **Sandboxed execution** | Three isolation tiers — VmKernel / WASM (QuickJS·Pyodide·Wasmtime) / microVM — with a single `CapabilityManifest` and MCP runtime firewall across all |\n| **Runtime compliance** | `TaskSpec` → `ConstraintIR` → `ComplianceEvalRecord` — every run produces an auditable, cross-repo training contract, not just a log |\n| **Trace-to-training contract** | Verifiable rollout branching, objective scoring, DPO/PPO export — the loop from runtime evidence to training data is first-class, not an afterthought |\n\n<details>\n<summary>Full feature axis table (10 axes vs. other JS agent frameworks)</summary>\n\n| # | Axis | Status |\n|---|---|---|\n| 1 | **Multi-provider adapters** — one `Model` interface across Anthropic, OpenAI, Doubao, DeepSeek, Kimi, Qwen, GLM, MiniMax, local llama.cpp | shipped |\n| 2 | **Three isolation tiers** — `VmKernel` (in-process) / QuickJS·Pyodide·Wasmtime (WASM) / `RemoteSandboxKernel` (microVM) — same `CapabilityManifest` across all | shipped |\n| 3 | **Cross-runtime + offline** — Node / edge / browser / air-gapped laptop; `@wasmagent/model-local` + WASM kernel = zero outbound traffic | shipped |\n| 4 | **Memory layers** — `MemoryBlockSet` (prompt-cache stable) + observational memory + Checkpointer + 4 KV backends | shipped |\n| 5 | **Durable workflows** — `LocalWorkflowEngine` + `CloudflareWorkflowEngine` — observable, terminable, resumable | shipped |\n| 6 | **Code-mode MCP** — N tools → 2 tools (`docs_search` + `execute_code`); 13.6% token cost at N=30 | shipped |\n| 7 | **Devtools + OTel** — local Studio, `gen_ai.*` semantic conventions (Datadog / Honeycomb / Grafana) | shipped |\n| 8 | **Goal-directed loop** — agent synthesises success criteria, verifies, retries with hints | shipped 2026-06-18 |\n| 9 | **Adaptive execution** — registered fallbacks (L1) → synthesised tool (L2) → relaxed goal (L3) | shipped 2026-06-18 |\n| 10 | **MCP runtime firewall** — `@wasmagent/mcp-firewall`: descriptor snapshot, static vetting (injection / exfiltration / rug-pull / taint), per-call policy, consent ledger | shipped 2026-06-25 |\n\n</details>\n\n> Full comparison with Vercel AI SDK, LangGraph.js, OpenAI Agents JS, Mastra, CF Agents SDK: **[docs/compare.md](./docs/compare.md)**\n\n---\n\n## Quick Start\n\n### Tool-Calling Agent\n\n```ts\nimport { ToolCallingAgent, AnthropicModel } from \"@wasmagent/core\";\nimport { z } from \"zod\";\n\nconst agent = new ToolCallingAgent({\n  model: new AnthropicModel(\"claude-haiku-4-5-20251001\"),\n  tools: [{\n    name: \"search\", description: \"Search the web\",\n    inputSchema: z.object({ query: z.string() }),\n    readOnly: true, idempotent: true,\n    forward: async ({ query }) => `Results for: ${query}`,\n  }],\n  stopPolicies: [\"steps:10\", \"cost:0.5\"],\n});\n\nfor await (const ev of agent.run(\"Search for recent AI news\")) {\n  if (ev.event === \"final_answer\") console.log(ev.data.answer);\n}\n```\n\n### Sandboxed Code Agent\n\n```ts\nimport { CodeAgent, AnthropicModel } from \"@wasmagent/core\";\n\nconst agent = new CodeAgent({\n  model: new AnthropicModel(\"claude-sonnet-4-6\"),\n  tools: [],  // kernel executes code; no extra tools needed\n  maxSteps: 10,\n});\n\nfor await (const ev of agent.run(\"What is 42 * 1337?\")) {\n  if (ev.event === \"final_answer\") console.log(ev.data.answer);\n}\n```\n\n### CLI\n\n```bash\nnpm install -g @wasmagent/cli\n\n# Agent runs\nwasmagent run \"What is the square root of 144?\"\nwasmagent run \"Summarise AI news\" --stream | jq .\n\n# Rollout / training data\nwasmagent rank-rollout rollouts.jsonl --out ranked.jsonl\nwasmagent validate-rollouts ranked.jsonl\nwasmagent export-rollouts --in ranked.jsonl --format dpo --out dpo.jsonl\n\n# MCP security (scan → guard → evidence)\nwasmagent init --guard               # generate wasmagent.policy.yaml\nwasmagent scan-mcp tools.json        # static risk scan, exits 1 on critical findings\nwasmagent guard --config wasmagent.policy.yaml --upstream tools.json\nwasmagent evidence export --input aep-records.jsonl --format json\n```\n\n**GitHub Action** — enforce policy in CI:\n\n```yaml\n- uses: WasmAgent/wasmagent-js/.github/actions/agent-evidence-gate@main\n  with:\n    policy: wasmagent.policy.yaml\n    tools-file: mcp-tools.json\n    fail-on-policy-violation: \"true\"\n```\n\n→ [MCP Guard guide](./docs/guides/mcp-guard.md) · [Attack demos](./docs/security/mcp-firewall-attack-demos.md)\n\n---\n\n## Key Capabilities\n\n| Capability | Guide |\n|---|---|\n| Shared state — reducer-backed agent↔UI sync, projections, affordances | [packages/core/src/shared-state/](./packages/core/src/shared-state/) |\n| MCP firewall — vetTool, ScopeLease, ApprovalReceipt | [docs/guides/mcp-guard.md](./docs/guides/mcp-guard.md) |\n| AEP v0.2 evidence — causal chain, scope lease, taint, memory refs | [packages/aep/src/types.ts](./packages/aep/src/types.ts) |\n| OWASP MCP Top 10 crosswalk | [docs/security/standards-crosswalk.yaml](./docs/security/standards-crosswalk.yaml) |\n| OWASP security demo (10 scenarios) | [examples/owasp-demo/](./examples/owasp-demo/) |\n| Security benchmark runner | [examples/security-benchmark/](./examples/security-benchmark/) |\n| AEP ↔ OTel bidirectional mapping | [packages/otel-exporter/src/aep-otel-bridge.ts](./packages/otel-exporter/src/aep-otel-bridge.ts) |\n| AgentTeam delegation chain | [packages/core/src/agents/AgentTeam.ts](./packages/core/src/agents/AgentTeam.ts) |\n| Claim dashboard | `node scripts/verify-claims.mjs --html` → `docs/claims/claims.html` |\n| Quality runners (self-consistency, reflect-refine, parallel fork-join) | [docs/guides/quality-runners.md](./docs/guides/quality-runners.md) |\n| Durable runtime (checkpoints, SSE resume, HITL) | [docs/guides/durable-runtime.md](./docs/guides/durable-runtime.md) |\n| Observational memory — ~22% tokens on 50-turn traces | [docs/guides/observational-memory.md](./docs/guides/observational-memory.md) |\n| Goal-directed agent with verifiers | [docs/guides/goal-directed.md](./docs/guides/goal-directed.md) |\n| Production APIs (retry, evals, OTel, React hook) | [docs/api/production-apis.md](./docs/api/production-apis.md) |\n| API stability policy | [docs/api/stability-policy.md](./docs/api/stability-policy.md) |\n\n---\n\n## Model Providers\n\nFirst-class adapters: Anthropic · OpenAI · Doubao · DeepSeek · Kimi · Qwen · GLM · MiniMax · local llama.cpp\n\n```ts\n// Chinese providers with thinking support\nimport { DoubaoModel, DoubaoModels } from \"@wasmagent/model-doubao\";\nimport { DeepSeekModel, DeepSeekModels } from \"@wasmagent/model-deepseek\";\n\n// Local / offline\nimport { LocalModel } from \"@wasmagent/model-local\";  // node-llama-cpp, multi-mirror download\n```\n\nFull provider reference and proxy/custom endpoint setup: [docs/guides/openai-compat-recipes.md](./docs/guides/openai-compat-recipes.md)\n\n---\n\n## Ecosystem\n\n| Project | Role |\n|---|---|\n| [bscode](https://github.com/WasmAgent/bscode) | Flagship Cloudflare deploy template — wires every wasmagent-js capability into a real edge product |\n| [trace-pipeline](https://github.com/WasmAgent/trace-pipeline) | Training data factory — converts ranked rollouts into DPO/PPO datasets |\n\nUpstream integration status (PRs filed to Vercel AI SDK, Mastra,\nLangChain.js, ElizaOS, MCP registry, …) is tracked in\n[`docs/distribution/upstream-prs.md`](./docs/distribution/upstream-prs.md).\n\n---\n\n## Development\n\n```bash\nbun install && bun run build\nbun test packages/\nbun run typecheck\nbun run bench          # reproduce all README benchmarks\nbun run check:branding # CI guard: no old brand references\nbun run verify:claims  # CI guard: all benchmark claims have evidence scripts\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) · [Changelog](./CHANGELOG.md) · [License: Apache-2.0](./LICENSE)\n",
  "bytes": 16428,
  "sha": "e115e47772e8b4392493cf12e2695e2c9cd68821bfdea1956228acc8d5846573",
  "repo_slug": "wasmagent/wasmagent-js",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_telleroutlook_mcp_server_dab194ca/readme"
}