# Monitor Protocol

[![npm version](https://img.shields.io/npm/v/@mentu/monitor-protocol)](https://www.npmjs.com/package/@mentu/monitor-protocol)
[![Node.js 20 or newer](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![CI status](https://github.com/mentu-ai/monitor-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/mentu-ai/monitor-protocol/actions/workflows/ci.yml)

**Shared monitors for people and agents: durable observations, independent subscriptions, and delivery into the tools they use.**

[Read the documentation](https://docs.mentu.ai/monitor-protocol/overview) · [Try it in your browser](https://docs.mentu.ai/monitor-protocol/playground) · [Quickstart](https://docs.mentu.ai/monitor-protocol/quickstart) · [Package on npm](https://www.npmjs.com/package/@mentu/monitor-protocol)

## The idea

A workspace can have people working in Codex, Claude Code, other agent tools, and ordinary terminals. They need to observe the same work while keeping their own place in it.

The Monitor Protocol gives them a shared service. A monitor exists independently of any conversation, records observations with provenance, and lets each participant subscribe with its own durable cursor. HTTP, SSE, and MCP expose the same objects and rules.

Delivery into a live conversation is a separate adapter. Claude Code's Monitor tool can follow a subscription. The Codex terminal bridge in this checkout can notify an existing, human-opened session through its native queue. A client without a supported wake mechanism can pull when its user returns. The workspace and its observations survive the end of any one session.

The same observations can also feed an operator-defined routine: start a script or agent job
when work arrives, record its result, then exit. The [routine runner design](docs/use-cases/event-triggered-routines.md)
also covers direct CLI invocation by a person, agent, or action, with prompts and context fetched
from local or cloud sources. A bounded implementation now lives in
[Mentu Recipes](https://github.com/mentu-ai/mentu-recipes/tree/b24d7cda2983ba279ad1f28d7e6af0266e7c5f46/integrations/continuity):
pinned local/HTTPS inputs, a fixed execution policy, and a one-shot MP consumer that acknowledges
after a durable report. A continuously supervised general routine service remains design work.

## What it does

There are five parts, and each one is small.

- **A monitor** is a definition: what is watched, how often, and with what authority.
- **An observation** is one thing the monitor saw. Each one says where it came from, who caused it, and how much it is worth believing.
- **A state** is the monitor's running summary, computed from its observations. It says out loud what it does not know, instead of filling the gap with a number.
- **A subscription** is a reader with its own place in the stream, called its cursor. It reads, does the work, and only then acknowledges. A reader that crashes gets the same items again instead of losing them.
- **A lease** is how two workers avoid doing the same job twice. It expires on its own if the worker holding it stops.

Configuration is not a sixth part. Pausing a monitor, changing its filter or retiring it is recorded as an observation too. Six months later, the question "why did this change?" has an answer.

## What makes it more than a queue

A queue moves messages and forgets them. The Monitor Protocol keeps them as evidence.

**A machine cannot claim a person's level of certainty.** Every observation carries a rating, from `src` (a person checked it against the source) down to `falsified` (checked, and found untrue). A program can report what it measured. The top of the ladder needs a person behind the observation. An agent working for you reaches your level by naming you in one field, `on_behalf_of`, and the record keeps both names: the agent that saw it, and the person it worked for. It can only name the person who owns the monitor, so it cannot borrow anyone else's level. Anything that tries to climb higher is refused, and the refusal is kept as an observation.

An independent audit showed that the first version of this check could be fooled, because it read its answer from the same request it was judging. It is now enforced, and the conformance suite tests it from five different angles.

**It does not lie by leaving things out.** A confidence with a missing input lists the input as missing. A source that did not answer is reported as not answering, never as zero. The count of waiting items covers only what this reader would actually receive, so it can reach zero.

## Try it

The fastest way is the [playground](https://docs.mentu.ai/monitor-protocol/playground): the real engine runs in your browser, and nothing leaves the page.

To run it yourself, you need [Node.js](https://nodejs.org) 20 or newer. Start a server:

```bash
npx @mentu/monitor-protocol serve --port 8130
```

Then, in use, it is four steps:

```bash
# 1. Define what is watched. The reply includes an owner token, shown once. Keep it.
curl -s localhost:8130/mp/v0/monitors \
  -d '{"id":"ci","name":"CI","horizon":"minute","capabilities":["observe"],"visibility":"public","types":["com.example.ci.run"]}'

# 2. A producer records what it saw, using the owner token.
curl -s localhost:8130/mp/v0/monitors/ci/observations -H "Authorization: Bearer $OWNER_TOKEN" \
  -d '{"type":"com.example.ci.run","subject":"build-412","actor":"probe:ci","tier":"measured","origin":"probe","data":{"status":"failed"}}'

# 3. A reader subscribes once, then takes what it has not seen yet.
curl -s localhost:8130/mp/v0/subscriptions -d '{"monitor":"ci","subscriber":"agent:reviewer","capabilities":["observe"]}'
curl -s "localhost:8130/mp/v0/subscriptions/$SUBSCRIPTION/pull" -H "Authorization: Bearer $READER_TOKEN"

# 4. It commits only after handling it. Send the "next" value from the pull reply.
curl -s localhost:8130/mp/v0/subscriptions/$SUBSCRIPTION/ack -H "Authorization: Bearer $READER_TOKEN" -d '{"cursor": 3}'
```

Reading never moves the cursor. Only an acknowledgement does, and it never moves backwards. The [quickstart](https://docs.mentu.ai/monitor-protocol/quickstart) walks through each reply.

## Use it from your workspace

Give each participant its own subscription. Reading or waking one participant does not advance another participant's cursor. Connecting a client over [MCP](https://modelcontextprotocol.io) gives it tools; whether it can start a turn from a notification depends on its host.

See [Shared terminal peers and event driven routines](docs/use-cases/shared-terminal-peers.md)
for both execution modes, component responsibilities, lifetimes, and live-test evidence.

Sessions also need verified tools. The [capability admission API](docs/tool-capabilities.md)
checks pinned MCP tools through the actual Codex thread and requires fresh successful calls
before admitting work. It does not inherit the Codex app's private tools or credentials.
The [workspace status view](docs/workspace-status.md) keeps source health, transport, handling,
tool readiness and native wake evidence separate.
An optional handling expectation flags overdue delivery receipts even while their
worker stays alive; it never acknowledges or launches work.
The [shared harness contract](docs/shared-harness-contract.md) aligns the Claude plugin design,
Codex host integration and other providers around the same semantic capability requirements,
ticket ownership, recipes and handling receipts. Concrete adapters must pass their own trials.

| Client | How it receives work | What advances its cursor |
| --- | --- | --- |
| Codex with the native runtime preview | A Rust/Tokio consumer inside the rebuilt App Server wakes the existing attended thread when idle | `monitor_handled` for observations; durable scan receipts for empty filtered ranges |
| Codex in an existing terminal session | Optional bridge to the live session's native `queue` capability | An explicit `bridge handled` receipt after processing |
| Claude Code with the Monitor tool | `watch` running in a Monitor arm | The session runs `ack` after processing |
| Other MCP, HTTP, or terminal clients | Pull; a host-specific wake adapter where one is implemented | The client acknowledges after processing |

### Native Codex runtime preview

The [native Codex integration](integrations/codex-native/README.md) contains a pinned source patch
and build instructions. It adds session-owned `monitor_start`, `monitor_status`, `monitor_show`,
`monitor_handled`, and `monitor_stop` tools inside Codex. An operator registers each source;
disconnecting or unsubscribing its owning frontend cancels the native consumer. Events arriving
during a turn stay pending until guarded idle admission.

This requires the rebuilt Codex runtime. It is not activated by installing this npm package,
an MCP server, or a skill, and it does not modify an already running Codex conversation.

### Codex terminal bridge

The bridge ships in the package from 0.3.0. If the version on npm is older than 0.3.0, build it from this checkout, then run it from the Codex session a person already opened:

```bash
npm ci
npm run build
# Set MP_SUBSCRIPTION_TOKEN securely to this participant's existing reader token.
node dist/index.js bridge run --adapter codex \
  --base http://localhost:8130 --subscription <id> \
  --token-env MP_SUBSCRIPTION_TOKEN --state ~/.monitor-protocol/codex-session
```

The bridge discovers that session, checks its native queue capability, and stops when the session dies or `bridge stop` is requested. It never opens or resumes a model session. A notification carries a delivery reference and fingerprint. The session reads it with `bridge show`, handles it under its existing authority, and records a disposition with `bridge handled`. Only then does the bridge acknowledge the subscription.

The [session bridge guide](docs/session-bridge.md) covers commands, supported platforms, receipts, retries, and how to add another provider adapter.

### Claude Code and MCP

Add it to Claude Code as an MCP server. It runs its own monitor server, so give it its own state file:

```bash
claude mcp add -s user monitor-protocol -- npx -y @mentu/monitor-protocol mcp --state ~/.monitor-protocol/mcp-state.json
```

Or follow a subscription from a session with the Monitor tool:

```text
Monitor(command: "npx -y @mentu/monitor-protocol watch --base http://localhost:8130 --subscription <id> --token <token> --catch-up")
```

The watch prints one line per observation and, after each batch, `NEXT <cursor>`. By default the CLI acknowledges nothing: once the session has handled the batch, it runs `monitor-protocol ack --base <url> --subscription <id> --token <token> --cursor <n>`. When the Monitor's time runs out, start it again. The subscription remembers the last place the session acknowledged, so an unhandled batch remains eligible for redelivery within the server's retention period. If the server restarts, the watch prints `DOWN`, waits, and carries on when the server is back. The guide [Claude Code and MCP](https://docs.mentu.ai/monitor-protocol/claude-code) covers both, and the tools.

The `watch` command also works in an ordinary terminal. Printing or enqueueing a notification is not processing it. Do not use the compatibility option `--ack-on-print` for a session that still needs to act on the output. Library callers must set `ackAfterPrint: false` explicitly; its historical default remains `true`.

## Safe by default on your machine

A monitor server usually runs next to a web browser, so it assumes every web page you open can reach it.

- **A web page is not you.** Requests from a browser page are refused unless you allow that page with `--allow-origin`. Command line tools are unaffected.
- **Nothing reaches it through a borrowed name.** On your own machine it only answers to `localhost`, `127.0.0.1` and `::1`, which stops DNS rebinding.
- **One request cannot exhaust it.** Request bodies over 1 MiB are refused.
- **Your state survives a bad day.** Each write is flushed to disk before it replaces the last, the previous copy is kept, and a damaged file is set aside instead of overwritten.
- **Only one server writes a state file.** A second one refuses to start and says which process holds it.

## Learn more

- [What is the Monitor Protocol?](https://docs.mentu.ai/monitor-protocol/overview)
- [Introducing the Monitor Protocol](https://docs.mentu.ai/monitor-protocol/introducing): why we built it, and how it works
- [Agents acting for people](https://docs.mentu.ai/monitor-protocol/trust): the trust rules in plain words
- [Concepts](https://docs.mentu.ai/monitor-protocol/concepts) and [Reference](https://docs.mentu.ai/monitor-protocol/reference)
- [The fourteen principles](spec/00-principles.md), each one learned from something that went wrong in a running system

## What is in this repository

| Folder | What it holds |
| --- | --- |
| [`spec/`](spec/) | The specification: [principles](spec/00-principles.md), [objects](spec/01-objects.md), [methods](spec/02-methods.md), [bindings](spec/03-bindings.md), [delivery](spec/04-delivery.md) and the [conformance checklist](spec/05-conformance.md) |
| [`schemas/`](schemas/) | A JSON Schema for every object. Where the prose and a schema disagree, the schema wins. |
| [`src/`](src/) | The reference server, CLI, MCP server, clients, and session bridge, in TypeScript |
| [`conformance/`](conformance/) | The conformance suite in Python, next to the TypeScript one in `src/` |
| [`adapters/`](adapters/README.md) | Server implementations and session delivery adapters, with their separate compatibility requirements |
| [`integrations/codex-native/`](integrations/codex-native/) | Pinned patch and build instructions for the native Codex runtime preview |
| [`docs/`](docs/) | Why each design choice was made, including a running [decision log](docs/decisions.md) |

## Build your own implementation

Read the [principles](spec/00-principles.md), implement the five objects over HTTP, and run the conformance suite against your server:

```bash
npx @mentu/monitor-protocol conform --base http://127.0.0.1:8124
python3 conformance/python/run.py --base http://127.0.0.1:8124 --subjects a,b,c
```

The suite covers C01–C34. Run it against the version you intend to deploy. Atrio, an event log, is a second implementation; its published results and limitations are recorded in [the implementation guide](adapters/README.md). Server conformance and the ability to wake a particular session are tested separately.

To use the reference server as a library:

```ts
import { MemoryStore, MonitorService, createHttpServer, MonitorClient } from "@mentu/monitor-protocol";
const service = new MonitorService(new MemoryStore("state.json"));
```

## Status

Releases are tagged on GitHub and listed in the [changelog](CHANGELOG.md). Not every tag reached npm: 0.2.0 and 0.3.0 were tagged but never published there. A release reaches npm only as the tarball that CI built and tested. From 0.3.0, a release includes the session bridge described above. The objects and methods are stable enough to build on. Names such as the `ai.mentu` prefix may still change before version 1.0. Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[Apache 2.0](LICENSE).