@maiaos/sdk

The TypeScript SDK for Maia Node: typed, validated calls to create and drive AI coding agent Sessions, send turns, wait for results, read receipts and observe events.

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.
A running Maia Node on the same machine. See the quick start.

Install

pnpm add @maiaos/sdk@canary

Usage

import { connectNodeApi } from "@maiaos/sdk/node";

const { client, status } = await connectNodeApi({ profile: "default" });
console.log(status.lifecycle); // "ready"

const projects = await client.listProjects(
  { afterCursor: "0", limit: 20 },
  { messageId: "request_projects_1" },
);
for (const project of projects.items) console.log(project.id, project.name);

connectNodeApi finds the profile's private connection descriptor, reads its credential and proves the Node's identity before it returns the client. A mutation takes a revision and a command ID you choose; after an unknown outcome, retry with the same command ID and read the receipt with client.getReceipt.

Every call takes request options: a messageId, an optional signal to cancel and an optional deadlineAt, a bigint on your own Clock.monotonicTimeNanos for an in-process requester that bounds its waiting. The SDK's own requesters ignore deadlineAt.

Status

Source candidate. This is the only request boundary between product clients and Maia Node: the maia CLI, the MCP server and the Desktop and Expo clients use it. It transports typed operations and never owns business authority. Many methods mirror operations that are release-disabled at the Node.