taskuary 0.3.7.2__tar.gz → 0.3.7.4__tar.gz

{taskuary-0.3.7.2/taskuary.egg-info → taskuary-0.3.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskuary
-Version: 0.3.7.2
+Version: 0.3.7.4
 Summary: Automate your job - the local-first operating system for your work: AI triage in, coding agents out.
 License: MIT
 Project-URL: Homepage, https://github.com/ldbumble/taskuary
@@ -69,7 +69,7 @@ Dynamic: license-file
 
 [![CI](https://github.com/ldbumble/taskuary/actions/workflows/ci.yml/badge.svg)](https://github.com/ldbumble/taskuary/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ldbumble/taskuary/badge)](https://scorecard.dev/viewer/?uri=github.com/ldbumble/taskuary)
-[![PyPI](https://img.shields.io/pypi/v/taskuary.svg?cacheSeconds=300&release=0.3.7.2&asof=2026-09-28T1810)](https://pypi.org/project/taskuary/)
+[![PyPI](https://img.shields.io/pypi/v/taskuary.svg?cacheSeconds=300&release=0.3.7.4&asof=2026-10-01T1249)](https://pypi.org/project/taskuary/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://github.com/ldbumble/taskuary)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Stars](https://img.shields.io/github/stars/ldbumble/taskuary?style=flat&color=d4a72c&label=%E2%98%85%20stars)](https://github.com/ldbumble/taskuary/stargazers)
@@ -83,7 +83,7 @@ your agents, and brings decisions back to you. Nothing sends or ships without yo
 
 ![The Taskuary Studio assembling as work arrives and AI agents take their seats.](https://raw.githubusercontent.com/ldbumble/taskuary/master/docs/hero.gif?v=workspace)
 
-Taskuary is early—currently **v0.3.7.2**—so breaking changes are still possible before 1.0.
+Taskuary is early—currently **v0.3.7.4**—so breaking changes are still possible before 1.0.
 
 <p align="center">
   <a href="https://taskuary.com/demo/"><img

{taskuary-0.3.7.2 → taskuary-0.3.7.4}/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/ldbumble/taskuary/actions/workflows/ci.yml/badge.svg)](https://github.com/ldbumble/taskuary/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ldbumble/taskuary/badge)](https://scorecard.dev/viewer/?uri=github.com/ldbumble/taskuary)
-[![PyPI](https://img.shields.io/pypi/v/taskuary.svg?cacheSeconds=300&release=0.3.7.2&asof=2026-09-28T1810)](https://pypi.org/project/taskuary/)
+[![PyPI](https://img.shields.io/pypi/v/taskuary.svg?cacheSeconds=300&release=0.3.7.4&asof=2026-10-01T1249)](https://pypi.org/project/taskuary/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://github.com/ldbumble/taskuary)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Stars](https://img.shields.io/github/stars/ldbumble/taskuary?style=flat&color=d4a72c&label=%E2%98%85%20stars)](https://github.com/ldbumble/taskuary/stargazers)
@@ -18,7 +18,7 @@ your agents, and brings decisions back to you. Nothing sends or ships without yo
 
 ![The Taskuary Studio assembling as work arrives and AI agents take their seats.](https://raw.githubusercontent.com/ldbumble/taskuary/master/docs/hero.gif?v=workspace)
 
-Taskuary is early—currently **v0.3.7.2**—so breaking changes are still possible before 1.0.
+Taskuary is early—currently **v0.3.7.4**—so breaking changes are still possible before 1.0.
 
 <p align="center">
   <a href="https://taskuary.com/demo/"><img

{taskuary-0.3.7.2 → taskuary-0.3.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "taskuary"
-version = "0.3.7.2"
+version = "0.3.7.4"
 description = "Automate your job - the local-first operating system for your work: AI triage in, coding agents out."
 readme = "README.md"
 license = { text = "MIT" }

{taskuary-0.3.7.2 → taskuary-0.3.7.4}/taskuary/aidefaults.py

@@ -211,7 +211,7 @@ def _resolved(cat: dict, model: str) -> str:
 # say it rather than showing an empty field that looks unconfigured.
 _CONN_DEFAULT = {'anthropic': 'claude-opus-5', 'openai': 'gpt-4o-mini', 'openrouter': 'openrouter/auto',
                  'meta': 'muse-spark-1.2', 'ollama': '(required - name the model you pulled)',
-                 'azure_openai': '(the deployment name on the card)'}
+                 'azure_openai': '(the deployment name on the card)', 'chatgpt': '(the first model your plan lists)'}
 _CONN_MODELS = {'anthropic': ['claude-opus-5', 'claude-sonnet-5', 'claude-haiku-4-5'],
                 'openai': ['gpt-4o-mini', 'gpt-4o'],
                 'openrouter': ['openrouter/auto', 'meta-llama/llama-3.3-70b-instruct'],

{taskuary-0.3.7.2 → taskuary-0.3.7.4}/taskuary/assistant.py

@@ -417,12 +417,10 @@ def health_ideas(store, now: datetime = None) -> list:
                         'text': f"{r['title']} is a workflow that has never run - its clock is {r['schedule'] or 'not set'}.",
                         'action': {'type': 'health', 'tab': 'Reports', 'hash': f"report={r['source_id']}", 'source_id': r['source_id'],
                                    'why': 'a workflow that never ran is either mis-clocked or waiting on a sign-in'}})
-    for c in appfacts.connections(store):
-        if c['active'] and c['last_error']:
-            out.append({'key': f"health:connection:{c['connector_id']}", 'kind': 'health', 'sig': re.sub(r'\d+', '#', _short(c['last_error'], 60)),
-                        'text': f"{c['name']} is erroring - {_short(c['last_error'], 80)}.",
-                        'action': {'type': 'health', 'tab': 'Connections', 'hash': f"connector={c['type']}", 'connector_id': c['connector_id'],
-                                   'why': 'a connection that errors reads nothing until somebody looks'}})
+    # An erroring CONNECTION is not raised here: the rail already carries it as its own "stopped answering" row
+    # (funnel.broken_connections), and said twice it became an idea, then a task, then a coding agent investigating
+    # a connection the owner was looking at (the owner, 2026-09-30: "don't need both ... if it fails we don't need
+    # advisor to tell us").
     try:
         waiting = len(store.pending_triage(limit=50))
         brain = str(store.get_setting('triage_ai') or '').strip()

taskuary-0.3.7.4/taskuary/background.py

@@ -0,0 +1,125 @@
+"""What a Claude run left RUNNING when its turn ended - background shells, monitors, subagents. Claude's own word
+first: its Stop payload lists them (`from_hook`); a Claude that does not send that list is read off its own
+transcript instead (`pending` - the Stop hook names it: `transcript_path`).
+
+Stop is the end of a RESPONSE. A coder that starts a long pull in the background, arms a monitor on it and says
+"re-pulling Jan 2024 now" ends its turn there, and the pane sits at a bare prompt with "1 shell, 1 monitor still
+running" under it - so every surface read "coder is waiting on you" while the work went on (the owner, 2026-10-01:
+"since there is a sub agent doing work the main chat might wait but the process is still going"). When a job
+ends Claude is woken by its notification, takes a turn, and Stops again, so each Stop re-reads this.
+
+The transcript says when a job STARTS (the tool result carries `backgroundTaskId`, a monitor's `taskId` +
+`timeoutMs`, a subagent's `isAsync` + `agentId`) and when it ENDS (a `<task-notification>` with a `<status>`,
+a monitor's "[Monitor expired" event, a TaskStop). Claude itself says some stops leave no marker - a shell killed
+from its UI - so every job also carries its own deadline, and one past it is not counted.
+"""
+import json, re, time
+from datetime import datetime
+
+SHELL_MS = 1_800_000      # Bash run_in_background's default timeout
+_TID = re.compile(r'<task-id>([^<]+)</task-id>')
+_ENDED = re.compile(r'<status>|\[Monitor expired')
+# cheap substring gate: a transcript runs to tens of MB and only these lines can start or end a job
+_MARKS = ('backgroundTaskId', '"timeoutMs"', 'async_launched', '<task-notification>', '"run_in_background":true',
+          '"name":"Monitor"', '"name":"TaskStop"', '"name":"Agent"', '"name":"Task"')
+
+
+def _epoch(ts) -> float:
+    try: return datetime.fromisoformat(str(ts).replace('Z', '+00:00')).timestamp()
+    except ValueError: return time.time()
+
+
+def _started(r: dict, inp: dict, at: float):
+    "(id, job) for a tool result that put work in the background, else None"
+    if r.get('backgroundTaskId'):
+        return r['backgroundTaskId'], {'kind': 'shell', 'what': inp.get('description') or str(inp.get('command') or '')[:120],
+                                       'until': at + (inp.get('timeout') or SHELL_MS) / 1000}
+    if r.get('taskId') and 'timeoutMs' in r:
+        return r['taskId'], {'kind': 'monitor', 'what': inp.get('description') or '',
+                             'until': None if r.get('persistent') else at + (r.get('timeoutMs') or 0) / 1000}
+    if r.get('isAsync') and r.get('agentId'):
+        return r['agentId'], {'kind': 'agent', 'what': r.get('description') or inp.get('description') or '', 'until': None}
+
+
+def pending(path, now: float = None) -> list:
+    """The jobs still running as of `now`: [{id, kind: shell|monitor|agent, what, until (epoch s, None = no deadline)}]."""
+    now, uses, jobs = now or time.time(), {}, {}
+    try: f = open(path, encoding='utf-8', errors='replace')
+    except (OSError, TypeError): return []
+    with f:
+        for l in f:
+            if not any(m in l for m in _MARKS): continue
+            try: o = json.loads(l)
+            except ValueError: continue
+            c = o.get('content') if o.get('type') == 'queue-operation' else (o.get('message') or {}).get('content')
+            if isinstance(c, str):
+                # the queued copy counts as well as the delivered one: the job has ended even before Claude reads it
+                if '<task-notification>' in c and _ENDED.search(c):
+                    for i in _TID.findall(c): jobs.pop(i, None)
+                continue
+            for b in c if isinstance(c, list) else []:
+                if not isinstance(b, dict): continue
+                if b.get('type') == 'tool_use':
+                    uses[b.get('id')] = b
+                    if b.get('name') == 'TaskStop':
+                        inp = b.get('input') or {}
+                        jobs.pop(str(inp.get('task_id') or inp.get('shell_id') or ''), None)
+                elif b.get('type') == 'tool_result' and isinstance(o.get('toolUseResult'), dict):
+                    got = _started(o['toolUseResult'], (uses.get(b.get('tool_use_id')) or {}).get('input') or {}, _epoch(o.get('timestamp')))
+                    if got: jobs[got[0]] = got[1]
+    return [dict(id=k, **v) for k, v in jobs.items() if v['until'] is None or v['until'] > now]
+
+
+def from_hook(p: dict):
+    """The jobs Claude itself says are running, off its Stop payload - None when this Claude does not send the list.
+
+    Claude 2.1.286 carries `background_tasks` on Stop and SubagentStop (measured 2026-10-01; the hooks reference does
+    not list it): [{id, type: shell|subagent, status, description, command|agent_type}], shrinking as each job ends.
+    A monitor is a `shell` there. The CLI's own word, so it needs no deadline; the transcript read is for a Claude
+    without it. `ambient` is the SDK's mark for housekeeping a host should not count as activity."""
+    got = p.get('background_tasks')
+    if not isinstance(got, list): return None
+    return [{'id': str(t.get('id') or ''), 'kind': 'agent' if t.get('type') == 'subagent' else str(t.get('type') or 'task'),
+             'what': str(t.get('description') or t.get('command') or '')[:120], 'until': None}
+            for t in got if isinstance(t, dict) and t.get('status', 'running') == 'running' and not t.get('ambient')]
+
+
+def is_wake(prompt) -> bool:
+    "a turn the CLI took because background work reported - a UserPromptSubmit nobody typed (Claude's, Copilot's)"
+    return str(prompt or '').lstrip().startswith(('<task-notification>', '<system_notification>'))
+
+
+# COPILOT (1.0.86, measured 2026-10-01) sends no list on Stop, but says both ends in its hooks: a shell started with
+# `mode: async` answers "<command started in background with shellId: 0>", and its end is a Notification
+# `shell_completed` naming "(shellId: 0)" - then Copilot wakes and takes a turn on it. `detach` is the other way: a
+# server left to outlive the session, which nobody wakes for, so it is not counted. No timeout is said, so a cap.
+_STARTED = re.compile(r'started in background with shellId:\s*([\w-]+)')
+_SHELL_ID = re.compile(r'shellId:\s*([\w-]+)')
+CAP_S = 7200
+
+
+def track(jobs: dict, p: dict) -> None:
+    "keep a session's own running jobs from its hook events (`jobs` lives on the pane: a pane and its jobs die together)"
+    ev = p.get('hook_event_name')
+    if ev == 'PostToolUse':
+        inp, res = p.get('tool_input') or {}, p.get('tool_result') or p.get('tool_response') or {}
+        m = _STARTED.search(str(res.get('text_result_for_llm') if isinstance(res, dict) else res))
+        if m and isinstance(inp, dict) and not inp.get('detach'):
+            jobs[m.group(1)] = {'id': m.group(1), 'kind': 'shell', 'what': str(inp.get('description') or inp.get('command') or '')[:120],
+                                'until': time.time() + CAP_S}
+    elif ev == 'Notification' and str(p.get('notification_type') or '').startswith('shell_'):
+        m = _SHELL_ID.search(str(p.get('message') or ''))
+        if m: jobs.pop(m.group(1), None)
+
+
+def live(jobs, now: float = None) -> list:
+    "the ones of a recorded list still inside their deadline"
+    now = now or time.time()
+    return [j for j in jobs or [] if isinstance(j, dict) and (j.get('until') is None or j['until'] > now)]
+
+
+def summary(jobs) -> str:
+    "'1 shell, 1 monitor still running' - the words Claude's own footer uses"
+    n = {}
+    for j in jobs: n[j['kind']] = n.get(j['kind'], 0) + 1
+    return ', '.join(f"{v} {k}{'' if v == 1 else 's'}" for k, v in n.items()) + ' still running' if n else ''

{taskuary-0.3.7.2 → taskuary-0.3.7.4}/taskuary/channels.py

@@ -769,6 +769,9 @@ def retire_draft_answered_elsewhere(store, tid: int | None, sent: dict) -> list:
         where = f'TQ-{tid:04d}'
         state = ' The task is still open because it has other work in progress.' \
             if task.get('Status') not in ('done', 'dropped') else ' I marked the task done.'
+    # ...said in the Assistant's conversation - and never as a dead end: the page offers Next under the newest line that has
+    # nothing to press (the owner, 2026-09-30: "it can write that and close task ... but then should move to next or at least
+    # have buttons to navigate")
     from . import concierge, funnel, general
     concierge.record(store, general.dock_task(store)[0]['TaskId'], 'assistant',
                      f'You replied {place} on {where}{excerpt}. '

taskuary-0.3.7.4/taskuary/chatgptauth.py

@@ -0,0 +1,268 @@
+"""Sign in with ChatGPT - the owner's ChatGPT plan as a brain, no API key.
+
+OpenAI's plan sharing for open-source, locally hosted apps (DevDay 2026, developers.openai.com/siwc):
+the owner signs in once in their own browser, OpenAI registers a client for THIS install on the fly
+(dynamic registration - there is no Taskuary app id to ship), and model calls are billed to their
+ChatGPT allowance under a weekly cap they set per app. The Codex CLI already rode the plan for coding;
+this is the same plan for the one-message jobs - triage, the Assistant, reports - which only ever
+spoke to API keys.
+
+The shape is msauth's: the refresh token is the card's secret, access tokens are minted from it and
+cached, a rotated refresh token is handed to on_rotate so it survives a restart. What differs is the
+sign-in itself: a browser redirect to a loopback listener on 127.0.0.1 (the only redirect OpenAI
+takes for desktop apps), with PKCE, state and nonce fresh per attempt.
+
+Limits the card states (developers.openai.com/siwc/.../preview-limitations): images, files, function tools and web
+search where the model accepts them; no image generation, file search, code interpreter, computer use or hosted
+connectors. Streamed and never stored on OpenAI's side; a cap reached stops the brain until the owner raises it.
+"""
+import base64, hashlib, json, re, secrets, threading, time, uuid
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+import requests
+from loguru import logger
+
+AUTH = 'https://auth.openai.com'
+API = 'https://api.openai.com/v1'
+SCOPES = 'openid profile email offline_access resource.invoke chatgpt.tokens.use.direct'
+PLAN_SCOPE = 'chatgpt.tokens.use.direct'   # without it the sign-in worked and no call will
+PORT = 1455                                # OpenAI's example; anything on loopback is taken, so a busy port is not fatal
+AGENT_NAME = 'Taskuary'
+
+_CACHE, _LOCK = {}, threading.Lock()       # refresh token -> (access, expires_at, current refresh token)
+_FLOWS = {}                                # flow id -> one sign-in in progress
+on_rotate = None                           # set by the server: (connector id, new refresh token) -> None
+
+
+def host_id(cfg: dict) -> str:
+    """This install's stable, opaque id - usage is counted per host. Minted once, kept on the card."""
+    return (cfg or {}).get('host_id') or f'urn:uuid:{uuid.uuid4()}'
+
+
+def _b64(b: bytes) -> str: return base64.urlsafe_b64encode(b).rstrip(b'=').decode()
+
+
+class _Callback(BaseHTTPRequestHandler):
+    """One GET, the browser coming back from auth.openai.com. Everything else is a 404."""
+    def do_GET(self):
+        u = urlparse(self.path)
+        f = self.server.flow
+        if u.path != '/auth/callback':
+            self.send_response(404); self.end_headers(); return
+        q = {k: v[0] for k, v in parse_qs(u.query).items()}
+        if q.get('state') != f['state']: f['error'] = 'the sign-in came back for a different attempt - start it again'
+        elif q.get('error'): f['error'] = q.get('error_description') or q['error']
+        else: f['code'], f['client_id'], f['scope'] = q.get('code'), q.get('client_id') or f['client_id'], q.get('scope', '')
+        ok = not f.get('error')
+        body = (f"<!doctype html><meta charset=utf-8><title>Taskuary</title><body style='font:15px system-ui;margin:3em'>"
+                f"<h2>{'Signed in to ChatGPT' if ok else 'The sign-in did not finish'}</h2>"
+                f"<p>{'You can close this tab - Taskuary is finishing on its own.' if ok else f.get('error', '')}</p>").encode()
+        self.send_response(200); self.send_header('Content-Type', 'text/html; charset=utf-8'); self.end_headers()
+        self.wfile.write(body)
+        threading.Thread(target=self.server.shutdown, daemon=True).start()
+    def log_message(self, *a): pass       # the request line would carry the code into the log
+
+
+class _Server(HTTPServer):
+    # HTTPServer sets SO_REUSEADDR, and on Windows that lets a SECOND socket bind a port another one is listening on -
+    # a Codex login or an earlier sign-in holding 1455 would then share it, and the browser could come back to the
+    # wrong listener. Refused instead, so the next line moves to a free port.
+    allow_reuse_address = False
+
+
+def _listen() -> HTTPServer:
+    for port in (PORT, 0):
+        try: return _Server(('127.0.0.1', port), _Callback)
+        except OSError: continue          # a Codex login holding 1455 is not a reason to fail
+    raise RuntimeError('could not open a local port for the sign-in to return to')
+
+
+def start(cfg: dict) -> dict:
+    """Begin a sign-in: the URL to open in the browser, and a flow id to poll with."""
+    for k, v in list(_FLOWS.items()):
+        if time.time() - v['at'] > 900: _stop(k)
+    verifier = _b64(secrets.token_bytes(32))
+    srv = _listen()
+    redirect = f'http://127.0.0.1:{srv.server_address[1]}/auth/callback'
+    flow = {'state': secrets.token_urlsafe(24), 'nonce': secrets.token_urlsafe(24), 'verifier': verifier, 'redirect': redirect,
+            'host_id': host_id(cfg), 'client_id': (cfg or {}).get('client_id') or 'dynamic_agent_client', 'at': time.time(), 'srv': srv}
+    srv.flow = flow
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    q = {'client_id': flow['client_id'], 'response_type': 'code', 'redirect_uri': redirect, 'scope': SCOPES,
+         'resource': API, 'state': flow['state'], 'nonce': flow['nonce'], 'code_challenge_method': 'S256',
+         'code_challenge': _b64(hashlib.sha256(verifier.encode()).digest())}
+    # a first sign-in registers this install; a card that already holds a client id signs back in to it
+    if q['client_id'] == 'dynamic_agent_client': q.update(agent_name_hint=AGENT_NAME, ext_agent_host_id=flow['host_id'])
+    fid = secrets.token_urlsafe(12)
+    _FLOWS[fid] = flow
+    return {'flow': fid, 'url': f'{AUTH}/api/accounts/authorize?{urlencode(q)}'}
+
+
+def _stop(fid):
+    f = _FLOWS.pop(fid, None)
+    if f:
+        try: f['srv'].shutdown(); f['srv'].server_close()
+        except Exception: pass
+
+
+def poll(fid: str) -> dict:
+    """{'pending': True} until the browser comes back; then the tokens and who signed in. Raises on refusal."""
+    f = _FLOWS.get(fid)
+    if not f: raise RuntimeError('no such sign-in in progress - start it again')
+    if f.get('error'): _stop(fid); raise RuntimeError(f['error'])
+    if not f.get('code'):
+        if time.time() - f['at'] > 900: _stop(fid); raise RuntimeError('the sign-in took too long - start it again')
+        return {'pending': True}
+    _stop(fid)
+    r = requests.post(f'{AUTH}/api/accounts/oauth/token', timeout=20, data={
+        'grant_type': 'authorization_code', 'client_id': f['client_id'], 'code': f['code'],
+        'code_verifier': f['verifier'], 'redirect_uri': f['redirect'], 'resource': API})
+    if r.status_code != 200: raise RuntimeError(f'OpenAI refused the sign-in ({r.status_code}): {_err(r)}')
+    t = r.json()
+    granted = str(t.get('scope') or f.get('scope') or '')
+    if PLAN_SCOPE not in granted.split():
+        raise RuntimeError('signed in, but ChatGPT plan usage was not granted - sign in again and allow it')
+    if not t.get('refresh_token'): raise RuntimeError('OpenAI returned no refresh token - offline access was not granted')
+    who = _identity(t.get('id_token'), f['nonce'])
+    return {'client_id': f['client_id'], 'host_id': f['host_id'], 'refresh_token': t['refresh_token'],
+            'access_token': t['access_token'], 'expires_in': t.get('expires_in'), 'scope': granted, **who}
+
+
+def _identity(id_token: str, nonce: str) -> dict:
+    """Who signed in, from the ID token. It came straight from the token endpoint over TLS, which OpenID Connect
+    accepts in place of a signature check (Core 3.1.3.7); issuer, expiry and our nonce are still checked."""
+    if not id_token: return {'sub': '', 'email': '', 'name': ''}
+    try:
+        part = id_token.split('.')[1]
+        c = json.loads(base64.urlsafe_b64decode(part + '=' * (-len(part) % 4)))
+    except (IndexError, ValueError): raise RuntimeError('OpenAI sent an ID token that does not parse')
+    if c.get('nonce') != nonce: raise RuntimeError('the sign-in answer does not belong to this attempt (nonce) - start it again')
+    if not str(c.get('iss') or '').startswith(AUTH): raise RuntimeError(f"unexpected token issuer {c.get('iss')!r}")
+    if c.get('exp') and float(c['exp']) < time.time(): raise RuntimeError('the sign-in answer had already expired - start it again')
+    return {'sub': c.get('sub', ''), 'email': c.get('email', ''), 'name': c.get('name', '')}
+
+
+_DEAD = {'invalid_grant', 'invalid_refresh_token', 'token_expired', 'refresh_token_expired', 'refresh_token_invalidated', 'refresh_token_reused'}
+
+
+def refresh(cfg: dict, refresh_token: str) -> dict:
+    r = requests.post(f'{AUTH}/api/accounts/oauth/token', timeout=20, data={
+        'grant_type': 'refresh_token', 'client_id': cfg.get('client_id') or '', 'refresh_token': refresh_token, 'resource': API})
+    if r.status_code != 200:
+        code = _code(r)
+        if code in _DEAD: raise RuntimeError('the ChatGPT sign-in has lapsed - sign in again on the ChatGPT card')
+        raise RuntimeError(f'OpenAI would not renew the ChatGPT sign-in ({r.status_code}): {_err(r)}')
+    return r.json()
+
+
+def access_token(cfg: dict, refresh_token: str) -> str:
+    """A live access token - cached until a minute before expiry; the mint is inside the lock so two callers never rotate
+    the refresh token out from under each other (a reused one is refused: refresh_token_reused)."""
+    if not refresh_token: raise RuntimeError('not signed in - click "Sign in with ChatGPT" on the ChatGPT card')
+    with _LOCK:
+        hit = _CACHE.get(refresh_token)
+        if hit and hit[1] > time.time() + 60: return hit[0]
+        rt_now = hit[2] if hit else refresh_token
+        t = refresh(cfg, rt_now)
+        new_rt = t.get('refresh_token') or rt_now
+        _CACHE[refresh_token] = (t['access_token'], time.time() + int(t.get('expires_in') or 3600), new_rt)
+    if new_rt != refresh_token and on_rotate and cfg.get('_cid'):
+        try: on_rotate(cfg['_cid'], new_rt)
+        except Exception as e: logger.warning(f'could not persist the rotated ChatGPT refresh token: {e}')
+    return t['access_token']
+
+
+def revoke(cfg: dict, refresh_token: str) -> None:
+    """Sign out: end the renewable session at OpenAI, not just forget it here."""
+    try:
+        conf = requests.get(f'{AUTH}/.well-known/openid-configuration', timeout=15).json()
+        requests.post(conf['revocation_endpoint'], timeout=15, data={
+            'token': refresh_token, 'token_type_hint': 'refresh_token', 'client_id': cfg.get('client_id') or ''})
+    except Exception as e: logger.warning(f'could not revoke the ChatGPT session at OpenAI: {e}')
+    with _LOCK: _CACHE.pop(refresh_token, None)
+
+
+def models(token: str) -> list:
+    """[(slug, display name)] the plan offers - the ones OpenAI marks for listing."""
+    r = requests.get(f'{API}/models', headers={'Authorization': f'Bearer {token}'}, timeout=20)
+    if r.status_code != 200: raise RuntimeError(f'OpenAI would not list the plan models ({r.status_code}): {_err(r)}')
+    # the docs show `data`; the plan answers with `models` (slug / display_name / visibility), the shape Codex caches
+    # in ~/.codex/models_cache.json - read either, and say what came back rather than "no models" when neither is there
+    j = r.json()
+    rows = j.get('models') or j.get('data') or []
+    if not rows: raise RuntimeError(f'OpenAI listed no plan models (the answer carried: {sorted(j) or "nothing"})')
+    return [(m.get('slug') or m.get('id'), m.get('display_name') or m.get('slug') or m.get('id'))
+            for m in rows if m.get('visibility', 'list') == 'list' and (m.get('slug') or m.get('id'))]
+
+
+# what each refusal means, and whether trying again can help (errors-and-recovery)
+_CALL_ERRORS = {
+    'subscription_sharing_usage_limit_exceeded': 'the weekly cap for Taskuary on your ChatGPT plan is used up - raise it in ChatGPT → Settings, or wait for it to reset',
+    'subscription_sharing_user_not_eligible': 'this ChatGPT account is not eligible to share its plan with apps',
+    'subscription_sharing_unsupported_capability': 'the plan does not serve part of this request (an image or a tool this model does not take)',
+    'subscription_sharing_invalid_user': 'the ChatGPT sign-in is no longer valid - sign in again on the ChatGPT card',
+}
+
+
+class Unsupported(RuntimeError):
+    """The plan cannot serve something in this request (an image, a tool) - worth asking again without it."""
+
+
+_OPTIONAL = ('text', 'max_output_tokens', 'instructions')
+
+
+def complete(token: str, model: str, system: str, user: str, max_tokens: int, want: dict = None, timeout: int = 120,
+             images=None, web: bool = False) -> str:
+    """One answer, streamed (the plan serves nothing else) and never stored. Only `response.completed` is success:
+    a stream that stops early is a failure, not a short answer."""
+    content = [{'type': 'input_image', 'image_url': f'data:{ct};base64,{b64}'} for ct, b64 in (images or [])]
+    # no max_output_tokens: the plan's endpoint refuses it ("Unsupported parameter", measured 2026-09-30)
+    body = {'model': model, 'instructions': system, 'store': False, 'stream': True,
+            'input': [{'role': 'user', 'content': content + [{'type': 'input_text', 'text': user}]}]}
+    if web: body['tools'] = [{'type': 'web_search'}]
+    if want: body['text'] = {'format': {'type': 'json_schema', 'name': want.get('name') or 'answer',
+                                        'schema': want.get('schema') or want, 'strict': True}}
+    # An OPTIONAL field the plan names as unsupported is taken out and the question asked again - the schema then
+    # lives in the prompt, as it does for every brain that cannot carry one. `tools` is the caller's to drop.
+    for _ in range(3):
+        r = requests.post(f'{API}/responses', json=body, stream=True, timeout=timeout,
+                          headers={'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'})
+        if r.status_code == 200: break
+        field = (re.search(r'Unsupported parameter: ([\w]+)', _err(r)) or [None, None])[1]
+        r.close()
+        if field == 'tools': raise Unsupported(f'the plan does not take tools on this model: {_err(r)}')
+        if field in _OPTIONAL and field in body: body.pop(field); continue
+        code = _code(r)
+        if code == 'subscription_sharing_unsupported_capability': raise Unsupported(_CALL_ERRORS[code])
+        raise RuntimeError(_CALL_ERRORS.get(code) or f'ChatGPT plan call failed ({r.status_code}): {_err(r)}')
+    with r:
+        if r.status_code != 200: raise RuntimeError(f'ChatGPT plan call failed ({r.status_code}): {_err(r)}')
+        out, done = [], False
+        for line in r.iter_lines(decode_unicode=True):
+            if not line or not line.startswith('data:'): continue
+            data = line[5:].strip()
+            if data == '[DONE]': break
+            try: ev = json.loads(data)
+            except ValueError: continue
+            kind = ev.get('type')
+            if kind == 'response.output_text.delta': out.append(ev.get('delta') or '')
+            elif kind == 'response.completed': done = True; break
+            elif kind in ('response.failed', 'error'):
+                err = (ev.get('response') or {}).get('error') or ev.get('error') or {}
+                raise RuntimeError(_CALL_ERRORS.get(err.get('code')) or f"ChatGPT plan call failed: {err.get('message') or err.get('code') or kind}")
+    if not done: raise RuntimeError('the ChatGPT plan answer stopped before it finished - try again')
+    return ''.join(out)
+
+
+def _code(r) -> str:
+    try: j = r.json()
+    except ValueError: return ''
+    e = j.get('error')
+    return (e.get('code') if isinstance(e, dict) else e) or ''
+
+
+def _err(r) -> str:
+    try:
+        j = r.json(); e = j.get('error')
+        return (e.get('message') if isinstance(e, dict) else j.get('error_description') or e or j.get('detail')) or r.text[:300]
+    except ValueError: return r.text[:300]