taskuary 0.2.0__py3-none-any.whl

taskuary/llm.py

@@ -0,0 +1,175 @@
+"""The triage brain -> one provider-agnostic llm(system, user) -> str callable, the shape
+triage.classify_intent expects. Which brain is the owner's choice (setting `triage_ai`):
+
+    ''                  first ACTIVE AI connector with a key (anthropic/openai/azure_openai/
+                        openrouter) - or keyless ollama, for a local model
+
+    connector:<type>    that specific AI connector
+    cli:<agent>         your CODING CLI does the triage too - one headless run per message,
+                        same brain that works the tasks, no second API key to buy
+
+Cloud keys are cheap and instant per message; a CLI run is slower and heavier but keeps
+everything on one model (and one bill). Configure it in Settings -> Triage & routing.
+"""
+import base64, json, mimetypes, requests
+from pathlib import Path
+
+AI_TYPES = ('anthropic', 'openai', 'azure_openai', 'openrouter', 'ollama')
+
+# What a vision model will look at. "See below." is half the mail this app reads, and below was
+# a screenshot - a text-only funnel filed the sentence and threw the actual ask away.
+VISION_TYPES = ('image/png', 'image/jpeg', 'image/gif', 'image/webp')
+VISION_MAX, VISION_BYTES = 4, 5 * 1024 * 1024      # per call: how many images, and how big each
+
+
+def readable_images(store, message_ids, cap: int = VISION_MAX) -> list:
+    """[(media_type, base64)] for the images on these messages, or [] when the owner has vision
+    switched off. SVG and PDF are skipped: no provider takes them as image input."""
+    if str(store.get_settings().get('vision_enabled') or '1') != '1': return []
+    out = []
+    for mid in message_ids or []:
+        for a in store.list_attachments(mid):
+            if len(out) >= cap: return out
+            ct = str(a.get('ContentType') or '').split(';')[0].lower()
+            path = a.get('Path')
+            if not path: continue
+            if ct not in VISION_TYPES:
+                ct = mimetypes.guess_type(path)[0] or ''
+                if ct not in VISION_TYPES: continue
+            f = Path(path)
+            try:
+                if not f.is_file() or f.stat().st_size > VISION_BYTES: continue
+                out.append((ct, base64.b64encode(f.read_bytes()).decode()))
+            except OSError:
+                continue
+    return out
+# Triage answers with a one-line JSON object, so it needs almost nothing. A report SUMMARY
+# needs room - and on a reasoning model a small budget is spent thinking and the visible
+# answer comes back EMPTY, which is how reports ended up filing raw data with no summary.
+MAX_TOKENS = 400
+
+
+def make_cli_llm(store, agent_name: str, model: str = None):
+    """A CLI agent as the classifier: prompt in on stdin, JSON out. The repo working dir
+    is dropped - triage is about the message, not about any checkout.
+
+    And the MODEL drops a tier: `light_model` on the agent profile (Connectors > AI CLI
+    agents) is what runs here - triage, drafts, summaries, the digest - while the profile's
+    main `model` stays reserved for the coding sessions. One brain, two gears: the classifier
+    reads one email; it does not need the model that rewrites your codebase."""
+    row = store.get_agent(agent_name)
+    if not row: return None
+    prof = {k: v for k, v in json.loads(row.get('Config') or '{}').items() if k not in ('cwd', 'cwd_map')}
+    light = str(prof.get('light_model') or '')
+    if light.startswith('effort:'):
+        # codex on a ChatGPT plan serves ONLY the plan's models - no mini/nano tier exists -
+        # so its cheap gear is reasoning effort on the same model (verified: -c
+        # model_reasoning_effort=low answers in a fraction of the tokens)
+        prof['args'] = list(prof.get('args') or []) + ['-c', f"model_reasoning_effort={light.split(':', 1)[1].strip()}"]
+    elif light:
+        prof['model'] = light
+    if model: prof['model'] = model     # an explicit per-job model outranks the light gear
+    prof['timeout'] = min(int(prof.get('timeout') or 300), 300)
+    def llm(system, user, max_tokens=MAX_TOKENS, images=None):
+        """max_tokens is advisory here - a CLI has no such flag; the system prompt already says
+        how long the answer should be. `images` is accepted and dropped: a CLI reads files off
+        disk itself, and the prompt already names their paths."""
+        from .agents import run_cli
+        out, _sid, _diff = run_cli(prof, f'{system}\n\n{user}', lambda *a: None)
+        return out
+    return llm
+
+
+def build_llm(store, pick=None, model=None):
+    """The brain named by `pick` ('' = first active AI connector, 'connector:<type>',
+    'cli:<agent>'), defaulting to the triage_ai setting - callers like reports may name
+    their OWN brain and model per job instead of riding the triage tier."""
+    pick = (pick if pick is not None else store.get_settings().get('triage_ai') or '').strip()
+    if pick.startswith('cli:'): return make_cli_llm(store, pick[4:], model)
+    want = pick[10:] if pick.startswith('connector:') else None
+    for c in store.list_connectors():
+        # a local model server (ollama) is the one brain that needs no key to be real
+        ready = c['Active'] and (c['HasSecret'] or c['Type'] == 'ollama')
+        if c['Type'] in AI_TYPES and ready and (not want or c['Type'] == want):
+            full = store.get_connector(c['ConnectorId'], with_secret=True)
+            cfg = json.loads(full.get('ConfigJson') or '{}')
+            if model: cfg = {**cfg, 'model': model}
+            return make_llm(full['Type'], cfg, full.get('Secret'))
+    return None
+
+
+def make_llm(t, cfg: dict, key: str):
+    if not key and t != 'ollama': raise RuntimeError('no API key saved - paste one under Credentials')
+    if t == 'anthropic':
+        import anthropic
+        cli = anthropic.Anthropic(api_key=key)
+        model = cfg.get('model') or 'claude-opus-5'
+        def llm(system, user, max_tokens=MAX_TOKENS, images=None):
+            # images FIRST: every provider reads a picture better when the question follows it
+            content = ([{'type': 'image', 'source': {'type': 'base64', 'media_type': ct, 'data': b64}}
+                        for ct, b64 in (images or [])] + [{'type': 'text', 'text': user}]) if images else user
+            r = cli.messages.create(model=model, max_tokens=max_tokens, system=system,
+                                    messages=[{'role': 'user', 'content': content}])
+            if r.stop_reason == 'refusal': raise RuntimeError('model refused the request')
+            return next((b.text for b in r.content if b.type == 'text'), '')
+        return llm
+    if t == 'openai':
+        urls = ['https://api.openai.com/v1/chat/completions']
+        headers, model = {'Authorization': f'Bearer {key}'}, cfg.get('model') or 'gpt-4o-mini'
+    elif t == 'openrouter':
+        # one key, the whole catalog behind the OpenAI schema - open-weights models included.
+        # Model strings are OpenRouter's names ('meta-llama/llama-3.3-70b-instruct', ...);
+        # 'openrouter/auto' lets their router pick, so an empty model box still works.
+        urls = ['https://openrouter.ai/api/v1/chat/completions']
+        headers, model = {'Authorization': f'Bearer {key}', 'X-Title': 'Taskuary'}, cfg.get('model') or 'openrouter/auto'
+    elif t == 'ollama':
+        # a LOCAL server speaking the OpenAI surface. Ollama's port out of the box, but base_url
+        # reaches LM Studio (:1234), llama.cpp, vLLM - anything /v1-compatible - so open-source
+        # models triage your mail without a byte leaving the machine. No key unless the server
+        # demands one; the model must be named because only `ollama list` knows what's pulled.
+        base = (cfg.get('base_url') or 'http://127.0.0.1:11434').rstrip('/')
+        if not cfg.get('model'): raise RuntimeError('a local brain needs its model named - `ollama list` shows what is installed')
+        urls, model = [f'{base}/v1/chat/completions'], cfg['model']
+        headers = {'Authorization': f'Bearer {key}'} if key else {}
+    elif t == 'azure_openai':
+        ep = (cfg.get('endpoint') or '').rstrip('/')
+        if not (ep and cfg.get('deployment')): raise RuntimeError('azure_openai needs endpoint + deployment')
+        # Azure's v1 surface first (no api-version, OpenAI-compatible, all params work);
+        # legacy deployments URL as fallback for resources without it. An explicit
+        # api_version in the config skips straight to legacy with that version.
+        legacy = f"{ep}/openai/deployments/{cfg['deployment']}/chat/completions?api-version={cfg.get('api_version') or '2024-12-01-preview'}"
+        urls = [legacy] if cfg.get('api_version') else [f'{ep}/openai/v1/chat/completions', legacy]
+        headers, model = {'api-key': key}, cfg['deployment']
+    else:
+        raise RuntimeError(f'unknown AI connector type: {t}')
+
+    def llm(system, user, max_tokens=MAX_TOKENS, images=None):
+        # two independent compat axes: newer models reject max_tokens ("use
+        # max_completion_tokens"), older Azure api-versions reject max_completion_tokens,
+        # and older Azure resources 404 the v1 url - walk the grid until one works
+        content = ([{'type': 'image_url', 'image_url': {'url': f'data:{ct};base64,{b64}'}}
+                    for ct, b64 in (images or [])] + [{'type': 'text', 'text': user}]) if images else user
+        msgs = [{'role': 'system', 'content': system}, {'role': 'user', 'content': content}]
+        last = None
+        for url in urls:
+            for tok_param in ('max_completion_tokens', 'max_tokens'):
+                body = {'messages': msgs, tok_param: max_tokens}
+                if model: body['model'] = model
+                # a local model may spend its first call loading weights off disk - give it room
+                r = requests.post(url, headers=headers, json=body, timeout=180 if t == 'ollama' else 60)
+                if r.status_code == 200:
+                    return r.json()['choices'][0]['message']['content']
+                last = r
+                if r.status_code == 404: break                     # wrong surface -> next url
+                if not (r.status_code == 400 and 'max_completion_tokens' in r.text):
+                    raise RuntimeError(f'{t} error {r.status_code} at {url.split("?")[0]}: {r.text[:300]}')
+        raise RuntimeError(f'{t} error {last.status_code} at {urls[-1].split("?")[0]}: {last.text[:300]}')
+    return llm
+
+
+def test_ai(store, cid: int) -> str:
+    """Real round trip through the configured model; returns a detail string or raises."""
+    c = store.get_connector(cid, with_secret=True)
+    out = make_llm(c['Type'], json.loads(c.get('ConfigJson') or '{}'), c.get('Secret'))(
+        'Reply with exactly: ok', 'ping')
+    return f'model responded: {(out or "").strip()[:80]} - wired into intent triage'

taskuary/logs.py

@@ -0,0 +1,17 @@
+"""Logging: INFO on the console (DEBUG with --debug), always-DEBUG rotating file at
+~/.taskuary/taskuary.log - so 'it crashed / nothing happened' is always diagnosable
+after the fact. Every API request, report run, connector test and ingest logs here.
+"""
+import sys
+from loguru import logger
+
+from . import config
+
+
+def setup(debug: bool = False):
+    logger.remove()
+    logger.add(sys.stderr, level='DEBUG' if debug else 'INFO',
+               format='<green>{time:HH:mm:ss}</green> <level>{level: <7}</level> {message}')
+    logger.add(config.home() / 'taskuary.log', level='DEBUG', rotation='5 MB', retention=3,
+               enqueue=True, format='{time:YYYY-MM-DD HH:mm:ss} {level: <7} {name}:{line} {message}')
+    logger.info(f"log file: {config.home() / 'taskuary.log'}" + (' (debug console)' if debug else ''))

taskuary/mcp.py

@@ -0,0 +1,78 @@
+"""MCP connector for reports: call any MCP server's tool on a schedule and file the result
+on the timeline. Config: {"cmd": "npx", "args": [...], "tool": "query", "tool_args": {...},
+"env": {...}}. Minimal stdio JSON-RPC client (initialize -> initialized -> tools/call), no
+SDK dependency - keeps the single-exe desktop build lean. Spec: modelcontextprotocol.io.
+"""
+import json, os, subprocess, threading, queue
+
+PROTOCOL = '2025-06-18'
+
+
+class MCPClient:
+    """One short-lived stdio session with an MCP server."""
+
+    def __init__(self, cmd, args=None, env=None, timeout=60):
+        self.timeout, self._id = timeout, 0
+        self.p = subprocess.Popen([cmd] + list(args or []), stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                  stderr=subprocess.DEVNULL, text=True, encoding='utf-8',
+                                  env={**os.environ, **(env or {})}, shell=False)
+        self.q = queue.Queue()
+        threading.Thread(target=self._pump, daemon=True).start()
+
+    def _pump(self):
+        for line in self.p.stdout:
+            line = line.strip()
+            if line:
+                try: self.q.put(json.loads(line))
+                except ValueError: pass
+
+    def _send(self, msg):
+        self.p.stdin.write(json.dumps(msg) + '\n'); self.p.stdin.flush()
+
+    def request(self, method, params=None):
+        self._id += 1
+        self._send({'jsonrpc': '2.0', 'id': self._id, 'method': method, **({'params': params} if params else {})})
+        while True:
+            m = self.q.get(timeout=self.timeout)
+            if m.get('id') == self._id:
+                if 'error' in m: raise RuntimeError(f"{method}: {m['error'].get('message', m['error'])}")
+                return m.get('result', {})
+
+    def start(self):
+        self.request('initialize', {'protocolVersion': PROTOCOL, 'capabilities': {},
+                                    'clientInfo': {'name': 'taskuary', 'version': '0.1'}})
+        self._send({'jsonrpc': '2.0', 'method': 'notifications/initialized'})
+        return self
+
+    def list_tools(self): return self.request('tools/list').get('tools', [])
+    def call_tool(self, name, args=None): return self.request('tools/call', {'name': name, 'arguments': args or {}})
+
+    def close(self):
+        try: self.p.stdin.close(); self.p.terminate()
+        except Exception: pass
+
+
+def _session(cfg):
+    if not cfg.get('cmd'): raise ValueError('mcp connector needs "cmd" (the MCP server command)')
+    return MCPClient(cfg['cmd'], cfg.get('args'), cfg.get('env'), int(cfg.get('timeout', 60))).start()
+
+
+def list_tools(cfg) -> list:
+    c = _session(cfg)
+    try: return [{'name': t['name'], 'description': t.get('description', '')[:200]} for t in c.list_tools()]
+    finally: c.close()
+
+
+def run_report(cfg):
+    """Report executor: call cfg['tool'] and return (headline, text content)."""
+    c = _session(cfg)
+    try:
+        args = cfg.get('tool_args') or {}
+        if isinstance(args, str): args = json.loads(args or '{}')
+        res = c.call_tool(cfg['tool'], args)
+        if res.get('isError'): raise RuntimeError(str(res.get('content'))[:500])
+        texts = [b.get('text', '') for b in res.get('content', []) if b.get('type') == 'text']
+        body = '\n'.join(t for t in texts if t) or json.dumps(res, default=str)
+        return f"{cfg['tool']} ok", body[:4000]
+    finally:
+        c.close()

taskuary/messengers.py

@@ -0,0 +1,205 @@
+"""Telegram and WhatsApp as inbound channels - the personal-messenger half of the funnel.
+
+Telegram is light: a bot token and plain HTTPS (getUpdates / sendMessage), so it is built in
+entirely. WhatsApp has no sanctioned API for a personal account - the working road is Baileys,
+a Node library speaking the WhatsApp Web protocol - so Taskuary does NOT embed it: a small
+bridge script (taskuary/whatsapp/bridge.mjs) runs beside the app with its own npm install, and
+this module just polls the bridge over localhost HTTP. Heavy dependency, separate install;
+Taskuary's side is ~40 lines either way.
+
+Both are CHAT: messages land with a conversation id per chat, replies go back into the same
+chat, and the responder already knows not to sign chat messages.
+"""
+import base64, json
+import requests
+from loguru import logger
+
+TG_API = 'https://api.telegram.org'
+TG_LIMIT = 25                # messages per poll, like the other channels
+WA_URL = 'http://127.0.0.1:8977'   # the bridge's default; override in the connector config
+
+
+def _cfg(c): return json.loads(c.get('ConfigJson') or '{}')
+
+
+# ── Telegram ─────────────────────────────────────────────────────────────────────────────
+def tg(token: str, method: str, **params):
+    r = requests.post(f'{TG_API}/bot{token}/{method}', json=params, timeout=30)
+    j = r.json()
+    if not j.get('ok'): raise RuntimeError(f"telegram {method}: {j.get('description') or r.status_code}")
+    return j['result']
+
+
+def tg_test(store, c) -> str:
+    """getMe proves the token; a '*' source is added so the poller has something to walk -
+    it is a LISTENING marker only, never an admit-everything: a bot is public, and anyone
+    who finds it can message it. Chats announce themselves in getUpdates and are registered
+    OFF under Sources with their chat id; only the ones the owner flips on become work."""
+    if not c.get('Secret'): raise RuntimeError('no bot token saved - paste the token @BotFather gave you under Credentials')
+    me = tg(c['Secret'], 'getMe')
+    if not any(s['Channel'] == 'telegram' for s in store.list_sources(active_only=False)):
+        store.save_source({'Channel': 'telegram', 'Address': '*', 'ConnectorId': c['ConnectorId'], 'Active': 1}, 'connector-test')
+    return (f"authenticated as @{me.get('username')} - message the bot (or add it to a group), Sync, "
+            f"and the chat appears under Sources with its chat id, OFF. Flip on the chats that are "
+            f"yours; every other chat stays out (a public bot can be messaged by anyone)")
+
+
+def _tg_photo(token: str, m: dict) -> list:
+    """The largest rendition of an attached photo/document, shaped like a Graph fileAttachment
+    so channels.save_attachments and vision reuse the one pipeline."""
+    out = []
+    for kind, meta in (('photo', (m.get('photo') or [])[-1:]), ('document', [m['document']] if m.get('document') else [])):
+        for f in meta:
+            try:
+                path = tg(token, 'getFile', file_id=f['file_id']).get('file_path') or ''
+                data = requests.get(f'{TG_API}/file/bot{token}/{path}', timeout=60).content
+                name = f.get('file_name') or (path.rsplit('/', 1)[-1] or f'{kind}.jpg')
+                ct = f.get('mime_type') or ('image/jpeg' if kind == 'photo' else 'application/octet-stream')
+                out.append({'id': f['file_id'][:60], 'name': name, 'contentType': ct,
+                            'size': len(data), 'contentBytes': base64.b64encode(data).decode(),
+                            'isInline': kind == 'photo'})
+            except Exception as e:
+                logger.warning(f'telegram file fetch failed: {e}')
+    return out
+
+
+def poll_telegram(store, c, sources: list, llm=None, file_only=False) -> int:
+    """getUpdates with the offset watermark kept on the connector - Telegram's own cursor, so a
+    restart never re-ingests.
+
+    Only chats the owner switched ON become work. A bot is PUBLIC - anyone who finds it can
+    message it, and 'blank takes every chat' was an open door for spam-as-tasks. An unknown
+    chat is registered instead: it shows up under Sources with its chat id, off, and flipping
+    it on admits it from the next message onward. That registration is also how you FIND a
+    chat id - message the bot once and read it off the card."""
+    from datetime import datetime
+    from .channels import images_for_triage, save_attachments
+    from .ingest import ingest_message
+    tok, cfg = c['Secret'], _cfg(c)
+    if not tok: return 0
+    # every telegram source ever seen, on or off - a report source in the same list (the
+    # seeded Morning digest) must never become a chat-id nothing can match
+    known = {s['Address']: s for s in store.list_sources(active_only=False)
+             if s.get('Channel') == 'telegram' and s.get('Address')}
+    want = {a for a, s in known.items() if a != '*' and s.get('Active')}
+    ups = tg(tok, 'getUpdates', offset=int(cfg.get('tg_offset') or 0), limit=TG_LIMIT,
+             allowed_updates=['message'])
+    n = 0
+    for u in ups:
+        m = u.get('message') or {}
+        chat, frm = m.get('chat') or {}, m.get('from') or {}
+        cid = str(chat.get('id') or '')
+        if not cid or frm.get('is_bot'): continue
+        # a reply in the NOTIFY chat may be a verdict on a pinged review ("approve") - it is
+        # handled before the approve-first filter, so the notify chat never needs a source
+        # row and the owner's verdicts never become work (see phone.py)
+        from . import phone
+        if phone.intercept(store, 'telegram', cid, m.get('text') or m.get('caption') or '',
+                           (m.get('reply_to_message') or {}).get('text')):
+            continue
+        if cid not in want:
+            if cid not in known:      # first sight of this chat: register it OFF, ingest nothing
+                title = chat.get('title') or ' '.join(x for x in (frm.get('first_name'), frm.get('last_name')) if x) \
+                        or frm.get('username') or 'chat'
+                store.save_source({'Channel': 'telegram', 'Address': cid, 'ConnectorId': c['ConnectorId'],
+                                   'Active': 0, 'Owner': f'discovered: {title}'[:80]}, 'telegram-poll')
+                known[cid] = {'Address': cid, 'Active': 0}
+                logger.info(f'telegram: chat {cid} ({title}) discovered - registered OFF under Sources')
+            continue
+        text = m.get('text') or m.get('caption') or ''
+        atts = _tg_photo(tok, m) if (m.get('photo') or m.get('document')) else []
+        if not text and not atts: continue
+        who = ' '.join(x for x in (frm.get('first_name'), frm.get('last_name')) if x) or frm.get('username') or 'someone'
+        out = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"telegram:{cid}:{m.get('message_id')}", 'channel': 'telegram',
+            'subject': None, 'body': text or '(no text - see the attachment)',
+            'from_name': who, 'from_email': f"@{frm['username']}" if frm.get('username') else None,
+            'conversation_id': f'telegram:{cid}',
+            'sent_at': datetime.fromtimestamp(m.get('date') or 0).strftime('%Y-%m-%d %H:%M:%S'),
+            'source_name': chat.get('title') or who,
+            'images': images_for_triage(store, atts)}, llm=llm)
+        n += out['status'] != 'duplicate'
+        if atts and out.get('message_id') and out['status'] != 'duplicate':
+            try: save_attachments(store, out['message_id'], atts, f"telegram:{cid}:{m.get('message_id')}")
+            except Exception as e: logger.warning(f'telegram attachments failed: {e}')
+    if ups:
+        store.set_connector_config(c['ConnectorId'], {**cfg, 'tg_offset': ups[-1]['update_id'] + 1})
+    return n
+
+
+def tg_send(store, chat_id: str, body: str) -> dict:
+    c = store.get_connector_by_type('telegram', with_secret=True)
+    if not (c and c.get('Secret')): raise RuntimeError('the Telegram connection is not set up')
+    tg(c['Secret'], 'sendMessage', chat_id=int(chat_id), text=body[:4000])
+    return {'channel': 'telegram', 'chat': chat_id}
+
+
+# ── WhatsApp (via the Baileys bridge) ────────────────────────────────────────────────────
+def _wa(c, path, body=None):
+    url = (_cfg(c).get('bridge_url') or WA_URL).rstrip('/')
+    try:
+        r = requests.post(f'{url}{path}', json=body, timeout=20) if body is not None \
+            else requests.get(f'{url}{path}', timeout=20)
+    except requests.ConnectionError:
+        raise RuntimeError(f'the WhatsApp bridge is not running at {url} - start it: '
+                           f'cd taskuary/whatsapp && npm install && node bridge.mjs')
+    if r.status_code >= 300: raise RuntimeError(f'bridge {path} failed ({r.status_code}): {r.text[:200]}')
+    return r.json()
+
+
+def wa_test(store, c) -> str:
+    st = _wa(c, '/status')
+    if not st.get('connected'):
+        raise RuntimeError('bridge is running but WhatsApp is not paired yet - '
+                           + (f"enter code {st['pairingCode']} on your phone (Linked devices)" if st.get('pairingCode')
+                              else 'scan the QR the bridge printed in its own terminal'))
+    if not any(s['Channel'] == 'whatsapp' for s in store.list_sources(active_only=False)):
+        store.save_source({'Channel': 'whatsapp', 'Address': '*', 'ConnectorId': c['ConnectorId'], 'Active': 1}, 'connector-test')
+    return f"paired as {st.get('me') or 'your account'} - chats flow in on the next sync"
+
+
+def poll_whatsapp(store, c, sources: list, llm=None, file_only=False) -> int:
+    """The bridge keeps a sequence number per message; ours is on the connector, so nothing is
+    read twice and a bridge restart just resets both to live traffic."""
+    from datetime import datetime
+    from .ingest import ingest_message
+    cfg = _cfg(c)
+    want = {s['Address'] for s in sources
+            if s.get('Channel', 'whatsapp') == 'whatsapp' and s['Address'] and s['Address'] != '*'}
+    out = _wa(c, f"/messages?after={int(cfg.get('wa_seq') or 0)}")
+    n, took = 0, []
+    from . import phone
+    for m in out.get('messages', []):
+        jid = m.get('jid') or ''
+        if not jid: continue
+        # the WhatsApp bridge is the owner's OWN account, so a verdict they type in the
+        # notify chat arrives as fromMe - intercept runs before that filter (phone.py also
+        # recognizes and swallows our own pings echoing back through the bridge)
+        if (m.get('text') or '').strip() and phone.intercept(store, 'whatsapp', jid, m['text']):
+            continue
+        if m.get('fromMe') or (want and jid not in want): continue
+        if not (m.get('text') or '').strip(): continue
+        r = ingest_message(store, file_only=file_only, msg={
+            'external_id': f"whatsapp:{jid}:{m.get('id')}", 'channel': 'whatsapp',
+            'subject': None, 'body': m['text'], 'from_name': m.get('name') or jid.split('@')[0],
+            'conversation_id': f'whatsapp:{jid}',
+            'sent_at': datetime.fromtimestamp(m.get('ts') or 0).strftime('%Y-%m-%d %H:%M:%S'),
+            'source_name': ('group chat' if m.get('group') else m.get('name')) or 'WhatsApp'}, llm=llm)
+        n += r['status'] != 'duplicate'
+        took.append(m.get('id'))
+    # blue ticks on what the funnel took, when the owner asked for it - best effort, and
+    # never at the cost of the poll: an unpaired or restarted bridge just does not mark
+    from .channels import wants_read
+    if took and wants_read(store):
+        try: _wa(c, '/read', {'ids': [i for i in took if i]})
+        except Exception as e: logger.warning(f'marking whatsapp read failed: {e}')
+    if out.get('seq') is not None:
+        store.set_connector_config(c['ConnectorId'], {**cfg, 'wa_seq': out['seq']})
+    return n
+
+
+def wa_send(store, jid: str, body: str) -> dict:
+    c = store.get_connector_by_type('whatsapp', with_secret=True)
+    if not c: raise RuntimeError('the WhatsApp connection is not set up')
+    _wa(c, '/send', {'jid': jid, 'text': body[:4000]})
+    return {'channel': 'whatsapp', 'chat': jid}

taskuary/mssql.py

@@ -0,0 +1,64 @@
+"""Microsoft SQL Server connector - local-first via pyodbc. Structured config (no DSN
+strings to hand-craft): {"server", "database", "auth": "windows"|"sql", "username",
+"password", "driver", "query"}. Windows auth is the default because local SQL Server is
+the primary use case; `driver` auto-picks the newest installed 'ODBC Driver NN for SQL
+Server'. TrustServerCertificate=yes because Driver 18 mandates encryption and local
+instances rarely have real certs. A raw "conn_str" overrides everything built.
+"""
+
+
+def drivers() -> list:
+    """Installed SQL Server ODBC drivers, best (newest) first."""
+    import pyodbc
+    ds = [d for d in pyodbc.drivers() if 'SQL Server' in d]
+    return sorted(ds, key=lambda d: ('ODBC Driver' in d, d), reverse=True)
+
+
+def conn_str(cfg: dict) -> str:
+    if cfg.get('conn_str'): return cfg['conn_str']
+    drv = cfg.get('driver') or (drivers() or ['ODBC Driver 17 for SQL Server'])[0]
+    parts = [f'DRIVER={{{drv}}}', f"SERVER={cfg.get('server') or 'localhost'}"]
+    if cfg.get('database'): parts.append(f"DATABASE={cfg['database']}")
+    if (cfg.get('auth') or 'windows') == 'windows': parts.append('Trusted_Connection=yes')
+    else: parts += [f"UID={cfg.get('username', '')}", f"PWD={cfg.get('password', '')}"]
+    parts.append('TrustServerCertificate=yes')
+    return ';'.join(parts)
+
+
+def _connect(cs: str):
+    import pyodbc
+    return pyodbc.connect(cs, timeout=int(10))
+
+
+def run_query(cfg: dict, limit: int = None) -> list:
+    """Execute cfg['query'], return up to `limit` rows as dicts (cfg['max_rows'] wins)."""
+    from .reports import row_limit
+    limit = limit or row_limit(cfg)[0]
+    with _connect(conn_str(cfg)) as cx:
+        cur = cx.cursor().execute(cfg['query'])
+        cols = [c[0] for c in cur.description or []]
+        return [dict(zip(cols, r)) for r in cur.fetchmany(limit)]
+
+
+def test(cfg: dict) -> dict:
+    """Connect and report server version + current db; never raises - errors come back as data."""
+    try:
+        with _connect(conn_str(cfg)) as cx:
+            ver, db = cx.cursor().execute('SELECT @@VERSION, DB_NAME()').fetchone()
+        return {'ok': True, 'version': str(ver).split('\n')[0][:200], 'database': db}
+    except Exception as e:
+        return {'ok': False, 'error': str(e)[:500]}
+
+
+def run_report(cfg: dict):
+    """Report executor: (headline, summary) for the timeline. One row past the limit is
+    fetched so the headline can admit when the result was cut (see reports.rows_out)."""
+    from .reports import row_limit, rows_out
+    lim, mine = row_limit(cfg)
+    if cfg.get('dsn'):  # back-compat: sqlalchemy-style dsn from old configs
+        import sqlalchemy
+        with sqlalchemy.create_engine(cfg['dsn']).connect() as cx:
+            rows = [dict(r._mapping) for r in cx.execute(sqlalchemy.text(cfg['query'])).fetchmany(lim + 1)]
+    else:
+        rows = run_query(cfg, lim + 1)
+    return rows_out(rows, lim, mine=mine)