claude-multiacc 1.0.13 → 1.0.15

package/lib/report.py

@@ -0,0 +1,434 @@
+"""Machine-readable pool report — the ONE place that builds the JSON `list --json`,
+`status --json` and `limits --json` emit, for BOTH providers, so a consumer (the
+app-robot panel/runner daemon) parses exactly one shape no matter which verb or
+provider produced it.
+
+Run:  python3 lib/report.py <acc-root> <claude|codex> <mac|linux> [list|status|limits]
+
+The document is a single JSON object on stdout:
+
+  schema      "claude-multiacc/pool.v1" — bumped only on a BREAKING change
+  provider    claude | codex
+  kind        which verb rendered it (list|status|limits)
+  pool        root, manifest path, threshold, sync target/mode/role, peers
+  accounts[]  id, email, home, home_dir, status, state, credential_class, usage, ...
+  summary     counts a dashboard can render without walking the list
+  warnings[]  duplicate emails, unreadable manifest bits — never fatal
+
+Every field is best-effort: one corrupt account file degrades that account only,
+never the document (a --json call that dies is worse than one that says 'unknown').
+
+Account status vocabulary (the panel's contract):
+  active    selectable right now
+  limited   authenticates, but a >=threshold bucket is parked until limit_reset_at
+  expired   has auth material that cannot authenticate — needs an interactive login
+  blocked   authenticates, but the org/workspace disabled the CLI for it
+  missing   no auth material on this machine (and this machine should own it)
+  remote    no auth here on purpose — the manifest says another machine owns it
+
+Credential classes (what may be COPIED between machines):
+  portable      claude setup-token (server.token) — safe to export/import anywhere
+  machine-local claude .credentials.json / codex auth.json — rotating refresh grant;
+                copying it makes two machines fight over one grant and breaks both
+  none          nothing on disk here
+"""
+
+import json
+import os
+import re
+import socket
+import sys
+import time
+
+SCHEMA = 'claude-multiacc/pool.v1'
+
+# Must match the SHIM's ranking window, or this document calls data "fresh" that
+# selection has already stopped ranking on. The two providers differ on purpose:
+# api.anthropic.com hands out Retry-After: 3600, so bin/claude trusts an hour;
+# bin/codex still uses 900 against chatgpt.com, which has not been measured.
+_STALE_DEFAULT = {'claude': 3600, 'codex': 900}
+
+
+def _stale_after(provider):
+    env = {'claude': 'CLAUDE_MULTIACC_STALE_AFTER',
+           'codex': 'CODEX_MULTIACC_STALE_AFTER'}.get(provider)
+    default = _STALE_DEFAULT.get(provider, 900)
+    try:
+        v = int(os.environ.get(env) or default) if env else default
+    except ValueError:
+        v = default
+    return v if v > 0 else default
+
+
+VALID_ID = re.compile(r'acct-\d{2}')
+
+
+def _iso(epoch):
+    try:
+        epoch = float(epoch)
+    except (TypeError, ValueError):
+        return None
+    if epoch <= 0:
+        return None
+    try:
+        return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(epoch))
+    except (ValueError, OSError, OverflowError):   # absurd epoch in a corrupt file
+        return None
+
+
+def _iso_ms(value):
+    """A milliseconds field (credentials carry them) -> ISO, tolerating whatever a
+    corrupt credential holds: a string, a list, null. One bad file must degrade its
+    own account, never the document."""
+    try:
+        return _iso(float(value or 0) / 1000.0)
+    except (TypeError, ValueError):
+        return None
+
+
+def _size(path):
+    try:
+        return os.path.getsize(path)
+    except OSError:
+        return 0
+
+
+def _mtime(path):
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return 0.0
+
+
+def _load_json(path):
+    try:
+        with open(path) as f:
+            doc = json.load(f)
+        return doc if isinstance(doc, dict) else None
+    except Exception:
+        return None
+
+
+def _marker(path):
+    """(reset_epoch, detail) of a .limited/.expired marker; (0, '') when absent."""
+    try:
+        lines = open(path, errors='replace').read().splitlines()
+    except OSError:
+        return 0, ''
+    reset = int(lines[0]) if lines and lines[0].strip().isdigit() else 0
+    detail = lines[1].strip() if len(lines) > 1 else ''
+    return reset, detail
+
+
+def _sync_block(root, manifest):
+    """Where this pool syncs to. The env values are what lib/common.sh RESOLVED
+    (env override > manifest), passed through so the report can never disagree with
+    what `sync` would actually do; without them the manifest is the authority."""
+    target = os.environ.get('MULTIACC_REPORT_SYNC_TARGET')
+    if target is None:
+        target = str(manifest.get('server') or '')
+    sroot = os.environ.get('MULTIACC_REPORT_SYNC_ROOT') or str(manifest.get('server_root') or '')
+    srepo = os.environ.get('MULTIACC_REPORT_SYNC_REPO') or str(manifest.get('server_repo') or '')
+    mode = os.environ.get('MULTIACC_REPORT_SYNC_MODE')
+    if not mode:
+        mode = 'local' if target.strip().lower() in ('', 'none', 'local', 'off', 'disabled') else 'server'
+    role = 'source'
+    try:
+        with open(os.path.join(root, 'sync-role'), errors='replace') as f:
+            if any(line.strip().lower() == 'replica' for line in f):
+                role = 'replica'
+    except OSError:
+        pass
+    peers = []
+    raw = manifest.get('peers')
+    if isinstance(raw, list):
+        for p in raw:
+            if isinstance(p, dict):
+                peers.append({'target': str(p.get('target') or ''),
+                              'root': str(p.get('root') or ''),
+                              'repo': str(p.get('repo') or '')})
+    return {'mode': mode, 'target': None if mode == 'local' else target,
+            'root': sroot or None, 'repo': srepo or None, 'role': role, 'peers': peers}
+
+
+def _claude_credentials(d):
+    """(credential_class, credentials-detail) for a claude account dir."""
+    cpath = os.path.join(d, '.credentials.json')
+    tpath = os.path.join(d, 'server.token')
+    has_oauth = _size(cpath) > 0
+    has_token = _size(tpath) > 0
+    detail = {'oauth': has_oauth, 'token': has_token,
+              'oauth_expires_at': None, 'oauth_refresh_expires_at': None,
+              'token_minted_at': None, 'token_age_days': None}
+    if has_oauth:
+        doc = _load_json(cpath) or {}
+        o = doc.get('claudeAiOauth')
+        if isinstance(o, dict):
+            detail['oauth_expires_at'] = _iso_ms(o.get('expiresAt'))
+            detail['oauth_refresh_expires_at'] = _iso_ms(o.get('refreshTokenExpiresAt'))
+    if has_token:
+        mt = _mtime(tpath)
+        detail['token_minted_at'] = _iso(mt)
+        if mt:
+            detail['token_age_days'] = int((time.time() - mt) / 86400)
+    # A setup-token is the only claude credential that survives being copied.
+    if has_token:
+        return 'portable', detail
+    if has_oauth:
+        return 'machine-local', detail
+    return 'none', detail
+
+
+def _codex_credentials(d, jwt_claims):
+    """(credential_class, credentials-detail) for a codex account dir. Codex has NO
+    portable class: auth.json carries a rotating refresh token."""
+    cpath = os.path.join(d, 'auth.json')
+    has_auth = _size(cpath) > 0
+    detail = {'oauth': has_auth, 'token': False, 'auth_expires_at': None,
+              'refresh_token': False, 'plan': None, 'auth_mode': None}
+    if not has_auth:
+        return 'none', detail
+    doc = _load_json(cpath) or {}
+    detail['auth_mode'] = str(doc.get('auth_mode') or '') or None
+    tokens = doc.get('tokens')
+    if isinstance(tokens, dict):
+        detail['refresh_token'] = bool(tokens.get('refresh_token'))
+        detail['auth_expires_at'] = _iso(jwt_claims(tokens.get('access_token')).get('exp'))
+        plan = (jwt_claims(tokens.get('id_token')).get('https://api.openai.com/auth') or {})
+        if isinstance(plan, dict):
+            detail['plan'] = plan.get('chatgpt_plan_type') or None
+    return 'machine-local', detail
+
+
+def _usage(d, stale_after):
+    lim = _load_json(os.path.join(d, 'limits.json'))
+    if not lim:
+        return None
+    buckets = []
+    for b in (lim.get('buckets') or []):
+        if not isinstance(b, dict):
+            continue
+        buckets.append({'name': str(b.get('name') or ''), 'kind': str(b.get('kind') or ''),
+                        'group': str(b.get('group') or ''), 'percent': b.get('percent'),
+                        'resets_at': b.get('resets_at')})
+    fetched = lim.get('fetched_at') or 0
+    out = {'fetched_at': _iso(fetched), 'source': lim.get('source'),
+           'max_percent': lim.get('max_percent'), 'weekly_percent': lim.get('weekly_percent'),
+           'session_percent': lim.get('session_percent'), 'buckets': buckets}
+    try:
+        out['age_seconds'] = max(0, int(time.time() - float(fetched)))
+    except (TypeError, ValueError):
+        out['age_seconds'] = None
+    # Past this window the shim stops ranking on these numbers entirely (bin/claude
+    # STALE_AFTER). A panel that shows "weekly 2%" without it is reporting a number
+    # nothing is using — which is how an 11-day telemetry outage stayed invisible.
+    out['stale'] = out['age_seconds'] is None or out['age_seconds'] > stale_after
+    # The horizon a stale weekly reading stays true until (bin/claude stale_weekly).
+    # Absent on documents written before it existed, which is itself the signal that
+    # the reading cannot be used for degraded ranking.
+    if lim.get('weekly_resets_epoch'):
+        out['weekly_resets_epoch'] = lim['weekly_resets_epoch']
+    if lim.get('last_error'):
+        out['last_error'] = lim['last_error']
+        if lim.get('last_error_at'):
+            out['last_error_at'] = _iso(lim['last_error_at'])
+    if lim.get('plan'):
+        out['plan'] = lim['plan']
+    if lim.get('retry_after'):
+        out['retry_after'] = _iso(lim['retry_after'])
+    return out
+
+
+def _last_pick(root, aid):
+    path = os.path.join(root, 'selection.log')
+    last = None
+    try:
+        with open(path, errors='replace') as f:
+            for line in f:
+                parts = line.split()
+                if len(parts) >= 2 and parts[1] == aid:
+                    last = parts[0]
+    except OSError:
+        pass
+    return last
+
+
+
+def telemetry_state(accounts, now=None):
+    """Three-state verdict on how the shim is CURRENTLY ranking this pool, over the
+    same candidate set bin/claude uses: the eligible accounts, or — when every one of
+    them is limit-marked — the valid ones it falls back to.
+
+      'fresh'    at least one candidate has telemetry inside the ranking window
+      'degraded' none do, but EVERY candidate still has a weekly reading whose bucket
+                 has not reset yet, so the shim ranks on those (all-or-nothing: one
+                 unusable reading and the comparison is not apples-to-apples)
+      'blind'    nothing usable anywhere — every account scores the same and selection
+                 is effectively a coin flip
+      'none'     no candidates at all; nothing to say
+
+    Kept here rather than beside either caller because `status` and `--json` disagreeing
+    with the shim is exactly how an eleven-day outage stayed invisible.
+    """
+    now = time.time() if now is None else now
+    usable = [a for a in accounts if a.get('status') in ('active', 'limited')]
+    cands = [a for a in usable if a.get('status') == 'active'] or usable
+    if not cands:
+        return 'none'
+    if any(a.get('usage') and not a['usage'].get('stale') for a in cands):
+        return 'fresh'
+    for a in cands:
+        u = a.get('usage') or {}
+        horizon = u.get('weekly_resets_epoch') or 0
+        pct = u.get('weekly_percent')
+        # bool is an int in Python but not a number to the shim's digit parser, so a
+        # document carrying `weekly_percent: true` must read as unusable HERE too —
+        # otherwise this says 'degraded' while the shim ranks blind.
+        if isinstance(horizon, bool) or isinstance(pct, bool) \
+                or not isinstance(horizon, (int, float)) or horizon <= now \
+                or not isinstance(pct, (int, float)):
+            return 'blind'
+    return 'degraded'
+
+
+def _account_row(root, a, aid, d, provider, jwt_claims, audit_account, now, kind, machine):
+    """One account's row. Everything it reads is already tolerant; build() catches
+    anything unexpected on top of that and degrades this account alone."""
+    st = audit_account(root, a, now=now, machine=machine)
+    if provider == 'codex':
+        cclass, cdetail = _codex_credentials(d, jwt_claims)
+    else:
+        cclass, cdetail = _claude_credentials(d)
+    reset_epoch, marker_detail = _marker(os.path.join(d, '.limited'))
+    limited = reset_epoch > now or (reset_epoch == 0 and os.path.isfile(os.path.join(d, '.limited')))
+    status = st['state']
+    if status == 'ok':
+        status = 'limited' if limited else 'active'
+    row = {
+        'id': aid,
+        'email': a.get('email', ''),
+        'home': a.get('home', ''),
+        'added_at': a.get('added_at'),
+        'home_dir': d,
+        'exists': os.path.isdir(d),
+        'adopted': os.path.islink(d),
+        'status': status,
+        'state': st['state'],
+        'label': st['label'],
+        'reason': st['reason'],
+        'fix': st['fix'],
+        'selectable': st['state'] == 'ok' and not limited,
+        'needs_login': st['state'] in ('expired', 'blocked', 'missing'),
+        'credential_class': cclass,
+        'portable': cclass == 'portable',
+        'credentials': cdetail,
+        'limited': bool(limited),
+        'limit_reset_at': _iso(reset_epoch) if limited and reset_epoch else None,
+        'limit_reset_epoch': reset_epoch if limited and reset_epoch else None,
+        'limit_detail': marker_detail if limited else None,
+        'usage': _usage(d, _stale_after(provider)),
+    }
+    if kind == 'status':
+        row['last_picked'] = _last_pick(root, aid)
+        expired_reset, expired_detail = _marker(os.path.join(d, '.expired'))
+        row['expired_marker'] = expired_detail or None
+    return row
+
+
+def build(root, provider, machine, kind='list'):
+    if provider == 'codex':
+        from codex_audit import audit_account, jwt_claims
+    else:
+        from audit import audit_account
+        jwt_claims = None
+    now = time.time()
+    warnings = []
+    manifest_path = os.path.join(root, 'accounts.json')
+    manifest = _load_json(manifest_path)
+    if manifest is None:
+        manifest = {}
+        warnings.append(f'manifest unreadable or missing: {manifest_path}')
+
+    raw_accounts = manifest.get('accounts')
+    if not isinstance(raw_accounts, list):
+        raw_accounts = []
+        if manifest:
+            warnings.append("manifest has no well-formed 'accounts' array")
+
+    accounts = []
+    seen_emails = {}
+    for a in raw_accounts:
+        if not isinstance(a, dict) or not VALID_ID.fullmatch(str(a.get('id', ''))):
+            warnings.append('skipped a manifest entry with a malformed id')
+            continue
+        aid = a['id']
+        d = os.path.join(root, aid)
+        try:
+            row = _account_row(root, a, aid, d, provider, jwt_claims, audit_account,
+                               now, kind, machine)
+        except Exception as e:      # one unreadable account must not empty the report
+            warnings.append(f'{aid}: could not be read ({str(e)[:120]})')
+            row = {'id': aid, 'email': a.get('email', ''), 'home': a.get('home', ''),
+                   'home_dir': d, 'status': 'unknown', 'state': 'unknown',
+                   'label': 'UNKNOWN', 'reason': f'unreadable: {str(e)[:120]}',
+                   'fix': '', 'selectable': False, 'needs_login': False,
+                   'credential_class': 'unknown', 'portable': False,
+                   'credentials': {}, 'limited': False, 'limit_reset_at': None,
+                   'usage': None}
+        accounts.append(row)
+        seen_emails.setdefault(str(a.get('email', '')).lower(), []).append(aid)
+
+    for email, ids in seen_emails.items():
+        if len(ids) > 1:
+            warnings.append(f"{email} is registered {len(ids)}x ({', '.join(ids)}) "
+                            f"— run '{provider}-accounts dedupe'")
+
+    threshold = manifest.get('threshold', 90)
+    try:
+        threshold = int(threshold)
+    except (TypeError, ValueError):
+        threshold = 90
+
+    return {
+        'schema': SCHEMA,
+        'provider': provider,
+        'kind': kind,
+        'generated_at': _iso(now),
+        'machine': machine,
+        'host': socket.gethostname(),
+        'pool': {
+            'root': root,
+            'manifest': manifest_path,
+            'threshold': threshold,
+            'sync': _sync_block(root, manifest),
+        },
+        'accounts': accounts,
+        'summary': {
+            'total': len(accounts),
+            'active': sum(1 for a in accounts if a['status'] == 'active'),
+            'limited': sum(1 for a in accounts if a['status'] == 'limited'),
+            'needs_login': sum(1 for a in accounts if a['needs_login']),
+            'portable': sum(1 for a in accounts if a['portable']),
+            'selectable': sum(1 for a in accounts if a['selectable']),
+            # The pool-wide verdict, so a dashboard can show the outage rather than a
+            # grid of reassuring percentages nothing is ranking on.
+            #   fresh    ranking on current data
+            #   degraded ranking on old-but-still-true weekly readings
+            #   blind    every account scores the same; selection is a coin flip
+            'telemetry': telemetry_state(accounts, now),
+            # Kept as its own boolean because a dashboard alerting on one field should
+            # not have to know the vocabulary. True ONLY for the coin-flip case.
+            'ranking_blind': telemetry_state(accounts, now) == 'blind',
+        },
+        'warnings': warnings,
+    }
+
+
+if __name__ == '__main__':
+    root = sys.argv[1]
+    provider = sys.argv[2] if len(sys.argv) > 2 else 'claude'
+    machine = sys.argv[3] if len(sys.argv) > 3 else 'mac'
+    kind = sys.argv[4] if len(sys.argv) > 4 else 'list'
+    sys.path = [os.path.dirname(os.path.abspath(__file__))] + \
+               [p for p in sys.path if p not in ('', '.')]
+    print(json.dumps(build(root, provider, machine, kind), indent=2, sort_keys=False))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "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.",
   "type": "module",
   "bin": {