One action contract. Every surface.
A framework-agnostic TypeScript action registry that keeps validation, execution, errors and retry semantics attached to one operation, then exposes thin adapters around it.

Project page · Demo fixture · Latest release

Try it in 30 seconds

npm install github:yashkhou/actionmesh zod

import { defineAction, ActionRegistry } from 'actionmesh';

Why I built this

The same capability often gets rewritten as a backend route, an agent tool, a CLI script and an MCP handler. Those copies drift. ActionMesh keeps one implementation and treats transports as adapters—not new places for business logic.

What ships today

• Typed defineAction() contracts
• Zod input validation before execution
• Optional output validation
• Stable machine-readable ActionMeshError codes
• Retries only when explicitly retryable
• MCP-style listTools() / callTool() adapter
• Node HTTP handler and CLI invocation helper

Real demo

Inspect the adapter demo fixture →

Quick start

git clone https://github.com/yashkhou/actionmesh.git
cd actionmesh
npm install
npm test
npm run build
node examples/demo.mjs

Small example

const registry = new ActionRegistry().register(defineAction({
  name: "lookup-lead",
  description: "Look up a lead by id",
  input: z.object({ id: z.string() }),
  output: z.object({ id: z.string(), status: z.string() }),
  run: async ({ id }) => ({ id, status: "active" }),
}));

await registry.invoke("lookup-lead", { id: "lead_123" });

Architecture

flowchart LR
    A[UI / app] --> E[Action contract]
    B[Agent] --> E
    C[MCP-style adapter] --> E
    D[HTTP / CLI] --> E
    E --> F[Input schema]
    F --> G["run()"]
    G --> H[Output schema]
    H --> I[One result / error contract]

Loading

The design rule is intentionally narrow: one action owns the contract; adapters translate transports without reimplementing business logic.

Good fits

• Keep an agent tool and application API on the same implementation
• Generate tool schemas from the same runtime validation
• Centralize retryable vs deterministic failures
• Reuse backend operations from scripts and CI without duplicating logic

FAQ

What is ActionMesh?

ActionMesh is a framework-agnostic TypeScript action registry that keeps an operation’s input schema, output schema, implementation, errors and retry semantics in one contract.

Why use ActionMesh instead of separate handlers?

It reduces drift between agent tools, HTTP routes, CLI commands and MCP-style surfaces by keeping business logic in one action implementation and treating transports as adapters.

Does ActionMesh implement the official MCP transport?

The current release ships an MCP-style listTools/callTool adapter. An official Model Context Protocol SDK transport is a separate roadmap item.

What validates ActionMesh inputs?

ActionMesh uses Zod schemas for runtime input validation and can also validate outputs before returning them to callers.

Roadmap

• Official Model Context Protocol transport package
• OpenAPI generation
• Action middleware and authorization policies
• Structured audit hooks
• Concurrency and idempotency policies

Related tools

• BrowserProof - browser-state verification for AI agents and Playwright workflows.
• RunLedger - tamper-evident execution history for AI-agent runs.
• ActionMesh - typed action contracts for tools, HTTP and CLI.

Development

npm install
npm test
npm run build

CI runs tests and the TypeScript build on every push and pull request.

Project links

• Docs source: docs/
• Project page: https://yashkhou.com/projects/actionmesh
• Source: https://github.com/yashkhou/actionmesh
• Author: Yash / @yashkhou

License

MIT. See LICENSE.