macp-sdk-typescript 0.2.2 → 0.4.0

package/dist/client.js

@@ -60,13 +60,45 @@ class AsyncQueue {
         else
             this.items.push(item);
     }
+    unshift(item) {
+        this.items.unshift(item);
+    }
     shift() {
         const item = this.items.shift();
         if (item !== undefined)
             return Promise.resolve(item);
         return new Promise((resolve) => this.resolvers.push(resolve));
     }
+    shiftWithTimeout(timeoutMs) {
+        const item = this.items.shift();
+        if (item !== undefined)
+            return Promise.resolve(item);
+        return new Promise((resolve) => {
+            let settled = false;
+            const resolver = (value) => {
+                if (settled) {
+                    // Timeout already fired; put the value back so it isn't lost.
+                    this.items.unshift(value);
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                resolve(value);
+            };
+            this.resolvers.push(resolver);
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                const idx = this.resolvers.indexOf(resolver);
+                if (idx >= 0)
+                    this.resolvers.splice(idx, 1);
+                resolve(TIMEOUT);
+            }, timeoutMs);
+        });
+    }
 }
+const TIMEOUT = Symbol('stream-read-timeout');
 const STREAM_END = Symbol('stream-end');
 class MacpStream {
     call;
@@ -109,16 +141,63 @@ 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.
+     */
+    sendSubscribe(sessionId, afterSequence = 0) {
+        if (this.closed)
+            return Promise.reject(new errors_1.MacpSdkError('stream is already closed'));
+        return new Promise((resolve, reject) => {
+            this.call.write({ subscribeSessionId: sessionId, afterSequence }, (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    }
     async *responses() {
         while (true) {
             const item = await this.queue.shift();
-            if (item === STREAM_END)
+            if (item === STREAM_END) {
+                // Re-push so a subsequent read()/responses() call also observes end-of-stream.
+                this.queue.unshift(STREAM_END);
                 return;
+            }
             if (item instanceof Error)
                 throw item;
             yield item;
         }
     }
+    /**
+     * Read a single envelope from the stream. Parity with python-sdk's
+     * {@code MacpStream.read(timeout)}.
+     *
+     * @param timeoutMs  Maximum time to wait for the next envelope. If omitted,
+     *                   blocks indefinitely until an envelope arrives, the stream
+     *                   ends, or an error occurs.
+     * @returns          The next envelope, or {@code null} if the stream has
+     *                   ended.
+     * @throws MacpTimeoutError  If {@code timeoutMs} elapses before an envelope
+     *                           arrives.
+     * @throws MacpTransportError  If the underlying stream errored.
+     */
+    async read(timeoutMs) {
+        const item = timeoutMs === undefined ? await this.queue.shift() : await this.queue.shiftWithTimeout(timeoutMs);
+        if (item === TIMEOUT) {
+            throw new errors_1.MacpTimeoutError(`stream read timed out after ${timeoutMs}ms`);
+        }
+        if (item === STREAM_END) {
+            // Re-push so future calls (including responses()) also observe the end.
+            this.queue.unshift(STREAM_END);
+            return null;
+        }
+        if (item instanceof Error)
+            throw item;
+        return item;
+    }
     close() {
         if (this.closed)
             return;
@@ -144,7 +223,7 @@ class MacpClient {
         }
         this.defaultDeadlineMs = options.defaultDeadlineMs;
         this.clientName = options.clientName ?? 'macp-sdk-typescript';
-        this.clientVersion = options.clientVersion ?? '0.2.0';
+        this.clientVersion = options.clientVersion ?? '0.3.0';
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const { protoDir: defaultProtoDir } = require('@multiagentcoordinationprotocol/proto');
         const protoDir = options.protoDir ?? defaultProtoDir;
@@ -240,6 +319,13 @@ class MacpClient {
         const auth = this.requireAuth(options?.auth);
         return this.unary('GetSession', { sessionId }, auth, options?.deadlineMs);
     }
+    /**
+     * Terminate a session via the `CancelSession` control-plane RPC.
+     *
+     * As of proto 0.1.3 the resulting `Ack.sessionState` is
+     * `SESSION_STATE_CANCELLED` (previously `SESSION_STATE_EXPIRED`) — distinct
+     * from TTL/policy expiry so consumers can tell explicit cancellation apart.
+     */
     async cancelSession(sessionId, reason, options) {
         const auth = this.requireAuth(options?.auth);
         const request = { sessionId, reason };
@@ -251,6 +337,39 @@ class MacpClient {
             throw new errors_1.MacpAckError(ack ?? {});
         return ack;
     }
+    /**
+     * Pause a session via the `SuspendSession` control-plane RPC (proto 0.1.3+).
+     *
+     * Suspension is non-terminal: the resulting `Ack.sessionState` is
+     * `SESSION_STATE_SUSPENDED`, the session's remaining TTL is banked, and
+     * messages sent to a suspended session are rejected until {@link resumeSession}
+     * restores it to `SESSION_STATE_OPEN`. Restricted to the initiator and
+     * policy-delegated roles, mirroring {@link cancelSession}.
+     */
+    async suspendSession(sessionId, reason, options) {
+        const auth = this.requireAuth(options?.auth);
+        const response = await this.unary('SuspendSession', { sessionId, reason }, auth, options?.deadlineMs);
+        const ack = response.ack;
+        if (options?.raiseOnNack !== false && !ack?.ok)
+            throw new errors_1.MacpAckError(ack ?? {});
+        return ack;
+    }
+    /**
+     * Resume a suspended session via the `ResumeSession` control-plane RPC
+     * (proto 0.1.3+).
+     *
+     * Restores `SESSION_STATE_OPEN` and adds the banked TTL back to the session's
+     * absolute deadline. Restricted to the initiator and policy-delegated roles,
+     * mirroring {@link suspendSession}.
+     */
+    async resumeSession(sessionId, reason, options) {
+        const auth = this.requireAuth(options?.auth);
+        const response = await this.unary('ResumeSession', { sessionId, reason }, auth, options?.deadlineMs);
+        const ack = response.ack;
+        if (options?.raiseOnNack !== false && !ack?.ok)
+            throw new errors_1.MacpAckError(ack ?? {});
+        return ack;
+    }
     async getManifest(agentId = '', deadlineMs) {
         return this.unary('GetManifest', { agentId }, undefined, deadlineMs);
     }
@@ -348,12 +467,13 @@ class MacpClient {
         (0, validation_1.validateSignalType)(options.signalType, options.data);
         const auth = this.requireAuth(options.auth);
         (0, auth_1.assertSenderMatchesIdentity)(auth, options.sender);
-        const payload = this.protoRegistry.encodeKnownPayload('', 'Signal', {
+        const signalPayload = (0, envelope_1.buildSignalPayload)({
             signalType: options.signalType,
-            data: options.data ?? Buffer.alloc(0),
-            confidence: options.confidence ?? 0,
-            correlationSessionId: options.correlationSessionId ?? '',
+            data: options.data,
+            confidence: options.confidence,
+            correlationSessionId: options.correlationSessionId,
         });
+        const payload = this.protoRegistry.encodeKnownPayload('', 'Signal', signalPayload);
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: '',
             messageType: 'Signal',
@@ -366,13 +486,14 @@ class MacpClient {
     async sendProgress(options) {
         const auth = this.requireAuth(options.auth);
         (0, auth_1.assertSenderMatchesIdentity)(auth, options.sender);
-        const payload = this.protoRegistry.encodeKnownPayload('', 'Progress', {
+        const progressPayload = (0, envelope_1.buildProgressPayload)({
             progressToken: options.progressToken,
             progress: options.progress,
             total: options.total,
-            message: options.message ?? '',
-            targetMessageId: options.targetMessageId ?? '',
+            message: options.message,
+            targetMessageId: options.targetMessageId,
         });
+        const payload = this.protoRegistry.encodeKnownPayload('', 'Progress', progressPayload);
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: options.mode ?? '',
             messageType: 'Progress',

package/dist/constants.d.ts

@@ -8,19 +8,24 @@ export declare const MODE_TASK = "macp.mode.task.v1";
 export declare const MODE_HANDOFF = "macp.mode.handoff.v1";
 export declare const MODE_QUORUM = "macp.mode.quorum.v1";
 export declare const MODE_MULTI_ROUND = "ext.multi_round.v1";
-export declare const ERR_UNSUPPORTED_PROTOCOL_VERSION = "UNSUPPORTED_PROTOCOL_VERSION";
-export declare const ERR_INVALID_ENVELOPE = "INVALID_ENVELOPE";
-export declare const ERR_SESSION_ALREADY_EXISTS = "SESSION_ALREADY_EXISTS";
-export declare const ERR_SESSION_NOT_FOUND = "SESSION_NOT_FOUND";
-export declare const ERR_SESSION_NOT_OPEN = "SESSION_NOT_OPEN";
-export declare const ERR_MODE_NOT_SUPPORTED = "MODE_NOT_SUPPORTED";
-export declare const ERR_FORBIDDEN = "FORBIDDEN";
-export declare const ERR_UNAUTHENTICATED = "UNAUTHENTICATED";
-export declare const ERR_DUPLICATE_MESSAGE = "DUPLICATE_MESSAGE";
-export declare const ERR_PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE";
-export declare const ERR_RATE_LIMITED = "RATE_LIMITED";
-export declare const ERR_INTERNAL_ERROR = "INTERNAL_ERROR";
-export declare const ERR_POLICY_DENIED = "POLICY_DENIED";
-export declare const ERR_INVALID_SESSION_ID = "INVALID_SESSION_ID";
-export declare const ERR_UNKNOWN_POLICY_VERSION = "UNKNOWN_POLICY_VERSION";
-export declare const ERR_INVALID_POLICY_DEFINITION = "INVALID_POLICY_DEFINITION";
+/**
+ * The five first-class coordination modes. Parity with
+ * python-sdk `macp_sdk.constants.STANDARD_MODES`.
+ */
+export declare const STANDARD_MODES: readonly ["macp.mode.decision.v1", "macp.mode.proposal.v1", "macp.mode.task.v1", "macp.mode.handoff.v1", "macp.mode.quorum.v1"];
+export declare const UNSUPPORTED_PROTOCOL_VERSION = "UNSUPPORTED_PROTOCOL_VERSION";
+export declare const INVALID_ENVELOPE = "INVALID_ENVELOPE";
+export declare const SESSION_ALREADY_EXISTS = "SESSION_ALREADY_EXISTS";
+export declare const SESSION_NOT_FOUND = "SESSION_NOT_FOUND";
+export declare const SESSION_NOT_OPEN = "SESSION_NOT_OPEN";
+export declare const MODE_NOT_SUPPORTED = "MODE_NOT_SUPPORTED";
+export declare const FORBIDDEN = "FORBIDDEN";
+export declare const UNAUTHENTICATED = "UNAUTHENTICATED";
+export declare const DUPLICATE_MESSAGE = "DUPLICATE_MESSAGE";
+export declare const PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE";
+export declare const RATE_LIMITED = "RATE_LIMITED";
+export declare const INTERNAL_ERROR = "INTERNAL_ERROR";
+export declare const POLICY_DENIED = "POLICY_DENIED";
+export declare const INVALID_SESSION_ID = "INVALID_SESSION_ID";
+export declare const UNKNOWN_POLICY_VERSION = "UNKNOWN_POLICY_VERSION";
+export declare const INVALID_POLICY_DEFINITION = "INVALID_POLICY_DEFINITION";

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ERR_INVALID_POLICY_DEFINITION = exports.ERR_UNKNOWN_POLICY_VERSION = exports.ERR_INVALID_SESSION_ID = exports.ERR_POLICY_DENIED = exports.ERR_INTERNAL_ERROR = exports.ERR_RATE_LIMITED = exports.ERR_PAYLOAD_TOO_LARGE = exports.ERR_DUPLICATE_MESSAGE = exports.ERR_UNAUTHENTICATED = exports.ERR_FORBIDDEN = exports.ERR_MODE_NOT_SUPPORTED = exports.ERR_SESSION_NOT_OPEN = exports.ERR_SESSION_NOT_FOUND = exports.ERR_SESSION_ALREADY_EXISTS = exports.ERR_INVALID_ENVELOPE = exports.ERR_UNSUPPORTED_PROTOCOL_VERSION = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
+exports.INVALID_POLICY_DEFINITION = exports.UNKNOWN_POLICY_VERSION = exports.INVALID_SESSION_ID = exports.POLICY_DENIED = exports.INTERNAL_ERROR = exports.RATE_LIMITED = exports.PAYLOAD_TOO_LARGE = exports.DUPLICATE_MESSAGE = exports.UNAUTHENTICATED = exports.FORBIDDEN = exports.MODE_NOT_SUPPORTED = exports.SESSION_NOT_OPEN = exports.SESSION_NOT_FOUND = exports.SESSION_ALREADY_EXISTS = exports.INVALID_ENVELOPE = exports.UNSUPPORTED_PROTOCOL_VERSION = exports.STANDARD_MODES = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
 exports.MACP_VERSION = '1.0';
 exports.DEFAULT_MODE_VERSION = '1.0.0';
 exports.DEFAULT_CONFIGURATION_VERSION = 'config.default';
@@ -11,19 +11,26 @@ exports.MODE_TASK = 'macp.mode.task.v1';
 exports.MODE_HANDOFF = 'macp.mode.handoff.v1';
 exports.MODE_QUORUM = 'macp.mode.quorum.v1';
 exports.MODE_MULTI_ROUND = 'ext.multi_round.v1';
-exports.ERR_UNSUPPORTED_PROTOCOL_VERSION = 'UNSUPPORTED_PROTOCOL_VERSION';
-exports.ERR_INVALID_ENVELOPE = 'INVALID_ENVELOPE';
-exports.ERR_SESSION_ALREADY_EXISTS = 'SESSION_ALREADY_EXISTS';
-exports.ERR_SESSION_NOT_FOUND = 'SESSION_NOT_FOUND';
-exports.ERR_SESSION_NOT_OPEN = 'SESSION_NOT_OPEN';
-exports.ERR_MODE_NOT_SUPPORTED = 'MODE_NOT_SUPPORTED';
-exports.ERR_FORBIDDEN = 'FORBIDDEN';
-exports.ERR_UNAUTHENTICATED = 'UNAUTHENTICATED';
-exports.ERR_DUPLICATE_MESSAGE = 'DUPLICATE_MESSAGE';
-exports.ERR_PAYLOAD_TOO_LARGE = 'PAYLOAD_TOO_LARGE';
-exports.ERR_RATE_LIMITED = 'RATE_LIMITED';
-exports.ERR_INTERNAL_ERROR = 'INTERNAL_ERROR';
-exports.ERR_POLICY_DENIED = 'POLICY_DENIED';
-exports.ERR_INVALID_SESSION_ID = 'INVALID_SESSION_ID';
-exports.ERR_UNKNOWN_POLICY_VERSION = 'UNKNOWN_POLICY_VERSION';
-exports.ERR_INVALID_POLICY_DEFINITION = 'INVALID_POLICY_DEFINITION';
+/**
+ * The five first-class coordination modes. Parity with
+ * python-sdk `macp_sdk.constants.STANDARD_MODES`.
+ */
+exports.STANDARD_MODES = [exports.MODE_DECISION, exports.MODE_PROPOSAL, exports.MODE_TASK, exports.MODE_HANDOFF, exports.MODE_QUORUM];
+// Well-known error codes. Names match the on-the-wire strings the runtime
+// emits and python-sdk's exports (no ERR_ prefix).
+exports.UNSUPPORTED_PROTOCOL_VERSION = 'UNSUPPORTED_PROTOCOL_VERSION';
+exports.INVALID_ENVELOPE = 'INVALID_ENVELOPE';
+exports.SESSION_ALREADY_EXISTS = 'SESSION_ALREADY_EXISTS';
+exports.SESSION_NOT_FOUND = 'SESSION_NOT_FOUND';
+exports.SESSION_NOT_OPEN = 'SESSION_NOT_OPEN';
+exports.MODE_NOT_SUPPORTED = 'MODE_NOT_SUPPORTED';
+exports.FORBIDDEN = 'FORBIDDEN';
+exports.UNAUTHENTICATED = 'UNAUTHENTICATED';
+exports.DUPLICATE_MESSAGE = 'DUPLICATE_MESSAGE';
+exports.PAYLOAD_TOO_LARGE = 'PAYLOAD_TOO_LARGE';
+exports.RATE_LIMITED = 'RATE_LIMITED';
+exports.INTERNAL_ERROR = 'INTERNAL_ERROR';
+exports.POLICY_DENIED = 'POLICY_DENIED';
+exports.INVALID_SESSION_ID = 'INVALID_SESSION_ID';
+exports.UNKNOWN_POLICY_VERSION = 'UNKNOWN_POLICY_VERSION';
+exports.INVALID_POLICY_DEFINITION = 'INVALID_POLICY_DEFINITION';

package/dist/decision.d.ts

@@ -61,6 +61,16 @@ export declare class DecisionSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/decision.js

@@ -142,6 +142,26 @@ class DecisionSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/envelope.d.ts

@@ -1,4 +1,4 @@
-import type { CommitmentPayload, Envelope, Root, SessionStartPayload } from './types';
+import type { CommitmentPayload, CommitmentRef, Envelope, ProgressPayload, Root, SessionStartPayload, SignalPayload } from './types';
 export declare function newSessionId(): string;
 export declare function newMessageId(): string;
 export declare function newCommitmentId(): string;
@@ -15,6 +15,15 @@ export declare function buildSessionStartPayload(input: {
     roots?: Root[];
 }): SessionStartPayload;
 export declare function inferOutcomePositive(action: string): boolean;
+/**
+ * Build a {@link CommitmentRef} pointing at a prior accepted commitment, for
+ * use as `buildCommitmentPayload({ supersedes })` (cross-session supersession,
+ * RFC-MACP-0001 §7.3). Parity with python-sdk `build_commitment_ref`.
+ */
+export declare function buildCommitmentRef(input: {
+    sessionId: string;
+    commitmentHash: string;
+}): CommitmentRef;
 export declare function buildCommitmentPayload(input: {
     action: string;
     authorityScope: string;
@@ -24,8 +33,35 @@ export declare function buildCommitmentPayload(input: {
     configurationVersion?: string;
     policyVersion?: string;
     outcomePositive?: boolean;
+    /**
+     * Cross-session supersession (RFC-MACP-0001 §7.3): reference to the prior
+     * commitment this one supersedes. Distinct from proposal-mode
+     * `supersedesProposalId`. Absent by default. Backward-compatible.
+     */
+    supersedes?: CommitmentRef;
 }): CommitmentPayload;
 export declare function buildRoot(uri: string, name?: string): Root;
+export declare function buildSignalPayload(input: {
+    signalType: string;
+    data?: Buffer | Uint8Array;
+    confidence?: number;
+    correlationSessionId?: string;
+}): SignalPayload;
+export declare function buildProgressPayload(input: {
+    progressToken: string;
+    progress: number;
+    total: number;
+    message?: string;
+    targetMessageId?: string;
+}): ProgressPayload;
+type ProtoSerializable = {
+    serializeBinary(): Uint8Array;
+} | {
+    toBinary(): Uint8Array;
+} | {
+    finish(): Uint8Array;
+};
+export declare function serializeMessage(message: ProtoSerializable | unknown): Uint8Array;
 /**
  * Type-erasure helper for protobuf payload encoders.
  *
@@ -48,3 +84,4 @@ export declare function buildEnvelope(input: {
     macpVersion?: string;
     timestampUnixMs?: string | number;
 }): Envelope;
+export {};

package/dist/envelope.js

@@ -6,8 +6,12 @@ exports.newCommitmentId = newCommitmentId;
 exports.nowUnixMs = nowUnixMs;
 exports.buildSessionStartPayload = buildSessionStartPayload;
 exports.inferOutcomePositive = inferOutcomePositive;
+exports.buildCommitmentRef = buildCommitmentRef;
 exports.buildCommitmentPayload = buildCommitmentPayload;
 exports.buildRoot = buildRoot;
+exports.buildSignalPayload = buildSignalPayload;
+exports.buildProgressPayload = buildProgressPayload;
+exports.serializeMessage = serializeMessage;
 exports.toProtoPayload = toProtoPayload;
 exports.buildEnvelope = buildEnvelope;
 const node_crypto_1 = require("node:crypto");
@@ -44,8 +48,16 @@ function inferOutcomePositive(action) {
         return false;
     return true;
 }
+/**
+ * Build a {@link CommitmentRef} pointing at a prior accepted commitment, for
+ * use as `buildCommitmentPayload({ supersedes })` (cross-session supersession,
+ * RFC-MACP-0001 §7.3). Parity with python-sdk `build_commitment_ref`.
+ */
+function buildCommitmentRef(input) {
+    return { sessionId: input.sessionId, commitmentHash: input.commitmentHash };
+}
 function buildCommitmentPayload(input) {
-    return {
+    const payload = {
         commitmentId: input.commitmentId ?? newCommitmentId(),
         action: input.action,
         authorityScope: input.authorityScope,
@@ -55,10 +67,50 @@ function buildCommitmentPayload(input) {
         policyVersion: input.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION,
         outcomePositive: input.outcomePositive ?? inferOutcomePositive(input.action),
     };
+    if (input.supersedes)
+        payload.supersedes = input.supersedes;
+    return payload;
 }
 function buildRoot(uri, name = '') {
     return { uri, name };
 }
+function buildSignalPayload(input) {
+    const data = input.data instanceof Buffer ? input.data : input.data ? Buffer.from(input.data) : Buffer.alloc(0);
+    return {
+        signalType: input.signalType,
+        data,
+        confidence: input.confidence ?? 0,
+        correlationSessionId: input.correlationSessionId ?? '',
+    };
+}
+function buildProgressPayload(input) {
+    return {
+        progressToken: input.progressToken,
+        progress: input.progress,
+        total: input.total,
+        message: input.message ?? '',
+        targetMessageId: input.targetMessageId ?? '',
+    };
+}
+function serializeMessage(message) {
+    // Parity with python-sdk `envelope.serialize_message`: invoke the protobuf
+    // serializer exposed on the message. Supports objects with `serializeBinary`
+    // (protoc-gen-js), `toBinary` (protobuf-es / ts-proto), or `finish`
+    // (protobufjs Writer). For plain JS interface payloads, use
+    // `ProtoRegistry.encodeKnownPayload(mode, messageType, payload)` instead —
+    // the registry owns the mode/messageType → descriptor mapping.
+    const candidate = message;
+    if (typeof candidate?.serializeBinary === 'function') {
+        return candidate.serializeBinary();
+    }
+    if (typeof candidate?.toBinary === 'function') {
+        return candidate.toBinary();
+    }
+    if (typeof candidate?.finish === 'function') {
+        return candidate.finish();
+    }
+    throw new TypeError('serializeMessage: object is not a protobuf message — expected serializeBinary(), toBinary(), or finish() method. For plain JS payloads, use ProtoRegistry.encodeKnownPayload().');
+}
 /**
  * Type-erasure helper for protobuf payload encoders.
  *

package/dist/errors.d.ts

@@ -5,6 +5,18 @@ export declare class MacpSdkError extends Error {
 export declare class MacpTransportError extends MacpSdkError {
     constructor(message: string);
 }
+/**
+ * Structured NACK record. Mirrors python-sdk's `AckFailure` dataclass so
+ * cross-SDK code can share the same shape when logging or persisting a
+ * rejected message.
+ */
+export interface AckFailure {
+    code: string;
+    message: string;
+    sessionId: string;
+    messageId: string;
+    reasons: string[];
+}
 export declare class MacpAckError extends MacpSdkError {
     readonly ack: Ack;
     /** Optional gRPC trailing metadata for extracting additional error details. */
@@ -12,14 +24,15 @@ export declare class MacpAckError extends MacpSdkError {
         key: string;
         value: string | Buffer;
     }>;
+    /** Structured NACK record — parity with python-sdk `MacpAckError.failure`. */
+    readonly failure: AckFailure;
     constructor(ack: Ack, grpcMetadata?: Array<{
         key: string;
         value: string | Buffer;
     }>);
-    /** Extract structured denial reasons from the ACK error details and/or gRPC trailing metadata. */
-    get reasons(): string[];
-    private _parseAckReasons;
-    private _parseGrpcMetadataReasons;
+    private static _extractReasons;
+    private static _parseAckReasons;
+    private static _parseGrpcMetadataReasons;
 }
 export declare class MacpSessionError extends MacpSdkError {
     constructor(message: string);

package/dist/errors.js

@@ -19,26 +19,35 @@ class MacpAckError extends MacpSdkError {
     ack;
     /** Optional gRPC trailing metadata for extracting additional error details. */
     grpcMetadata;
+    /** Structured NACK record — parity with python-sdk `MacpAckError.failure`. */
+    failure;
     constructor(ack, grpcMetadata) {
         super(`${ack.error?.code ?? 'UNKNOWN'}: ${ack.error?.message ?? 'runtime returned nack'}`);
         this.name = 'MacpAckError';
         this.ack = ack;
         this.grpcMetadata = grpcMetadata;
+        const reasons = MacpAckError._extractReasons(ack, grpcMetadata);
+        this.failure = {
+            code: ack.error?.code ?? 'UNKNOWN',
+            message: ack.error?.message ?? 'runtime returned nack',
+            sessionId: ack.sessionId ?? ack.error?.sessionId ?? '',
+            messageId: ack.messageId ?? ack.error?.messageId ?? '',
+            reasons,
+        };
     }
-    /** Extract structured denial reasons from the ACK error details and/or gRPC trailing metadata. */
-    get reasons() {
+    static _extractReasons(ack, grpcMetadata) {
         // First try: parse from ack.error.details (matches Python _parse_ack_reasons)
-        const fromDetails = this._parseAckReasons();
+        const fromDetails = MacpAckError._parseAckReasons(ack);
         if (fromDetails.length > 0)
             return fromDetails;
         // Second try: parse from gRPC trailing metadata (matches Python _parse_grpc_metadata_reasons)
-        return this._parseGrpcMetadataReasons();
+        return MacpAckError._parseGrpcMetadataReasons(grpcMetadata);
     }
-    _parseAckReasons() {
-        if (!this.ack.error?.details)
+    static _parseAckReasons(ack) {
+        if (!ack.error?.details)
             return [];
         try {
-            const details = this.ack.error.details;
+            const details = ack.error.details;
             const raw = Buffer.isBuffer(details) ? details.toString('utf-8') : String(details);
             const parsed = JSON.parse(raw);
             const reasons = parsed.reasons;
@@ -48,11 +57,11 @@ class MacpAckError extends MacpSdkError {
             return [];
         }
     }
-    _parseGrpcMetadataReasons() {
-        if (!this.grpcMetadata)
+    static _parseGrpcMetadataReasons(grpcMetadata) {
+        if (!grpcMetadata)
             return [];
         try {
-            for (const item of this.grpcMetadata) {
+            for (const item of grpcMetadata) {
                 if (item.key === 'macp-error-details-bin') {
                     const data = Buffer.isBuffer(item.value)
                         ? item.value.toString('utf-8')

package/dist/handoff.d.ts

@@ -40,14 +40,6 @@ export declare class HandoffSession {
         sender?: string;
         auth?: AuthConfig;
     }): Promise<Ack>;
-    /**
-     * @deprecated Use {@link addContext} instead. Scheduled for removal in 0.4.0.
-     * First call logs a one-shot warning to guide migrations without spamming long-lived processes.
-     */
-    sendContext(input: HandoffContextPayload & {
-        sender?: string;
-        auth?: AuthConfig;
-    }): Promise<Ack>;
     acceptHandoff(input: HandoffAcceptPayload & {
         sender?: string;
         auth?: AuthConfig;
@@ -69,6 +61,16 @@ export declare class HandoffSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};