agent-core-channel 0.9.0__tar.gz

agent_core_channel-0.9.0/.gitignore

@@ -0,0 +1,248 @@
+# 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/
+# ...but agent_core.venv is a SOURCE package, not a virtualenv — don't ignore it.
+!packages/core/src/agent_core/venv/
+!packages/core/src/agent_core/venv/**
+
+# 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_channel-0.9.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## [0.8.2](https://github.com/jeffrichley/agent_core/compare/v0.8.1...agent-core-channel-v0.8.2) (2026-08-03)
+
+
+### 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.1](https://github.com/jeffrichley/agent_core/compare/v0.8.0...agent-core-channel-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-channel-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))

agent_core_channel-0.9.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: agent-core-channel
+Version: 0.9.0
+Summary: Stdio MCP channel relay — bridges agent-core daemon notifications to Claude Code's wake mechanism.
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12

agent_core_channel-0.9.0/README.md

@@ -0,0 +1,60 @@
+# agent-core-channel
+
+`agent-core-channel` is a stdio MCP channel relay for Claude Code. It connects
+to the agent_core daemon's `/notify/<agent>` SSE stream and re-emits each event
+as `notifications/claude/channel` so Claude Code can wake autonomously when
+mail arrives on the bus.
+
+Claude Code still uses the daemon's HTTP MCP endpoint for tools such as
+`send`, `list_pending`, and `handle`. This package only relays notifications.
+
+## Claude Code Configuration
+
+On Windows in this workspace, use the workspace venv executable for now:
+
+```json
+{
+  "mcpServers": {
+    "agent-core": {
+      "type": "http",
+      "url": "http://localhost:8788/mcp/agent-testbot"
+    },
+    "agent-core-channel": {
+      "command": "E:\\workspaces\\ai\\agents\\agent_core\\.venv\\Scripts\\agent-core-channel.exe",
+      "args": ["--agent", "agent-testbot"]
+    }
+  }
+}
+```
+
+Launch Claude Code with the development channel enabled:
+
+```powershell
+claude --dangerously-load-development-channels server:agent-core-channel
+```
+
+## Windows Development Caveat
+
+As of the 2026-04-30 live validation, `uv tool install --from
+packages/agent-core-channel agent-core-channel` is not reliable on Windows in
+this workspace. The installed tool environment includes `pywin32` wheels, but
+the post-install step that stages `_win32sysloader.pyd` does not run, and the
+MCP SDK's Windows utility import can fail at startup.
+
+For non-Windows installs, or once the Windows packaging issue is fixed, a
+PATH-resolved binary is the intended shape:
+
+```json
+{
+  "mcpServers": {
+    "agent-core-channel": {
+      "command": "agent-core-channel",
+      "args": ["--agent", "agent-testbot"]
+    }
+  }
+}
+```
+
+Do not switch the testbot config back to a PATH-resolved `uv tool install`
+binary until the `pywin32` packaging issue is fixed or the install path moves
+to a wrapper that runs the required post-install setup.

agent_core_channel-0.9.0/VERSION

@@ -0,0 +1 @@
+0.8.2

agent_core_channel-0.9.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "agent-core-channel"
+dynamic = ["version"]
+description = "Stdio MCP channel relay — bridges agent-core daemon notifications to Claude Code's wake mechanism."
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.0",
+    "anyio>=4.0",
+    "httpx>=0.27",
+    "typer>=0.12",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+agent-core-channel = "agent_core_channel.__main__:app"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_core_channel"]
+
+[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_channel-0.9.0/src/agent_core_channel/__init__.py

@@ -0,0 +1 @@
+"""agent-core-channel — stdio MCP relay for the agent-core daemon."""

agent_core_channel-0.9.0/src/agent_core_channel/__main__.py

@@ -0,0 +1,95 @@
+"""Typer CLI entry point for agent-core-channel.
+
+Parses --agent, --daemon-url, and the inline-content config flags
+(issue #70), resolves layered RelayConfig (CLI > env > YAML > defaults),
+then hands off to run_relay().
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from types import SimpleNamespace
+
+import anyio
+import typer
+
+app = typer.Typer(add_completion=False)
+
+_DEFAULT_CONFIG_PATH = Path.home() / ".agent-core" / "agent_core.yaml"
+_CONFIG_PATH_OPTION = typer.Option(
+    _DEFAULT_CONFIG_PATH,
+    "--config-path",
+    help="Path to agent_core.yaml (for the channel_relay block).",
+)
+_INLINE_MODE_OPTION = typer.Option(
+    None,
+    "--inline-mode",
+    help="Override channel_relay.inline_mode (full|preview|disabled).",
+)
+_INLINE_MAX_ENVELOPES_OPTION = typer.Option(
+    None,
+    "--inline-max-envelopes",
+    help="Override channel_relay.max_envelopes.",
+)
+_INLINE_MAX_BYTES_OPTION = typer.Option(
+    None,
+    "--inline-max-bytes",
+    help="Override channel_relay.max_bytes.",
+)
+_INLINE_PER_ENVELOPE_BYTES_OPTION = typer.Option(
+    None,
+    "--inline-per-envelope-bytes",
+    help="Override channel_relay.per_envelope_bytes.",
+)
+
+
+@app.command()
+def main(
+    agent: str = typer.Option(..., "--agent", help="Agent name on the bus."),
+    daemon_url: str = typer.Option(
+        "http://127.0.0.1:8788",
+        "--daemon-url",
+        help="agent-core daemon URL (default: http://127.0.0.1:8788).",
+    ),
+    config_path: Path = _CONFIG_PATH_OPTION,
+    inline_mode: str | None = _INLINE_MODE_OPTION,
+    inline_max_envelopes: int | None = _INLINE_MAX_ENVELOPES_OPTION,
+    inline_max_bytes: int | None = _INLINE_MAX_BYTES_OPTION,
+    inline_per_envelope_bytes: int | None = _INLINE_PER_ENVELOPE_BYTES_OPTION,
+) -> None:
+    """Run the agent-core stdio channel relay."""
+    from agent_core.plugins.manager import create_plugin_manager, get_envelope_renderers
+    from agent_core_channel.config import load_config
+    from agent_core_channel.rendering import set_plugin_renderers
+    from agent_core_channel.stdio_server import run_relay
+
+    # Wire plugin-registered envelope renderers into the rendering dispatch
+    # table. agent_core PR #124 added the capability + dispatch but deferred
+    # the bootstrap wiring; without this call, plugin renderers like
+    # pepper-roots' `Desire` renderer never load and dispatch falls back to
+    # JSON. Caught by Pepper's behavioral round-trip 2026-05-25.
+    pm = create_plugin_manager()
+    set_plugin_renderers(get_envelope_renderers(pm))
+
+    cli_args = SimpleNamespace(
+        inline_mode=inline_mode,
+        inline_max_envelopes=inline_max_envelopes,
+        inline_max_bytes=inline_max_bytes,
+        inline_per_envelope_bytes=inline_per_envelope_bytes,
+    )
+    config = load_config(
+        agent=agent,
+        config_path=config_path,
+        cli_args=cli_args,
+        env=os.environ,
+    )
+
+    async def _run() -> None:
+        await run_relay(agent, daemon_url, config=config)
+
+    anyio.run(_run)
+
+
+if __name__ == "__main__":
+    app()

agent_core_channel-0.9.0/src/agent_core_channel/bus_client.py

@@ -0,0 +1,80 @@
+"""Issue #70: persistent MCP client connection from the relay to the bus.
+
+The relay calls consume(auto_ack=False, batch_window_seconds=N) on every
+wake to fetch the queue snapshot. This client wraps fastmcp.Client with
+the relay-specific contract (no ack, parameter shape).
+
+Connection lifecycle: opened on relay startup, kept alive for the relay's
+lifetime. Reconnects on connection loss are handled by fastmcp.Client's
+underlying transport — when call_tool raises a transport error, the
+caller (stdio_server) catches and falls back to the bare-wake shape for
+that wake. Subsequent wakes get a fresh attempt.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Self
+
+from fastmcp import Client
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+class BusClient:
+    """Persistent MCP client to the bus daemon's per-agent endpoint.
+
+    Two construction modes:
+
+    - ``BusClient(daemon_url, agent)`` — production: connects to
+      ``{daemon_url}/mcp/{agent}`` over HTTP.
+    - ``BusClient.from_in_process(fastmcp_server)`` — tests: connects
+      directly to a FastMCP server instance, no HTTP transport.
+
+    Use as an async context manager. ``consume_no_ack`` is the single
+    operation the relay needs; further tools (peek, etc.) can be added
+    here as the relay grows.
+    """
+
+    # Typed as Any to accommodate the two Client transport variants:
+    # Client[StreamableHttpTransport] (HTTP mode) and
+    # Client[FastMCPTransport] (in-process mode). Both share the same
+    # call_tool / __aenter__ / __aexit__ interface.
+    _client: Any
+
+    def __init__(self, daemon_url: str, agent: str) -> None:
+        url = f"{daemon_url.rstrip('/')}/mcp/{agent}"
+        self._client = Client(url)
+
+    @classmethod
+    def from_in_process(cls, server: FastMCP) -> Self:
+        instance = cls.__new__(cls)
+        instance._client = Client(server)
+        return instance
+
+    async def __aenter__(self) -> Self:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: Any,
+    ) -> None:
+        await self._client.__aexit__(exc_type, exc, tb)
+
+    async def consume_no_ack(self, *, batch_window_seconds: int = 30) -> dict:
+        """Fetch the queue snapshot without acking any envelopes.
+
+        Returns the consume() response shape:
+        ``{"meta": {...}, "items": [...]}``.
+        """
+        result = await self._client.call_tool(
+            "consume",
+            {
+                "auto_ack": False,
+                "batch_window_seconds": batch_window_seconds,
+            },
+        )
+        return result.data

agent_core_channel-0.9.0/src/agent_core_channel/config.py

@@ -0,0 +1,118 @@
+"""Issue #70: relay configuration with layered precedence.
+
+Order of precedence (highest first):
+    1. CLI flag (--inline-mode, etc.)
+    2. Env var (AGENT_CORE_CHANNEL_INLINE_MODE, etc.)
+    3. YAML config (agent_core.yaml endpoints[name=<agent>].params.channel_relay)
+    4. Hardcoded defaults
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+
+
+@dataclass(frozen=True)
+class RelayConfig:
+    inline_mode: Literal["full", "preview", "disabled"] = "full"
+    max_envelopes: int = 5
+    max_bytes: int = 8192
+    per_envelope_bytes: int = 4096
+
+
+_ENV_PREFIX = "AGENT_CORE_CHANNEL_"
+_VALID_MODES = ("full", "preview", "disabled")
+
+
+def _coerce_mode(value: Any) -> Literal["full", "preview", "disabled"] | None:
+    if value is None:
+        return None
+    s = str(value).strip().lower()
+    if s in _VALID_MODES:
+        return s  # type: ignore[return-value]
+    return None
+
+
+def _coerce_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _yaml_layer(path: Path, agent: str) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError:
+        return {}
+    endpoints = data.get("endpoints", []) if isinstance(data, dict) else []
+    for ep in endpoints:
+        if not isinstance(ep, dict):
+            continue
+        if ep.get("name") != agent:
+            continue
+        params = ep.get("params", {}) or {}
+        block = params.get("channel_relay") if isinstance(params, dict) else None
+        if isinstance(block, dict):
+            return block
+    return {}
+
+
+def _env_layer(env: Mapping[str, str]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    if (v := env.get(f"{_ENV_PREFIX}INLINE_MODE")) is not None:
+        out["inline_mode"] = v
+    if (v := env.get(f"{_ENV_PREFIX}INLINE_MAX_ENVELOPES")) is not None:
+        out["max_envelopes"] = v
+    if (v := env.get(f"{_ENV_PREFIX}INLINE_MAX_BYTES")) is not None:
+        out["max_bytes"] = v
+    if (v := env.get(f"{_ENV_PREFIX}INLINE_PER_ENVELOPE_BYTES")) is not None:
+        out["per_envelope_bytes"] = v
+    return out
+
+
+def _cli_layer(args: Any) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    if getattr(args, "inline_mode", None) is not None:
+        out["inline_mode"] = args.inline_mode
+    if getattr(args, "inline_max_envelopes", None) is not None:
+        out["max_envelopes"] = args.inline_max_envelopes
+    if getattr(args, "inline_max_bytes", None) is not None:
+        out["max_bytes"] = args.inline_max_bytes
+    if getattr(args, "inline_per_envelope_bytes", None) is not None:
+        out["per_envelope_bytes"] = args.inline_per_envelope_bytes
+    return out
+
+
+def load_config(
+    *,
+    agent: str,
+    config_path: Path,
+    cli_args: Any,
+    env: Mapping[str, str],
+) -> RelayConfig:
+    """Resolve RelayConfig with precedence: CLI > env > YAML > defaults."""
+    config = RelayConfig()
+
+    layers = [_yaml_layer(config_path, agent), _env_layer(env), _cli_layer(cli_args)]
+
+    for layer in layers:
+        if (mode := _coerce_mode(layer.get("inline_mode"))) is not None:
+            config = replace(config, inline_mode=mode)
+        if (n := _coerce_int(layer.get("max_envelopes"))) is not None:
+            config = replace(config, max_envelopes=n)
+        if (n := _coerce_int(layer.get("max_bytes"))) is not None:
+            config = replace(config, max_bytes=n)
+        if (n := _coerce_int(layer.get("per_envelope_bytes"))) is not None:
+            config = replace(config, per_envelope_bytes=n)
+
+    return config