# Mayura

> Mayura is a TypeScript framework for building AI agents, typed tools and durable workflows. It is one npm package, `mayura`: the root import is the core SDK (agents, tools, runtime) and every other part is a subpath such as `mayura/provider-openai` or `mayura/workflows/lifecycle`. The `mayura` CLI creates, runs and operates projects.

Rules that matter when writing Mayura code:

- Import from `mayura` or `mayura/<entry point>`, never from `@mayura/...`.
- Schemas use `z` from `mayura` (it is Zod 4); do not install or import `zod` separately.
- Nothing is allowed by default: grant `model:<adapter id>`, `tool:<tool id>`, `effect:<read|write|host>` and each tool capability in `createRuntime({ permissions: { allow } })`.
- Costs are in micros (1,000,000 = 1 US dollar). A run may spend nothing until `limits.maxCostMicros` is set; model adapters need prices and a per-call `maxCostMicros`.
- Mayura generates the JSON Schemas providers need from Zod schemas; providers accept only strict ones, so use `.nullable()`, not `.optional()`, for fields a model may leave empty.
- Check `result.status` before reading `result.output`; `outcome_unknown` means reconcile, not retry.
- Test offline with `scriptedModel` from `mayura/testing`.

## Get started

- [Introduction](docs/introduction.md): What Mayura is, the ideas behind it, and how its parts fit together.
- [Quickstart](docs/quickstart.md): Create a Mayura project in one command, or add a first agent to your own project and run it offline or on a real model.
- [Installation](docs/installation.md): Requirements, the optional packages each part of Mayura needs, and TypeScript settings.
- [Using Mayura with AI coding agents](docs/ai-agents.md): Point Claude Code, Cursor, Codex and other coding assistants at documentation that matches your installed Mayura version.

## Concepts

- [Agents](docs/concepts/agent.md): Define an agent: instructions, a model, typed tools and typed input and output, checked once and reused for every run.
- [Tools](docs/concepts/tools.md): Define typed tools with defineTool: schemas, effects, capabilities, cost, timeouts, refusals and batches.
- [Runtime](docs/concepts/runtime.md): Create a runtime, submit agents, watch their events, cancel them and read their outcome, costs and evidence.
- [Outcomes and errors](docs/concepts/outcomes.md): Every run ends with one outcome: succeeded, failed, blocked, cancelled or outcome_unknown. What each means and what to do.
- [Permissions](docs/concepts/permissions.md): Explicit allow-lists decide which models, tools, effects and capabilities a run may use. Nothing is allowed by default.
- [Costs and budgets](docs/concepts/costs-and-budgets.md): Cap what a run can spend: costs in micros, per-call ceilings, the run cost limit, tool costs and shared budgets.
- [Workflows](docs/concepts/workflows.md): What a Mayura workflow is, when to use one instead of a single agent run, and which workflow entry point to start with.

## Agents and models

- [Model providers](docs/guides/model-providers.md): Connect an agent to OpenAI, Anthropic or any OpenAI-compatible endpoint, with explicit keys, prices and a per-call cost limit.
- [Model routing](docs/guides/model-routing.md): Fail over between model providers with createModelRouter: priority order, a circuit breaker and conservative cost accounting.
- [Streaming](docs/guides/streaming.md): Stream one text field of an agent's answer as the model writes it, with guards on every batch and the final output still checked.
- [Vision: images and PDFs](docs/guides/vision.md): Agents that see: send images and PDFs with an agent's input, return screenshots from tools, and keep media checked, limited and out of logs.
- [Child agents](docs/guides/child-agents.md): Let one agent call another as a tool, spawn child runs from your code, or race speculative branches, under one shared budget.
- [Skills](docs/guides/skills.md): Give an agent SKILL.md folders of task instructions that it loads only when a task needs them.
- [MCP tools](docs/guides/mcp.md): Wrap one operation of a Model Context Protocol server as a Mayura tool, with the effects, permissions and cost you declare.
- [Terminal](docs/guides/terminal.md): Chat with an agent in the terminal, or turn it into a one-shot command, with a person confirming actions and answering questions.
- [Testing](docs/guides/testing.md): Test agents, tools and provider settings without a network or an API key, using scriptedModel from mayura/testing.

## Workflows

- [Workflow composition](docs/guides/workflow-composition.md): Run a fixed graph of tool calls in-process as an agent, or hand it to another agent as a single tool.
- [Durable workflows](docs/guides/durable-workflows.md): Define and run workflows that survive restarts, wait for people and timers, and never repeat a step whose outcome is unknown.
- [Approvals and human input](docs/guides/approvals-and-human-input.md): Stop a durable workflow until a person approves an exact tool call or answers a typed question, and respond from code, CLI or UI.
- [Sagas and loops](docs/guides/sagas-and-loops.md): Compose durable workflows into sagas that undo finished steps when a later one fails, and into loops that repeat until a condition is met.
- [Webhooks](docs/guides/webhooks.md): Accept signed webhook deliveries, verify their HMAC signature and freshness, and start work exactly once per delivery.
- [Operating workflows](docs/guides/workflow-operations.md): Run durable workflows in production: list and inspect runs, cancel, pause, hold the whole fleet, and ship new definition versions safely.

## Data, safety and extensions

- [Storage](docs/guides/storage.md): Persist durable workflows, memory, budgets and jobs in SQLite or PostgreSQL, run migrations, and back the store up.
- [Memory and context](docs/guides/memory-and-context.md): Give agents scoped long-term memory with lexical, semantic and hybrid search, and assemble prompt context within a budget.
- [Guardrails](docs/guides/guardrails.md): Check, redact or block what goes into and comes out of an agent with local guards, processor pipelines and model-backed moderation.
- [Lifecycle hooks](docs/guides/lifecycle-hooks.md): Run your own checks and observers at fixed points of an agent run: before model and tool calls, before output release, and at the end.
- [Artifacts](docs/guides/artifacts.md): Store files your agents produce on local disk with verified content, per-tenant isolation, safe downloads, audits and backups.
- [Code Mode](docs/guides/code-mode.md): Run small JavaScript programs, including model-written ones, in a sandbox that can call only the tools you allow.
- [Helpers](docs/guides/helpers.md): Small utilities for configuration, secrets, retries, cancellation, pagination, redacted logging and budgeted concurrency.

## Serve, observe and deploy

- [Server and client](docs/guides/server-and-client.md): Serve agents over authenticated HTTP with mayura/server and mayura/server-node, and call them from browsers or Node with mayura/client.
- [React and UI bindings](docs/guides/react.md): Show live agent runs, workflow progress and human response forms in React, or in any UI framework through headless stores.
- [Observability](docs/guides/observability.md): Watch agent runs through their metadata events, keep run summaries, and export logs, traces and metrics to OpenTelemetry.
- [Operator console](docs/guides/operator-console.md): A built-in web console for operators: health, agents and tools, workflow runs, approvals, human requests, fleet control and migrations.
- [Deployment](docs/guides/deployment.md): Run a Mayura app in production: on containers, Kubernetes, managed platforms, virtual machines, serverless functions or inside an app you already run.

## CLI

- [CLI overview](docs/cli/overview.md): Install and run the mayura command: its commands, readable and JSON output, help, version, exit codes and errors.
- [Create a project](docs/cli/init.md): Create a Mayura project from a starter or a template with mayura init, interactively or with flags, then validate and inspect it.
- [Develop with mayura dev](docs/cli/dev.md): Build and run your project with mayura dev, load .env, and rebuild and restart on every saved change.
- [Serve, worker and migrate](docs/cli/run.md): Run your application in production with mayura serve, mayura worker and mayura migrate, and write the module they load.
- [Operate a server](docs/cli/operations.md): Inspect and control a running Mayura server from the CLI: health, tools, runs, human requests, workflows and the fleet.

## Reference

- [Entry points](docs/reference/entry-points.md): Every public entry point of the mayura package: what it is for, its key exports and the optional packages it needs.

## Project

- [Versioning](docs/project/versioning.md): What Mayura keeps stable, how versions follow SemVer, how APIs are deprecated, and how release candidates and npm tags work.
- [Support](docs/project/support.md): Supported Node.js versions, platforms and package managers, how to get help with Mayura, and how to report a bug.
- [Security](docs/project/security.md): Mayura's security model: what it protects, what your code is trusted with, and how to report a vulnerability.
- [Credits](docs/project/credits.md): The open-source projects and open standards Mayura is built on, what each one does in Mayura, and its license.

## Optional

- [All of the documentation in one file](llms-full.txt)