macp-sdk-typescript 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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/).
 
+## [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

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
@@ -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

package/dist/base-session.d.ts

@@ -60,5 +60,16 @@ export declare abstract class BaseSession<P extends BaseProjection> {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: TTL
+     * is banked and messages are rejected until {@link resume}. See
+     * {@link MacpClient.suspendSession}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring OPEN and the banked TTL. See {@link MacpClient.resumeSession}.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }

package/dist/base-session.js

@@ -105,6 +105,21 @@ class BaseSession {
     cancel(reason = '', auth) {
         return this.client.cancelSession(this.sessionId, reason, { auth: auth ?? this.auth });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: TTL
+     * is banked and messages are rejected until {@link resume}. See
+     * {@link MacpClient.suspendSession}.
+     */
+    suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, { auth: auth ?? this.auth });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring OPEN and the banked TTL. See {@link MacpClient.resumeSession}.
+     */
+    resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, { auth: auth ?? this.auth });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/client.d.ts

@@ -83,12 +83,46 @@ export declare class MacpClient {
     }): Promise<{
         metadata: SessionMetadata;
     }>;
+    /**
+     * Terminate a session via the `CancelSession` control-plane RPC.
+     *
+     * As of proto 0.1.3 the resulting `Ack.sessionState` is
+     * `SESSION_STATE_CANCELLED` (previously `SESSION_STATE_EXPIRED`) — distinct
+     * from TTL/policy expiry so consumers can tell explicit cancellation apart.
+     */
     cancelSession(sessionId: string, reason: string, options?: {
         auth?: AuthConfig;
         deadlineMs?: number;
         raiseOnNack?: boolean;
         cancelledBy?: string;
     }): Promise<Ack>;
+    /**
+     * Pause a session via the `SuspendSession` control-plane RPC (proto 0.1.3+).
+     *
+     * Suspension is non-terminal: the resulting `Ack.sessionState` is
+     * `SESSION_STATE_SUSPENDED`, the session's remaining TTL is banked, and
+     * messages sent to a suspended session are rejected until {@link resumeSession}
+     * restores it to `SESSION_STATE_OPEN`. Restricted to the initiator and
+     * policy-delegated roles, mirroring {@link cancelSession}.
+     */
+    suspendSession(sessionId: string, reason: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+        raiseOnNack?: boolean;
+    }): Promise<Ack>;
+    /**
+     * Resume a suspended session via the `ResumeSession` control-plane RPC
+     * (proto 0.1.3+).
+     *
+     * Restores `SESSION_STATE_OPEN` and adds the banked TTL back to the session's
+     * absolute deadline. Restricted to the initiator and policy-delegated roles,
+     * mirroring {@link suspendSession}.
+     */
+    resumeSession(sessionId: string, reason: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+        raiseOnNack?: boolean;
+    }): Promise<Ack>;
     getManifest(agentId?: string, deadlineMs?: number): Promise<{
         manifest: AgentManifest;
     }>;

package/dist/client.js

@@ -319,6 +319,13 @@ class MacpClient {
         const auth = this.requireAuth(options?.auth);
         return this.unary('GetSession', { sessionId }, auth, options?.deadlineMs);
     }
+    /**
+     * Terminate a session via the `CancelSession` control-plane RPC.
+     *
+     * As of proto 0.1.3 the resulting `Ack.sessionState` is
+     * `SESSION_STATE_CANCELLED` (previously `SESSION_STATE_EXPIRED`) — distinct
+     * from TTL/policy expiry so consumers can tell explicit cancellation apart.
+     */
     async cancelSession(sessionId, reason, options) {
         const auth = this.requireAuth(options?.auth);
         const request = { sessionId, reason };
@@ -330,6 +337,39 @@ class MacpClient {
             throw new errors_1.MacpAckError(ack ?? {});
         return ack;
     }
+    /**
+     * Pause a session via the `SuspendSession` control-plane RPC (proto 0.1.3+).
+     *
+     * Suspension is non-terminal: the resulting `Ack.sessionState` is
+     * `SESSION_STATE_SUSPENDED`, the session's remaining TTL is banked, and
+     * messages sent to a suspended session are rejected until {@link resumeSession}
+     * restores it to `SESSION_STATE_OPEN`. Restricted to the initiator and
+     * policy-delegated roles, mirroring {@link cancelSession}.
+     */
+    async suspendSession(sessionId, reason, options) {
+        const auth = this.requireAuth(options?.auth);
+        const response = await this.unary('SuspendSession', { sessionId, reason }, auth, options?.deadlineMs);
+        const ack = response.ack;
+        if (options?.raiseOnNack !== false && !ack?.ok)
+            throw new errors_1.MacpAckError(ack ?? {});
+        return ack;
+    }
+    /**
+     * Resume a suspended session via the `ResumeSession` control-plane RPC
+     * (proto 0.1.3+).
+     *
+     * Restores `SESSION_STATE_OPEN` and adds the banked TTL back to the session's
+     * absolute deadline. Restricted to the initiator and policy-delegated roles,
+     * mirroring {@link suspendSession}.
+     */
+    async resumeSession(sessionId, reason, options) {
+        const auth = this.requireAuth(options?.auth);
+        const response = await this.unary('ResumeSession', { sessionId, reason }, auth, options?.deadlineMs);
+        const ack = response.ack;
+        if (options?.raiseOnNack !== false && !ack?.ok)
+            throw new errors_1.MacpAckError(ack ?? {});
+        return ack;
+    }
     async getManifest(agentId = '', deadlineMs) {
         return this.unary('GetManifest', { agentId }, undefined, deadlineMs);
     }

package/dist/decision.d.ts

@@ -61,6 +61,16 @@ export declare class DecisionSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/decision.js

@@ -142,6 +142,26 @@ class DecisionSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/envelope.d.ts

@@ -1,4 +1,4 @@
-import type { CommitmentPayload, Envelope, ProgressPayload, Root, SessionStartPayload, SignalPayload } from './types';
+import type { CommitmentPayload, CommitmentRef, Envelope, ProgressPayload, Root, SessionStartPayload, SignalPayload } from './types';
 export declare function newSessionId(): string;
 export declare function newMessageId(): string;
 export declare function newCommitmentId(): string;
@@ -15,6 +15,15 @@ export declare function buildSessionStartPayload(input: {
     roots?: Root[];
 }): SessionStartPayload;
 export declare function inferOutcomePositive(action: string): boolean;
+/**
+ * Build a {@link CommitmentRef} pointing at a prior accepted commitment, for
+ * use as `buildCommitmentPayload({ supersedes })` (cross-session supersession,
+ * RFC-MACP-0001 §7.3). Parity with python-sdk `build_commitment_ref`.
+ */
+export declare function buildCommitmentRef(input: {
+    sessionId: string;
+    commitmentHash: string;
+}): CommitmentRef;
 export declare function buildCommitmentPayload(input: {
     action: string;
     authorityScope: string;
@@ -24,6 +33,12 @@ export declare function buildCommitmentPayload(input: {
     configurationVersion?: string;
     policyVersion?: string;
     outcomePositive?: boolean;
+    /**
+     * Cross-session supersession (RFC-MACP-0001 §7.3): reference to the prior
+     * commitment this one supersedes. Distinct from proposal-mode
+     * `supersedesProposalId`. Absent by default. Backward-compatible.
+     */
+    supersedes?: CommitmentRef;
 }): CommitmentPayload;
 export declare function buildRoot(uri: string, name?: string): Root;
 export declare function buildSignalPayload(input: {

package/dist/envelope.js

@@ -6,6 +6,7 @@ exports.newCommitmentId = newCommitmentId;
 exports.nowUnixMs = nowUnixMs;
 exports.buildSessionStartPayload = buildSessionStartPayload;
 exports.inferOutcomePositive = inferOutcomePositive;
+exports.buildCommitmentRef = buildCommitmentRef;
 exports.buildCommitmentPayload = buildCommitmentPayload;
 exports.buildRoot = buildRoot;
 exports.buildSignalPayload = buildSignalPayload;
@@ -47,8 +48,16 @@ function inferOutcomePositive(action) {
         return false;
     return true;
 }
+/**
+ * Build a {@link CommitmentRef} pointing at a prior accepted commitment, for
+ * use as `buildCommitmentPayload({ supersedes })` (cross-session supersession,
+ * RFC-MACP-0001 §7.3). Parity with python-sdk `build_commitment_ref`.
+ */
+function buildCommitmentRef(input) {
+    return { sessionId: input.sessionId, commitmentHash: input.commitmentHash };
+}
 function buildCommitmentPayload(input) {
-    return {
+    const payload = {
         commitmentId: input.commitmentId ?? newCommitmentId(),
         action: input.action,
         authorityScope: input.authorityScope,
@@ -58,6 +67,9 @@ function buildCommitmentPayload(input) {
         policyVersion: input.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION,
         outcomePositive: input.outcomePositive ?? inferOutcomePositive(input.action),
     };
+    if (input.supersedes)
+        payload.supersedes = input.supersedes;
+    return payload;
 }
 function buildRoot(uri, name = '') {
     return { uri, name };

package/dist/handoff.d.ts

@@ -61,6 +61,16 @@ export declare class HandoffSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/handoff.js

@@ -138,6 +138,26 @@ class HandoffSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/policy.js

@@ -10,6 +10,9 @@ function serializeCommitment(commitment) {
     return {
         authority: commitment?.authority ?? 'initiator_only',
         designated_roles: commitment?.designatedRoles ?? [],
+        // Parity with python-sdk `_commitment_dict`: emitted for every mode, not
+        // just decision, so policy JSON is byte-identical across SDKs.
+        require_vote_quorum: commitment?.requireVoteQuorum ?? false,
     };
 }
 function buildDecisionPolicy(policyId, description, rules) {
@@ -28,11 +31,7 @@ function buildDecisionPolicy(policyId, description, rules) {
             minimum_confidence: rules.evaluation?.minimumConfidence ?? 0,
             required_before_voting: rules.evaluation?.requiredBeforeVoting ?? false,
         },
-        commitment: {
-            authority: rules.commitment?.authority ?? 'initiator_only',
-            designated_roles: rules.commitment?.designatedRoles ?? [],
-            require_vote_quorum: rules.commitment?.requireVoteQuorum ?? false,
-        },
+        commitment: serializeCommitment(rules.commitment),
     };
     return {
         policyId,

package/dist/proposal.d.ts

@@ -65,6 +65,16 @@ export declare class ProposalSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/proposal.js

@@ -149,6 +149,26 @@ class ProposalSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/quorum.d.ts

@@ -61,6 +61,16 @@ export declare class QuorumSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/quorum.js

@@ -138,6 +138,26 @@ class QuorumSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/task.d.ts

@@ -69,6 +69,16 @@ export declare class TaskSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/task.js

@@ -160,6 +160,26 @@ class TaskSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/types.d.ts

@@ -19,13 +19,24 @@ export interface MacpErrorShape {
     messageId?: string;
     details?: Buffer;
 }
+/**
+ * Lifecycle state of a session. Mirrors the `SessionState` enum in
+ * `macp/v1/envelope.proto`.
+ *
+ * `SESSION_STATE_SUSPENDED` is a non-terminal pause (TTL is banked while
+ * suspended and restored on resume); `SESSION_STATE_CANCELLED` is the terminal
+ * state for an explicit `CancelSession` — distinct from `SESSION_STATE_EXPIRED`
+ * (TTL / deterministic runtime policy) so consumers can tell explicit
+ * cancellation from expiry.
+ */
+export type SessionState = 'SESSION_STATE_UNSPECIFIED' | 'SESSION_STATE_OPEN' | 'SESSION_STATE_RESOLVED' | 'SESSION_STATE_EXPIRED' | 'SESSION_STATE_SUSPENDED' | 'SESSION_STATE_CANCELLED';
 export interface Ack {
     ok?: boolean;
     duplicate?: boolean;
     messageId?: string;
     sessionId?: string;
     acceptedAtUnixMs?: string;
-    sessionState?: string;
+    sessionState?: SessionState;
     error?: MacpErrorShape;
 }
 export interface ParticipantActivity {
@@ -36,7 +47,7 @@ export interface ParticipantActivity {
 export interface SessionMetadata {
     sessionId?: string;
     mode?: string;
-    state?: string;
+    state?: SessionState;
     startedAtUnixMs?: string;
     expiresAtUnixMs?: string;
     modeVersion?: string;
@@ -99,6 +110,15 @@ export interface SessionStartPayload {
     extensions?: Record<string, Buffer>;
     roots?: Root[];
 }
+/**
+ * Reference to a specific accepted commitment, used for cross-session
+ * supersession (RFC-MACP-0001 §7.3). Mirrors `macp.v1.CommitmentRef`.
+ */
+export interface CommitmentRef {
+    sessionId: string;
+    /** Content hash of the superseded `CommitmentPayload`. */
+    commitmentHash: string;
+}
 export interface CommitmentPayload {
     commitmentId: string;
     action: string;
@@ -108,6 +128,13 @@ export interface CommitmentPayload {
     policyVersion?: string;
     configurationVersion: string;
     outcomePositive?: boolean;
+    /**
+     * Cross-session supersession (RFC-MACP-0001 §7.3): when present, this
+     * commitment supersedes a prior commitment identified by
+     * `{sessionId, commitmentHash}`. The superseding commitment lives in a NEW
+     * session — a RESOLVED session accepts no further messages.
+     */
+    supersedes?: CommitmentRef;
 }
 export interface SignalPayload {
     signalType: string;
@@ -264,7 +291,7 @@ export interface RegistryChanged {
 export interface RootsChanged {
     observedAtUnixMs: string;
 }
-export type SessionLifecycleEventType = 'EVENT_TYPE_UNSPECIFIED' | 'EVENT_TYPE_CREATED' | 'EVENT_TYPE_RESOLVED' | 'EVENT_TYPE_EXPIRED';
+export type SessionLifecycleEventType = 'EVENT_TYPE_UNSPECIFIED' | 'EVENT_TYPE_CREATED' | 'EVENT_TYPE_RESOLVED' | 'EVENT_TYPE_EXPIRED' | 'EVENT_TYPE_SUSPENDED' | 'EVENT_TYPE_RESUMED' | 'EVENT_TYPE_CANCELLED';
 export interface SessionLifecycleEvent {
     eventType: SessionLifecycleEventType;
     session: SessionMetadata;

package/dist/watchers.d.ts

@@ -1,6 +1,28 @@
 import type { AuthConfig } from './auth';
 import type { MacpClient } from './client';
-import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged, SessionLifecycleEvent } from './types';
+import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged, SessionLifecycleEvent, SessionLifecycleEventType } from './types';
+/**
+ * The lifecycle event types after which a session emits no further events.
+ * `EVENT_TYPE_CANCELLED` (proto 0.1.3) is terminal alongside `RESOLVED` and
+ * `EXPIRED`; `SUSPENDED` / `RESUMED` are non-terminal. Parity with python-sdk
+ * `SessionLifecycle.is_terminal`.
+ */
+export declare const TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES: readonly SessionLifecycleEventType[];
+type LifecycleEventOrType = SessionLifecycleEvent | SessionLifecycleEventType;
+/**
+ * Predicates over a {@link SessionLifecycleEvent} (or a bare
+ * {@link SessionLifecycleEventType}), mirroring python-sdk's `SessionLifecycle`
+ * properties so consumers can classify lifecycle events without re-deriving the
+ * proto enum strings. {@link isTerminalSessionLifecycleEvent} deliberately
+ * includes `EVENT_TYPE_CANCELLED`.
+ */
+export declare const isSessionCreated: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionResolved: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionExpired: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionCancelled: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionSuspended: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionResumed: (e: LifecycleEventOrType) => boolean;
+export declare const isTerminalSessionLifecycleEvent: (e: LifecycleEventOrType) => boolean;
 export declare class ModeRegistryWatcher {
     private readonly client;
     private readonly auth?;
@@ -67,3 +89,4 @@ export declare class SessionLifecycleWatcher {
      */
     nextEvent(): Promise<SessionLifecycleEvent>;
 }
+export {};

package/dist/watchers.js

@@ -1,7 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionLifecycleWatcher = exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = void 0;
+exports.SessionLifecycleWatcher = exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = exports.isTerminalSessionLifecycleEvent = exports.isSessionResumed = exports.isSessionSuspended = exports.isSessionCancelled = exports.isSessionExpired = exports.isSessionResolved = exports.isSessionCreated = exports.TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES = void 0;
 const logging_1 = require("./logging");
+/**
+ * The lifecycle event types after which a session emits no further events.
+ * `EVENT_TYPE_CANCELLED` (proto 0.1.3) is terminal alongside `RESOLVED` and
+ * `EXPIRED`; `SUSPENDED` / `RESUMED` are non-terminal. Parity with python-sdk
+ * `SessionLifecycle.is_terminal`.
+ */
+exports.TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES = [
+    'EVENT_TYPE_RESOLVED',
+    'EVENT_TYPE_EXPIRED',
+    'EVENT_TYPE_CANCELLED',
+];
+function lifecycleEventType(e) {
+    return typeof e === 'string' ? e : e.eventType;
+}
+/**
+ * Predicates over a {@link SessionLifecycleEvent} (or a bare
+ * {@link SessionLifecycleEventType}), mirroring python-sdk's `SessionLifecycle`
+ * properties so consumers can classify lifecycle events without re-deriving the
+ * proto enum strings. {@link isTerminalSessionLifecycleEvent} deliberately
+ * includes `EVENT_TYPE_CANCELLED`.
+ */
+const isSessionCreated = (e) => lifecycleEventType(e) === 'EVENT_TYPE_CREATED';
+exports.isSessionCreated = isSessionCreated;
+const isSessionResolved = (e) => lifecycleEventType(e) === 'EVENT_TYPE_RESOLVED';
+exports.isSessionResolved = isSessionResolved;
+const isSessionExpired = (e) => lifecycleEventType(e) === 'EVENT_TYPE_EXPIRED';
+exports.isSessionExpired = isSessionExpired;
+const isSessionCancelled = (e) => lifecycleEventType(e) === 'EVENT_TYPE_CANCELLED';
+exports.isSessionCancelled = isSessionCancelled;
+const isSessionSuspended = (e) => lifecycleEventType(e) === 'EVENT_TYPE_SUSPENDED';
+exports.isSessionSuspended = isSessionSuspended;
+const isSessionResumed = (e) => lifecycleEventType(e) === 'EVENT_TYPE_RESUMED';
+exports.isSessionResumed = isSessionResumed;
+const isTerminalSessionLifecycleEvent = (e) => exports.TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES.includes(lifecycleEventType(e));
+exports.isTerminalSessionLifecycleEvent = isTerminalSessionLifecycleEvent;
 function serverStreamToAsyncGenerator(stream) {
     const queue = [];
     let resolve = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
-    "@multiagentcoordinationprotocol/proto": "^0.1.2",
+    "@multiagentcoordinationprotocol/proto": "^0.1.3",
     "protobufjs": "^8.0.0"
   },
   "devDependencies": {