agentwire-dev 1.35.1__tar.gz → 1.37.0__tar.gz

{agentwire_dev-1.35.1 → agentwire_dev-1.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.35.1
+Version: 1.37.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev
@@ -849,7 +849,8 @@ Agent responses are spoken back — Kokoro neural voice out of the box, or any T
 AgentWire supports orchestrator/worker patterns for complex tasks:
 
 ```yaml
-# .agentwire.yml in your project
+# .agentwire.yml in your project (keep it gitignored — it's personal config,
+# and tracked copies break worktree dispatch; agentwire adds it to .gitignore for you)
 type: claude-bypass
 roles:
   - agentwire

{agentwire_dev-1.35.1 → agentwire_dev-1.37.0}/README.md

@@ -128,7 +128,8 @@ Agent responses are spoken back — Kokoro neural voice out of the box, or any T
 AgentWire supports orchestrator/worker patterns for complex tasks:
 
 ```yaml
-# .agentwire.yml in your project
+# .agentwire.yml in your project (keep it gitignored — it's personal config,
+# and tracked copies break worktree dispatch; agentwire adds it to .gitignore for you)
 type: claude-bypass
 roles:
   - agentwire

{agentwire_dev-1.35.1 → agentwire_dev-1.37.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.35.1"
+__version__ = "1.37.0"

{agentwire_dev-1.35.1 → agentwire_dev-1.37.0}/agentwire/__main__.py

@@ -36,7 +36,15 @@ from .project_config import (
     normalize_session_type,
     save_project_config,
 )
-from .roles import RoleConfig, inject_soul, load_roles, merge_roles
+from .roles import (
+    WORKTREE_MISSION_ROLE,
+    RoleConfig,
+    inject_soul,
+    inject_worktree_mission,
+    load_roles,
+    merge_roles,
+    render_mission_placeholders,
+)
 from .worktree import ensure_worktree, parse_session_name, remove_worktree
 
 # Default config directory
@@ -193,10 +201,20 @@ def build_agent_command(session_type: str, roles: list[RoleConfig] | None = None
             raise ValueError(
                 f"No config for pi provider '{provider}'. "
                 f"Add pi.providers.{provider} to ~/.agentwire/config.yaml "
-                f"with at least env_var, api_key, and default_model."
+                f"with at least env_var and default_model, and put the key "
+                f"itself in ~/.agentwire/.env (docs/wiki/security/secrets.md)."
             )
         env_var = provider_cfg.get("env_var", f"{provider.upper().replace('-', '_')}_API_KEY")
-        api_key = provider_cfg.get("api_key", "")
+        if provider_cfg.get("api_key"):
+            print(
+                f"Warning: pi.providers.{provider}.api_key in config.yaml is "
+                f"ignored — put {env_var}=... in ~/.agentwire/.env instead "
+                f"(docs/wiki/security/secrets.md)",
+                file=sys.stderr,
+            )
+        # The key comes from the process environment — ~/.agentwire/.env is
+        # loaded on every entry point, so one line there is all it takes.
+        api_key = os.environ.get(env_var, "")
         default_model = provider_cfg.get("default_model", "")
 
         # Merge provider key + any global pi extra_env
@@ -2418,32 +2436,38 @@ def cmd_notify_parent(args) -> int:
         if parent:
             target_session = parent
 
-    # Build notification message
-    source = current_session or "unknown"
-    if current_pane is not None and current_pane > 0:
-        notification = f"[NOTIFY from {source} pane {current_pane}] {text}"
+    # Build notification message (--raw sends verbatim — queued messages
+    # already carry their own [WORKER SUMMARY ...] / [PROMPT ...] headers)
+    if getattr(args, 'raw', False):
+        notification = text
     else:
-        notification = f"[NOTIFY from {source}] {text}"
-
-    try:
-        if target_session:
-            if target_session == current_session and current_pane == 0:
-                print("Cannot notify own pane", file=sys.stderr)
-                return 1
-            pane_manager.send_to_pane(target_session, 0, notification)
-            if not getattr(args, 'quiet', False):
-                print(f"Notified {target_session}")
-        elif current_pane is not None and current_pane > 0 and current_session:
-            pane_manager.send_to_pane(current_session, 0, notification)
-            if not getattr(args, 'quiet', False):
-                print(f"Notified {current_session} pane 0")
+        source = current_session or "unknown"
+        if current_pane is not None and current_pane > 0:
+            notification = f"[NOTIFY from {source} pane {current_pane}] {text}"
         else:
-            print("No target session (set 'parent' in .agentwire.yml or use --to)", file=sys.stderr)
+            notification = f"[NOTIFY from {source}] {text}"
+
+    if target_session:
+        if target_session == current_session and current_pane == 0:
+            print("Cannot notify own pane", file=sys.stderr)
             return 1
-    except Exception as e:
-        print(f"Failed to send notification: {e}", file=sys.stderr)
+    elif current_pane is not None and current_pane > 0 and current_session:
+        target_session = current_session
+    else:
+        print("No target session (set 'parent' in .agentwire.yml or use --to)", file=sys.stderr)
         return 1
 
+    # safe_deliver refuses targets where a paste could do damage (live
+    # dialog on screen, bare shell, parked session) and verifies the paste
+    # actually landed. Callers (queue processor) retry on failure.
+    from agentwire import prompt_router
+
+    delivered, reason = prompt_router.safe_deliver(target_session, 0, notification)
+    if not delivered:
+        print(f"Notification not delivered to {target_session}: {reason}", file=sys.stderr)
+        return 1
+    if not getattr(args, 'quiet', False):
+        print(f"Notified {target_session}")
     return 0
 
 
@@ -2843,6 +2867,23 @@ def store_session_metadata(session_name: str, metadata: dict) -> None:
         pass
 
 
+def _record_session_creator(session_name: str, created_by: str | None, via: str) -> None:
+    """Record which session created this one (merge-preserving).
+
+    The creator becomes the session's parent for prompt routing
+    (prompt_router.resolve_parent), winning over .agentwire.yml `parent:`.
+    """
+    if not created_by or created_by == session_name.split("@")[0]:
+        return
+    metadata = load_session_metadata(session_name)
+    metadata.update({
+        "created_by": created_by,
+        "created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "created_via": via,
+    })
+    store_session_metadata(session_name, metadata)
+
+
 def cmd_notify(args) -> int:
     """Send a notification to the portal about session/pane state changes.
 
@@ -3272,6 +3313,13 @@ def cmd_new(args) -> int:
             default_role = config.get("session", {}).get("default_role", "agentwire")
             role_names = [default_role] if default_role else []
 
+    # Standing mission briefing for worktree dispatches: cmd_worktree passes
+    # mission_context (branch/cwd/base/creator values) which both opts the
+    # session into the worktree-mission role and templates its placeholders.
+    mission_context = getattr(args, 'mission_context', None)
+    if mission_context:
+        role_names = inject_worktree_mission(role_names)
+
     # Always-inject the soul personality role (rides last for recency weight)
     role_names = inject_soul(role_names, load_config(), no_soul=getattr(args, 'no_soul', False))
 
@@ -3284,6 +3332,11 @@ def cmd_new(args) -> int:
         if missing:
             return _output_result(False, json_mode, f"Roles not found: {', '.join(missing)}")
 
+    if mission_context:
+        for role in roles:
+            if role.name == WORKTREE_MISSION_ROLE:
+                role.instructions = render_mission_placeholders(role.instructions, mission_context)
+
     # Parse session name: project, branch, machine
     project, branch, machine_id = parse_session_name(name)
 
@@ -3657,6 +3710,13 @@ def cmd_new(args) -> int:
         if not first_message_delivered and not json_mode:
             print(f"Warning: first message not delivered to '{session_name}' — paste it manually", file=sys.stderr)
 
+    # Record the creating session as parent for prompt routing. --created-by
+    # overrides; empty string opts out; default = the calling tmux session.
+    created_by = getattr(args, 'created_by', None)
+    if created_by is None:
+        created_by = pane_manager.get_current_session()
+    _record_session_creator(session_name, created_by, via="new")
+
     if json_mode:
         result = {
             "success": True,
@@ -4066,6 +4126,15 @@ def cmd_kill(args) -> int:
     if not json_mode:
         print(f"Killed session '{session}'")
 
+    # Drop session metadata (creator record) so a future unrelated session
+    # reusing this name doesn't inherit a stale parent.
+    metadata_file = CONFIG_DIR / "sessions" / session.split("@")[0] / "metadata.json"
+    if metadata_file.exists():
+        try:
+            metadata_file.unlink()
+        except OSError:
+            pass
+
     _notify_portal_sessions_changed()
 
     if json_mode:
@@ -4435,6 +4504,10 @@ def cmd_send_keys(args) -> int:
     # Parse session@machine format
     session, machine_id = _parse_session_target(session_full)
 
+    # Optional pane targeting (worker panes); None targets the session.
+    pane = getattr(args, 'pane', None)
+    target = f"{session}.{pane}" if pane is not None else session
+
     if machine_id:
         # Remote: SSH and run tmux commands
         machine = _get_machine_config(machine_id)
@@ -4443,10 +4516,10 @@ def cmd_send_keys(args) -> int:
             return 1
 
         # Build remote command with pauses between keys
-        quoted_session = shlex.quote(session)
+        quoted_target = shlex.quote(target)
         cmd_parts = []
         for i, key in enumerate(keys):
-            cmd_parts.append(f"tmux send-keys -t {quoted_session} {shlex.quote(key)}")
+            cmd_parts.append(f"tmux send-keys -t {quoted_target} {shlex.quote(key)}")
             if i < len(keys) - 1:
                 cmd_parts.append("sleep 0.1")
 
@@ -4473,14 +4546,14 @@ def cmd_send_keys(args) -> int:
     # Send each key group with a pause between
     for i, key in enumerate(keys):
         subprocess.run(
-            ["tmux", "send-keys", "-t", session, key],
+            ["tmux", "send-keys", "-t", target, key],
             check=True
         )
         # Brief pause between key groups (not after last one)
         if i < len(keys) - 1:
             time.sleep(0.1)
 
-    print(f"Sent keys to {session}")
+    print(f"Sent keys to {target}")
     return 0
 
 
@@ -4726,6 +4799,12 @@ def cmd_worktree(args) -> int:
     - --ref: detached at a ref. `agentwire worktree review-v2 --ref v2.0.0`
 
     If the worktree already exists, reattaches to the existing session.
+
+    Default/--existing dispatches auto-inject the bundled worktree-mission
+    briefing role (isolation, no live-tool mutation, in-worktree
+    verification, draft-PR + notify-back contract) with branch/cwd/base/
+    creator templated in — opt out with --no-mission. --ref dispatches skip
+    it (detached checkout, nothing to push).
     """
     json_mode = getattr(args, 'json', False)
     name = args.name
@@ -4751,13 +4830,42 @@ def cmd_worktree(args) -> int:
     session_name = f"{project_name}-{name}"
     worktree_path = worktree_dir / session_name
 
-    def _launch_session():
+    default_base = getattr(args, 'base', None) or wt_config.get("default_base", "main")
+    no_mission = getattr(args, 'no_mission', False)
+
+    def _mission_context(base_branch: str) -> dict | None:
+        """Values templated into the worktree-mission briefing role.
+
+        None (no briefing) when --no-mission is passed, or for --ref
+        dispatches — a detached review checkout has no branch to push, so
+        the finishing contract doesn't apply.
+        """
+        if no_mission or ref:
+            return None
+        creator = pane_manager.get_current_session()
+        notify_back = (
+            f'agentwire notify-parent --to {creator} "{session_name}: <one-liner + PR URL>"'
+            if creator else
+            f'agentwire notify-parent "{session_name}: <one-liner + PR URL>"'
+        )
+        return {
+            "session": session_name,
+            "branch": name,
+            "worktree_path": str(worktree_path),
+            "main_checkout": str(project_path),
+            "base_branch": base_branch,
+            "creator": creator or "your creator session",
+            "notify_back": notify_back,
+        }
+
+    def _launch_session(mission_context: dict | None = None):
         return cmd_new(type('Args', (), {
             'session': session_name, 'path': str(worktree_path), 'json': json_mode,
             'force': False, 'bare': False, 'restricted': False, 'prompted': False,
             'type': getattr(args, 'type', None), 'roles': getattr(args, 'roles', None),
             'instructions': None, 'persist': False,
             'env': getattr(args, 'env', None),
+            'mission_context': mission_context,
         })())
 
     # If worktree already exists, reattach
@@ -4769,10 +4877,11 @@ def cmd_worktree(args) -> int:
         if tmux_session_exists(session_name):
             subprocess.run(["tmux", "attach-session", "-t", session_name])
         else:
-            return _launch_session()
+            return _launch_session(_mission_context(default_base))
         return 0
 
     # Resolve the git ref to create the worktree from
+    pr_base = default_base
     if ref:
         # --ref mode: detached at a specific ref (tag, commit, branch)
         git_ref = ref
@@ -4794,7 +4903,8 @@ def cmd_worktree(args) -> int:
                 return _output_result(False, json_mode, f"Failed to detect current branch in {project_path}")
             base_branch = result.stdout.strip()
         else:
-            base_branch = getattr(args, 'base', None) or wt_config.get("default_base", "main")
+            base_branch = default_base
+        pr_base = base_branch
         git_ref = f"origin/{base_branch}"
         new_branch = name
         mode_label = f"new branch {name} from {git_ref}"
@@ -4841,7 +4951,7 @@ def cmd_worktree(args) -> int:
         print(f"Created worktree: {worktree_path}")
         print(f"Mode: {mode_label}")
 
-    return _launch_session()
+    return _launch_session(_mission_context(pr_base))
 
 
 def cmd_fork(args) -> int:
@@ -6737,6 +6847,45 @@ def cmd_doctor(args) -> int:
             print("       Fix: agentwire stt start")
             print("       If it won't boot: uv pip install --python .venv/bin/python -e '.[stt]'")
             issues_found += 1
+    elif getattr(stt_cfg, "backend", "default") == "cloud":
+        cloud_cfg = getattr(stt_cfg, "cloud", None) or {}
+        key_env = cloud_cfg.get("api_key_env", "OPENAI_API_KEY")
+        if os.environ.get(key_env):
+            print(f"  [ok] Stt: cloud tier ({key_env} is set)")
+        else:
+            print(f"  [!!] Stt: cloud tier but {key_env} is not set")
+            print("       The portal will refuse to start until the key is in its environment.")
+            print("       Fix: add the key to ~/.agentwire/.env (docs/wiki/security/secrets.md)")
+            issues_found += 1
+
+    # 8c. Secrets — for each configured feature that needs a key, report
+    # whether its env var is present. Names only, never values. Keys live in
+    # ~/.agentwire/.env (docs/wiki/security/secrets.md), loaded on every
+    # entry point, so os.environ is the authoritative view here.
+    raw_cfg = load_config()
+    expected_keys: list[tuple[str, list[str]]] = []
+    channels_cfg = raw_cfg.get("channels", {}) or {}
+    if channels_cfg.get("email"):
+        expected_keys.append(("channels.email (Resend)", ["RESEND_API_KEY"]))
+    if channels_cfg.get("quo"):
+        expected_keys.append(
+            ("channels.quo (OpenPhone)", ["QUO_API_KEY", "OPENPHONE_API_KEY"])
+        )
+    for pname, pcfg in (raw_cfg.get("pi", {}).get("providers", {}) or {}).items():
+        p_env_var = (pcfg or {}).get(
+            "env_var", f"{pname.upper().replace('-', '_')}_API_KEY"
+        )
+        expected_keys.append((f"pi.providers.{pname}", [p_env_var]))
+    if expected_keys:
+        print("\nChecking secrets (~/.agentwire/.env)...")
+        for feature, candidates in expected_keys:
+            found = next((v for v in candidates if os.environ.get(v)), None)
+            if found:
+                print(f"  [ok] {feature}: {found} is set")
+            else:
+                print(f"  [!!] {feature}: {' / '.join(candidates)} not set")
+                print(f"       Fix: add {candidates[0]}=... to ~/.agentwire/.env")
+                issues_found += 1
 
     # 9. Validate remote machines
     print("\nChecking remote machines...")
@@ -7465,7 +7614,7 @@ _VALID_PROJECT_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
 def cmd_projects_create(args) -> int:
     """Create a new local project: make the directory, optionally git-init or clone, and write .agentwire.yml."""
     from .config import get_config
-    from .project_config import ProjectConfig, SessionType, save_project_config
+    from .project_config import ProjectConfig, SessionType, ensure_gitignored, save_project_config
 
     name = (args.name or "").strip()
     clone_url = (getattr(args, "from_url", None) or "").strip() or None
@@ -7518,6 +7667,7 @@ def cmd_projects_create(args) -> int:
     except OSError as e:
         return _fail(f"Failed to create directory: {e}")
 
+    gitignore_updated = ensure_gitignored(project_path)
     config = ProjectConfig(type=SessionType.from_str("claude-bypass"), roles=[], voice=None)
     if not save_project_config(config, project_path):
         return _fail("Created project directory but failed to write .agentwire.yml")
@@ -7538,6 +7688,8 @@ def cmd_projects_create(args) -> int:
             print(f"  Cloned from: {clone_url}")
         elif do_git_init:
             print("  Initialized empty git repository")
+        if gitignore_updated:
+            print("  Added .agentwire.yml to .gitignore (personal config — keep it untracked)")
     return 0
 
 
@@ -8444,8 +8596,6 @@ def cmd_ensure(args) -> int:
                 print(f"  {preview_template(cmd, ctx)}")
             print()
 
-        if task.output.notify:
-            print(f"Notification: {task.output.notify}")
         if task.output.save:
             print(f"Save output to: {preview_template(task.output.save, ctx)}")
 
@@ -9016,7 +9166,7 @@ def cmd_task_show(args) -> int:
             "pre": [{"name": p.name, "cmd": p.cmd, "required": p.required, "validate": p.validate, "timeout": p.timeout} for p in task.pre],
             "on_task_end": task.on_task_end,
             "post": task.post,
-            "output": {"capture": task.output.capture, "save": task.output.save, "notify": task.output.notify},
+            "output": {"capture": task.output.capture, "save": task.output.save},
             "validation_issues": issues,
         })
         return 0
@@ -9055,12 +9205,9 @@ def cmd_task_show(args) -> int:
             print(f"  {cmd}")
         print()
 
-    if task.output.notify or task.output.save:
+    if task.output.save:
         print("Output:")
-        if task.output.save:
-            print(f"  Save to: {task.output.save}")
-        if task.output.notify:
-            print(f"  Notify: {task.output.notify}")
+        print(f"  Save to: {task.output.save}")
 
     if issues:
         print(f"\nValidation issues: {', '.join(issues)}")
@@ -10540,6 +10687,8 @@ def main() -> int:
     notify_cmd_parser.add_argument("text", nargs="*", help="Notification message")
     notify_cmd_parser.add_argument("--to", type=str, metavar="SESSION", help="Target session (default: parent from .agentwire.yml)")
     notify_cmd_parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
+    notify_cmd_parser.add_argument("--raw", action="store_true",
+                                   help="Send the message verbatim (no [NOTIFY from ...] prefix)")
     notify_cmd_parser.set_defaults(func=cmd_notify_parent)
 
     # === open command (artifact windows) ===
@@ -10617,6 +10766,8 @@ def main() -> int:
         "send-keys", help="Send raw keys to a session (with pause between groups)"
     )
     send_keys_parser.add_argument("-s", "--session", required=True, help="Target session (supports session@machine)")
+    send_keys_parser.add_argument("--pane", type=int, default=None,
+                                  help="Target a specific pane index (default: the session's active pane)")
     send_keys_parser.add_argument("keys", nargs="*", help="Key groups to send (e.g., 'hello world' Enter)")
     send_keys_parser.set_defaults(func=cmd_send_keys)
 
@@ -10649,6 +10800,9 @@ def main() -> int:
     new_parser.add_argument("--no-pull-first", dest="pull_first", action="store_false", help="Skip the fetch — branch from the local copy of <base> as-is")
     new_parser.add_argument("--first-message", dest="first_message",
                             help="After the agent boots, deliver this as its first message (verified; local sessions only)")
+    new_parser.add_argument("--created-by", dest="created_by",
+                            help="Record this session as the creator/parent for prompt routing "
+                                 "(default: the calling tmux session; pass '' to opt out)")
     new_parser.add_argument("--json", action="store_true", help="Output as JSON")
     new_parser.set_defaults(func=cmd_new)
 
@@ -10746,6 +10900,8 @@ def main() -> int:
     wt_parser.add_argument("--project", "-p", help="Path to git repo (default: from config or cwd)")
     wt_parser.add_argument("--type", help="Session type override")
     wt_parser.add_argument("--roles", help="Comma-separated role names")
+    wt_parser.add_argument("--no-mission", dest="no_mission", action="store_true",
+                           help="Skip the auto-injected worktree-mission briefing role")
     wt_parser.add_argument("--env", action="append", metavar="KEY=VAL", help="Inject env var via `tmux set-environment` (repeatable)")
     wt_parser.add_argument("--json", action="store_true", help="Output as JSON")
     wt_parser.set_defaults(func=cmd_worktree)
@@ -11488,6 +11644,14 @@ def main() -> int:
     )
     l_uninstall.set_defaults(func=limits_cli.cmd_limits_uninstall)
 
+    # === prompts command group (prompt routing, rides the limits watchdog) ===
+    from . import prompts_cli
+    prompts_cli.register_prompts_parser(subparsers)
+
+    # === msg command group (polite agent-to-agent inbox, rides the watchdog) ===
+    from . import msg_cli
+    msg_cli.register_msg_parser(subparsers)
+
     # === council command group ===
     council_parser = subparsers.add_parser(
         "council",

{agentwire_dev-1.35.1 → agentwire_dev-1.37.0}/agentwire/agents/tmux.py

@@ -9,6 +9,7 @@ import subprocess
 from pathlib import Path
 
 from .base import AgentBackend
+from ..ssh import ssh_base_opts
 
 logger = logging.getLogger(__name__)
 
@@ -134,6 +135,7 @@ class TmuxAgent(AgentBackend):
         port = machine.get("port")
         ssh_cmd = [
             "ssh",
+            *ssh_base_opts(),
             "-o", "BatchMode=yes",
             "-o", "ConnectTimeout=5",
         ]

{agentwire_dev-1.35.1 → agentwire_dev-1.37.0}/agentwire/channels/email.py

@@ -9,7 +9,7 @@ import os
 import random
 import re
 import sys
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Optional
 
@@ -34,19 +34,23 @@ class EmailConfigError(NotificationError):
 
 @dataclass
 class EmailConfig:
-    """Email notification configuration (Resend)."""
+    """Email notification configuration (Resend).
+
+    The API key is env-only: RESEND_API_KEY, normally a line in
+    ~/.agentwire/.env (docs/wiki/security/secrets.md). It is never read
+    from config.yaml.
+    """
 
-    api_key: str = ""
     from_address: str = ""
     default_to: str = ""
     banner_image_url: str = ""
     echo_image_url: str = ""
     echo_small_url: str = ""
     logo_image_url: str = ""
+    api_key: str = field(init=False, default="")
 
     def __post_init__(self):
-        if not self.api_key:
-            self.api_key = os.environ.get("RESEND_API_KEY", "")
+        self.api_key = os.environ.get("RESEND_API_KEY", "")
 
 
 # Playful greetings from Echo
@@ -225,8 +229,8 @@ def send_email(
     if not email_config.api_key:
         raise EmailConfigError(
             "Email API key not configured. "
-            "Set RESEND_API_KEY in ~/.agentwire/.env "
-            "or set channels.email.api_key in ~/.agentwire/config.yaml"
+            "Add RESEND_API_KEY=re_... to ~/.agentwire/.env "
+            "(see docs/wiki/security/secrets.md)"
         )
 
     # Determine recipients (list form — Resend's `to` field accepts an array)

{agentwire_dev-1.35.1 → agentwire_dev-1.37.0}/agentwire/channels/quo.py

@@ -9,7 +9,7 @@ import os
 import sys
 import urllib.error
 import urllib.request
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Optional
 
 from .base import (
@@ -28,15 +28,19 @@ class QuoConfigError(NotificationError):
 
 @dataclass
 class QuoConfig:
-    """Quo (OpenPhone) SMS configuration."""
+    """Quo (OpenPhone) SMS configuration.
+
+    The API key is env-only: QUO_API_KEY (or legacy OPENPHONE_API_KEY),
+    normally a line in ~/.agentwire/.env (docs/wiki/security/secrets.md).
+    It is never read from config.yaml.
+    """
 
-    api_key: str = ""
     from_number: str = ""  # E.164 format (+1...) or phone number ID (PNxxx)
     default_to: str = ""
+    api_key: str = field(init=False, default="")
 
     def __post_init__(self):
-        if not self.api_key:
-            self.api_key = os.environ.get("QUO_API_KEY", "") or os.environ.get("OPENPHONE_API_KEY", "")
+        self.api_key = os.environ.get("QUO_API_KEY", "") or os.environ.get("OPENPHONE_API_KEY", "")
 
 
 API_URL = "https://api.openphone.com/v1/messages"
@@ -72,8 +76,9 @@ def send_quo_sms(
 
     if not quo_config.api_key:
         raise QuoConfigError(
-            "Quo API key not configured. Set QUO_API_KEY env var "
-            "or channels.quo.api_key in ~/.agentwire/config.yaml"
+            "Quo API key not configured. "
+            "Add QUO_API_KEY=... to ~/.agentwire/.env "
+            "(see docs/wiki/security/secrets.md)"
         )
 
     recipient = to or quo_config.default_to