macp-sdk-typescript 0.2.0 → 0.3.0

package/dist/agent/participant.js

@@ -4,12 +4,15 @@ exports.Participant = void 0;
 const constants_1 = require("../constants");
 const decision_1 = require("../decision");
 const handoff_1 = require("../handoff");
+const logging_1 = require("../logging");
 const decision_2 = require("../projections/decision");
 const proposal_1 = require("../proposal");
 const quorum_1 = require("../quorum");
 const task_1 = require("../task");
+const cancel_callback_1 = require("./cancel-callback");
 const dispatcher_1 = require("./dispatcher");
 const transports_1 = require("./transports");
+const TERMINAL_PHASES = new Set(['Committed', 'Accepted', 'Declined', 'Cancelled', 'TerminalRejected']);
 class Participant {
     participantId;
     sessionId;
@@ -21,8 +24,15 @@ class Participant {
     dispatcher;
     session;
     transport;
+    initiatorConfig;
+    participants;
+    modeVersion;
+    configurationVersion;
+    policyVersion;
     running = false;
     lastPhase;
+    cancelCallbackServer;
+    cancelCallbackConfig;
     constructor(config) {
         this.participantId = config.participantId;
         this.sessionId = config.sessionId;
@@ -43,6 +53,12 @@ class Participant {
         this.lastPhase = projection.phase;
         this.actions = this.buildActions();
         this.transport = config.transport ?? new transports_1.GrpcTransportAdapter(config.client, config.sessionId, config.auth);
+        this.initiatorConfig = config.initiator;
+        this.participants = config.participants ?? [];
+        this.modeVersion = config.modeVersion;
+        this.configurationVersion = config.configurationVersion;
+        this.policyVersion = config.policyVersion;
+        this.cancelCallbackConfig = config.cancelCallback;
     }
     createModeSession(mode, client, opts) {
         switch (mode) {
@@ -154,68 +170,150 @@ class Participant {
         this.dispatcher.onTerminal(handler);
         return this;
     }
+    /** Whether {@link stop} has been called (or the loop has exited). */
+    get isStopped() {
+        return !this.running;
+    }
     async run() {
         if (this.running)
             return;
         this.running = true;
-        const sessionInfo = {
-            sessionId: this.sessionId,
-            mode: this.mode,
-            participants: [],
-            policyVersion: undefined,
-        };
+        if (this.cancelCallbackConfig && !this.cancelCallbackServer) {
+            this.cancelCallbackServer = await (0, cancel_callback_1.startCancelCallbackServer)({
+                host: this.cancelCallbackConfig.host,
+                port: this.cancelCallbackConfig.port,
+                path: this.cancelCallbackConfig.path,
+                onCancel: () => {
+                    void this.stop();
+                },
+            });
+        }
+        if (this.initiatorConfig && this.session) {
+            await this.emitInitiatorEnvelopes();
+        }
         try {
             for await (const message of this.transport.start()) {
                 if (!this.running)
                     break;
-                const ctx = {
-                    participant: this,
-                    projection: this.projection,
-                    actions: this.actions,
-                    session: sessionInfo,
-                    log: (msg, details) => {
-                        // eslint-disable-next-line no-console
-                        console.log(`[${this.participantId}] ${msg}`, details ?? '');
-                    },
-                };
-                // Apply envelope to projection if we have a mode session
-                if (this.session && message.raw) {
-                    const applyMethod = this.session
-                        .projection.applyEnvelope;
-                    if (typeof applyMethod === 'function') {
-                        applyMethod.call(this.session.projection, message.raw, this.client.protoRegistry);
-                    }
-                }
-                // Dispatch message
-                await this.dispatcher.dispatch(message, ctx);
-                // Check for phase change
-                const currentPhase = this.projection.phase;
-                if (currentPhase !== this.lastPhase) {
-                    this.lastPhase = currentPhase;
-                    await this.dispatcher.dispatchPhaseChange(currentPhase, ctx);
-                    // Check for terminal state
-                    if (currentPhase === 'Committed' ||
-                        currentPhase === 'Accepted' ||
-                        currentPhase === 'Declined' ||
-                        currentPhase === 'Cancelled' ||
-                        currentPhase === 'TerminalRejected') {
-                        const terminalResult = {
-                            state: currentPhase,
-                            commitment: this.projection.commitment,
-                        };
-                        await this.dispatcher.dispatchTerminal(terminalResult);
-                        break;
-                    }
-                }
+                const reachedTerminal = await this.processMessage(message);
+                if (reachedTerminal)
+                    break;
             }
         }
         finally {
             this.running = false;
         }
     }
+    /**
+     * Manually process a single envelope. Parity with python-sdk's
+     * {@code Participant.process_event}. Useful for deterministic unit tests
+     * and for driving the participant from a foreign event loop without
+     * installing a {@link TransportAdapter}.
+     */
+    async processEvent(envelope) {
+        const payload = this.client.protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload) ?? {};
+        const message = {
+            messageType: envelope.messageType,
+            sender: envelope.sender,
+            payload,
+            proposalId: payload.proposalId ?? payload.proposal_id,
+            raw: envelope,
+            seq: 0,
+        };
+        await this.processMessage(message);
+    }
+    buildHandlerContext() {
+        const sessionInfo = {
+            sessionId: this.sessionId,
+            mode: this.mode,
+            participants: this.participants,
+            modeVersion: this.modeVersion,
+            configurationVersion: this.configurationVersion,
+            policyVersion: this.policyVersion,
+        };
+        return {
+            participant: this,
+            projection: this.projection,
+            actions: this.actions,
+            session: sessionInfo,
+            log: (msg, details) => {
+                logging_1.logger.debug(`[${this.participantId}] ${msg}`, details ?? '');
+            },
+        };
+    }
+    /** Returns true if a terminal state was reached. */
+    async processMessage(message) {
+        const ctx = this.buildHandlerContext();
+        if (this.session && message.raw) {
+            const applyMethod = this.session.projection
+                .applyEnvelope;
+            if (typeof applyMethod === 'function') {
+                applyMethod.call(this.session.projection, message.raw, this.client.protoRegistry);
+            }
+        }
+        await this.dispatcher.dispatch(message, ctx);
+        const currentPhase = this.projection.phase;
+        if (currentPhase !== this.lastPhase) {
+            this.lastPhase = currentPhase;
+            await this.dispatcher.dispatchPhaseChange(currentPhase, ctx);
+            if (TERMINAL_PHASES.has(currentPhase)) {
+                const terminalResult = {
+                    state: currentPhase,
+                    commitment: this.projection.commitment,
+                };
+                await this.dispatcher.dispatchTerminal(terminalResult);
+                return true;
+            }
+        }
+        return false;
+    }
     async stop() {
         this.running = false;
         await this.transport.stop();
+        if (this.cancelCallbackServer) {
+            const srv = this.cancelCallbackServer;
+            this.cancelCallbackServer = undefined;
+            try {
+                await srv.close();
+            }
+            catch (err) {
+                logging_1.logger.debug('cancel_callback close failed', err);
+            }
+        }
+    }
+    /**
+     * Attach a running cancel-callback HTTP server to this participant.
+     * The server is closed automatically when {@link stop} is called.
+     * Parity with python-sdk's `Participant.attach_cancel_callback_server`.
+     */
+    attachCancelCallbackServer(server) {
+        this.cancelCallbackServer = server;
+    }
+    async emitInitiatorEnvelopes() {
+        if (!this.initiatorConfig || !this.session)
+            return;
+        const ss = this.initiatorConfig.sessionStart;
+        if ('start' in this.session && typeof this.session.start === 'function') {
+            await this.session.start({
+                intent: ss.intent,
+                participants: ss.participants,
+                ttlMs: ss.ttlMs,
+                contextId: ss.contextId,
+                extensions: ss.extensions,
+                roots: ss.roots,
+            });
+        }
+        const kickoff = this.initiatorConfig.kickoff;
+        if (!kickoff)
+            return;
+        if (kickoff.messageType === 'Proposal' && this.session instanceof decision_1.DecisionSession) {
+            const payload = kickoff.payload;
+            await this.session.propose({
+                proposalId: String(payload.proposalId ?? payload.proposal_id ?? `${this.sessionId}-kickoff`),
+                option: String(payload.option ?? 'decide'),
+                rationale: payload.rationale !== undefined ? String(payload.rationale) : undefined,
+            });
+        }
     }
 }
 exports.Participant = Participant;

package/dist/agent/runner.d.ts

@@ -11,8 +11,41 @@ export interface BootstrapPayload {
     auth_token?: string;
     agent_id?: string;
     secure?: boolean;
-    /** Mirror of {@link MacpClientOptions.allowInsecure}; required when `secure` is false. */
     allow_insecure?: boolean;
     participants?: string[];
+    initiator?: {
+        session_start: {
+            intent: string;
+            participants: string[];
+            ttl_ms: number;
+            mode_version?: string;
+            configuration_version?: string;
+            policy_version?: string;
+            context?: Record<string, unknown>;
+            context_id?: string;
+            extensions?: Record<string, unknown>;
+            roots?: Array<{
+                uri: string;
+                name?: string;
+            }>;
+        };
+        kickoff?: {
+            message_type: string;
+            payload_type?: string;
+            payload: Record<string, unknown>;
+        };
+    };
+    metadata?: Record<string, unknown>;
+    /**
+     * Bind a cancel-callback HTTP endpoint (RFC-0001 §7.2 Option A). The
+     * orchestrator POSTs `{runId, reason}` to `http://host:port{path}` to
+     * request a clean shutdown. The runner starts the endpoint before
+     * entering the event loop and closes it when the participant stops.
+     */
+    cancel_callback?: {
+        host: string;
+        port: number;
+        path: string;
+    };
 }
 export declare function fromBootstrap(bootstrapPath?: string): Participant;

package/dist/agent/runner.js

@@ -69,6 +69,26 @@ function fromBootstrap(bootstrapPath) {
         allowInsecure: payload.allow_insecure,
         auth,
     });
+    let initiator;
+    if (payload.initiator) {
+        const ss = payload.initiator.session_start;
+        initiator = {
+            sessionStart: {
+                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
+                ? {
+                    messageType: payload.initiator.kickoff.message_type,
+                    payload: payload.initiator.kickoff.payload,
+                }
+                : undefined,
+        };
+    }
     const config = {
         participantId: payload.participant_id,
         sessionId: payload.session_id,
@@ -79,6 +99,39 @@ function fromBootstrap(bootstrapPath) {
         modeVersion: payload.mode_version,
         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 {
@@ -125,6 +145,11 @@ export declare class MacpClient {
         auth?: AuthConfig;
         deadlineMs?: number;
     }): Promise<PolicyDescriptor[]>;
+    listSessions(options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<SessionMetadata[]>;
+    watchSessions(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     /** @deprecated Use {@link watchPolicies}. Scheduled for removal in 0.4.0. */
     _watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;