macp-sdk-typescript 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -4,15 +4,190 @@ 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.4.0] - 2026-06-22
+
+Adopts `@multiagentcoordinationprotocol/proto` 0.1.3 — session
+suspend/resume, explicit cancellation, and cross-session commitment
+supersession. Plan: `plans/macp-proto-0.1.3-suspend-cancel-supersede.md`.
+
+### Added
+
+- **`MacpClient.suspendSession(sessionId, reason, options?)` /
+  `resumeSession(...)`** — control-plane RPCs for the new non-terminal
+  `SUSPENDED` state. Suspension banks the session's remaining TTL and
+  causes the runtime to reject messages until resume restores `OPEN`.
+  Mirrors `cancelSession`'s generic-invoke pattern and NACK handling.
+- **`suspend()` / `resume()` on every session helper** (`DecisionSession`,
+  `ProposalSession`, `TaskSession`, `HandoffSession`, `QuorumSession`, and
+  `BaseSession`) — delegate to the new client RPCs with `raiseOnNack: true`.
+- **`SessionState` string-union type** (`src/types.ts`) — mirrors the proto
+  `SessionState` enum and now types `Ack.sessionState` and
+  `SessionMetadata.state`. Adds `SESSION_STATE_SUSPENDED` and
+  `SESSION_STATE_CANCELLED`.
+- **`CommitmentRef` type + `supersedes?` on `CommitmentPayload`** — supports
+  cross-session commitment supersession (RFC-MACP-0001 §7.3).
+  `buildCommitmentPayload({ ..., supersedes })` attaches it; absent by default.
+- **Three new `SessionLifecycleEventType` values** — `EVENT_TYPE_SUSPENDED`,
+  `EVENT_TYPE_RESUMED`, `EVENT_TYPE_CANCELLED`. `SessionLifecycleWatcher`
+  surfaces them unchanged; exhaustive `switch (event.eventType)` blocks now
+  type-check against the widened union.
+- **`buildCommitmentRef({ sessionId, commitmentHash })`** in `src/envelope.ts`
+  — convenience builder for a `CommitmentRef` to pass as
+  `buildCommitmentPayload({ supersedes })`. Parity with python-sdk
+  `build_commitment_ref`.
+- **Session lifecycle predicates** in `src/watchers.ts` —
+  `isSessionCreated` / `isSessionResolved` / `isSessionExpired` /
+  `isSessionCancelled` / `isSessionSuspended` / `isSessionResumed` /
+  `isTerminalSessionLifecycleEvent`, plus the
+  `TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES` constant. They accept either a
+  `SessionLifecycleEvent` or a bare `SessionLifecycleEventType`, mirror
+  python-sdk's `SessionLifecycle` properties, and treat `RESOLVED` / `EXPIRED`
+  / `CANCELLED` as terminal.
+
+### Changed
+
+- **`cancelSession` now resolves to `SESSION_STATE_CANCELLED`** (was
+  `SESSION_STATE_EXPIRED`). The terminal cancellation state is distinct from
+  TTL/policy expiry so consumers can tell an explicit cancel apart from an
+  expiry. No change to the `cancelSession` call signature.
+- **Policy `require_vote_quorum` parity**: `serializeCommitment` now emits
+  `require_vote_quorum` for **every** mode's commitment block (quorum /
+  proposal / task / handoff), not just decision, so policy JSON is
+  byte-identical to python-sdk's `_commitment_dict` across all modes.
+- **Dependency**: bumped `@multiagentcoordinationprotocol/proto` to `^0.1.3`.
+
+## [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

@@ -62,10 +62,13 @@ client.close();
 
 ## Architecture
 
-The SDK uses a **two-layer** design:
+The SDK uses a **three-layer** design:
 
-- **Low-level transport** (`MacpClient`): gRPC connection to the runtime with all 14 RPCs — `initialize`, `send`, `openStream`, `getSession`, `cancelSession`, `getManifest`, `listModes`, `listRoots`, `listExtModes`, `registerExtMode`, `unregisterExtMode`, `promoteMode`, plus streaming watchers.
-- **High-level session helpers**: One class per coordination mode (`DecisionSession`, `ProposalSession`, `TaskSession`, `HandoffSession`, `QuorumSession`). Each wraps `MacpClient`, builds envelopes, encodes payloads, and maintains a local state projection.
+- **Low-level transport** (`MacpClient`): typed wrappers around every `MACPRuntimeService` RPC — `initialize`, `send`, `openStream`, `getSession`, `cancelSession`, `suspendSession`, `resumeSession`, `listSessions`, `getManifest`, `listModes`, `listRoots`, `listExtModes`, `registerExtMode`, `unregisterExtMode`, `promoteMode`, the policy RPCs (`register`/`unregister`/`get`/`listPolicies`), plus streaming watchers (`ModeRegistryWatcher`, `RootsWatcher`, `SignalWatcher`, `PolicyWatcher`, `SessionLifecycleWatcher`).
+- **High-level session helpers**: one class per coordination mode (`DecisionSession`, `ProposalSession`, `TaskSession`, `HandoffSession`, `QuorumSession`) — wraps `MacpClient`, builds envelopes, encodes payloads, and maintains a local state projection.
+- **Agent framework** (`src/agent/`): event-driven `Participant` with strategy-based handlers, bootstrap runner (`fromBootstrap`), gRPC/HTTP transports, and the optional cancel-callback HTTP server.
+
+See [`docs/guides/architecture.md`](docs/guides/architecture.md) for the full map.
 
 Every session class follows the same pattern:
 1. Construct with a `MacpClient` and options
@@ -141,10 +144,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
@@ -262,6 +265,35 @@ Bootstrap files can include an `initiator` section for participants that start t
 }
 ```
 
+### Strategies
+
+Composable handler factories for Decision Mode — register them directly on a
+`Participant`:
+
+```typescript
+participant
+  .on('Proposal', agent.evaluationHandler(agent.functionEvaluator(async (p) => ({
+    recommendation: 'APPROVE', confidence: 0.9, reason: 'looks good',
+  }))))
+  .on('Evaluation', agent.votingHandler(agent.majorityVoter({ positiveThreshold: 0.6 })))
+  .on('Vote', agent.commitmentHandler(agent.majorityCommitter({ quorumSize: 2 })));
+```
+
+Each layer has a prebuilt and a function-wrapper form: `functionEvaluator`,
+`functionVoter`, `functionCommitter` (zero-ceremony wrappers) next to
+`majorityVoter` / `majorityCommitter` (batteries-included defaults). Full
+reference: [`docs/api/strategies.md`](docs/api/strategies.md).
+
+### Cancel Callback
+
+Long-running agents can expose an HTTP endpoint that an orchestrator POSTs to
+in order to request a clean shutdown (RFC-MACP-0001 §7.2 Option A). Bootstrap
+JSON with a `cancel_callback: { host, port, path }` block auto-wires the
+server via `fromBootstrap()`; for the manual path use
+`startCancelCallbackServer(...)` + `Participant.attachCancelCallbackServer(...)`.
+See [`docs/api/cancel-callback.md`](docs/api/cancel-callback.md) and
+[`examples/cancel-callback.ts`](examples/cancel-callback.ts).
+
 ## Authentication
 
 ```typescript
@@ -319,6 +351,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;
 }