agentirc-cli 9.6.2__tar.gz → 9.7.0__tar.gz

agentirc_cli-9.7.0/.devague/current

@@ -0,0 +1 @@
+agentirc-9-7-0-ships-an-embedded-bot-framework-bot

agentirc_cli-9.7.0/.devague/current_plan

@@ -0,0 +1 @@
+agentirc-9-7-0-ships-an-embedded-bot-framework-bot

agentirc_cli-9.7.0/.devague/frames/agentirc-9-7-0-ships-an-embedded-bot-framework-bot.json

@@ -0,0 +1,211 @@
+{
+  "slug": "agentirc-9-7-0-ships-an-embedded-bot-framework-bot",
+  "title": "agentirc 9.7.0 ships an embedded bot framework: BotManager + Bot + filter DSL + template engine + YAML bot config live in agentirc/bots/, tested here, so culture can replace its in-tree culture/bots/* with thin forwards in a single cutover PR with no functionality gap",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-06-12T11:19:28Z",
+  "updated": "2026-06-12T11:27:23Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "agentirc 9.7.0 ships an embedded bot framework: BotManager + Bot + filter DSL + template engine + YAML bot config live in agentirc/bots/, tested here, so culture can replace its in-tree culture/bots/* with thin forwards in a single cutover PR with no functionality gap",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "agentirc-cli 9.7.0 is published to PyPI with the bot framework importable, and culture's cutover PR replaces culture/bots/* with forwards while keeping its suite green",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "culture (the immediate consumer wiring its IRCd to install BotManager + forwarding culture bot CLI verbs) and any standalone agentirc embedder wanting deterministic YAML chatops bots inside their IRCd",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "culture's cutover PR consumes the published agentirc API (installs BotManager + forwards CLI) without reimplementing bot logic",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "the bot framework lives only in culture/bots/* (~1340 lines incl config.py); agentirc ships only no-op BotManager/http_listener stubs in _internal/bots/; culture cannot slim its front door because deleting bots would lose functionality",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "the _internal/bots stubs and culture/bots/* line counts are verifiable in the two repos at cutover time",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "after_state",
+      "text": "manager + Bot + filter_dsl + template_engine + config (YAML BotConfig) live in agentirc, are unit-tested here (filter DSL + template engine edge cases especially), and a documented public API lets an embedder install a BotManager onto a running IRCd and register YAML-spec'd bots",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "docs/api-stability.md documents the agentirc.bots install/register API with a worked example",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "the bot brain is already bound to agentirc protocol types (filter DSL evaluates Event/EventType; bot host subclasses agentirc.virtual_client.VirtualClient) \u2014 bots have no coherent life without an IRCd, so the framework belongs here, not in culture or a third package",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "filter_dsl.evaluate runs against real agentirc Event objects in a test, and the bot host resolves agentirc.virtual_client.VirtualClient as its base",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "NOT in scope: porting culture's system bots (culture/bots/system/*), any LLM/agent-backend bot harness (forbidden by the dependency boundary), and renaming on-disk artifacts (BOTS_DIR stays ~/.culture/bots for culture continuity)",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "no file under culture/bots/system/ is vendored, no backend SDK is added to pyproject deps, and BOTS_DIR default still resolves under ~/.culture/bots",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "pip install agentirc-cli==9.7.0 in a clean venv imports the bot framework; pytest covers filter DSL + template engine + manager lifecycle; culture's cutover PR replaces culture/bots/* with re-export shims and its test suite stays green",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "a clean-venv install test imports agentirc.bots and the DSL/template/lifecycle tests run green in agentirc CI",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "the real BotManager must satisfy the existing _internal/bots stub contract (__init__(server), async load_bots, load_system_bots, get_bot(nick), async on_event(event), async stop_all) because IRCd.start() already calls these methods",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "an IRCd booted in-process with a BotManager installed loads a YAML bot, dispatches a matching Event to it, and the bot replies \u2014 exercised by a test",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "vendored via cite-don't-copy: each moved file gets a [tool.citation] entry (quote/paraphrase/synthesize) with source URL + sha256; culture.bots.* imports rewrite to agentirc.bots.*; bot.py's culture.constants.EVENT_TYPE_RE rewrites to agentirc._internal.constants",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "cite check passes after the move and the new [tool.citation] entries resolve against real culture source SHAs",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "no imports back into culture: git grep '^(from|import) culture' over agentirc/ must stay empty after the move",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "CI's git grep portability check returns nothing for 'from culture'/'import culture' across agentirc/ and tests/",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "decision",
+      "text": "version bump is minor (9.7.0): the move is additive \u2014 a new public bot subsystem and CLI verbs, no breaking change to the five existing public modules",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "decision",
+      "text": "Webhook: port http_listener.py too \u2014 add aiohttp + opentelemetry-instrumentation-aiohttp-server deps, reversing the 9.5.0 deferral; bots ship with full webhook-ingress parity",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "decision",
+      "text": "Placement: agentirc/bots/ is a PUBLIC, semver-tracked subsystem (6th public surface); embedders import agentirc.bots.BotManager / Bot; _internal/bots stubs become re-export shims or are removed; public API table in CLAUDE.md + docs/api-stability.md gains an agentirc.bots row",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "decision",
+      "text": "CLI: ship 'agentirc bot create/start/stop/list/inspect/archive/unarchive' verbs in 9.7.0, ported from culture/cli/bot.py, so culture bot can become a thin forward to agentirc.cli.dispatch",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": []
+}

agentirc_cli-9.7.0/.devague/plans/agentirc-9-7-0-ships-an-embedded-bot-framework-bot.json

@@ -0,0 +1,318 @@
+{
+  "slug": "agentirc-9-7-0-ships-an-embedded-bot-framework-bot",
+  "title": "agentirc 9.7.0 ships an embedded bot framework: BotManager + Bot + filter DSL + template engine + YAML bot config live in agentirc/bots/, tested here, so culture can replace its in-tree culture/bots/* with thin forwards in a single cutover PR with no functionality gap",
+  "frame_slug": "agentirc-9-7-0-ships-an-embedded-bot-framework-bot",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-06-12T11:28:49Z",
+  "updated": "2026-06-12T11:32:38Z",
+  "targets": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "agentirc 9.7.0 ships an embedded bot framework: BotManager + Bot + filter DSL + template engine + YAML bot config live in agentirc/bots/, tested here, so culture can replace its in-tree culture/bots/* with thin forwards in a single cutover PR with no functionality gap"
+    },
+    {
+      "id": "h4",
+      "kind": "honesty",
+      "text": "agentirc-cli 9.7.0 is published to PyPI with the bot framework importable, and culture's cutover PR replaces culture/bots/* with forwards while keeping its suite green"
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "culture (the immediate consumer wiring its IRCd to install BotManager + forwarding culture bot CLI verbs) and any standalone agentirc embedder wanting deterministic YAML chatops bots inside their IRCd"
+    },
+    {
+      "id": "h5",
+      "kind": "honesty",
+      "text": "culture's cutover PR consumes the published agentirc API (installs BotManager + forwards CLI) without reimplementing bot logic"
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "the bot framework lives only in culture/bots/* (~1340 lines incl config.py); agentirc ships only no-op BotManager/http_listener stubs in _internal/bots/; culture cannot slim its front door because deleting bots would lose functionality"
+    },
+    {
+      "id": "h6",
+      "kind": "honesty",
+      "text": "the _internal/bots stubs and culture/bots/* line counts are verifiable in the two repos at cutover time"
+    },
+    {
+      "id": "c4",
+      "kind": "after_state",
+      "text": "manager + Bot + filter_dsl + template_engine + config (YAML BotConfig) live in agentirc, are unit-tested here (filter DSL + template engine edge cases especially), and a documented public API lets an embedder install a BotManager onto a running IRCd and register YAML-spec'd bots"
+    },
+    {
+      "id": "h7",
+      "kind": "honesty",
+      "text": "docs/api-stability.md documents the agentirc.bots install/register API with a worked example"
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "the bot brain is already bound to agentirc protocol types (filter DSL evaluates Event/EventType; bot host subclasses agentirc.virtual_client.VirtualClient) \u2014 bots have no coherent life without an IRCd, so the framework belongs here, not in culture or a third package"
+    },
+    {
+      "id": "h8",
+      "kind": "honesty",
+      "text": "filter_dsl.evaluate runs against real agentirc Event objects in a test, and the bot host resolves agentirc.virtual_client.VirtualClient as its base"
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "NOT in scope: porting culture's system bots (culture/bots/system/*), any LLM/agent-backend bot harness (forbidden by the dependency boundary), and renaming on-disk artifacts (BOTS_DIR stays ~/.culture/bots for culture continuity)"
+    },
+    {
+      "id": "h9",
+      "kind": "honesty",
+      "text": "no file under culture/bots/system/ is vendored, no backend SDK is added to pyproject deps, and BOTS_DIR default still resolves under ~/.culture/bots"
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "pip install agentirc-cli==9.7.0 in a clean venv imports the bot framework; pytest covers filter DSL + template engine + manager lifecycle; culture's cutover PR replaces culture/bots/* with re-export shims and its test suite stays green"
+    },
+    {
+      "id": "h10",
+      "kind": "honesty",
+      "text": "a clean-venv install test imports agentirc.bots and the DSL/template/lifecycle tests run green in agentirc CI"
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "the real BotManager must satisfy the existing _internal/bots stub contract (__init__(server), async load_bots, load_system_bots, get_bot(nick), async on_event(event), async stop_all) because IRCd.start() already calls these methods"
+    },
+    {
+      "id": "h1",
+      "kind": "honesty",
+      "text": "an IRCd booted in-process with a BotManager installed loads a YAML bot, dispatches a matching Event to it, and the bot replies \u2014 exercised by a test"
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "vendored via cite-don't-copy: each moved file gets a [tool.citation] entry (quote/paraphrase/synthesize) with source URL + sha256; culture.bots.* imports rewrite to agentirc.bots.*; bot.py's culture.constants.EVENT_TYPE_RE rewrites to agentirc._internal.constants"
+    },
+    {
+      "id": "h2",
+      "kind": "honesty",
+      "text": "cite check passes after the move and the new [tool.citation] entries resolve against real culture source SHAs"
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "no imports back into culture: git grep '^(from|import) culture' over agentirc/ must stay empty after the move"
+    },
+    {
+      "id": "h3",
+      "kind": "honesty",
+      "text": "CI's git grep portability check returns nothing for 'from culture'/'import culture' across agentirc/ and tests/"
+    }
+  ],
+  "tasks": [
+    {
+      "id": "t1",
+      "summary": "Vendor template_engine.py -> agentirc/bots/template_engine.py (verbatim quote)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "render_template + render_fallback produce identical output to culture's template_engine across a case table incl. missing-key fallback and json-value rendering"
+      ],
+      "deps": [],
+      "covers": [
+        "c4"
+      ]
+    },
+    {
+      "id": "t2",
+      "summary": "Vendor filter_dsl.py -> agentirc/bots/filter_dsl.py (verbatim quote)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "compile_filter parses every DSL operator; evaluate() returns correct bool against a constructed agentirc Event; malformed filter raises FilterParseError"
+      ],
+      "deps": [],
+      "covers": [
+        "c5",
+        "h8"
+      ]
+    },
+    {
+      "id": "t3",
+      "summary": "Vendor config.py BotConfig + BOTS_DIR -> agentirc/bots/config.py (paraphrase)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "BotConfig loads a valid YAML bot spec; BOTS_DIR default resolves under ~/.culture/bots; malformed YAML rejected without partial state"
+      ],
+      "deps": [],
+      "covers": [
+        "c4",
+        "h9"
+      ]
+    },
+    {
+      "id": "t4",
+      "summary": "Vendor bot-host virtual_client subclass -> agentirc/bots/virtual_client.py (paraphrase)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "agentirc.bots.virtual_client.VirtualClient subclasses agentirc.virtual_client.VirtualClient with no behavioral override; instantiation registers presence in a channel"
+      ],
+      "deps": [],
+      "covers": [
+        "c5",
+        "h8"
+      ]
+    },
+    {
+      "id": "t5",
+      "summary": "Packaging: pyproject deps (aiohttp + opentelemetry-instrumentation-aiohttp-server) + version 9.7.0 + all [tool.citation] entries + uv.lock + CHANGELOG",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "pyproject declares both aiohttp deps; agentirc version reads 9.7.0; uv.lock regenerated+staged; [tool.citation] has quote/paraphrase entries for all 8 vendored bot files; no backend SDK added"
+      ],
+      "deps": [],
+      "covers": [
+        "h4",
+        "c6",
+        "c9"
+      ]
+    },
+    {
+      "id": "t6",
+      "summary": "Vendor bot.py -> agentirc/bots/bot.py (paraphrase: import rewrites to agentirc.*)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "Bot loads from BotConfig, matches an Event via the filter DSL, renders a reply via the template engine; all imports resolve to agentirc.* with EVENT_TYPE_RE from agentirc._internal.constants; zero culture imports"
+      ],
+      "deps": [
+        "t1",
+        "t2",
+        "t3",
+        "t4"
+      ],
+      "covers": [
+        "c4",
+        "c5",
+        "c8",
+        "h8"
+      ]
+    },
+    {
+      "id": "t7",
+      "summary": "Vendor bot_manager.py -> agentirc/bots/bot_manager.py satisfying the _internal/bots stub contract",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "BotManager matches the stub contract (__init__(server), async load_bots/on_event/stop_all, load_system_bots, get_bot); an in-process IRCd with BotManager installed loads a YAML bot, dispatches a matching Event, and the bot replies \u2014 proven by a test"
+      ],
+      "deps": [
+        "t6"
+      ],
+      "covers": [
+        "c2",
+        "c3",
+        "c8",
+        "h1"
+      ]
+    },
+    {
+      "id": "t8",
+      "summary": "Vendor http_listener.py -> agentirc/bots/http_listener.py (aiohttp webhook ingress)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "http_listener binds an aiohttp webhook endpoint that dispatches an inbound webhook to a registered bot; a test posts a webhook and asserts the bot fired; otel aiohttp instrumentation wired"
+      ],
+      "deps": [
+        "t7"
+      ],
+      "covers": [
+        "c4"
+      ]
+    },
+    {
+      "id": "t9",
+      "summary": "Public surface: agentirc/bots/__init__.py exports + convert _internal/bots stubs to deprecation re-export shims",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "from agentirc.bots import BotManager, Bot works in a clean session; _internal/bots stubs re-export from agentirc.bots and emit DeprecationWarning"
+      ],
+      "deps": [
+        "t7"
+      ],
+      "covers": [
+        "c4",
+        "h5"
+      ]
+    },
+    {
+      "id": "t10",
+      "summary": "Port culture/cli/bot.py -> agentirc bot CLI verbs wired into agentirc.cli.dispatch",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "agentirc bot create/start/stop/list/inspect/archive/unarchive dispatch through agentirc.cli; agentirc bot list runs; flags match culture/cli/bot.py so culture bot can forward"
+      ],
+      "deps": [
+        "t7",
+        "t9"
+      ],
+      "covers": [
+        "c2",
+        "h5"
+      ]
+    },
+    {
+      "id": "t11",
+      "summary": "Docs: agentirc.bots in docs/api-stability.md (worked example) + CLAUDE.md public API table row",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "docs/api-stability.md gains an agentirc.bots row + worked example installing BotManager onto a running IRCd and registering a YAML bot; CLAUDE.md public API table lists agentirc.bots"
+      ],
+      "deps": [
+        "t9"
+      ],
+      "covers": [
+        "c4",
+        "h7"
+      ]
+    },
+    {
+      "id": "t12",
+      "summary": "Integration gate: cite check + full suite + clean-venv import + portability grep",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "cite check passes (entries resolve to real culture SHAs); pytest -n auto green; clean-venv install of built wheel imports agentirc.bots; CI grep finds no 'from culture'/'import culture' in agentirc/+tests/; no culture/bots/system/ file vendored"
+      ],
+      "deps": [
+        "t5",
+        "t6",
+        "t7",
+        "t8",
+        "t9",
+        "t10",
+        "t11"
+      ],
+      "covers": [
+        "c1",
+        "c3",
+        "c6",
+        "c7",
+        "c9",
+        "c10",
+        "h2",
+        "h3",
+        "h6",
+        "h9",
+        "h10"
+      ]
+    }
+  ],
+  "risks": []
+}

{agentirc_cli-9.6.2 → agentirc_cli-9.7.0}/.gitignore

@@ -222,3 +222,6 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# devague working state (not committed by default)
+.devague/reviews/

{agentirc_cli-9.6.2 → agentirc_cli-9.7.0}/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [9.7.0] - 2026-06-12
+
+Absorb culture's bot framework into the public `agentirc.bots` subsystem. Closes
+[#33](https://github.com/agentculture/agentirc/issues/33).
+
+### Added
+
+- **`agentirc.bots` public subsystem** — embeds culture's bot framework directly
+  into agentirc as a semver-tracked public API. Eight modules vendored from
+  `culture@df50942` via the cite-don't-copy pattern:
+  - `agentirc.bots.template_engine` — Jinja2-style template engine for bot
+    response rendering (quote from `culture/bots/template_engine.py`).
+  - `agentirc.bots.filter_dsl` — filter DSL for routing bot event subscriptions
+    (quote from `culture/bots/filter_dsl.py`).
+  - `agentirc.bots.config` — bot YAML configuration dataclasses (paraphrase of
+    `culture/bots/config.py` with import rewrites).
+  - `agentirc.bots.virtual_client` — in-process IRC client for bots to speak
+    into a hosted IRCd (paraphrase of `culture/bots/virtual_client.py`).
+  - `agentirc.bots.bot` — base `Bot` class with lifecycle hooks and event
+    dispatch (paraphrase of `culture/bots/bot.py`).
+  - `agentirc.bots.bot_manager` — `BotManager` that owns the bot lifecycle and
+    wires bots to the IRCd's event subscription stream (paraphrase of
+    `culture/bots/bot_manager.py`).
+  - `agentirc.bots.http_listener` — `HttpListener` webhook receiver that
+    converts HTTP POST payloads into IRC events (paraphrase of
+    `culture/bots/http_listener.py`; requires `aiohttp`).
+  - `agentirc.bots.cli` — `bot` subcommand for the `agentirc` CLI (paraphrase
+    of `culture/cli/bot.py`).
+- **New runtime dependencies**: `aiohttp>=3.9` (HTTP webhook listener) and
+  `opentelemetry-instrumentation-aiohttp-server>=0.43b0` (OTEL tracing for the
+  webhook server), consistent with the existing `>=1.22` otel pins.
+
 ## [9.6.2] - 2026-06-10
 
 Resync the vendored steward skills. Closes

{agentirc_cli-9.6.2 → agentirc_cli-9.7.0}/CLAUDE.md

@@ -2,9 +2,9 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Current state: bootstrap closed; bot extension API + in-process embedding API shipped (9.6.0 released)
+## Current state: bootstrap closed; bot framework absorption shipped (9.7.0 released)
 
-This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/agentculture/culture). The bootstrap is closed; 9.0.0 through 9.6.0 are live on PyPI. The most recent ship is the in-process embedding API (9.6.0, closed [#22](https://github.com/agentculture/agentirc/issues/22)) — promoting `agentirc.ircd.IRCd` and `agentirc.virtual_client.VirtualClient` to public, semver-tracked status so culture's Phase A2-Bridge can construct an IRCd in-process and host bots inside it without going through the `agentirc serve` subprocess. The previous ship was the out-of-process bot extension API (9.5.0, closed [#15](https://github.com/agentculture/agentirc/issues/15)). The repo currently contains:
+This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/agentculture/culture). The bootstrap is closed; 9.0.0 through 9.7.0 are live on PyPI. The most recent ship is the bot framework absorption (9.7.0, closed [#33](https://github.com/agentculture/agentirc/issues/33)) — promoting `agentirc.bots` (BotManager, Bot, BotConfig) to public, semver-tracked status so culture and other embedders can register deterministic, YAML-spec'd event-trigger bots against a running `IRCd` in-process. The previous ship was the in-process embedding API (9.6.0, closed [#22](https://github.com/agentculture/agentirc/issues/22)). The repo currently contains:
 
 - **Server-core** (`agentirc/{ircd,server_link,channel,events,skill,remote_client,…}.py`, `agentirc/skills/{rooms,threads,history,icon}.py`) — vendored from `culture@df50942` via the `cite-don't-copy` pattern (see `[tool.citation]` in `pyproject.toml`).
 - **Client transport** (`agentirc/client.py`) — vendored from `culture/agentirc/client.py` in PR-B2.
@@ -14,7 +14,8 @@ This repo is the agentirc server-core extraction out of the sibling project [`cu
 - **Bot extension API (9.5.0)** — IRCv3 `agentirc.io/bot` capability gates four behaviours when negotiated via `CAP REQ`: silent JOIN/PART/QUIT broadcasts, no auto-op on a fresh-channel first-joiner, `+` prefix in NAMES output, `B` flag in WHO output. `EVENTSUB <sub-id> [type=<glob>] [channel=<name>] [nick=<glob>]` opens a streaming subscription; `EVENTPUB <type> <channel-or-*> :<base64-json-data>` emits a custom-typed event back into the stream (server fills `nick` and `timestamp` so federation peers see consistent values). Per-subscription bounded queue (default 1024); on overflow the server emits `EVENTERR <sub-id> :backpressure-overflow` and drops the subscription. Quick reference at [`docs/extension-api.md`](docs/extension-api.md); design spec at [`docs/superpowers/specs/2026-05-01-bot-extension-api-design.md`](docs/superpowers/specs/2026-05-01-bot-extension-api-design.md).
 - **Test suite** — 36 tests vendored from `culture@df50942` (~6.5kloc) plus agentirc-native tests in `tests/test_config_loader.py` and `tests/test_wire_format_envelope.py` (the 9.5.0a2 golden-file lock-in). `pytest -n auto` in ~30s on default workers. Three telemetry tests (`test_bot_event_dispatch_span`, `test_bot_run_span`, `test_metrics_bots`) and `test_welcome_bot` stay in culture because they depend on the real `BotManager`.
 - **In-process embedding API (9.6.0)** — `agentirc.ircd.IRCd` and `agentirc.virtual_client.VirtualClient` promoted to the public surface. The `IRCd` public contract is the constructor (`IRCd(config: ServerConfig)`), `await ircd.start()`/`stop()`, `await ircd.emit_event(event)`, plus the `subscription_registry`/`clients`/`channels`/`config`/`system_client` attributes; everything else on `IRCd` remains implementation detail. `VirtualClient` moved from `agentirc/_internal/virtual_client.py` to `agentirc/virtual_client.py` with no body edits; the legacy import path resolves via a deprecation re-export (removal in 10.0.0). Worked example + member breakdown live in [`docs/api-stability.md`](docs/api-stability.md#embedding-agentirc-in-process). Same wire surface as 9.5.0; no protocol changes.
-- **Internal support** (`agentirc/_internal/`) — `aio`, `constants`, `protocol/`, `telemetry/`, `pidfile`, `cli_shared/`, `bots/` stubs, `event_subscriptions/` (added 9.5.0). The `_internal/virtual_client.py` module remains as a deprecation re-export of the now-public `agentirc.virtual_client.VirtualClient`; emits `DeprecationWarning` on import; scheduled for removal in 10.0.0.
+- **Bot framework absorption (9.7.0)** — `agentirc.bots` promoted to public surface with `BotManager`, `Bot`, and `BotConfig` as semver-tracked exports. Deterministic, YAML-spec'd event-trigger bots load from `~/.culture/bots/`, register against a running `IRCd` in-process, match events via compiled filter expressions, and respond by sending messages or emitting custom-typed events. Paraphrased from `culture.bots.*` with import paths rewritten; `http_listener` is real aiohttp-backed; system-bot discovery imports culture's module lazily at runtime. Full API reference and worked example live in [`docs/api-stability.md`](docs/api-stability.md#embedding-bots-agentircbots).
+- **Internal support** (`agentirc/_internal/`) — `aio`, `constants`, `protocol/`, `telemetry/`, `pidfile`, `cli_shared/`, `bots/` stubs (backward compat, removal in 10.0.0), `event_subscriptions/` (added 9.5.0). The `_internal/virtual_client.py` module remains as a deprecation re-export of the now-public `agentirc.virtual_client.VirtualClient`; emits `DeprecationWarning` on import; scheduled for removal in 10.0.0.
 - **Bootstrap docs** (PR-B4, 9.4.0) — `docs/api-stability.md` (3 public modules + semver contract), `docs/cli.md` (verb table, flag reference, exit codes, YAML/CLI precedence, agentirc-vs-culture diff table), `docs/deployment.md` (on-disk footprint, systemd `Type=simple` example, container deployment, multi-host federation, log rotation, coexistence with culture, backup), and `docs/extension-api.md` (bot-author quick reference, added 9.5.0). Public-facing `README.md` rewritten for issue [#19](https://github.com/agentculture/agentirc/issues/19).
 
 End-to-end verified: `agentirc start --port <p>` boots a real IRCd, TCP NICK/USER handshake returns `001 RPL_WELCOME`, `agentirc stop` shuts cleanly. `agentirc serve --config server.yaml --port 9999` correctly overlays CLI flag on YAML. `pip install agentirc-cli==9.5.0` from real PyPI in a clean venv produces both `agentirc` and `agentirc-cli` binaries; both reach the same `agentirc.cli:main` entry point. Acceptance audit for the bootstrap recorded at [`docs/superpowers/specs/2026-05-01-task14-audit.md`](docs/superpowers/specs/2026-05-01-task14-audit.md). Culture-side cutover unblocked via [agentculture/culture#308](https://github.com/agentculture/culture/issues/308).
@@ -47,8 +48,9 @@ There are three different names in play. Don't conflate them:
 
 - **Server-core (here):** `ircd.py`, `server_link.py`, `channel.py`, `config.py`, `events.py`, the stores (`room_store`, `thread_store`, `history_store`), `rooms_util.py`, `skill.py`, `remote_client.py`, and the `skills/` directory (`rooms`, `threads`, `history`, `icon`).
 - **Client transport (here, since 9.2.0):** `client.py` — vendored in PR-B2. Pre-9.2 the bootstrap spec said "stays in culture"; that assumption broke down once we found `client.py` only imports already-vendored modules and that the IRCd needs it at runtime to accept TCP clients.
-- **Internal support (here):** `agentirc/_internal/{aio, constants, protocol/, telemetry/, virtual_client, pidfile, cli_shared/}` plus `bots/` no-op stubs (the real `culture.bots.*` depends on backend SDKs forbidden by agentirc's dependency boundary; culture replaces the stubs at runtime when wrapping an IRCd).
-- **Stays in culture:** `culture.bots.*` (the real bot manager), `culture.config` / `culture.bots.config` (agent-manifest concerns), `culture.cli.shared.{ipc,display,formatting,process}` (CLI ergonomics agentirc doesn't need), `culture.credentials` / `culture.mesh_config` (OS-keyring + mesh.yaml).
+- **Bot framework (here, since 9.7.0):** `agentirc/bots/{bot_manager.py, bot.py, config.py, template_engine.py, filter_dsl.py, http_listener.py, virtual_client.py}` and `agentirc/bots/system.py` (system bot discovery, culture-supplied at runtime). Public surface: `BotManager`, `Bot`, `BotConfig`. Paraphrased from `culture.bots.*` with import paths rewritten; the `http_listener` is real aiohttp-backed, and system-bot discovery imports culture's module lazily at runtime.
+- **Internal support (here):** `agentirc/_internal/{aio, constants, protocol/, telemetry/, virtual_client, pidfile, cli_shared/}` plus `_internal/bots/` stubs for backward compat (scheduled for removal in 10.0.0).
+- **Stays in culture:** `culture.config` / `culture.bots.config` (agent-manifest concerns beyond agentirc's scope), `culture.cli.shared.{ipc,display,formatting,process}` (CLI ergonomics agentirc doesn't need), `culture.credentials` / `culture.mesh_config` (OS-keyring + mesh.yaml).
 
 When migrating tests, the rule is: pure server tests come here, transport tests **also** come here now that we own `client.py`, mixed tests stay in culture and get rewritten to drive `agentirc serve` as a subprocess fixture rather than importing `IRCd` directly. When unsure, **prefer copying the test here** — this repo owns the IRCd and the client transport.
 
@@ -61,7 +63,7 @@ When migrating tests, the rule is: pure server tests come here, transport tests
 
 ## Public API contract (semver-tracked)
 
-Five modules are public. Everything else is internal and may be refactored without a major bump.
+Six modules are public. Everything else is internal and may be refactored without a major bump.
 
 | Module | Members | Since |
 |---|---|---|
@@ -70,6 +72,7 @@ Five modules are public. Everything else is internal and may be refactored witho
 | `agentirc.protocol` | verb name constants, numeric reply codes, extension tag names; bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT` verbs, `BOT_CAP`) | 9.2.0 (extended 9.5.0) |
 | `agentirc.ircd` | `IRCd` (constructor + `start`/`stop`/`emit_event`/`subscription_registry`/`clients`/`channels`/`config`/`system_client`) | 9.6.0 |
 | `agentirc.virtual_client` | `VirtualClient` | 9.6.0 |
+| `agentirc.bots` | `BotManager`, `Bot`, `BotConfig` | 9.7.0 |
 
 `agentirc.cli.dispatch(argv)` is the function `culture`'s `culture server` shim calls — it must accept the exact same flag set, exit codes, and stderr formatting that `culture server` produces today. Do not "improve" CLI ergonomics during the bootstrap; that breaks the transparency contract culture relies on. `dispatch()` returns `int` on successful command dispatch and lets argparse's `SystemExit` propagate on `--help`/`--version`/parse-errors per Python convention; in-process callers (i.e. culture's shim) must catch `SystemExit` themselves or use `subprocess`.