agent-core-notify 0.8.2__tar.gz

agent_core_notify-0.8.2/.gitignore

@@ -0,0 +1,245 @@
+# Memory compiler runtime state
+memory-compiler/daily/
+memory-compiler/reports/
+memory-compiler/scripts/state.json
+memory-compiler/scripts/last-flush.json
+memory-compiler/scripts/flush.log
+memory-compiler/scripts/compile.log
+memory-compiler/scripts/session-flush-*.md
+memory-compiler/scripts/flush-context-*.md
+
+# Handoff writer state (placed alongside handoff files)
+**/handoff-state.json
+
+# Git worktrees (superpowers / parallel feature work)
+.worktrees/
+# Native (harness) worktrees
+.claude/worktrees/
+
+# Superpowers brainstorm mockups / scratch
+.superpowers/
+
+# Agent-core runtime state (handoffs, bus.sqlite, transcripts, etc.)
+.agent-core/
+
+# Local scratch / smoke-test artifacts
+.tmp/
+
+# Claude Code per-machine local overrides
+.claude/settings.local.json
+.claude/*.lock
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+.gstack/
+
+# macOS Finder metadata (occasionally sneaks in via vendored sources)
+.DS_Store
+
+# Operational docs that must not live in source control
+pepper-vault-plan.txt

agent_core_notify-0.8.2/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.8.1](https://github.com/jeffrichley/agent_core/compare/v0.8.0...agent-core-notify-v0.8.1) (2026-07-22)
+
+
+### Bug Fixes
+
+* republish package family to complete rate-limited first publish ([#477](https://github.com/jeffrichley/agent_core/issues/477)) ([32977ac](https://github.com/jeffrichley/agent_core/commit/32977ac78da4a15553329bb4e1fdaa9e894834ad))
+
+## [0.8.0](https://github.com/jeffrichley/agent_core/compare/v0.7.0...agent-core-notify-v0.8.0) (2026-07-21)
+
+
+### Features
+
+* **hatchery:** ungendered templates + .mcp.json generation ([#81](https://github.com/jeffrichley/agent_core/issues/81)/[#82](https://github.com/jeffrichley/agent_core/issues/82)) ([#357](https://github.com/jeffrichley/agent_core/issues/357)) ([f48762d](https://github.com/jeffrichley/agent_core/commit/f48762df78eb12cfa9524e9b5a277741534ea8a7)), closes [#311](https://github.com/jeffrichley/agent_core/issues/311)
+* **release:** configure release-please for 12-package synchronized version train ([#428](https://github.com/jeffrichley/agent_core/issues/428)) ([c1b4097](https://github.com/jeffrichley/agent_core/commit/c1b409765c61d09a6657b0e8b5e43a27cb235b3e))
+
+## Changelog
+
+All notable changes to `agent-core-notify` are documented in this file. The
+format is generated by towncrier from fragments in `changelog.d/` at release
+time.
+
+<!-- towncrier release notes start -->

agent_core_notify-0.8.2/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: agent-core-notify
+Version: 0.8.2
+Summary: Desktop notification MCP server for agent-core agents
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: desktop-notifier>=5.0
+Requires-Dist: mcp>=1.9.0

agent_core_notify-0.8.2/VERSION

@@ -0,0 +1 @@
+0.8.1

agent_core_notify-0.8.2/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "agent-core-notify"
+dynamic = ["version"]
+description = "Desktop notification MCP server for agent-core agents"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "desktop-notifier>=5.0",
+    "mcp>=1.9.0",
+]
+
+[project.scripts]
+agent-core-notify = "agent_core_notify.mcp_server:run"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_core_notify"]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]

agent_core_notify-0.8.2/src/agent_core_notify/__init__.py

@@ -0,0 +1 @@
+"""agent_core_notify — Desktop notification MCP server."""

agent_core_notify-0.8.2/src/agent_core_notify/mcp_server.py

@@ -0,0 +1,314 @@
+"""Desktop notification MCP server.
+
+Provides toast notification tools that agents can call during a session.
+Stays alive for the session lifetime, enabling interactive notifications
+with reply fields and action buttons.
+
+Tools:
+    send_notification: Fire-and-forget toast notification.
+    ask_user: Send notification with reply field, return immediately with ID.
+    notify_with_buttons: Send notification with action buttons, return immediately with ID.
+    get_reply: Check if the user has replied to a notification.
+    clear_notifications: Clear all active notifications.
+
+Launch:
+    python -m agent_core_notify.mcp_server   # stdio transport (for .mcp.json)
+
+Register in .mcp.json:
+    {
+        "mcpServers": {
+            "notify": {
+                "command": "uv",
+                "args": [
+                    "run",
+                    "--no-sync",
+                    "--directory",
+                    "E:/workspaces/ai/agents/agent_core",
+                    "python",
+                    "-m",
+                    "agent_core_notify.mcp_server"
+                ]
+            }
+        }
+    }
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+import uuid
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from desktop_notifier import (
+    Attachment,
+    Button,
+    DesktopNotifier,
+    Icon,
+    ReplyField,
+    Sound,
+    Urgency,
+)
+
+# Logging to stderr — stdout is reserved for MCP stdio transport
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger("agent_core_notify")
+
+mcp = FastMCP("agent-core-notify")
+
+# Shared notifier instance
+_notifier = DesktopNotifier(app_name="Agent Core")
+
+# Store for pending interactive notifications (id -> reply/button result)
+_pending: dict[str, dict] = {}
+# Reference to the running event loop for thread-safe callback signaling
+_loop: asyncio.AbstractEventLoop | None = None
+
+URGENCY_MAP = {
+    "low": Urgency.Low,
+    "normal": Urgency.Normal,
+    "critical": Urgency.Critical,
+}
+
+
+def _make_sound(sound: str | None) -> Sound | None:
+    """Create a Sound object — auto-detects file path vs system sound name."""
+    if not sound:
+        return None
+    if Path(sound).suffix in (".wav", ".mp3", ".ogg", ".flac", ".aac", ".wma"):
+        return Sound(path=Path(sound))
+    return Sound(name=sound)
+
+
+def _resolve_reply(notification_id: str, reply: str) -> None:
+    """Thread-safe callback for reply fields."""
+    if notification_id in _pending:
+        _pending[notification_id]["reply"] = reply
+        _pending[notification_id]["status"] = "replied"
+        logger.info("Reply received for %s: %s", notification_id, reply)
+
+
+def _resolve_button(notification_id: str, button: str) -> None:
+    """Thread-safe callback for button presses."""
+    if notification_id in _pending:
+        _pending[notification_id]["reply"] = button
+        _pending[notification_id]["status"] = "clicked"
+        logger.info("Button clicked for %s: %s", notification_id, button)
+
+
+def _resolve_dismissed(notification_id: str) -> None:
+    """Thread-safe callback for dismissed notifications."""
+    if notification_id in _pending:
+        _pending[notification_id]["reply"] = ""
+        _pending[notification_id]["status"] = "dismissed"
+        logger.info("Notification dismissed: %s", notification_id)
+
+
+@mcp.tool()
+async def send_notification(
+    title: str,
+    message: str,
+    urgency: str = "normal",
+    icon: str | None = None,
+    attachment: str | None = None,
+    sound: str | None = None,
+    thread: str | None = None,
+) -> dict[str, str]:
+    """Send a desktop toast notification (fire-and-forget).
+
+    Args:
+        title: Notification title (e.g., agent name).
+        message: Notification body text.
+        urgency: "low", "normal", or "critical". Default: "normal".
+        icon: Path to an icon image file. Optional.
+        attachment: Path to a file to attach. Optional.
+        sound: Name of a system sound, or path to a sound file. Optional.
+        thread: Thread ID to group related notifications. Optional.
+    """
+    urg = URGENCY_MAP.get(urgency, Urgency.Normal)
+    icon_obj = Icon(path=Path(icon)) if icon else None
+    attach_obj = Attachment(path=Path(attachment)) if attachment else None
+    sound_obj = _make_sound(sound)
+
+    await _notifier.send(
+        title=title,
+        message=message,
+        urgency=urg,
+        icon=icon_obj,
+        attachment=attach_obj,
+        sound=sound_obj,
+        thread=thread,
+    )
+
+    logger.info("Notification sent: %s — %s", title, message)
+    return {"status": "sent", "title": title, "message": message}
+
+
+@mcp.tool()
+async def ask_user(
+    title: str,
+    message: str,
+    reply_button_title: str = "Reply",
+    urgency: str = "normal",
+    icon: str | None = None,
+    sound: str | None = None,
+    thread: str | None = None,
+) -> dict[str, str]:
+    """Send a notification with a reply field. Returns immediately with a notification_id.
+
+    Use get_reply(notification_id) to check if the user has replied.
+    This does NOT block — the agent can continue working while waiting.
+
+    Args:
+        title: Notification title.
+        message: The question or prompt to show.
+        reply_button_title: Label for the reply button. Default: "Reply".
+        urgency: "low", "normal", or "critical". Default: "normal".
+        icon: Path to an icon image file. Optional.
+        sound: Name of a system sound, or path to a sound file. Optional.
+        thread: Thread ID to group related notifications. Optional.
+    """
+    notification_id = str(uuid.uuid4())[:8]
+    _pending[notification_id] = {"status": "pending", "reply": ""}
+
+    urg = URGENCY_MAP.get(urgency, Urgency.Normal)
+    icon_obj = Icon(path=Path(icon)) if icon else None
+    sound_obj = _make_sound(sound)
+
+    await _notifier.send(
+        title=title,
+        message=message,
+        urgency=urg,
+        icon=icon_obj,
+        sound=sound_obj,
+        thread=thread,
+        reply_field=ReplyField(
+            title="Type your reply",
+            button_title=reply_button_title,
+            on_replied=lambda text: _resolve_reply(notification_id, text),
+        ),
+        on_dismissed=lambda: _resolve_dismissed(notification_id),
+    )
+
+    logger.info("Ask sent [%s]: %s — %s", notification_id, title, message)
+    return {"status": "pending", "notification_id": notification_id}
+
+
+@mcp.tool()
+async def notify_with_buttons(
+    title: str,
+    message: str,
+    buttons: list[str],
+    urgency: str = "normal",
+    icon: str | None = None,
+    sound: str | None = None,
+    thread: str | None = None,
+) -> dict[str, str]:
+    """Send a notification with action buttons. Returns immediately with a notification_id.
+
+    Use get_reply(notification_id) to check which button the user clicked.
+    This does NOT block — the agent can continue working while waiting.
+
+    Args:
+        title: Notification title.
+        message: Notification body text.
+        buttons: List of button labels (e.g., ["Approve", "Deny", "Snooze"]).
+        urgency: "low", "normal", or "critical". Default: "normal".
+        icon: Path to an icon image file. Optional.
+        sound: Name of a system sound, or path to a sound file. Optional.
+        thread: Thread ID to group related notifications. Optional.
+    """
+    notification_id = str(uuid.uuid4())[:8]
+    _pending[notification_id] = {"status": "pending", "reply": ""}
+
+    button_objs = [
+        Button(
+            title=label,
+            on_pressed=lambda lbl=label: _resolve_button(notification_id, lbl),
+        )
+        for label in buttons
+    ]
+
+    urg = URGENCY_MAP.get(urgency, Urgency.Normal)
+    icon_obj = Icon(path=Path(icon)) if icon else None
+    sound_obj = _make_sound(sound)
+
+    await _notifier.send(
+        title=title,
+        message=message,
+        urgency=urg,
+        icon=icon_obj,
+        sound=sound_obj,
+        thread=thread,
+        buttons=button_objs,
+        on_dismissed=lambda: _resolve_dismissed(notification_id),
+    )
+
+    logger.info("Buttons sent [%s]: %s — %s [%s]", notification_id, title, message, ", ".join(buttons))
+    return {"status": "pending", "notification_id": notification_id}
+
+
+@mcp.tool()
+async def get_reply(notification_id: str) -> dict[str, str]:
+    """Check if the user has replied to or interacted with a notification.
+
+    Returns the current status:
+    - {"status": "pending"} — user hasn't responded yet
+    - {"status": "replied", "reply": "user's text"} — user typed a reply
+    - {"status": "clicked", "button": "Approve"} — user clicked a button
+    - {"status": "dismissed"} — user dismissed the notification
+    - {"status": "not_found"} — unknown notification_id
+
+    Args:
+        notification_id: The ID returned by ask_user or notify_with_buttons.
+    """
+    if notification_id not in _pending:
+        return {"status": "not_found", "notification_id": notification_id}
+
+    entry = _pending[notification_id]
+    result = {"status": entry["status"], "notification_id": notification_id}
+
+    if entry["status"] == "replied":
+        result["reply"] = entry["reply"]
+        del _pending[notification_id]
+    elif entry["status"] == "clicked":
+        result["button"] = entry["reply"]
+        del _pending[notification_id]
+    elif entry["status"] == "dismissed":
+        del _pending[notification_id]
+
+    return result
+
+
+@mcp.tool()
+async def clear_notifications() -> dict[str, str]:
+    """Clear all active notifications sent by this server."""
+    await _notifier.clear_all()
+    _pending.clear()
+    logger.info("All notifications cleared")
+    return {"status": "cleared"}
+
+
+def run() -> None:
+    """Launch the MCP server on stdio transport."""
+    try:
+        mcp.run(transport="stdio")
+    finally:
+        # desktop-notifier's WinRT backend keeps non-daemon threads alive,
+        # which blocks normal interpreter shutdown on Windows. Force-exit
+        # so the agent-core-notify entry-point .exe isn't held open after
+        # stdio closes (otherwise `uv sync` can't replace it on the next run).
+        import os
+        os._exit(0)
+
+
+if __name__ == "__main__":
+    run()

agent_core_notify-0.8.2/towncrier.toml

@@ -0,0 +1,38 @@
+[tool.towncrier]
+name = "agent-core-notify"
+package = "agent_core_notify"
+package_dir = "src"
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+title_format = "## {version} ({project_date})"
+issue_format = "[#{issue}](https://github.com/jeffrichley/agent_core/pull/{issue})"
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "security"
+name = "Security"
+showcontent = true