convez.ai
MCP Server
sensigo-hq

realm

sensigo-hq/realm

Ver no GitHub
InicialPluginScore · de 0 a 100

Make AI agents follow instructions reliably and prove what they did. State machine engine with evidence chains, multi-agent delegation, human gates, and auditable execution — via MCP or CLI.

Instalação

$npx convez-ai sensigo-hq/realm

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 1 dia
Versão
v0.50.0
Issues abertas
316
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Realm

The agent calls Realm. Every other tool calls the agent.

Most AI workflow platforms orchestrate LLMs as services: the platform decides when to call the model, what to send, and what to do with the result. Realm inverts this. The agent calls execute_step via MCP. Realm's state machine responds with the current step's task and schema. The agent executes. It cannot skip steps, produce malformed output, or proceed past a human gate — not because of instructions it might ignore, but because the state cannot change until valid output is submitted.

If your skill file has grown a list of "Do NOT" rules, each one is a scar from a failure the agent invented. Realm replaces those rules with structure: wrong behaviour becomes impossible rather than prohibited.

You define workflows in YAML. The engine enforces step order, validates every agent output against a JSON schema, captures tamper-evident evidence at each step, and pauses at human gates until a person approves. The result is not just a log of what ran — it is a cryptographically verifiable record that every step ran correctly. For developers building AI workflows for clients, that record is the deliverable.

Packages

PackagenpmDescription
@sensigo/realmnpmCore engine — state guard, execution loop, evidence capture
@sensigo/realm-clinpmrealm CLI — 18 commands for building, operating, and serving workflows
@sensigo/realm-mcpnpmrealm-mcp MCP server — 9 tools for AI agent connections
@sensigo/realm-testingnpmTesting utilities — fixtures, assertions, in-memory store

Installation

CLI (global)

npm install -g @sensigo/realm-cli

MCP server (global, for AI agent connections)

npm install -g @sensigo/realm-mcp

Programmatic use

npm install @sensigo/realm

Testing utilities

npm install --save-dev @sensigo/realm-testing

Quick Start

1. Scaffold a workflow

realm workflow init my-workflow

This creates my-workflow/ with workflow.yaml, schema.json, .env.example, and a README.md.

2. Edit my-workflow/workflow.yaml

id: my-workflow
name: 'My Workflow'
version: 1

steps:
  gather_input:
    description: 'Agent collects the required information'
    execution: agent
    depends_on: []
    input_schema:
      type: object
      required: [summary]
      properties:
        summary:
          type: string

  finalize:
    description: 'Human reviews and approves the submitted summary'
    execution: auto
    depends_on: [gather_input]
    trust: human_confirmed

3. Validate, register, and run

realm workflow validate ./my-workflow   # check the YAML
realm workflow register ./my-workflow   # register with the local store
realm workflow run ./my-workflow        # run interactively (development mode)

realm workflow run drives the workflow step by step, prompting you for simulated agent output and pausing at human gates.

Connect an AI Agent via MCP

Start the MCP server (built into the CLI — no extra install needed):

realm mcp

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "realm": {
      "command": "realm",
      "args": ["mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "realm": {
      "command": "realm",
      "args": ["mcp"]
    }
  }
}

Hosted agent platforms (OpenClaw, Claude.ai, custom backends) that cannot spawn a local subprocess use realm serve instead:

REALM_SERVE_TOKEN=<secret> realm serve --port 3001

This starts an HTTP MCP server protected by Bearer token authentication. Use --dev to skip auth during local development.

Once connected the agent has access to 9 tools: list_workflows, get_workflow_protocol, start_run, start_run_batch, execute_step, submit_human_response, get_run_state, create_workflow, and list_runs.

The agent calls list_workflows to discover registered workflows, then get_workflow_protocol for the matched workflow to receive explicit step-by-step instructions. It cannot execute a step out of order or submit output that fails schema validation.

When no registered workflow matches the task, the agent calls create_workflow with a steps array to register a dynamic workflow and immediately start a run — no YAML file or realm workflow register required. The run proceeds identically to a YAML workflow from that point.

Multiple workflows: register as many as you need with realm workflow register. The agent discovers them all via list_workflows and picks the right one by ID. Add a skill.md alongside each workflow for workflow-specific agent behaviour.

CLI Reference

CommandDescription
realm workflow init <name>Scaffold a new workflow project directory
realm workflow validate <path>Validate a workflow YAML without registering it
realm workflow register <path>Register a workflow in the local store
realm workflow watch <path>Watch a workflow YAML and re-register on every change
realm workflow run <path>Run a workflow interactively (development mode)
realm agentRun a workflow autonomously with an LLM — no MCP client or IDE required
realm workflow test <path>Run fixture-based tests against a workflow
realm run listList all runs; filter by --workflow <id> or --status <phase>
realm run resume <run-id>Resume a paused run
realm run respond <run-id>Submit a response to a human gate
realm run inspect <run-id>Print the full evidence chain for a run
realm run replay <run-id>Re-evaluate preconditions with modified step outputs
realm run diff <run-a> <run-b>Compare evidence chains of two runs side by side
realm run cleanupMark idle non-terminal runs as abandoned
realm workflow migrateBack-fill provenance fields on local workflow definitions from earlier versions
realm mcpStart the MCP server over stdio (for local AI agents)
realm serveStart the MCP server over HTTP with Bearer token auth (for hosted platforms)
realm webhookStart a webhook server that creates runs from GitHub events

Run realm <command> --help for full options on any command.

Documentation

Development

Prerequisites: Node.js 22+, npm 10+

npm install          # install all workspace dependencies
npm run build        # compile all packages
npm run test         # run all tests
npm run lint         # lint all packages

License

Apache 2.0

Ver o original no GitHub

Bom para

Relacionados