tmux-agent-control 0.1.0__tar.gz

tmux_agent_control-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tmux_agent_control-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: tmux-agent-control
+Version: 0.1.0
+Summary: Local HTTP control daemon for tmux-backed coding-agent sessions
+License-Expression: MIT
+License-File: LICENSE
+Author: Tong
+Author-email: 16934247+jiaton@users.noreply.github.com
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: fastapi (>=0.139.0,<0.140.0)
+Requires-Dist: libtmux (>=0.61.0,<0.62.0)
+Requires-Dist: pywebpush (>=2.0)
+Requires-Dist: segno (>=1.6.0,<2.0.0)
+Requires-Dist: uvicorn[standard] (>=0.50.2,<0.51.0)

tmux_agent_control-0.1.0/daemon/adapter/tmux.py

@@ -0,0 +1,96 @@
+"""Thin wrapper over libtmux — the only module allowed to touch tmux directly."""
+import libtmux
+
+# Pinned to a fixed socket name rather than the ambient $TMUX var. Without
+# this, a daemon (re)started from inside a tmux pane inherits that pane's
+# server socket and can only see sessions on it — sessions launched from a
+# different pane, a different socket, or no tmux at all silently vanish
+# from find_pane(), and the reaper deletes their registry entries as if
+# the tmux session itself were gone. launcher/launch.py uses the same
+# socket name when creating sessions, so both sides always agree.
+TMUX_SOCKET_NAME = "tmux-agent-control"
+
+_server = libtmux.Server(socket_name=TMUX_SOCKET_NAME)
+
+
+def list_sessions():
+    return _server.sessions
+
+
+def find_session(session_name):
+    return _server.sessions.get(session_name=session_name, default=None)
+
+
+def find_pane(session_name, window_index=0, pane_index=0):
+    session = find_session(session_name)
+    if session is None:
+        return None
+    window = session.windows[window_index]
+    return window.panes[pane_index]
+
+
+def create_session(session_name, cwd, command):
+    """command is a single binary name (e.g. "claude"), never a shell
+    string with arguments — callers must not build up an argv/command line
+    here, that's exactly the "arbitrary shell execution over HTTP" this
+    project's AGENTS.md forbids."""
+    _server.new_session(session_name=session_name, start_directory=cwd, window_command=command)
+
+
+def kill_session(session_name):
+    session = find_session(session_name)
+    if session is not None:
+        session.kill()
+
+
+def capture_screen(pane):
+    # join_wrapped (tmux capture-pane -J) merges lines tmux only split
+    # because they hard-wrapped at the terminal's current width, back into
+    # one real line — without it, a real terminal (e.g. Warp) attached at
+    # whatever width it happens to be open to bakes those wrap points into
+    # the captured text as literal newlines, which a browser client then
+    # wraps *again* to fit its own narrower container, turning normal
+    # paragraphs into short, choppy multi-line fragments. This is the
+    # actual fix for that double-wrap; it doesn't require pinning the tmux
+    # window to any particular size, so a real terminal attaching to the
+    # session keeps resizing/wrapping normally on its own.
+    return "\n".join(pane.capture_pane(join_wrapped=True))
+
+
+DEFAULT_HISTORY_LINES = 100
+MAX_HISTORY_LINES = 2000
+
+
+def capture_screen_ansi(pane, lines=DEFAULT_HISTORY_LINES):
+    """Same as capture_screen but preserves ANSI escape codes (colors,
+    styles) and includes scrollback history, for clients that render a
+    real terminal (e.g. xterm.js) with scrollable history. classify.py
+    must keep using capture_screen (current screen only, no history,
+    plain text) — escape codes and extra history would break its
+    pattern matching and slow down the auto-approve poll loop.
+
+    `lines` defaults to a small window (just enough to cover a screen's
+    worth) since this gets re-fetched on every ~2s poll tick — the full
+    MAX_HISTORY_LINES is only worth the bandwidth when a client explicitly
+    asks for it (e.g. the user scrolled toward the top and needs more
+    history than the default window covers). join_wrapped=True for the
+    same reason as capture_screen — see that docstring."""
+    lines = max(1, min(lines, MAX_HISTORY_LINES))
+    return "\n".join(pane.capture_pane(escape_sequences=True, start=-lines, join_wrapped=True))
+
+
+def send_keys(pane, keys, enter=True):
+    pane.send_keys(keys, enter=enter)
+
+
+def send_key_name(pane, key):
+    """Sends a single tmux key name (e.g. "Escape", "C-o", "Up") rather than
+    literal text — libtmux's literal=False passes it straight to `tmux
+    send-keys` unquoted, which is what makes tmux interpret it as a key
+    rather than typing the characters "C-o" out. No enter: a named key is
+    already the whole input, unlike send_keys's text-then-Enter shape."""
+    pane.send_keys(key, enter=False, literal=False)
+
+
+def resize_pane(pane, width, height):
+    pane.resize(width=width, height=height)

tmux_agent_control-0.1.0/daemon/agent_aware/auto_approve.py

@@ -0,0 +1,51 @@
+"""Background auto-approve loop. Opt-in (see AGENTS.md) — disabled unless
+explicitly enabled, and only ever acts on a freshly re-classified state via
+try_approve(), never a cached/assumed one."""
+import asyncio
+import logging
+import os
+
+from daemon.adapter import tmux
+from daemon.agent_aware import classify
+from daemon.api.write import try_approve
+from daemon.registry import store
+
+logger = logging.getLogger("tmux_agent_control.auto_approve")
+
+# Subset of APPROVABLE_STATES that's safe to approve without a human in the
+# loop: repetitive, low-stakes confirmations. waiting_for_question_answer
+# and plan_review require actually thinking about the answer, never auto-approved.
+AUTO_APPROVE_STATES = {
+    classify.WAITING_FOR_TOOL_PERMISSION,
+    classify.WAITING_FOR_WORKSPACE_TRUST,
+    classify.WAITING_FOR_MCP_APPROVAL,
+}
+
+POLL_INTERVAL_SECONDS = float(os.environ.get("TAC_AUTO_APPROVE_INTERVAL", "0.5"))
+
+# Runtime-toggleable via POST /auto-approve (daemon/api/write.py) — the loop
+# below is always running; this flag just gates whether it acts. Seeded from
+# TAC_AUTO_APPROVE at import time so existing env-var-based startup behavior
+# is unchanged, but a client with the write token can flip it without a
+# daemon restart.
+enabled = os.environ.get("TAC_AUTO_APPROVE") == "1"
+
+
+async def run_loop():
+    logger.info("auto-approve loop started (states=%s)", AUTO_APPROVE_STATES)
+    while True:
+        if enabled:
+            for entry in store.list_entries():
+                try:
+                    pane = tmux.find_pane(entry["tmux_session"])
+                    if pane is None:
+                        continue
+                    state = classify.classify(tmux.capture_screen(pane))
+                    if state in AUTO_APPROVE_STATES:
+                        try_approve(pane)
+                        logger.info("auto-approved session_id=%s state=%s", entry["session_id"], state)
+                except Exception:
+                    logger.exception(
+                        "auto-approve check failed for session_id=%s, skipping", entry["session_id"]
+                    )
+        await asyncio.sleep(POLL_INTERVAL_SECONDS)

tmux_agent_control-0.1.0/daemon/agent_aware/classify.py

@@ -0,0 +1,73 @@
+"""Classifies a captured pane screen into a coarse agent state.
+
+Signatures are empirically verified for Claude Code (see docs/design.md).
+Order matters: check the most specific dialog footers before falling back
+to busy/idle, since dialog and busy/error text can co-occur on screen.
+"""
+import re
+
+WAITING_FOR_TOOL_PERMISSION = "waiting_for_tool_permission"
+WAITING_FOR_QUESTION_ANSWER = "waiting_for_question_answer"
+WAITING_FOR_WORKSPACE_TRUST = "waiting_for_workspace_trust"
+WAITING_FOR_MCP_APPROVAL = "waiting_for_mcp_approval"
+PLAN_REVIEW = "plan_review"
+ERROR = "error"
+BUSY = "busy"
+IDLE = "idle"
+
+_TOOL_PERMISSION_RE = re.compile(r"Tab\s+to\s+amend.*ctrl\+e\s+to\s+explain", re.DOTALL)
+_TOOL_PERMISSION_GENERIC_RE = re.compile(
+    r"Do\s+you\s+want\s+to.*?\n\s*❯?\s*1\.\s*Yes", re.DOTALL
+)
+_QUESTION_ANSWER_RE = re.compile(r"↑/↓\s+to\s+navigate")
+# AskUserQuestion's multi-step tabbed questionnaire (a "☐ step  ☐ step  ✔
+# Submit" tab bar above each step's own numbered options) — a distinct
+# dialog shape from the single free-text question _QUESTION_ANSWER_RE
+# matches. Without this, classify() fell through every other pattern and
+# misreported this as idle even while it was actively waiting on an
+# answer. Matched on the tab bar's own ☐/✔ icons rather than footer
+# wording ("Tab/Arrow keys to navigate") — the icons are this dialog's own
+# structural marker (every step renders one), where footer text is just
+# a hint string that could plausibly get reworded across Claude Code
+# versions independent of the dialog's actual shape.
+_MULTI_STEP_QUESTION_RE = re.compile(r"☐.*✔\s*Submit", re.DOTALL)
+_WORKSPACE_TRUST_RE = re.compile(r"Enter\s+to\s+confirm")
+_MCP_APPROVAL_RE = re.compile(r"MCP\s+server")
+_PLAN_REVIEW_RE = re.compile(r"How\s+would\s+you\s+like\s+to\s+proceed\?")
+_ERROR_RE = re.compile(r"API\s+Error:")
+_BUSY_RE = re.compile(r"esc\s+to\s+interrupt")
+
+
+def classify(screen_text):
+    if _TOOL_PERMISSION_RE.search(screen_text):
+        return WAITING_FOR_TOOL_PERMISSION
+    if _TOOL_PERMISSION_GENERIC_RE.search(screen_text):
+        return WAITING_FOR_TOOL_PERMISSION
+    if _QUESTION_ANSWER_RE.search(screen_text):
+        return WAITING_FOR_QUESTION_ANSWER
+    if _MULTI_STEP_QUESTION_RE.search(screen_text):
+        return WAITING_FOR_QUESTION_ANSWER
+    if _MCP_APPROVAL_RE.search(screen_text) and _WORKSPACE_TRUST_RE.search(screen_text):
+        return WAITING_FOR_MCP_APPROVAL
+    if _WORKSPACE_TRUST_RE.search(screen_text):
+        return WAITING_FOR_WORKSPACE_TRUST
+    if _PLAN_REVIEW_RE.search(screen_text):
+        return PLAN_REVIEW
+    if _ERROR_RE.search(screen_text):
+        return ERROR
+    if _BUSY_RE.search(screen_text):
+        return BUSY
+    return IDLE
+
+
+# States where sending "1" + Enter is a meaningful approve action.
+# Anything outside this set means there's no dialog to approve — approve()
+# must refuse rather than blindly injecting keystrokes (see AGENTS.md:
+# approve must be explicit, never inferred from generic input injection).
+APPROVABLE_STATES = {
+    WAITING_FOR_TOOL_PERMISSION,
+    WAITING_FOR_QUESTION_ANSWER,
+    WAITING_FOR_WORKSPACE_TRUST,
+    WAITING_FOR_MCP_APPROVAL,
+    PLAN_REVIEW,
+}

tmux_agent_control-0.1.0/daemon/agent_aware/push_watcher.py

@@ -0,0 +1,139 @@
+"""Always-on background push notification watcher. Fires a Web Push for each
+session that transitions into a pushable state requiring a human decision.
+Unlike auto_approve.py this is unconditional (not opt-in) — it becomes a
+no-op when there are zero stored subscriptions, at negligible cost.
+
+State-entry debounce: each push fires exactly once per transition into a
+pushable state. The in-memory map is cleared when a session leaves the
+pushable set. Losing the map on daemon restart may produce one duplicate push
+per session — acceptable per the approved design."""
+import asyncio
+import json
+import logging
+import os
+from datetime import datetime, timezone
+
+from pywebpush import WebPushException, webpush
+
+from daemon.adapter import tmux
+from daemon.agent_aware import classify
+from daemon.api import vapid
+from daemon.registry import push_store, store
+
+logger = logging.getLogger("tmux_agent_control.push")
+
+# States that require a real human decision — subset of APPROVABLE_STATES that
+# is not in auto_approve.AUTO_APPROVE_STATES. Mirror how auto_approve.py and
+# classify.py define their own state-set constants as module-level names.
+PUSHABLE_STATES = {
+    classify.WAITING_FOR_QUESTION_ANSWER,
+    classify.PLAN_REVIEW,
+}
+
+POLL_INTERVAL_SECONDS = float(os.environ.get("TAC_PUSH_INTERVAL_SECONDS", "2.0"))
+
+
+def _matches_filter(session_id: str, state: str, filters: dict) -> bool:
+    """Returns True if this subscription should receive a push for this
+    session/state combination."""
+    if session_id in filters.get("muted_session_ids", []):
+        return False
+    session_ids = filters.get("session_ids")
+    if session_ids is not None and session_id not in session_ids:
+        return False
+    if state == classify.WAITING_FOR_QUESTION_ANSWER and not filters.get("push_on_question_answer", True):
+        return False
+    if state == classify.PLAN_REVIEW and not filters.get("push_on_plan_review", True):
+        return False
+    return True
+
+
+def _build_payload(entry: dict, state: str) -> str:
+    return json.dumps({
+        "session_id": entry["session_id"],
+        "project_name": entry.get("project_name", ""),
+        "tmux_session": entry.get("tmux_session", ""),
+        "state": state,
+        "runtime": entry.get("runtime", ""),
+    })
+
+
+async def _send_push(sub_id: str, record: dict, payload: str, subs_path) -> None:
+    """Wraps pywebpush.webpush() (synchronous/blocking) in asyncio.to_thread."""
+    subscription_info = {
+        "endpoint": record["endpoint"],
+        "keys": record["keys"],
+    }
+    vapid_kwargs = vapid.get_vapid_claims()
+    try:
+        await asyncio.to_thread(
+            webpush,
+            subscription_info=subscription_info,
+            data=payload,
+            **vapid_kwargs,
+        )
+        now = datetime.now(timezone.utc).isoformat()
+        push_store.update_last_pushed(sub_id, now, path=subs_path)
+        logger.info("push sent sub_id=%s", sub_id)
+    except WebPushException as exc:
+        if exc.response is not None and exc.response.status_code in (404, 410):
+            push_store.remove_subscription(sub_id, path=subs_path)
+            logger.info("removed expired subscription sub_id=%s status=%s", sub_id, exc.response.status_code)
+        else:
+            logger.warning("push failed sub_id=%s error=%s", sub_id, exc)
+    except Exception as exc:
+        logger.warning("push error sub_id=%s error=%s", sub_id, exc)
+
+
+async def run_loop(registry_path=None, subs_path=None):
+    logger.info("push watcher loop started (states=%s)", PUSHABLE_STATES)
+    # In-memory debounce: {session_id: last_pushed_state}
+    last_pushed: dict[str, str] = {}
+
+    while True:
+        entries = store.list_entries(path=registry_path)
+        live_session_ids = set()
+
+        for entry in entries:
+            session_id = entry["session_id"]
+            live_session_ids.add(session_id)
+            try:
+                pane = tmux.find_pane(entry["tmux_session"])
+                if pane is None:
+                    continue
+                state = classify.classify(tmux.capture_screen(pane))
+
+                if state not in PUSHABLE_STATES:
+                    last_pushed.pop(session_id, None)
+                    continue
+
+                if last_pushed.get(session_id) == state:
+                    continue
+
+                last_pushed[session_id] = state
+                payload = _build_payload(entry, state)
+
+                subscriptions = push_store.list_subscriptions(path=subs_path)
+                if not subscriptions:
+                    continue
+
+                push_tasks = []
+                for sub_id, record in subscriptions.items():
+                    filters = record.get("filters", {})
+                    if _matches_filter(session_id, state, filters):
+                        push_tasks.append(_send_push(sub_id, record, payload, subs_path))
+
+                if push_tasks:
+                    await asyncio.gather(*push_tasks, return_exceptions=True)
+
+            except Exception:
+                logger.exception(
+                    "push watcher check failed for session_id=%s, skipping", session_id
+                )
+
+        # Clean up debounce entries for sessions no longer in the registry
+        for gone_id in list(last_pushed.keys()):
+            if gone_id not in live_session_ids:
+                last_pushed.pop(gone_id, None)
+
+        await asyncio.sleep(POLL_INTERVAL_SECONDS)

tmux_agent_control-0.1.0/daemon/api/auth.py

@@ -0,0 +1,29 @@
+"""Bearer-token auth for write routes. Read routes stay open (see
+AGENTS.md — phone/glasses clients poll status freely; only mutation is
+gated). Token is generated once and persisted next to the registry so it
+survives daemon restarts without any config step."""
+import secrets
+from pathlib import Path
+
+from fastapi import Header, HTTPException
+
+TOKEN_PATH = Path.home() / ".tmux-agent-control" / "token"
+
+
+def _load_or_create_token(path=None):
+    path = path or TOKEN_PATH
+    if path.exists():
+        return path.read_text().strip()
+
+    token = secrets.token_urlsafe(32)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(token)
+    path.chmod(0o600)
+    return token
+
+
+def require_token(authorization: str = Header(default="")):
+    expected = _load_or_create_token()
+    scheme, _, presented = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not secrets.compare_digest(presented, expected):
+        raise HTTPException(status_code=401, detail="missing or invalid bearer token")

tmux_agent_control-0.1.0/daemon/api/main.py

@@ -0,0 +1,73 @@
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from daemon.agent_aware import auto_approve, push_watcher
+from daemon.api.auth import _load_or_create_token
+from daemon.api.push import read_router as push_read_router
+from daemon.api.push import write_router as push_write_router
+from daemon.api.read import public_router as read_public_router
+from daemon.api.read import router as read_router
+from daemon.api.write import router as write_router
+from daemon.registry import reaper
+
+# Without this, every module-level `logging.getLogger(...).info(...)` call
+# (auto_approve's "loop started"/"auto-approved", write.py's audit_log, the
+# reaper) is silently dropped — the root logger's default level is WARNING,
+# so INFO never reaches daemon.log. That made a truly stuck/crashed
+# auto-approve loop indistinguishable from a working-but-just-quiet one when
+# grepping the log for evidence either way.
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+
+
+def _log_task_exception(task: asyncio.Task, name: str):
+    """asyncio silently swallows an unhandled exception in a background
+    task unless something explicitly retrieves it — a crash in
+    auto_approve.run_loop() or reaper.run_loop() would otherwise just stop
+    that loop forever with zero trace in daemon.log."""
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        logging.getLogger("tmux_agent_control.main").error("%s crashed", name, exc_info=exc)
+
+
+@asynccontextmanager
+async def lifespan(app):
+    token = _load_or_create_token()
+    print(f"tmux-agent-control write-API token: {token}")
+
+    reaper_task = asyncio.create_task(reaper.run_loop())
+    reaper_task.add_done_callback(lambda t: _log_task_exception(t, "reaper.run_loop"))
+    auto_approve_task = asyncio.create_task(auto_approve.run_loop())
+    auto_approve_task.add_done_callback(lambda t: _log_task_exception(t, "auto_approve.run_loop"))
+    push_watcher_task = asyncio.create_task(push_watcher.run_loop())
+    push_watcher_task.add_done_callback(lambda t: _log_task_exception(t, "push_watcher.run_loop"))
+
+    tasks = [reaper_task, auto_approve_task, push_watcher_task]
+    yield
+    for task in tasks:
+        task.cancel()
+
+
+app = FastAPI(title="tmux-agent-control", lifespan=lifespan)
+
+# Daemon binds to 127.0.0.1 only (see AGENTS.md) — CORS just lets a page
+# served from a different local origin (e.g. a static file server for the
+# mobile-web client) call it from a browser. Write routes require a bearer
+# token (daemon.api.auth); CORS alone was never meant to gate anything.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+app.include_router(read_public_router)
+app.include_router(read_router)
+app.include_router(write_router)
+app.include_router(push_read_router)
+app.include_router(push_write_router)

tmux_agent_control-0.1.0/daemon/api/pairing.py

@@ -0,0 +1,34 @@
+"""Pairing-window state, shared by the public `GET /pair` (daemon/api/read.py)
+and the token-gated `POST /pair/open` / `POST /pair/close` (daemon/api/
+write.py). Kept in its own module so read.py doesn't need write.py's auth
+dependency wiring just to check the flag, and write.py doesn't need read.py's
+segno/QR rendering just to flip it.
+
+The window used to open automatically for 10 minutes after every daemon
+start — meaning any restart (intentional, crash-loop, container restart)
+silently reopened an unauthenticated token-serving endpoint to anyone who
+could reach the port. Opening it is now an explicit action (`tac-daemon
+--pair`, which reads the token from the local filesystem and calls
+`POST /pair/open` itself) — closed by default, independent of process
+lifecycle.
+"""
+import time
+
+WINDOW_SECONDS = 10 * 60
+
+_open_until = None
+
+
+def open_window(seconds=WINDOW_SECONDS):
+    global _open_until
+    _open_until = time.monotonic() + seconds
+    return _open_until
+
+
+def close_window():
+    global _open_until
+    _open_until = None
+
+
+def is_open():
+    return _open_until is not None and time.monotonic() < _open_until

tmux_agent_control-0.1.0/daemon/api/panes.py

@@ -0,0 +1,17 @@
+"""Shared pane-resolution helper for both read and write routers."""
+from fastapi import HTTPException
+
+from daemon.adapter import tmux
+from daemon.registry import store
+
+
+def resolve_pane(session_id):
+    entry = store.get_entry(session_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail="unknown session_id")
+
+    pane = tmux.find_pane(entry["tmux_session"])
+    if pane is None:
+        raise HTTPException(status_code=404, detail="tmux session not found")
+
+    return pane

tmux_agent_control-0.1.0/daemon/api/push.py

@@ -0,0 +1,104 @@
+"""Push notification API — VAPID public key, subscribe, unsubscribe.
+
+Two separate APIRouters per the project's read/write separation rule, so
+main.py can apply the same router-level auth dependency as read.py/write.py:
+  - read_router:  GET /push/vapid-public-key
+  - write_router: POST /push/subscribe, POST /push/unsubscribe
+"""
+import hashlib
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from daemon.api.auth import require_token
+from daemon.api import vapid
+from daemon.registry import push_store
+
+read_router = APIRouter(dependencies=[Depends(require_token)])
+write_router = APIRouter(dependencies=[Depends(require_token)])
+audit_log = logging.getLogger("tmux_agent_control.audit")
+
+
+def _subscription_id(endpoint: str) -> str:
+    return hashlib.sha256(endpoint.encode()).hexdigest()
+
+
+# --- Pydantic models ---
+
+class SubscriptionKeys(BaseModel):
+    p256dh: str
+    auth: str
+
+
+class SubscriptionInfo(BaseModel):
+    endpoint: str
+    keys: SubscriptionKeys
+
+
+class SubscriptionFilters(BaseModel):
+    session_ids: Optional[list[str]] = None
+    muted_session_ids: list[str] = []
+    push_on_question_answer: bool = True
+    push_on_plan_review: bool = True
+
+
+class SubscribeRequest(BaseModel):
+    subscription: SubscriptionInfo
+    filters: SubscriptionFilters = SubscriptionFilters()
+
+
+class UnsubscribeRequest(BaseModel):
+    subscription_id: Optional[str] = None
+    endpoint: Optional[str] = None
+
+
+# --- Read routes ---
+
+@read_router.get("/push/vapid-public-key")
+def get_vapid_public_key():
+    return {"public_key": vapid.get_public_key_b64()}
+
+
+# --- Write routes ---
+
+@write_router.post("/push/subscribe")
+def subscribe(body: SubscribeRequest):
+    if not body.subscription.endpoint:
+        raise HTTPException(status_code=400, detail="endpoint is required")
+
+    sub_id = _subscription_id(body.subscription.endpoint)
+    record = {
+        "endpoint": body.subscription.endpoint,
+        "keys": {
+            "p256dh": body.subscription.keys.p256dh,
+            "auth": body.subscription.keys.auth,
+        },
+        "filters": {
+            "session_ids": body.filters.session_ids,
+            "muted_session_ids": body.filters.muted_session_ids,
+            "push_on_question_answer": body.filters.push_on_question_answer,
+            "push_on_plan_review": body.filters.push_on_plan_review,
+        },
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "last_pushed_at": None,
+    }
+    push_store.upsert_subscription(sub_id, record)
+    audit_log.info("push subscribe sub_id=%s endpoint=%s", sub_id, body.subscription.endpoint)
+    return {"subscription_id": sub_id}
+
+
+@write_router.post("/push/unsubscribe")
+def unsubscribe(body: UnsubscribeRequest):
+    if body.subscription_id is None and body.endpoint is None:
+        raise HTTPException(status_code=400, detail="subscription_id or endpoint is required")
+
+    sub_id = body.subscription_id
+    if sub_id is None:
+        sub_id = _subscription_id(body.endpoint)
+
+    removed = push_store.remove_subscription(sub_id)
+    audit_log.info("push unsubscribe sub_id=%s removed=%s", sub_id, removed)
+    return {"removed": removed}