macp-sdk-typescript 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.19.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.18.0...v0.19.0) (2026-10-26)
+
+
+### Features
+
+* capability-gated whatIfReplay and HISTORY_UNAVAILABLE (RFC-MACP-0012 §8.1) ([c5bc5cf](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/c5bc5cf6d8206c30f5d69f6fde44800e8d294fa6))
+* **claude-agent-sdk:** Claude Agent SDK subagents reach a binding MACP decision (W3.5) ([573bf33](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/573bf335d433ad13bcb5668d1563b67494df4442))
+
 ## [0.18.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.17.1...v0.18.0) (2026-10-25)
 
 

package/README.md

@@ -72,7 +72,7 @@ client.close();
 
 The SDK uses a **three-layer** design:
 
-- **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`).
+- **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`, and `whatIfReplay` where the runtime advertises it), 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.
 
@@ -335,6 +335,17 @@ server via `fromBootstrap()`; for the manual path use
 See [`docs/api/cancel-callback.md`](docs/api/cancel-callback.md) and
 [`examples/cancel-callback.ts`](examples/cancel-callback.ts).
 
+## Framework Integrations
+
+Framework adapters live under [`integrations/`](integrations/). Each is a separate npm package
+with its own version and release tag.
+
+| Framework | Package | |
+| --- | --- | --- |
+| LangGraph | [`@multiagentcoordinationprotocol/langgraph`](integrations/langgraph/) | `MacpConsensusNode`: a graph node whose participants evaluate and vote through a Decision or Quorum session and write the commitment into graph state |
+| Claude Agent SDK | [`@multiagentcoordinationprotocol/claude-agent-sdk`](integrations/claude-agent-sdk/) | `claudeEvaluator` runs a Claude agent as a participant; `macpConsensusServer` gives a lead agent an `mcp__macp__consensus` tool whose subagents evaluate and vote, returning the commitment |
+| OpenAI Agents SDK | planned | |
+
 ## Authentication
 
 ```typescript

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import * as grpc from '@grpc/grpc-js';
 import { type AuthConfig } from './auth';
 import { ProtoRegistry } from './proto-registry';
-import type { Ack, AgentManifest, Envelope, InitializeResult, ModeDescriptor, PolicyDescriptor, SessionMetadata, Root } from './types';
+import type { Ack, AgentManifest, Envelope, InitializeResult, ModeDescriptor, PolicyDescriptor, SessionMetadata, Root, WhatIfReplayResult } from './types';
 interface MacpClientOptions {
     address: string;
     /**
@@ -99,6 +99,10 @@ export declare class MacpClient {
     private readonly defaultDeadlineMs?;
     private readonly clientName;
     private readonly clientVersion;
+    /** The last {@link initialize} result; {@link whatIfReplay} reads its capabilities. */
+    private initializeResult?;
+    /** The runtime's capabilities from the last {@link initialize}; `undefined` before one. */
+    get serverCapabilities(): Record<string, unknown> | undefined;
     constructor(options: MacpClientOptions);
     private requireAuth;
     private metadata;
@@ -226,6 +230,25 @@ export declare class MacpClient {
         auth?: AuthConfig;
         deadlineMs?: number;
     }): Promise<PolicyDescriptor[]>;
+    /**
+     * Replay a session's accepted history under a candidate policy and report how
+     * the outcome would differ (RFC-MACP-0012 §8.1). Read-only and advisory: the
+     * session, its history and the policy registry are untouched, and the
+     * candidate is never registered.
+     *
+     * The RPC is optional, so this checks `capabilities.policyRegistry.whatIfReplay`
+     * from {@link initialize} first (calling it once if this client hasn't) and
+     * throws {@link MacpSdkError} without sending anything when the runtime
+     * doesn't advertise it. Runtime refusals arrive as {@link MacpTransportError}
+     * with `macpErrorCode` set: `SESSION_NOT_FOUND`, `FORBIDDEN` (authorized as
+     * {@link getSession}), `INVALID_POLICY_DEFINITION` (the candidate fails
+     * RegisterPolicy admission, or its mode is neither the session's nor `*`),
+     * `HISTORY_UNAVAILABLE` (history compacted), `INTERNAL_ERROR`.
+     */
+    whatIfReplay(sessionId: string, candidate: PolicyDescriptor, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<WhatIfReplayResult>;
     /**
      * Fetch a single page of sessions (proto ≥ 0.1.6). `pageSize: 0` (or absent)
      * lets the server choose the page size; the server MAY cap it. Callers MUST

package/dist/client.js

@@ -276,6 +276,12 @@ class MacpClient {
     defaultDeadlineMs;
     clientName;
     clientVersion;
+    /** The last {@link initialize} result; {@link whatIfReplay} reads its capabilities. */
+    initializeResult;
+    /** The runtime's capabilities from the last {@link initialize}; `undefined` before one. */
+    get serverCapabilities() {
+        return this.initializeResult?.capabilities;
+    }
     constructor(options) {
         this.auth = options.auth;
         this.secure = options.secure ?? true;
@@ -360,7 +366,7 @@ class MacpClient {
         });
     }
     async initialize(deadlineMs) {
-        return this.unary('Initialize', {
+        const result = await this.unary('Initialize', {
             supportedProtocolVersions: ['1.0'],
             clientInfo: {
                 name: this.clientName,
@@ -380,6 +386,8 @@ class MacpClient {
                 experimental: { features: {} },
             },
         }, undefined, deadlineMs);
+        this.initializeResult = result;
+        return result;
     }
     async send(envelope, options) {
         const auth = this.requireAuth(options?.auth);
@@ -513,6 +521,40 @@ class MacpClient {
         const res = await this.unary('ListPolicies', { mode: mode || '' }, auth, options?.deadlineMs);
         return res.descriptors || [];
     }
+    /**
+     * Replay a session's accepted history under a candidate policy and report how
+     * the outcome would differ (RFC-MACP-0012 §8.1). Read-only and advisory: the
+     * session, its history and the policy registry are untouched, and the
+     * candidate is never registered.
+     *
+     * The RPC is optional, so this checks `capabilities.policyRegistry.whatIfReplay`
+     * from {@link initialize} first (calling it once if this client hasn't) and
+     * throws {@link MacpSdkError} without sending anything when the runtime
+     * doesn't advertise it. Runtime refusals arrive as {@link MacpTransportError}
+     * with `macpErrorCode` set: `SESSION_NOT_FOUND`, `FORBIDDEN` (authorized as
+     * {@link getSession}), `INVALID_POLICY_DEFINITION` (the candidate fails
+     * RegisterPolicy admission, or its mode is neither the session's nor `*`),
+     * `HISTORY_UNAVAILABLE` (history compacted), `INTERNAL_ERROR`.
+     */
+    async whatIfReplay(sessionId, candidate, options) {
+        const auth = this.requireAuth(options?.auth);
+        const capabilities = this.serverCapabilities ?? (await this.initialize(options?.deadlineMs)).capabilities;
+        const policyRegistry = capabilities?.policyRegistry;
+        if (!policyRegistry?.whatIfReplay) {
+            throw new errors_1.MacpSdkError('this runtime does not advertise capabilities.policyRegistry.whatIfReplay; ' +
+                'WhatIfReplay is optional and a client MUST NOT call it otherwise (RFC-MACP-0012 §8.1)');
+        }
+        const res = await this.unary('WhatIfReplay', { sessionId, candidate }, auth, options?.deadlineMs);
+        // proto3 `optional` decodes with a synthetic oneof discriminator; an unset
+        // first_divergence is absent, never "0" (index 0 is the SessionStart).
+        const result = {
+            ...res,
+            denials: res.denials ?? [],
+            entries: res.entries ?? [],
+        };
+        delete result._firstDivergence;
+        return result;
+    }
     /**
      * Fetch a single page of sessions (proto ≥ 0.1.6). `pageSize: 0` (or absent)
      * lets the server choose the page size; the server MAY cap it. Callers MUST

package/dist/constants.d.ts

@@ -37,6 +37,11 @@ export declare const INVALID_REQUEST = "INVALID_REQUEST";
 export declare const STREAM_LAGGED = "STREAM_LAGGED";
 /** GetManifest for an agent this runtime does not host — NOT_FOUND. */
 export declare const AGENT_NOT_FOUND = "AGENT_NOT_FOUND";
+/**
+ * WhatIfReplay on a session whose full accepted history the runtime no longer
+ * holds (e.g. compacted when it ended) — FAILED_PRECONDITION. RFC-MACP-0012 §8.1.
+ */
+export declare const HISTORY_UNAVAILABLE = "HISTORY_UNAVAILABLE";
 export declare const DENY_VETO = "veto";
 export declare const DENY_VETO_HOLD = "veto_hold";
 export declare const DENY_QUORUM_NOT_MET = "quorum_not_met";

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_DENY_CODES = exports.DENY_UNSPECIFIED = exports.DENY_INVALID_RULES = exports.DENY_UNSUPPORTED_SCHEMA_VERSION = exports.DENY_REASSIGNMENT_NOT_ALLOWED = exports.DENY_OUTPUT_REQUIRED = exports.DENY_CRITERION_NOT_MET = exports.DENY_DECLINE_NOT_BACKED = exports.DENY_DECLINE_OVER_APPROVAL = exports.DENY_NO_VOTES = exports.DENY_EVALUATION_REQUIRED = exports.DENY_CONFIDENCE_BELOW_MINIMUM = exports.DENY_THRESHOLD_NOT_MET = exports.DENY_QUORUM_NOT_MET = exports.DENY_VETO_HOLD = exports.DENY_VETO = exports.AGENT_NOT_FOUND = exports.STREAM_LAGGED = exports.INVALID_REQUEST = exports.REGISTRY_READ_ONLY = exports.INVALID_POLICY_DEFINITION = exports.UNKNOWN_POLICY_VERSION = exports.INVALID_SESSION_ID = exports.POLICY_DENIED = exports.INTERNAL_ERROR = exports.RATE_LIMITED = exports.PAYLOAD_TOO_LARGE = exports.DUPLICATE_MESSAGE = exports.UNAUTHENTICATED = exports.FORBIDDEN = exports.MODE_NOT_SUPPORTED = exports.SESSION_NOT_OPEN = exports.SESSION_NOT_FOUND = exports.SESSION_ALREADY_EXISTS = exports.INVALID_ENVELOPE = exports.UNSUPPORTED_PROTOCOL_VERSION = exports.STANDARD_MODES = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
+exports.KNOWN_DENY_CODES = exports.DENY_UNSPECIFIED = exports.DENY_INVALID_RULES = exports.DENY_UNSUPPORTED_SCHEMA_VERSION = exports.DENY_REASSIGNMENT_NOT_ALLOWED = exports.DENY_OUTPUT_REQUIRED = exports.DENY_CRITERION_NOT_MET = exports.DENY_DECLINE_NOT_BACKED = exports.DENY_DECLINE_OVER_APPROVAL = exports.DENY_NO_VOTES = exports.DENY_EVALUATION_REQUIRED = exports.DENY_CONFIDENCE_BELOW_MINIMUM = exports.DENY_THRESHOLD_NOT_MET = exports.DENY_QUORUM_NOT_MET = exports.DENY_VETO_HOLD = exports.DENY_VETO = exports.HISTORY_UNAVAILABLE = exports.AGENT_NOT_FOUND = exports.STREAM_LAGGED = exports.INVALID_REQUEST = exports.REGISTRY_READ_ONLY = exports.INVALID_POLICY_DEFINITION = exports.UNKNOWN_POLICY_VERSION = exports.INVALID_SESSION_ID = exports.POLICY_DENIED = exports.INTERNAL_ERROR = exports.RATE_LIMITED = exports.PAYLOAD_TOO_LARGE = exports.DUPLICATE_MESSAGE = exports.UNAUTHENTICATED = exports.FORBIDDEN = exports.MODE_NOT_SUPPORTED = exports.SESSION_NOT_OPEN = exports.SESSION_NOT_FOUND = exports.SESSION_ALREADY_EXISTS = exports.INVALID_ENVELOPE = exports.UNSUPPORTED_PROTOCOL_VERSION = exports.STANDARD_MODES = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
 exports.MACP_VERSION = '1.0';
 exports.DEFAULT_MODE_VERSION = '1.0.0';
 exports.DEFAULT_CONFIGURATION_VERSION = 'config.default';
@@ -44,6 +44,11 @@ exports.INVALID_REQUEST = 'INVALID_REQUEST';
 exports.STREAM_LAGGED = 'STREAM_LAGGED';
 /** GetManifest for an agent this runtime does not host — NOT_FOUND. */
 exports.AGENT_NOT_FOUND = 'AGENT_NOT_FOUND';
+/**
+ * WhatIfReplay on a session whose full accepted history the runtime no longer
+ * holds (e.g. compacted when it ended) — FAILED_PRECONDITION. RFC-MACP-0012 §8.1.
+ */
+exports.HISTORY_UNAVAILABLE = 'HISTORY_UNAVAILABLE';
 // Structured POLICY_DENIED denial codes (`PolicyDenial.code`, runtime ≥ 0.9.0;
 // RFC-MACP-0012 §6.2). Open set — names match python-sdk's exports.
 exports.DENY_VETO = 'veto';

package/dist/types.d.ts

@@ -100,6 +100,65 @@ export interface PolicyRegistryCapability {
      * admission, not this list, is authoritative. Runtime ≥ 0.9.0.
      */
     ruleExtensions?: string[];
+    /**
+     * The runtime implements the optional, read-only `WhatIfReplay` RPC
+     * (RFC-MACP-0012 §8.1); {@link MacpClient.whatIfReplay} refuses to call it
+     * otherwise. Proto ≥ 0.1.12.
+     */
+    whatIfReplay?: boolean;
+}
+/** How one replay handled one history entry (`macp.v1.WhatIfEntryOutcome`). */
+export interface WhatIfEntryOutcome {
+    kind: 'KIND_UNSPECIFIED' | 'KIND_APPLIED' | 'KIND_NOT_OPEN' | 'KIND_REFUSED' | 'KIND_NO_SESSION';
+    /** Session state after the entry, for `KIND_APPLIED`. */
+    state: string;
+    /** MACP error code, for `KIND_REFUSED`. */
+    errorCode: string;
+    /** For a `POLICY_DENIED` refusal, the §6.2 detail JSON; see {@link parseErrorDetails}. */
+    details: Buffer;
+}
+/** One accepted-history entry as both replays handled it. `historyIndex` is 0-based; the SessionStart is 0. */
+export interface WhatIfEntry {
+    historyIndex: string;
+    messageId: string;
+    messageType: string;
+    recorded: WhatIfEntryOutcome | null;
+    candidate: WhatIfEntryOutcome | null;
+}
+/** One replay's final outcome (`macp.v1.WhatIfOutcome`). */
+export interface WhatIfOutcome {
+    /** `SESSION_STATE_UNSPECIFIED` when the candidate refused the SessionStart. */
+    state: string;
+    /** The resolving Commitment's payload bytes; empty if unresolved. */
+    resolution: Buffer;
+    resolvedByHistoryIndex: string;
+    /** Empty if unresolved. */
+    resolvedByMessageId: string;
+    resolvedByMessageType: string;
+}
+/** A `POLICY_DENIED` the candidate produced; `details` as {@link WhatIfEntryOutcome.details}. */
+export interface WhatIfDenial {
+    historyIndex: string;
+    messageId: string;
+    details: Buffer;
+}
+/**
+ * `macp.v1.WhatIfReplayResponse`: a session's accepted history replayed under
+ * its bound policy (`recorded`) and under a candidate. Advisory, never binding.
+ * uint64 fields are decimal strings, as elsewhere in this client.
+ */
+export interface WhatIfReplayResult {
+    candidatePolicyId: string;
+    /** The policy the session is bound to (`policy.default` if none was named). */
+    recordedPolicyId: string;
+    recorded: WhatIfOutcome | null;
+    candidate: WhatIfOutcome | null;
+    /** First history index the two replays handled differently; absent when they agree throughout. */
+    firstDivergence?: string;
+    /** Every POLICY_DENIED the candidate produced, in history order. */
+    denials: WhatIfDenial[];
+    /** One entry per accepted-history entry, in history order. */
+    entries: WhatIfEntry[];
 }
 export interface InitializeResult {
     selectedProtocolVersion: string;

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.19.0";

package/dist/version.js

@@ -7,4 +7,4 @@ exports.VERSION = void 0;
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-exports.VERSION = '0.18.0'; // x-release-please-version
+exports.VERSION = '0.19.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -60,7 +60,7 @@
   "dependencies": {
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
-    "@multiagentcoordinationprotocol/proto": "^0.1.11",
+    "@multiagentcoordinationprotocol/proto": "^0.1.12",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
     "protobufjs": "^8.6.5"