agent-notifiers 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,89 @@
1
+ """MCP server: lets Claude decide when/where to ping you, and listen for replies."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import time
6
+
7
+ try: # mcp >= 2.0 renamed FastMCP -> MCPServer
8
+ from mcp.server.mcpserver import MCPServer as FastMCP
9
+ except ImportError: # mcp 1.x
10
+ from mcp.server.fastmcp import FastMCP
11
+
12
+ from . import channels as ch
13
+ from .config import Settings
14
+ from .core import norm_priority, notify
15
+ from .inbox import poll_inbox, wait_for_reply
16
+
17
+ INSTRUCTIONS = """\
18
+ Use these tools to reach the user away from the screen.
19
+
20
+ - notify_me: call it ONCE when you finish a long task (more than a minute or two of work) or when you
21
+ are blocked and need the user. Message = what was done / what is needed, in 1-3 short lines, no secrets.
22
+ priority: low = FYI, normal = finished, high = needs attention soon, urgent = blocked or something broke
23
+ (high/urgent go to every configured channel).
24
+ - ask_me: use when you need a decision to continue. It sends the question and waits for the reply
25
+ (Telegram / ntfy inbox). If it times out, state your assumption, proceed safely, and notify_me.
26
+ - check_inbox: read messages the user sent while you were working.
27
+ Never send API keys, tokens, passwords or private file contents through these tools. Do not spam:
28
+ one ping per finished task, not one per step.
29
+ """
30
+
31
+ mcp = FastMCP("agent-notifier", instructions=INSTRUCTIONS)
32
+
33
+
34
+ @mcp.tool()
35
+ async def notify_me(
36
+ message: str, title: str = "Claude", priority: str = "normal", channels: list[str] | None = None
37
+ ) -> dict:
38
+ """Send the user a notification (Telegram / ntfy / Gmail / WhatsApp).
39
+
40
+ priority: low | normal | high | urgent. `channels` optionally forces specific channels.
41
+ """
42
+ return await asyncio.to_thread(notify, message, title, norm_priority(priority), channels)
43
+
44
+
45
+ @mcp.tool()
46
+ async def ask_me(question: str, timeout_seconds: int = 300, title: str = "Claude needs a decision") -> dict:
47
+ """Ask the user a question and wait for the reply (max 900s). Returns the reply text or a timeout."""
48
+ timeout = max(10, min(int(timeout_seconds), 900))
49
+ settings = Settings()
50
+ sent_at = time.time()
51
+ body = f"{question}\n\n(Reply to this message. Waiting up to {timeout // 60 or 1} min.)"
52
+ res = await asyncio.to_thread(notify, body, title, "high", None, settings)
53
+ if not res.get("sent"):
54
+ return {"answered": False, "error": "could not send question", "detail": res}
55
+ reply, earlier = await asyncio.to_thread(wait_for_reply, settings, timeout, sent_at)
56
+ out: dict = {"answered": reply is not None, "reply": reply["text"] if reply else None}
57
+ if reply:
58
+ out["via"] = reply["channel"]
59
+ if earlier:
60
+ out["earlier_messages"] = [m["text"] for m in earlier]
61
+ return out
62
+
63
+
64
+ @mcp.tool()
65
+ async def check_inbox(wait_seconds: int = 0) -> dict:
66
+ """Read new messages the user sent (Telegram replies / ntfy inbox topic)."""
67
+ msgs = await asyncio.to_thread(poll_inbox, None, max(0, min(int(wait_seconds), 30)), True)
68
+ return {"count": len(msgs), "messages": [{"via": m["channel"], "text": m["text"]} for m in msgs]}
69
+
70
+
71
+ @mcp.tool()
72
+ async def channel_status() -> dict:
73
+ """Show which channels are configured (never reveals secrets)."""
74
+ settings = Settings()
75
+ return {
76
+ "default_channels": settings.default_channels,
77
+ "channels": {
78
+ name: {"configured": c.configured(), "two_way": c.inbound, "needs": c.needs}
79
+ for name, c in ch.build(settings).items()
80
+ },
81
+ }
82
+
83
+
84
+ def main() -> None:
85
+ mcp.run()
86
+
87
+
88
+ if __name__ == "__main__":
89
+ main()
@@ -0,0 +1,64 @@
1
+ """Tiny JSON state store (inbox cursors, run start times, debounce)."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import os
6
+ import time
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from .config import HOME
11
+
12
+ STATE_FILE = HOME / "state.json"
13
+ RUNS_DIR = HOME / "runs"
14
+
15
+
16
+ def _ensure() -> None:
17
+ HOME.mkdir(parents=True, exist_ok=True)
18
+ try:
19
+ os.chmod(HOME, 0o700)
20
+ except OSError:
21
+ pass
22
+
23
+
24
+ def load() -> dict[str, Any]:
25
+ try:
26
+ return json.loads(STATE_FILE.read_text(encoding="utf-8"))
27
+ except (OSError, ValueError):
28
+ return {}
29
+
30
+
31
+ def save(data: dict[str, Any]) -> None:
32
+ _ensure()
33
+ tmp = STATE_FILE.with_suffix(".tmp")
34
+ tmp.write_text(json.dumps(data), encoding="utf-8")
35
+ tmp.replace(STATE_FILE)
36
+
37
+
38
+ def mark_run_start(session_id: str) -> None:
39
+ _ensure()
40
+ RUNS_DIR.mkdir(parents=True, exist_ok=True)
41
+ (RUNS_DIR / f"{_safe(session_id)}.json").write_text(
42
+ json.dumps({"start": time.time()}), encoding="utf-8"
43
+ )
44
+
45
+
46
+ def run_start(session_id: str) -> float | None:
47
+ try:
48
+ data = json.loads((RUNS_DIR / f"{_safe(session_id)}.json").read_text(encoding="utf-8"))
49
+ return float(data["start"])
50
+ except (OSError, ValueError, KeyError):
51
+ return None
52
+
53
+
54
+ def _safe(name: str) -> str:
55
+ return "".join(c for c in name if c.isalnum() or c in "-_")[:80] or "default"
56
+
57
+
58
+ def log(line: str) -> None:
59
+ _ensure()
60
+ try:
61
+ with open(HOME / "notify.log", "a", encoding="utf-8") as fh:
62
+ fh.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} {line}\n")
63
+ except OSError:
64
+ pass
@@ -0,0 +1,24 @@
1
+ """Keep background CLI discovery from flashing console windows on Windows.
2
+
3
+ Only use this for trusted, fixed local subprocesses. No shell is introduced.
4
+ """
5
+ from __future__ import annotations
6
+
7
+ import os
8
+ import subprocess
9
+
10
+
11
+ def hidden_kwargs(platform: str | None = None) -> dict:
12
+ """Return subprocess flags; portable on Linux/macOS and safe for Windows .cmd."""
13
+ if (os.name if platform is None else platform) != "nt":
14
+ return {}
15
+ flags = {"creationflags": getattr(subprocess, "CREATE_NO_WINDOW", 0x08000000)}
16
+ # CREATE_NO_WINDOW covers console executables; SW_HIDE also helps with
17
+ # .cmd/.bat launchers that would otherwise briefly steal focus.
18
+ startup_class = getattr(subprocess, "STARTUPINFO", None)
19
+ if startup_class is not None:
20
+ startup = startup_class()
21
+ startup.dwFlags |= getattr(subprocess, "STARTF_USESHOWWINDOW", 0x0001)
22
+ startup.wShowWindow = getattr(subprocess, "SW_HIDE", 0)
23
+ flags["startupinfo"] = startup
24
+ return flags
@@ -0,0 +1,25 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-notifiers
3
+ Version: 0.2.0
4
+ Summary: Agent Notifiers: approved AI agent runs, local companion and device pairing
5
+ Classifier: Programming Language :: Python :: 3
6
+ Classifier: Operating System :: OS Independent
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: mcp>=1.2
10
+ Requires-Dist: httpx>=0.27
11
+
12
+ # agent-notifiers (distribution candidate)
13
+
14
+ This is the proposed public Python distribution of the Agent Notifier desktop
15
+ companion. It uses the same `agent_notifier` importable module and supports both
16
+ `agent-notifiers` and legacy `agent-notifier` command names.
17
+
18
+ **Not published and not reserved on PyPI.** Only install from reviewed artifacts
19
+ built by this repository's private CI, or install from the trusted source checkout
20
+ using `python -m pip install -e ./local`. Public package publication requires the
21
+ owner to confirm registry availability, provenance and release credentials.
22
+
23
+ The package must be built by `scripts/build_agent_notifiers_dist.py`, which
24
+ copies the current source into an isolated temporary directory rather than
25
+ changing the existing package installed on Windows.
@@ -0,0 +1,28 @@
1
+ agent_notifier/__init__.py,sha256=55hezHwn63SalgKRYEZRTlHIs_w5lk2gA5S0R-y3Vqg,85
2
+ agent_notifier/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
3
+ agent_notifier/adapter.py,sha256=N3_vJieA3JQDQ2CYjd-ToknxVZkYK0lLYgH0CEdtiSk,2748
4
+ agent_notifier/agents.py,sha256=XgnSGAyv25uAxj8_wb8nfBQaLEKaOqWHvHRf7g23oHY,3444
5
+ agent_notifier/autostart.py,sha256=nyDjdlkTrAEECqcsoJ-k9qZuCCM7idZ7VreHyhRZzzM,6050
6
+ agent_notifier/bridge.py,sha256=04ARblCFN7xGxxMJW5GouSbiff8-Vnm0JkJ7YRc2iVw,54618
7
+ agent_notifier/channels.py,sha256=IDMQgkz1NQYUDBkmYIrAgN6ekjE79KsHRDuwoYcc4w4,7086
8
+ agent_notifier/cli.py,sha256=jPlcH1TA2ycoqmkXWfzx4dSw_Rjn0ppunEDodSzIRuc,11056
9
+ agent_notifier/codex_models.py,sha256=bppDRZc5-QU4l4jLXv-eexNhEHLTYHcy6fRV17xqpDs,2210
10
+ agent_notifier/codex_workspace.py,sha256=uv6-8zhpnwYEe-V6_EoFxPagpoFxwpcKOOh7U4uWkZY,854
11
+ agent_notifier/companion.py,sha256=sCDl5CRbHbfycvKHF9bQk-DlLKOgsCqFWgHAHDpTCpE,15971
12
+ agent_notifier/config.py,sha256=Ci3MLO93JiXh3kfKCVFpcPvv-Y3YxeBV77dCadf2wl0,2166
13
+ agent_notifier/core.py,sha256=ML7Kc5PZMccM_xST9JddAgcprPK_MQ6Pi2_c2TSTBwA,3155
14
+ agent_notifier/device.py,sha256=doRlk-3_WvGZCxrwVMiLbJlArklFeA1Z7pHY9o7xJJY,4378
15
+ agent_notifier/hooks.py,sha256=Er6MlRdfKq6_RyOcnMlOgltp5mkwX0J9QOSGIK207Jo,4708
16
+ agent_notifier/inbox.py,sha256=AG_-foYFU6xhmUZqsI9pssaEXJ6JI241xORBQqACi4w,2190
17
+ agent_notifier/local_models.py,sha256=MWhnFUCIK5elKMKJuzR3xyeI1gvoXj_-F6wwgJdXpsM,2789
18
+ agent_notifier/recovery.py,sha256=ZdQq9_29hoGFbygpkpo9tuaiO_Zj_kHfQnTCqh4k39g,4059
19
+ agent_notifier/redact.py,sha256=x_46cARCeYDcJIbH5W86uiwjHM7if9b8MTX7Z5n6Mdo,1415
20
+ agent_notifier/runtime.py,sha256=2ii8aBnF7ogAqr10H6Ypn1ia_SCS9RhFCIJ1GDeKNYo,5081
21
+ agent_notifier/server.py,sha256=Dn6N9n_c8sXCXyBPPmohUAl3_ihOZnoZD8B66qmr2xE,3568
22
+ agent_notifier/state.py,sha256=8-urKLFYF3mEdv4jFEv-yl9FipNzhhNERNj8Vn82mn4,1582
23
+ agent_notifier/windows_process.py,sha256=g0ccplNW8ccS0hRKdllPGbVxJjMxtambzuinKU_vIGE,997
24
+ agent_notifiers-0.2.0.dist-info/METADATA,sha256=X1Zc5FkMuMOiTaJIVc1oQZWViDPp22pra98wJCj4wWs,1171
25
+ agent_notifiers-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
26
+ agent_notifiers-0.2.0.dist-info/entry_points.txt,sha256=32nOTjbPCgtK00OjeERsCjbqAwmrfuljybFL8RD1R7U,150
27
+ agent_notifiers-0.2.0.dist-info/top_level.txt,sha256=bOGCfUMYix5zfu2py3QD9vWo6ykIhrOmtxbgwKoG00M,15
28
+ agent_notifiers-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,4 @@
1
+ [console_scripts]
2
+ agent-notifier = agent_notifier.cli:main
3
+ agent-notifiers = agent_notifier.cli:main
4
+ agent-notifiers-mcp = agent_notifier.server:main
@@ -0,0 +1 @@
1
+ agent_notifier