macp-sdk-typescript 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.20.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.19.0...v0.20.0) (2026-10-26)
+
+
+### Features
+
+* runtime-issued decision receipts — getDecisionReceipt, getReceiptKeys, trustedKeysFromJwks (RFC-MACP-0013 §13) ([#210](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/210)) ([931d9e1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/931d9e13d7695a9f4659d0538e85dcb709eaeb20))
+
+## [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), `getDecisionReceipt`/`getReceiptKeys` where the runtime advertises receipts, 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
@@ -452,6 +463,29 @@ const result = verifyReceipt(receipt, { 'prod-2026': 'TDVzkxaSf6_Oxu7mmn5TbCkF80
 | `attestations[i]` | `valid`, `invalid`, `unknown_key` or `unsupported` (any other `alg`, and every `vendor` attestation)                                                                                           |
 | `verdict`         | `attested` (integrity holds and at least one attestation is valid), `integrity_only`, `unverified` (integrity fails, so attestations are not checked), or `refused` (unknown `receipt_format`) |
 
+To trust a published key set (a JWK Set, such as a runtime's `GetReceiptKeys` response; RFC-MACP-0013 §13), convert it with `trustedKeysFromJwks(jwks)`:
+
+```typescript
+import { trustedKeysFromJwks, verifyReceipt } from 'macp-sdk-typescript/receipt';
+
+const trustedKeys = trustedKeysFromJwks(jwks); // { 'example-1': 'TDVzkxaSf6_…' }
+verifyReceipt(receipt, trustedKeys).verdict; // 'attested'
+```
+
+It keeps only Ed25519 public keys (`kty` `OKP`, `crv` `Ed25519`) with a `kid` and an `x`, whose `alg` (if any) is `EdDSA` and `use` (if any) is `sig`. It drops a key that carries a private member (`d`, `k`, …) and any `kid` that more than one entry of the set claims, even when the other entry is a key it can't use (an EC key, say). It never throws: anything that isn't a key set gives `{}`. Deciding to trust the set is still up to you.
+
+### Fetching a runtime-issued receipt
+
+A runtime that advertises `capabilities.decisionReceipt.getDecisionReceipt` issues receipts itself (RFC-MACP-0013 §13). Fetch one for a resolved session, fetch the runtime's key set, and verify:
+
+```typescript
+const { receipt, raw } = await client.getDecisionReceipt(sessionId); // raw: the exact bytes served
+const jwks = await client.getReceiptKeys(); // { keys: [] } from an unsigned runtime
+verifyReceipt(receipt, trustedKeysFromJwks(jwks)).verdict; // 'attested', or 'integrity_only' if unsigned
+```
+
+Both methods throw `MacpSdkError` without sending anything when the runtime doesn't advertise the capability. A session the runtime can't issue a receipt for (not resolved yet, or resolved without a `CommitmentPayload`) gives `MacpTransportError` with `macpErrorCode` `RECEIPT_UNAVAILABLE`.
+
 If you hold the snake_case §3 projection (a receipt's `commitment`) instead of a `CommitmentPayload`, convert it with `commitmentFromProjection(projection)`.
 
 `verifyReceipt` never throws. `buildReceipt` throws `MacpSdkError` on a missing field, and when `commitmentWire` is not the wire encoding of the commitment. Signing is deterministic: the same inputs always produce the same receipt.

package/dist/client.d.ts

@@ -1,7 +1,8 @@
 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 { DecisionReceiptResult, ReceiptKeySet } from './receipt';
+import type { Ack, AgentManifest, Envelope, InitializeResult, ModeDescriptor, PolicyDescriptor, SessionMetadata, Root, WhatIfReplayResult } from './types';
 interface MacpClientOptions {
     address: string;
     /**
@@ -99,8 +100,21 @@ export declare class MacpClient {
     private readonly defaultDeadlineMs?;
     private readonly clientName;
     private readonly clientVersion;
+    /** The last {@link initialize} result; capability-gated RPCs read its capabilities. */
+    private initializeResult?;
+    /** An `Initialize` that {@link requireCapability} started and is still in flight. */
+    private pendingInit?;
+    /** The runtime's capabilities from the last {@link initialize}; `undefined` before one. */
+    get serverCapabilities(): Record<string, unknown> | undefined;
     constructor(options: MacpClientOptions);
     private requireAuth;
+    /**
+     * Throws {@link MacpSdkError}, without sending anything, unless
+     * `capabilities.<group>.<flag>` from {@link initialize} is `true`. Calls
+     * `Initialize` once if this client hasn't; concurrent first callers share
+     * that one in-flight call (and the first caller's deadline).
+     */
+    private requireCapability;
     private metadata;
     private deadline;
     private unary;
@@ -226,6 +240,64 @@ 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 the runtime-issued decision receipt for a resolved session
+     * (RFC-MACP-0013 §13). Returns the parsed `macp-receipt/1` object and `raw`,
+     * the exact JSON text the runtime served, which is stable across calls
+     * (§13 item 6), so it can be stored or forwarded byte for byte. Verify it
+     * with `verifyReceipt(receipt, trustedKeysFromJwks(await getReceiptKeys()))`;
+     * this method does not.
+     *
+     * The RPC is optional, so this checks
+     * `capabilities.decisionReceipt.getDecisionReceipt` 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. Authorized as {@link getSession}. Runtime refusals arrive as
+     * {@link MacpTransportError} with `macpErrorCode` set: `RECEIPT_UNAVAILABLE`
+     * (no receipt can be issued: not resolved yet, or resolved without a
+     * `CommitmentPayload`), `SESSION_NOT_FOUND`, `FORBIDDEN`,
+     * `INTERNAL_ERROR`. A `receipt_json` that isn't a JSON object throws
+     * {@link MacpSdkError}.
+     */
+    getDecisionReceipt(sessionId: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<DecisionReceiptResult>;
+    /**
+     * Fetch the JWK Set of public keys the runtime signs receipts with
+     * (RFC-MACP-0013 §13 item 8); an unsigned runtime returns `{keys: []}`. Pass
+     * it to `trustedKeysFromJwks` for the map `verifyReceipt` takes. Whether
+     * to trust these keys is the caller's decision.
+     *
+     * Gated on `capabilities.decisionReceipt.getDecisionReceipt` like
+     * {@link getDecisionReceipt}. Needs transport auth only, like
+     * {@link getManifest}: `auth` is optional and falls back to the client's.
+     * A `jwks_json` that isn't a JSON object with a `keys` array throws
+     * {@link MacpSdkError}.
+     */
+    getReceiptKeys(options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<ReceiptKeySet>;
     /**
      * 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,14 @@ class MacpClient {
     defaultDeadlineMs;
     clientName;
     clientVersion;
+    /** The last {@link initialize} result; capability-gated RPCs read its capabilities. */
+    initializeResult;
+    /** An `Initialize` that {@link requireCapability} started and is still in flight. */
+    pendingInit;
+    /** 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;
@@ -314,6 +322,23 @@ class MacpClient {
             throw new errors_1.MacpSdkError('this operation requires auth; pass auth= or configure client.auth');
         return selected;
     }
+    /**
+     * Throws {@link MacpSdkError}, without sending anything, unless
+     * `capabilities.<group>.<flag>` from {@link initialize} is `true`. Calls
+     * `Initialize` once if this client hasn't; concurrent first callers share
+     * that one in-flight call (and the first caller's deadline).
+     */
+    async requireCapability(group, flag, rpc, rfc, deadlineMs) {
+        const capabilities = this.serverCapabilities ??
+            (await (this.pendingInit ??= this.initialize(deadlineMs).finally(() => {
+                this.pendingInit = undefined;
+            }))).capabilities;
+        const advertised = capabilities?.[group];
+        if (advertised?.[flag] !== true) {
+            throw new errors_1.MacpSdkError(`this runtime does not advertise capabilities.${group}.${flag}; ` +
+                `${rpc} is optional and a client MUST NOT call it otherwise (${rfc})`);
+        }
+    }
     metadata(auth) {
         const selected = auth ?? this.auth;
         if (!selected)
@@ -360,7 +385,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 +405,8 @@ class MacpClient {
                 experimental: { features: {} },
             },
         }, undefined, deadlineMs);
+        this.initializeResult = result;
+        return result;
     }
     async send(envelope, options) {
         const auth = this.requireAuth(options?.auth);
@@ -513,6 +540,83 @@ 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);
+        await this.requireCapability('policyRegistry', 'whatIfReplay', 'WhatIfReplay', 'RFC-MACP-0012 §8.1', options?.deadlineMs);
+        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 the runtime-issued decision receipt for a resolved session
+     * (RFC-MACP-0013 §13). Returns the parsed `macp-receipt/1` object and `raw`,
+     * the exact JSON text the runtime served, which is stable across calls
+     * (§13 item 6), so it can be stored or forwarded byte for byte. Verify it
+     * with `verifyReceipt(receipt, trustedKeysFromJwks(await getReceiptKeys()))`;
+     * this method does not.
+     *
+     * The RPC is optional, so this checks
+     * `capabilities.decisionReceipt.getDecisionReceipt` 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. Authorized as {@link getSession}. Runtime refusals arrive as
+     * {@link MacpTransportError} with `macpErrorCode` set: `RECEIPT_UNAVAILABLE`
+     * (no receipt can be issued: not resolved yet, or resolved without a
+     * `CommitmentPayload`), `SESSION_NOT_FOUND`, `FORBIDDEN`,
+     * `INTERNAL_ERROR`. A `receipt_json` that isn't a JSON object throws
+     * {@link MacpSdkError}.
+     */
+    async getDecisionReceipt(sessionId, options) {
+        const auth = this.requireAuth(options?.auth);
+        await this.requireCapability('decisionReceipt', 'getDecisionReceipt', 'GetDecisionReceipt', 'RFC-MACP-0013 §13', options?.deadlineMs);
+        const res = await this.unary('GetDecisionReceipt', { sessionId }, auth, options?.deadlineMs);
+        const raw = res.receiptJson ?? '';
+        const receipt = parseJsonObject(raw, 'receipt_json');
+        return { receipt: receipt, raw };
+    }
+    /**
+     * Fetch the JWK Set of public keys the runtime signs receipts with
+     * (RFC-MACP-0013 §13 item 8); an unsigned runtime returns `{keys: []}`. Pass
+     * it to `trustedKeysFromJwks` for the map `verifyReceipt` takes. Whether
+     * to trust these keys is the caller's decision.
+     *
+     * Gated on `capabilities.decisionReceipt.getDecisionReceipt` like
+     * {@link getDecisionReceipt}. Needs transport auth only, like
+     * {@link getManifest}: `auth` is optional and falls back to the client's.
+     * A `jwks_json` that isn't a JSON object with a `keys` array throws
+     * {@link MacpSdkError}.
+     */
+    async getReceiptKeys(options) {
+        await this.requireCapability('decisionReceipt', 'getDecisionReceipt', 'GetReceiptKeys', 'RFC-MACP-0013 §13', options?.deadlineMs);
+        const res = await this.unary('GetReceiptKeys', {}, options?.auth, options?.deadlineMs);
+        const jwks = parseJsonObject(res.jwksJson ?? '', 'jwks_json');
+        if (!Array.isArray(jwks.keys)) {
+            throw new errors_1.MacpSdkError('runtime returned a jwks_json with no keys array');
+        }
+        return jwks;
+    }
     /**
      * 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
@@ -641,3 +745,17 @@ class MacpClient {
     }
 }
 exports.MacpClient = MacpClient;
+/** Parses runtime-served JSON text that must be an object, else throws {@link MacpSdkError}. */
+function parseJsonObject(text, field) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new errors_1.MacpSdkError(`runtime returned a ${field} that is not valid JSON: ${err.message}`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new errors_1.MacpSdkError(`runtime returned a ${field} that is not a JSON object`);
+    }
+    return value;
+}

package/dist/constants.d.ts

@@ -37,6 +37,18 @@ 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";
+/**
+ * GetDecisionReceipt named a session no receipt can be issued for: not
+ * RESOLVED, resolved without a `CommitmentPayload`, or issuance failed —
+ * FAILED_PRECONDITION. RFC-MACP-0013 §13. **Provisional** in the spec's error
+ * registry (not yet in the parity contract's permanent set).
+ */
+export declare const RECEIPT_UNAVAILABLE = "RECEIPT_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.RECEIPT_UNAVAILABLE = 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,18 @@ 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';
+/**
+ * GetDecisionReceipt named a session no receipt can be issued for: not
+ * RESOLVED, resolved without a `CommitmentPayload`, or issuance failed —
+ * FAILED_PRECONDITION. RFC-MACP-0013 §13. **Provisional** in the spec's error
+ * registry (not yet in the parity contract's permanent set).
+ */
+exports.RECEIPT_UNAVAILABLE = 'RECEIPT_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/index.d.ts

@@ -14,7 +14,7 @@ export * from './proposal';
 export * from './proto-registry';
 export * from './retry';
 export * from './quorum';
-export { RECEIPT_FORMAT, buildReceipt, commitmentFromProjection, verifyReceipt, type AttestationOutcome, type BuildReceiptOptions, type DecisionReceipt, type JwsAttestation, type ReceiptAttestation, type ReceiptCommitment, type ReceiptIntegrity, type ReceiptSigner, type ReceiptVerdict, type ReceiptVerification, type VendorAttestation, } from './receipt';
+export { RECEIPT_FORMAT, buildReceipt, commitmentFromProjection, trustedKeysFromJwks, verifyReceipt, type AttestationOutcome, type BuildReceiptOptions, type DecisionReceipt, type DecisionReceiptResult, type JwsAttestation, type ReceiptAttestation, type ReceiptCommitment, type ReceiptIntegrity, type ReceiptJwk, type ReceiptKeySet, type ReceiptSigner, type ReceiptVerdict, type ReceiptVerification, type VendorAttestation, } from './receipt';
 export * from './task';
 export * from './types';
 export * from './validation';

package/dist/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agent = exports.VERSION = exports.verifyReceipt = exports.commitmentFromProjection = exports.buildReceipt = exports.RECEIPT_FORMAT = exports.logger = exports.configureLogging = exports.verifyCommitmentHash = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
+exports.agent = exports.VERSION = exports.verifyReceipt = exports.trustedKeysFromJwks = exports.commitmentFromProjection = exports.buildReceipt = exports.RECEIPT_FORMAT = exports.logger = exports.configureLogging = exports.verifyCommitmentHash = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
 // Auth: export only the public constructors and types. The helpers
 // `validateAuth`, `authSender`, `assertSenderMatchesIdentity`, and
 // `metadataFromAuth` are SDK-internal — importable from the `./auth`
@@ -84,6 +84,7 @@ var receipt_1 = require("./receipt");
 Object.defineProperty(exports, "RECEIPT_FORMAT", { enumerable: true, get: function () { return receipt_1.RECEIPT_FORMAT; } });
 Object.defineProperty(exports, "buildReceipt", { enumerable: true, get: function () { return receipt_1.buildReceipt; } });
 Object.defineProperty(exports, "commitmentFromProjection", { enumerable: true, get: function () { return receipt_1.commitmentFromProjection; } });
+Object.defineProperty(exports, "trustedKeysFromJwks", { enumerable: true, get: function () { return receipt_1.trustedKeysFromJwks; } });
 Object.defineProperty(exports, "verifyReceipt", { enumerable: true, get: function () { return receipt_1.verifyReceipt; } });
 __exportStar(require("./task"), exports);
 __exportStar(require("./types"), exports);

package/dist/receipt.d.ts

@@ -49,6 +49,32 @@ export interface DecisionReceipt {
     issued_at: string;
     attestations: ReceiptAttestation[];
 }
+/**
+ * {@link MacpClient.getDecisionReceipt}'s result: the parsed receipt and the
+ * `receipt_json` text exactly as the runtime served it, so a caller can store
+ * the issued bytes unchanged (RFC-MACP-0013 §13 item 6 serves them
+ * byte-identical). `receipt` is parsed, not validated: {@link verifyReceipt}
+ * is the authority on whether it is a well-formed `macp-receipt/1`.
+ */
+export interface DecisionReceiptResult {
+    receipt: DecisionReceipt;
+    raw: string;
+}
+/** One JWK of a receipt key set (`schemas/json/macp-receipt-keys.schema.json`). */
+export interface ReceiptJwk {
+    kid: string;
+    kty: string;
+    crv?: string;
+    x?: string;
+    alg?: string;
+    use?: string;
+    [member: string]: unknown;
+}
+/** A JWK Set [RFC 7517] of receipt verification keys, as `GetReceiptKeys` returns it. */
+export interface ReceiptKeySet {
+    keys: ReceiptJwk[];
+    [member: string]: unknown;
+}
 /**
  * Signs a receipt with Ed25519: either a 32-byte private key seed, or a
  * callback that returns the 64-byte signature over `signingInput` (for a key
@@ -122,3 +148,19 @@ export declare function buildReceipt(commitment: CommitmentPayload, options: Bui
  * Never throws: malformed input yields an outcome, not an exception.
  */
 export declare function verifyReceipt(receipt: unknown, trustedKeys: Record<string, string>): ReceiptVerification;
+/**
+ * Turns a receipt key set (the JWK Set `GetReceiptKeys` returns, RFC-MACP-0013
+ * §13 item 8) into the `kid → x` map {@link verifyReceipt} takes. Choosing to
+ * trust the set is the caller's decision; this only converts it.
+ *
+ * A key is kept only if it is an Ed25519 public key (`kty` `OKP`, `crv`
+ * `Ed25519`) with a non-empty `kid` and `x`, an `alg` (if any) of `EdDSA`, a
+ * `use` (if any) of `sig`, and no private member (`d`, `p`, `q`, `dp`, `dq`,
+ * `qi`, `oth`, `k`): a key set that publishes private key material is
+ * misconfigured and is not trusted silently. A `kid` that more than one entry
+ * of the set claims is dropped entirely, even when the other entry is a key
+ * this function can't use (an EC key, say): item 8 makes kids unique across
+ * the whole set, so a repeated one leaves the set ambiguous about which key it
+ * names. Never throws: input that is not a key set yields `{}`.
+ */
+export declare function trustedKeysFromJwks(jwks: unknown): Record<string, string>;

package/dist/receipt.js

@@ -4,6 +4,7 @@ exports.RECEIPT_FORMAT = void 0;
 exports.commitmentFromProjection = commitmentFromProjection;
 exports.buildReceipt = buildReceipt;
 exports.verifyReceipt = verifyReceipt;
+exports.trustedKeysFromJwks = trustedKeysFromJwks;
 /**
  * RFC-MACP-0013 Appendix A decision receipts (`macp-receipt/1`).
  *
@@ -374,3 +375,54 @@ function verifyReceipt(receipt, trustedKeys) {
         verdict: outcomes.includes('valid') ? 'attested' : 'integrity_only',
     };
 }
+/** JWK private-key members (RFC 7518 §6); RFC-MACP-0013 §13 item 8 forbids them in a key set. */
+const PRIVATE_JWK_MEMBERS = ['d', 'p', 'q', 'dp', 'dq', 'qi', 'oth', 'k'];
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+/** An Ed25519 public verification key usable for an EdDSA `jws` attestation. */
+function usableEd25519Key(key) {
+    if (!isRecord(key))
+        return false;
+    if (key.kty !== 'OKP' || key.crv !== 'Ed25519')
+        return false;
+    if (!isNonEmptyString(key.kid) || !isNonEmptyString(key.x))
+        return false;
+    if (key.alg !== undefined && key.alg !== 'EdDSA')
+        return false;
+    if (key.use !== undefined && key.use !== 'sig')
+        return false;
+    return !PRIVATE_JWK_MEMBERS.some((m) => Object.prototype.hasOwnProperty.call(key, m));
+}
+/**
+ * Turns a receipt key set (the JWK Set `GetReceiptKeys` returns, RFC-MACP-0013
+ * §13 item 8) into the `kid → x` map {@link verifyReceipt} takes. Choosing to
+ * trust the set is the caller's decision; this only converts it.
+ *
+ * A key is kept only if it is an Ed25519 public key (`kty` `OKP`, `crv`
+ * `Ed25519`) with a non-empty `kid` and `x`, an `alg` (if any) of `EdDSA`, a
+ * `use` (if any) of `sig`, and no private member (`d`, `p`, `q`, `dp`, `dq`,
+ * `qi`, `oth`, `k`): a key set that publishes private key material is
+ * misconfigured and is not trusted silently. A `kid` that more than one entry
+ * of the set claims is dropped entirely, even when the other entry is a key
+ * this function can't use (an EC key, say): item 8 makes kids unique across
+ * the whole set, so a repeated one leaves the set ambiguous about which key it
+ * names. Never throws: input that is not a key set yields `{}`.
+ */
+function trustedKeysFromJwks(jwks) {
+    const result = {};
+    if (!isRecord(jwks) || !Array.isArray(jwks.keys))
+        return result;
+    // Count every entry's string kid, usable or not, before keeping any.
+    const claims = new Map();
+    for (const key of jwks.keys) {
+        if (isRecord(key) && typeof key.kid === 'string')
+            claims.set(key.kid, (claims.get(key.kid) ?? 0) + 1);
+    }
+    for (const key of jwks.keys) {
+        if (!usableEd25519Key(key) || claims.get(key.kid) !== 1)
+            continue;
+        // defineProperty, not assignment: a kid of "__proto__" must become an own
+        // key (which verifyReceipt's hasOwnProperty lookup finds), not a prototype.
+        Object.defineProperty(result, key.kid, { value: key.x, enumerable: true, writable: true, configurable: true });
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -100,6 +100,82 @@ 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;
+}
+/**
+ * `capabilities.decisionReceipt` (`macp.v1.DecisionReceiptCapability`, proto
+ * ≥ 0.1.13): optional runtime-issued decision receipts (RFC-MACP-0013 §13).
+ */
+export interface DecisionReceiptCapability {
+    /**
+     * The runtime implements `GetDecisionReceipt` and `GetReceiptKeys`;
+     * {@link MacpClient.getDecisionReceipt} and {@link MacpClient.getReceiptKeys}
+     * refuse to call them otherwise.
+     */
+    getDecisionReceipt?: boolean;
+    /**
+     * Every receipt issued from now on carries at least one EdDSA `jws`
+     * attestation. Says nothing about receipts issued earlier.
+     */
+    signed?: 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.20.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.20.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.18.0",
+  "version": "0.20.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.13",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
     "protobufjs": "^8.6.5"