macp-sdk-typescript 0.2.0 → 0.3.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;
@@ -214,7 +293,7 @@ class MacpClient {
                 websiteUrl: '',
             },
             capabilities: {
-                sessions: { stream: true },
+                sessions: { stream: true, listSessions: true, watchSessions: true },
                 cancellation: { cancelSession: true },
                 progress: { progress: true },
                 manifest: { getManifest: true },
@@ -293,6 +372,15 @@ class MacpClient {
         const res = await this.unary('ListPolicies', { mode: mode || '' }, auth, options?.deadlineMs);
         return res.descriptors || [];
     }
+    async listSessions(options) {
+        const auth = this.requireAuth(options?.auth);
+        const res = await this.unary('ListSessions', {}, auth, options?.deadlineMs);
+        return res.sessions || [];
+    }
+    watchSessions(auth) {
+        const metadata = this.metadata(auth);
+        return metadata ? this.client.WatchSessions({}, metadata) : this.client.WatchSessions({});
+    }
     watchPolicies(auth) {
         const metadata = this.metadata(auth);
         return metadata ? this.client.WatchPolicies({}, metadata) : this.client.WatchPolicies({});
@@ -339,12 +427,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',
@@ -357,13 +446,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

@@ -24,7 +24,8 @@ export declare class DecisionSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/decision.js

@@ -47,7 +47,8 @@ class DecisionSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/envelope.d.ts

@@ -1,9 +1,8 @@
-import type { CommitmentPayload, Envelope, Root, SessionStartPayload } from './types';
+import type { CommitmentPayload, Envelope, ProgressPayload, Root, SessionStartPayload, SignalPayload } from './types';
 export declare function newSessionId(): string;
 export declare function newMessageId(): string;
 export declare function newCommitmentId(): string;
 export declare function nowUnixMs(): number;
-export declare function encodeContext(context?: Buffer | string | Record<string, unknown>): Buffer;
 export declare function buildSessionStartPayload(input: {
     intent: string;
     participants: string[];
@@ -11,7 +10,8 @@ export declare function buildSessionStartPayload(input: {
     modeVersion?: string;
     configurationVersion?: string;
     policyVersion?: string;
-    context?: Buffer | string | Record<string, unknown>;
+    contextId?: string;
+    extensions?: Record<string, Buffer>;
     roots?: Root[];
 }): SessionStartPayload;
 export declare function inferOutcomePositive(action: string): boolean;
@@ -26,6 +26,27 @@ export declare function buildCommitmentPayload(input: {
     outcomePositive?: boolean;
 }): 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 +69,4 @@ export declare function buildEnvelope(input: {
     macpVersion?: string;
     timestampUnixMs?: string | number;
 }): Envelope;
+export {};

package/dist/envelope.js

@@ -4,11 +4,13 @@ exports.newSessionId = newSessionId;
 exports.newMessageId = newMessageId;
 exports.newCommitmentId = newCommitmentId;
 exports.nowUnixMs = nowUnixMs;
-exports.encodeContext = encodeContext;
 exports.buildSessionStartPayload = buildSessionStartPayload;
 exports.inferOutcomePositive = inferOutcomePositive;
 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");
@@ -25,15 +27,6 @@ function newCommitmentId() {
 function nowUnixMs() {
     return Date.now();
 }
-function encodeContext(context) {
-    if (!context)
-        return Buffer.alloc(0);
-    if (Buffer.isBuffer(context))
-        return context;
-    if (typeof context === 'string')
-        return Buffer.from(context, 'utf8');
-    return Buffer.from(JSON.stringify(context), 'utf8');
-}
 function buildSessionStartPayload(input) {
     return {
         intent: input.intent,
@@ -42,7 +35,8 @@ function buildSessionStartPayload(input) {
         configurationVersion: input.configurationVersion ?? constants_1.DEFAULT_CONFIGURATION_VERSION,
         policyVersion: input.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION,
         ttlMs: input.ttlMs,
-        context: encodeContext(input.context),
+        contextId: input.contextId ?? '',
+        extensions: input.extensions ?? {},
         roots: input.roots ?? [],
     };
 }
@@ -68,6 +62,43 @@ function buildCommitmentPayload(input) {
 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

@@ -24,7 +24,8 @@ export declare class HandoffSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;
@@ -39,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;

package/dist/handoff.js

@@ -6,14 +6,6 @@ const constants_1 = require("./constants");
 const envelope_1 = require("./envelope");
 const handoff_1 = require("./projections/handoff");
 const validation_1 = require("./validation");
-let sendContextWarned = false;
-function warnSendContextOnce() {
-    if (sendContextWarned)
-        return;
-    sendContextWarned = true;
-    // eslint-disable-next-line no-console
-    console.warn('[macp-sdk-typescript] HandoffSession.sendContext() is deprecated and will be removed in 0.4.0. Use addContext() instead.');
-}
 class HandoffSession {
     client;
     sessionId;
@@ -55,7 +47,8 @@ class HandoffSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
@@ -94,14 +87,6 @@ class HandoffSession {
         });
         return this.sendAndTrack(envelope, input.auth);
     }
-    /**
-     * @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.
-     */
-    async sendContext(input) {
-        warnSendContextOnce();
-        return this.addContext(input);
-    }
     async acceptHandoff(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
         const envelope = (0, envelope_1.buildEnvelope)({

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-export * from './auth';
+export { Auth, type AuthConfig, type BearerAuthOptions } from './auth';
+export * from './base-session';
 export * from './client';
 export * from './constants';
 export * from './decision';
 export * from './envelope';
 export * from './errors';
 export * from './handoff';
+export * from './logging';
 export * from './policy';
 export * from './projections';
 export * from './proposal';

package/dist/index.js

@@ -36,14 +36,22 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agent = void 0;
-__exportStar(require("./auth"), exports);
+exports.agent = 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`
+// submodule if needed, but intentionally absent from the top-level surface
+// to match python-sdk's `__all__` (which only exposes `AuthConfig`).
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "Auth", { enumerable: true, get: function () { return auth_1.Auth; } });
+__exportStar(require("./base-session"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./decision"), exports);
 __exportStar(require("./envelope"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./handoff"), exports);
+__exportStar(require("./logging"), exports);
 __exportStar(require("./policy"), exports);
 __exportStar(require("./projections"), exports);
 __exportStar(require("./proposal"), exports);

package/dist/logging.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structured logger for the MACP SDK.
+ *
+ * Parity with python-sdk's `macp_sdk._logging.logger` + `configure_logging()`:
+ * production Node apps need controllable log levels (silent by default-ish,
+ * opt-in verbose) and the ability to re-route to Pino / Winston / etc.
+ */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+export type LogSink = (level: Exclude<LogLevel, 'silent'>, args: unknown[]) => void;
+export declare const logger: {
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+};
+export declare function configureLogging(options: {
+    level?: LogLevel;
+    sink?: LogSink;
+}): void;
+/** Test-only: reset to env-derived level + default sink. */
+export declare function _resetLoggingForTests(): void;