@taasky/protocol 0.0.0-stage → 0.1.1

package/dist/subject.js

@@ -0,0 +1,186 @@
+// The free half (SPEC.md §4). The protocol does not know what is being
+// negotiated; each party declares the shape of its own subject when it enters
+// the room, and that declaration is what the peer validates against and what
+// the confirmation card renders from.
+//
+// Validation is strict: an unknown field rejects the whole message rather than
+// being ignored, because an ignored field is a place for text to hide.
+const MAX_FIELDS = 24;
+const MAX_STRING = 500;
+const MAX_ITEMS = 32;
+export class SubjectError extends Error {
+}
+function fail(path, why) {
+    throw new SubjectError(`${path}: ${why}`);
+}
+export function parseSchema(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        fail("subject_schema", "must be an object of field declarations");
+    }
+    const entries = Object.entries(raw);
+    if (entries.length === 0)
+        fail("subject_schema", "declares no fields");
+    if (entries.length > MAX_FIELDS) {
+        fail("subject_schema", `declares more than ${MAX_FIELDS} fields`);
+    }
+    const schema = {};
+    for (const [name, decl] of entries) {
+        const at = `subject_schema.${name}`;
+        if (!/^[a-z][a-z0-9_]{0,31}$/.test(name))
+            fail(at, "invalid field name: use a-z, 0-9 and _, starting with a letter, at most 32 characters " +
+                '(e.g. "meeting_time"). Put the human wording, in any language, in `label`');
+        if (decl === null || typeof decl !== "object")
+            fail(at, "must be an object");
+        const d = decl;
+        const type = d.type;
+        if (type !== "string" &&
+            type !== "int" &&
+            type !== "bool" &&
+            type !== "timerange" &&
+            type !== "enum" &&
+            type !== "money" &&
+            type !== "date") {
+            fail(at, "unknown type");
+        }
+        if (typeof d.label !== "string" || d.label.length === 0 || d.label.length > 80) {
+            fail(at, "label must be a string of 1..80 chars");
+        }
+        if (type === "enum") {
+            if (!Array.isArray(d.values) || d.values.length < 2 || d.values.length > 32) {
+                fail(at, "enum needs 2..32 values");
+            }
+            if (!d.values.every((v) => typeof v === "string" && v.length <= 40)) {
+                fail(at, "enum values must be short strings");
+            }
+        }
+        if (d.currency !== undefined && (type !== "money" || !isCurrency(d.currency))) {
+            fail(at, "currency is a three-letter ISO 4217 code, for money fields only");
+        }
+        schema[name] = {
+            type,
+            label: d.label,
+            optional: d.optional === true,
+            repeated: d.repeated === true,
+            values: type === "enum" ? d.values : undefined,
+            currency: type === "money" ? d.currency : undefined,
+            max_len: type === "string"
+                ? Math.min(typeof d.max_len === "number" ? d.max_len : MAX_STRING, MAX_STRING)
+                : undefined,
+        };
+    }
+    return schema;
+}
+const isCurrency = (code) => typeof code === "string" && /^[A-Z]{3}$/.test(code);
+/** Digits after the point for a currency: 2 for EUR, 0 for JPY, 3 for KWD. */
+export function minorDigits(currency) {
+    return new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions()
+        .maximumFractionDigits;
+}
+/** YYYY-MM-DD that names a real day: no 2026-02-30. */
+function isDate(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const d = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().startsWith(value);
+}
+function checkScalar(decl, value, at) {
+    switch (decl.type) {
+        case "string":
+            if (typeof value !== "string")
+                fail(at, "expected string");
+            if (value.length > (decl.max_len ?? MAX_STRING))
+                fail(at, "string too long");
+            return;
+        case "int":
+            if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+                fail(at, "expected integer");
+            }
+            return;
+        case "bool":
+            if (typeof value !== "boolean")
+                fail(at, "expected boolean");
+            return;
+        case "enum":
+            if (typeof value !== "string" || !decl.values.includes(value)) {
+                fail(at, "value outside declared set");
+            }
+            return;
+        case "date":
+            if (!isDate(value))
+                fail(at, "expected a date, YYYY-MM-DD");
+            return;
+        case "money": {
+            // Amount as a decimal string, so no float ever stands between the
+            // number an agent meant and the one a human confirms.
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                fail(at, "expected {amount, currency}");
+            }
+            const keys = Object.keys(value);
+            if (keys.length !== 2 || !keys.includes("amount") || !keys.includes("currency")) {
+                fail(at, "money takes exactly amount and currency");
+            }
+            const { amount, currency } = value;
+            if (!isCurrency(currency))
+                fail(at, "currency must be a three-letter ISO 4217 code");
+            if (decl.currency && currency !== decl.currency)
+                fail(at, `currency must be ${decl.currency}`);
+            const digits = minorDigits(currency);
+            const shape = digits ? `^\\d{1,15}(\\.\\d{1,${digits}})?$` : "^\\d{1,15}$";
+            if (typeof amount !== "string" || !new RegExp(shape).test(amount)) {
+                fail(at, `amount must be a decimal string with at most ${digits} digits after the point`);
+            }
+            return;
+        }
+        case "timerange": {
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                fail(at, "expected {start, end}");
+            }
+            const keys = Object.keys(value);
+            if (keys.length !== 2 || !keys.includes("start") || !keys.includes("end")) {
+                fail(at, "timerange takes exactly start and end");
+            }
+            const { start, end } = value;
+            const s = typeof start === "string" ? Date.parse(start) : NaN;
+            const e = typeof end === "string" ? Date.parse(end) : NaN;
+            if (Number.isNaN(s) || Number.isNaN(e))
+                fail(at, "start/end must be RFC3339");
+            if (e <= s)
+                fail(at, "end must follow start");
+            return;
+        }
+    }
+}
+/** Validates a subject against a declared schema. Throws on the first problem. */
+export function validateSubject(schema, subject) {
+    if (subject === null || typeof subject !== "object" || Array.isArray(subject)) {
+        fail("subject", "must be an object");
+    }
+    const value = subject;
+    for (const key of Object.keys(value)) {
+        if (!(key in schema))
+            fail(`subject.${key}`, "not in the declared schema");
+    }
+    for (const [name, decl] of Object.entries(schema)) {
+        const at = `subject.${name}`;
+        const v = value[name];
+        if (v === undefined || v === null) {
+            if (!decl.optional)
+                fail(at, "required field missing");
+            continue;
+        }
+        if (decl.repeated) {
+            if (!Array.isArray(v))
+                fail(at, "expected an array");
+            if (v.length === 0)
+                fail(at, "array is empty");
+            if (v.length > MAX_ITEMS)
+                fail(at, `more than ${MAX_ITEMS} items`);
+            for (const [i, item] of v.entries())
+                checkScalar(decl, item, `${at}[${i}]`);
+        }
+        else {
+            checkScalar(decl, v, at);
+        }
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@taasky/protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Taasky Negotiation Protocol: a spec and reference implementation for two agents negotiating terms their humans confirm.",
+  "license": "Apache-2.0",
+  "author": "Taasky",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taasky/protocol.git"
+  },
+  "homepage": "https://github.com/taasky/protocol#readme",
+  "bugs": {
+    "url": "https://github.com/taasky/protocol/issues"
+  },
+  "keywords": [
+    "agents",
+    "negotiation",
+    "mcp",
+    "agent-to-agent",
+    "protocol"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "schema",
+    "vectors",
+    "SPEC.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "fix": "biome check --write .",
+    "test": "vitest run",
+    "check": "biome check . && tsc --noEmit && vitest run",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@types/node": "24.0.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  }
+}

package/schema/envelope.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/taasky/protocol/schema/envelope.schema.json",
+  "title": "Envelope",
+  "description": "One move in a room (SPEC.md §3). The relay reads this half; `subject` is validated against the sender's declared subject schema, not here.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "v",
+    "room",
+    "msg",
+    "from",
+    "round",
+    "verdict",
+    "in_reply_to",
+    "subject_hash",
+    "deadline",
+    "ts",
+    "subject"
+  ],
+  "properties": {
+    "v": { "const": 1, "description": "Protocol major version." },
+    "room": { "type": "string", "minLength": 1 },
+    "msg": { "type": "string", "minLength": 1, "description": "Unique per room." },
+    "from": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Assigned by the relay, never echoed from the sender."
+    },
+    "round": { "type": "integer", "minimum": 0 },
+    "verdict": { "enum": ["offer", "counter", "need_more_detail", "approve", "reject", "cancel"] },
+    "in_reply_to": { "type": ["string", "null"] },
+    "subject_hash": { "type": ["string", "null"], "pattern": "^sha256:[0-9a-f]{64}$" },
+    "deadline": { "type": ["string", "null"], "format": "date-time" },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Set by the relay on receipt."
+    },
+    "subject": { "type": ["object", "null"] }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "verdict": { "enum": ["offer", "counter"] } } },
+      "then": {
+        "properties": { "subject": { "type": "object" }, "subject_hash": { "type": "string" } }
+      },
+      "else": { "properties": { "subject": { "type": "null" } } }
+    },
+    {
+      "if": { "properties": { "verdict": { "const": "approve" } } },
+      "then": {
+        "properties": { "subject_hash": { "type": "string" }, "in_reply_to": { "type": "string" } }
+      }
+    }
+  ]
+}

package/schema/limits.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/taasky/protocol/schema/limits.schema.json",
+  "title": "Private limits",
+  "description": "A party's bounds per field of its own subject schema (SPEC.md §7). Seen by the relay only. Which shape a field takes, and what its bounds look like, follows from the field's declared type: min/max for int, money, date and timerange; one_of for enum; equals for bool; nothing for string.",
+  "type": "object",
+  "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,31}$" },
+  "additionalProperties": {
+    "oneOf": [
+      {
+        "type": "object",
+        "additionalProperties": false,
+        "minProperties": 1,
+        "properties": { "min": {}, "max": {} }
+      },
+      {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["one_of"],
+        "properties": {
+          "one_of": { "type": "array", "minItems": 1, "items": { "type": "string" } }
+        }
+      },
+      {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["equals"],
+        "properties": { "equals": { "type": "boolean" } }
+      }
+    ]
+  }
+}

package/schema/subject-schema.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/taasky/protocol/schema/subject-schema.schema.json",
+  "title": "Subject schema",
+  "description": "The shape of a party's terms, declared when it opens or joins a room (SPEC.md §4). Labels are written by the counterparty and are untrusted text.",
+  "type": "object",
+  "minProperties": 1,
+  "maxProperties": 24,
+  "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,31}$" },
+  "additionalProperties": { "$ref": "#/$defs/field" },
+  "$defs": {
+    "field": {
+      "type": "object",
+      "required": ["type", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "enum": ["string", "int", "bool", "enum", "timerange", "date", "money"] },
+        "label": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "optional": { "type": "boolean" },
+        "repeated": { "type": "boolean", "description": "An array of 1 to 32 values of the type." },
+        "values": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 32,
+          "items": { "type": "string", "maxLength": 40 }
+        },
+        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+        "max_len": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Capped at 500 whatever is declared."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "enum" } } },
+          "then": { "required": ["values"] },
+          "else": { "not": { "required": ["values"] } }
+        },
+        {
+          "if": { "not": { "properties": { "type": { "const": "money" } } } },
+          "then": { "not": { "required": ["currency"] } }
+        }
+      ]
+    }
+  }
+}

package/vectors/canonical.json

@@ -0,0 +1,59 @@
+{
+  "description": "canonicalize(subject) sorts keys at every level, by UTF-16 code unit, and drops nothing but undefined; subject_hash is \"sha256:\" + hex SHA-256 of its UTF-8 bytes (SPEC.md §3).",
+  "cases": [
+    {
+      "name": "meeting terms",
+      "input": {
+        "slot": {
+          "start": "2026-10-14T10:00:00Z",
+          "end": "2026-10-14T10:30:00Z"
+        },
+        "duration_min": 30
+      },
+      "canonical": "{\"duration_min\":30,\"slot\":{\"end\":\"2026-10-14T10:30:00Z\",\"start\":\"2026-10-14T10:00:00Z\"}}",
+      "subject_hash": "sha256:a6819e25e6eec105881568b2a3d4e06f03bfac1b7b2c147bab87e6861af716c8"
+    },
+    {
+      "name": "same terms, keys in another order",
+      "input": {
+        "duration_min": 30,
+        "slot": {
+          "end": "2026-10-14T10:30:00Z",
+          "start": "2026-10-14T10:00:00Z"
+        }
+      },
+      "canonical": "{\"duration_min\":30,\"slot\":{\"end\":\"2026-10-14T10:30:00Z\",\"start\":\"2026-10-14T10:00:00Z\"}}",
+      "subject_hash": "sha256:a6819e25e6eec105881568b2a3d4e06f03bfac1b7b2c147bab87e6861af716c8"
+    },
+    {
+      "name": "money, arrays and booleans",
+      "input": {
+        "price": {
+          "currency": "EUR",
+          "amount": "1500.00"
+        },
+        "days": ["2026-11-02", "2026-11-03"],
+        "delivery": true
+      },
+      "canonical": "{\"days\":[\"2026-11-02\",\"2026-11-03\"],\"delivery\":true,\"price\":{\"amount\":\"1500.00\",\"currency\":\"EUR\"}}",
+      "subject_hash": "sha256:6b07e465b36a22ad60fa74d9cf311d5be4d7833a2db4ec7cb0624719f64c4910"
+    },
+    {
+      "name": "non-ASCII labels survive as UTF-8",
+      "input": {
+        "note": "Встреча в кафе",
+        "place": "café"
+      },
+      "canonical": "{\"note\":\"Встреча в кафе\",\"place\":\"café\"}",
+      "subject_hash": "sha256:485be4bc83fdadfd5b5bfaf71afed7818ff432b20acaaa9754bc35274dd16e66"
+    },
+    {
+      "name": "arrays keep their order",
+      "input": {
+        "days": ["2026-11-03", "2026-11-02"]
+      },
+      "canonical": "{\"days\":[\"2026-11-03\",\"2026-11-02\"]}",
+      "subject_hash": "sha256:f96c5ae801e9b3091f11a086f175b5beb1b35186d5b01b3355b66453f47b3c0a"
+    }
+  ]
+}

package/vectors/circling.json

@@ -0,0 +1,63 @@
+{
+  "description": "isCircling(history) (SPEC.md §7): the last 4 moves are all counter or need_more_detail, and none tabled terms not seen before them. Each move is [verdict, subject_hash or null].",
+  "cases": [
+    {
+      "name": "two positions, restated twice",
+      "moves": [
+        ["offer", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"],
+        ["counter", "h2"]
+      ],
+      "circling": true
+    },
+    {
+      "name": "one move short",
+      "moves": [
+        ["offer", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"]
+      ],
+      "circling": false
+    },
+    {
+      "name": "asking each other the same thing",
+      "moves": [
+        ["offer", "h1"],
+        ["need_more_detail", null],
+        ["need_more_detail", null],
+        ["need_more_detail", null],
+        ["need_more_detail", null]
+      ],
+      "circling": true
+    },
+    {
+      "name": "a small concession is progress",
+      "moves": [
+        ["offer", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"],
+        ["counter", "h3"]
+      ],
+      "circling": false
+    },
+    {
+      "name": "an approval in the window",
+      "moves": [
+        ["offer", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"],
+        ["approve", "h1"],
+        ["counter", "h2"],
+        ["counter", "h1"]
+      ],
+      "circling": false
+    }
+  ]
+}

package/vectors/limits.json

@@ -0,0 +1,138 @@
+{
+  "description": "Private limits (SPEC.md §7). check: where terms break one party's limits. cannot_meet: the fields on which two parties' limits leave no deal.",
+  "schema": {
+    "price": { "type": "money", "label": "Price", "currency": "EUR" },
+    "meeting_time": { "type": "timerange", "label": "Meeting time" },
+    "seats": { "type": "int", "label": "Seats" },
+    "pickup": { "type": "date", "label": "Pickup day" },
+    "place": { "type": "enum", "label": "Place", "values": ["office", "cafe", "online"] },
+    "delivery": { "type": "bool", "label": "Delivery" },
+    "note": { "type": "string", "label": "Note", "optional": true }
+  },
+  "invalid": [
+    { "name": "a field not in the schema", "limits": { "colour": { "max": 1 } } },
+    { "name": "a string field", "limits": { "note": { "max": 1 } } },
+    { "name": "min on an enum", "limits": { "place": { "max": "cafe" } } },
+    { "name": "an enum value that is not declared", "limits": { "place": { "one_of": ["moon"] } } },
+    {
+      "name": "another currency than the field's",
+      "limits": { "price": { "max": { "amount": "100", "currency": "USD" } } }
+    },
+    { "name": "min above max", "limits": { "seats": { "min": 5, "max": 4 } } },
+    { "name": "a bare number for money", "limits": { "price": { "max": 100 } } },
+    { "name": "a day that does not exist", "limits": { "pickup": { "min": "2026-02-30" } } }
+  ],
+  "check": [
+    {
+      "name": "inside, touching the bounds",
+      "limits": {
+        "price": { "max": { "amount": "100.00", "currency": "EUR" } },
+        "meeting_time": { "min": "2026-12-01T09:00:00+01:00", "max": "2026-12-01T18:00:00+01:00" },
+        "place": { "one_of": ["cafe", "online"] }
+      },
+      "subject": {
+        "price": { "amount": "100", "currency": "EUR" },
+        "meeting_time": {
+          "start": "2026-12-01T09:00:00+01:00",
+          "end": "2026-12-01T10:00:00+01:00"
+        },
+        "place": "cafe"
+      },
+      "breaches": []
+    },
+    {
+      "name": "every breach, with the bound it broke",
+      "limits": {
+        "price": { "max": { "amount": "100.00", "currency": "EUR" } },
+        "meeting_time": { "min": "2026-12-01T09:00:00+01:00", "max": "2026-12-01T18:00:00+01:00" },
+        "place": { "one_of": ["cafe", "online"] }
+      },
+      "subject": {
+        "price": { "amount": "100.01", "currency": "EUR" },
+        "meeting_time": {
+          "start": "2026-12-01T17:30:00+01:00",
+          "end": "2026-12-01T18:30:00+01:00"
+        },
+        "place": "office"
+      },
+      "breaches": [
+        {
+          "field": "price",
+          "rule": "above_max",
+          "bound": { "amount": "100.00", "currency": "EUR" }
+        },
+        { "field": "meeting_time", "rule": "above_max", "bound": "2026-12-01T18:00:00+01:00" },
+        { "field": "place", "rule": "not_allowed", "bound": ["cafe", "online"] }
+      ]
+    },
+    {
+      "name": "times compare across offsets",
+      "limits": { "meeting_time": { "min": "2026-12-01T09:00:00+01:00" } },
+      "subject": {
+        "meeting_time": { "start": "2026-12-01T08:30:00Z", "end": "2026-12-01T09:00:00Z" }
+      },
+      "breaches": []
+    },
+    {
+      "name": "amounts past 2^53 compare exactly",
+      "limits": { "price": { "max": { "amount": "999999999999999.99", "currency": "EUR" } } },
+      "subject": { "price": { "amount": "999999999999999.98", "currency": "EUR" } },
+      "breaches": []
+    },
+    {
+      "name": "below min, and a bool that is not the one asked for",
+      "limits": { "seats": { "min": 2 }, "delivery": { "equals": true } },
+      "subject": { "seats": 1, "delivery": false },
+      "breaches": [
+        { "field": "seats", "rule": "below_min", "bound": 2 },
+        { "field": "delivery", "rule": "not_equal", "bound": true }
+      ]
+    }
+  ],
+  "cannot_meet": [
+    {
+      "name": "a buyer's max below a seller's min",
+      "a": { "price": { "max": { "amount": "80.00", "currency": "EUR" } } },
+      "b": { "price": { "min": { "amount": "90.00", "currency": "EUR" } } },
+      "fields": ["price"]
+    },
+    {
+      "name": "a max equal to a min is a deal",
+      "a": { "price": { "max": { "amount": "80.00", "currency": "EUR" } } },
+      "b": { "price": { "min": { "amount": "80", "currency": "EUR" } } },
+      "fields": []
+    },
+    {
+      "name": "a meeting needs time between start and end",
+      "a": { "meeting_time": { "max": "2026-12-01T12:00:00Z" } },
+      "b": { "meeting_time": { "min": "2026-12-01T12:00:00Z" } },
+      "fields": ["meeting_time"]
+    },
+    {
+      "name": "enums, bools and dates",
+      "a": {
+        "place": { "one_of": ["office"] },
+        "delivery": { "equals": true },
+        "pickup": { "max": "2026-12-01" }
+      },
+      "b": {
+        "place": { "one_of": ["cafe"] },
+        "delivery": { "equals": false },
+        "pickup": { "min": "2026-12-02" }
+      },
+      "fields": ["place", "delivery", "pickup"]
+    },
+    {
+      "name": "one side set no limits",
+      "a": { "price": { "max": { "amount": "1.00", "currency": "EUR" } } },
+      "b": null,
+      "fields": []
+    },
+    {
+      "name": "two maxes always meet",
+      "a": { "seats": { "max": 2 } },
+      "b": { "seats": { "max": 1 } },
+      "fields": []
+    }
+  ]
+}