macp-sdk-typescript 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -4,15 +4,138 @@ All notable changes to `macp-sdk-typescript` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project uses [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.3.0] - 2026-04-21
+
+Parity release — brings TypeScript SDK to full feature parity with
+`macp-sdk-python` 0.3.0. Plan: `plans/sdk-parity-plan.md`.
+
+### Added
+
+- **Cancel-callback server** (Gap B, RFC-0001 §7.2 Option A):
+  `startCancelCallbackServer({ host, port, path, onCancel })` returns a
+  handle backed by Node's `http` module; `Participant` starts the server
+  automatically when `ParticipantConfig.cancelCallback` is set and closes
+  it on `stop()`. `fromBootstrap()` wires the new `cancel_callback`
+  field in the bootstrap JSON. Exports:
+  `startCancelCallbackServer`, `CancelCallbackServer`, `CancelHandler`.
+- **Function-wrapped voting and commitment strategies** (Gap C):
+  `functionVoter(shouldVote, decideVote)` and
+  `functionCommitter(shouldCommit, decideCommitment)` in
+  `src/agent/strategies.ts` — the low-friction way to plug a custom rule
+  into a `Participant` without a class.
+- **Standalone signal and progress builders** (Gap D):
+  `buildSignalPayload(input)` and `buildProgressPayload(input)` in
+  `src/envelope.ts`. `MacpClient.sendSignal` / `sendProgress` now use
+  the shared builders internally.
+- **`serializeMessage(msg)` helper** (Gap N) — parity with
+  `python-sdk envelope.serialize_message`; dispatches to
+  `serializeBinary()` / `toBinary()` / `finish()` on the passed
+  protobuf message.
+- **Structured logger** (Gap G): `src/logging.ts` exports `logger` with
+  `error`/`warn`/`info`/`debug` level methods and `configureLogging({ level, sink })`.
+  Reads `MACP_LOG_LEVEL` on module init (default `warn`). The two
+  remaining `console.*` callsites in `src/agent/participant.ts` and
+  `src/handoff.ts` now route through the structured logger.
+- **`AckFailure` shape** (Gap I): structured NACK record exported from
+  `src/errors.ts`. Populated on `MacpAckError.failure` from both
+  `ack.error.details` and gRPC trailing metadata.
+- **`BaseSession` / `BaseProjection`** (Gap J): abstract extension
+  points exported from `src/base-session.ts` and `src/projections/base.ts`
+  for custom mode helpers (modes registered via `registerExtMode`).
+  Mirrors `python-sdk`'s `BaseSession` / `BaseProjection`.
+- **Named policy rule interfaces** (Gap K): `VotingRules`,
+  `ObjectionHandlingRules`, `EvaluationRules`, `CommitmentRules`,
+  `QuorumThreshold`, `AbstentionRules`, `ProposalAcceptanceRules`,
+  `CounterProposalRules`, `RejectionRules`, `TaskAssignmentRules`,
+  `TaskCompletionRules`, `HandoffAcceptanceRules` now exported as
+  first-class interfaces matching `macp-sdk-python` exports.
+- **`STANDARD_MODES` tuple** (Gap L) in `src/constants.ts`.
+- **Parity examples** (Gap M): `examples/policy-registration.ts`,
+  `examples/agent-policy-aware.ts`, `examples/direct-agent-auth-initiator.ts`,
+  `examples/direct-agent-auth-observer.ts`.
+
+### Changed
+
+- **Error-code constants renamed** (Gap F, breaking): dropped the
+  `ERR_` prefix so TS constants match the on-the-wire strings and the
+  `macp-sdk-python` exports. Rename table —
+  `ERR_UNSUPPORTED_PROTOCOL_VERSION` → `UNSUPPORTED_PROTOCOL_VERSION`,
+  `ERR_INVALID_ENVELOPE` → `INVALID_ENVELOPE`,
+  `ERR_SESSION_NOT_FOUND` → `SESSION_NOT_FOUND`,
+  `ERR_SESSION_NOT_OPEN` → `SESSION_NOT_OPEN`,
+  `ERR_SESSION_ALREADY_EXISTS` → `SESSION_ALREADY_EXISTS`,
+  `ERR_MODE_NOT_SUPPORTED` → `MODE_NOT_SUPPORTED`,
+  `ERR_FORBIDDEN` → `FORBIDDEN`,
+  `ERR_UNAUTHENTICATED` → `UNAUTHENTICATED`,
+  `ERR_DUPLICATE_MESSAGE` → `DUPLICATE_MESSAGE`,
+  `ERR_PAYLOAD_TOO_LARGE` → `PAYLOAD_TOO_LARGE`,
+  `ERR_RATE_LIMITED` → `RATE_LIMITED`,
+  `ERR_INTERNAL_ERROR` → `INTERNAL_ERROR`,
+  `ERR_POLICY_DENIED` → `POLICY_DENIED`,
+  `ERR_INVALID_SESSION_ID` → `INVALID_SESSION_ID`,
+  `ERR_UNKNOWN_POLICY_VERSION` → `UNKNOWN_POLICY_VERSION`,
+  `ERR_INVALID_POLICY_DEFINITION` → `INVALID_POLICY_DEFINITION`.
+- `MacpClient.clientVersion` default now `0.3.0`.
+
+### Removed
+
+- **`HandoffSession.sendContext()`** (Gap A, breaking): the deprecated
+  alias (warning first emitted in 0.2.3) has been removed. Use
+  `HandoffSession.addContext()`.
+- **`MacpAckError.reasons` getter** (breaking): use
+  `MacpAckError.failure.reasons` instead. `.failure` is the canonical
+  structured NACK record and matches `macp-sdk-python`'s
+  `MacpAckError.failure`.
+- **Mode-prefixed policy rule type aliases** (breaking): the
+  `CommitmentRulesInput`, `DecisionVotingRules`,
+  `DecisionObjectionHandling`, `DecisionEvaluationRules`, and
+  `DecisionCommitmentRules` type aliases have been removed. Use the
+  unprefixed names (`CommitmentRules`, `VotingRules`,
+  `ObjectionHandlingRules`, `EvaluationRules`) introduced in Gap K.
+
+## [0.2.3] - 2026-04-21
 
 ### Added
+- `MacpStream.sendSubscribe(sessionId, afterSequence?)` — subscribe-only stream
+  frame (RFC-MACP-0006-A1). The runtime replays accepted envelopes from the
+  cursor before switching to live broadcast, so non-initiator agents observe
+  `SessionStart` and earlier mode envelopes regardless of join order.
+- `GrpcTransportAdapter` now sends a subscribe frame automatically on start so
+  `Participant`-based agents pick up history without bespoke wiring.
+- Unit coverage for `MacpStream.sendSubscribe` (default cursor, custom cursor,
+  closed-stream rejection, write-error propagation, sequential resubscribe) and
+  `GrpcTransportAdapter` (subscribe ordering, empty-stream subscribe, auth
+  pass-through to `openStream`).
+- Integration tests for late-subscriber replay and future-cursor skip
+  (`tests/integration/runtime.test.ts`).
+- `InitiatorConfig.sessionStart` now accepts `contextId` and `extensions`, and
+  `Participant.emitInitiatorEnvelopes()` forwards both to the mode-session
+  `start()` call (SDK-TS-1). `fromBootstrap()` decodes `context_id` plus a
+  JSON-native `extensions` map from the bootstrap file — each value is
+  serialised as UTF-8 JSON into the `Record<string, Buffer>` shape the
+  envelope requires; pre-encoded `Buffer` / `Uint8Array` values pass through
+  unchanged.
+- Documented `MacpClient.listSessions()` (parity with the python-sdk SDK-PY-2
+  gap) and `SessionLifecycleWatcher` (parity with python-sdk SDK-PY-3). Both
+  were already implemented — this release adds the API reference, a
+  `docs/guides/streaming.md` section, unit coverage for `listSessions`, and
+  integration tests that exercise enumeration + a `CREATED` lifecycle event
+  round-trip against a live runtime.
 - Warn-once migration hint when the deprecated `HandoffSession.sendContext()`
   alias is invoked. Scheduled for removal in `0.4.0`; use `addContext()`.
 - `docs/api/sessions.md` now documents the identity-guard contract.
 - `docs/guides/architecture.md` rewritten to reflect the three-layer design
   (transport / session helpers / agent framework).
 
+### Changed
+- Integration tests updated to match the proto field renames that landed in
+  `@multiagentcoordinationprotocol/proto@0.1.x`: `Evaluation.analysis` →
+  `reason`, `Proposal.description` → `summary`, `TaskRequest.assignee` →
+  `requestedAssignee` (Task accept/update/complete/fail/reject now carry an
+  `assignee` field), `TaskUpdate.progress` is required, `HandoffContext.data`
+  → `context` (+ `contentType`), `HandoffAccept.acceptedBy` and
+  `HandoffDecline.declinedBy` are now required.
+
 ### Deprecated
 - `HandoffSession.sendContext()` remains available as an alias but emits a
   one-shot `console.warn`. Use `HandoffSession.addContext()` instead.

package/README.md

@@ -141,10 +141,10 @@ import { TaskSession } from 'macp-sdk-typescript';
 
 const session = new TaskSession(client);
 await session.start({ intent: '...', participants: ['worker'], ttlMs: 120_000 });
-await session.request({ taskId: 't1', title: 'Build feature', instructions: '...' });
+await session.requestTask({ taskId: 't1', title: 'Build feature', instructions: '...' });
 await session.acceptTask({ taskId: 't1', assignee: 'worker' });
-await session.update({ taskId: 't1', status: 'working', progress: 0.5, message: 'halfway' });
-await session.complete({ taskId: 't1', assignee: 'worker', summary: 'done' });
+await session.updateTask({ taskId: 't1', status: 'working', progress: 0.5, message: 'halfway' });
+await session.completeTask({ taskId: 't1', assignee: 'worker', summary: 'done' });
 await session.commit({ action: 'task.completed', authorityScope: 'lead', reason: '...' });
 
 // Projection queries
@@ -319,6 +319,17 @@ for await (const envelope of stream.responses()) {
 stream.close();
 ```
 
+To attach to a session that is already in flight and receive accepted history before live broadcast (RFC-MACP-0006 §3.2 passive subscribe):
+
+```typescript
+const stream = client.openStream({ auth });
+await stream.sendSubscribe(sessionId);            // full replay then live
+// or, after a reconnect:
+await stream.sendSubscribe(sessionId, lastSeq);    // resume from cursor
+```
+
+The agent framework's `GrpcTransportAdapter` calls this for you on start, so non-initiator agents see `SessionStart` regardless of join order.
+
 ### Registry & Root Watchers
 
 ```typescript

package/dist/agent/cancel-callback.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cancel-callback HTTP endpoint — RFC-0001 §7.2 Option A.
+ *
+ * Parity with python-sdk's `macp_sdk.agent.cancel_callback`. The
+ * examples-service's `BootstrapPayload.cancel_callback` field asks each
+ * agent to listen on `http://host:port{path}` for a `POST` whose JSON
+ * body is `{"runId": ..., "reason": ...}`. Receipt of the POST should
+ * stop the participant cleanly — typically by calling `participant.stop()`.
+ */
+export type CancelHandler = (runId: string, reason: string) => void | Promise<void>;
+export interface CancelCallbackServerOptions {
+    host: string;
+    port: number;
+    path: string;
+    onCancel: CancelHandler;
+}
+export interface CancelCallbackServer {
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+    close(): Promise<void>;
+}
+export declare function startCancelCallbackServer(options: CancelCallbackServerOptions): Promise<CancelCallbackServer>;

package/dist/agent/cancel-callback.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startCancelCallbackServer = startCancelCallbackServer;
+const http = __importStar(require("node:http"));
+const logging_1 = require("../logging");
+function normalisePath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
+function startCancelCallbackServer(options) {
+    const path = normalisePath(options.path);
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(async (req, res) => {
+            if (req.method !== 'POST' || req.url !== path) {
+                res.statusCode = 404;
+                res.end();
+                return;
+            }
+            let body = {};
+            try {
+                const raw = await readBody(req);
+                if (raw)
+                    body = JSON.parse(raw);
+            }
+            catch {
+                body = {};
+            }
+            const runId = String(body.runId ?? body.run_id ?? '');
+            const reason = String(body.reason ?? '');
+            logging_1.logger.info('cancel_callback invoked', { runId, reason });
+            try {
+                await options.onCancel(runId, reason);
+            }
+            catch (err) {
+                logging_1.logger.error('cancel_callback handler raised', err);
+                res.statusCode = 500;
+                res.end();
+                return;
+            }
+            res.statusCode = 202;
+            res.setHeader('Content-Type', 'application/json');
+            res.end('{"ok":true}');
+        });
+        server.once('error', reject);
+        server.listen(options.port, options.host, () => {
+            server.removeListener('error', reject);
+            const addr = server.address();
+            const boundHost = addr.address;
+            const boundPort = addr.port;
+            logging_1.logger.debug(`cancel_callback listening on http://${boundHost}:${boundPort}${path}`);
+            let closing = false;
+            const handle = {
+                host: boundHost,
+                port: boundPort,
+                path,
+                close() {
+                    if (closing)
+                        return Promise.resolve();
+                    closing = true;
+                    return new Promise((res, rej) => {
+                        server.close((err) => (err ? rej(err) : res()));
+                    });
+                },
+            };
+            resolve(handle);
+        });
+    });
+}

package/dist/agent/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types';
+export * from './cancel-callback';
 export * from './dispatcher';
 export * from './participant';
 export * from './strategies';

package/dist/agent/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpTransportAdapter = exports.GrpcTransportAdapter = void 0;
 __exportStar(require("./types"), exports);
+__exportStar(require("./cancel-callback"), exports);
 __exportStar(require("./dispatcher"), exports);
 __exportStar(require("./participant"), exports);
 __exportStar(require("./strategies"), exports);

package/dist/agent/participant.d.ts

@@ -1,5 +1,7 @@
 import type { AuthConfig } from '../auth';
 import type { MacpClient } from '../client';
+import type { Envelope } from '../types';
+import { type CancelCallbackServer } from './cancel-callback';
 import { type TransportAdapter } from './transports';
 import type { MessageHandler, PhaseChangeHandler, ProjectionLike, SessionActions, TerminalHandler } from './types';
 export interface InitiatorConfig {
@@ -7,6 +9,8 @@ export interface InitiatorConfig {
         intent: string;
         participants: string[];
         ttlMs: number;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         context?: Record<string, unknown>;
         roots?: Array<{
             uri: string;
@@ -30,6 +34,17 @@ export interface ParticipantConfig {
     policyVersion?: string;
     transport?: TransportAdapter;
     initiator?: InitiatorConfig;
+    /**
+     * Bind a cancel-callback HTTP endpoint (RFC-0001 §7.2 Option A) when
+     * this participant's event loop starts. The server is closed
+     * automatically when {@link Participant.stop} is called. Parity with
+     * python-sdk's bootstrap `cancel_callback` field.
+     */
+    cancelCallback?: {
+        host: string;
+        port: number;
+        path: string;
+    };
 }
 export declare class Participant {
     readonly participantId: string;
@@ -43,15 +58,39 @@ export declare class Participant {
     private readonly session;
     private readonly transport;
     private readonly initiatorConfig?;
+    private readonly participants;
+    private readonly modeVersion?;
+    private readonly configurationVersion?;
+    private readonly policyVersion?;
     private running;
     private lastPhase;
+    private cancelCallbackServer?;
+    private readonly cancelCallbackConfig?;
     constructor(config: ParticipantConfig);
     private createModeSession;
     private buildActions;
     on(messageType: string, handler: MessageHandler): Participant;
     onPhaseChange(phase: string, handler: PhaseChangeHandler): Participant;
     onTerminal(handler: TerminalHandler): Participant;
+    /** Whether {@link stop} has been called (or the loop has exited). */
+    get isStopped(): boolean;
     run(): Promise<void>;
+    /**
+     * 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}.
+     */
+    processEvent(envelope: Envelope): Promise<void>;
+    private buildHandlerContext;
+    /** Returns true if a terminal state was reached. */
+    private processMessage;
     stop(): Promise<void>;
+    /**
+     * 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: CancelCallbackServer): void;
     private emitInitiatorEnvelopes;
 }

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;
@@ -22,8 +25,14 @@ class Participant {
     session;
     transport;
     initiatorConfig;
+    participants;
+    modeVersion;
+    configurationVersion;
+    policyVersion;
     running = false;
     lastPhase;
+    cancelCallbackServer;
+    cancelCallbackConfig;
     constructor(config) {
         this.participantId = config.participantId;
         this.sessionId = config.sessionId;
@@ -45,6 +54,11 @@ class Participant {
         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) {
@@ -156,71 +170,124 @@ 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;
+        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();
         }
-        const sessionInfo = {
-            sessionId: this.sessionId,
-            mode: this.mode,
-            participants: [],
-            policyVersion: undefined,
-        };
         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)
@@ -231,6 +298,8 @@ class Participant {
                 intent: ss.intent,
                 participants: ss.participants,
                 ttlMs: ss.ttlMs,
+                contextId: ss.contextId,
+                extensions: ss.extensions,
                 roots: ss.roots,
             });
         }

package/dist/agent/runner.d.ts

@@ -22,6 +22,8 @@ export interface BootstrapPayload {
             configuration_version?: string;
             policy_version?: string;
             context?: Record<string, unknown>;
+            context_id?: string;
+            extensions?: Record<string, unknown>;
             roots?: Array<{
                 uri: string;
                 name?: string;
@@ -34,5 +36,16 @@ export interface BootstrapPayload {
         };
     };
     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;