wasmagent-js

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.

Protect → Record → Audit → Admit · Sync — agent↔UI shared state

Start in 30 seconds

Pick your entry point:

Trust Pack — 30-minute end-to-end: [docs/quickstarts/trust-pack-30min.md](./docs/quickstarts/trust-pack-30min.md)

Quickstart

Three paths — pick the one that fits your use case:

Path 1 — Protect: MCP runtime firewall

Wrap any MCP server: vet tools before execution, enforce policy per call, track taint across results.

npm install @wasmagent/mcp-firewall

import { evaluatePolicy, snapshotTool, taintObservation, vetTool } from "@wasmagent/mcp-firewall";

const entry = {
  name: "read_file",
  description: "Read a file from disk",
  inputSchema: { type: "object", properties: { path: { type: "string" } } },
};
const args = { path: "/tmp/report.txt" };
const consentRecords = [];

// Before calling a tool
const snap     = snapshotTool(entry, "my-server");   // hash descriptor at registration
const vetting  = vetTool(entry);                     // static scan: injection / exfil / rug-pull
const decision = evaluatePolicy(entry.name, args, vetting, consentRecords);

if (decision.decision === "deny")   throw new Error(`Blocked: ${decision.reasons.join("; ")}`);
if (decision.decision === "ask_user") {
  // surface consent UI, then call recordConsent(...)
}

// After receiving result
const rawResult = "example report contents";
const obs = taintObservation(entry.name, rawResult);  // boundary-tagged, safe to assemble into prompt

→ Security pack · OWASP Agentic Top 10 · Attack demos

Path 2 — Record: AEP evidence export

Emit a signed evidence record after every agent run — consumable by trace-pipeline for audit and training.

npm install @wasmagent/aep

import { AEPEmitter } from "@wasmagent/aep";

const emitter = new AEPEmitter({ run_id: "run-001", model_id: "claude-sonnet-4-6" });

// During the run — add tool call evidence
emitter.addAction({ tool_name: "bash", outcome: "pass", exit_code: 0 });

// At the end — emit the record
const record = emitter.build();
// record satisfies aep/v0.3 JSON Schema — ready for evomerge validate-aep

→ AEP schema · trace-pipeline 10-min tutorial

Path 3 — Execute: Sandboxed code execution

Run agent-generated code in an isolated WASM kernel — no host-process access.

npm install @wasmagent/aisdk @wasmagent/kernel-quickjs

import { sandboxedJsTool } from "@wasmagent/aisdk";
import { QuickJSKernel } from "@wasmagent/kernel-quickjs";

// Drop into any AI SDK / LangChain / OpenAI Agents setup
const codeTool = sandboxedJsTool({ kernel: new QuickJSKernel() });

→ Kernel comparison · Getting started

Path 4 — Sync: Human-agent shared state

Reducer-backed collaborative state where the LLM reads projections, dispatches semantic actions, and respects affordances — all through standard tools.

npm install @wasmagent/core

import { defineStateModel, SharedStateStore, stateTools } from "@wasmagent/core/shared-state";

// 1. One reducer, shared by both UI and agent.
const model = defineStateModel({
  initial: () => ({ page: "list", selectedId: null as string | null }),
  reduce: (s, a) => {
    if (a.type === "SELECT") return { ...s, page: "detail", selectedId: a.id };
    if (a.type === "BACK")   return { ...s, page: "list", selectedId: null };
    return s;
  },
  project: (s) => ({ page: s.page, selectedId: s.selectedId }),
  affordances: (s) => s.page === "list" ? ["SELECT"] : ["BACK"],
});

// 2. Server-side store keyed by session.
const store = new SharedStateStore(model);

// 3. Give the agent read_state + dispatch_action tools.
const tools = stateTools(store, "session-001");
// Pass `tools` to any ToolCallingAgent — the LLM reads state and dispatches intent.

The semantic action stream doubles as AEP evidence — every dispatch is a provenance-ready record (see #141 for the full confluence design).

📚 [Docs](https://WasmAgent.github.io/wasmagent-js/) · Getting started · Kernels · OWASP governance · Security pack · Changelog

What is shipped vs alpha

WasmAgent uses a five-tier maturity scale to prevent "shipped" from becoming a vague claim:

Packages not listed here (model adapters, UI cards, etc.) follow the same scale — see each package's README or package.json wasmagent.stability field.

Package maturity

WasmAgent Ecosystem

WasmAgent is a portable, governable agent runtime for safe code execution, verifiable rollouts, and post-training data loops.

Task → Safe Runtime → Verifiable Rollout → Trajectory Export → DPO/PPO Data → Better Models

What makes wasmagent different

Three wedges where wasmagent stands apart from generic agent frameworks:

<details> <summary>Full feature axis table (10 axes vs. other JS agent frameworks)</summary>

</details>

Full comparison with Vercel AI SDK, LangGraph.js, OpenAI Agents JS, Mastra, CF Agents SDK: [docs/compare.md](./docs/compare.md)

Quick Start

Tool-Calling Agent

import { ToolCallingAgent, AnthropicModel } from "@wasmagent/core";
import { z } from "zod";

const agent = new ToolCallingAgent({
  model: new AnthropicModel("claude-haiku-4-5-20251001"),
  tools: [{
    name: "search", description: "Search the web",
    inputSchema: z.object({ query: z.string() }),
    readOnly: true, idempotent: true,
    forward: async ({ query }) => `Results for: ${query}`,
  }],
  stopPolicies: ["steps:10", "cost:0.5"],
});

for await (const ev of agent.run("Search for recent AI news")) {
  if (ev.event === "final_answer") console.log(ev.data.answer);
}

Sandboxed Code Agent

import { CodeAgent, AnthropicModel } from "@wasmagent/core";

const agent = new CodeAgent({
  model: new AnthropicModel("claude-sonnet-4-6"),
  tools: [],  // kernel executes code; no extra tools needed
  maxSteps: 10,
});

for await (const ev of agent.run("What is 42 * 1337?")) {
  if (ev.event === "final_answer") console.log(ev.data.answer);
}

CLI

npm install -g @wasmagent/cli

# Agent runs
wasmagent run "What is the square root of 144?"
wasmagent run "Summarise AI news" --stream | jq .

# Rollout / training data
wasmagent rank-rollout rollouts.jsonl --out ranked.jsonl
wasmagent validate-rollouts ranked.jsonl
wasmagent export-rollouts --in ranked.jsonl --format dpo --out dpo.jsonl

# MCP security (scan → guard → evidence)
wasmagent init --guard               # generate wasmagent.policy.yaml
wasmagent scan-mcp tools.json        # static risk scan, exits 1 on critical findings
wasmagent guard --config wasmagent.policy.yaml --upstream tools.json
wasmagent evidence export --input aep-records.jsonl --format json

GitHub Action — enforce policy in CI:

- uses: WasmAgent/wasmagent-js/.github/actions/agent-evidence-gate@main
  with:
    policy: wasmagent.policy.yaml
    tools-file: mcp-tools.json
    fail-on-policy-violation: "true"

→ MCP Guard guide · Attack demos

Key Capabilities

Model Providers

First-class adapters: Anthropic · OpenAI · Doubao · DeepSeek · Kimi · Qwen · GLM · MiniMax · local llama.cpp

// Chinese providers with thinking support
import { DoubaoModel, DoubaoModels } from "@wasmagent/model-doubao";
import { DeepSeekModel, DeepSeekModels } from "@wasmagent/model-deepseek";

// Local / offline
import { LocalModel } from "@wasmagent/model-local";  // node-llama-cpp, multi-mirror download

Full provider reference and proxy/custom endpoint setup: docs/guides/openai-compat-recipes.md

Ecosystem

Upstream integration status (PRs filed to Vercel AI SDK, Mastra, LangChain.js, ElizaOS, MCP registry, …) is tracked in docs/distribution/upstream-prs.md.

Development

bun install && bun run build
bun test packages/
bun run typecheck
bun run bench          # reproduce all README benchmarks
bun run check:branding # CI guard: no old brand references
bun run verify:claims  # CI guard: all benchmark claims have evidence scripts

See CONTRIBUTING.md · Changelog · License: Apache-2.0