macp-sdk-typescript 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.14.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.13.0...v0.14.0) (2026-10-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* **agent:** encodeExtensions() (src/agent/runner.ts) no longer JSON-stringifies a session_start.extensions value. A string value is now base64-decoded (falling back to raw UTF-8 if it isn't valid base64); a number, boolean, plain object, array, or null value now throws instead of being silently JSON-encoded, as does a present-but-non-object extensions map itself. Buffer/Uint8Array values are unaffected. This reverses the UTF-8-JSON-encoding behavior documented in the 0.2.3 (SDK-TS-1) CHANGELOG entry, which silently put wire bytes on the connection that a conforming peer cannot decode.
+* **projections:** ProposalRecord.status's type no longer accepts 'accepted'. A TypeScript consumer comparing status === 'accepted' or switching on it now gets a compile-time TS2367/TS2678/TS2322 instead of silently-dead code; a plain-JS (or `as any`-cast) caller sees no behavior change, since the comparison always evaluated false.
+
+### Bug Fixes
+
+* **agent:** encodeExtensions() base64-decodes extensions values ([#149](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/149)) ([72c6ea4](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/72c6ea484e1dd5e75dbfc0bd12cbed787eeeacbd))
+* **projections:** ProposalRecord.status no longer accepts 'accepted' ([#147](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/147)) ([c5142d7](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/c5142d7c1ccd37b128549e512e9d5c6436899e30))
+
 ## [0.13.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.12.0...v0.13.0) (2026-09-30)
 
 
@@ -131,6 +144,30 @@ project uses [Semantic Versioning](https://semver.org/).
   still only fails server-side). A caller that genuinely needs one
   credential reused across multiple senders should use
   `Auth.bearer(token, senderHint)` (the legacy two-arg form) instead.
+* **projections:** `ProposalRecord.status`'s type no longer accepts
+  `'accepted'` (issue #146). No code path has ever assigned it — acceptance
+  is tracked separately via `accepts`/`isAccepted()`, since it's a
+  per-sender, supersedable relation (RFC-MACP-0008 §5 rule 5), not a
+  per-proposal fact a scalar field could hold. A TypeScript consumer
+  comparing `status === 'accepted'` or switching on it now gets a
+  compile-time `TS2367`/`TS2678`/`TS2322` instead of silently-dead code; a
+  plain-JS (or `as any`-cast) caller sees no behavior change, since the
+  comparison always evaluated `false`.
+* **agent:** `fromBootstrap()`'s `encodeExtensions()` now base64-decodes a
+  `session_start.extensions` string value (falling back to raw UTF-8 for a
+  non-base64 string), instead of `JSON.stringify`-ing it, per RFC-MACP-0001
+  §10.3 (a protobuf `bytes` field's canonical JSON representation is
+  base64) — the wire-level `extensions` map is `map<string, bytes>` (issue
+  #139). This reverses the UTF-8-JSON-encoding behavior documented at the
+  `0.2.3` entry above (SDK-TS-1): that release's choice silently put wire
+  bytes on the connection that a conforming peer (including this SDK's own
+  `macp-sdk-python` counterpart) cannot decode, even for the canonical
+  example value. A number, boolean, plain object, array, or `null`
+  extension value — previously silently JSON-encoded — now throws at
+  bootstrap construction instead, naming the offending key; so does a
+  present-but-non-object `extensions` map itself. `Buffer`/`Uint8Array`
+  values are unaffected (same passthrough as before, for TS-only
+  in-process callers — never reachable via a JSON bootstrap file).
 
 ### Features
 
@@ -191,6 +228,12 @@ project uses [Semantic Versioning](https://semver.org/).
   sites. `DecisionProjection`'s late-`Vote`-after-`Commitment` site remains
   the one still-open, undecided case (per #128's own explicit scoping) —
   unaffected by this change.
+- **`encodeExtensions()` is now exported from `macp-sdk-typescript/agent`**
+  (issue #139), so a caller constructing a bootstrap `extensions` map
+  programmatically can validate/encode a value the same way
+  `fromBootstrap()` does, and so it's directly unit-testable (a
+  `Buffer`/`Uint8Array` value can't round-trip through a JSON bootstrap
+  file otherwise).
 
 ### Changed
 
@@ -466,6 +509,11 @@ project uses [Semantic Versioning](https://semver.org/).
   site — `taskId`, `title`, `requestId`, `proposalId`, `option`, `handoffId`,
   `targetParticipant`, `modeVersion`, `configurationVersion` — is unaffected
   and still rejects an empty value.
+- **`ProposalRecord.status`'s declared type no longer lies about
+  `'accepted'`** (issue #146). The union included `'accepted'` since this
+  type was first written, but nothing has ever assigned it — see the
+  `### ⚠ BREAKING CHANGES` entry above for why, and why that correction is a
+  breaking (not purely additive) change.
 
 ### Documentation
 

package/dist/agent/runner.d.ts

@@ -24,7 +24,7 @@ export interface BootstrapPayload {
             policy_version?: string;
             context?: Record<string, unknown>;
             context_id?: string;
-            extensions?: Record<string, unknown>;
+            extensions?: Record<string, string | Buffer | Uint8Array>;
             roots?: Array<{
                 uri: string;
                 name?: string;
@@ -50,3 +50,25 @@ export interface BootstrapPayload {
     };
 }
 export declare function fromBootstrap(bootstrapPath?: string): Participant;
+/**
+ * Coerce a bootstrap `session_start.extensions` map into the
+ * `Record<string, Buffer>` form the SessionStart envelope expects
+ * (`map<string, bytes>` on the wire).
+ *
+ * Per RFC-MACP-0001 §10.3, a protobuf `bytes` field's canonical JSON
+ * representation is a base64 string, so a `string` value is base64-decoded
+ * first (strict shape check via `BASE64_PATTERN`, not Node's lenient
+ * decoder); a string that isn't valid base64 falls back to raw UTF-8 bytes.
+ * This base64-first heuristic — and the resulting ambiguity for a plain
+ * string that happens to also be valid base64 — mirrors
+ * `macp-sdk-python`'s `_decode_extensions` on purpose, to stay
+ * byte-for-byte interoperable; it is a known, tracked wart, not fixed here.
+ * `Buffer`/`Uint8Array` values pass through unchanged, for TS-only
+ * in-process callers that already hold raw bytes (never reachable via a
+ * JSON bootstrap file). Anything else — including the `extensions`
+ * container itself being a non-object (string/number/boolean/array) —
+ * throws, naming the offending key and/or type, so a malformed bootstrap
+ * fails loudly at construction instead of silently corrupting wire bytes a
+ * peer can't decode (issue #139).
+ */
+export declare function encodeExtensions(extensions: Record<string, string | Buffer | Uint8Array> | undefined): Record<string, Buffer> | undefined;

package/dist/agent/runner.js

@@ -34,11 +34,13 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromBootstrap = fromBootstrap;
+exports.encodeExtensions = encodeExtensions;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const auth_1 = require("../auth");
 const client_1 = require("../client");
 const constants_1 = require("../constants");
+const logging_1 = require("../logging");
 const participant_1 = require("./participant");
 function fromBootstrap(bootstrapPath) {
     const resolvedPath = bootstrapPath ?? process.env.MACP_BOOTSTRAP_FILE;
@@ -111,17 +113,53 @@ function fromBootstrap(bootstrapPath) {
     };
     return new participant_1.Participant(config);
 }
+// Matches a syntactically valid base64 string (correct alphabet, correct
+// padding) — a cheap stand-in for Python's `base64.b64decode(value,
+// validate=True)` so a plainly non-base64 string (e.g. "pack:example-001")
+// is rejected up front rather than silently mis-decoded by Node's lenient
+// `Buffer.from(str, 'base64')`, which ignores invalid characters instead of
+// raising. Matches the empty string too (decodes to an empty buffer either
+// way, so which branch handles it is immaterial).
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+function tryDecodeBase64(value) {
+    if (!BASE64_PATTERN.test(value))
+        return undefined;
+    return Buffer.from(value, 'base64');
+}
+function describeExtensionsValueType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
 /**
- * Serialise a JSON-native extensions map (as delivered in the bootstrap
- * payload) into the `Record<string, Buffer>` form the SessionStart envelope
- * expects. Each value is encoded as UTF-8 JSON so arbitrary structures
- * round-trip through the protobuf `bytes` field. `Buffer` / `Uint8Array`
- * values are passed through untouched so callers that already hold raw bytes
- * don't pay a double-encode.
+ * Coerce a bootstrap `session_start.extensions` map into the
+ * `Record<string, Buffer>` form the SessionStart envelope expects
+ * (`map<string, bytes>` on the wire).
+ *
+ * Per RFC-MACP-0001 §10.3, a protobuf `bytes` field's canonical JSON
+ * representation is a base64 string, so a `string` value is base64-decoded
+ * first (strict shape check via `BASE64_PATTERN`, not Node's lenient
+ * decoder); a string that isn't valid base64 falls back to raw UTF-8 bytes.
+ * This base64-first heuristic — and the resulting ambiguity for a plain
+ * string that happens to also be valid base64 — mirrors
+ * `macp-sdk-python`'s `_decode_extensions` on purpose, to stay
+ * byte-for-byte interoperable; it is a known, tracked wart, not fixed here.
+ * `Buffer`/`Uint8Array` values pass through unchanged, for TS-only
+ * in-process callers that already hold raw bytes (never reachable via a
+ * JSON bootstrap file). Anything else — including the `extensions`
+ * container itself being a non-object (string/number/boolean/array) —
+ * throws, naming the offending key and/or type, so a malformed bootstrap
+ * fails loudly at construction instead of silently corrupting wire bytes a
+ * peer can't decode (issue #139).
  */
 function encodeExtensions(extensions) {
-    if (!extensions)
+    if (extensions === undefined || extensions === null)
         return undefined;
+    if (typeof extensions !== 'object' || Array.isArray(extensions)) {
+        throw new Error(`bootstrap session_start.extensions must be an object, got ${describeExtensionsValueType(extensions)}`);
+    }
     const out = {};
     for (const [key, value] of Object.entries(extensions)) {
         if (Buffer.isBuffer(value)) {
@@ -130,8 +168,19 @@ function encodeExtensions(extensions) {
         else if (value instanceof Uint8Array) {
             out[key] = Buffer.from(value);
         }
+        else if (typeof value === 'string') {
+            const decoded = tryDecodeBase64(value);
+            if (decoded !== undefined) {
+                logging_1.logger.debug(`[fromBootstrap] extensions["${key}"] decoded as base64`);
+                out[key] = decoded;
+            }
+            else {
+                logging_1.logger.debug(`[fromBootstrap] extensions["${key}"] is not valid base64; falling back to raw UTF-8`);
+                out[key] = Buffer.from(value, 'utf8');
+            }
+        }
         else {
-            out[key] = Buffer.from(JSON.stringify(value), 'utf8');
+            throw new Error(`bootstrap extensions["${key}"] must be a base64-encoded string (or Buffer/Uint8Array), got ${describeExtensionsValueType(value)}`);
         }
     }
     return out;

package/dist/projections/base.d.ts

@@ -14,9 +14,12 @@ export type ProjectionAnomalyKind = 'duplicate_vote' | 'duplicate_ballot' | 'dup
  * this proposal (RFC-MACP-0007 §5.3), or a second distinct ballot across
  * `Approve`/`Reject`/`Abstain` from this sender for this request
  * (RFC-MACP-0011 §5 rule 3), was observed and discarded — the first stands.
- * (RFC-MACP-0011 §5 rule 3 caps *how many* ballots and is silent on *which of
- * two* stands; first-ballot-wins here is parity with RFC-MACP-0007 §5.3 plus
- * runtime-enforced behaviour.)
+ * (RFC-MACP-0011 §5 rule 3 states "the first accepted ballot stands"
+ * directly, since the rule-3 hardening in spec PR
+ * multiagentcoordinationprotocol#85 — before that, this SDK's
+ * first-ballot-wins behaviour was an inference from parity with
+ * RFC-MACP-0007 §5.3 plus runtime-enforced behaviour, not a direct
+ * RFC-0011 citation.)
  *
  * **Deliberately narrow claim — do not overclaim "this transcript violates
  * the spec".** A projection cannot tell a genuinely non-conforming source

package/dist/projections/proposal.d.ts

@@ -8,7 +8,24 @@ export interface ProposalRecord {
     tags?: string[];
     sender: string;
     supersedes?: string;
-    status: 'open' | 'accepted' | 'rejected' | 'withdrawn';
+    /**
+     * Reachable values only (issue #146). An `Accept` is recorded on the
+     * projection's `accepts` list (and surfaced via `acceptedProposal()` /
+     * `isAccepted()`), never on this field — no code path assigns `'accepted'`
+     * here. A non-terminal `Reject` likewise leaves this `'open'`; only a
+     * terminal `Reject` sets `'rejected'`.
+     *
+     * That is by design, not an omission: acceptance is a per-sender,
+     * supersedable relation (RFC-MACP-0008 §5 rule 5), not a per-proposal
+     * fact, so a scalar field here cannot hold it — "alice accepts p2 while
+     * bob still accepts p1" is a legal state. This mirrors the runtime, whose
+     * `ProposalDisposition` is `{Live, Withdrawn}` with acceptance in a
+     * separate `accepts` map, and `macp-sdk-python`'s own `status: str`
+     * (documented the same way after its issue #112). `task.ts`/`handoff.ts`
+     * do set `'accepted'`-equivalent statuses because their acceptance is one
+     * actor claiming one slot — this mode's isn't. See `docs/modes/proposal.md`.
+     */
+    status: 'open' | 'rejected' | 'withdrawn';
 }
 export interface ProposalAcceptRecord {
     proposalId: string;

package/dist/projections/quorum.js

@@ -54,21 +54,24 @@ class QuorumProjection extends base_1.BaseProjection {
         const senderMap = this.ballots.get(requestId) ?? new Map();
         const kept = senderMap.get(envelope.sender);
         if (kept !== undefined) {
-            // RFC-MACP-0011 §5 rule 3 (`:67`): participation is MAY (a participant need
-            // not cast a ballot), but the cap of one ballot per participant ACROSS
-            // Approve, Reject, and Abstain is enforced under §5's opening sentence,
-            // "Implementations MUST enforce the following:" (`:63`). Do NOT phrase this
-            // as "a participant MUST cast at most one ballot" — RFC-0011 puts the MUST
-            // on the implementation, not the participant (contrast RFC-MACP-0007 §5.3,
-            // which puts it directly on the participant; same obligation, different
-            // addressee). A later ballot of a *different* type is still a duplicate,
-            // not a change of vote, so this guard is keyed on the sender ALONE within
-            // the request — never on sender + vote. macp-runtime enforces this
-            // identically in all three arms (quorum.rs:164/184/204).
-            // Keeping the sender's FIRST ballot (rather than the last) is not stated
-            // by RFC-0011 either; it is parity with RFC-MACP-0007 §5 item 3's
-            // explicit first-stands rule for `Vote`, plus macp-runtime's enforced
-            // first-wins behaviour.
+            // RFC-MACP-0011 §5 rule 3 (`:69`, hardened by spec PR
+            // multiagentcoordinationprotocol#85): "Each eligible participant MUST
+            // cast at most one ballot per request_id... A runtime MUST reject a
+            // second ballot from the same sender for the same request_id,
+            // regardless of the type of either ballot; the first accepted ballot
+            // stands." Participation itself is still MAY (a participant need not
+            // ballot at all) — only the one-per-participant cap and first-wins
+            // outcome are MUST. A later ballot of a *different* type is still a
+            // duplicate, not a change of vote, so this guard is keyed on the
+            // sender ALONE within the request — never on sender + vote.
+            // macp-runtime enforces this identically in all three arms
+            // (quorum.rs:164/184/204).
+            //
+            // Keeping the sender's FIRST ballot is now a direct rule-3 citation
+            // (above), not an inference — before PR #85 hardened the rule, this
+            // comment relied on parity with RFC-MACP-0007 §5 item 3's first-stands
+            // rule for `Vote` plus macp-runtime's observed behavior, since RFC-0011
+            // capped *how many* ballots without yet stating *which* stands.
             this.recordAnomaly({
                 kind: 'duplicate_ballot',
                 mode: envelope.mode,

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.13.0";
+export declare const VERSION = "0.14.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.13.0'; // x-release-please-version
+exports.VERSION = '0.14.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",