Envelope Builders API Reference

Utility functions for constructing MACP envelopes and payloads.

buildEnvelope(input)

Constructs a canonical MACP Envelope with sensible defaults.

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

const envelope = buildEnvelope({
  mode: 'macp.mode.decision.v1',    // required
  messageType: 'Proposal',           // required
  sessionId: 'session-uuid',         // required
  payload: encodedBuffer,            // required (Buffer)
  sender: 'agent-a',                 // default: ''
  messageId: undefined,              // default: auto-generated UUID
  macpVersion: undefined,            // default: MACP_VERSION ('1.0')
  timestampUnixMs: undefined,        // default: Date.now() as string
});

Auto-Generated Fields

buildSessionStartPayload(input)

Constructs a SessionStartPayload object.

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

const payload = buildSessionStartPayload({
  intent: 'decide something',        // required
  participants: ['alice', 'bob'],     // required
  ttlMs: 60_000,                     // required
  maxSuspendMs: 3_600_000,           // optional; 0/absent = runtime default (7 days). proto ≥ 0.1.5
  modeVersion: '1.0.0',              // default: DEFAULT_MODE_VERSION
  configurationVersion: 'config.default', // default
  policyVersion: 'policy.default',    // default
  contextId: 'ctx-123',              // optional; default: ''
  extensions: { 'ext.key': Buffer.from('...') }, // optional; default: {}
  roots: [{ uri: '...', name: '...' }], // default: []
});

maxSuspendMs binds a per-session cap on cumulative suspended time before a SUSPENDED session transitions to EXPIRED (RFC-MACP-0001 (Core) §7.5). 0 or absent selects the runtime's configured default; negative values are rejected. The runtime records the resolved cap so replay is deterministic. Every mode session's start() accepts maxSuspendMs too and threads it here.

buildCommitmentPayload(input)

Constructs a CommitmentPayload object.

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

const payload = buildCommitmentPayload({
  action: 'deployment.approved',      // required
  authorityScope: 'release-mgmt',     // required
  reason: 'approved by team',         // required
  commitmentId: undefined,            // default: auto-generated UUID
  modeVersion: '1.0.0',              // default
  configurationVersion: 'config.default',
  policyVersion: 'policy.default',
  outcomePositive: undefined,         // default: inferOutcomePositive(action)
  supersedes: undefined,              // optional CommitmentRef (cross-session supersession)
});

Policy-version echo (runtime ≥ 0.5.0): a Commitment with an empty policyVersion matches the session's bound policy (a non-empty value must equal the resolved policy id exactly). The mode session helpers echo the bound value automatically; the standalone builder keeps the 'policy.default' default for backward compatibility (pass policyVersion: '' to opt into empty-echo — '' is not coalesced by the default).

When supersedes is provided (any non-undefined value), it must be a CommitmentRef object — null or any other non-object value throws MacpSessionError rather than being silently dropped. A well-formed object's commitmentHash is then validated the same way as in buildCommitmentRef (sha256:<64 lowercase hex>, else throws MacpSessionError) — build it with buildCommitmentRef() (see below) rather than constructing a CommitmentRef by hand.

inferOutcomePositive(action)

Infers a commitment's outcome polarity from its action string: returns false when the lowercased action ends with 'rejected', 'failed', or 'declined'; true otherwise. Used as the outcomePositive default in buildCommitmentPayload and the agent framework's commitment strategies.

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

inferOutcomePositive('deployment.approved'); // true
inferOutcomePositive('deployment.rejected'); // false

buildCommitmentRef(input)

Builds a CommitmentRef pointing at a prior accepted commitment, for use as buildCommitmentPayload({ supersedes }) (cross-session supersession, RFC-MACP-0001 §7.3). Validates that commitmentHash has the shape sha256:<64 lowercase hex> and throws MacpSessionError if it doesn't — use commitmentHash() (from ./commitment-hash) to produce a valid value from the prior CommitmentPayload.

import { commitmentHash, buildCommitmentRef } from 'macp-sdk-typescript';

const hash = commitmentHash(priorCommitmentPayload); // 'sha256:' + 64 lowercase hex chars
const ref = buildCommitmentRef({ sessionId: 'old-session', commitmentHash: hash });

isCanonicalCommitmentHash(value)

A non-throwing counterpart to the shape check buildCommitmentRef/ buildCommitmentPayload perform internally (which throw MacpSessionError on a malformed hash): returns true/false for whether value matches sha256:<64 lowercase hex>, never throwing for any input. Use this where a boolean fits better than a thrown exception — filtering a list of candidate hashes, or a non-fatal validity check — rather than wrapping a try/catch around buildCommitmentRef.

import { commitmentHash, isCanonicalCommitmentHash } from 'macp-sdk-typescript';

const hash = commitmentHash(payload);
isCanonicalCommitmentHash(hash);        // true
isCanonicalCommitmentHash('not-a-hash'); // false

Pinned as part of the cross-SDK parity contract — see Testing § Parity Contract Gate.

buildSignalPayload(input) / buildProgressPayload(input)

Ambient-plane payload builders used by client.sendSignal() and client.sendProgress().

buildSignalPayload({ signalType: 'ext.signal.x', data, confidence, correlationSessionId });
buildProgressPayload({ progressToken: 't', progress: 1, total: 10, message, targetMessageId });

Omitted optional fields normalise to protobuf zero values (0, '', empty Buffer).

buildRoot(uri, name?)

Constructs a Root ({ uri, name }); name defaults to ''.

ID Generators

import { newSessionId, newMessageId, newCommitmentId } from 'macp-sdk-typescript';

newSessionId();     // UUIDv4 string
newMessageId();     // UUIDv4 string
newCommitmentId();  // UUIDv4 string

nowUnixMs()

Returns the current time as a number of milliseconds since epoch (Date.now()). buildEnvelope stringifies it when populating timestampUnixMs.

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

nowUnixMs();  // e.g., 1711738400000

serializeMessage(message)

Serializes a protobuf message object by invoking its own serializer — supports serializeBinary() (protoc-gen-js), toBinary() (protobuf-es / ts-proto), or finish() (protobufjs Writer). Throws TypeError for plain objects; for plain JS interface payloads use ProtoRegistry.encodeKnownPayload() instead.

toProtoPayload(input)

Type-erasure helper: casts a typed payload interface to the Record<string, unknown> that ProtoRegistry.encodeKnownPayload() accepts. Never narrows or copies.