wraithd 0.0.1__py3-none-any.whl

wraithd/__init__.py

@@ -0,0 +1,5 @@
+"""wraithd: a personal agent that runs on your own machine."""
+
+from importlib.metadata import version
+
+__version__ = version('wraithd')

wraithd/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m wraithd`: the same as the `wraithd` command (the background service runs it this way)."""
+
+from wraithd.cli import main
+
+raise SystemExit(main())

wraithd/audit.py

@@ -0,0 +1,251 @@
+"""
+`wraithd audit`: the live setup checked against the security rules (docs/ec2-to-laptop.md). One line per rule,
+pass or FAIL with a fix, and a few info lines for standing permissions worth knowing about. Exit code 1 on a FAIL.
+
+Like doctor it only reads (the config, file modes, the store) and never changes anything. doctor runs it too and
+reports one line for all of it.
+"""
+
+import contextlib
+import ipaddress
+import os
+import stat
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from wraithd.config import ConfigError, Home, load_config
+from wraithd.core import gate
+from wraithd.core.secrets import redact
+from wraithd.daemon import app as daemon_app
+from wraithd.daemon.security import TOKEN_FILE
+from wraithd.doctor import FAIL, INFO, OK, Check, render
+
+MIN_TOKEN_LENGTH = 32
+MAX_LISTED = 3  # offending paths named per rule
+DB_FILES = ('', '-wal', '-shm')  # state.db and SQLite's side files: the event log, the review queue, the pins
+TAILNET = '.ts.net'
+
+
+def _shown(home: Home, paths: list[Path]) -> str:
+    names = [str(path.relative_to(home.root)) for path in paths[:MAX_LISTED]]
+    return ', '.join(names) + (f' and {len(paths) - MAX_LISTED} more' if len(paths) > MAX_LISTED else '')
+
+
+def _loose(home: Home) -> tuple[list[Path], list[Path]]:
+    """Paths inside the state folder that others can write to, and paths another account owns. Symlinks aren't
+    followed: what they point to isn't the folder's."""
+    writable, foreign = [], []
+    uid = os.getuid()
+    for folder, folders, files in os.walk(home.root):
+        for name in folders + files:
+            path = Path(folder) / name
+            info = path.lstat()
+            if stat.S_ISLNK(info.st_mode):
+                continue
+            if info.st_mode & 0o022:
+                writable.append(path)
+            if info.st_uid != uid:
+                foreign.append(path)
+    return writable, foreign
+
+
+def _local_origin(origin: str) -> bool:
+    """http on localhost or 127.0.0.1 with a real port, and nothing else (config only checks the prefix)."""
+    parts = urlsplit(origin)
+    try:
+        port = parts.port
+    except ValueError:
+        return False
+    return (parts.scheme == 'http' and parts.hostname in ('localhost', '127.0.0.1') and port is not None
+            and not parts.path.strip('/') and not parts.username)
+
+
+def checks(home: Home) -> list[Check]:
+    found = []
+
+    def add(state: str, text: str, fix: str = '') -> None:
+        found.append(Check(state, text, fix))
+
+    # --- the state folder: memory, the event log, the token, the config -------------------------------------
+    if not home.root.is_dir():
+        add(FAIL, f'No state folder at {home.root}', 'wraithd onboard')
+        return found
+    info = home.root.stat()
+    mode = stat.S_IMODE(info.st_mode)
+    add(OK if mode & 0o077 == 0 and info.st_uid == os.getuid() else FAIL,
+        f'{home.root} is yours alone (mode {mode:o})', f'chmod 700 {home.root}')
+    writable, foreign = _loose(home)
+    add(OK if not writable else FAIL,
+        'Nothing in it is writable by other accounts' if not writable else f'Writable by other accounts: '
+        f'{_shown(home, writable)}', f'chmod -R go-w {home.root}')
+    add(OK if not foreign else FAIL,
+        'Everything in it belongs to you' if not foreign else f'Owned by another account: {_shown(home, foreign)}',
+        f'chown -R {os.getuid()} {home.root}')
+
+    # --- the local API ----------------------------------------------------------------------------------------
+    loopback = ipaddress.ip_address(daemon_app.HOST).is_loopback
+    add(OK if loopback else FAIL, f'The API binds to {daemon_app.HOST} only' if loopback else
+        f'The API binds to {daemon_app.HOST}, which other machines can reach', 'reinstall wraithd')
+    token = home.root / TOKEN_FILE
+    if token.exists():
+        mode = stat.S_IMODE(token.stat().st_mode)
+        strong = len(token.read_text().strip()) >= MIN_TOKEN_LENGTH
+        add(OK if mode & 0o077 == 0 and strong else FAIL,
+            f'API token is set and private (mode {mode:o})' if strong else 'API token is too short',
+            f'chmod 600 {token}' if strong else f'rm {token} and restart the daemon (it makes a new one)')
+    else:
+        add(OK, 'API token: not made yet (the daemon makes one, mode 600, before it serves anything)')
+
+    try:
+        config = load_config(home)
+    except ConfigError as e:
+        add(FAIL, f'Settings don\'t load, so the rules below can\'t be checked: {e}', f'edit {home.config_path}')
+        return found
+
+    if not config.dev_origin:
+        add(OK, 'Only the daemon\'s own origin may call the API')
+    elif _local_origin(config.dev_origin):
+        add(INFO, f'One more origin may call the API (with the token): {config.dev_origin}')
+    else:
+        add(FAIL, f'dev_origin {config.dev_origin} isn\'t on this machine: that site\'s pages may call the API',
+            f'remove dev_origin from [daemon] in {home.config_path}')
+
+    # --- the shell --------------------------------------------------------------------------------------------
+    gated = gate.classify_tool('shell_run') == gate.ToolAccess.WRITE and 'shell_run' in gate.NEVER_UNATTENDED
+    if not config.shell_enabled:
+        add(OK, 'Shell: off')
+    else:
+        add(OK if gated else FAIL, 'Shell: on, every command asks first and never runs unattended' if gated else
+            'Shell: on, and not every command asks first', f'set shell_enabled = false in {home.config_path}')
+
+    # --- keys -------------------------------------------------------------------------------------------------
+    _, kinds = redact(home.config_path.read_text()) if home.config_path.exists() else ('', [])
+    add(OK if not kinds else FAIL, 'No keys in config.toml (they belong in the keychain)' if not kinds else
+        f'config.toml holds what looks like a key ({", ".join(kinds)})',
+        f'remove it from {home.config_path}; keep it with wraithd key set <provider> or mcp add --env')
+
+    # --- reach: what the agent can open on its own (docs/lockdown.md) -------------------------------------------
+    from wraithd.tools import choose_search
+
+    browser = config.section('browser')['enabled']
+    add(INFO, f'Web: search {choose_search(config).backend or "off"}, page reading '
+              f'{"on" if config.web_read else "off"}, browser {"on" if browser else "off"}')
+    for server in config.mcp_servers:
+        add(INFO, f'MCP {server.name}: ' + (f'only {", ".join(server.tools)}' if server.tools else
+                                            'every tool it lists (no tools list)'))
+
+    # --- standing permissions: not problems, but the owner should know they exist -----------------------------
+    allowed = [f'{server.name} {tool}' for server in config.mcp_servers for tool in server.always_allow]
+    if allowed:
+        add(INFO, f'Always allowed (run without asking, but only to recipients you wrote): {", ".join(allowed)}. '
+                  'A tool the server marks destructive asks anyway.')
+    if home.db_path.exists():
+        from wraithd.store import SQLiteStore
+
+        store = SQLiteStore(home.db_path)
+        try:
+            active = len(store.list_schedules())
+        finally:
+            store.close()
+        if active:
+            add(INFO, f'{active} schedule{"s" if active > 1 else ""} run{"" if active > 1 else "s"} unattended: '
+                      'wraithd schedules list')
+    # New rules: each worker adds `found += its_rules(home, config)` (a list of Check) inside its block only
+    # >>> security
+    found += security_rules(home, config)
+    # <<< security
+    # >>> efficiency
+    # <<< efficiency
+    # >>> capabilities
+    # <<< capabilities
+    # >>> reach
+    # <<< reach
+    # >>> evals
+    # <<< evals
+    # >>> sandbox
+    from wraithd.sandbox.audit import sandbox_rules
+
+    found += sandbox_rules(home, config)
+    # <<< sandbox
+    return found
+
+
+def remote_hosts(config) -> list[str]:
+    """The [remote] allowed_hosts entries (reach's daemon.security.remote_hosts; none until it exists)."""
+    from wraithd.daemon import security
+
+    found = getattr(security, 'remote_hosts', None)
+    return list(found(config)) if found else []
+
+
+def _remote_host_problem(host: str) -> str:
+    """Why a remote host isn't a tailnet name, or '' if it is one."""
+    name = host.strip().lower().rstrip('.')
+    with contextlib.suppress(ValueError):
+        ipaddress.ip_address(name.strip('[]'))
+        return 'is an IP address'
+    if name in ('localhost', '127.0.0.1') or name.endswith('.localhost'):
+        return 'is this machine'
+    if not name.endswith(TAILNET) or name == TAILNET.lstrip('.'):
+        return f'isn\'t a tailnet name (*{TAILNET})'
+    return ''
+
+
+def security_rules(home: Home, config) -> list[Check]:
+    """The review queue's and the pins' storage, pinned MCP tools, remote access (docs/security.md)."""
+    found = []
+
+    def add(state: str, text: str, fix: str = '') -> None:
+        found.append(Check(state, text, fix))
+
+    # --- state.db holds the review queue (third-party text) and the pins: the owner's alone ----------------------
+    exposed = [Path(f'{home.db_path}{suffix}') for suffix in DB_FILES]
+    exposed = [path for path in exposed if path.exists() and stat.S_IMODE(path.stat().st_mode) & 0o077]
+    add(OK if not exposed else FAIL, 'The store (review queue, pins, event log) is readable by you alone' if not exposed
+        else f'Other accounts can open the store: {_shown(home, exposed)}',
+        f'chmod 600 {" ".join(str(path) for path in exposed)}')
+
+    # --- always-allowed MCP tools are pinned to what they were when allowed --------------------------------------
+    allowed = [(server.name, tool) for server in config.mcp_servers for tool in server.always_allow]
+    rows = {}
+    if home.db_path.exists():
+        from wraithd.mcp.pinning import Pins
+        from wraithd.review.queue import ReviewQueue
+        from wraithd.store import SQLiteStore
+
+        store = SQLiteStore(home.db_path)
+        try:
+            rows = {(row['server'], row['tool']): row for row in Pins(store).rows()}
+            pending = ReviewQueue(store).pending_count()
+        finally:
+            store.close()
+        if pending:
+            add(INFO, f'{pending} item{"s" if pending > 1 else ""} wait{"" if pending > 1 else "s"} for your review: '
+                      'wraithd review list')
+    unpinned = [f'{server} {tool}' for server, tool in allowed
+                if not (rows.get((server, tool)) or {}).get('allowed_hash')]
+    changed = [f'{server} {tool}' for server, tool in allowed
+               if (row := rows.get((server, tool))) and row['allowed_hash'] and row['allowed_hash'] != row['seen_hash']]
+    if allowed:
+        add(OK if not unpinned else FAIL, 'Always-allowed MCP tools are pinned to what you allowed' if not unpinned
+            else f'Always allowed but not pinned, so they ask (re-allow needed): {", ".join(unpinned)}',
+            'wraithd mcp allow <server> <tool> for each (it checks the tool and pins it)')
+        add(OK if not changed else FAIL, 'No always-allowed MCP tool changed since you allowed it' if not changed
+            else f'Changed since you allowed them, so they ask until you review: {", ".join(changed)}',
+            'wraithd review list')
+
+    # --- remote access: only through the tailnet, and still with the token -------------------------------------
+    for host in remote_hosts(config):
+        problem = _remote_host_problem(host)
+        if problem:
+            add(FAIL, f'Remote access host {host} {problem}: anyone who can reach it could reach the API',
+                'use your tailnet name from `tailscale status`')
+        else:
+            add(INFO, f'Reachable remotely at https://{host.strip().rstrip(".")} (token still required)')
+    return found
+
+
+def main(home: Home) -> int:
+    found = checks(home)
+    print(render(found))
+    return 1 if any(check.state == FAIL for check in found) else 0

wraithd/channels/__init__.py

@@ -0,0 +1 @@
+"""Where the owner talks to the agent. The terminal now; Telegram and the web UI with the daemon (Phase 5)."""

wraithd/channels/base.py

@@ -0,0 +1,318 @@
+"""
+What every phone channel shares, so the rules live in one place and a new channel only writes its transport:
+
+- Pairing: a 6-digit code (`wraithd <channel> pair`) the owner sends as `/pair <code>` within 10 minutes; that
+  chat becomes the owner's. Five wrong tries and the code is gone.
+- The owner's messages are runs; anyone else's get no run, no model call, no reply and no download, except
+  `/pair <code>`. Each such chat is logged as the channel's ignored event (chat and name, never the text), at most
+  once an hour per chat.
+- Attachments from the owner: a photo is image input (saved instead when the model can't see), a voice note is
+  transcribed (voice.py), any other file is saved to workspace/files/inbox/.
+- Approvals are a prompt with choices (buttons, or numbered replies on a channel without them); only the owner's
+  answer counts.
+
+A channel subclass turns its service's updates into Incoming and Decision, and implements send, fetch,
+acknowledge and close_prompt. Settings are stored under '<name>.<key>' (telegram.owner_chat ...).
+"""
+
+import asyncio
+import base64
+import json
+import logging
+import secrets
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+
+from wraithd import providers, voice
+from wraithd.channels.conversation import reply
+from wraithd.core import events as ev
+from wraithd.core.gate import approval_card
+from wraithd.store import base as store_base
+from wraithd.tools import files
+
+logger = logging.getLogger(__name__)
+
+PAIRING_MINUTES = 10
+PAIRING_TRIES = 5
+IGNORED_LOG_EVERY = timedelta(hours=1)  # per stranger chat
+MAX_FILE_BYTES = 20_000_000
+MAX_PHOTO_BYTES = 5_000_000  # what goes to the model as an image (Anthropic takes up to 5 MB)
+INBOX = 'inbox'  # in workspace/files/
+ALLOW, DENY = 'a', 'd'  # a choice's data is '<a|d>:<approval id>'
+
+
+class ChannelError(Exception):
+    """A call to the channel's service failed. The message never includes a token or a URL with one in it."""
+
+
+class FileTooLarge(ChannelError):
+    """A download is over its cap."""
+
+
+class Unusable(Exception):
+    """An attachment that won't reach a run. The message is the reply the owner gets."""
+
+
+@dataclass(frozen=True)
+class Attachment:
+    kind: str  # 'photo', 'voice' or 'file'
+    ref: str  # the channel's own id to fetch it with
+    size: int | None = None  # what the service declares, before downloading
+    name: str = ''  # a file's name, '' when the service gives none
+    mime: str = ''
+
+
+@dataclass(frozen=True)
+class Incoming:
+    """One message, as the channel's service gave it."""
+
+    chat: object  # the chat id, in the channel's own type
+    who: dict = field(default_factory=dict)  # username / first_name, for the log and the owner's name
+    text: str = ''  # the message text (commands live here)
+    caption: str = ''  # an attachment's caption
+    attachment: Attachment | None = None
+
+
+@dataclass(frozen=True)
+class Choice:
+    label: str
+    data: str
+
+
+@dataclass(frozen=True)
+class Decision:
+    """Someone picked a choice (a button tap, a numbered reply)."""
+
+    chat: object
+    data: str
+    ref: object = None  # what acknowledge() answers (a callback query id)
+    who: dict = field(default_factory=dict)
+
+
+def new_pairing(store, channel: str, now: datetime | None = None) -> dict:
+    """A fresh pairing code for the channel, replacing any earlier one."""
+    now = now or datetime.now(UTC)
+    pairing = {'code': f'{secrets.randbelow(1_000_000):06d}',
+               'expires_at': (now + timedelta(minutes=PAIRING_MINUTES)).isoformat(timespec='microseconds'),
+               'tries': 0}
+    store.set_setting(f'{channel}.pairing', json.dumps(pairing))
+    return pairing
+
+
+def approval_prompt(data: dict) -> tuple[str, list[Choice]]:
+    """The card for an approval_required callback: tool, arguments, why, third-party warnings; Allow and Deny."""
+    lines = [f'Allow {data["tool"]}?']
+    lines += [f'  {key}: {value if isinstance(value, str) else json.dumps(value)}'
+              for key, value in data['arguments'].items()]
+    if data['reason']:
+        lines.append(data['reason'])
+    lines += [f'! {r["value"]} was not written by you (it came from {r["source"]})'
+              for r in data['suspicious_recipients']]
+    if data['untrusted_sources'] and not data['suspicious_recipients']:
+        lines.append(f'! This run read third-party content first: {", ".join(data["untrusted_sources"])}')
+    return '\n'.join(lines), [Choice('Allow', f'{ALLOW}:{data["approval_id"]}'),
+                              Choice('Deny', f'{DENY}:{data["approval_id"]}')]
+
+
+class Channel:
+    name = ''  # settings prefix, conversation kind and run source
+    title = ''  # how replies name the service
+    ignored_event = ''  # the between-runs event for a stranger
+    max_file_bytes = MAX_FILE_BYTES
+    max_photo_bytes = MAX_PHOTO_BYTES
+
+    def __init__(self, rt, mcp=None, clock=lambda: datetime.now(UTC)):
+        self.rt, self.mcp, self.clock = rt, mcp, clock
+        self.tasks: set[asyncio.Task] = set()
+        self.cards: dict[str, object] = {}  # approval id -> where its prompt is (what close_prompt needs)
+        # stranger chat -> when it was last logged. In memory: a daemon restart logs each one again, which is fine
+        self.ignored_logged: dict[object, datetime] = {}
+
+    # --- the transport: each channel ---------------------------------------------------------------------
+
+    async def send(self, chat, text: str, choices: list[Choice] | None = None):
+        """Sends text (and choices) to a chat; returns where the last part is, for close_prompt."""
+        raise NotImplementedError
+
+    async def fetch(self, attachment: Attachment, limit: int) -> bytes:
+        """The attachment's bytes, at most limit (FileTooLarge past it, ChannelError when it fails)."""
+        raise NotImplementedError
+
+    async def acknowledge(self, decision: Decision, text: str) -> None:
+        """Tells whoever picked a choice what came of it."""
+        raise NotImplementedError
+
+    async def close_prompt(self, where, status: str) -> None:
+        """Replaces a decided prompt's choices with its outcome."""
+        raise NotImplementedError
+
+    def chat_from_setting(self, value: str):
+        return value
+
+    # --- the owner -----------------------------------------------------------------------------------------
+
+    def setting(self, key: str) -> str:
+        return f'{self.name}.{key}'
+
+    @property
+    def owner_chat(self):
+        value = self.rt.store.get_setting(self.setting('owner_chat'))
+        return self.chat_from_setting(value) if value else None
+
+    async def pair(self, chat, who: dict, code: str) -> None:
+        key = self.setting('pairing')
+        pairing = json.loads(self.rt.store.get_setting(key) or 'null')
+        if not pairing or datetime.fromisoformat(pairing['expires_at']) < self.clock():
+            self.rt.store.set_setting(key, None)
+            return await self.send(chat, 'There is no pairing code waiting. Make one with '
+                                         f'`wraithd {self.name} pair`.')
+        if not secrets.compare_digest(code, pairing['code']):
+            pairing['tries'] += 1
+            self.rt.store.set_setting(key, json.dumps(pairing) if pairing['tries'] < PAIRING_TRIES else None)
+            return await self.send(chat, 'That code is not right.')
+        self.rt.store.set_setting(key, None)
+        self.rt.store.set_setting(self.setting('owner_chat'), str(chat))
+        self.rt.store.set_setting(self.setting('owner_name'), who.get('username') and f'@{who["username"]}'
+                                  or who.get('first_name') or str(chat))
+        await self.send(chat, 'Paired: this chat is now the owner\'s.')
+
+    def ignore(self, chat, who: dict) -> None:
+        """A stranger: nothing is sent back and no model sees it, so it costs nothing and leaks nothing.
+        Logged by chat id and username only: the text is a stranger's, and the log is the owner's."""
+        now, last = self.clock(), self.ignored_logged.get(chat)
+        if last is not None and now - last < IGNORED_LOG_EVERY:
+            return
+        self.ignored_logged[chat] = now
+        ev.record_event(self.rt.store, self.ignored_event, chat=chat, username=who.get('username') or '')
+
+    # --- receiving -----------------------------------------------------------------------------------------
+
+    async def receive(self, message: Incoming) -> None:
+        text, chat = message.text.strip(), message.chat
+        if text.startswith('/pair'):
+            return await self.pair(chat, message.who, text.removeprefix('/pair').strip())
+        if chat != self.owner_chat:
+            return self.ignore(chat, message.who)
+        if not text and message.attachment is None:
+            return
+        if text == '/start':
+            return await self.send(chat, 'Hi. This is a personal assistant. Its owner pairs it with '
+                                         f'`wraithd {self.name} pair`.')
+        task = asyncio.create_task(self.answer(message))  # so choices keep being handled while it runs
+        self.tasks.add(task)
+        task.add_done_callback(self.tasks.discard)
+
+    async def answer(self, message: Incoming) -> None:
+        """The owner's message (receive() never gets here for anyone else)."""
+        chat = message.chat
+        try:
+            text, images = await self.for_run(message)
+        except Unusable as e:
+            return await self.send(chat, str(e))
+        conversation = (self.rt.store.find_conversation(self.name, str(chat))
+                        or self.rt.store.start_conversation(self.name, external=str(chat)))
+        result = await reply(self.rt, conversation.id, text, source=self.name,
+                             callback=self.approval_callback(chat), mcp=self.mcp, images=images)
+        await self.send(chat, result.answer)
+
+    async def settle(self) -> None:
+        """Waits for the messages being answered (tests, and a clean shutdown)."""
+        while self.tasks:
+            await asyncio.gather(*list(self.tasks), return_exceptions=True)
+
+    # --- attachments ---------------------------------------------------------------------------------------
+
+    async def for_run(self, message: Incoming) -> tuple[str, list[str]]:
+        """The run's message and images, attachments downloaded. Raises Unusable."""
+        text = (message.text or message.caption).strip()
+        item = message.attachment
+        if item is None:
+            return text, []
+        if item.kind == 'photo':
+            return await self._photo(item, text)
+        if item.kind == 'voice':
+            return await self._voice(item, text), []
+        return await self._file(item, text), []
+
+    async def _download(self, item: Attachment, limit: int) -> bytes:
+        too_large = f'That is too large for me to download from {self.title} ({limit // 1_000_000} MB at most).'
+        if (item.size or 0) > limit:
+            raise Unusable(too_large)
+        try:
+            return await self.fetch(item, limit)
+        except FileTooLarge:
+            raise Unusable(too_large) from None
+        except ChannelError as e:
+            logger.warning(str(e))
+            raise Unusable(f'I couldn\'t download that from {self.title}. Please send it again.') from None
+
+    def _save(self, name: str, data: bytes) -> str:
+        try:
+            name = f'{self.clock().astimezone():%Y-%m-%d}-{files.safe_name(name)}'
+            return files.save_new(self.rt.home.files_dir, INBOX, name, data)
+        except (files.OutsideWorkspace, OSError) as e:
+            logger.warning(f'Saving a {self.title} file failed: {e}')
+            raise Unusable('I couldn\'t save that file in your workspace.') from None
+
+    async def _photo(self, item: Attachment, caption: str) -> tuple[str, list[str]]:
+        """Image input; saved instead when the model can't see. The channel picks the size (the largest that fits)."""
+        if (item.size or 0) > self.max_photo_bytes:
+            raise Unusable(f'That photo is too large for me ({self.max_photo_bytes // 1_000_000} MB at most).')
+        data = await self._download(item, self.max_photo_bytes)
+        if not providers.can_see_images(self.rt.config):
+            saved = self._save('photo.jpg', data)
+            raise Unusable(f'Your model ({self.rt.config.model.default}) can\'t see images, so I saved the photo to '
+                           f'your workspace files as {saved}.')
+        image = f'data:{item.mime or "image/jpeg"};base64,' + base64.b64encode(data).decode()
+        return (f'[photo] {caption}' if caption else '[photo, no caption]'), [image]
+
+    async def _voice(self, item: Attachment, caption: str) -> str:
+        transcriber = voice.transcriber(self.rt.config, self.rt.voice_transport)
+        if transcriber is None:
+            why = voice.choose_transcriber(self.rt.config).why
+            raise Unusable(f'I can\'t listen to voice notes yet: transcription is {why}.')
+        data = await self._download(item, self.max_file_bytes)
+        try:
+            words = await transcriber.transcribe(data, 'voice.ogg', item.mime or 'audio/ogg')
+        except voice.TranscriptionFailed as e:
+            raise Unusable(f'I couldn\'t transcribe that voice note: {e}') from None
+        if not words:
+            raise Unusable('I couldn\'t hear any words in that voice note.')
+        return f'[voice note, transcribed] {words}' + (f'\n[caption] {caption}' if caption else '')
+
+    async def _file(self, item: Attachment, caption: str) -> str:
+        data = await self._download(item, self.max_file_bytes)
+        saved = self._save(item.name or 'file', data)
+        note = f'[The user sent a file, saved in the workspace files as {saved}. Read it with files_read if needed.]'
+        return f'{caption}\n{note}' if caption else note
+
+    # --- approvals -----------------------------------------------------------------------------------------
+
+    def approval_callback(self, chat):
+        async def callback(event_type: str, data: dict) -> None:
+            if event_type == 'approval_required':
+                text, choices = approval_prompt(data)
+                self.cards[data['approval_id']] = await self.send(chat, text, choices)
+            elif event_type == 'approval_resolved':
+                await self._close(data['approval_id'], data['status'])
+        return callback
+
+    async def decide(self, decision: Decision) -> None:
+        """A choice picked: only the paired owner's chat decides; anyone else is refused (and logged as ignored)."""
+        action, _, approval_id = decision.data.partition(':')
+        owner = self.owner_chat
+        if decision.chat != owner or action not in (ALLOW, DENY):
+            if decision.chat != owner and decision.chat is not None:
+                self.ignore(decision.chat, decision.who)
+            return await self.acknowledge(decision, 'Only the owner can decide.')
+        decision_ = store_base.APPROVED if action == ALLOW else store_base.DENIED
+        decided = self.rt.store.decide_approval(approval_id, decision_)
+        approval = self.rt.store.get_approval(approval_id)
+        status = approval_card(approval)['status'] if approval else 'unknown'
+        await self.acknowledge(decision, status.capitalize() if decided else f'Already {status}.')
+        await self._close(approval_id, status)
+
+    async def _close(self, approval_id: str, status: str) -> None:
+        where = self.cards.pop(approval_id, None)
+        if where is not None:
+            await self.close_prompt(where, status)

wraithd/channels/conversation.py

@@ -0,0 +1,26 @@
+"""
+One message in a conversation, the same way for every channel: store it, compact the history, run, store the
+answer. Conversations run one message at a time, so a second message waits for the first answer instead of
+racing it (the web API refuses it instead of waiting, see daemon/api.py).
+"""
+
+import asyncio
+
+from wraithd.core import compaction
+from wraithd.run import RunResult, Runtime, run
+
+_locks: dict[str, asyncio.Lock] = {}
+
+
+def lock_for(conversation_id: str) -> asyncio.Lock:
+    return _locks.setdefault(conversation_id, asyncio.Lock())
+
+
+async def reply(rt: Runtime, conversation_id: str, message: str, **run_options) -> RunResult:
+    """Answers one message in the conversation. run_options go to run() (callback, source, owner, mcp...)."""
+    async with lock_for(conversation_id):
+        rt.store.add_message(conversation_id, 'user', message)
+        history = await compaction.history_for(rt.store, conversation_id, rt.completer('compaction'))
+        result = await run(rt, message, history=history, **run_options)
+        rt.store.add_message(conversation_id, 'assistant', result.answer, run_id=result.run_id)
+        return result