Neutral agent interoperability bus and control plane.
MoltMesh lets heterogeneous agent systems communicate through shared contracts, adapter-based translation, policy enforcement, and end-to-end tracing. It is not another agent network — it is the governance and mediation layer that sits between existing agent frameworks.
MoltMesh is part of a broader ecosystem of agent governance tools:
- MoltPermit — Cedar-based policy engine, audit logging, budget tracking, JIT tokens
- MoltCaptcha — Agent verification via semantic-mathematical challenges
- MoltDoor — Agent reputation/ranking platform
MoltMesh is designed to eventually integrate with these systems — importing MoltPermit for policy evaluation, querying MoltDoor for reputation data, and using MoltCaptcha for agent verification.
# Install dependencies
npm install
# Run all tests (467 tests)
npm test
# Run the 7-scenario flagship demo
npx tsx demo/full-demo.ts
# Run the 7 federation scenarios
npx tsx demo/federation-demo.ts
# Run the 7 exchange scenarios
npx tsx demo/exchange-demo.ts
# Run all demos sequentially
npm run demo:all
# Start the operator console server
npm run demo:server
# Then open http://localhost:3456- Contract registry with JSON Schema validation, versioning, fallback chains
- Agent identity with four trust tiers (Internal Trusted → Public Vendor)
- Policy engine with configurable allow/deny rules
- Router with capability-based resolution, retry, and fallback
- Three adapters: Echo, HTTP, OpenAI-compatible
- SQLite-backed trace store with structured event recording
- 88 tests (Phase 0 baseline)
- Tool-level policy restrictions — Policies can deny agents access to specific tools (e.g., block
web_searchfor restricted-tier agents) - Token budget enforcement — Per-agent daily token budgets with automatic tracking and denial when exceeded
- Approval workflows — Contracts can require human approval before execution; operators approve/deny via console or API
- Dead-letter queue — Failed tasks are captured with full context, retry history, and resolution tracking
- Circuit breaker — Per-agent circuit breakers (closed → open → half-open) prevent cascade failures
- Cost accounting — Per-step token tracking, cost roll-up per trace, per-agent spend summaries with configurable rates
- Custom error classes — Typed errors (PolicyDenied, BudgetExceeded, CircuitOpen, ApprovalRequired, ContractViolation, AdapterError) for programmatic handling
- Operator console — Full web dashboard with 6 tabs: Dashboard, Workflows, Contracts, Agents, Policies, Dead Letters (expanded to 8 tabs in Phase 2)
- Flagship demo — 7 scenarios demonstrating the complete governance surface
- 168 tests (80 new)
- Multi-tenant architecture with organizations and namespaces
- Federation grants for cross-org access control
- Dual-policy evaluation (caller + target org policies)
- Gateway API with API key authentication and rate limiting
- Webhook delivery with HMAC-SHA256 signing and retry
- SQLite persistence for all registries (agents, contracts, orgs, grants, keys)
- Operator console updated with Federation and Organizations tabs
- 7 new federation demo scenarios
- 327 tests (159 new)
- Service catalog with full-text search and category filtering
- Credit-based billing with 10% platform fee
- Per-request and per-token pricing models
- Subscription management with auto-grants and overage billing
- Service ratings and reviews with provider responses
- Exchange gateway API (catalog, invoke, subscribe, billing, reviews)
- Operator console updated with Exchange tab (marketplace, provider, billing views)
- 7 exchange demo scenarios
- 467 tests (140 new)
┌──────────────────────────────────────────────────────────────────┐
│ MoltMesh Bus │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌───────────┐ │
│ │ Contract │ │ Identity │ │ Policy │ │ Trace │ │
│ │ Registry │ │ Registry │ │ Engine │ │ Store │ │
│ └────────────┘ └────────────┘ └────────────┘ └───────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌───────────┐ │
│ │ Budget │ │ Approval │ │ Cost │ │ Dead │ │
│ │ Tracker │ │ Manager │ │ Accounting │ │ Letters │ │
│ └────────────┘ └────────────┘ └────────────┘ └───────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Router │ │
│ │ validate → policy → budget → approve → dispatch → respond │ │
│ │ ↓ circuit breaker ↓ dead-letter on failure │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Echo │ │ HTTP │ │ OpenAI-compatible │ │
│ │ Adapter │ │ Adapter │ │ Adapter │ │
│ └──────────────┘ └──────────────┘ └────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│ │ │
In-process HTTP endpoint OpenAI-style API
agents agents agents
The operator console is a real-time web dashboard for monitoring and controlling the bus. Start the demo server and open http://localhost:3456.
- KPI cards: total workflows, active agents, policy decisions (allow/deny ratio), total cost
- Real-time activity feed with color-coded events
- System health panel showing agent status and circuit breaker states
- Pending approval management with approve/deny actions
- Trace table with contract, agent, status, duration, and token count
- Expandable trace detail with SVG timeline visualization
- Per-event breakdown: policy decisions, token usage, errors
- Card-based registry browser
- Contract detail: capability, version, timeout, retries, approval requirements, required tools
- Agent detail: trust tier, circuit state, capabilities, invocation count, spend, budget usage bar
- Filterable decision log (All / Allowed / Denied)
- Shows agent, contract, decision, rule ID, and reason for each evaluation
- Queue browser with reason, attempt count, timestamps
- One-click resolve action
The flagship demo (demo/full-demo.ts) demonstrates the complete governance surface:
| # | Scenario | What It Shows |
|---|---|---|
| 1 | Happy path research | Contract validation → policy check → HTTP dispatch → trace capture |
| 2 | Policy denial | External vendor blocked from internal-only contract |
| 3 | Tool restriction | Restricted agent denied access to web_search tool |
| 4 | Budget exhaustion | Agent hits daily token limit, subsequent request denied |
| 5 | Circuit breaker | Agent failures trip the breaker → requests fast-fail → half-open recovery |
| 6 | Dead letter + retry | Failed task enters dead-letter queue → resolved → retried |
| 7 | Multi-step workflow | Planner → Researcher (HTTP) → Reviewer (OpenAI) with full tracing |
The federation demo (demo/federation-demo.ts) demonstrates cross-org governance:
| # | Scenario | What It Shows |
|---|---|---|
| 8 | Org registration | Two orgs register: "Acme Corp" (owner) and "Widget Inc" (partner) with namespaces |
| 9 | Namespace isolation | Widget tries to invoke Acme's agent — DENIED (no grant, namespace isolation) |
| 10 | Grant creation | Acme grants Widget access to the "research" capability with 50K token/day limit |
| 11 | Cross-org success | Widget invokes Acme's researcher through the grant — dual-policy check passes |
| 12 | Grant quota exceeded | Widget burns through token budget, next request denied with GRANT_QUOTA_EXCEEDED |
| 13 | Grant revocation | Acme revokes Widget's grant — Widget's next request immediately denied |
| 14 | API key auth | Create an API key for Widget, validate via gateway authentication |
The exchange demo (demo/exchange-demo.ts) demonstrates the inter-org marketplace:
| # | Scenario | What It Shows |
|---|---|---|
| 15 | Service publication | Acme publishes "Deep Research Agent" with per-request pricing (5 credits) |
| 16 | Catalog discovery | Widget searches catalog for "research" — finds Acme's listing, views categories |
| 17 | Credit setup | Show initial balances, Widget adds 500 credits (now 1500 total) |
| 18 | Per-request invoke | Widget invokes Acme's service — 5 credits charged, Acme earns 4.5 (10% platform fee) |
| 19 | Subscription flow | Widget subscribes daily (50 credits/day, 10 requests) — auto-grant created |
| 20 | Overage billing | Widget exceeds 10-request quota — overage charged at per-request rate |
| 21 | Rating & review | Widget rates 4/5 stars, Acme responds — listing rating updated |
Without MoltMesh:
- No visibility into which agent did what
- No budget controls — agents can burn unlimited tokens
- No policy enforcement — any agent can call any tool
- Failed tasks disappear silently
- No audit trail for compliance
With MoltMesh:
- Every step traced with structured events
- Per-agent token budgets with automatic enforcement
- Fine-grained policy: trust tier + tool restrictions + approval gates
- Dead-letter queue captures failures for inspection and retry
- Cost accounting across every trace
import { MoltMesh } from 'moltmesh';
const bus = new MoltMesh({
dbPath: ':memory:', // SQLite path (default: in-memory)
policyRules: [], // Custom policy rules
openAIHandler: handler, // Custom OpenAI handler
});
// Register a contract
bus.registerContract({
contractId: 'research',
version: '1.0.0',
capability: 'research',
description: 'Research a topic',
inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
outputSchema: { type: 'object' },
securityClass: TrustTier.INTERNAL_TRUSTED,
requiredTools: ['web_search'],
timeout: 10000,
retryPolicy: { maxRetries: 2, backoffMs: 1000 },
approvalRequired: false,
});
// Register an agent
bus.registerAgent(
{
agentId: 'researcher',
name: 'Research Agent',
trustTier: TrustTier.INTERNAL_TRUSTED,
capabilities: ['research'],
allowedTools: ['web_search'],
metadata: {},
registeredAt: new Date().toISOString(),
},
{
agentId: 'researcher',
endpoint: 'http://localhost:8080/task',
metadata: { protocol: 'http' },
}
);
// Submit a task
const envelope = bus.createEnvelope('research', '1.0.0', { query: 'AI safety' }, callerIdentity);
const result = await bus.submit(envelope);
// Query traces
const traces = bus.getTrace(envelope.traceId);
const recent = bus.getRecentTraces(50);
// Cost summaries
const agentCosts = bus.getAgentCosts('researcher');
const traceCosts = bus.getTraceCosts(envelope.traceId);import { TrustTier } from 'moltmesh';
TrustTier.INTERNAL_TRUSTED // Broad scoped access
TrustTier.INTERNAL_RESTRICTED // Limited tools, stronger approvals
TrustTier.EXTERNAL_PARTNER // Contract-limited, isolated, full logging
TrustTier.PUBLIC_VENDOR // Zero-trust, explicit allowlistsimport {
MoltMeshError,
PolicyDeniedError,
BudgetExceededError,
CircuitOpenError,
ApprovalRequiredError,
ContractViolationError,
AdapterError,
} from 'moltmesh';
try {
await bus.submit(envelope);
} catch (e) {
if (e instanceof PolicyDeniedError) {
console.log(e.ruleId, e.reason);
} else if (e instanceof BudgetExceededError) {
console.log(e.agentId, e.limit, e.usage);
} else if (e instanceof CircuitOpenError) {
console.log(e.agentId, e.failureCount);
}
}External orgs submit cross-org tasks through the authenticated gateway:
| Method | Endpoint | Description |
|---|---|---|
| POST | /gateway/v1/submit |
Submit a cross-org task |
| GET | /gateway/v1/contracts |
List federated contracts visible to caller |
| GET | /gateway/v1/status/:traceId |
Check status of a submitted task |
| POST | /gateway/v1/webhooks |
Register a webhook for async results |
| GET | /gateway/v1/webhooks |
List webhooks for caller's org |
| DELETE | /gateway/v1/webhooks/:id |
Delete a webhook |
All gateway endpoints require Authorization: Bearer <api-key> header.
Federation management endpoints (no auth required on demo server):
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/orgs |
Register an organization |
| GET | /api/v1/orgs |
List all organizations |
| POST | /api/v1/orgs/:orgId/namespaces |
Create a namespace |
| GET | /api/v1/orgs/:orgId/namespaces |
List namespaces for an org |
| POST | /api/v1/grants |
Create a federation grant |
| GET | /api/v1/grants |
List all grants |
| PATCH | /api/v1/grants/:grantId |
Suspend or revoke a grant |
| GET | /api/v1/grants/:grantId/usage |
Get grant usage stats |
| POST | /api/v1/api-keys |
Create an API key for an org |
Service marketplace endpoints (auth required via Authorization: Bearer <api-key>):
| Method | Endpoint | Description |
|---|---|---|
| GET | /exchange/v1/catalog |
Browse/search published services |
| GET | /exchange/v1/catalog/categories |
List categories with counts |
| GET | /exchange/v1/catalog/:listingId |
Service detail with reviews |
| POST | /exchange/v1/invoke/:listingId |
Invoke a service by listing ID |
| POST | /exchange/v1/subscribe/:listingId |
Subscribe to a service |
| GET | /exchange/v1/subscriptions |
My active subscriptions |
| DELETE | /exchange/v1/subscriptions/:id |
Cancel subscription |
| GET | /exchange/v1/billing/balance |
My credit balance |
| GET | /exchange/v1/billing/transactions |
My transaction history |
| GET | /exchange/v1/billing/earnings |
My earnings as provider |
| POST | /exchange/v1/billing/topup |
Add credits (stub) |
| POST | /exchange/v1/reviews |
Submit a review |
| GET | /exchange/v1/reviews/:listingId |
Reviews for a listing |
| POST | /exchange/v1/reviews/:reviewId/respond |
Provider responds to review |
The demo server (demo/server.ts) exposes 15+ endpoints:
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/submit |
Submit a task to the bus |
| GET | /api/traces |
All trace events |
| GET | /api/traces/:traceId |
Events for a specific trace |
| GET | /api/contracts |
Registered contracts |
| GET | /api/agents |
Registered agents with spend + circuit state |
| GET | /api/policy-log |
All policy decision events |
| GET | /api/costs |
Per-agent cost summaries |
| GET | /api/costs/:agentId |
Cost summary for one agent |
| GET | /api/dead-letters |
Dead letter queue (with ?includeResolved=true) |
| POST | /api/dead-letters/:id/resolve |
Resolve a dead letter |
| POST | /api/dead-letters/:id/retry |
Retry a dead letter |
| GET | /api/approvals |
Pending approval requests |
| POST | /api/approve/:id |
Approve a pending request |
| POST | /api/deny/:id |
Deny a pending request |
src/
contracts/ — Contract schema, registry, JSON Schema validation
identity/ — Agent identity, trust tiers
policy/ — Policy engine, budget tracking, approval workflows
router/ — Task routing, dispatch, circuit breaker, dead letters
adapters/ — Echo, HTTP, OpenAI-compatible adapters
trace/ — SQLite-backed trace storage and querying
cost/ — Per-step token tracking, cost roll-up
federation/ — Organizations, namespaces, grants, usage tracking
gateway/ — API keys, auth middleware, rate limiter, webhooks
exchange/ — Service catalog, billing engine, subscriptions, reviews, exchange API
bus.ts — MoltMesh orchestrator
errors.ts — Typed error classes
index.ts — Public API exports
demo/
agents/ — Planner, Researcher, Reviewer demo agents
scenario.ts — Basic demo scenario
full-demo.ts — 7-scenario flagship demo
federation-demo.ts — 7 federation scenarios
exchange-demo.ts — 7 exchange marketplace scenarios
server.ts — Express server with REST API + console serving
console/
index.html — Operator web console (dark mode, 9 tabs, real-time)
test/ — 467 tests across 28 test files
Apache 2.0