macp-sdk-typescript 0.11.0 → 0.12.0

package/dist/proto-registry.js

@@ -170,7 +170,13 @@ class ProtoRegistry {
      * Decode an `ext.multi_round.v1` `Contribute` payload, accepting both wire
      * formats: legacy JSON (`{"value":"..."}`, still replayed verbatim from
      * pre-proto histories) and canonical protobuf (`ContributePayload`). Both
-     * normalize to `{ value: string }`.
+     * normalize to `{ value }`, but only the protobuf path's `value` is always
+     * a `string` — the legacy-JSON path passes `parsed.value` through exactly
+     * as `JSON.parse` produced it (issue #124: no `String(...)` coercion, no
+     * `?? ''` fallback for an absent key), so `value` may be `undefined`,
+     * `null`, a number, a boolean, or an object/array for malformed-but-valid
+     * legacy JSON. This method's own contract is observational, not a gate —
+     * see the `contribute_acceptance` note below.
      *
      * Parse-then-fallback (issue #93), not a first-byte shortcut: JSON is always
      * attempted first, and only a `JSON.parse` failure falls through to
@@ -178,8 +184,27 @@ class ProtoRegistry {
      * not generalize — e.g. legacy JSON with leading whitespace has neither byte
      * first, and used to reach `decodeMessage` and throw. Parity with
      * `macp-sdk-python`'s `_decode_json_first_then_proto`, which has always
-     * worked this way. Safe because a canonical proto payload's bytes are
-     * essentially never also syntactically valid JSON.
+     * worked this way.
+     *
+     * **A successful `JSON.parse` is not proof the bytes are legacy JSON**
+     * (issue #104 — this method's prior "essentially never also syntactically
+     * valid JSON" claim was false, not merely imprecise): the canonical proto
+     * tag byte for field 1 (`0x0A`) is itself insignificant JSON whitespace, so
+     * for specific value byte-lengths the length varint — or, when the varint
+     * is itself whitespace, the value's own leading byte — becomes the first
+     * significant character `JSON.parse` sees, and a genuine `ContributePayload`
+     * silently misreads as a JSON number/string/object. Verified directly
+     * (encode-then-decode sweep, value lengths 1-127, seven value shapes): every
+     * one of lengths 9, 10, 13, 32, 34, 45, 48, 49-57, and 123 corrupted before
+     * `isCanonicalProto` below, most to total silent data loss
+     * (`String(undefined ?? '') === ''`), zero corrupt after.
+     *
+     * `isCanonicalProto` resolves the ambiguity by tie-break, not by refusing
+     * to try JSON first: bytes that parse as JSON *and* are the exact canonical
+     * proto encoding are treated as proto. This has a narrow, priced cost on
+     * the reverse direction (legacy JSON misread as proto) that it introduces
+     * rather than merely fails to close — see `isCanonicalProto`'s own
+     * docblock.
      *
      * An empty payload falls through the same path: `JSON.parse('')` throws, so
      * it reaches `decodeMessage` on zero bytes, which yields `{}` (proto3
@@ -192,10 +217,63 @@ class ProtoRegistry {
     decodeMultiRoundContribute(payload) {
         try {
             const parsed = JSON.parse(payload.toString('utf8'));
-            return { value: typeof parsed.value === 'string' ? parsed.value : String(parsed.value ?? '') };
+            if (!this.isCanonicalProto(MULTI_ROUND_CONTRIBUTE, payload)) {
+                return { value: parsed.value };
+            }
+        }
+        catch {
+            // Not JSON at all — fall through to the protobuf decode below.
+        }
+        return this.decodeMessage(MULTI_ROUND_CONTRIBUTE, payload);
+    }
+    /**
+     * True iff `payload` is the exact canonical protobuf encoding of
+     * `typeName` — used to break the JSON/proto ambiguity in
+     * `decodeMultiRoundContribute` (issue #104): bytes that both parse as JSON
+     * *and* round-trip byte-identically through the proto message are treated
+     * as proto, not JSON.
+     *
+     * `macp-sdk-python`'s equivalent (`_is_canonical_proto`) needs an explicit
+     * `DiscardUnknownFields()` step before comparing, because Python's protobuf
+     * runtime preserves unknown fields verbatim through
+     * `ParseFromString`/`SerializeToString` by default — without it, a plain
+     * round-trip check misclassified several whitespace-prefixed legacy-JSON
+     * payloads as canonical proto. **`protobufjs` needs no equivalent step**:
+     * verified directly (a synthetic payload with a declared field-1 string
+     * plus an undeclared field 2) that `Type.decode()` silently drops fields
+     * not in the schema rather than preserving them, so `Type.encode()` can
+     * never reproduce bytes it never captured — a byte-exact round-trip here
+     * is already proof the payload is *exactly* the single-field encoding, no
+     * unknown fields possible. Confirmed this closes the same
+     * whitespace-prefixed false-positive class `DiscardUnknownFields` closes
+     * in Python (tab/space-prefixed legacy JSON at several lengths).
+     *
+     * One narrow, symmetric residual survives regardless — genuinely
+     * irreducible, not a gap this check merely fails to close: a payload whose
+     * first byte is a literal `0x0A` (`\n`) and whose remainder forms a
+     * complete, well-formed proto field-1 string with nothing left over has no
+     * unknown field for either implementation to expose a mismatch on, because
+     * it *is*, byte for byte, both a legal JSON reading and the canonical
+     * proto encoding of some (possibly nonsensical) string. Verified instances
+     * (this SDK's own `JSON.stringify`, which — unlike Python's `json.dumps`
+     * — omits the space after `:`, shifting the colliding lengths by one byte
+     * from `macp-sdk-python`'s pinned cases): `'\n' + JSON.stringify({value:
+     * 'z'.repeat(112)})`, and with one extra whitespace byte inserted after the
+     * `\n`, `'\r'` at value length 1 and `' '` at value length 20. A real
+     * legacy-JSON sender would need to deliberately prefix with a literal
+     * newline byte for this to matter — this SDK's own JSON producers never
+     * emit one — so the trade (fixing the ordinary, naturally-reachable
+     * forward-direction corruption above at the cost of this adversarial,
+     * unreachable-by-any-known-encoder reverse case) is the right one.
+     */
+    isCanonicalProto(typeName, payload) {
+        try {
+            const type = this.lookupType(typeName);
+            const decoded = type.decode(payload);
+            return Buffer.from(type.encode(decoded).finish()).equals(payload);
         }
         catch {
-            return this.decodeMessage(MULTI_ROUND_CONTRIBUTE, payload);
+            return false;
         }
     }
     lookupType(typeName) {

package/dist/quorum.d.ts

@@ -32,6 +32,7 @@ export declare class QuorumSession {
         }[];
         maxSuspendMs?: number;
         sender?: string;
+        auth?: AuthConfig;
     }): Promise<Ack>;
     requestApproval(input: ApprovalRequestPayload & {
         sender?: string;

package/dist/quorum.js

@@ -60,15 +60,15 @@ class QuorumSession {
             mode: constants_1.MODE_QUORUM,
             messageType: 'SessionStart',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender),
+            sender: this.senderFor(input.sender, input.auth),
             payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_QUORUM, 'SessionStart', (0, envelope_1.toProtoPayload)(payload)),
         });
-        return this.sendAndTrack(envelope, this.auth);
+        return this.sendAndTrack(envelope, input.auth ?? this.auth);
     }
     async requestApproval(input) {
         (0, validation_1.validateRequiredField)('requestId', input.requestId);
-        (0, validation_1.validateRequiredField)('action', input.action);
-        (0, validation_1.validateRequiredField)('summary', input.summary);
+        // `action`/`summary` are proto3 singular string fields (implicit
+        // presence) -- no client-side non-empty check here (issue #124 item 3).
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_QUORUM,
             messageType: 'ApprovalRequest',

package/dist/task.d.ts

@@ -32,6 +32,7 @@ export declare class TaskSession {
         }[];
         maxSuspendMs?: number;
         sender?: string;
+        auth?: AuthConfig;
     }): Promise<Ack>;
     requestTask(input: TaskRequestPayload & {
         sender?: string;

package/dist/task.js

@@ -60,15 +60,16 @@ class TaskSession {
             mode: constants_1.MODE_TASK,
             messageType: 'SessionStart',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender),
+            sender: this.senderFor(input.sender, input.auth),
             payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'SessionStart', (0, envelope_1.toProtoPayload)(payload)),
         });
-        return this.sendAndTrack(envelope, this.auth);
+        return this.sendAndTrack(envelope, input.auth ?? this.auth);
     }
     async requestTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
         (0, validation_1.validateRequiredField)('title', input.title);
-        (0, validation_1.validateRequiredField)('instructions', input.instructions);
+        // `instructions` is a proto3 singular string field (implicit presence) --
+        // no client-side non-empty check here (issue #124 item 3).
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
             messageType: 'TaskRequest',
@@ -80,23 +81,31 @@ class TaskSession {
     }
     async acceptTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
+        const sender = this.senderFor(input.sender, input.auth);
+        // Issue #108.5/4e: default assignee to the resolved sender, matching
+        // Python (`task.py:299,323,391,430`). `||` not `??` — an explicit empty
+        // string is never a meaningful assignee, and the reported gap includes
+        // that case, which `??` would let through unchanged.
+        const assignee = input.assignee || sender;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
             messageType: 'TaskAccept',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskAccept', (0, envelope_1.toProtoPayload)(input)),
+            sender,
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskAccept', (0, envelope_1.toProtoPayload)({ ...input, assignee })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }
     async rejectTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
+        const sender = this.senderFor(input.sender, input.auth);
+        const assignee = input.assignee || sender;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
             messageType: 'TaskReject',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskReject', (0, envelope_1.toProtoPayload)(input)),
+            sender,
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskReject', (0, envelope_1.toProtoPayload)({ ...input, assignee })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }
@@ -113,23 +122,27 @@ class TaskSession {
     }
     async completeTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
+        const sender = this.senderFor(input.sender, input.auth);
+        const assignee = input.assignee || sender;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
             messageType: 'TaskComplete',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskComplete', (0, envelope_1.toProtoPayload)(input)),
+            sender,
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskComplete', (0, envelope_1.toProtoPayload)({ ...input, assignee })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }
     async failTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
+        const sender = this.senderFor(input.sender, input.auth);
+        const assignee = input.assignee || sender;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
             messageType: 'TaskFail',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskFail', (0, envelope_1.toProtoPayload)(input)),
+            sender,
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_TASK, 'TaskFail', (0, envelope_1.toProtoPayload)({ ...input, assignee })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }

package/dist/types.d.ts

@@ -217,12 +217,14 @@ export interface TaskRequestPayload {
 }
 export interface TaskAcceptPayload {
     taskId: string;
-    assignee: string;
+    /** Defaults to the resolved sender when omitted or empty (issue #108.5). */
+    assignee?: string;
     reason?: string;
 }
 export interface TaskRejectPayload {
     taskId: string;
-    assignee: string;
+    /** Defaults to the resolved sender when omitted or empty (issue #108.5). */
+    assignee?: string;
     reason?: string;
 }
 export interface TaskUpdatePayload {
@@ -234,13 +236,15 @@ export interface TaskUpdatePayload {
 }
 export interface TaskCompletePayload {
     taskId: string;
-    assignee: string;
+    /** Defaults to the resolved sender when omitted or empty (issue #108.5). */
+    assignee?: string;
     output?: Buffer;
     summary?: string;
 }
 export interface TaskFailPayload {
     taskId: string;
-    assignee: string;
+    /** Defaults to the resolved sender when omitted or empty (issue #108.5). */
+    assignee?: string;
     errorCode?: string;
     reason?: string;
     retryable?: boolean;
@@ -253,12 +257,14 @@ export interface HandoffOfferPayload {
 }
 export interface HandoffContextPayload {
     handoffId: string;
-    contentType: string;
+    /** Defaults to 'application/octet-stream' when omitted (issue #108.6). */
+    contentType?: string;
     context?: Buffer;
 }
 export interface HandoffAcceptPayload {
     handoffId: string;
-    acceptedBy: string;
+    /** Defaults to the resolved sender when omitted or empty (issue #108.5). */
+    acceptedBy?: string;
     reason?: string;
     /**
      * Runtime-emitted synthetic accepts ONLY (RFC-MACP-0010 §5.1): `true` on the
@@ -272,7 +278,8 @@ export interface HandoffAcceptPayload {
 }
 export interface HandoffDeclinePayload {
     handoffId: string;
-    declinedBy: string;
+    /** Defaults to the resolved sender when omitted or empty (issue #108.5). */
+    declinedBy?: string;
     reason?: string;
 }
 export interface ApprovalRequestPayload {

package/dist/validation.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Validate that `sid` is a lowercase UUID v4/v7 or base64url (22+ chars).
+ *
+ * Mirrors the runtime's **no-fall-through** rule (issue #108.1, and
+ * `macp-sdk-python`'s `validate_session_id`, `validation.py:33-58`, which
+ * this ports verbatim in shape): a string with the *structural* shape of a
+ * UUID (36 chars, hyphens at 8-13-18-23, hex-only) is validated strictly as
+ * a lowercase v4/v7 UUID — it is never reinterpreted as base64url, which
+ * would otherwise let an uppercase, wrong-version, or bad-variant UUID slip
+ * through since it also happens to satisfy the base64url charset. A single
+ * combined regex cannot express this: the absence of fall-through is itself
+ * the rule. Only a string that is not UUID-shaped at all reaches the
+ * base64url branch.
+ */
 export declare function validateSessionId(sid: string): void;
 export declare function validateVote(value: string): string;
 export declare function validateRecommendation(value: string): string;

package/dist/validation.js

@@ -15,12 +15,36 @@ exports.validateRequiredField = validateRequiredField;
 exports.validateCommitmentHash = validateCommitmentHash;
 exports.validateSessionStart = validateSessionStart;
 const errors_1 = require("./errors");
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+// A string with the structural shape of a UUID (36 chars, hyphens at
+// 8-13-18-23, hex-only otherwise) — case-insensitive, any version/variant.
+const UUID_SHAPE_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+// Strict lowercase UUID v4/v7 (version nibble 4 or 7, RFC 9562 variant 8/9/a/b).
+const UUID_V4V7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const BASE64URL_RE = /^[A-Za-z0-9_-]{22,}$/;
+/**
+ * Validate that `sid` is a lowercase UUID v4/v7 or base64url (22+ chars).
+ *
+ * Mirrors the runtime's **no-fall-through** rule (issue #108.1, and
+ * `macp-sdk-python`'s `validate_session_id`, `validation.py:33-58`, which
+ * this ports verbatim in shape): a string with the *structural* shape of a
+ * UUID (36 chars, hyphens at 8-13-18-23, hex-only) is validated strictly as
+ * a lowercase v4/v7 UUID — it is never reinterpreted as base64url, which
+ * would otherwise let an uppercase, wrong-version, or bad-variant UUID slip
+ * through since it also happens to satisfy the base64url charset. A single
+ * combined regex cannot express this: the absence of fall-through is itself
+ * the rule. Only a string that is not UUID-shaped at all reaches the
+ * base64url branch.
+ */
 function validateSessionId(sid) {
-    if (!UUID_RE.test(sid) && !BASE64URL_RE.test(sid)) {
-        throw new errors_1.MacpSessionError(`session_id must be UUID v4/v7 or base64url (22+ chars), got: ${sid}`);
+    if (UUID_SHAPE_RE.test(sid)) {
+        if (!UUID_V4V7_RE.test(sid)) {
+            throw new errors_1.MacpSessionError(`session_id is UUID-shaped but not a lowercase v4/v7 UUID (no fall-through to base64url), got: ${sid}`);
+        }
+        return;
     }
+    if (BASE64URL_RE.test(sid))
+        return;
+    throw new errors_1.MacpSessionError(`session_id must be a lowercase UUID v4/v7 or base64url (22+ chars), got: ${sid}`);
 }
 const VALID_VOTES = new Set(['APPROVE', 'REJECT', 'ABSTAIN']);
 function validateVote(value) {
@@ -39,7 +63,13 @@ function validateRecommendation(value) {
     return normalized;
 }
 function validateConfidence(value) {
-    if (value < 0.0 || value > 1.0) {
+    // `Number.isFinite` (matching this file's own `ttlMs`/`maxSuspendMs`
+    // idiom) rather than two range comparisons alone: `NaN < 0` and
+    // `NaN > 1.0` are both `false`, so a bare range check silently *accepts*
+    // `NaN` (issue #108.2) — verified by execution before this fix. `Infinity`
+    // was already rejected incidentally (`Infinity > 1.0`); this also rejects
+    // it explicitly rather than by accident.
+    if (!Number.isFinite(value) || value < 0.0 || value > 1.0) {
         throw new errors_1.MacpSessionError(`confidence must be in [0.0, 1.0], got ${value}`);
     }
 }
@@ -131,7 +161,11 @@ function validateCommitmentHash(value, field = 'commitmentHash') {
     }
 }
 function validateSessionStart(input) {
-    validateRequiredField('intent', input.intent);
+    // `intent` is a proto3 singular string field (implicit presence -- an
+    // omitted field and an explicit "" serialize identically on the wire), and
+    // RFC-MACP-0001 §7.1 states a runtime "MUST NOT reject a SessionStart
+    // solely because intent is empty" -- no client-side non-empty check here
+    // (issue #124 item 3).
     validateParticipants(input.participants);
     validateTtlMs(input.ttlMs);
     if (input.maxSuspendMs !== undefined)

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -20,7 +20,8 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "check": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit && npm run check:examples",
+    "check:examples": "tsc -p tsconfig.examples.json",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts' --ignore-unknown",