MacpClient API Reference

MacpClient is the low-level gRPC transport layer. It manages the connection to the MACP runtime and provides typed wrappers for all RPCs.

Constructor

import { MacpClient } from 'macp-sdk-typescript';

const client = new MacpClient({
  address: '127.0.0.1:50051',
  secure: false,
  auth: Auth.devAgent('agent'),
  rootCertificates: undefined,
  defaultDeadlineMs: 10_000,
  clientName: 'my-app',
  clientVersion: '1.0.0',
  protoDir: '/path/to/proto',
});

Options

Option	Type	Default	Description
`address`	`string`	required	gRPC server address (`host:port`)
`secure`	`boolean`	`false`	Use TLS credentials
`auth`	`AuthConfig`	`undefined`	Default auth for all operations
`rootCertificates`	`Buffer`	`undefined`	TLS root CA certificates
`defaultDeadlineMs`	`number`	`undefined`	Default RPC deadline (ms)
`clientName`	`string`	`'macp-sdk-typescript'`	Client name for Initialize
`clientVersion`	`string`	`'0.1.0'`	Client version for Initialize
`protoDir`	`string`	`<pkg>/proto`	Proto definitions directory

Properties

Property	Type	Description
`auth`	`AuthConfig \| undefined`	Default auth config
`protoRegistry`	`ProtoRegistry`	Protobuf encode/decode registry

Methods

`initialize(deadlineMs?)`

Handshake with the runtime. Negotiates protocol version and exchanges capabilities.

const result: InitializeResult = await client.initialize();
// result.selectedProtocolVersion — '1.0'
// result.runtimeInfo — { name, title, version, description, websiteUrl }
// result.supportedModes — ['macp.mode.decision.v1', ...]
// result.capabilities — { sessions: { stream: true }, ... }
// result.instructions — optional human-readable guidance

`send(envelope, options?)`

Send an envelope to the runtime. Returns the Ack.

const ack: Ack = await client.send(envelope, {
  auth: Auth.devAgent('agent'),  // override default auth
  deadlineMs: 5000,              // override default deadline
  raiseOnNack: true,             // default: true; throw MacpAckError on nack
});

`getSession(sessionId, options?)`

Query session metadata.

const { metadata } = await client.getSession('session-id', { auth, deadlineMs });
// metadata.state — 'SESSION_STATE_OPEN', 'SESSION_STATE_RESOLVED', 'SESSION_STATE_EXPIRED'
// metadata.mode — 'macp.mode.decision.v1'
// metadata.startedAtUnixMs, metadata.expiresAtUnixMs

`cancelSession(sessionId, reason, options?)`

Cancel an open session. Returns Ack.

const ack = await client.cancelSession('session-id', 'no longer needed', { auth });

`getManifest(agentId?, deadlineMs?)`

Retrieve an agent or runtime manifest.

const { manifest } = await client.getManifest();       // self manifest
const { manifest } = await client.getManifest('other'); // another agent

`listModes(deadlineMs?)`

List standards-track modes.

const { modes } = await client.listModes();
// modes: ModeDescriptor[]

`listExtModes(deadlineMs?)`

List dynamically registered extension modes.

const { modes } = await client.listExtModes();

`listRoots(deadlineMs?)`

List coordination roots/boundaries.

const { roots } = await client.listRoots();
// roots: Root[] — [{ uri, name }]

`registerExtMode(descriptor, options?)`

const result = await client.registerExtMode({
  mode: 'ext.custom.v1',
  modeVersion: '1.0.0',
  title: 'Custom Mode',
  description: 'My custom coordination mode',
  messageTypes: ['CustomMsg'],
  terminalMessageTypes: ['Commitment'],
}, { auth });

`unregisterExtMode(mode, options?)`

Remove a dynamically registered extension mode.

const result = await client.unregisterExtMode('ext.custom.v1', { auth });

`promoteMode(mode, promotedModeName?, options?)`

Promote an extension mode to standards-track.

const result = await client.promoteMode('ext.custom.v1', 'macp.mode.custom.v1', { auth });

`openStream(options?)`

Open a bidirectional session stream.

const stream: MacpStream = client.openStream({ auth });

`senderHint(auth?)`

Get the sender identity hint from the given or default auth config.

const sender: string | undefined = client.senderHint();

`close()`

Close the gRPC connection.

client.close();

MacpStream

Wraps a gRPC duplex stream for session streaming.

`send(envelope)`

Write an envelope to the stream.

await stream.send(envelope);

`responses()`

Async generator yielding received envelopes.

for await (const envelope of stream.responses()) {
  console.log(envelope.messageType);
}

`close()`

End the stream.

stream.close();

MacpClient API Reference

On this page