agentwire-dev 1.30.1__tar.gz → 1.31.0__tar.gz

{agentwire_dev-1.30.1 → agentwire_dev-1.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.30.1
+Version: 1.31.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
@@ -729,7 +729,7 @@ Description-Content-Type: text/markdown
   <a href="https://pypi.org/project/agentwire-dev/"><img src="https://img.shields.io/pypi/v/agentwire-dev?color=green" alt="PyPI"></a>
   <a href="https://pypi.org/project/agentwire-dev/"><img src="https://img.shields.io/pypi/pyversions/agentwire-dev" alt="Python"></a>
   <a href="https://github.com/dotdevdotdev/agentwire-dev/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dotdevdotdev/agentwire-dev" alt="License"></a>
-  <a href="https://discord.gg/bspFZNTdUr"><img src="https://img.shields.io/discord/1234567890?color=5865F2&label=discord" alt="Discord"></a>
+  <a href="https://discord.gg/bspFZNTdUr"><img src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
 </p>
 
 ---
@@ -748,10 +748,6 @@ Old way: Get up. Walk to computer. Type.
 
 Push-to-talk voice control for [Claude Code](https://github.com/anthropics/claude-code) or any AI coding assistant running in tmux.
 
-<p align="center">
-  <img src="https://agentwire.dev/images/demo.gif" alt="Demo" width="600">
-</p>
-
 ```
 Phone → AgentWire Portal → tmux session → Claude Code
  🎤        (WebSocket)         📺           🤖
@@ -777,11 +773,15 @@ agentwire generate-certs
 
 # Run
 agentwire portal start
-# Open https://localhost:8765
+# Open http://127.0.0.1:8765 in Chrome — voice works immediately
 ```
 
 **Requirements:** Python 3.10+, tmux, ffmpeg, Claude Code
 
+**Honest setup time:** under a minute to a working voice portal (instant mode: Chrome speech in, browser voice out — robotic but real). ~15 minutes for the full experience: cloned voices via a self-hosted TTS shim, Whisper-grade transcription, phone-from-anywhere (certs + token).
+
+> **Network & trust model.** The portal binds `127.0.0.1` by default — local only. To use it from your phone, set `server.host: 0.0.0.0` in `~/.agentwire/config.yaml`. Non-loopback binds require an auth token (auto-generated on first start; print it with `agentwire portal token`) — your phone prompts for it once, then remembers it. Origin checks reject cross-site browser requests on every bind. Still: keep it on a trusted LAN. Never port-forward it or run it on a public-facing VPS — for internet access use Cloudflare Tunnel + Zero Trust. Details in [SECURITY.md](SECURITY.md).
+
 <details>
 <summary><strong>Platform-specific instructions</strong></summary>
 
@@ -802,6 +802,8 @@ pip install agentwire-dev
 
 </details>
 
+> **tmux config matters.** Default tmux has no mouse scroll, a tiny scrollback, and broken copy UX — see [Recommended tmux config](docs/wiki/quickstart.md#recommended-tmux-config), or let `agentwire init` install it for you.
+
 ---
 
 ## Features
@@ -828,13 +830,13 @@ agentwire new -s myproject -p ~/projects/myproject
 ```
 
 **2. Open the portal:**
-Visit `https://localhost:8765` on your phone/tablet/laptop
+Visit `http://127.0.0.1:8765` in Chrome (or your phone/tablet with LAN access configured)
 
 **3. Talk:**
-Hold the mic button, speak your request, release. The transcription goes to Claude Code.
+Hold the mic button, speak your request, release. In instant mode the transcript appears for a quick glance — Enter sends it to Claude Code.
 
 **4. Listen:**
-Agent responses are spoken back via TTS (optional, requires GPU for self-hosted or RunPod).
+Agent responses are spoken back — browser voice out of the box, or a real TTS model behind a custom shim.
 
 ---
 
@@ -883,29 +885,33 @@ All decisions logged for audit trails.
 
 ## Voice Configuration
 
-**TTS (Text-to-Speech):** Requires GPU. Options:
+Two tiers, both sides:
+
+**`default` (zero setup, what a fresh install gets):** Chrome speech recognition in, browser speechSynthesis out, OS voice when no browser is connected. No GPU, no models, no certs.
+
+**`custom` (bring your own model):** any HTTP shim implementing the [voice shim contract](docs/wiki/voice/shim-contract.md) — ~30 lines wraps anything (Deepgram, whisper.cpp, an expressive emotion-tag model). The bundled servers are reference shims:
 
 ```yaml
 # ~/.agentwire/config.yaml
 tts:
-  backend: "runpod"  # Recommended: RunPod serverless
-  runpod_endpoint_id: "your-endpoint"
-  runpod_api_key: "your-key"
+  backend: "custom"
+  url: "http://localhost:8100"     # agentwire tts start (kokoro CPU / chatterbox GPU / qwen / zonos)
+  options:
+    backend: kokoro
+stt:
+  backend: "custom"
+  url: "http://localhost:8101"     # agentwire stt start (moonshine ONNX, CPU)
 ```
 
-Or self-host with `agentwire tts start` on a GPU machine.
-
-**STT (Speech-to-Text):** Runs locally via `agentwire stt start`. Uses Moonshine ONNX by default (fast CPU inference, no GPU required), with automatic fallback to faster-whisper. Configure backend in `config.yaml`.
+Shims can declare capabilities (emotion tags, style instructions) via `GET /capabilities` — agentwire injects the shim's `tool_prompt` into the agent's `say` tooldef so agents actually use them.
 
 <details>
-<summary><strong>Disable voice (text-only mode)</strong></summary>
-
-```yaml
-tts:
-  backend: "none"
-```
+<summary><strong>Prefer text-only?</strong></summary>
 
-You can still use the portal for session management without voice.
+Instant mode already needs nothing — just don't press the mic. Agent speech
+plays through the browser; mute the tab (or close it — with no browser
+connected the OS voice handles notifications, which you can silence at the
+system level).
 
 </details>
 
@@ -983,7 +989,7 @@ Quick links:
 - [Troubleshooting](docs/wiki/internals/troubleshooting.md)
 - [Portal API](docs/wiki/internals/portal.md)
 - [Remote Machines](docs/wiki/deployment/remote-machines.md)
-- [RunPod TTS](docs/wiki/tts/runpod-tts.md) · [Self-Hosted TTS](docs/wiki/tts/tts-self-hosted.md)
+- [Voice Shim Contract](docs/wiki/voice/shim-contract.md) · [Self-Hosted TTS](docs/wiki/voice/tts-self-hosted.md)
 - [Safety Hooks](docs/wiki/internals/damage-control.md)
 
 ---

{agentwire_dev-1.30.1 → agentwire_dev-1.31.0}/README.md

@@ -10,7 +10,7 @@
   <a href="https://pypi.org/project/agentwire-dev/"><img src="https://img.shields.io/pypi/v/agentwire-dev?color=green" alt="PyPI"></a>
   <a href="https://pypi.org/project/agentwire-dev/"><img src="https://img.shields.io/pypi/pyversions/agentwire-dev" alt="Python"></a>
   <a href="https://github.com/dotdevdotdev/agentwire-dev/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dotdevdotdev/agentwire-dev" alt="License"></a>
-  <a href="https://discord.gg/bspFZNTdUr"><img src="https://img.shields.io/discord/1234567890?color=5865F2&label=discord" alt="Discord"></a>
+  <a href="https://discord.gg/bspFZNTdUr"><img src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
 </p>
 
 ---
@@ -29,10 +29,6 @@ Old way: Get up. Walk to computer. Type.
 
 Push-to-talk voice control for [Claude Code](https://github.com/anthropics/claude-code) or any AI coding assistant running in tmux.
 
-<p align="center">
-  <img src="https://agentwire.dev/images/demo.gif" alt="Demo" width="600">
-</p>
-
 ```
 Phone → AgentWire Portal → tmux session → Claude Code
  🎤        (WebSocket)         📺           🤖
@@ -58,11 +54,15 @@ agentwire generate-certs
 
 # Run
 agentwire portal start
-# Open https://localhost:8765
+# Open http://127.0.0.1:8765 in Chrome — voice works immediately
 ```
 
 **Requirements:** Python 3.10+, tmux, ffmpeg, Claude Code
 
+**Honest setup time:** under a minute to a working voice portal (instant mode: Chrome speech in, browser voice out — robotic but real). ~15 minutes for the full experience: cloned voices via a self-hosted TTS shim, Whisper-grade transcription, phone-from-anywhere (certs + token).
+
+> **Network & trust model.** The portal binds `127.0.0.1` by default — local only. To use it from your phone, set `server.host: 0.0.0.0` in `~/.agentwire/config.yaml`. Non-loopback binds require an auth token (auto-generated on first start; print it with `agentwire portal token`) — your phone prompts for it once, then remembers it. Origin checks reject cross-site browser requests on every bind. Still: keep it on a trusted LAN. Never port-forward it or run it on a public-facing VPS — for internet access use Cloudflare Tunnel + Zero Trust. Details in [SECURITY.md](SECURITY.md).
+
 <details>
 <summary><strong>Platform-specific instructions</strong></summary>
 
@@ -83,6 +83,8 @@ pip install agentwire-dev
 
 </details>
 
+> **tmux config matters.** Default tmux has no mouse scroll, a tiny scrollback, and broken copy UX — see [Recommended tmux config](docs/wiki/quickstart.md#recommended-tmux-config), or let `agentwire init` install it for you.
+
 ---
 
 ## Features
@@ -109,13 +111,13 @@ agentwire new -s myproject -p ~/projects/myproject
 ```
 
 **2. Open the portal:**
-Visit `https://localhost:8765` on your phone/tablet/laptop
+Visit `http://127.0.0.1:8765` in Chrome (or your phone/tablet with LAN access configured)
 
 **3. Talk:**
-Hold the mic button, speak your request, release. The transcription goes to Claude Code.
+Hold the mic button, speak your request, release. In instant mode the transcript appears for a quick glance — Enter sends it to Claude Code.
 
 **4. Listen:**
-Agent responses are spoken back via TTS (optional, requires GPU for self-hosted or RunPod).
+Agent responses are spoken back — browser voice out of the box, or a real TTS model behind a custom shim.
 
 ---
 
@@ -164,29 +166,33 @@ All decisions logged for audit trails.
 
 ## Voice Configuration
 
-**TTS (Text-to-Speech):** Requires GPU. Options:
+Two tiers, both sides:
+
+**`default` (zero setup, what a fresh install gets):** Chrome speech recognition in, browser speechSynthesis out, OS voice when no browser is connected. No GPU, no models, no certs.
+
+**`custom` (bring your own model):** any HTTP shim implementing the [voice shim contract](docs/wiki/voice/shim-contract.md) — ~30 lines wraps anything (Deepgram, whisper.cpp, an expressive emotion-tag model). The bundled servers are reference shims:
 
 ```yaml
 # ~/.agentwire/config.yaml
 tts:
-  backend: "runpod"  # Recommended: RunPod serverless
-  runpod_endpoint_id: "your-endpoint"
-  runpod_api_key: "your-key"
+  backend: "custom"
+  url: "http://localhost:8100"     # agentwire tts start (kokoro CPU / chatterbox GPU / qwen / zonos)
+  options:
+    backend: kokoro
+stt:
+  backend: "custom"
+  url: "http://localhost:8101"     # agentwire stt start (moonshine ONNX, CPU)
 ```
 
-Or self-host with `agentwire tts start` on a GPU machine.
-
-**STT (Speech-to-Text):** Runs locally via `agentwire stt start`. Uses Moonshine ONNX by default (fast CPU inference, no GPU required), with automatic fallback to faster-whisper. Configure backend in `config.yaml`.
+Shims can declare capabilities (emotion tags, style instructions) via `GET /capabilities` — agentwire injects the shim's `tool_prompt` into the agent's `say` tooldef so agents actually use them.
 
 <details>
-<summary><strong>Disable voice (text-only mode)</strong></summary>
-
-```yaml
-tts:
-  backend: "none"
-```
+<summary><strong>Prefer text-only?</strong></summary>
 
-You can still use the portal for session management without voice.
+Instant mode already needs nothing — just don't press the mic. Agent speech
+plays through the browser; mute the tab (or close it — with no browser
+connected the OS voice handles notifications, which you can silence at the
+system level).
 
 </details>
 
@@ -264,7 +270,7 @@ Quick links:
 - [Troubleshooting](docs/wiki/internals/troubleshooting.md)
 - [Portal API](docs/wiki/internals/portal.md)
 - [Remote Machines](docs/wiki/deployment/remote-machines.md)
-- [RunPod TTS](docs/wiki/tts/runpod-tts.md) · [Self-Hosted TTS](docs/wiki/tts/tts-self-hosted.md)
+- [Voice Shim Contract](docs/wiki/voice/shim-contract.md) · [Self-Hosted TTS](docs/wiki/voice/tts-self-hosted.md)
 - [Safety Hooks](docs/wiki/internals/damage-control.md)
 
 ---

agentwire_dev-1.31.0/SECURITY.md

@@ -0,0 +1,63 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in AgentWire, please report it privately.
+
+**Do NOT open a public GitHub issue for security vulnerabilities.**
+
+### How to Report
+
+Email: security@agentwire.dev
+
+Include:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Any suggested fixes (optional)
+
+### What to Expect
+
+- **Acknowledgment:** Within 48 hours
+- **Initial Assessment:** Within 1 week
+- **Resolution Timeline:** Depends on severity, typically 30-90 days
+
+### Scope
+
+This security policy applies to:
+- The AgentWire CLI (`agentwire` command)
+- The AgentWire portal (web interface)
+- Official AgentWire packages on PyPI
+
+### Out of Scope
+
+- Third-party dependencies (report to their maintainers)
+- Self-hosted TTS/STT servers
+- User misconfiguration
+
+## Security Features
+
+AgentWire includes built-in security features:
+
+- **Damage Control Hooks:** Block 300+ dangerous command patterns
+- **Path Protection:** Prevent access to sensitive files (.env, SSH keys, credentials)
+- **Audit Logging:** All blocked operations are logged
+
+See `docs/wiki/internals/damage-control.md` for details.
+
+## Trust Model
+
+The portal enforces two security layers in-process:
+
+1. **Origin validation (always on).** Every state-changing request (POST/PUT/DELETE/PATCH) and WebSocket upgrade with an `Origin` header must match the portal's own origin, a localhost equivalent, or an entry in `server.allowed_origins` (exact `scheme://host[:port]` strings — needed when fronting with Cloudflare Tunnel, where the browser's origin is the tunnel domain). Mismatches get a 403 and a log line. Requests without an Origin header (curl, CLI, scripts) pass — CSRF is a browser vector. This protects loopback-only users from malicious pages firing cross-site requests at `localhost:8765`.
+
+2. **Bearer-token auth (required for non-loopback binds).** The portal binds `127.0.0.1:8765` by default — local only. Binding anything else (`0.0.0.0`, a LAN IP) auto-generates a token at `~/.agentwire/portal.token` (mode 0600) and requires it on every request outside the public bootstrap surface (`GET /`, `/health`, `/static/*`): `Authorization: Bearer <token>` on HTTP, `agentwire.bearer.<token>` WebSocket subprotocol. The portal **refuses to start** on a non-loopback bind with auth explicitly disabled. Print the token with `agentwire portal token`; rotate with `--rotate`. Browsers prompt once per device and store it in localStorage.
+
+Token configuration (`server.auth_token` in `~/.agentwire/config.yaml`): unset = use the token file (auto-generated); any string = explicit override; `""` = auth disabled, allowed only on loopback binds. Tokens are compared constant-time and redacted from the config served to the portal's config editor.
+
+What this means in practice:
+
+- **LAN exposure (`server.host: 0.0.0.0`) is protected by the token.** Someone on your network who can reach the port gets 401s until they present it. Treat the token like a password; rotate it if a device is lost.
+- **Do not expose the portal directly to the public internet.** Token auth raises the bar on a trusted LAN; it is not a substitute for identity, MFA, audit, and revocation. For anything internet-facing, front it with **Cloudflare Tunnel + Zero Trust** (see `docs/wiki/deployment/remote-access.md`) and add your tunnel domain to `server.allowed_origins`.
+- **Project deletion via `/api/projects/delete`** validates the path is absolute, contains no `..`, contains no shell metacharacters, and is not in a protected list. Local execution uses argv form (no shell); SSH execution uses `shlex.quote` per argument. These mitigations reduce blast radius if the perimeter fails.
+- **Self-hosted TTS/STT servers are a separate trust domain** — they have no auth of their own and are out of scope here.

{agentwire_dev-1.30.1 → agentwire_dev-1.31.0}/agentwire/__init__.py

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