Skip to content

@maiaos/protocol

The operation registry and Effect Schema contracts that Maia Node and every Maia OS client agree on: operation IDs, request and response envelopes, errors, receipts and MCP tool definitions.

Pre-release. Maia publishes canary builds to npm only, and latest follows the newest one (earlier nightly builds are historical). They are not release-qualified, and Maia has no stable release (D-202).

Requirements

Node.js 24.22.1.

Install

pnpm add @maiaos/protocol@canary

Usage

Validate a Maia payload with a runtime schema:

import {
  MAIA_PROTOCOL_VERSION,
  projectListParametersSchema,
} from "@maiaos/protocol";

const parsed = projectListParametersSchema.safeParse({
  afterCursor: "0",
  limit: 20,
});
if (parsed.success) console.log(MAIA_PROTOCOL_VERSION, parsed.data.limit);
// maia.protocol/v1alpha1 20

Every schema exposes parse and safeParse, and its TypeScript type is inferred from it. To call a running Node, use @maiaos/sdk.

Status

Source candidate. This package is the single source of truth for Maia's wire contracts: the Node validates every request against it, and the SDK, CLI and MCP server are generated from it or checked against it. The contracts carry the maia.protocol/v1alpha1 identifier, and additions to it are listed in the compatibility policy.

In this section

  • Connection protocol

    Source candidate for named vendor-executor accounts (maia.connection/v1). The decision record is External brain and vendor executors.

  • Coordinator tool registry

    coordinatorToolDefinitions() lists the Node operations an external coordinator (Claude Code or Codex acting as the brain) may call as MCP tools.

  • External-origin interaction contract candidate

    This standalone module defines strict request, projection and result parsers for the accepted R1a interaction.create, interaction.list, interaction.show, interaction.respond, and interaction.cancel…

  • Harness compatibility contracts

    These protocol files describe imported compatibility operations. They are not advertised CLI runtime options.

  • Operator-local presentation candidate

    The bounded contract exposes presentation.catalog.show, presentation.workspace-directory.show, presentation.project-list.show and presentation.session-list.show.

  • Port lease protocol

    Source candidate for advisory TCP port leases (maia.port-lease/v1). Maia supplies the tool; agents and Skills decide how to use the ports.

  • Run ledger protocol

    Source candidate for the Run ledger over executor Sessions (maia.run-ledger/v1, S19): the coordinator's durable memory of a task graph whose dispatches are Codex or Claude Code Session turns…

  • Session guard protocol

    Source candidate for S18a Session-bound worker credentials and S18b fan-out guards (maia.session-guard/v1). The Node enforces both.

Imported from Maia OS docs at a2175bb