macp-sdk-typescript 0.9.0 → 0.10.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.10.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.9.0...v0.10.0) (2026-09-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* `client.sendProgress()` now throws `MacpSessionError` when exactly one of `sessionId`/`mode` is supplied. Such calls used to succeed against a runtime that had the symmetric gap; as of macp-runtime PR #137 they are rejected with `INVALID_ENVELOPE`. Pass both fields for a session-scoped Progress, or neither for an ambient one.
+* **projections:** `TaskProjection` assignee semantics changed twice. (1) The first-accept-wins guard is now per-session, not per-`task_id`: on a transcript with two `TaskRequest`s, only the first `TaskAccept` assigns — the second task keeps `assignee === undefined` and `status === 'requested'`, where it previously got its own assignee. A `TaskAccept` the guard discards also no longer sets `phase = 'InProgress'`. (2) `TaskAccept` is no longer sticky forever: a `TaskReject` from the active assignee clears `assignee` back to `undefined`, so code reading `getTask(id).assignee` after a reject now sees `undefined` (or the reassigned participant) rather than the participant who rejected.
+
+### Bug Fixes
+
+* **projections:** scope the Task assignee slot to the session and free it on reject ([#75](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/75)) ([f7841a9](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/f7841a96d120b3fc55effdfabf63a2d72f431081)), closes [#59](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/59) [#60](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/60) [#70](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/70) [#71](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/71)
+* reject mixed ambient/session-scoped Progress envelopes ([#76](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/76)) ([a9e00e3](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/a9e00e370b7a4bf08d09190e8b75a12d221319f8))
+
 ## [0.9.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.8.0...v0.9.0) (2026-09-01)
 
 

package/dist/client.d.ts

@@ -262,6 +262,15 @@ export declare class MacpClient {
         auth?: AuthConfig;
         deadlineMs?: number;
     }): Promise<Ack>;
+    /**
+     * Send a `Progress` message.
+     *
+     * Per RFC-MACP-0001 §6, `Progress` is legal in exactly two shapes: *ambient*
+     * (`sessionId` and `mode` both omitted/empty) or *session-scoped* (both
+     * non-empty). Supplying exactly one of the two throws `MacpSessionError` —
+     * the runtime rejects that mixed envelope with `INVALID_ENVELOPE`, so this
+     * fails fast with a message naming the mismatched field.
+     */
     sendProgress(options: {
         sessionId?: string;
         mode?: string;

package/dist/client.js

@@ -545,7 +545,17 @@ class MacpClient {
         });
         return this.send(envelope, { auth, deadlineMs: options.deadlineMs });
     }
+    /**
+     * Send a `Progress` message.
+     *
+     * Per RFC-MACP-0001 §6, `Progress` is legal in exactly two shapes: *ambient*
+     * (`sessionId` and `mode` both omitted/empty) or *session-scoped* (both
+     * non-empty). Supplying exactly one of the two throws `MacpSessionError` —
+     * the runtime rejects that mixed envelope with `INVALID_ENVELOPE`, so this
+     * fails fast with a message naming the mismatched field.
+     */
     async sendProgress(options) {
+        (0, validation_1.validateProgressScope)(options.sessionId ?? '', options.mode ?? '');
         const auth = this.requireAuth(options.auth);
         (0, auth_1.assertSenderMatchesIdentity)(auth, options.sender);
         const progressPayload = (0, envelope_1.buildProgressPayload)({

package/dist/projections/task.d.ts

@@ -61,6 +61,26 @@ export declare class TaskProjection {
      * only as a one-line pointer.
      */
     private readonly seenMessageIds;
+    /**
+     * The **session-level** active assignment: who currently holds the session's
+     * single assignee slot, and which `task_id` they took it on.
+     *
+     * RFC-MACP-0009 §5 rule 3 (`:69`): "Only one assignee may become active for
+     * the Session in base v1." The constraint is scoped to the *Session*, not to
+     * a `task_id` — rule 1 (`:67`) separately caps a v1 session at one
+     * `TaskRequest`, so in a conforming transcript the two scopes coincide, but
+     * an unfiltered transcript carrying two `TaskRequest`s must not be able to
+     * hand out two active assignees. That is why this is one field on the
+     * projection rather than a per-`TaskRecord` flag (issue #71).
+     *
+     * `sender` is the envelope sender, not `TaskAcceptPayload.assignee`, to
+     * mirror the reference runtime: `macp-runtime`
+     * `crates/macp-modes/src/mode/task.rs:211` sets `state.active_assignee =
+     * Some(env.sender)` after rejecting any payload whose `assignee` disagrees
+     * with the sender (`:205-207`). `taskId` is retained so a reject can clear
+     * the right `TaskRecord.assignee` even on a multi-task transcript.
+     */
+    private activeAssignment?;
     /**
      * Apply one envelope to this projection's in-process state.
      *

package/dist/projections/task.js

@@ -31,6 +31,26 @@ class TaskProjection {
      * only as a one-line pointer.
      */
     seenMessageIds = new Set();
+    /**
+     * The **session-level** active assignment: who currently holds the session's
+     * single assignee slot, and which `task_id` they took it on.
+     *
+     * RFC-MACP-0009 §5 rule 3 (`:69`): "Only one assignee may become active for
+     * the Session in base v1." The constraint is scoped to the *Session*, not to
+     * a `task_id` — rule 1 (`:67`) separately caps a v1 session at one
+     * `TaskRequest`, so in a conforming transcript the two scopes coincide, but
+     * an unfiltered transcript carrying two `TaskRequest`s must not be able to
+     * hand out two active assignees. That is why this is one field on the
+     * projection rather than a per-`TaskRecord` flag (issue #71).
+     *
+     * `sender` is the envelope sender, not `TaskAcceptPayload.assignee`, to
+     * mirror the reference runtime: `macp-runtime`
+     * `crates/macp-modes/src/mode/task.rs:211` sets `state.active_assignee =
+     * Some(env.sender)` after rejecting any payload whose `assignee` disagrees
+     * with the sender (`:205-207`). `taskId` is retained so a reject can clear
+     * the right `TaskRecord.assignee` even on a multi-task transcript.
+     */
+    activeAssignment;
     /**
      * Apply one envelope to this projection's in-process state.
      *
@@ -81,46 +101,72 @@ class TaskProjection {
             case 'TaskAccept': {
                 const record = payload;
                 const task = this.tasks.get(record.taskId);
-                // RFC-MACP-0009 §5 rules 3/3a (`:69-71`): "Only one assignee may
+                // RFC-MACP-0009 §5 rules 3/3a (`:69-70`): "Only one assignee may
                 // become active for the Session in base v1. The first accepted
                 // `TaskAccept` from any eligible participant designates that
                 // participant as the active assignee. Subsequent `TaskAccept`
                 // messages for the same session MUST be rejected if an active
                 // assignee is already designated." A conforming runtime rejects the
-                // second `TaskAccept` before it reaches accepted history; this guard
-                // makes the projection first-accept-wins too, so a rogue second one
-                // (e.g. an unfiltered transcript) cannot silently reassign the task.
+                // second `TaskAccept` before it reaches accepted history
+                // (`macp-runtime` `crates/macp-modes/src/mode/task.rs:184-186`); this
+                // guard makes the projection first-accept-wins too, so a rogue second
+                // one (e.g. an unfiltered transcript) cannot silently reassign.
                 //
-                // Rule 3c's policy-gated reassignment path (`allow_reassignment_on_reject`,
-                // RFC-MACP-0012 `:135`) is deliberately NOT modelled here:
-                // `TaskProjection` has no session-policy input today, and rule 3b
-                // makes an unconditional reassignment wrong by default ("`TaskAccept`
-                // is irrevocable unless policy explicitly permits reassignment").
-                // Plumbing policy into this projection needs its own decision (see
-                // plans/cross-repo/macp-sdk-typescript-conformance-and-transport.md,
-                // Phase 3 open question 4) before that path can be implemented.
+                // The guard is keyed on the SESSION slot (`activeAssignment`), not on
+                // `task.assignee`, because rule 3's scope is the Session (issue #71).
+                // Two `TaskRequest`s in one transcript therefore share one assignee
+                // slot, matching the runtime, whose `TaskState` holds a single
+                // `active_assignee` (`task.rs:70`) alongside a single `task`.
+                //
+                // Rule 3c's policy-gated reassignment (`allow_reassignment_on_reject`,
+                // RFC-MACP-0012 `:135`) is reachable here via the `TaskReject` case
+                // below, which frees the slot — see its comment for why that needs no
+                // policy input.
                 //
                 // An anomaly would be recorded when this guard discards a second
                 // `TaskAccept`, but `ProjectionAnomalyKind` (`base.ts:8-9`) is
                 // deliberately frozen pending cross-SDK agreement with
                 // macp-sdk-python.
-                if (task && task.assignee === undefined) {
+                if (task && this.activeAssignment === undefined) {
                     task.assignee = record.assignee;
                     task.status = 'accepted';
+                    this.activeAssignment = { sender: envelope.sender, taskId: record.taskId };
+                    this.phase = 'InProgress';
                 }
-                this.phase = 'InProgress';
                 break;
             }
             case 'TaskReject': {
                 const record = payload;
                 const task = this.tasks.get(record.taskId);
-                // Deliberately does not clear `task.assignee`: rule 3c's
-                // policy-gated reassignment path is not modelled here (see the
-                // `TaskAccept` case above), so `assignee` is treated as sticky once
-                // set, per rule 3b's default ("irrevocable unless policy explicitly
-                // permits reassignment").
                 if (task)
                     task.status = 'rejected';
+                // RFC-MACP-0009 §5 rule 3c (`:72`): "When policy sets
+                // `allow_reassignment_on_reject: true` and the active assignee sends
+                // `TaskReject`, the session returns to the pre-assignment state. Other
+                // eligible participants MAY then send `TaskAccept` for the same
+                // `task_id`." Mirrors `macp-runtime`
+                // `crates/macp-modes/src/mode/task.rs:257-260`, which clears
+                // `active_assignee` only when the ACTIVE assignee is the rejecter —
+                // a reject from anyone else never frees the slot (`task.rs:241-244`
+                // rejects it as `InvalidPayload`).
+                //
+                // Deliberately NOT gated on the session policy, and it does not need
+                // to be. The runtime gates the reassignment twice — it denies the
+                // active assignee's `TaskReject` (`task.rs:223-239`) and the follow-up
+                // `TaskAccept` (`task.rs:187-204`) with `PolicyDenied` when
+                // `allow_reassignment_on_reject` is false — and a projection is a view
+                // of history the runtime ALREADY ACCEPTED (see this method's
+                // accepted-only input contract). A reassignment the runtime denied
+                // never reaches the transcript, so tracking the reject unconditionally
+                // cannot diverge from the runtime on any real transcript, and it needs
+                // no new API surface (threading a `PolicyDefinition` into the
+                // constructor would). Issue #70, option 2.
+                if (this.activeAssignment?.sender === envelope.sender) {
+                    const held = this.tasks.get(this.activeAssignment.taskId);
+                    if (held)
+                        held.assignee = undefined;
+                    this.activeAssignment = undefined;
+                }
                 break;
             }
             case 'TaskUpdate': {

package/dist/validation.d.ts

@@ -5,6 +5,26 @@ export declare function validateConfidence(value: number): void;
 export declare function validateSeverity(value: string): string;
 export declare function validateParticipantCount(count: number): void;
 export declare function validateSignalType(signalType: string, data?: Buffer | Uint8Array): void;
+/**
+ * Validate the `Progress` scope pairing (RFC-MACP-0001 §6).
+ *
+ * `Progress` is legal in exactly two shapes — ambient (`sessionId` and `mode`
+ * both empty) or session-scoped (both non-empty). An envelope with exactly one
+ * of the two empty is a mixed shape that the runtime rejects with
+ * `INVALID_ENVELOPE`; raising here names the mismatched field instead.
+ *
+ * Unlike Signals, `Progress` is *not* required to be ambient — this is a
+ * tri-state rule, so neither field may be inferred from the other.
+ *
+ * The emptiness test deliberately mirrors `macp-runtime`'s
+ * `validate_envelope_shape` **exactly**, including its asymmetry: `sessionId`
+ * is compared raw while `mode` is trimmed first. Mirroring rather than
+ * normalising is the only choice under which the SDK neither accepts a shape
+ * the runtime rejects nor rejects one it accepts. Concretely, a
+ * whitespace-only `mode` alongside an empty `sessionId` is ambient to the
+ * runtime, so it stays ambient here.
+ */
+export declare function validateProgressScope(sessionId: string, mode: string): void;
 export declare function validateTtlMs(ttlMs: number): void;
 export declare function validateMaxSuspendMs(maxSuspendMs: number): void;
 export declare function validateParticipants(participants: string[]): void;

package/dist/validation.js

@@ -7,6 +7,7 @@ exports.validateConfidence = validateConfidence;
 exports.validateSeverity = validateSeverity;
 exports.validateParticipantCount = validateParticipantCount;
 exports.validateSignalType = validateSignalType;
+exports.validateProgressScope = validateProgressScope;
 exports.validateTtlMs = validateTtlMs;
 exports.validateMaxSuspendMs = validateMaxSuspendMs;
 exports.validateParticipants = validateParticipants;
@@ -61,6 +62,37 @@ function validateSignalType(signalType, data) {
         throw new errors_1.MacpSessionError('signalType must be non-empty when data is present');
     }
 }
+/**
+ * Validate the `Progress` scope pairing (RFC-MACP-0001 §6).
+ *
+ * `Progress` is legal in exactly two shapes — ambient (`sessionId` and `mode`
+ * both empty) or session-scoped (both non-empty). An envelope with exactly one
+ * of the two empty is a mixed shape that the runtime rejects with
+ * `INVALID_ENVELOPE`; raising here names the mismatched field instead.
+ *
+ * Unlike Signals, `Progress` is *not* required to be ambient — this is a
+ * tri-state rule, so neither field may be inferred from the other.
+ *
+ * The emptiness test deliberately mirrors `macp-runtime`'s
+ * `validate_envelope_shape` **exactly**, including its asymmetry: `sessionId`
+ * is compared raw while `mode` is trimmed first. Mirroring rather than
+ * normalising is the only choice under which the SDK neither accepts a shape
+ * the runtime rejects nor rejects one it accepts. Concretely, a
+ * whitespace-only `mode` alongside an empty `sessionId` is ambient to the
+ * runtime, so it stays ambient here.
+ */
+function validateProgressScope(sessionId, mode) {
+    const sessionIdEmpty = sessionId === '';
+    const modeEmpty = mode.trim() === '';
+    if (sessionIdEmpty === modeEmpty)
+        return;
+    const detail = sessionIdEmpty
+        ? `mode is ${JSON.stringify(mode)} but sessionId is empty`
+        : `sessionId is ${JSON.stringify(sessionId)} but mode is empty`;
+    throw new errors_1.MacpSessionError(`Progress must be either ambient (sessionId and mode both empty) or session-scoped ` +
+        `(both non-empty), but ${detail} (RFC-MACP-0001 §6). ` +
+        'Pass both fields for a session-scoped Progress, or neither for an ambient one.');
+}
 const MAX_TTL_MS = 86_400_000; // 24 hours
 function validateTtlMs(ttlMs) {
     if (!Number.isFinite(ttlMs) || ttlMs < 1 || ttlMs > MAX_TTL_MS) {

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

package/package.json

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