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

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

@@ -4,6 +4,29 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [9.8.0] - 2026-06-12
+
+Make bot authoring discoverable: a dedicated guide plus first-class CLI support
+for event-triggered bots.
+
+### Added
+
+- **`agentirc bot create --trigger event --event-filter "<expr>"`** — the CLI
+  can now create event-triggered bots, not just `webhook` ones. The filter is
+  compiled and validated at create time (a malformed expression is rejected
+  immediately). `--event-filter` is required for `--trigger event` and rejected
+  for `--trigger webhook`.
+- **[`docs/bots.md`](docs/bots.md)** — a bot-authoring guide: CLI quick start
+  for both trigger types, the `bot.yaml` schema for hand-authoring, the
+  event-filter DSL grammar, and templating. Linked from the README.
+
+### Changed
+
+- README public-API table now lists all six public modules (it had drifted to
+  three) and gains an "Embedded bots" section. Corrected the stale 9.5.0
+  "webhook never bound" operational note — since 9.7.0 `IRCd.start()` binds the
+  listener when `webhook_port > 0`.
+
 ## [9.7.0] - 2026-06-12
 
 Absorb culture's bot framework into the public `agentirc.bots` subsystem. Closes

{agentirc_cli-9.7.0 → agentirc_cli-9.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.7.0
+Version: 9.8.0
 Summary: Agent-friendly IRCd: server core for AI agent meshes
 Project-URL: Homepage, https://github.com/agentculture/agentirc
 Project-URL: Issues, https://github.com/agentculture/agentirc/issues
@@ -145,15 +145,18 @@ multi-host federation.
 
 ## Public API and stability
 
-Three modules form the **public, semver-tracked surface**. Everything else
+Six modules form the **public, semver-tracked surface**. Everything else
 under `agentirc.*` is internal and may be refactored — including renamed,
 split, or removed — in any minor or patch release.
 
-| Module | Members |
-|---|---|
-| [`agentirc.config`](docs/api-stability.md#agentircconfig) | `ServerConfig`, `LinkConfig`, `TelemetryConfig`, `ServerConfig.from_yaml(path)` |
-| [`agentirc.cli`](docs/api-stability.md#agentirccli) | `main()`, `dispatch(argv) -> int` |
-| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`) |
+| Module | Members | Since |
+|---|---|---|
+| [`agentirc.config`](docs/api-stability.md#agentircconfig) | `ServerConfig`, `LinkConfig`, `TelemetryConfig`, `ServerConfig.from_yaml(path)` | 9.0.0 |
+| [`agentirc.cli`](docs/api-stability.md#agentirccli) | `main()`, `dispatch(argv) -> int` | 9.2.0 |
+| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`) | 9.2.0 |
+| [`agentirc.ircd`](docs/api-stability.md#embedding-agentirc-in-process) | `IRCd` (constructor + `start`/`stop`/`emit_event` + core attributes) | 9.6.0 |
+| [`agentirc.virtual_client`](docs/api-stability.md#embedding-agentirc-in-process) | `VirtualClient` | 9.6.0 |
+| [`agentirc.bots`](docs/api-stability.md#botconfig-yaml-schema) | `BotManager`, `Bot`, `BotConfig` — embedded YAML-spec'd bots (see [`docs/bots.md`](docs/bots.md)) | 9.7.0 |
 
 `agentirc.cli.dispatch(argv)` is the in-process integration surface — it is
 what culture's `culture server` shim calls today. It returns `int` on
@@ -222,11 +225,31 @@ behavior) and
 [`docs/api-stability.md#bot-extension-surface-shipped-in-950`](docs/api-stability.md#bot-extension-surface-shipped-in-950)
 for the wire contract.
 
-**Operational note.** As of 9.5.0, `agentirc` no longer binds `webhook_port`
-even when set in YAML — the field stays in `ServerConfig` for backward
-compatibility with culture's `~/.culture/server.yaml`, but consumers that
-need webhook→bot dispatch host their own HTTP listener (notably culture).
-The field will be removed in 10.0.0.
+## Embedded bots (since 9.7.0)
+
+Distinct from the out-of-process extension API above, `agentirc.bots` is an
+**in-process** bot framework: deterministic, YAML-spec'd automations that run as
+`VirtualClient` presences inside the IRCd (no separate process). A bot reacts to
+an event filter or an HTTP webhook and replies with a Jinja2-templated message.
+
+```bash
+agentirc bot create pinger --owner ori \
+  --trigger event \
+  --event-filter "type == 'user.message' and channel == '#general'" \
+  --channels '#general' --template 'pong {{event.nick}}'
+```
+
+Bots live under `~/.culture/bots/<name>/bot.yaml` and load when the server
+starts. See **[`docs/bots.md`](docs/bots.md)** for the authoring guide (CLI +
+hand-written YAML, the two trigger types, the filter DSL, templates) and
+[`docs/api-stability.md`](docs/api-stability.md#botconfig-yaml-schema) for
+embedding a `BotManager` onto a running `IRCd`.
+
+**Operational note.** Since 9.7.0, `IRCd.start()` binds the webhook listener
+when `webhook_port` is set (>0), giving webhook-triggered bots HTTP ingress
+under standalone `agentirc serve`; when `webhook_port` is unset/0 nothing is
+bound (preserving the 9.5.0 default). The field stays in `ServerConfig` for
+backward compatibility with culture's `~/.culture/server.yaml`.
 
 ## Current state and roadmap
 

{agentirc_cli-9.7.0 → agentirc_cli-9.8.0}/README.md

@@ -107,15 +107,18 @@ multi-host federation.
 
 ## Public API and stability
 
-Three modules form the **public, semver-tracked surface**. Everything else
+Six modules form the **public, semver-tracked surface**. Everything else
 under `agentirc.*` is internal and may be refactored — including renamed,
 split, or removed — in any minor or patch release.
 
-| Module | Members |
-|---|---|
-| [`agentirc.config`](docs/api-stability.md#agentircconfig) | `ServerConfig`, `LinkConfig`, `TelemetryConfig`, `ServerConfig.from_yaml(path)` |
-| [`agentirc.cli`](docs/api-stability.md#agentirccli) | `main()`, `dispatch(argv) -> int` |
-| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`) |
+| Module | Members | Since |
+|---|---|---|
+| [`agentirc.config`](docs/api-stability.md#agentircconfig) | `ServerConfig`, `LinkConfig`, `TelemetryConfig`, `ServerConfig.from_yaml(path)` | 9.0.0 |
+| [`agentirc.cli`](docs/api-stability.md#agentirccli) | `main()`, `dispatch(argv) -> int` | 9.2.0 |
+| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`) | 9.2.0 |
+| [`agentirc.ircd`](docs/api-stability.md#embedding-agentirc-in-process) | `IRCd` (constructor + `start`/`stop`/`emit_event` + core attributes) | 9.6.0 |
+| [`agentirc.virtual_client`](docs/api-stability.md#embedding-agentirc-in-process) | `VirtualClient` | 9.6.0 |
+| [`agentirc.bots`](docs/api-stability.md#botconfig-yaml-schema) | `BotManager`, `Bot`, `BotConfig` — embedded YAML-spec'd bots (see [`docs/bots.md`](docs/bots.md)) | 9.7.0 |
 
 `agentirc.cli.dispatch(argv)` is the in-process integration surface — it is
 what culture's `culture server` shim calls today. It returns `int` on
@@ -184,11 +187,31 @@ behavior) and
 [`docs/api-stability.md#bot-extension-surface-shipped-in-950`](docs/api-stability.md#bot-extension-surface-shipped-in-950)
 for the wire contract.
 
-**Operational note.** As of 9.5.0, `agentirc` no longer binds `webhook_port`
-even when set in YAML — the field stays in `ServerConfig` for backward
-compatibility with culture's `~/.culture/server.yaml`, but consumers that
-need webhook→bot dispatch host their own HTTP listener (notably culture).
-The field will be removed in 10.0.0.
+## Embedded bots (since 9.7.0)
+
+Distinct from the out-of-process extension API above, `agentirc.bots` is an
+**in-process** bot framework: deterministic, YAML-spec'd automations that run as
+`VirtualClient` presences inside the IRCd (no separate process). A bot reacts to
+an event filter or an HTTP webhook and replies with a Jinja2-templated message.
+
+```bash
+agentirc bot create pinger --owner ori \
+  --trigger event \
+  --event-filter "type == 'user.message' and channel == '#general'" \
+  --channels '#general' --template 'pong {{event.nick}}'
+```
+
+Bots live under `~/.culture/bots/<name>/bot.yaml` and load when the server
+starts. See **[`docs/bots.md`](docs/bots.md)** for the authoring guide (CLI +
+hand-written YAML, the two trigger types, the filter DSL, templates) and
+[`docs/api-stability.md`](docs/api-stability.md#botconfig-yaml-schema) for
+embedding a `BotManager` onto a running `IRCd`.
+
+**Operational note.** Since 9.7.0, `IRCd.start()` binds the webhook listener
+when `webhook_port` is set (>0), giving webhook-triggered bots HTTP ingress
+under standalone `agentirc serve`; when `webhook_port` is unset/0 nothing is
+bound (preserving the 9.5.0 default). The field stays in `ServerConfig` for
+backward compatibility with culture's `~/.culture/server.yaml`.
 
 ## Current state and roadmap
 

{agentirc_cli-9.7.0 → agentirc_cli-9.8.0}/agentirc/bots/cli.py

@@ -25,6 +25,7 @@ import argparse
 import sys
 import time
 
+from agentirc.bots.filter_dsl import FilterParseError, compile_filter
 from agentirc.bots.config import (
     BOT_CONFIG_FILE,
     BOTS_DIR,
@@ -51,7 +52,19 @@ def register(subparsers: argparse._SubParsersAction) -> None:
     bot_create.add_argument("--owner", required=True, help="Owner nick (e.g. spark-ori)")
     bot_create.add_argument("--channels", nargs="+", default=[], help="Channels to join")
     bot_create.add_argument(
-        "--trigger", default="webhook", choices=["webhook"], help="Trigger type"
+        "--trigger",
+        default="webhook",
+        choices=["webhook", "event"],
+        help="Trigger type: 'webhook' (HTTP POST) or 'event' (matches an "
+        "event filter). 'event' requires --event-filter.",
+    )
+    bot_create.add_argument(
+        "--event-filter",
+        default=None,
+        help="Filter expression for an event-triggered bot, e.g. "
+        "\"type == 'user.message' and channel == '#general'\". "
+        "Matches against {type, channel, nick, data}. Required for "
+        "--trigger event.",
     )
     bot_create.add_argument("--mention", default=None, help="Agent to @mention on trigger")
     bot_create.add_argument("--template", default=None, help="Message template")
@@ -141,6 +154,29 @@ def _bot_create(args: argparse.Namespace) -> int:
         # name has no prefix yet — mimic culture's auto-prefix
         name = f"{owner}-{name}"
 
+    # An event-triggered bot is meaningless without a filter; validate it
+    # compiles now so the user gets immediate feedback instead of a silent
+    # skip at load time.
+    event_filter = getattr(args, "event_filter", None)
+    if args.trigger == "event":
+        if not event_filter:
+            print(
+                "Error: --trigger event requires --event-filter",
+                file=sys.stderr,
+            )
+            return 1
+        try:
+            compile_filter(event_filter)
+        except (FilterParseError, TypeError) as exc:
+            print(f"Error: invalid --event-filter: {exc}", file=sys.stderr)
+            return 1
+    elif event_filter:
+        print(
+            "Error: --event-filter only applies to --trigger event",
+            file=sys.stderr,
+        )
+        return 1
+
     bot_config = BotConfig(
         name=name,
         owner=args.owner,
@@ -152,6 +188,7 @@ def _bot_create(args: argparse.Namespace) -> int:
         mention=args.mention,
         template=args.template,
         fallback="json",
+        event_filter=event_filter,
     )
 
     bot_dir = BOTS_DIR / name
@@ -163,6 +200,8 @@ def _bot_create(args: argparse.Namespace) -> int:
     print(f"Bot '{name}' created at {bot_dir}")
     print(f"  Owner:    {args.owner}")
     print(f"  Trigger:  {args.trigger}")
+    if event_filter:
+        print(f"  Filter:   {event_filter}")
     if args.channels:
         print(f"  Channels: {', '.join(args.channels)}")
     if args.mention:

agentirc_cli-9.8.0/docs/bots.md

@@ -0,0 +1,174 @@
+# Writing agentirc bots
+
+agentirc bots are **deterministic, YAML-spec'd chatops automations** — think
+ChanServ-class services, not LLM agents. Each bot runs as an in-process
+`VirtualClient` presence inside a running IRCd: it has no separate process and
+lives and dies with the server. A bot reacts to either an **event** (matched by
+a filter expression) or a **webhook** (an inbound HTTP POST) and responds by
+sending a templated message to its channels and/or emitting a custom event.
+
+This guide is for **authoring** bots. For embedding the bot framework in your
+own process (installing a `BotManager` onto an `IRCd`), see
+[`api-stability.md` → Embedding bots](api-stability.md#botconfig-yaml-schema).
+
+## Where bots live
+
+Each bot is a directory under the bots dir with a single `bot.yaml`:
+
+```
+~/.culture/bots/<bot-name>/bot.yaml
+```
+
+The default bots dir is `~/.culture/bots/` (shared with culture for continuity).
+`agentirc bot …` and the in-process `BotManager.load_bots()` both read from it;
+non-archived bots are loaded and started when the server starts.
+
+## The two trigger types
+
+| Trigger | Fires when | Needs |
+|---------|-----------|-------|
+| `event` | an `Event` flowing through the IRCd matches the bot's filter | a `trigger.filter` expression |
+| `webhook` | an HTTP POST arrives at the bot's webhook endpoint | the server's `webhook_port` set (>0) |
+
+`event` bots are the common case (they react to chat/room activity). `webhook`
+bots give external systems an HTTP ingress; the listener binds only when the
+server is configured with a `webhook_port`.
+
+## Quick start (CLI)
+
+### An event-triggered bot
+
+```bash
+agentirc bot create pinger \
+  --owner ori \
+  --trigger event \
+  --event-filter "type == 'user.message' and channel == '#general'" \
+  --channels '#general' \
+  --template 'pong {{event.nick}}'
+```
+
+The filter is **compiled and validated at create time** — a malformed
+expression is rejected immediately rather than silently skipped at load. The bot
+is written to `~/.culture/bots/ori-pinger/bot.yaml` (the owner is prefixed to the
+name when the name has no `-`).
+
+### A webhook bot
+
+```bash
+agentirc bot create deployer \
+  --owner ori \
+  --trigger webhook \
+  --channels '#ops' \
+  --template 'deploy: {{payload.status}}'
+```
+
+POST JSON to `/<bot-name>` on the server's `webhook_port` to fire it.
+
+### Activate, then manage
+
+```bash
+agentirc bot start ori-pinger      # mark active (loads on next server start)
+agentirc bot list                  # list bots (use --all to include archived)
+agentirc bot inspect ori-pinger    # show details
+agentirc bot archive ori-pinger    # disable without deleting
+agentirc bot unarchive ori-pinger  # re-enable
+```
+
+Newly created bots load when the server (re)starts; `agentirc bot start` marks a
+bot active for the next load.
+
+## Hand-authoring `bot.yaml`
+
+The CLI is a convenience over a plain YAML file you can write directly. The
+layout mirrors the `BotConfig` dataclass:
+
+```yaml
+bot:
+  name: ori-pinger
+  owner: ori
+  description: "Replies to messages in #general"
+trigger:
+  type: event                                  # "event" or "webhook"
+  filter: "type == 'user.message' and channel == '#general'"
+output:
+  channels:
+    - "#general"
+  template: "pong {{ event.nick }}"            # Jinja2
+  fallback: json                               # "json" or "text"
+  mention: null                                # nick to @-mention on fire, or null
+  dm_owner: false                              # also DM the owner on fire
+```
+
+Field reference:
+
+| Field | Meaning |
+|-------|---------|
+| `bot.name` / `bot.owner` / `bot.description` | metadata |
+| `trigger.type` | `event` (filter) or `webhook` (HTTP POST) |
+| `trigger.filter` | event-filter expression (event bots only) — see below |
+| `output.channels` | channels the bot joins and addresses |
+| `output.template` | Jinja2 template rendered with the bot context + event/payload |
+| `output.fallback` | render fallback when the template can't render: `json` or `text` |
+| `output.mention` | nick to `@`-mention when the bot fires, or `null` |
+| `output.dm_owner` | also DM the owner when the bot fires |
+| `archived` | set `true` to skip loading without deleting |
+
+## The event-filter DSL
+
+`trigger.filter` is a small, safe boolean expression — **no code execution**.
+It evaluates against the event dict `{type, channel, nick, data}` (and nested
+`data.*` via dotted paths). A missing field compares `False` to everything.
+
+Grammar:
+
+```text
+expr     := or_expr
+or_expr  := and_expr ('or' and_expr)*
+and_expr := not_expr ('and' not_expr)*
+not_expr := 'not' not_expr | cmp_expr
+cmp_expr := atom (('==' | '!=' | 'in') atom)?
+atom     := STRING | NUMBER | LIST | IDENT('.'IDENT)* | '(' expr ')'
+LIST     := '[' [atom (',' atom)*] ']'
+```
+
+Operators: `==`, `!=`, `in`, `and`, `or`, `not`, parentheses, list literals.
+String literals use **single quotes**.
+
+Examples:
+
+```yaml
+filter: "type == 'user.message'"
+filter: "type == 'user.join' and channel == '#welcome'"
+filter: "type == 'user.message' and nick in ['alice', 'bob']"
+filter: "type == 'custom.ping' and data.target == 'pinger'"
+filter: "not (channel == '#noisy')"
+```
+
+## Templates
+
+`output.template` is a Jinja2 template. Event bots get the event in context
+(`event.type`, `event.channel`, `event.nick`, `event.data.*`); webhook bots get
+the posted JSON as `payload`. If rendering fails, the bot falls back to
+`output.fallback` (`json` dumps the context, `text` stringifies it).
+
+```yaml
+template: "{{ event.nick }} said hi in {{ event.channel }}"
+template: "deploy {{ payload.env }} -> {{ payload.status }}"
+```
+
+## Validate and inspect
+
+- `agentirc bot create … --trigger event --event-filter …` compiles the filter
+  up front and refuses a bad one.
+- `agentirc bot inspect <name>` shows the parsed config.
+- A bot with a filter that fails to compile at load time is logged and skipped
+  (it won't crash the server).
+
+## See also
+
+- [`api-stability.md`](api-stability.md#botconfig-yaml-schema) — the public
+  `agentirc.bots` API, the `BotConfig` schema, and a worked example of installing
+  a `BotManager` onto a running `IRCd` in-process.
+- [`extension-api.md`](extension-api.md) — the IRCv3 bot capability and the
+  `EVENTSUB`/`EVENTPUB` streaming surface for **TCP-connected** bots (a different
+  thing from these in-process YAML bots).

{agentirc_cli-9.7.0 → agentirc_cli-9.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "9.7.0"
+version = "9.8.0"
 description = "Agent-friendly IRCd: server core for AI agent meshes"
 readme = "README.md"
 license = "Apache-2.0"

{agentirc_cli-9.7.0 → agentirc_cli-9.8.0}/tests/bots/test_cli_bot.py

@@ -270,3 +270,59 @@ def test_bot_inspect_rejects_path_traversal_names(bots_dir, capsys):
     rc = _dispatch("bot", "inspect", "../../secret")
     assert rc == 1
     assert "Invalid bot name" in capsys.readouterr().err
+
+
+# ---------------------------------------------------------------------------
+# Event-triggered bot creation (since 9.8.0)
+# ---------------------------------------------------------------------------
+
+
+def _read_yaml(bots_dir, bot_name):
+    import yaml
+
+    return yaml.safe_load(
+        (bots_dir / bot_name / "bot.yaml").read_text()
+    )
+
+
+def test_bot_create_event_writes_filter(bots_dir, capsys):
+    """``--trigger event --event-filter ...`` writes an event bot spec."""
+    rc = _dispatch(
+        "bot", "create", "pinger", "--owner", "ori",
+        "--trigger", "event",
+        "--event-filter", "type == 'user.message' and channel == '#general'",
+        "--channels", "#general", "--template", "pong {{event.nick}}",
+    )
+    assert rc == 0
+    spec = _read_yaml(bots_dir, "ori-pinger")
+    assert spec["trigger"]["type"] == "event"
+    assert spec["trigger"]["filter"] == "type == 'user.message' and channel == '#general'"
+
+
+def test_bot_create_event_requires_filter(bots_dir, capsys):
+    """``--trigger event`` without a filter is rejected."""
+    rc = _dispatch("bot", "create", "nofilter", "--owner", "ori", "--trigger", "event")
+    assert rc == 1
+    assert "requires --event-filter" in capsys.readouterr().err
+    assert list(bots_dir.iterdir()) == []
+
+
+def test_bot_create_event_rejects_bad_filter(bots_dir, capsys):
+    """An --event-filter that doesn't compile is rejected at create time."""
+    rc = _dispatch(
+        "bot", "create", "badfilter", "--owner", "ori",
+        "--trigger", "event", "--event-filter", "type == =",
+    )
+    assert rc == 1
+    assert "invalid --event-filter" in capsys.readouterr().err
+    assert list(bots_dir.iterdir()) == []
+
+
+def test_bot_create_webhook_rejects_event_filter(bots_dir, capsys):
+    """--event-filter only applies to event triggers."""
+    rc = _dispatch(
+        "bot", "create", "wh", "--owner", "ori",
+        "--trigger", "webhook", "--event-filter", "type == 'x.y'",
+    )
+    assert rc == 1
+    assert "only applies to --trigger event" in capsys.readouterr().err

{agentirc_cli-9.7.0 → agentirc_cli-9.8.0}/uv.lock

@@ -10,7 +10,7 @@ resolution-markers = [
 
 [[package]]
 name = "agentirc-cli"
-version = "9.7.0"
+version = "9.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },