macp-sdk-typescript 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,471 @@ 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.12.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.11.0...v0.12.0) (2026-09-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **auth:** Auth.devAgent sets expectedSender to enforce sender identity client-side ([#133](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/133))
+
+### Features
+
+* **parity:** add isCanonicalCommitmentHash + anomaly constant exports ([bbde8d2](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/bbde8d2f72b6fa2d1dc9024bafa587a21243d051))
+* **projections:** rename TaskCompletionRecord/TaskFailureRecord ([#142](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/142)) ([84008e1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/84008e1700304814fe17093ae35c9046aab553ea))
+* **projections:** rename TaskProjection.isComplete to isCompleted ([#141](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/141)) ([3239ae6](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/3239ae63df50b25064b51bdee93d397af2ed904e))
+
+
+### Bug Fixes
+
+* **agent:** Participant terminal-on-cancel, teardown on every run() exit, tri-state isStopped, guarded rollback pop ([#113](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/113)) ([e1a7de4](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/e1a7de486c9ce6d23c249811a98ba99a15814a9b))
+* **agent:** retry a transient NOT_FOUND on subscribe ([#100](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/100)) ([#101](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/101)) ([ffb0251](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/ffb02514aaaeb9351bf465c00e808833536d3568))
+* **auth:** Auth.devAgent sets expectedSender to enforce sender identity client-side ([#133](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/133)) ([cc0f344](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/cc0f344f2cbb4cf4d59e17fbe4d043cc6f9eebac))
+* **client:** map stream inline errors and registry gRPC statuses to MacpAckError ([#118](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/118)) ([28d4c52](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/28d4c527c324469848ce90a9199b7318970dd071))
+* **commitment-hash:** supersedes: null now hashes as absent, matching macp-sdk-python ([#114](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/114)) ([6e15b9f](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/6e15b9fbc2fc61699970ed30276fd2e249152f08))
+* **index:** drop _resetLoggingForTests from public surface; correct pagination/ListRoots docs ([#112](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/112)) ([99c2f4a](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/99c2f4a67c5200a60f3d7facfbec0ab0dc08eb85))
+* **parity:** re-vendor contract.json for contract_version 1.1.1 ([#129](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/129)) ([459e795](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/459e7959a5eabaa32008b8750bbf33c972e151a3)), closes [#125](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/125)
+* **parity:** re-vendor contract.json for contract_version 1.2.0 ([#136](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/136)) ([8ef1ab1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/8ef1ab1861e8e871cf3284ee3e125fceba7e2691)), closes [#135](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/135)
+* **projections:** gate TaskComplete/TaskFail phase transitions on task existence ([#120](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/120)) ([41f9010](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/41f90109df032c8072052232cd4501d2bbda0fed)), closes [#111](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/111)
+* **projections:** gate three more phase transitions on entity existence ([#123](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/123)) ([866490a](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/866490a332353049064596371dd1e05b4598062f)), closes [#119](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/119)
+* **projections:** guard QuorumProjection.setBallot on request existence ([#127](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/127)) ([e3b75aa](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/e3b75aa265e019610cfd7b0d0446a38a93437d01)), closes [#121](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/121)
+* **projections:** unfreeze 5 of 6 ProjectionAnomalyKind sites ([#126](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/126), [#128](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/128)) ([#134](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/134)) ([a99668c](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/a99668cf8977309c91c0390f5c0967ad80c2786b))
+* **proto-registry:** stop coercing legacy-JSON Contribute value ([#124](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/124)) ([#130](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/130)) ([02bbe90](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/02bbe90c48824e82e0436d315dd0582d057ffec2))
+* **proto-registry:** stop misdecoding canonical Contribute payloads as JSON ([#110](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/110)) ([26dddb6](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/26dddb61eb7ff163c23ecbd6e96c2abedfab150c))
+* **sessions,agent,auth:** thread auth through start(), default identities, validate strategy output ([#116](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/116)) ([4c633e0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/4c633e02f11bc5f6a8995346b9b4cdc0213003c0))
+* **strategies:** exclude REVIEW evaluations from majorityVoter ratio ([#124](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/124)) ([#131](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/131)) ([b52c7f2](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/b52c7f2744bd5841a023461a4009c411a9514b75))
+* **validation:** enforce no-fall-through session-id rule, reject NaN confidence, normalize decision.ts wire case ([#115](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/115)) ([df1c6a2](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/df1c6a2c966f2f5f88937b3b2fcc2a160edbd987))
+* **validation:** stop rejecting empty/omitted intent, instructions, action, summary ([#124](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/124)) ([#132](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/132)) ([aa157ee](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/aa157eeff8d284c1cc727c7cb0d73a86f41ab35b))
+
+## [0.11.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.10.0...v0.11.0) (2026-09-22)
+
+
+### ⚠ BREAKING CHANGES
+
+* **policy:** buildDecisionPolicy's default schemaVersion is now 3 (was 2). A call that omits options.schemaVersion and uses a binding voting algorithm now fails closed on an empty decisive tally instead of silently sealing on zero ballots. Pass { schemaVersion: 1 } or { schemaVersion: 2 } explicitly to keep the old fail-open behavior.
+
+### Features
+
+* **policy:** flip Decision-policy schemaVersion default from 2 to 3 ([#97](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/97)) ([a82972a](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/a82972ae43550f4b953a6bd0e32bfb387fd25806))
+
+## [Unreleased]
+
+### ⚠ BREAKING CHANGES
+
+* **policy:** `QuorumThreshold.type` no longer accepts `'weighted'`. The
+  identifier was removed from the canonical `quorum-rules.schema.json`
+  without ever having defined semantics (no weights vocabulary, no
+  electorate rule) and every descriptor that used it was already refused by
+  the runtime at `RegisterPolicy` — so this is a compile-time break for
+  callers whose descriptors could never register in the first place.
+  `buildQuorumPolicy` now also rejects it at runtime (for JS callers or an
+  `as` cast), naming the reservation.
+* **policy:** `buildQuorumPolicy(id, desc, {})` (an omitted `threshold`) now
+  emits `threshold: { value: 1 }` instead of `value: 0`. A zero approval bar
+  is trivially satisfied by any ballot set, so the canonical schema declares
+  `value` with `exclusiveMinimum: 0`; `buildQuorumPolicy` now enforces that
+  bound for every `threshold.type`, not just `'percentage'`, and rejects a
+  non-integer or non-positive `value` with `MacpSessionError`.
+* **policy:** `buildDecisionPolicy` now enforces the canonical
+  `decision-rules.schema.json` voting constraints client-side, so calls that
+  previously returned an unregistrable descriptor now throw `MacpSessionError`
+  instead:
+  - `voting.algorithm` must be one of the six canonical values.
+  - `voting.threshold` must be `0 < threshold <= 1`.
+  - `algorithm: 'majority'` requires `threshold >= 0.5` (inclusive — a `0.3`
+    "majority" now throws).
+  - `algorithm: 'supermajority'` **at its own default `threshold: 0.5`** now
+    throws — this is the change most likely to break an existing idiomatic
+    call (`buildDecisionPolicy(id, desc, { voting: { algorithm: 'supermajority' } })`);
+    pass an explicit `threshold` above `0.5` (e.g. `0.67`).
+  - `algorithm: 'weighted'` with no `weights` now throws.
+  - `voting.weights`, if supplied at all, is now validated **unconditionally
+    at every algorithm, not only `'weighted'`**: it must be non-empty, and
+    every value must be `> 0`. `weights: { a: 0 }` now throws — a weight-0
+    participant must be expressed by omission from the map.
+* **policy:** all five `build*Policy` functions (`buildDecisionPolicy`,
+  `buildQuorumPolicy`, `buildProposalPolicy`, `buildTaskPolicy`,
+  `buildHandoffPolicy`) now throw `MacpSessionError` when
+  `commitment.authority` is `'designated_role'` and `designatedRoles` is
+  omitted or `[]`. An authority rule that names no one is unsatisfiable, and
+  every canonical rule schema already refused this combination at
+  `RegisterPolicy` — this call previously returned a descriptor the runtime
+  would reject.
+* **policy:** `buildDecisionPolicy`'s default `schemaVersion` is now `3`
+  (was `2`), decided jointly with `macp-sdk-python`'s identical default flip
+  (issue #85, see `macp-sdk-python`#65). Any `buildDecisionPolicy` call that
+  omits `options.schemaVersion` and uses a binding voting algorithm
+  (`majority`, `unanimous`, etc.) now fails closed on an empty decisive
+  tally instead of silently sealing on zero ballots. Not retroactive — a
+  stored policy always evaluates under its own recorded `schemaVersion`
+  forever (RFC-MACP-0012 §8); this only changes what new callers who don't
+  pass `schemaVersion` explicitly get going forward. Pass
+  `{ schemaVersion: 1 }` or `{ schemaVersion: 2 }` explicitly to keep the
+  old fail-open behavior.
+* **auth:** `Auth.devAgent(agentId)` now also sets `expectedSender: agentId`
+  on the returned `AuthConfig` (issue #124 item 4). The runtime's dev
+  fallback already authenticates the gRPC connection as the bearer value
+  (`agentId`) and unconditionally refuses a mismatched `sender` for dev
+  credentials (`macp-runtime/src/server.rs:229-231`, no insecure/dev
+  exemption) — this SDK now enforces the same guarantee client-side instead
+  of surfacing the runtime's rejection late and confusingly. A bootstrap or
+  caller whose `agent_id`/credential diverges from the `sender`/
+  `participant_id` it actually sends now fails on the first typed
+  handler-driven action (e.g. `acceptTask`, `vote`) with
+  `MacpIdentityMismatchError`, instead of only failing server-side. The
+  initiator's `SessionStart`/kickoff path is unaffected (it passes no
+  explicit `sender`), as is the generic `actions.send` escape hatch (which
+  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.
+
+### Features
+
+* **policy:** `buildDecisionPolicy` accepts a new fourth `options` argument,
+  `{ schemaVersion?: 1 | 2 | 3 }`, to select a Decision policy's
+  RFC-MACP-0012 empty-tally semantics — `3` (the default) fails closed
+  (§4.1's "vacuous participation floor"); `1`/`2` fail open. An out-of-range
+  value throws `MacpSessionError`.
+
+### Bug Fixes
+
+* **policy:** `buildQuorumPolicy`, `buildProposalPolicy`, `buildTaskPolicy`,
+  and `buildHandoffPolicy` no longer emit `require_vote_quorum` into their
+  `commitment` block. Only `decision-rules.schema.json`'s commitment object
+  declares that key; the other four canonical rule schemas close with
+  `additionalProperties: false` and do not, so the previous output was
+  spec-nonconformant with no CI signal (today's runtime does not enforce
+  `additionalProperties`, but a stricter or future validator would reject
+  it). Passing `commitment.requireVoteQuorum` to these four builders is now
+  silently dropped, matching its existing "ignored for other modes"
+  documentation, rather than leaking an unrecognized key onto the wire.
+  `buildDecisionPolicy` is unaffected.
+* **projections:** all six `applyEnvelope` entry points now roll back
+  `transcript` and the `message_id` redelivery-dedup set on a failed payload
+  decode, instead of leaving a partial application in place. Previously, a
+  failed decode still marked the envelope's `message_id` "seen," so a
+  legitimate retry with a corrected payload was silently absorbed as a
+  redelivery and the envelope's effect was lost forever.
+
+### Added
+
+- **All five mode sessions' `start()` now accept a per-call
+  `auth?: AuthConfig`** (issue #108, part 2 of 2 — 4B), matching every other
+  action method on these classes. Previously `start()` alone ignored a
+  per-call `auth` on `DecisionSession`/`ProposalSession`/`TaskSession`/
+  `HandoffSession`/`QuorumSession`, resolving the sender only against the
+  session/client-level credential — so a caller passing a conflicting
+  per-call `auth.expectedSender` never got the identity-mismatch guard
+  (RFC-MACP-0004 §4) that every other method already enforced.
+  `BaseSession.start()` already accepted and threaded a per-call `auth`
+  before this change; see the `BaseSession.start()` validation entry below
+  for what actually changed there in 4B.
+- **`ProjectionAnomalyKind` gains two new, cross-SDK-agreed kinds:
+  `duplicate_task_accept` and `settled_handoff`** (issue #126/#128;
+  `macp-sdk-python` landed its half in PR #95). `TaskProjection` now records
+  a `duplicate_task_accept` anomaly when a `TaskAccept` for a task it has a
+  `TaskRequest` on file for is discarded because another task already holds
+  the session's one assignee slot (RFC-MACP-0009 §5 rules 3/3a).
+  `HandoffProjection` now records a `settled_handoff` anomaly when a
+  `HandoffAccept`/`HandoffDecline` targets a `handoff_id` that already
+  settled as accepted or declined (RFC-MACP-0010 §5 rule 4). Both new
+  constants (`ANOMALY_DUPLICATE_TASK_ACCEPT`/`ANOMALY_SETTLED_HANDOFF`)
+  export from the package root alongside the existing pair. A `TaskAccept`/
+  `HandoffAccept`/`HandoffDecline` for an *unknown* `task_id`/`handoff_id`
+  still records no anomaly — that determination (not caller misuse) is
+  unchanged by this release. This is purely additive observability: no
+  change to `phase`, `tasks`, or `handoffs` state itself at any of these
+  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.
+
+### Changed
+
+- **BREAKING (test-only surface): `_resetLoggingForTests` is no longer part
+  of the package's public export surface.** (issue #109) It was reachable
+  only via `src/index.ts`'s `export * from './logging'` wildcard; that line
+  is now a named re-export listing `logger`, `configureLogging`, `LogLevel`,
+  and `LogSink`. Because `package.json`'s `exports` map exposes only `"."`,
+  this makes the helper unreachable from the published package entirely (no
+  submodule fallback) — accepted, since it is test-only by name and by
+  purpose, and `configureLogging` already covers every legitimate caller
+  need.
+- **`validateSessionId` now enforces the runtime's actual no-fall-through
+  rule** (issue #108, part 1 of 2 — 4A). A UUID-**shaped** string (36 chars,
+  hyphens at 8-13-18-23, hex-only) is now validated strictly as a lowercase
+  v4/v7 UUID and never reinterpreted as base64url. An uppercase UUID, a
+  lowercase v1 UUID, the nil UUID, or a UUID with a bad variant nibble now
+  throws `MacpSessionError` client-side — all were already rejected by the
+  runtime, so nothing that previously *worked* stops working, but a caller
+  relying on the old, looser client-side check now gets the rejection
+  earlier. Ports `macp-sdk-python`'s two-regex no-fall-through structure.
+- **`DecisionSession.evaluate`/`raiseObjection`/`vote` now put the
+  normalized (uppercased/lowercased) value on the wire, not the caller's
+  original case** (issue #108, part 1 of 2 — 4A).
+  `validateVote`/`validateRecommendation`/`validateSeverity` each return a
+  normalized string; the three call sites in `decision.ts` previously
+  discarded it. A consumer that string-compares an un-normalized value
+  (e.g. `'approve'` instead of `'APPROVE'`) sees a different value on the
+  wire; every in-repo projection already normalizes case itself, so no
+  projection assertion is affected by this change.
+- **An empty/missing `bearerToken` now throws `MacpSdkError`, not a bare
+  `Error`** (issue #108, part 2 of 2 — 4B). `validateAuth` (and therefore
+  `metadataFromAuth`, reached from every authenticated RPC) previously threw
+  a plain `Error('bearerToken is required')`, which is not `instanceof
+  MacpSdkError` — escaping the documented `catch (e) { if (e instanceof
+  MacpSdkError) ... }` pattern from both SDKs' error-handling docs. Message
+  text unchanged.
+- **`BaseSession.start()` now runs the same full `validateSessionStart`
+  check as the five built-in mode sessions, not a partial check** (issue
+  #108, part 2 of 2 — 4B). Previously this documented ext-mode extension
+  point validated only participant count and `maxSuspendMs`, so an empty
+  `intent`, an empty/duplicate `participants` array, or an out-of-range
+  `ttlMs` reached the wire unvalidated from a custom mode built on
+  `BaseSession` — the weakest-validated mode in the SDK. All five now
+  reject client-side, matching every built-in mode session.
+- **BREAKING (narrows an exception type): `send()` now throws `MacpAckError`,
+  not `MacpTransportError`, for a gRPC `ALREADY_EXISTS`/`FAILED_PRECONDITION`;
+  same for `registerExtMode`/`unregisterExtMode`/`promoteMode`/
+  `registerPolicy`/`unregisterPolicy` on `FAILED_PRECONDITION`** (issue #107).
+  These are application-level rejections the runtime couldn't express as a
+  normal Ack, not transport faults — `MacpAckError` (`failure.code`
+  `'SESSION_ALREADY_EXISTS'` / `'POLICY_DENIED'` / `'FAILED_PRECONDITION'`
+  respectively) is the correct, Python-parity model
+  (`client.py:442-452`, `_map_registry_mutation_error` at `client.py:347-362`).
+  Code today catching `MacpTransportError` around these calls for these
+  specific statuses stops matching (`MacpAckError` extends `MacpSdkError`
+  directly, not `MacpTransportError`); every other gRPC status on these RPCs,
+  and every status on every other RPC, is unaffected. A knock-on effect on
+  `retrySend()`: a `FAILED_PRECONDITION` `send()` was previously retried to
+  exhaustion (no code filter on `MacpTransportError`) and surfaced as
+  `MacpRetryError`; it now surfaces immediately as `MacpAckError`, since
+  `POLICY_DENIED` is not in `DEFAULT_RETRY_POLICY.retryableCodes` — strictly
+  more correct (neither condition is retryable) and no longer masks the real
+  error behind a generic "retries exhausted."
+- **`TaskProjection.isComplete(taskId)` renamed to `isCompleted(taskId)`**
+  (issue #138, cross-SDK naming decision at
+  multiagentcoordinationprotocol#135). Every other `is*` predicate in this
+  SDK is past-participle (`isFailed`, `isAccepted`, `isTerminallyRejected`,
+  `isDeclined`); `isComplete` was the outlier, and `macp-sdk-python` has
+  always spelled this `is_completed`. The old name remains available — see
+  `### Deprecated` below.
+- **`TaskCompletionRecord` renamed to `TaskCompleteRecord`, and
+  `TaskFailureRecord` renamed to `TaskFailRecord`** (issue #138, cross-SDK
+  naming decision at multiagentcoordinationprotocol#135). Both now mirror
+  their triggering `TaskComplete`/`TaskFail` message types the way their
+  sibling `TaskUpdateRecord` already mirrors `TaskUpdate`, and match
+  `macp-sdk-python` and `macp-runtime`'s own names for the same records. The
+  old names remain available — see `### Deprecated` below.
+
+### Deprecated
+
+- **`TaskProjection.isComplete(taskId)`** remains available as a
+  `@deprecated` alias for `isCompleted(taskId)`; use `isCompleted()` instead.
+  Scheduled for removal in 0.13.0.
+- **`TaskCompletionRecord`/`TaskFailureRecord`** remain available as
+  `@deprecated` type aliases for `TaskCompleteRecord`/`TaskFailRecord`
+  respectively. Scheduled for removal in 0.13.0.
+
+### Fixed
+
+- **`validateConfidence` now rejects `NaN`** (issue #108, part 1 of 2 — 4A).
+  `NaN < 0` and `NaN > 1.0` are both `false`, so a bare range check silently
+  accepted `NaN` — verified by execution before this fix. `±Infinity` was
+  already rejected (incidentally); this also rejects it explicitly via
+  `Number.isFinite`, matching this file's own `ttlMs`/`maxSuspendMs` idiom.
+- **`commitmentHash`/`canonicalizeCommitmentPayload`: `supersedes: null` now
+  hashes as absent, matching `macp-sdk-python`** (issue #105). `supersedes`
+  is a proto3 message-typed field with only present/absent wire states;
+  `null` is the idiomatic in-language representation of "absent" (e.g. under
+  a `defaults: true` protobufjs/proto-loader decode, or a payload
+  round-tripped through JSON). Previously `supersedes: null` took the
+  *present* branch and hashed identically to an explicit
+  `{ sessionId: '', commitmentHash: '' }`, producing a different digest than
+  `macp-sdk-python` computes for the same logical commitment. The predicate
+  changed from `p.supersedes !== undefined` to `p.supersedes != null`
+  (deliberately loose — catches `null` and `undefined` only, so `0`, `''`,
+  `false`, and other falsy-but-not-nullish values still take the present
+  branch, unaffected). Not a protocol MINOR bump: the hashing `LABEL` and
+  frozen field set are unchanged — this corrects a projection bug, not the
+  algorithm. Any digest a caller already computed by feeding `null` was
+  already wrong (Python never reproduced it), so there is no
+  correct-value regression, but the fix is a security/audit-relevant
+  behavior change on this SDK's own output.
+- **`Participant` lifecycle: `SessionCancel` now reaches `onTerminal`, and
+  teardown runs on every exit from `run()`, not just an explicit `stop()`**
+  (issue #106). Three independent bugs in `src/agent/participant.ts`:
+  - A runtime-issued `SessionCancel` never fired `onTerminal` at all — no
+    built-in projection maps it to a terminal phase, so the phase-driven
+    dispatch path had nothing to trigger on. `Participant` now recognizes
+    `SessionCancel` directly as a fallback when the phase path doesn't fire,
+    dispatching `{ state: 'Cancelled' }`. Against the current `macp-runtime`,
+    this fallback's practical reach is `processEvent()` callers and
+    cross-SDK parity with `macp-sdk-python`'s identical fallback — the
+    streamed `run()` path never observes a `SessionCancel` at all today,
+    since `cancel_session` stores it as `EntryKind::Internal` and
+    `get_incoming_after` filters strictly to `EntryKind::Incoming`;
+    cancellation surfaces via `session_lifecycle_bus`/`WatchSessions`
+    instead.
+  - `run()`'s `finally` only cleared an internal flag; the transport
+    subscription and the cancel-callback HTTP listener were torn down
+    exclusively inside `stop()`. A normal terminal exit, or a transport
+    simply running out of messages, leaked both — a long-lived agent
+    process running many sessions sequentially leaked one gRPC stream
+    subscription and one listening TCP socket per completed session.
+    Teardown now runs on every exit from `run()`.
+  - `isStopped` computed `!running`, so it read `true` immediately after
+    construction, before `run()` had ever been called. Fixed by tracking
+    three independent states (`running` / `terminal` / `stopRequested`)
+    instead of one flag — deliberately **not** a single latch copied from
+    `macp-sdk-python`, because that would make a `Participant` single-use
+    after any `stop()`, breaking this SDK's own documented and tested
+    restart contract (issue #66): `stop()` mid-stream, then a second
+    `run()` on the same instance, must resume rather than refuse. Only a
+    genuinely *terminal* outcome is single-use; a `stop()`-only exit is a
+    resumable pause.
+- **`BaseProjection`'s rollback pop is now guarded by reference identity**
+  (issue #106, item 4): it no longer unconditionally pops the last
+  `transcript` entry on a failed decode. `BaseProjection` is documented
+  subclassable API; a third-party subclass whose `applyMode` pushes its own
+  entry onto `transcript` before throwing would previously have had that
+  entry silently removed instead of the envelope actually under
+  application — data corruption strictly worse than the bug the rollback
+  itself fixes. Mirrors `macp-sdk-python`'s identical guard and its own
+  documented trade-off in this exact scenario.
+- **Identity fields on `Task`/`Handoff` actions now default to the resolved
+  sender when omitted or empty, matching `macp-sdk-python`** (issue #108,
+  part 2 of 2 — 4B): `TaskSession.acceptTask`/`rejectTask`/`completeTask`/
+  `failTask`'s `assignee`, and `HandoffSession.acceptHandoff`'s `acceptedBy`/
+  `decline`'s `declinedBy`, are now optional and fall back to the caller's
+  authenticated identity (`input.field || resolvedSender` — `||`, not `??`,
+  since an explicit empty string is also meant to fall back). Previously
+  these were required fields passed straight through with no default, unlike
+  the Python SDK (`task.py:299,323,391,430`, `handoff.py:247,271`).
+- **`HandoffSession.addContext`'s `contentType` now defaults to
+  `'application/octet-stream'` when omitted**, matching `macp-sdk-python`
+  (`handoff.py:210`) (issue #108, part 2 of 2 — 4B). Previously `contentType`
+  was a required field with no default.
+- **`evaluationHandler`/`votingHandler` now validate a strategy's output
+  before dispatching it** (issue #108, part 2 of 2 — 4B). Both previously
+  passed a custom `EvaluationStrategy`/`VotingStrategy`'s raw
+  `recommendation`/`confidence`/`vote` straight to `ctx.actions.*` with no
+  validation, so a buggy strategy (an out-of-enum recommendation, a `NaN`
+  confidence, an out-of-enum vote) failed later and less legibly, from
+  inside the session rather than at the handler that produced the bad
+  value. Both handlers now reuse this SDK's own `validateRecommendation`/
+  `validateConfidence`/`validateVote` (throwing the documented
+  `MacpSessionError`) and dispatch the validators' normalized return value.
+- **`MacpStream`'s inline-error path was reading a shape a real decode never
+  produces, silently dropping every inline application-level error** (issue
+  #107). `StreamSessionResponse.response` is a proto3 `oneof`; under this
+  file's own `@grpc/proto-loader` options (`oneofs: true`), the decoded
+  object exposes the payload directly as `chunk.envelope`/`chunk.error`, with
+  `chunk.response` set to the oneof's *arm name as a string* (`'envelope'` or
+  `'error'`) — not a nested object. The old code read
+  `chunk?.response?.error`, which indexes a string and is always `undefined`
+  on every message that has ever crossed this stream; the corresponding unit
+  test only ever passed because it emitted the same fictional
+  `{ response: { error } }` shape by hand rather than a real decode. Fixed to
+  read `chunk.error` directly, and each inline error is now also logged at
+  `warn` (it previously produced no log line anywhere).
+- **`TaskProjection.phase` no longer advances to `'Completed'`/`'Failed'` for
+  a `TaskComplete`/`TaskFail` naming an unknown `task_id`** (issue #111).
+  Both `this.phase` assignments sat outside the `if (task) { ... }` guard
+  that already gated every other per-task field mutation in the same
+  `applyMode` cases, so a message for a `task_id` this projection never saw
+  a `TaskRequest` for still flipped the session-level `phase` to a terminal
+  state even though no task actually completed or failed. Moved both
+  assignments inside their sibling `if (task)` block, matching the guard
+  already correct on `TaskAccept` (issue #71/#70) and on
+  `HandoffProjection`'s analogous `phase` transitions.
+- **Three more `phase`-transition-outside-guard sites, same bug shape as
+  issue #111, found during that fix's verification** (issue #119):
+  - `ProposalProjection`'s `Reject` case moved `this.phase =
+    'TerminalRejected'` inside the sibling `if (proposal) { ... }` guard. A
+    terminal `Reject` for an unknown `proposalId` no longer advances `phase`
+    — which matters beyond bookkeeping, since `'TerminalRejected'` is a
+    `TERMINAL_PHASES` member in `src/agent/participant.ts`, so the bug could
+    end a live `Participant`'s `run()` loop for a session that never
+    actually terminated.
+  - `HandoffProjection`'s `HandoffContext` case moved its `phase` transition
+    (`'OfferPending'` → `'ContextSharing'`) inside the sibling `if (handoff)
+    { ... }` guard, matching `HandoffAccept`/`HandoffDecline`, which were
+    already correct.
+  - `DecisionProjection`'s `Vote` case gained a new existence guard (none
+    existed before): `if (!this.proposals.has(record.proposalId)) break;`,
+    per RFC-MACP-0007 §5 rule 2 ("`Evaluation`, `Objection`, and `Vote` MUST
+    reference an existing `proposal_id`"). Previously a `Vote` for an unknown
+    `proposalId` fabricated a `votes` `Map` entry and flipped `phase` to
+    `'Voting'` — the fabricated entry also inflated `voteTotals()`'s and
+    `majorityWinner()`'s denominators, able to flip a real proposal from
+    winner to non-winner in a close tally.
+
+  All three sites' `rejections`/audit-array-style writes remain unconditional
+  (append-only logs, matching the runtime), so query methods reading from
+  them (`isTerminallyRejected`, `hasTerminalRejection`) can still report
+  `true` for an unknown id even though `phase` no longer moves — intentional,
+  not a residual gap.
+- **`QuorumProjection.setBallot` no longer fabricates a `ballots` entry for an
+  unknown `request_id`** (issue #121, found during issue #119's plan-review
+  sweep). RFC-MACP-0011 §5 rule 3 requires a ballot (`Approve`/`Reject`/
+  `Abstain`) to reference the Session's accepted `request_id`; there was no
+  check against `this.requests` before creating or extending a `ballots` Map
+  entry, so an unfiltered/multi-session transcript could make
+  `votedSenders()` and `approvalCount()`/`rejectionCount()`/
+  `abstentionCount()` report on a `request_id` that was never opened, and a
+  second such ballot from the same sender could fire a spurious
+  `duplicate_ballot` anomaly against it. Unlike the three sites above, this
+  bug never touched `phase` — `QuorumProjection.phase` is set only by
+  `ApprovalRequest` and by `Commitment` handling in `BaseProjection` — so the
+  fix is a single existence guard at the top of `setBallot`, with no phase
+  component.
+- **`ProtoRegistry.decodeMultiRoundContribute` no longer coerces a legacy-JSON
+  `Contribute` payload's `value` to a string** (issue #124). Previously
+  `String(parsed.value ?? '')` made an absent `value` key indistinguishable
+  from a genuine empty string, and stringified any non-string JSON value
+  (`123` decoded to `'123'`, `null` decoded to `''`). The legacy-JSON decode
+  path now passes `parsed.value` through exactly as `JSON.parse` produced
+  it — `undefined` stays `undefined`, `null` stays `null`, a number stays a
+  number. The canonical-protobuf decode path is unaffected (its `value` is
+  always a `string`, per the proto schema).
+- **`majorityVoter` no longer counts `REVIEW` evaluations in its approval
+  ratio** (issue #124). RFC-MACP-0007 §4 states `REVIEW` evaluations "do not
+  block or approve a proposal; they serve as informational analysis records
+  only" — a `REVIEW` was nonetheless lowering the ratio's denominator, so a
+  proposal with one `APPROVE` and one `REVIEW` voted at ratio `0.5` instead
+  of `1.0`. The ratio's denominator is now the `decisive` evaluations
+  (everything except `REVIEW`, case-insensitive); `shouldVote` now returns
+  `false` for an evaluation set of only `REVIEW`s (no decisive evaluation to
+  vote on) instead of voting `REJECT` at ratio `0`. `BLOCK` and `REJECT`
+  remain in the denominator — they are stances, not informational-only
+  records.
+- **`intent`, `instructions`, `action`, and `summary` no longer rejected when
+  empty or omitted** (issue #124). `SessionStart.intent`,
+  `TaskSession.requestTask`'s `instructions`, and
+  `QuorumSession.requestApproval`'s `action`/`summary` are proto3 singular
+  `string` fields — implicit presence means an omitted value and an explicit
+  `''` serialize to identical bytes, so a client-side "required, non-empty"
+  check rejected a payload the runtime would accept and no runtime-side check
+  could ever distinguish. `intent` also has an explicit normative rule
+  (RFC-MACP-0001 §7.1: a runtime "MUST NOT reject a SessionStart solely
+  because intent is empty"). Every other `validateRequiredField` call
+  site — `taskId`, `title`, `requestId`, `proposalId`, `option`, `handoffId`,
+  `targetParticipant`, `modeVersion`, `configurationVersion` — is unaffected
+  and still rejects an empty value.
+
+### Documentation
+
+- **Pagination memory caveat** (issue #109): `docs/api/client.md`'s
+  `listSessions` and `listSessionsPage` entries now state plainly that while
+  `macp-runtime` ≥ 0.7.0 (current: 0.8.3) implements real server-side
+  pagination, `listSessions()` itself still accumulates every page into one
+  in-memory array regardless of `pageSize` — callers who need bounded
+  memory should call `listSessionsPage()` directly.
+- **`ListRoots` wording** (issue #109): `docs/guides/streaming.md` no
+  longer says the runtime "serves `ListRoots`," which reads as "returns
+  real data" — reworded to state plainly that the runtime always returns an
+  empty root list. `docs/api/client.md`'s `listRoots` entry gains the same
+  statement, which it previously lacked entirely.
+
 ## [0.10.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.9.0...v0.10.0) (2026-09-01)
 
 

package/README.md

@@ -158,7 +158,7 @@ await session.commit({ action: 'task.completed', authorityScope: 'lead', reason:
 
 // Projection queries
 session.projection.progressOf('t1');   // 1.0
-session.projection.isComplete('t1');   // true
+session.projection.isCompleted('t1');  // true
 session.projection.activeTasks();      // []
 ```
 
@@ -416,7 +416,7 @@ npm run test:integration   # Integration tests (requires Docker runtime; not run
 ```
 
 CI (GitHub Actions) runs type-check, lint, format check, the coverage-gated
-test suite, and the build on Node 20, 22, and 24 for every push and pull
+test suite, and the build on Node 22 and 24 for every push and pull
 request, and posts a coverage summary comment on PRs.
 
 ### Integration Tests

package/dist/agent/index.d.ts

@@ -4,4 +4,4 @@ export * from './dispatcher';
 export * from './participant';
 export * from './strategies';
 export * from './runner';
-export { GrpcTransportAdapter, HttpTransportAdapter, type TransportAdapter, type HttpPollingConfig, } from './transports';
+export { GrpcTransportAdapter, HttpTransportAdapter, DEFAULT_SUBSCRIBE_RETRY_POLICY, type TransportAdapter, type HttpPollingConfig, type SubscribeRetryPolicy, } from './transports';

package/dist/agent/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpTransportAdapter = exports.GrpcTransportAdapter = void 0;
+exports.DEFAULT_SUBSCRIBE_RETRY_POLICY = exports.HttpTransportAdapter = exports.GrpcTransportAdapter = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./cancel-callback"), exports);
 __exportStar(require("./dispatcher"), exports);
@@ -24,3 +24,4 @@ __exportStar(require("./runner"), exports);
 var transports_1 = require("./transports");
 Object.defineProperty(exports, "GrpcTransportAdapter", { enumerable: true, get: function () { return transports_1.GrpcTransportAdapter; } });
 Object.defineProperty(exports, "HttpTransportAdapter", { enumerable: true, get: function () { return transports_1.HttpTransportAdapter; } });
+Object.defineProperty(exports, "DEFAULT_SUBSCRIBE_RETRY_POLICY", { enumerable: true, get: function () { return transports_1.DEFAULT_SUBSCRIBE_RETRY_POLICY; } });

package/dist/agent/participant.d.ts

@@ -39,8 +39,10 @@ export interface ParticipantConfig {
     /**
      * Bind a cancel-callback HTTP endpoint (RFC-0001 §7.2 Option A) when
      * this participant's event loop starts. The server is closed
-     * automatically when {@link Participant.stop} is called. Parity with
-     * python-sdk's bootstrap `cancel_callback` field.
+     * automatically on any exit from {@link Participant.run} — an explicit
+     * {@link Participant.stop}, a terminal outcome, or the transport running
+     * out of messages. Parity with python-sdk's bootstrap `cancel_callback`
+     * field.
      */
     cancelCallback?: {
         host: string;
@@ -64,7 +66,23 @@ export declare class Participant {
     private readonly modeVersion?;
     private readonly configurationVersion?;
     private readonly policyVersion?;
+    /** Whether the event loop is currently inside {@link run}. */
     private running;
+    /**
+     * Latching: set once a terminal result is dispatched (a terminal phase,
+     * or the {@code SessionCancel} fallback in {@link processMessage}). A
+     * terminal `Participant` is single-use — {@link run} refuses to
+     * re-enter, because the projection is resolved and the runtime will
+     * accept nothing further for this session.
+     */
+    private terminal;
+    /**
+     * The cooperative cancel flag {@link stop} sets and {@link run} clears
+     * on entry — the loop's break predicate. Distinct from {@link terminal}:
+     * a `stop()`-exited, non-terminal `Participant` is a resumable pause
+     * (see {@link isStopped}), not single-use.
+     */
+    private stopRequested;
     private lastPhase;
     private cancelCallbackServer?;
     private readonly cancelCallbackConfig?;
@@ -74,7 +92,12 @@ export declare class Participant {
     on(messageType: string, handler: MessageHandler): Participant;
     onPhaseChange(phase: string, handler: PhaseChangeHandler): Participant;
     onTerminal(handler: TerminalHandler): Participant;
-    /** Whether {@link stop} has been called (or the loop has exited). */
+    /**
+     * `true` after a terminal outcome (single-use from here on), or while a
+     * `stop()` request is pending/has taken effect on a `Participant` whose
+     * loop has not (yet) been resumed by a later {@link run}. A `stop()`
+     * exit is resumable — see {@link run} and {@link terminal}'s own doc.
+     */
     get isStopped(): boolean;
     run(): Promise<void>;
     /**
@@ -87,10 +110,30 @@ export declare class Participant {
     private buildHandlerContext;
     /** Returns true if a terminal state was reached. */
     private processMessage;
+    /**
+     * Idempotent teardown of everything {@link run} started: the transport
+     * subscription and the cancel-callback HTTP listener, if any. Called
+     * from both {@link stop} and every exit from {@link run}'s loop (issue
+     * #106.2) — a normal terminal exit or a transport running out of
+     * messages used to leak both. A rejecting `transport.stop()` is caught
+     * rather than propagated, so a transport fault on teardown cannot mask
+     * a clean session outcome as a thrown error from {@link run}.
+     */
+    private teardown;
+    /**
+     * Request that {@link run}'s loop stop. This SDK's {@link TransportAdapter}
+     * has no `cancel()` — `stop()` on the transport is the only thing that can
+     * wake a loop suspended awaiting the next envelope, so teardown (including
+     * the transport) runs here unconditionally, not just the flag. Safe to
+     * call whether or not `run()` is currently active; does not itself flip
+     * {@link running} — only `run()`'s own loop exit does that, since it is
+     * the only place that actually knows the loop has left.
+     */
     stop(): Promise<void>;
     /**
      * Attach a running cancel-callback HTTP server to this participant.
-     * The server is closed automatically when {@link stop} is called.
+     * The server is closed automatically on any exit from {@link run} — see
+     * {@link teardown}.
      * Parity with python-sdk's `Participant.attach_cancel_callback_server`.
      */
     attachCancelCallbackServer(server: CancelCallbackServer): void;