claude-multiacc 1.0.21 → 2.0.0

package/lib/selector_primitives.py

@@ -0,0 +1,201 @@
+"""Strict transport, normalization, and RFC 8785 primitives for pool-selection.v2."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+import unicodedata
+from datetime import datetime, timezone
+from decimal import Decimal, InvalidOperation
+
+SCHEMA = "claude-multiacc/pool-selection.v2"
+SELECTOR_VERSION = "2.0.0"
+TIME_RE = re.compile(
+    r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-5][0-9]"
+    r"(\.[0-9]{1,6})?(Z|[+-][0-9]{2}:[0-9]{2})$")
+DECIMAL_RE = re.compile(r"^-?(0|[1-9][0-9]*)(\.[0-9]+)?$")
+SAFE_INTEGER = 9_007_199_254_740_991
+MAX_PLAIN_DECIMAL_PLACES = 10_000
+IDENTITY_KEYS = {"runner_id", "runner_generation", "engine", "account_id"}
+CANDIDATE_KEYS = IDENTITY_KEYS | {
+    "status", "weekly_pct", "session_pct", "resets_at", "limited_until", "seen_at",
+    "provider_capable", "reservation_history"}
+REQUEST_KEYS = {
+    "schema", "database_now", "policy", "required_engine", "producer_identity",
+    "excluded_identities", "candidates", "reservation_key"}
+POLICIES = {
+    "default_claude", "default_codex", "default_both", "explicit", "producer_retry", "reviewer"}
+
+
+def timestamp(value: object) -> tuple[datetime, str]:
+    if not isinstance(value, str) or not TIME_RE.fullmatch(value):
+        raise ValueError("invalid timestamp")
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        utc = parsed.astimezone(timezone.utc).replace(tzinfo=None)
+    except (ValueError, OverflowError) as error:
+        raise ValueError("invalid timestamp") from error
+    return parsed, utc.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def decimal_value(value: object) -> tuple[Decimal | None, str | None]:
+    if isinstance(value, bool) or value is None:
+        return None, None
+    if isinstance(value, str) and not DECIMAL_RE.fullmatch(value):
+        return None, None
+    try:
+        parsed = Decimal(str(value))
+        if not parsed.is_finite() or (isinstance(value, float) and not math.isfinite(value)):
+            return None, None
+        if parsed <= 0:
+            clamped = Decimal(0)
+        elif parsed >= 100:
+            clamped = Decimal(100)
+        elif parsed.as_tuple().exponent < -MAX_PLAIN_DECIMAL_PLACES:
+            return None, None
+        else:
+            clamped = parsed
+        result = format(clamped, "f") if clamped else "0"
+    except (InvalidOperation, ValueError, OverflowError):
+        return None, None
+    return clamped, result.rstrip("0").rstrip(".") if "." in result else result
+
+
+def identity(raw: dict) -> tuple[int | None, int | None, str | None, str | None, bool]:
+    runner = raw.get("runner_id")
+    generation = raw.get("runner_generation")
+    engine_value = raw.get("engine")
+    account_value = raw.get("account_id")
+    engine = engine_value.strip().lower() if isinstance(engine_value, str) else None
+    account = unicodedata.normalize("NFC", account_value).strip() \
+        if isinstance(account_value, str) else None
+    runner = runner if isinstance(runner, int) and not isinstance(runner, bool) and runner > 0 else None
+    generation = generation if isinstance(generation, int) \
+        and not isinstance(generation, bool) and generation > 0 else None
+    engine = engine if engine in {"claude", "codex"} else None
+    account = account or None
+    return runner, generation, engine, account, all((runner, generation, engine, account))
+
+
+def collision_key(parts: tuple) -> tuple:
+    runner, generation, engine, account = parts
+    folded = unicodedata.normalize("NFC", account.casefold()) if account else account
+    return runner, generation, engine, folded
+
+
+def _encode_rfc8785(value: object) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        if abs(value) > SAFE_INTEGER:
+            raise ValueError("integer outside RFC 8785 interoperable range")
+        return str(value)
+    if isinstance(value, str):
+        value.encode("utf-8")
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, list):
+        return "[" + ",".join(_encode_rfc8785(item) for item in value) + "]"
+    if isinstance(value, dict):
+        if any(not isinstance(key, str) for key in value):
+            raise ValueError("RFC 8785 object keys must be strings")
+        keys = sorted(value, key=lambda key: key.encode("utf-16-be", "surrogatepass"))
+        pairs = (_encode_rfc8785(key) + ":" + _encode_rfc8785(value[key]) for key in keys)
+        return "{" + ",".join(pairs) + "}"
+    raise ValueError(f"value outside frozen RFC 8785 digest domain: {type(value).__name__}")
+
+
+def canonical_sha256(value: object) -> str:
+    return hashlib.sha256(_encode_rfc8785(value).encode("utf-8")).hexdigest()
+
+
+def _identity_error(value: object, field: str) -> str | None:
+    if not isinstance(value, dict) or set(value) != IDENTITY_KEYS:
+        return field
+    runner, generation, _, account, valid = identity(value)
+    if not isinstance(value.get("engine"), str) or not valid:
+        return field
+    if abs(runner or 0) > SAFE_INTEGER or abs(generation or 0) > SAFE_INTEGER or account is None:
+        return field
+    return None
+
+
+def _candidate_error(value: object, index: int) -> str | None:
+    field = f"candidates[{index}]"
+    if not isinstance(value, dict) or set(value) != CANDIDATE_KEYS:
+        return field
+    for name in ("runner_id", "runner_generation"):
+        item = value[name]
+        if not isinstance(item, int) or isinstance(item, bool) or not 0 < item <= SAFE_INTEGER:
+            return f"{field}.{name}"
+    if not all(isinstance(value[name], str) for name in ("engine", "account_id", "status", "seen_at")):
+        return field
+    if not isinstance(value["provider_capable"], bool):
+        return f"{field}.provider_capable"
+    scalars = (str, int, float, Decimal, bool, type(None))
+    if any(not isinstance(value[name], scalars) for name in ("weekly_pct", "session_pct")):
+        return field
+    if any(isinstance(value[name], float) and not math.isfinite(value[name])
+           for name in ("weekly_pct", "session_pct")):
+        return field
+    if any(item is not None and not isinstance(item, str)
+           for item in (value["resets_at"], value["limited_until"])):
+        return field
+    history = value["reservation_history"]
+    if not isinstance(history, dict) or set(history) != {"active_expires_at", "last_selected_at"}:
+        return f"{field}.reservation_history"
+    if any(item is not None and not isinstance(item, str) for item in history.values()):
+        return f"{field}.reservation_history"
+    if history["active_expires_at"] is not None:
+        try:
+            timestamp(history["active_expires_at"])
+        except ValueError:
+            return f"{field}.reservation_history.active_expires_at"
+    return None
+
+
+def request_error(request: object) -> tuple[str, dict] | None:
+    if not isinstance(request, dict):
+        return "invalid_request", {"field": "$"}
+    if "schema" not in request:
+        return "invalid_request", {"field": "schema"}
+    if request.get("schema") != SCHEMA:
+        return "unsupported_schema", {"field": "schema"}
+    if set(request) != REQUEST_KEYS:
+        return "invalid_request", {"field": "$"}
+    try:
+        timestamp(request["database_now"])
+    except ValueError:
+        return "invalid_request", {"field": "database_now"}
+    policy, required = request["policy"], request["required_engine"]
+    if not isinstance(policy, str) or policy not in POLICIES:
+        return "invalid_request", {"field": "policy"}
+    if required is not None and (not isinstance(required, str) or required not in {"claude", "codex"}):
+        return "invalid_request", {"field": "required_engine"}
+    needs_engine = policy in {"explicit", "producer_retry", "reviewer"}
+    if (needs_engine and required is None) or (not needs_engine and required is not None):
+        return "invalid_request", {"field": "required_engine"}
+    producer = request["producer_identity"]
+    if (policy == "reviewer") != (producer is not None):
+        return "invalid_request", {"field": "producer_identity"}
+    if producer is not None and (error := _identity_error(producer, "producer_identity")):
+        return "invalid_request", {"field": error}
+    excluded = request["excluded_identities"]
+    if not isinstance(excluded, list):
+        return "invalid_request", {"field": "excluded_identities"}
+    for index, value in enumerate(excluded):
+        if error := _identity_error(value, f"excluded_identities[{index}]"):
+            return "invalid_request", {"field": error}
+    if not isinstance(request["reservation_key"], str) or not request["reservation_key"].strip():
+        return "invalid_request", {"field": "reservation_key"}
+    if not isinstance(request["candidates"], list):
+        return "invalid_request", {"field": "candidates"}
+    for index, value in enumerate(request["candidates"]):
+        if error := _candidate_error(value, index):
+            return "invalid_request", {"field": error}
+    return None

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "claude-multiacc",
-  "version": "1.0.21",
-  "description": "Multi-account addon for Claude Code and OpenAI Codex CLI: every claude / claude -p and every codex / codex exec runs under a randomly-picked subscription account with the most usage headroom. Mirrors to a deploy server. No API keys.",
+  "version": "2.0.0",
+  "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {
-    "claude-multiacc": "bin/cli.mjs"
+    "claude-multiacc": "bin/cli.mjs",
+    "multiacc-select": "bin/multiacc-select"
   },
   "files": [
     "bin/",
@@ -12,6 +13,7 @@
     "install.sh",
     "scripts/postinstall.mjs",
     "tests/",
+    "docs/",
     "README.md",
     "CLAUDE_ACCS_TASK.md"
   ],
@@ -51,7 +53,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "test": "bash tests/run-tests.sh"
+    "test": "bash tests/run-tests.sh && python3 tests/test_selector.py"
   },
   "dependencies": {
     "update-notifier": "^7.3.1"

package/tests/test_selector.py

@@ -0,0 +1,209 @@
+"""Golden and transport tests for pool-selection.v2."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "lib"))
+
+from selector_policy import select  # noqa: E402
+from selector_primitives import canonical_sha256  # noqa: E402
+
+SCHEMA = "claude-multiacc/pool-selection.v2"
+NOW = "2026-08-25T09:00:00.000000Z"
+
+
+def _candidate(**patch) -> dict:
+    row = {
+        "runner_id": 3, "runner_generation": 7, "engine": "claude", "account_id": "acct-a",
+        "status": "active", "weekly_pct": 20, "session_pct": 40,
+        "resets_at": "2026-08-26T09:00:00Z", "limited_until": None,
+        "seen_at": "2026-08-25T08:59:00Z", "provider_capable": True,
+        "reservation_history": {"active_expires_at": None, "last_selected_at": None}}
+    row.update(patch)
+    return row
+
+
+def _request(candidates: list[dict], **patch) -> dict:
+    request = {
+        "schema": SCHEMA, "database_now": NOW, "policy": "default_both",
+        "required_engine": None, "producer_identity": None, "excluded_identities": [],
+        "candidates": candidates, "reservation_key": "proof"}
+    request.update(patch)
+    return request
+
+
+class SelectorTests(unittest.TestCase):
+    def test_union_proof_vector_is_byte_stable(self):
+        request = _request([
+            _candidate(engine="claude", account_id="claude-a", weekly_pct=10, session_pct=20,
+                       seen_at="2026-08-25T08:54:59Z"),
+            _candidate(engine="codex", account_id="codex-b", weekly_pct=30, session_pct=40),
+            _candidate(engine="both", account_id="   ", weekly_pct=0, session_pct=0),
+        ], reservation_key="launch-1")
+        response = select(request)
+        self.assertEqual(response["engine"], "codex")
+        self.assertEqual(response["account_id"], "codex-b")
+        self.assertEqual(
+            response["candidate_snapshot_digest"],
+            "e8ef0b4bc7b95e76231ee6da79616d92bd9251c1c991845c8c0524fcbfb6593a")
+        self.assertEqual(
+            response["selection_digest"],
+            "66179083753e967bbe3914692103c1b4a30966a86ecf85cd62e14f3511c78cc3")
+
+    def test_unicode_and_active_reservation_proof(self):
+        busy = {"active_expires_at": "2026-08-25T09:00:00.000001Z", "last_selected_at": None}
+        response = select(_request([
+            _candidate(engine="claude", account_id="claude-active", reservation_history=busy),
+            _candidate(engine="codex", account_id="café-🚀", weekly_pct=25, session_pct=50),
+        ], policy="explicit", required_engine="codex", reservation_key="launch-unicode"))
+        self.assertEqual((response["engine"], response["account_id"]), ("codex", "café-🚀"))
+        self.assertEqual(
+            response["candidate_snapshot_digest"],
+            "29e8e7d1a611f38ee0be43622102b33875e7ff75ff9024aa43d16151575071d4")
+        self.assertEqual(
+            response["selection_digest"],
+            "eaea620082bb0882a12598b8cc46e79090da07be0b307f34f0a68f555a6c9d3e")
+
+    def test_both_chooses_each_provider_and_survives_provider_loss(self):
+        codex = select(_request([
+            _candidate(engine="claude", account_id="claude-a", weekly_pct=70, session_pct=60),
+            _candidate(engine="codex", account_id="codex-a", weekly_pct=20, session_pct=30)]))
+        claude = select(_request([
+            _candidate(engine="claude", account_id="claude-a", weekly_pct=10, session_pct=30),
+            _candidate(engine="codex", account_id="codex-a", weekly_pct=20, session_pct=80)]))
+        only = select(_request([_candidate(engine="codex", account_id="codex-only")]))
+        self.assertEqual((codex["engine"], claude["engine"], only["engine"]),
+                         ("codex", "claude", "codex"))
+
+    def test_known_quota_and_least_recent_selection_win(self):
+        known = select(_request([
+            _candidate(engine="claude", account_id="unknown", weekly_pct=None, session_pct=None),
+            _candidate(engine="codex", account_id="known", weekly_pct=99, session_pct=99)]))
+        old = {"active_expires_at": None, "last_selected_at": "2026-08-25T08:00:00Z"}
+        recent = {"active_expires_at": None, "last_selected_at": "2026-08-25T08:50:00Z"}
+        fair = select(_request([
+            _candidate(engine="claude", account_id="recent", weekly_pct=20, session_pct=20,
+                       reservation_history=recent),
+            _candidate(engine="codex", account_id="old", weekly_pct=20, session_pct=20,
+                       reservation_history=old)]))
+        self.assertEqual((known["account_id"], fair["account_id"]), ("known", "old"))
+        utc = select(_request([_candidate()]))
+        offset = select(_request(
+            [_candidate()], database_now="2026-08-25T12:00:00+03:00"))
+        self.assertEqual(utc["selection_digest"], offset["selection_digest"])
+
+    def test_explicit_and_reviewer_policies_never_cross_provider(self):
+        explicit = select(_request([
+            _candidate(engine="claude", account_id="free", weekly_pct=0, session_pct=0),
+            _candidate(engine="codex", account_id="busy", weekly_pct=90, session_pct=90),
+        ], policy="explicit", required_engine="codex"))
+        producer = {"runner_id": 3, "runner_generation": 7, "engine": "claude",
+                    "account_id": "producer"}
+        review = select(_request([
+            _candidate(engine="claude", account_id="producer", weekly_pct=0, session_pct=0),
+            _candidate(engine="claude", account_id="reviewer", weekly_pct=90, session_pct=90),
+        ], policy="reviewer", required_engine="claude", producer_identity=producer,
+            excluded_identities=[producer]))
+        sole = select(_request([
+            _candidate(engine="claude", account_id="producer")], policy="reviewer",
+            required_engine="claude", producer_identity=producer))
+        alternative = {"runner_id": 4, "runner_generation": 7, "engine": "claude",
+                       "account_id": "alternative"}
+        fallback = select(_request([
+            _candidate(account_id="producer"),
+            _candidate(runner_id=4, account_id="alternative")], policy="reviewer",
+            required_engine="claude", producer_identity=producer,
+            excluded_identities=[alternative]))
+        self.assertEqual((explicit["engine"], review["account_id"]), ("codex", "reviewer"))
+        self.assertEqual(sole["fallback_reason"], "sole_eligible_account")
+        self.assertEqual((fallback["account_id"], fallback["fallback_reason"]),
+                         ("producer", "sole_eligible_account"))
+
+    def test_stable_errors_fail_closed(self):
+        collisions = [(" Acct-A ", "acct-a"), ("CAFÉ", "cafe\u0301")]
+        duplicates = [select(_request([
+            _candidate(engine=" CLAUDE ", account_id=left),
+            _candidate(engine="claude", account_id=right)])) for left, right in collisions]
+        no_candidate = select(_request([
+            _candidate(engine="claude")], policy="default_codex"))
+        invalid = select({**_request([]), "unexpected": True})
+        preserved = select(_request([_candidate(account_id=" Acct-A ")]))
+        overflow_now = select(_request(
+            [], database_now="9999-12-31T23:59:59-01:00"))
+        overflow_seen = select(_request([
+            _candidate(seen_at="0001-01-01T00:00:00+01:00")]))
+        overflow_history = select(_request([_candidate(reservation_history={
+            "active_expires_at": "9999-12-31T23:59:59-01:00", "last_selected_at": None})]))
+        self.assertTrue(all(item["error_code"] == "duplicate_candidate_identity"
+                            for item in duplicates))
+        self.assertTrue(all(item["error_detail"] == {"input_ordinals": [0, 1]}
+                            for item in duplicates))
+        self.assertEqual(no_candidate["error_code"], "no_candidate")
+        self.assertEqual(preserved["account_id"], "Acct-A")
+        self.assertEqual(overflow_now["error_detail"], {"field": "database_now"})
+        self.assertEqual(overflow_seen["error_code"], "no_candidate")
+        self.assertEqual(overflow_history["error_detail"], {
+            "field": "candidates[0].reservation_history.active_expires_at"})
+        self.assertEqual(invalid, {"schema": SCHEMA, "selector_version": "2.0.0", "ok": False,
+                                   "error_code": "invalid_request", "error_detail": {"field": "$"}})
+
+    def test_rfc8785_digest_vectors(self):
+        self.assertEqual(
+            canonical_sha256({"account_id": "café-🚀", "metadata": {"": "bmp", "😀": "astral"}}),
+            "2f33747d98d7c2f3cfc0a660eba492a7652a66bc46b147edeccf4cc941154981")
+        with self.assertRaises(ValueError):
+            canonical_sha256({"unsafe": 9_007_199_254_740_992})
+
+    def test_cli_transport_and_version_contract(self):
+        binary = ROOT / "bin" / "multiacc-select"
+        args = [str(binary), "--request-json", "-", "--response-json", "-"]
+        good_payload = json.dumps(_request([_candidate(engine="codex")]), separators=(",", ":"))
+        good = subprocess.run(args, input=good_payload, text=True, capture_output=True, check=True)
+        bad_payloads = [
+            good_payload.replace('"weekly_pct":20', '"weekly_pct":NaN', 1),
+            good_payload.replace(
+                '"weekly_pct":20', '"weekly_pct":1e999999999999999999999999999999', 1),
+            good_payload.replace('"policy":"default_both"',
+                                 '"policy":"explicit","policy":"default_both"', 1),
+            good_payload.replace('"active_expires_at":null',
+                                 '"active_expires_at":null,"active_expires_at":null', 1),
+            good_payload + "{}",
+        ]
+        bad = [subprocess.run(args, input=payload, text=True, capture_output=True, check=True)
+               for payload in bad_payloads]
+        decimal_request = _request([
+            _candidate(account_id="z-lower", weekly_pct="LOW"),
+            _candidate(runner_id=4, account_id="a-higher", weekly_pct="HIGH")])
+        decimal_payload = json.dumps(decimal_request, separators=(",", ":"))
+        decimal_payload = decimal_payload.replace(
+            '"LOW"', "50.00000000000000000000000000001")
+        decimal_payload = decimal_payload.replace(
+            '"HIGH"', "50.00000000000000000000000000002")
+        decimal_response = subprocess.run(
+            args, input=decimal_payload, text=True, capture_output=True, check=True)
+        version = subprocess.run([str(binary), "--version"], text=True,
+                                 capture_output=True, check=True).stdout.strip()
+        version_script = (
+            "import {resolveVersion} from './scripts/auto-version.mjs';"
+            "console.log(resolveVersion('2.0.0','1.0.21'));"
+            "console.log(resolveVersion('2.0.0','2.0.0'));"
+        )
+        versions = subprocess.run(
+            ["node", "--input-type=module", "-e", version_script], cwd=ROOT,
+            text=True, capture_output=True, check=True).stdout.splitlines()
+        self.assertTrue(json.loads(good.stdout)["ok"])
+        self.assertTrue(all(json.loads(item.stdout)["error_code"] == "invalid_request"
+                            for item in bad))
+        self.assertEqual(json.loads(decimal_response.stdout)["account_id"], "z-lower")
+        self.assertEqual(version, "2.0.0")
+        self.assertEqual(versions, ["2.0.0", "2.0.1"])
+
+
+if __name__ == "__main__":
+    unittest.main()