antigravity-wakeup 0.1.0__tar.gz

antigravity_wakeup-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladimir Berezhnoy <non7top@gmail.com>
+
+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.

antigravity_wakeup-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: antigravity-wakeup
+Version: 0.1.0
+Summary: Wake an idle Antigravity (agy) conversation from another process via agy agentapi send-message.
+Author: non7top
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/non7top/antigravity-wakeup
+Project-URL: Source, https://github.com/non7top/antigravity-wakeup
+Project-URL: Issues, https://github.com/non7top/antigravity-wakeup/issues
+Keywords: antigravity,agy,wakeup,push,agentapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: dev
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# antigravity-wakeup
+
+Wake an idle Antigravity CLI (`agy`) conversation from another process.
+
+An MCP server cannot start a turn in `agy`. The only way is `agy agentapi send-message`, which needs `ANTIGRAVITY_LS_ADDRESS` and `ANTIGRAVITY_CSRF_TOKEN`. `agy` puts those (and `ANTIGRAVITY_CONVERSATION_ID`) only into its agent's shell tool, never into MCP servers or hook processes. This library works around that with a one-time "prime" step run from the agent's own shell.
+
+## How it works
+
+1. A host process (for example an MCP server running under `agy`) creates a `Prime`, builds a poker with `prime.new_poker()` and serves its control socket (`poker.serve_control_socket(path)`, a `0600` Unix socket).
+2. The agent runs the command from `prime.command()` in its shell tool. That runs `antigravity-wakeup --prime`, which reads the `ANTIGRAVITY_*` environment, finds the host process under the same `agy` process and sends the endpoint to its control socket.
+3. The host calls `poker.notify(sender)` whenever something arrives. Notifications are debounced, then the poker runs `agy agentapi send-message` with text from your `wake_text` callback. A send counts as delivered only when agy's reply names the conversation (`response.sendMessage.recipientId`).
+4. A marker file records which host is primed for a conversation. The `PreInvocation` hook (`antigravity-wakeup --prime-hook`) reads it and, for an unprimed conversation, injects an `ephemeralMessage` telling the agent to run the prime command. After a failed attempt the hook waits 10 minutes before asking again.
+
+The token is held in memory only and reaches the `agy` child through its environment, never argv, logs or disk. Only loopback addresses are accepted. Optional `pin_agy_process=True` also checks that the primed `agy` process (pid plus start time) is still the same one before each send.
+
+## Use
+
+```python
+from antigravity_wakeup.prime import Prime
+
+prime = Prime(
+    script_name="my-tool",              # console script that runs --prime / --prime-hook
+    module="my_tool.cli",               # fallback for `python -m` when the script is not found
+    notice="...",                       # text injected by the hook for an unprimed conversation
+    wake_text=lambda senders: "...",    # text sent on each wake; must not carry peer-written content
+)
+poker = prime.new_poker()
+# in the host's event loop:  asyncio.create_task(poker.serve_control_socket(path))
+# when something arrives:    poker.notify(sender)
+# to tell the agent what to run: prime.command()
+```
+
+The `antigravity-wakeup` command exposes `--prime` and `--prime-hook` for a host that has no CLI of its own; `antigravity_wakeup.cli.main(prime)` takes a configured `Prime`.
+
+## Current limits
+
+Several defaults still come from the project this was split out of: marker and stable-link directories under `~/.claude/chatter-*`, and host discovery through Claude Code's `~/.claude/sessions` files (`messagingSocketPath`). Making those pluggable is open work.
+
+## Development
+
+```
+make build
+make lint
+make test
+make package
+```
+
+Everything runs in a throwaway container with its own `$HOME`.
+
+## License
+
+MIT

antigravity_wakeup-0.1.0/README.md

@@ -0,0 +1,52 @@
+# antigravity-wakeup
+
+Wake an idle Antigravity CLI (`agy`) conversation from another process.
+
+An MCP server cannot start a turn in `agy`. The only way is `agy agentapi send-message`, which needs `ANTIGRAVITY_LS_ADDRESS` and `ANTIGRAVITY_CSRF_TOKEN`. `agy` puts those (and `ANTIGRAVITY_CONVERSATION_ID`) only into its agent's shell tool, never into MCP servers or hook processes. This library works around that with a one-time "prime" step run from the agent's own shell.
+
+## How it works
+
+1. A host process (for example an MCP server running under `agy`) creates a `Prime`, builds a poker with `prime.new_poker()` and serves its control socket (`poker.serve_control_socket(path)`, a `0600` Unix socket).
+2. The agent runs the command from `prime.command()` in its shell tool. That runs `antigravity-wakeup --prime`, which reads the `ANTIGRAVITY_*` environment, finds the host process under the same `agy` process and sends the endpoint to its control socket.
+3. The host calls `poker.notify(sender)` whenever something arrives. Notifications are debounced, then the poker runs `agy agentapi send-message` with text from your `wake_text` callback. A send counts as delivered only when agy's reply names the conversation (`response.sendMessage.recipientId`).
+4. A marker file records which host is primed for a conversation. The `PreInvocation` hook (`antigravity-wakeup --prime-hook`) reads it and, for an unprimed conversation, injects an `ephemeralMessage` telling the agent to run the prime command. After a failed attempt the hook waits 10 minutes before asking again.
+
+The token is held in memory only and reaches the `agy` child through its environment, never argv, logs or disk. Only loopback addresses are accepted. Optional `pin_agy_process=True` also checks that the primed `agy` process (pid plus start time) is still the same one before each send.
+
+## Use
+
+```python
+from antigravity_wakeup.prime import Prime
+
+prime = Prime(
+    script_name="my-tool",              # console script that runs --prime / --prime-hook
+    module="my_tool.cli",               # fallback for `python -m` when the script is not found
+    notice="...",                       # text injected by the hook for an unprimed conversation
+    wake_text=lambda senders: "...",    # text sent on each wake; must not carry peer-written content
+)
+poker = prime.new_poker()
+# in the host's event loop:  asyncio.create_task(poker.serve_control_socket(path))
+# when something arrives:    poker.notify(sender)
+# to tell the agent what to run: prime.command()
+```
+
+The `antigravity-wakeup` command exposes `--prime` and `--prime-hook` for a host that has no CLI of its own; `antigravity_wakeup.cli.main(prime)` takes a configured `Prime`.
+
+## Current limits
+
+Several defaults still come from the project this was split out of: marker and stable-link directories under `~/.claude/chatter-*`, and host discovery through Claude Code's `~/.claude/sessions` files (`messagingSocketPath`). Making those pluggable is open work.
+
+## Development
+
+```
+make build
+make lint
+make test
+make package
+```
+
+Everything runs in a throwaway container with its own `$HOME`.
+
+## License
+
+MIT

antigravity_wakeup-0.1.0/antigravity_wakeup/__init__.py

@@ -0,0 +1,6 @@
+"""
+Wake an idle Antigravity (agy) conversation from another process.
+
+Kept free of imports on purpose: the PreInvocation hook runs before every model
+invocation and must stay cheap.
+"""

antigravity_wakeup-0.1.0/antigravity_wakeup/agentapi.py

@@ -0,0 +1,57 @@
+"""The one call made into agy: `agy agentapi send-message`."""
+import os
+import json
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+from .endpoint import Endpoint
+
+logger = logging.getLogger("antigravity_wakeup")
+
+
+@dataclass(frozen=True)
+class SendResult:
+    ok: bool
+    error: Optional[str] = None
+    endpoint_gone: bool = False
+
+
+class AgentApi:
+    def __init__(self, timeout_seconds: float = 20.0, title: str = "antigravity-wakeup"):
+        self._timeout = timeout_seconds
+        self._title = title
+
+    async def send_message(self, endpoint: Endpoint, text: str) -> SendResult:
+        # The token goes through the child's environment only, never argv or logs.
+        env = dict(os.environ)
+        env["ANTIGRAVITY_LS_ADDRESS"] = endpoint.ls_address
+        env["ANTIGRAVITY_CSRF_TOKEN"] = endpoint.csrf_token
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                endpoint.agy_path, "agentapi", "send-message", f"--title={self._title}",
+                endpoint.conversation_id, text,
+                env=env, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+            )
+            stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=self._timeout)
+        except Exception as e:
+            return SendResult(False, f"agentapi invocation failed: {e}")
+        return self._classify(stdout, proc.returncode, endpoint.conversation_id)
+
+    @staticmethod
+    def _classify(stdout: bytes, returncode: Optional[int], conversation_id: str) -> SendResult:
+        # agentapi exits 0 even on failure, so the JSON is the only reliable signal.
+        try:
+            reply = json.loads(stdout.decode("utf-8"))
+        except ValueError:
+            reply = None
+        if not isinstance(reply, dict):
+            return SendResult(False, f"unparseable agentapi output (exit {returncode})")
+        if reply.get("error"):
+            error = str(reply["error"])[:300]
+            return SendResult(False, error, endpoint_gone="Unavailable" in error)
+        sent = (reply.get("response") or {}).get("sendMessage")
+        if not isinstance(sent, dict) or sent.get("recipientId") != conversation_id:
+            return SendResult(False, "agy did not confirm delivery to the conversation")
+        return SendResult(True)

antigravity_wakeup-0.1.0/antigravity_wakeup/cli.py

@@ -0,0 +1,27 @@
+"""CLI for the two modes an agy session needs: priming from its shell, and the PreInvocation hook."""
+import sys
+import json
+import argparse
+
+from .prime import Prime
+
+
+def main(prime: Prime = None):
+    prime = prime or Prime()
+    parser = argparse.ArgumentParser(description="Wake an idle Antigravity conversation")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--prime", action="store_true", help="From an agy shell tool: hand this agy's push endpoint to its host process")
+    group.add_argument("--prime-hook", action="store_true", help="PreInvocation hook: reads hook JSON on stdin and prints the JSON that makes the session prime push")
+    args = parser.parse_args()
+
+    if args.prime_hook:
+        print(prime.run_hook(sys.stdin.read()))
+        sys.exit(0)
+
+    result = prime.prime_from_shell()
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result.get("ok") else 1)
+
+
+if __name__ == "__main__":
+    main()

antigravity_wakeup-0.1.0/antigravity_wakeup/command.py

@@ -0,0 +1,48 @@
+"""The shell command an agent runs to prime push."""
+import os
+import sys
+import shlex
+import shutil
+from typing import Optional
+
+from . import paths
+
+
+class PrimeCommand:
+    def __init__(self, script_name: str = "antigravity-wakeup", module: str = "antigravity_wakeup.cli", stable_link: Optional[str] = None):
+        self._script_name = script_name
+        self._module = module
+        self._stable_link = stable_link or os.path.join(paths.STABLE_LINK_DIR, script_name)
+
+    def build(self) -> str:
+        """The shortest shell command that runs this install's own `--prime`."""
+        bin_dir = os.path.dirname(sys.executable)
+        script = os.path.join(bin_dir, self._script_name)
+        if not os.path.exists(script):
+            return f"{shlex.quote(sys.executable)} -m {self._module} --prime"
+        # `uv run` puts the project venv's bin on this process's PATH only; the
+        # agent's shell won't have it, so don't count that directory as "on PATH".
+        other_dirs = [
+            d for d in os.environ.get("PATH", "").split(os.pathsep)
+            if d and os.path.realpath(d) != os.path.realpath(bin_dir)
+        ]
+        on_path = shutil.which(self._script_name, path=os.pathsep.join(other_dirs))
+        if on_path and os.path.realpath(on_path) == os.path.realpath(script):
+            return f"{self._script_name} --prime"
+        # A uvx cache path changes on every rebuild, which defeats a permission
+        # allow-list entry for the command; this link keeps the command stable.
+        try:
+            self._refresh_stable_link(script)
+            return f"{shlex.quote(self._stable_link)} --prime"
+        except OSError:
+            return f"{shlex.quote(script)} --prime"
+
+    def _refresh_stable_link(self, script: str):
+        os.makedirs(os.path.dirname(self._stable_link), exist_ok=True)
+        tmp_path = f"{self._stable_link}.{os.getpid()}"
+        try:
+            os.remove(tmp_path)
+        except FileNotFoundError:
+            pass
+        os.symlink(script, tmp_path)
+        os.replace(tmp_path, self._stable_link)

antigravity_wakeup-0.1.0/antigravity_wakeup/control.py

@@ -0,0 +1,48 @@
+"""The 0600 Unix control socket a primed host listens on for prime and status requests."""
+import os
+import json
+import asyncio
+import logging
+from typing import Any, Callable, Dict
+
+logger = logging.getLogger("antigravity_wakeup")
+
+
+def control_socket_path(bridge_socket_path: str) -> str:
+    return bridge_socket_path + ".ctl"
+
+
+class ControlServer:
+    """One JSON request line in, one JSON reply line out; what the request means is the handler's business."""
+
+    def __init__(self, handler: Callable[[Dict[str, Any]], Dict[str, Any]]):
+        self._handler = handler
+
+    async def serve(self, path: str):
+        if os.path.exists(path):
+            os.remove(path)
+        server = await asyncio.start_unix_server(self._handle, path)
+        os.chmod(path, 0o600)
+        logger.info(f"Push control socket operational on: {path}")
+        async with server:
+            await server.serve_forever()
+
+    async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+        try:
+            line = await asyncio.wait_for(reader.readline(), timeout=5.0)
+            try:
+                request = json.loads(line.decode("utf-8"))
+            except ValueError:
+                reply = {"ok": False, "error": "invalid JSON"}
+            else:
+                reply = self._handler(request) if isinstance(request, dict) else {"ok": False, "error": "invalid JSON"}
+            writer.write((json.dumps(reply) + "\n").encode("utf-8"))
+            await writer.drain()
+        except Exception as e:
+            logger.error(f"Push control request failed: {e}")
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass

antigravity_wakeup-0.1.0/antigravity_wakeup/endpoint.py

@@ -0,0 +1,72 @@
+"""The agy conversation to wake: its endpoint credentials and the marker that records it is primed."""
+import os
+import re
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from . import paths
+
+logger = logging.getLogger("antigravity_wakeup")
+
+# The token is handed to an agy child that connects to this address, so a
+# non-loopback address would send it somewhere else.
+_LOOPBACK_ADDRESS = re.compile(r"^(localhost|127\.0\.0\.1|\[::1\]):\d{1,5}$")
+
+
+class InvalidEndpoint(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    conversation_id: str
+    ls_address: str
+    csrf_token: str
+    agy_path: str
+    agy_pid: Optional[int] = None
+    agy_started: Optional[float] = None
+
+    @classmethod
+    def from_request(cls, req: Dict[str, Any], require_agy_process: bool = False) -> "Endpoint":
+        conv, address, token, agy_path = (req.get(k) for k in ("conversation_id", "ls_address", "csrf_token", "agy_path"))
+        if not all(isinstance(v, str) and v for v in (conv, address, token, agy_path)):
+            raise InvalidEndpoint("conversation_id, ls_address, csrf_token and agy_path are required strings")
+        if not paths.CONVERSATION_ID.match(conv):
+            raise InvalidEndpoint("conversation_id has an unexpected format")
+        if not _LOOPBACK_ADDRESS.match(address):
+            raise InvalidEndpoint("ls_address must be a loopback host:port")
+        if not (os.path.isabs(agy_path) and os.access(agy_path, os.X_OK)):
+            raise InvalidEndpoint("agy_path must be an absolute path to an executable")
+
+        pid, started = req.get("agy_pid"), req.get("agy_started")
+        has_process = (
+            isinstance(pid, int) and not isinstance(pid, bool) and pid > 0
+            and isinstance(started, (int, float)) and not isinstance(started, bool)
+        )
+        if require_agy_process and not has_process:
+            raise InvalidEndpoint("agy_pid and agy_started are required when agy process pinning is on")
+        return cls(conv, address, token, agy_path, pid if has_process else None, float(started) if has_process else None)
+
+
+class PrimedMarker:
+    """Lets the prime hook cheaply tell "already primed" without ever holding the token."""
+
+    @staticmethod
+    def path(conversation_id: str) -> str:
+        return os.path.join(paths.PRIMED_DIR, f"{conversation_id}.json")
+
+    def write(self, conversation_id: str):
+        try:
+            os.makedirs(paths.PRIMED_DIR, exist_ok=True)
+            with open(self.path(conversation_id), "w", encoding="utf-8") as f:
+                json.dump({"bridge_pid": os.getpid(), "conversation_id": conversation_id}, f)
+        except OSError as e:
+            logger.error(f"Failed to write primed marker: {e}")
+
+    def remove(self, conversation_id: str):
+        try:
+            os.remove(self.path(conversation_id))
+        except OSError:
+            pass

antigravity_wakeup-0.1.0/antigravity_wakeup/hook.py

@@ -0,0 +1,76 @@
+"""
+An Antigravity PreInvocation hook that makes sure the conversation is primed
+for push. Pure stdlib and cheap, since it runs before every model invocation.
+
+A hook process does not get the language-server token, so it cannot prime by
+itself. Instead it injects an ephemeralMessage telling the agent to run the
+prime command in its own shell, where the token exists.
+"""
+import os
+import json
+import time
+from typing import Any, Dict, Optional
+
+from . import paths
+
+# A failed priming must not be retried before every model invocation.
+RETRY_AFTER_SECONDS = 600
+DEFAULT_NOTICE = (
+    "[antigravity-wakeup] Push is not enabled for this conversation, so messages from other "
+    "sessions cannot wake you. Before anything else, run `antigravity-wakeup --prime` in your "
+    "shell, exactly as given. Then continue with the user's request."
+)
+
+
+class PrimeHook:
+    def __init__(self, notice: str = DEFAULT_NOTICE, primed_dir: Optional[str] = None):
+        self._notice = notice
+        self._primed_dir = primed_dir
+
+    def run(self, stdin_text: str) -> str:
+        try:
+            hook_input = json.loads(stdin_text) if stdin_text.strip() else {}
+        except ValueError:
+            hook_input = {}
+        return json.dumps(self.decide(hook_input))
+
+    def decide(self, hook_input: Dict[str, Any], now: Optional[float] = None) -> Dict[str, Any]:
+        primed_dir = self._primed_dir or paths.PRIMED_DIR
+        conv = hook_input.get("conversationId")
+        if not isinstance(conv, str) or not paths.CONVERSATION_ID.match(conv):
+            return {}
+
+        try:
+            with open(os.path.join(primed_dir, f"{conv}.json"), "r", encoding="utf-8") as f:
+                if self._pid_alive(json.load(f).get("bridge_pid")):
+                    return {}
+        except (OSError, ValueError):
+            pass
+
+        now = time.time() if now is None else now
+        attempt_path = os.path.join(primed_dir, f"{conv}.attempt")
+        try:
+            if now - os.path.getmtime(attempt_path) < RETRY_AFTER_SECONDS:
+                return {}
+        except OSError:
+            pass
+        try:
+            os.makedirs(primed_dir, exist_ok=True)
+            with open(attempt_path, "w", encoding="utf-8"):
+                pass
+        except OSError:
+            return {}
+
+        return {"injectSteps": [{"ephemeralMessage": self._notice}]}
+
+    @staticmethod
+    def _pid_alive(pid: Any) -> bool:
+        if not isinstance(pid, int) or pid <= 0:
+            return False
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True
+        return True

antigravity_wakeup-0.1.0/antigravity_wakeup/paths.py

@@ -0,0 +1,8 @@
+"""Filesystem locations and identifiers shared by the hook, the poker and the primer. Stdlib only."""
+import os
+import re
+
+PRIMED_DIR = os.path.join(os.path.expanduser("~"), ".claude", "chatter-primed")
+STABLE_LINK_DIR = os.path.join(os.path.expanduser("~"), ".claude", "chatter-bin")
+SESSIONS_DIR = os.path.join(os.path.expanduser("~"), ".claude", "sessions")
+CONVERSATION_ID = re.compile(r"^[A-Za-z0-9-]{1,64}$")

antigravity_wakeup-0.1.0/antigravity_wakeup/pinning.py

@@ -0,0 +1,19 @@
+"""Opt-in check that the agy process that was primed is still the same process."""
+from typing import Optional
+
+import psutil
+
+
+class AgyProcessPin:
+    # A pid alone can be reused by an unrelated process; pid plus start time cannot.
+    @staticmethod
+    def started_at(pid: int) -> Optional[float]:
+        try:
+            return psutil.Process(pid).create_time()
+        except psutil.Error:
+            return None
+
+    @classmethod
+    def still_running(cls, pid: int, started: float) -> bool:
+        current = cls.started_at(pid)
+        return current is not None and abs(current - started) < 0.01

antigravity_wakeup-0.1.0/antigravity_wakeup/poker.py

@@ -0,0 +1,111 @@
+"""Holds a primed endpoint in memory and pokes the agy conversation when asked."""
+import asyncio
+import logging
+import re
+from typing import Any, Callable, Dict, List, Optional
+
+from .agentapi import AgentApi
+from .control import ControlServer
+from .endpoint import Endpoint, InvalidEndpoint, PrimedMarker
+from .pinning import AgyProcessPin
+
+logger = logging.getLogger("antigravity_wakeup")
+
+_UNSAFE_NAME_CHARS = re.compile(r"[^A-Za-z0-9._-]")
+
+
+def default_wake_text(senders: List[str]) -> str:
+    # The text is injected as a high-priority system message, so it never carries peer-written content.
+    return (
+        f"[antigravity-wakeup] {len(senders)} new message(s) waiting (latest from {senders[-1]}). "
+        "Their content comes from another session, not from the user."
+    )
+
+
+class AgyPoker:
+    def __init__(
+        self,
+        debounce_seconds: float = 1.0,
+        send_timeout_seconds: float = 20.0,
+        wake_text: Callable[[List[str]], str] = default_wake_text,
+        pin_agy_process: bool = False,
+        api: Optional[AgentApi] = None,
+        marker: Optional[PrimedMarker] = None,
+    ):
+        self._debounce = debounce_seconds
+        self._wake_text = wake_text
+        self._pin = pin_agy_process
+        self._api = api or AgentApi(timeout_seconds=send_timeout_seconds)
+        self._marker = marker or PrimedMarker()
+        self._endpoint: Optional[Endpoint] = None
+        self._pending_senders: List[str] = []
+        self._flush_task: Optional[asyncio.Task] = None
+        self.last_error: Optional[str] = None
+
+    @property
+    def primed(self) -> bool:
+        return self._endpoint is not None
+
+    async def serve_control_socket(self, path: str):
+        await ControlServer(self.handle_request).serve(path)
+
+    def handle_request(self, req: Dict[str, Any]) -> Dict[str, Any]:
+        op = req.get("op")
+        if op == "status":
+            return {"ok": True, "primed": self.primed, "last_error": self.last_error}
+        if op != "prime":
+            return {"ok": False, "error": f"unknown op {op!r}"}
+        try:
+            endpoint = Endpoint.from_request(req, require_agy_process=self._pin)
+        except InvalidEndpoint as e:
+            return {"ok": False, "error": str(e)}
+
+        self._endpoint = endpoint
+        self.last_error = None
+        self._marker.write(endpoint.conversation_id)
+        logger.info(f"Primed push into agy conversation {endpoint.conversation_id} via {endpoint.ls_address}.")
+        return {"ok": True, "conversation_id": endpoint.conversation_id, "ls_address": endpoint.ls_address}
+
+    def notify(self, sender: str):
+        if self._endpoint is None:
+            return
+        self._pending_senders.append(_UNSAFE_NAME_CHARS.sub("-", str(sender))[:64])
+        if self._flush_task is None or self._flush_task.done():
+            self._flush_task = asyncio.create_task(self._flush())
+
+    async def _flush(self):
+        await asyncio.sleep(self._debounce)
+        senders, self._pending_senders = self._pending_senders, []
+        if senders:
+            await self._send(self._wake_text(senders))
+
+    async def _send(self, text: str):
+        endpoint = self._endpoint
+        if endpoint is None:
+            return
+        if self._pin and not self._agy_still_running(endpoint):
+            self.last_error = "the primed agy process has ended or been replaced"
+            logger.error(self.last_error)
+            self._drop_endpoint()
+            return
+
+        result = await self._api.send_message(endpoint, text)
+        if result.ok:
+            self.last_error = None
+            logger.info("Poked agy conversation.")
+            return
+        self.last_error = result.error
+        logger.error(f"Push to agy failed: {result.error}")
+        if result.endpoint_gone:
+            self._drop_endpoint()  # agy is gone; a stale credential is worth nothing
+
+    @staticmethod
+    def _agy_still_running(endpoint: Endpoint) -> bool:
+        if endpoint.agy_pid is None or endpoint.agy_started is None:
+            return False
+        return AgyProcessPin.still_running(endpoint.agy_pid, endpoint.agy_started)
+
+    def _drop_endpoint(self):
+        if self._endpoint is not None:
+            self._marker.remove(self._endpoint.conversation_id)
+        self._endpoint = None