Session Classes API Reference

All session classes follow the same base pattern. They differ only in their mode-specific methods.

Common Pattern

Every session class:

Constructor: new XxxSession(client, options?)
Properties: client, sessionId, modeVersion, configurationVersion, policyVersion, auth, projection
Lifecycle: start(input) → mode-specific methods → commit(input)
Metadata: metadata(auth?) queries session state from runtime
Projection: session.projection provides typed local state

Common Options

interface SessionOptions {
  sessionId?: string;             // default: auto-generated UUIDv4
  modeVersion?: string;           // default: '1.0.0'
  configurationVersion?: string;  // default: 'config.default'
  policyVersion?: string;         // default: 'policy.default'
  auth?: AuthConfig;              // default: uses client.auth
}

Common `start()` Input

{
  intent: string;                                    // session purpose
  participants: string[];                            // participant identifiers
  ttlMs: number;                                     // time-to-live in milliseconds
  context?: Buffer | string | Record<string, unknown>; // optional bound context
  roots?: { uri: string; name?: string }[];          // optional coordination roots
  sender?: string;                                   // optional sender override
}

Common `commit()` Input

{
  action: string;          // outcome descriptor (e.g., 'deployment.approved')
  authorityScope: string;  // scope of authority
  reason: string;          // auditable reason
  commitmentId?: string;   // default: auto-generated UUID
  sender?: string;
  auth?: AuthConfig;
}

Session Classes Summary

Class	Mode	Key Methods
`DecisionSession`	`macp.mode.decision.v1`	`propose`, `evaluate`, `raiseObjection`, `vote`
`ProposalSession`	`macp.mode.proposal.v1`	`propose`, `counterPropose`, `accept`, `reject`, `withdraw`
`TaskSession`	`macp.mode.task.v1`	`request`, `acceptTask`, `rejectTask`, `update`, `complete`, `fail`
`HandoffSession`	`macp.mode.handoff.v1`	`offer`, `sendContext`, `acceptHandoff`, `decline`
`QuorumSession`	`macp.mode.quorum.v1`	`requestApproval`, `approve`, `reject`, `abstain`

Per-Method Auth Override

All mode-specific methods accept optional sender and auth fields:

await session.vote({
  proposalId: 'p1',
  vote: 'approve',
  sender: 'alice',                // populate envelope.sender
  auth: Auth.devAgent('alice'),   // use alice's credentials for this call
});

This enables a single process to act on behalf of multiple agents within the same session.

Projection Integration

Each sendAndTrack() call:

Builds an envelope with buildEnvelope() + ProtoRegistry.encodeKnownPayload()
Sends via MacpClient.send() (throws MacpAckError on nack)
On success (ack.ok === true), applies the envelope to the projection

Rejected messages are never applied to the projection.

For full details on each session class, see the Mode documentation.