wraithd 0.0.1__py3-none-any.whl

wraithd/channels/telegram.py

@@ -0,0 +1,238 @@
+"""
+Telegram, by long polling over httpx: no public URL, no webhook, no extra library.
+
+- Pairing: `wraithd telegram pair` (or the web UI) makes a 6-digit code; the owner sends `/pair <code>` to the
+  bot within 10 minutes, and that chat becomes the owner's. Five wrong tries and the code is gone.
+- The owner's messages are runs like the terminal's (memory, files, apps), and writes ask with inline buttons,
+  decided through the same approval store as everywhere else.
+- The bot is personal: anyone else's message gets no run, no model call and no reply, except `/pair <code>` (the
+  owner's first contact comes from a chat that isn't paired yet). Each such chat is logged as a telegram_ignored
+  event, at most once an hour, so the owner can see someone tried without strangers filling the log.
+- Attachments from the owner: a photo goes to the model as image input with its caption (saved to the workspace
+  instead when the model can't see images), a voice note is transcribed (voice.py) and the transcript is the
+  message, and any other file is saved to workspace/files/inbox/ with a line in the message saying where. A
+  stranger's attachment is never downloaded. Downloads are capped (Telegram lets bots download 20 MB at most).
+- The bot token is in the keychain (`wraithd key set telegram`) and registered for redaction; errors never
+  include the API URL, since the token is in it.
+"""
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+
+import httpx
+
+from wraithd import providers, voice  # noqa: F401 (used by channels/base.py; tests patch them through here)
+from wraithd.channels import base
+from wraithd.core import events as ev
+from wraithd.tools.notify import StoreNotifier
+
+logger = logging.getLogger(__name__)
+
+API = 'https://api.telegram.org'
+POLL_SECONDS = 30
+MESSAGE_CHARS = 4000  # Telegram's limit is 4096
+MAX_FILE_BYTES = 20_000_000  # the Bot API's own limit for downloads
+MAX_PHOTO_BYTES = base.MAX_PHOTO_BYTES
+FILE_KINDS = {'document': 'file', 'audio': 'audio', 'video': 'video.mp4', 'video_note': 'video-note.mp4',
+              'animation': 'animation.mp4'}  # saved to the inbox; the value is the name when Telegram gives none
+OWNER_CHAT, OWNER_NAME, PAIRING, OFFSET = 'telegram.owner_chat', 'telegram.owner_name', 'telegram.pairing', \
+    'telegram.offset'
+
+
+class TelegramError(base.ChannelError):
+    """A Bot API call failed. The message never includes the URL (it has the token in it)."""
+
+
+class FileTooLarge(TelegramError, base.FileTooLarge):
+    """A download is over its cap."""
+
+
+def new_pairing(store, now: datetime | None = None) -> dict:
+    """A fresh pairing code, replacing any earlier one."""
+    return base.new_pairing(store, 'telegram', now)
+
+
+def _chunks(text: str) -> list[str]:
+    text = text or '(no answer)'
+    return [text[i:i + MESSAGE_CHARS] for i in range(0, len(text), MESSAGE_CHARS)]
+
+
+class TelegramBot:
+    """The Bot API calls the channel needs."""
+
+    def __init__(self, token: str, transport: httpx.AsyncBaseTransport | None = None):
+        self._client = httpx.AsyncClient(base_url=f'{API}/bot{token}/', transport=transport,
+                                         timeout=POLL_SECONDS + 10)
+        self._files = f'{API}/file/bot{token}/'  # has the token in it too: never logged or shown
+
+    async def call(self, method: str, **params) -> dict | list:
+        try:
+            response = await self._client.post(method, json=params)
+            data = response.json()
+        except (httpx.HTTPError, ValueError) as e:
+            raise TelegramError(f'Telegram {method} failed ({type(e).__name__}).') from None
+        if not data.get('ok'):
+            raise TelegramError(f'Telegram {method} failed: {data.get("description", "unknown error")}')
+        return data['result']
+
+    async def download(self, file_id: str, limit: int) -> bytes:
+        """A file someone sent, through getFile, read up to limit bytes (FileTooLarge past it)."""
+        info = await self.call('getFile', file_id=file_id)
+        if (info.get('file_size') or 0) > limit:
+            raise FileTooLarge('The file is too large.')
+        if not info.get('file_path'):
+            raise TelegramError('Telegram getFile gave no file path.')
+        data = bytearray()
+        try:
+            async with self._client.stream('GET', self._files + info['file_path']) as response:
+                response.raise_for_status()
+                async for chunk in response.aiter_bytes():
+                    data += chunk
+                    if len(data) > limit:
+                        raise FileTooLarge('The file is too large.')
+        except httpx.HTTPError as e:
+            raise TelegramError(f'Telegram file download failed ({type(e).__name__}).') from None
+        return bytes(data)
+
+    async def send(self, chat_id, text: str, buttons=None) -> int | None:
+        message_id = None
+        for part in _chunks(text):
+            params = {'chat_id': chat_id, 'text': part}
+            if buttons:
+                params['reply_markup'] = {'inline_keyboard': buttons}
+            message_id = (await self.call('sendMessage', **params))['message_id']
+        return message_id
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+class TelegramChannel(base.Channel):
+    """The channel interface (channels/base.py) over the Bot API: updates in, messages and inline buttons out."""
+
+    name, title, ignored_event = 'telegram', 'Telegram', ev.TELEGRAM_IGNORED
+    # read when used, so the module's limits can be changed (tests do)
+    max_file_bytes = property(lambda self: MAX_FILE_BYTES)
+    max_photo_bytes = property(lambda self: MAX_PHOTO_BYTES)
+
+    def __init__(self, rt, bot: TelegramBot, mcp=None, clock=lambda: datetime.now(UTC)):
+        super().__init__(rt, mcp=mcp, clock=clock)
+        self.bot = bot
+
+    def chat_from_setting(self, value: str) -> int:
+        return int(value)
+
+    # --- the transport -------------------------------------------------------------------------------------
+
+    async def send(self, chat, text: str, choices: list[base.Choice] | None = None) -> tuple[int, int | None]:
+        buttons = [[{'text': c.label, 'callback_data': c.data} for c in choices]] if choices else None
+        return chat, await self.bot.send(chat, text, buttons)
+
+    async def fetch(self, attachment: base.Attachment, limit: int) -> bytes:
+        return await self.bot.download(attachment.ref, limit)
+
+    async def acknowledge(self, decision: base.Decision, text: str) -> None:
+        await self.bot.call('answerCallbackQuery', callback_query_id=decision.ref, text=text)
+
+    async def close_prompt(self, where: tuple[int, int | None], status: str) -> None:
+        await self.bot.call('editMessageReplyMarkup', chat_id=where[0], message_id=where[1],
+                            reply_markup={'inline_keyboard': [[{'text': status.capitalize(),
+                                                                'callback_data': 'done'}]]})
+
+    # --- polling -------------------------------------------------------------------------------------------
+
+    async def poll_once(self, timeout: int = POLL_SECONDS) -> int:
+        """One getUpdates call; each update is handled (messages in their own task). Returns how many arrived."""
+        offset = int(self.rt.store.get_setting(OFFSET) or 0)
+        updates = await self.bot.call('getUpdates', offset=offset, timeout=timeout,
+                                      allowed_updates=['message', 'callback_query'])
+        for update in updates:
+            # Move past it first: an update that crashes the handler must not come back forever
+            self.rt.store.set_setting(OFFSET, str(update['update_id'] + 1))
+            try:
+                await self.handle(update)
+            except Exception:
+                logger.exception('Telegram update failed')
+        return len(updates)
+
+    async def poll_for_pairing(self, timeout: int = 5) -> bool:
+        """
+        For `wraithd onboard` when no daemon is polling: one getUpdates call that handles only `/pair` and stops
+        at the first pairing that works. Updates after it are left for the daemon, so the owner's first message
+        isn't lost; other messages before it (from chats that aren't the owner's yet) are passed over.
+        """
+        offset = int(self.rt.store.get_setting(OFFSET) or 0)
+        updates = await self.bot.call('getUpdates', offset=offset, timeout=timeout, allowed_updates=['message'])
+        for update in updates:
+            self.rt.store.set_setting(OFFSET, str(update['update_id'] + 1))
+            message = update.get('message') or {}
+            text, chat = (message.get('text') or '').strip(), message.get('chat') or {}
+            if 'id' in chat and text.startswith('/pair'):
+                await self.pair(chat['id'], chat, text.removeprefix('/pair').strip())
+                if self.owner_chat is not None:
+                    return True
+        return self.owner_chat is not None
+
+    async def run_forever(self) -> None:
+        while True:
+            try:
+                await self.poll_once()
+            except TelegramError as e:
+                logger.warning(str(e))
+                await asyncio.sleep(5)
+
+    # --- updates -------------------------------------------------------------------------------------------
+
+    async def handle(self, update: dict) -> None:
+        if 'callback_query' in update:
+            query = update['callback_query']
+            chat = ((query.get('message') or {}).get('chat') or {})
+            return await self.decide(base.Decision(chat=chat.get('id'), data=query.get('data') or '',
+                                                   ref=query['id'], who=query.get('from') or chat))
+        message = update.get('message') or {}
+        chat = message.get('chat') or {}
+        if 'id' not in chat:
+            return
+        await self.receive(base.Incoming(chat=chat['id'], who=chat, text=message.get('text') or '',
+                                         caption=message.get('caption') or '', attachment=_attachment(message)))
+
+
+def _attachment(message: dict) -> base.Attachment | None:
+    """The message's photo (the largest size that fits the cap), voice note or file, as the channel sees it."""
+    if message.get('photo'):
+        sizes = message['photo']
+        fitting = [size for size in sizes if (size.get('file_size') or 0) <= MAX_PHOTO_BYTES]
+        best = max(fitting, key=lambda size: (size.get('width', 0) * size.get('height', 0),
+                                              size.get('file_size', 0))) if fitting else \
+            min(sizes, key=lambda size: size.get('file_size') or 0)  # none fits: too large, said without a download
+        return base.Attachment('photo', best['file_id'], best.get('file_size'), mime='image/jpeg')  # always JPEG
+    if message.get('voice'):
+        note = message['voice']
+        return base.Attachment('voice', note['file_id'], note.get('file_size'), mime=note.get('mime_type') or '')
+    kind = next((kind for kind in FILE_KINDS if message.get(kind)), None)
+    if kind:
+        item = message[kind]
+        return base.Attachment('file', item['file_id'], item.get('file_size'),
+                               name=item.get('file_name') or FILE_KINDS[kind], mime=item.get('mime_type') or '')
+    return None
+
+
+class TelegramNotifier:
+    """notify_owner through Telegram when there's a paired owner chat; otherwise into the store's inbox."""
+
+    channel = 'telegram'
+
+    def __init__(self, store, bot: TelegramBot):
+        self.store, self.bot, self.inbox = store, bot, StoreNotifier(store)
+
+    async def deliver(self, text: str) -> str:
+        owner = self.store.get_setting(OWNER_CHAT)
+        if not owner:
+            return await self.inbox.deliver(text)
+        try:
+            await self.bot.send(int(owner), text)
+            return self.channel
+        except TelegramError as e:
+            logger.warning(f'{e}; kept in the inbox instead')
+            return await self.inbox.deliver(text)

wraithd/channels/terminal.py

@@ -0,0 +1,111 @@
+"""
+Chat in the terminal: the owner types, the answer streams back, and write actions ask y/N first.
+
+One session is one conversation. Its messages are stored, so long sessions are compacted, and when the session
+ends, distill turns it into memory: that's how "I prefer short replies" holds the next time.
+"""
+
+import asyncio
+import getpass
+import json
+import sys
+
+from wraithd.core import compaction
+from wraithd.mcp.client import McpConnections
+from wraithd.memory import distill
+from wraithd.run import Runtime, run
+from wraithd.store import base as store_base
+
+QUIT = {'/quit', '/exit', 'quit', 'exit', ':q'}
+DISTILL_MIN_MESSAGES = 2  # at the end of a session, one exchange is enough to learn from
+
+
+class Terminal:
+    """Reading and writing, so tests can play the owner."""
+
+    async def ask(self, prompt: str) -> str | None:
+        """A line from the owner, or None when input ends (Ctrl-D)."""
+        try:
+            return await asyncio.to_thread(input, prompt)
+        except EOFError:
+            return None
+
+    async def secret(self, prompt: str) -> str | None:
+        """A line typed without echo (keys, tokens), or None when input ends."""
+        try:
+            return await asyncio.to_thread(getpass.getpass, prompt)
+        except EOFError:
+            return None
+
+    def say(self, text: str = '', end: str = '\n') -> None:
+        sys.stdout.write(text + end)
+        sys.stdout.flush()
+
+
+def _approval_card(data: dict) -> str:
+    lines = [f'\nThe agent wants to run {data["tool"]}:']
+    lines += [f'  {key}: {json.dumps(value) if not isinstance(value, str) else value}'
+              for key, value in data['arguments'].items()]
+    if data.get('reason'):
+        lines.append(f'  {data["reason"]}')
+    for recipient in data.get('suspicious_recipients') or []:
+        lines.append(f'  ! {recipient["value"]} was not written by you (it came from {recipient["source"]})')
+    if data.get('untrusted_sources') and not data.get('suspicious_recipients'):
+        lines.append(f'  ! This run read third-party content first: {", ".join(data["untrusted_sources"])}')
+    return '\n'.join(lines)
+
+
+def make_callback(rt: Runtime, terminal: Terminal, state: dict):
+    """Streams text as it's written, shows tool calls, and turns approval cards into a y/N question."""
+
+    async def callback(event_type: str, data: dict) -> None:
+        if event_type == 'content_delta':
+            state['streamed'] = True
+            terminal.say(data['content'], end='')
+        elif event_type == 'tool_call_start':
+            terminal.say(f'  · {data["tool"]}')
+        elif event_type == 'approval_required':
+            terminal.say(_approval_card(data))
+            answer = (await terminal.ask('Allow? [y/N] ') or '').strip().lower()
+            decision = store_base.APPROVED if answer in ('y', 'yes') else store_base.DENIED
+            rt.store.decide_approval(data['approval_id'], decision)
+
+    return callback
+
+
+async def chat(rt: Runtime, terminal: Terminal | None = None) -> str:
+    """One session. Returns the conversation id."""
+    terminal = terminal or Terminal()
+    async with McpConnections(rt.config.mcp_servers, store=rt.store) as mcp:  # once per session, not once per message
+        for name, problem in mcp.errors.items():
+            terminal.say(f'(MCP server {name} is not available this session: {problem})')
+        return await _session(rt, terminal, mcp)
+
+
+async def _session(rt: Runtime, terminal: Terminal, mcp) -> str:
+    conversation = rt.store.start_conversation('terminal')
+    terminal.say('wraithd. Type /quit to end; what you share is remembered for next time.')
+    try:
+        while True:
+            message = await terminal.ask('\n> ')
+            if message is None or message.strip().lower() in QUIT:
+                break
+            if not message.strip():
+                continue
+            rt.store.add_message(conversation.id, 'user', message)
+            history = await compaction.history_for(rt.store, conversation.id, rt.completer('compaction'))
+            state = {'streamed': False}
+            result = await run(rt, message, history=history, callback=make_callback(rt, terminal, state),
+                               source='chat', mcp=mcp)
+            # A streamed answer is already on screen; a refusal or failure message never streamed
+            terminal.say('' if state['streamed'] else result.answer)
+            rt.store.add_message(conversation.id, 'assistant', result.answer, run_id=result.run_id)
+    finally:
+        try:
+            outcome = await distill.distill_conversation(rt.store, rt.memory, rt.completer('distill'),
+                                                         conversation.id, min_messages=DISTILL_MIN_MESSAGES)
+            if outcome.get('notes'):
+                terminal.say(f'Remembered: {", ".join(outcome["notes"])}')
+        except Exception as e:
+            terminal.say(f'(Could not save what I learned this time: {type(e).__name__})')
+    return conversation.id

wraithd/cli.py

@@ -0,0 +1,319 @@
+"""
+The `wraithd` command.
+
+    wraithd onboard                  set everything up, one question at a time (safe to run again)
+    wraithd chat                     talk to the agent in the terminal
+    wraithd runs list                the latest runs
+    wraithd runs show <id> [--json]  one run's timeline (a unique prefix of the id is enough)
+    wraithd events [--type T]        what happened between runs: compaction, distill, ignored Telegram chats
+    wraithd schedules list [--all]   schedules and reminders, with their next times
+    wraithd schedules rm <id>        cancel one
+    wraithd mcp add|list|tools|allow|disallow|remove   your apps, as MCP servers (see mcp/commands.py)
+    wraithd daemon                   the API, web UI, scheduler and Telegram, in the foreground
+    wraithd daemon install|start|stop|restart|status|logs|uninstall   the same, as a background service
+    wraithd doctor                   check the setup; a fix for anything wrong
+    wraithd audit                    check the live setup against the security rules
+    wraithd update                   upgrade (with uv or pipx) and restart the service
+    wraithd telegram pair            a code that makes your Telegram chat the owner's
+    wraithd key set <provider>       store an API key in the OS keychain
+    wraithd key rm <provider>        delete it from the keychain
+"""
+
+import argparse
+import asyncio
+import getpass
+import json
+import logging
+import sys
+
+from wraithd import __version__
+from wraithd.config import KEY_NAMES, ConfigError, Home, NoKeychain, delete_key, set_key
+from wraithd.core import events as ev
+from wraithd.core import inspector
+from wraithd.daemon import commands as daemon_commands
+from wraithd.mcp import commands as mcp_commands
+from wraithd.providers import ProviderError
+from wraithd.store import SQLiteStore
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='wraithd',
+        description='A personal agent that runs on your own machine.',
+    )
+    parser.add_argument('--version', action='version', version=f'wraithd {__version__}')
+    commands = parser.add_subparsers(dest='command')
+
+    commands.add_parser('onboard', help='set up the model, keys, Telegram and the background service')
+    commands.add_parser('chat', help='talk to the agent in the terminal')
+
+    runs = commands.add_parser('runs', help='look at what runs did').add_subparsers(dest='runs_command',
+                                                                                   required=True)
+    listing = runs.add_parser('list', help='the latest runs')
+    listing.add_argument('--limit', type=int, default=20)
+    show = runs.add_parser('show', help="one run's timeline")
+    show.add_argument('run_id', help='the run id, or a unique prefix of it')
+    show.add_argument('--json', action='store_true', help='the summary and every event, as JSON')
+
+    events = commands.add_parser('events', help='what happened between runs: compaction, distill, ignored chats')
+    events.add_argument('--limit', type=int, default=20)
+    events.add_argument('--type', choices=ev.BETWEEN_RUNS, action='append', help='only this type (repeatable)')
+
+    schedules = commands.add_parser('schedules', help='schedules and reminders').add_subparsers(
+        dest='schedules_command', required=True)
+    schedules_list = schedules.add_parser('list', help='active schedules (--all: cancelled and finished too)')
+    schedules_list.add_argument('--all', action='store_true')
+    schedules_rm = schedules.add_parser('rm', help='cancel a schedule')
+    schedules_rm.add_argument('schedule_id', type=int)
+
+    mcp_commands.add_arguments(commands)
+    daemon_commands.add_arguments(commands)
+    commands.add_parser('doctor', help='check the setup: settings, keys, permissions, the service, the daemon')
+    commands.add_parser('audit', help='check the setup against the security rules: the API, the token, the shell, '
+                                      'file permissions')
+    commands.add_parser('update', help='upgrade wraithd (uv or pipx) and restart the background service')
+    telegram = commands.add_parser('telegram', help='the Telegram channel').add_subparsers(
+        dest='telegram_command', required=True)
+    telegram.add_parser('pair', help='a code to send to your bot as /pair <code> (valid for 10 minutes)')
+
+    key = commands.add_parser('key', help='API keys, kept in the OS keychain').add_subparsers(dest='key_command',
+                                                                                           required=True)
+    key_set = key.add_parser('set', help='store a key (asked for without echo)')
+    key_set.add_argument('provider', choices=KEY_NAMES)
+    key_rm = key.add_parser('rm', help='delete a key from the keychain')
+    key_rm.add_argument('provider', choices=KEY_NAMES)
+    # New commands: each worker adds its subparser to `commands` inside its own block only
+    # >>> security
+    from wraithd.review import cli as review_cli
+
+    review_cli.add_arguments(commands)
+    # <<< security
+    # >>> efficiency
+    tokens = runs.add_parser('tokens', help="where one run's input tokens went, part by part")
+    tokens.add_argument('run_id', help='the run id, or a unique prefix of it')
+    tokens.add_argument('--json', action='store_true')
+    tokens.set_defaults(command='runs_tokens')  # handled in main's efficiency block
+    # <<< efficiency
+    # >>> capabilities
+    from wraithd.daemon import heartbeat
+
+    heartbeat.add_arguments(commands)
+    # <<< capabilities
+    # >>> reach
+    # <<< reach
+    # >>> evals
+    # <<< evals
+    # >>> sandbox
+    # <<< sandbox
+    return parser
+
+
+def _store(home: Home) -> SQLiteStore | None:
+    return SQLiteStore(home.db_path) if home.db_path.exists() else None
+
+
+def runs_list(home: Home, limit: int) -> int:
+    store = _store(home)
+    runs = store.recent_runs(limit) if store else []
+    if not runs:
+        print('No runs yet.')
+        return 0
+    for info in runs:
+        message = info.message if len(info.message) <= 60 else info.message[:57] + '...'
+        print(f'{info.run_id[:8]}  {info.started_at.astimezone():%Y-%m-%d %H:%M}  {info.source:<9} {message}')
+    return 0
+
+
+def runs_show(home: Home, prefix: str, as_json: bool) -> int:
+    store = _store(home)
+    matches = store.find_runs(prefix) if store and prefix else []
+    if len(matches) != 1:
+        print(f'No run matches {prefix!r}.' if not matches else
+              f'{len(matches)} runs start with {prefix!r}; give more of the id.', file=sys.stderr)
+        return 1
+    events = store.run_events(matches[0])
+    if as_json:
+        print(json.dumps({'run_id': matches[0], 'summary': inspector.summarize(events),
+                          'events': inspector.timeline(events)}, indent=1, default=str))
+    else:
+        print(inspector.render_text(matches[0], events, children=store.run_events))  # subagents nested
+    return 0
+
+
+def events_list(home: Home, limit: int, types) -> int:
+    store = _store(home)
+    listed = store.events_between_runs(limit, types or ()) if store else []
+    if not listed:
+        print('Nothing has happened between runs yet.')
+        return 0
+    for event in listed:
+        print(f'{event.created_at.astimezone():%Y-%m-%d %H:%M}  {event.type:<16} {inspector.between_runs_text(event)}')
+    return 0
+
+
+def schedules_list(home: Home, show_all: bool) -> int:
+    from wraithd.schedules import describe
+
+    store = _store(home)
+    listed = store.list_schedules(active_only=not show_all) if store else []
+    if not listed:
+        print('No schedules.')
+        return 0
+    for schedule in listed:
+        state = '' if schedule.active else '  [off]'
+        print(f'{schedule.id:>4}  {describe(schedule)}{state}\n      {schedule.message}')
+    return 0
+
+
+def schedules_rm(home: Home, schedule_id: int) -> int:
+    store = _store(home)
+    if not store or not store.cancel_schedule(schedule_id):
+        print(f'No active schedule {schedule_id}.', file=sys.stderr)
+        return 1
+    print(f'Cancelled schedule {schedule_id}.')
+    return 0
+
+
+def daemon(home: Home) -> int:
+    from wraithd.daemon.app import Daemon
+    from wraithd.run import Runtime
+
+    # Timestamps for the service's log file. WARNING and up only: httpx logs every request URL at INFO, and the
+    # Telegram ones have the bot token in them
+    logging.basicConfig(level=logging.WARNING, format='%(asctime)s %(levelname)s %(name)s: %(message)s')
+    try:
+        rt = Runtime.open(home)
+    except (ConfigError, ProviderError) as e:
+        print(e, file=sys.stderr)
+        return 1
+    try:
+        asyncio.run(Daemon(rt).serve())
+    except KeyboardInterrupt:
+        pass
+    finally:
+        rt.close()
+    return 0
+
+
+def telegram_pair(home: Home) -> int:
+    from wraithd.channels.telegram import new_pairing
+
+    home.ensure()
+    store = SQLiteStore(home.db_path)
+    try:
+        pairing = new_pairing(store)
+    finally:
+        store.close()
+    print(f'Send this to your bot within 10 minutes:  /pair {pairing["code"]}')
+    return 0
+
+
+def key_set(provider: str) -> int:
+    value = getpass.getpass(f'{provider} API key (not shown): ').strip()
+    if not value:
+        print('Nothing saved.', file=sys.stderr)
+        return 1
+    try:
+        set_key(provider, value)
+    except NoKeychain as e:
+        print(e, file=sys.stderr)
+        return 1
+    print(f'Saved the {provider} key in the keychain.')
+    return 0
+
+
+def key_rm(provider: str) -> int:
+    if not delete_key(provider):
+        print(f'No {provider} key in the keychain.')
+        return 0
+    print(f'Deleted the {provider} key from the keychain.')
+    return 0
+
+
+def chat(home: Home) -> int:
+    from wraithd.channels.terminal import chat as chat_session
+    from wraithd.run import Runtime
+
+    try:
+        rt = Runtime.open(home)
+    except (ConfigError, ProviderError) as e:
+        print(e, file=sys.stderr)
+        return 1
+    try:
+        asyncio.run(chat_session(rt))
+    except KeyboardInterrupt:
+        pass
+    finally:
+        rt.close()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    argv, server_command = mcp_commands.split_command(sys.argv[1:] if argv is None else list(argv))
+    args = parser.parse_args(argv)
+    if server_command:
+        args.server_command = server_command
+    home = Home.locate()
+    if args.command == 'onboard':
+        from wraithd import onboard
+        return onboard.main(home)
+    if args.command == 'doctor':
+        from wraithd import doctor
+        return doctor.main(home)
+    if args.command == 'audit':
+        from wraithd import audit
+        return audit.main(home)
+    if args.command == 'update':
+        from wraithd import update
+        return update.update(home)
+    if args.command == 'chat':
+        return chat(home)
+    if args.command == 'runs':
+        if args.runs_command == 'list':
+            return runs_list(home, args.limit)
+        return runs_show(home, args.run_id, args.json)
+    if args.command == 'events':
+        return events_list(home, args.limit, args.type)
+    if args.command == 'schedules':
+        if args.schedules_command == 'list':
+            return schedules_list(home, args.all)
+        return schedules_rm(home, args.schedule_id)
+    if args.command == 'daemon':
+        return daemon(home) if args.daemon_command is None else daemon_commands.main(home, args)
+    if args.command == 'telegram':
+        return telegram_pair(home)
+    if args.command == 'mcp':
+        return mcp_commands.main(home, args)
+    if args.command == 'key':
+        return key_set(args.provider) if args.key_command == 'set' else key_rm(args.provider)
+    # New commands: each worker dispatches its own inside its block only
+    # >>> security
+    if args.command == 'review':
+        from wraithd.review import cli as review_cli
+
+        return review_cli.main(home, args)
+    # <<< security
+    # >>> efficiency
+    if args.command == 'runs_tokens':
+        from wraithd.core import tokens
+        return tokens.main(home, args.run_id, args.json)
+    # <<< efficiency
+    # >>> capabilities
+    if args.command == 'heartbeat':
+        from wraithd.daemon import heartbeat
+
+        return heartbeat.main(home, args)
+    # <<< capabilities
+    # >>> reach
+    # <<< reach
+    # >>> evals
+    # <<< evals
+    # >>> sandbox
+    # <<< sandbox
+    parser.print_help()
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())