macp-sdk-typescript 0.4.1 → 0.6.0

package/dist/client.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MacpClient = exports.MacpStream = void 0;
+exports.grpcStatusName = grpcStatusName;
 /* eslint-disable @typescript-eslint/no-explicit-any --
  * The gRPC service client returned by `protoLoader.loadSync()` is typed as
  * `any` by `@grpc/proto-loader`; method signatures (Send, StreamSession,
@@ -98,6 +99,17 @@ class AsyncQueue {
         });
     }
 }
+/**
+ * Map a gRPC `ServiceError.code` (numeric `grpc.status`) to its status name
+ * (e.g. `8` → `'RESOURCE_EXHAUSTED'`). Returns `undefined` for non-numeric or
+ * unknown codes. Used to populate {@link MacpTransportError.code}.
+ */
+function grpcStatusName(code) {
+    if (typeof code !== 'number')
+        return undefined;
+    const name = grpc.status[code];
+    return typeof name === 'string' ? name : undefined;
+}
 const TIMEOUT = Symbol('stream-read-timeout');
 const STREAM_END = Symbol('stream-end');
 class MacpStream {
@@ -120,7 +132,7 @@ class MacpStream {
             }
         });
         call.on('error', (error) => {
-            this.queue.push(new errors_1.MacpTransportError(error.details || error.message));
+            this.queue.push(new errors_1.MacpTransportError(error.details || error.message, grpcStatusName(error.code)));
         });
         call.on('end', () => {
             this.queue.push(STREAM_END);
@@ -142,9 +154,19 @@ class MacpStream {
         });
     }
     /**
-     * RFC-MACP-0006-A1: Send a subscribe-only frame to receive session history
-     * + live broadcast. The runtime replays accepted envelopes from
-     * `afterSequence` onwards, then continues with live broadcast.
+     * RFC-MACP-0006 §3.2: Send a subscribe-only frame to receive session history
+     * + live broadcast. The runtime replays accepted envelopes strictly after
+     * `afterSequence`, then continues with live broadcast.
+     *
+     * `afterSequence` is the **1-based accepted-envelope ordinal**, exclusive:
+     * `0` (default) replays from the very start; `k` replays envelopes with
+     * ordinal `> k`. Clients derive the ordinal by counting delivered envelopes
+     * (the Nth accepted envelope has ordinal N) — see
+     * `IncomingMessage.seq`, which is exactly this ordinal under the new contract.
+     * Ordinals are stable across log compaction and runtime restart. Resuming
+     * below a compacted base returns `FAILED_PRECONDITION` (inspectable via
+     * `MacpTransportError.code`) rather than silently skipping history (runtime
+     * ≥ 0.5.0; older runtimes compared inclusively against a raw log index).
      */
     sendSubscribe(sessionId, afterSequence = 0) {
         if (this.closed)
@@ -223,7 +245,7 @@ class MacpClient {
         }
         this.defaultDeadlineMs = options.defaultDeadlineMs;
         this.clientName = options.clientName ?? 'macp-sdk-typescript';
-        this.clientVersion = options.clientVersion ?? '0.3.0';
+        this.clientVersion = options.clientVersion ?? '0.5.0';
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const { protoDir: defaultProtoDir } = require('@multiagentcoordinationprotocol/proto');
         const protoDir = options.protoDir ?? defaultProtoDir;
@@ -266,7 +288,7 @@ class MacpClient {
         return new Promise((resolve, reject) => {
             const callback = (error, response) => {
                 if (error)
-                    reject(new errors_1.MacpTransportError(error.details || error.message));
+                    reject(new errors_1.MacpTransportError(error.details || error.message, grpcStatusName(error.code)));
                 else
                     resolve(response);
             };
@@ -382,7 +404,25 @@ class MacpClient {
     async listRoots(deadlineMs) {
         return this.unary('ListRoots', {}, undefined, deadlineMs);
     }
+    /**
+     * Register an extension-mode descriptor (runtime 0.5.0 guardrails,
+     * change-review A5):
+     * - the descriptor MUST declare `Commitment` among `terminalMessageTypes` —
+     *   an ext mode without a terminal `Commitment` can never resolve, so the
+     *   runtime rejects it. This method fails fast client-side to match.
+     * - a later {@link promoteMode} into the reserved `macp.mode.*` namespace is
+     *   rejected by the runtime.
+     * - a SessionStart with an empty `mode_version` binds the registered
+     *   descriptor's `modeVersion`; a subsequent Commitment must echo that bound
+     *   version (echoing `""` no longer matches vacuously). `BaseSession`
+     *   defaults `modeVersion` to `'1.0.0'`, so set the descriptor's version to
+     *   match, or override the session's `modeVersion`.
+     */
     async registerExtMode(descriptor, options) {
+        if (!descriptor.terminalMessageTypes?.includes('Commitment')) {
+            throw new errors_1.MacpSessionError(`ext-mode descriptor '${descriptor.mode}' must declare 'Commitment' in terminalMessageTypes; ` +
+                'a mode without a terminal Commitment can never resolve and the runtime rejects it.');
+        }
         const auth = this.requireAuth(options?.auth);
         return this.unary('RegisterExtMode', { modeDescriptor: descriptor }, auth, options?.deadlineMs);
     }
@@ -412,10 +452,42 @@ class MacpClient {
         const res = await this.unary('ListPolicies', { mode: mode || '' }, auth, options?.deadlineMs);
         return res.descriptors || [];
     }
-    async listSessions(options) {
+    /**
+     * Fetch a single page of sessions (proto ≥ 0.1.6). `pageSize: 0` (or absent)
+     * lets the server choose the page size; the server MAY cap it. Callers MUST
+     * NOT assume the listing is complete unless `nextPageToken` is empty. Pass a
+     * returned non-empty `nextPageToken` back as `pageToken` to fetch the next
+     * page; a stale token yields `INVALID_ARGUMENT`.
+     */
+    async listSessionsPage(options) {
         const auth = this.requireAuth(options?.auth);
-        const res = await this.unary('ListSessions', {}, auth, options?.deadlineMs);
-        return res.sessions || [];
+        const res = await this.unary('ListSessions', { pageSize: options?.pageSize ?? 0, pageToken: options?.pageToken ?? '' }, auth, options?.deadlineMs);
+        return { sessions: res.sessions ?? [], nextPageToken: res.nextPageToken ?? '' };
+    }
+    /**
+     * Enumerate ALL sessions, transparently walking pages until the runtime
+     * returns an empty `nextPageToken`. Preserves the "complete list" semantics
+     * this method has always documented, even against runtimes that cap page
+     * sizes (proto ≥ 0.1.6). For manual page control, use {@link listSessionsPage}.
+     */
+    async listSessions(options) {
+        const all = [];
+        let pageToken = '';
+        // Bound the walk defensively so a misbehaving runtime that never returns an
+        // empty token cannot spin forever.
+        for (let page = 0; page < 100_000; page++) {
+            const res = await this.listSessionsPage({
+                pageSize: options?.pageSize,
+                pageToken,
+                auth: options?.auth,
+                deadlineMs: options?.deadlineMs,
+            });
+            all.push(...res.sessions);
+            if (!res.nextPageToken)
+                return all;
+            pageToken = res.nextPageToken;
+        }
+        return all;
     }
     watchSessions(auth) {
         const metadata = this.metadata(auth);
@@ -425,10 +497,6 @@ class MacpClient {
         const metadata = this.metadata(auth);
         return metadata ? this.client.WatchPolicies({}, metadata) : this.client.WatchPolicies({});
     }
-    /** @deprecated Use {@link watchPolicies}. Scheduled for removal in 0.4.0. */
-    _watchPolicies(auth) {
-        return this.watchPolicies(auth);
-    }
     openStream(options) {
         const auth = this.requireAuth(options?.auth);
         const metadata = this.metadata(auth);
@@ -443,25 +511,15 @@ class MacpClient {
         const metadata = this.metadata(auth);
         return metadata ? this.client.WatchRoots({}, metadata) : this.client.WatchRoots({});
     }
-    watchSignals(auth) {
-        const metadata = this.metadata(auth);
-        return metadata ? this.client.WatchSignals({}, metadata) : this.client.WatchSignals({});
-    }
     /**
-     * @deprecated Use {@link watchModeRegistry}, {@link watchRoots},
-     * {@link watchSignals}. Scheduled for removal in 0.4.0 — the underscored
-     * aliases were kept while `src/watchers.ts` migrated.
+     * Subscribe to the ambient signal plane. Requires auth as of runtime 0.5.0 —
+     * routed through {@link requireAuth} so a missing credential fails fast with a
+     * clear client-side error instead of a stream `UNAUTHENTICATED`.
      */
-    _watchModeRegistry(auth) {
-        return this.watchModeRegistry(auth);
-    }
-    /** @deprecated Use {@link watchRoots}. Scheduled for removal in 0.4.0. */
-    _watchRoots(auth) {
-        return this.watchRoots(auth);
-    }
-    /** @deprecated Use {@link watchSignals}. Scheduled for removal in 0.4.0. */
-    _watchSignals(auth) {
-        return this.watchSignals(auth);
+    watchSignals(auth) {
+        const selected = this.requireAuth(auth);
+        const metadata = (0, auth_1.metadataFromAuth)(selected);
+        return this.client.WatchSignals({}, metadata);
     }
     async sendSignal(options) {
         (0, validation_1.validateSignalType)(options.signalType, options.data);

package/dist/decision.d.ts

@@ -30,6 +30,7 @@ export declare class DecisionSession {
             uri: string;
             name?: string;
         }[];
+        maxSuspendMs?: number;
         sender?: string;
     }): Promise<Ack>;
     propose(input: DecisionProposalPayload & {

package/dist/decision.js

@@ -40,6 +40,7 @@ class DecisionSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
         });
@@ -47,6 +48,7 @@ class DecisionSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             contextId: input.contextId,
             extensions: input.extensions,
             roots: input.roots,

package/dist/envelope.d.ts

@@ -7,6 +7,12 @@ export declare function buildSessionStartPayload(input: {
     intent: string;
     participants: string[];
     ttlMs: number;
+    /**
+     * Per-session max-suspend cap in ms (proto ≥ 0.1.5). `0`/absent selects the
+     * runtime default (7 days). Emitted as `0` when omitted, matching `ttlMs`'s
+     * "0 = default" convention.
+     */
+    maxSuspendMs?: number;
     modeVersion?: string;
     configurationVersion?: string;
     policyVersion?: string;
@@ -24,6 +30,20 @@ export declare function buildCommitmentRef(input: {
     sessionId: string;
     commitmentHash: string;
 }): CommitmentRef;
+/**
+ * Build a `CommitmentPayload`. Defaults `policyVersion` to
+ * {@link DEFAULT_POLICY_VERSION} (`'policy.default'`) when omitted.
+ *
+ * Policy-version echo (runtime ≥ 0.5.0): a Commitment with an **empty**
+ * `policyVersion` matches the session's bound policy — a session started with an
+ * empty policy_version no longer has to echo `'policy.default'`. A **non-empty**
+ * value must equal the session's resolved policy id exactly. The mode session
+ * helpers (`DecisionSession.commit`, etc.) echo the session-bound value, which
+ * is correct against both old and new runtimes; this standalone builder keeps
+ * the `'policy.default'` default for backward compatibility (older runtimes
+ * rejected an empty echo). Pass `policyVersion: ''` explicitly to opt into the
+ * new empty-matches-bound behavior — `''` is not coalesced by the default.
+ */
 export declare function buildCommitmentPayload(input: {
     action: string;
     authorityScope: string;

package/dist/envelope.js

@@ -36,6 +36,7 @@ function buildSessionStartPayload(input) {
         configurationVersion: input.configurationVersion ?? constants_1.DEFAULT_CONFIGURATION_VERSION,
         policyVersion: input.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION,
         ttlMs: input.ttlMs,
+        maxSuspendMs: input.maxSuspendMs ?? 0,
         contextId: input.contextId ?? '',
         extensions: input.extensions ?? {},
         roots: input.roots ?? [],
@@ -56,6 +57,20 @@ function inferOutcomePositive(action) {
 function buildCommitmentRef(input) {
     return { sessionId: input.sessionId, commitmentHash: input.commitmentHash };
 }
+/**
+ * Build a `CommitmentPayload`. Defaults `policyVersion` to
+ * {@link DEFAULT_POLICY_VERSION} (`'policy.default'`) when omitted.
+ *
+ * Policy-version echo (runtime ≥ 0.5.0): a Commitment with an **empty**
+ * `policyVersion` matches the session's bound policy — a session started with an
+ * empty policy_version no longer has to echo `'policy.default'`. A **non-empty**
+ * value must equal the session's resolved policy id exactly. The mode session
+ * helpers (`DecisionSession.commit`, etc.) echo the session-bound value, which
+ * is correct against both old and new runtimes; this standalone builder keeps
+ * the `'policy.default'` default for backward compatibility (older runtimes
+ * rejected an empty echo). Pass `policyVersion: ''` explicitly to opt into the
+ * new empty-matches-bound behavior — `''` is not coalesced by the default.
+ */
 function buildCommitmentPayload(input) {
     const payload = {
         commitmentId: input.commitmentId ?? newCommitmentId(),

package/dist/errors.d.ts

@@ -3,7 +3,16 @@ export declare class MacpSdkError extends Error {
     constructor(message: string);
 }
 export declare class MacpTransportError extends MacpSdkError {
-    constructor(message: string);
+    /**
+     * gRPC status name (e.g. `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`,
+     * `UNAUTHENTICATED`) when the underlying transport failure carried one.
+     * Lets consumers distinguish, for example, watch-stream consumer lag
+     * (`RESOURCE_EXHAUSTED` → reconnect) from an auth failure (`UNAUTHENTICATED`
+     * → do not reconnect), or a passive-subscribe resume below a compacted base
+     * (`FAILED_PRECONDITION`). Absent for locally-raised transport errors.
+     */
+    readonly code?: string;
+    constructor(message: string, code?: string);
 }
 /**
  * Structured NACK record. Mirrors python-sdk's `AckFailure` dataclass so

package/dist/errors.js

@@ -9,9 +9,19 @@ class MacpSdkError extends Error {
 }
 exports.MacpSdkError = MacpSdkError;
 class MacpTransportError extends MacpSdkError {
-    constructor(message) {
+    /**
+     * gRPC status name (e.g. `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`,
+     * `UNAUTHENTICATED`) when the underlying transport failure carried one.
+     * Lets consumers distinguish, for example, watch-stream consumer lag
+     * (`RESOURCE_EXHAUSTED` → reconnect) from an auth failure (`UNAUTHENTICATED`
+     * → do not reconnect), or a passive-subscribe resume below a compacted base
+     * (`FAILED_PRECONDITION`). Absent for locally-raised transport errors.
+     */
+    code;
+    constructor(message, code) {
         super(message);
         this.name = 'MacpTransportError';
+        this.code = code;
     }
 }
 exports.MacpTransportError = MacpTransportError;

package/dist/handoff.d.ts

@@ -30,6 +30,7 @@ export declare class HandoffSession {
             uri: string;
             name?: string;
         }[];
+        maxSuspendMs?: number;
         sender?: string;
     }): Promise<Ack>;
     offer(input: HandoffOfferPayload & {

package/dist/handoff.js

@@ -40,6 +40,7 @@ class HandoffSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
         });
@@ -47,6 +48,7 @@ class HandoffSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             contextId: input.contextId,
             extensions: input.extensions,
             roots: input.roots,
@@ -89,12 +91,18 @@ class HandoffSession {
     }
     async acceptHandoff(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
+        // `implicit` is a runtime-emitted-only flag (RFC-MACP-0010 §5.1); the
+        // runtime rejects client-submitted accepts with implicit=true. Strip it so
+        // a caller can never produce a rejected envelope, regardless of what they
+        // pass — belt and braces with the JSDoc "read-only" contract on the type.
+        const rest = { ...input };
+        delete rest.implicit;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_HANDOFF,
             messageType: 'HandoffAccept',
             sessionId: this.sessionId,
             sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffAccept', (0, envelope_1.toProtoPayload)(input)),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffAccept', rest),
         });
         return this.sendAndTrack(envelope, input.auth);
     }

package/dist/index.d.ts

@@ -16,5 +16,6 @@ export * from './quorum';
 export * from './task';
 export * from './types';
 export * from './validation';
+export { VERSION } from './version';
 export * from './watchers';
 export * as agent from './agent';

package/dist/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agent = exports.Auth = void 0;
+exports.agent = exports.VERSION = exports.Auth = void 0;
 // Auth: export only the public constructors and types. The helpers
 // `validateAuth`, `authSender`, `assertSenderMatchesIdentity`, and
 // `metadataFromAuth` are SDK-internal — importable from the `./auth`
@@ -61,5 +61,7 @@ __exportStar(require("./quorum"), exports);
 __exportStar(require("./task"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./validation"), exports);
+var version_1 = require("./version");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });
 __exportStar(require("./watchers"), exports);
 exports.agent = __importStar(require("./agent"));

package/dist/policy.d.ts

@@ -15,7 +15,18 @@ export interface CommitmentRules {
 }
 export interface VotingRules {
     algorithm?: 'none' | 'majority' | 'supermajority' | 'unanimous' | 'weighted' | 'plurality';
+    /**
+     * Vote-share fraction on a **0–1 scale** (e.g. `0.5` = simple majority). This
+     * is a DIFFERENT field from the quorum `percentage` below — do not confuse
+     * the scales.
+     */
     threshold?: number;
+    /**
+     * Participation quorum. For `type: 'percentage'`, `value` is an **integer
+     * 0–100** (the runtime evaluates it on the same 0–100 scale as the quorum
+     * mode's threshold), NOT a 0–1 fraction. For `type: 'count'`, an absolute
+     * participant count.
+     */
     quorum?: {
         type: 'count' | 'percentage';
         value: number;
@@ -39,6 +50,15 @@ export interface EvaluationRules {
 }
 export interface QuorumThreshold {
     type: 'n_of_m' | 'percentage' | 'weighted';
+    /**
+     * The approval bar (RFC-MACP-0012 §4.2) — how many APPROVE commitments the
+     * request needs, NOT a participation quorum. Scale depends on `type`:
+     * - `n_of_m` / `weighted`: an absolute count (or weight sum).
+     * - `percentage`: an **integer 0–100**; the runtime computes the bar as
+     *   `ceil(value / 100 × participants)`. So `75` means "≥ 75% of participants
+     *   must approve", NOT `0.75`. `buildQuorumPolicy` validates this range and
+     *   throws on a non-integer or out-of-[0,100] value.
+     */
     value: number;
 }
 export interface AbstentionRules {

package/dist/policy.js

@@ -5,6 +5,7 @@ exports.buildQuorumPolicy = buildQuorumPolicy;
 exports.buildProposalPolicy = buildProposalPolicy;
 exports.buildTaskPolicy = buildTaskPolicy;
 exports.buildHandoffPolicy = buildHandoffPolicy;
+const errors_1 = require("./errors");
 // ── Builder helpers ─────────────────────────────────────────────────
 function serializeCommitment(commitment) {
     return {
@@ -49,6 +50,14 @@ function buildDecisionPolicy(policyId, description, rules) {
     };
 }
 function buildQuorumPolicy(policyId, description, rules) {
+    if (rules.threshold?.type === 'percentage') {
+        const v = rules.threshold.value;
+        if (!Number.isInteger(v) || v < 0 || v > 100) {
+            throw new errors_1.MacpSessionError(`quorum percentage threshold must be an integer in [0, 100] (e.g. 75 for 75%), got ${v}. ` +
+                'The runtime computes the approval bar as ceil(value/100 × participants); a fractional value ' +
+                'like 0.75 would round to a ~1% bar.');
+        }
+    }
     const rulesJson = {
         threshold: {
             type: rules.threshold?.type ?? 'n_of_m',

package/dist/projections/handoff.d.ts

@@ -10,6 +10,12 @@ export interface HandoffRecord {
     contextContentType?: string;
     acceptedBy?: string;
     declinedBy?: string;
+    /**
+     * `true` when the accept that resolved this handoff was a runtime-emitted
+     * synthetic implicit accept (RFC-MACP-0010 §5.1, proto ≥ 0.1.6). `false` for
+     * an explicit target accept. Only meaningful once `status === 'accepted'`.
+     */
+    implicit?: boolean;
 }
 export declare class HandoffProjection {
     readonly handoffs: Map<string, HandoffRecord>;
@@ -22,6 +28,12 @@ export declare class HandoffProjection {
     getHandoff(handoffId: string): HandoffRecord | undefined;
     isAccepted(handoffId: string): boolean;
     isDeclined(handoffId: string): boolean;
+    /**
+     * `true` when the handoff was resolved by a runtime-emitted synthetic implicit
+     * accept (RFC-MACP-0010 §5.1) rather than an explicit target accept. Returns
+     * `false` for explicitly-accepted or not-yet-accepted handoffs.
+     */
+    isImplicitlyAccepted(handoffId: string): boolean;
     pendingHandoffs(): HandoffRecord[];
     hasAcceptedOffer(handoffId?: string): boolean;
     activeOffer(): HandoffRecord | undefined;

package/dist/projections/handoff.js

@@ -47,6 +47,10 @@ class HandoffProjection {
                 if (handoff) {
                     handoff.status = 'accepted';
                     handoff.acceptedBy = record.acceptedBy;
+                    // proto3 bool defaults are materialized to `false` on decode
+                    // (proto-registry), so this is always a real boolean once proto 0.1.6
+                    // is loaded — `true` marks a runtime synthetic implicit accept.
+                    handoff.implicit = record.implicit ?? false;
                 }
                 this.phase = 'Accepted';
                 break;
@@ -89,6 +93,15 @@ class HandoffProjection {
     isDeclined(handoffId) {
         return this.handoffs.get(handoffId)?.status === 'declined';
     }
+    /**
+     * `true` when the handoff was resolved by a runtime-emitted synthetic implicit
+     * accept (RFC-MACP-0010 §5.1) rather than an explicit target accept. Returns
+     * `false` for explicitly-accepted or not-yet-accepted handoffs.
+     */
+    isImplicitlyAccepted(handoffId) {
+        const handoff = this.handoffs.get(handoffId);
+        return handoff?.status === 'accepted' && handoff.implicit === true;
+    }
     pendingHandoffs() {
         return [...this.handoffs.values()].filter((h) => h.status === 'offered' || h.status === 'context_sent');
     }

package/dist/proposal.d.ts

@@ -30,6 +30,7 @@ export declare class ProposalSession {
             uri: string;
             name?: string;
         }[];
+        maxSuspendMs?: number;
         sender?: string;
     }): Promise<Ack>;
     propose(input: ProposalModeProposalPayload & {

package/dist/proposal.js

@@ -40,6 +40,7 @@ class ProposalSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
         });
@@ -47,6 +48,7 @@ class ProposalSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             contextId: input.contextId,
             extensions: input.extensions,
             roots: input.roots,

package/dist/proto-registry.d.ts

@@ -7,6 +7,16 @@ export declare class ProtoRegistry {
     decodeMessage(typeName: string, payload: Buffer): Record<string, unknown>;
     encodeKnownPayload(mode: string, messageType: string, value: Record<string, unknown>): Buffer;
     decodeKnownPayload(mode: string, messageType: string, payload: Buffer): Record<string, unknown> | undefined;
+    /**
+     * Decode an `ext.multi_round.v1` `Contribute` payload, accepting both wire
+     * formats: legacy JSON (`{"value":"..."}`, still replayed verbatim from
+     * pre-proto histories) and canonical protobuf (`ContributePayload`). JSON is
+     * tried first — mirroring the runtime's permanent decode order — and the two
+     * encodings are disjoint on their first byte (`{` = 0x7b vs proto field-1
+     * tag 0x0A), so a canonical proto payload never mis-parses as JSON and vice
+     * versa. Both normalize to `{ value: string }`.
+     */
+    private decodeMultiRoundContribute;
     private lookupType;
     private tryDecodeUtf8;
 }

package/dist/proto-registry.js

@@ -46,6 +46,9 @@ const CORE_MAP = {
     Signal: 'macp.v1.SignalPayload',
     Progress: 'macp.v1.ProgressPayload',
 };
+// The one mapping whose historical payloads may be legacy JSON. Runtime replays
+// pre-proto histories byte-identically, so decode must accept both encodings.
+const MULTI_ROUND_CONTRIBUTE = 'macp.modes.multi_round.v1.ContributePayload';
 const MODE_MAP = {
     [constants_1.MODE_DECISION]: {
         Proposal: 'macp.modes.decision.v1.ProposalPayload',
@@ -81,7 +84,10 @@ const MODE_MAP = {
         Abstain: 'macp.modes.quorum.v1.AbstainPayload',
     },
     [constants_1.MODE_MULTI_ROUND]: {
-        Contribute: '__json__',
+        // Canonical protobuf as of proto 0.1.4 / runtime 0.5.0. Encode is always
+        // protobuf; decode tries legacy JSON (`{"value":"..."}`) first, then
+        // protobuf — see `MULTI_ROUND_CONTRIBUTE` handling in decodeKnownPayload.
+        Contribute: MULTI_ROUND_CONTRIBUTE,
     },
 };
 const PROTO_FILES = [
@@ -93,6 +99,7 @@ const PROTO_FILES = [
     'macp/modes/task/v1/task.proto',
     'macp/modes/handoff/v1/handoff.proto',
     'macp/modes/quorum/v1/quorum.proto',
+    'macp/modes/multi_round/v1/multi_round.proto',
 ];
 class ProtoRegistry {
     protoDir;
@@ -155,8 +162,34 @@ class ProtoRegistry {
             return this.tryDecodeUtf8(payload);
         if (typeName === '__json__')
             return this.tryDecodeUtf8(payload);
+        if (typeName === MULTI_ROUND_CONTRIBUTE)
+            return this.decodeMultiRoundContribute(payload);
         return this.decodeMessage(typeName, payload);
     }
+    /**
+     * Decode an `ext.multi_round.v1` `Contribute` payload, accepting both wire
+     * formats: legacy JSON (`{"value":"..."}`, still replayed verbatim from
+     * pre-proto histories) and canonical protobuf (`ContributePayload`). JSON is
+     * tried first — mirroring the runtime's permanent decode order — and the two
+     * encodings are disjoint on their first byte (`{` = 0x7b vs proto field-1
+     * tag 0x0A), so a canonical proto payload never mis-parses as JSON and vice
+     * versa. Both normalize to `{ value: string }`.
+     */
+    decodeMultiRoundContribute(payload) {
+        if (!payload.length)
+            return this.decodeMessage(MULTI_ROUND_CONTRIBUTE, payload);
+        if (payload[0] === 0x7b) {
+            // Leading `{` — legacy JSON. Parse and normalize to { value }.
+            try {
+                const parsed = JSON.parse(payload.toString('utf8'));
+                return { value: typeof parsed.value === 'string' ? parsed.value : String(parsed.value ?? '') };
+            }
+            catch {
+                // Not valid JSON despite the leading brace — fall through to protobuf.
+            }
+        }
+        return this.decodeMessage(MULTI_ROUND_CONTRIBUTE, payload);
+    }
     lookupType(typeName) {
         const lookedUp = this.root.lookupType(typeName);
         if (!(lookedUp instanceof protobufjs_1.default.Type))

package/dist/quorum.d.ts

@@ -30,6 +30,7 @@ export declare class QuorumSession {
             uri: string;
             name?: string;
         }[];
+        maxSuspendMs?: number;
         sender?: string;
     }): Promise<Ack>;
     requestApproval(input: ApprovalRequestPayload & {

package/dist/quorum.js

@@ -40,6 +40,7 @@ class QuorumSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
         });
@@ -47,6 +48,7 @@ class QuorumSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
+            maxSuspendMs: input.maxSuspendMs,
             contextId: input.contextId,
             extensions: input.extensions,
             roots: input.roots,

package/dist/retry.d.ts

@@ -5,6 +5,13 @@ export interface RetryPolicy {
     maxRetries: number;
     backoffBase: number;
     backoffMax: number;
+    /**
+     * Retryable **ack** (NACK) codes — MACP application-level error codes on a
+     * `Send` response (e.g. `RATE_LIMITED`, `INTERNAL_ERROR`). This is distinct
+     * from a gRPC **stream** status such as `RESOURCE_EXHAUSTED` (watch-stream
+     * consumer lag), which is not an ack code and is not handled here — reconnect
+     * the stream instead (see the watcher classes' reconnect JSDoc).
+     */
     retryableCodes: Set<string>;
 }
 export declare const DEFAULT_RETRY_POLICY: RetryPolicy;