macp-sdk-typescript 0.2.2 → 0.3.0

package/dist/agent/runner.js

@@ -77,6 +77,8 @@ function fromBootstrap(bootstrapPath) {
                 intent: ss.intent,
                 participants: ss.participants,
                 ttlMs: ss.ttl_ms,
+                contextId: ss.context_id,
+                extensions: encodeExtensions(ss.extensions),
                 roots: ss.roots,
             },
             kickoff: payload.initiator.kickoff
@@ -98,6 +100,38 @@ function fromBootstrap(bootstrapPath) {
         configurationVersion: payload.configuration_version,
         policyVersion: payload.policy_version ?? constants_1.DEFAULT_POLICY_VERSION,
         initiator,
+        cancelCallback: payload.cancel_callback
+            ? {
+                host: payload.cancel_callback.host,
+                port: payload.cancel_callback.port,
+                path: payload.cancel_callback.path,
+            }
+            : undefined,
     };
     return new participant_1.Participant(config);
 }
+/**
+ * Serialise a JSON-native extensions map (as delivered in the bootstrap
+ * payload) into the `Record<string, Buffer>` form the SessionStart envelope
+ * expects. Each value is encoded as UTF-8 JSON so arbitrary structures
+ * round-trip through the protobuf `bytes` field. `Buffer` / `Uint8Array`
+ * values are passed through untouched so callers that already hold raw bytes
+ * don't pay a double-encode.
+ */
+function encodeExtensions(extensions) {
+    if (!extensions)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(extensions)) {
+        if (Buffer.isBuffer(value)) {
+            out[key] = value;
+        }
+        else if (value instanceof Uint8Array) {
+            out[key] = Buffer.from(value);
+        }
+        else {
+            out[key] = Buffer.from(JSON.stringify(value), 'utf8');
+        }
+    }
+    return out;
+}

package/dist/agent/strategies.d.ts

@@ -19,6 +19,7 @@ export interface VotingStrategy {
     decideVote(projection: DecisionProjection): Promise<VoteResult>;
 }
 export declare function votingHandler(strategy: VotingStrategy): MessageHandler;
+export declare function functionVoter(shouldVote: (projection: DecisionProjection) => boolean, decideVote: (projection: DecisionProjection) => Promise<VoteResult>): VotingStrategy;
 export declare function majorityVoter(options?: {
     positiveThreshold?: number;
 }): VotingStrategy;
@@ -33,6 +34,7 @@ export interface CommitmentStrategy {
     decideCommitment(projection: DecisionProjection): Promise<CommitmentResult>;
 }
 export declare function commitmentHandler(strategy: CommitmentStrategy): MessageHandler;
+export declare function functionCommitter(shouldCommit: (projection: DecisionProjection) => boolean, decideCommitment: (projection: DecisionProjection) => Promise<CommitmentResult>): CommitmentStrategy;
 export declare function majorityCommitter(options?: {
     quorumSize?: number;
     action?: string;

package/dist/agent/strategies.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluationHandler = evaluationHandler;
 exports.functionEvaluator = functionEvaluator;
 exports.votingHandler = votingHandler;
+exports.functionVoter = functionVoter;
 exports.majorityVoter = majorityVoter;
 exports.commitmentHandler = commitmentHandler;
+exports.functionCommitter = functionCommitter;
 exports.majorityCommitter = majorityCommitter;
 const envelope_1 = require("../envelope");
 function evaluationHandler(strategy) {
@@ -43,6 +45,9 @@ function votingHandler(strategy) {
         }
     };
 }
+function functionVoter(shouldVote, decideVote) {
+    return { shouldVote, decideVote };
+}
 function majorityVoter(options) {
     const threshold = options?.positiveThreshold ?? 0.5;
     return {
@@ -80,6 +85,9 @@ function commitmentHandler(strategy) {
         }
     };
 }
+function functionCommitter(shouldCommit, decideCommitment) {
+    return { shouldCommit, decideCommitment };
+}
 function majorityCommitter(options) {
     const quorum = options?.quorumSize ?? 1;
     const action = options?.action ?? 'commit';

package/dist/agent/transports.js

@@ -25,6 +25,11 @@ class GrpcTransportAdapter {
     }
     async *start() {
         this.stream = this.client.openStream({ auth: this.auth });
+        // RFC-MACP-0006-A1: Subscribe to the session with history replay.
+        // The runtime replays accepted envelopes then switches to live broadcast.
+        // This ensures non-initiator agents receive the SessionStart + Proposal
+        // regardless of spawn order or connection timing.
+        await this.stream.sendSubscribe(this.sessionId);
         for await (const envelope of this.stream.responses()) {
             if (envelope.sessionId !== this.sessionId)
                 continue;

package/dist/base-session.d.ts

@@ -0,0 +1,64 @@
+import { type AuthConfig } from './auth';
+import type { MacpClient, MacpStream } from './client';
+import type { BaseProjection } from './projections/base';
+import type { Ack, Envelope, Root, SessionMetadata } from './types';
+export interface BaseSessionOptions {
+    sessionId?: string;
+    modeVersion?: string;
+    configurationVersion?: string;
+    policyVersion?: string;
+    auth?: AuthConfig;
+}
+/**
+ * Abstract base class for mode session helpers — parity with python-sdk's
+ * `macp_sdk.base_session.BaseSession`. Provides the shared lifecycle
+ * (start, commit, cancel, metadata, openStream) and the two identity-guarded
+ * helpers (`senderFor`, `sendAndTrack`) that every mode session needs.
+ *
+ * Concrete session classes (DecisionSession, etc.) pre-date this base class
+ * and implement their own equivalents; BaseSession is the recommended
+ * extension point for custom modes registered via `registerExtMode`.
+ */
+export declare abstract class BaseSession<P extends BaseProjection> {
+    readonly client: MacpClient;
+    readonly sessionId: string;
+    readonly modeVersion: string;
+    readonly configurationVersion: string;
+    readonly policyVersion: string;
+    readonly auth?: AuthConfig;
+    readonly projection: P;
+    protected abstract readonly mode: string;
+    constructor(client: MacpClient, options?: BaseSessionOptions);
+    /** Return a new projection instance. Subclasses construct their mode-specific projection here. */
+    protected abstract createProjection(): P;
+    /** Resolve the envelope sender, raising {@link MacpIdentityMismatchError} on conflict. */
+    protected senderFor(sender: string | undefined, auth?: AuthConfig): string;
+    /** Send an envelope and, on ACK, feed it to the projection. */
+    protected sendAndTrack(envelope: Envelope, auth?: AuthConfig): Promise<Ack>;
+    /** Send SessionStart and begin tracking via the projection. */
+    start(input: {
+        intent: string;
+        participants: string[];
+        ttlMs: number;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
+        roots?: Root[];
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    /** Send a Commitment envelope to resolve the session. */
+    commit(input: {
+        action: string;
+        authorityScope: string;
+        reason: string;
+        commitmentId?: string;
+        outcomePositive?: boolean;
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    metadata(auth?: AuthConfig): Promise<{
+        metadata: SessionMetadata;
+    }>;
+    cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    openStream(auth?: AuthConfig): MacpStream;
+}

package/dist/base-session.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseSession = void 0;
+const auth_1 = require("./auth");
+const constants_1 = require("./constants");
+const envelope_1 = require("./envelope");
+const logging_1 = require("./logging");
+const validation_1 = require("./validation");
+/**
+ * Abstract base class for mode session helpers — parity with python-sdk's
+ * `macp_sdk.base_session.BaseSession`. Provides the shared lifecycle
+ * (start, commit, cancel, metadata, openStream) and the two identity-guarded
+ * helpers (`senderFor`, `sendAndTrack`) that every mode session needs.
+ *
+ * Concrete session classes (DecisionSession, etc.) pre-date this base class
+ * and implement their own equivalents; BaseSession is the recommended
+ * extension point for custom modes registered via `registerExtMode`.
+ */
+class BaseSession {
+    client;
+    sessionId;
+    modeVersion;
+    configurationVersion;
+    policyVersion;
+    auth;
+    projection;
+    constructor(client, options = {}) {
+        this.client = client;
+        if (options.sessionId)
+            (0, validation_1.validateSessionId)(options.sessionId);
+        this.sessionId = options.sessionId ?? (0, envelope_1.newSessionId)();
+        this.modeVersion = options.modeVersion ?? constants_1.DEFAULT_MODE_VERSION;
+        this.configurationVersion = options.configurationVersion ?? constants_1.DEFAULT_CONFIGURATION_VERSION;
+        this.policyVersion = options.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION;
+        this.auth = options.auth;
+        this.projection = this.createProjection();
+    }
+    /** Resolve the envelope sender, raising {@link MacpIdentityMismatchError} on conflict. */
+    senderFor(sender, auth) {
+        const effectiveAuth = auth ?? this.auth ?? this.client.auth;
+        (0, auth_1.assertSenderMatchesIdentity)(effectiveAuth, sender);
+        return sender ?? (0, auth_1.authSender)(effectiveAuth) ?? '';
+    }
+    /** Send an envelope and, on ACK, feed it to the projection. */
+    async sendAndTrack(envelope, auth) {
+        logging_1.logger.debug('send', {
+            session: envelope.sessionId,
+            messageType: envelope.messageType,
+            sender: envelope.sender,
+        });
+        const ack = await this.client.send(envelope, { auth: auth ?? this.auth });
+        if (ack.ok)
+            this.projection.applyEnvelope(envelope, this.client.protoRegistry);
+        else
+            logging_1.logger.warn('nack', { session: envelope.sessionId, code: ack.error?.code });
+        return ack;
+    }
+    /** Send SessionStart and begin tracking via the projection. */
+    async start(input) {
+        (0, validation_1.validateParticipantCount)(input.participants.length);
+        const payload = (0, envelope_1.buildSessionStartPayload)({
+            intent: input.intent,
+            participants: input.participants,
+            ttlMs: input.ttlMs,
+            contextId: input.contextId,
+            extensions: input.extensions,
+            roots: input.roots,
+            modeVersion: this.modeVersion,
+            configurationVersion: this.configurationVersion,
+            policyVersion: this.policyVersion,
+        });
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: this.mode,
+            messageType: 'SessionStart',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(this.mode, 'SessionStart', (0, envelope_1.toProtoPayload)(payload)),
+        });
+        return this.sendAndTrack(envelope, input.auth ?? this.auth);
+    }
+    /** Send a Commitment envelope to resolve the session. */
+    async commit(input) {
+        const payload = (0, envelope_1.buildCommitmentPayload)({
+            action: input.action,
+            authorityScope: input.authorityScope,
+            reason: input.reason,
+            commitmentId: input.commitmentId,
+            outcomePositive: input.outcomePositive,
+            modeVersion: this.modeVersion,
+            configurationVersion: this.configurationVersion,
+            policyVersion: this.policyVersion,
+        });
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: this.mode,
+            messageType: 'Commitment',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(this.mode, 'Commitment', (0, envelope_1.toProtoPayload)(payload)),
+        });
+        return this.sendAndTrack(envelope, input.auth);
+    }
+    metadata(auth) {
+        return this.client.getSession(this.sessionId, { auth: auth ?? this.auth });
+    }
+    cancel(reason = '', auth) {
+        return this.client.cancelSession(this.sessionId, reason, { auth: auth ?? this.auth });
+    }
+    openStream(auth) {
+        return this.client.openStream({ auth: auth ?? this.auth });
+    }
+}
+exports.BaseSession = BaseSession;

package/dist/client.d.ts

@@ -35,7 +35,27 @@ export declare class MacpStream {
     constructor(call: grpc.ClientDuplexStream<any, any>);
     onInlineError(callback: InlineErrorCallback): void;
     send(envelope: Envelope): Promise<void>;
+    /**
+     * 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: string, afterSequence?: number): Promise<void>;
     responses(): AsyncGenerator<Envelope, void, void>;
+    /**
+     * 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.
+     */
+    read(timeoutMs?: number): Promise<Envelope | null>;
     close(): void;
 }
 export declare class MacpClient {

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;
@@ -348,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',
@@ -366,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/envelope.d.ts

@@ -1,4 +1,4 @@
-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;
@@ -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

@@ -8,6 +8,9 @@ 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");
@@ -59,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.
  *