mention-gate

Files (3)

• SKILL.md
• mention-gate.py · scripts/
• witness.py · scripts/

SKILL.md (first lines)

# Mention Gate

Today, in every requireMention channel, a message @-tagging the owner (but not
the bot) is never ingested — it stays invisible to the fleet. This skill adds
the missing ON side:

- **ON** — an owner-tagged message from anyone but the owner counts as a bot
  mention: it passes the requireMention check and becomes a task. Every
  message pulled in this way is appended to a durable audit log so the owner
  can review exactly what the toggle admitted.
- **OFF (default)** — today's behavior, unchanged.

Never affected: messages from the owner himself (they follow the existing
rules), messages that actually mention the bot (ingested in both states, as
always), and `requireMention:false` channels (everything there already
ingests, gate on or off). Later access gates (channel allowFrom, tier
resolution) still apply to an admitted message — the gate substitutes only the
missing bot-mention, nothing else.

**Fail-closed:** the feature ADDS ingestion, so every failure reads as OFF —
missing or malformed state, an unparseable `until`, or any exception inside
the bridge's gate check leaves the ordinary requireMention rejection standing.
A broken state file must never surprise-ingest.

## Usage

```bash
python3 skills/mention-gate/scripts/mention-gate.py on              # owner tags trigger ingestion
python3 skills/mention-gate/scripts/mention-gate.py on --for 2h     # with auto-expiry back to off (30m/2h/1d)
python3 skills/mention-gate/scripts/mention-gate.py off             # today's behavior (default)
python3 skills/mention-gate/scripts/mention-gate.py status          # state + how many messages pulled in
```

## State + audit

### Scope: PER-HOST, not fleet-wide

The gate is stored under `<workspace>/state/`, which `vault.sync.exclude` lists
explicitly — the vault runs in whitelist mode and carries only `notes/`,
`talks/`, `hosts/` and the memory tree. `git ls-files state/mention-gate.json`
returns nothing on a live host. So **toggling the gate changes only the host it
was run on**; every other host keeps its own setting. Run the command once per
host. There is currently no synced fleet-policy surface to store it on.

- Gate state: `<workspace>/state/mention-gate.json` —
  `{"mentions_enabled": bool, "until": "<ISO-8601>"|null}` (`mentions_enabled`
  = this gate is on), written atomically (temp sibling + `os.replace`).
  `until` auto-expiry needs no follow-up write: once passed, the gate reads
  OFF.
- Audit log: `<workspace>/state/mention-gate-ingested.jsonl` — one fsync'd
  JSON line per admitted message `{ts, channel_id, author_id, message_id,
  body (first 120 chars)}`. `status` reports the count. The row is appended
  only AFTER the admitted task file is durably written — a sender the later
  authorization gates (channel allowFrom, global allowlist) reject leaves no
  audit row, so an unauthorized sender can never inflate the audit (#3473).

## Architecture

- **Policy owner (core):** `src/mention_gate.py` — `read_state` / `write_state`
  / `owner_tag_triggers_ingest` (fail-closed) / `message_tags_owner(mention_ids,
  text, owner_ids)` / `log_gated_ingest` / `gated_ingest_count`. Owner ids are
  parameters; the module hardcodes none.
- **Discord adapter (wired):** `src/discord-bridge.py` —
  `_mention_gate_triggers_ingest(message)`, consulted inside
  `_handle_discord_message` at the requireMention rejection site (the
  `require_mention and not bot_mentioned and not role_mentioned` branch):
  when it returns True the rejection is bypassed and the message continues
  down the existing pipeline; otherwise (including on any error) the ordinary
  skip stands. The helper returns a verdict only; the audit row is written by
  `_mention_gate_log_admission` right after `_write_task_file` succeeds.
  Owner-tagging is detected from the platform `message.mentions` array plus a
  `<@ID>`/`<@!ID>` text fallback. Owner ids come from `access.json`: a
  PRESENT `tierMap` is authoritative — only its explicit `owner` entries
  count, and an empty map means no owners (the gate never triggers);
  `allowFrom` is consulted only when the `tierMap` key is absent (legacy
  file), so read-only members are never promoted to owner for this gate.
- **ag2space/Matrix adapter (NOT wired — documented instead):** verified by
  reading the code: gateway messages become task files inside `_write_task` in
  `packages/ag2-sparrow/ag2_sparrow/remote_gateway_bridge.py`, which is
  package-canonical (PyPI-published, intentionally divergent from `src/`; the
  `src/remote-gateway-bridge.py` loader only injects dirs/seams and execs it —
  no per-message ingest passes through repo-level code first). The broker also
  makes the mention-match decision (`is_mention`) server-side, so wiring here
  would fork the vendored contract. Where the trigger belongs: an injectable
  ingest-trigger seam in the package (mirroring
  `local_task_protocol.set_task_stamper`), consulted where `_write_task`'s
  callers decide whether a room message is for this agent; the loader would
  bind it to `mention_gate.owner_tag_triggers_ingest` + `message_tags_owner`
  with the workspace it already resolves and the owner mxid from its channel
  config. Until that package change lands, the gate has no effect on
  ag2space/Matrix rooms.

## Tests

`tests/mention-gate.test.py` — fail-closed state contract (default/missing and
malformed state read OFF, unparseable `until` reads OFF, atomic write),
tagging detection (mentions array + text fallback), injected-now expiry
flipping ON→OFF, audit-log order + count, owner-id resolution controls (an
explicitly empty tierMap yields no owners and the gate never triggers; a
present tierMap beats allowFrom; absent tierMap falls back), the production
chokepoint matrix on `_mention_gate_triggers_ingest` (verdict-only — no audit
at verdict time; OFF and default-state reject as the fail-closed control;
tags-neither, bot-only-mention and owner-authored never trigger; any error
fails closed), full-handler behavioral drives (gate ON + authorized → task
written then exactly one audit row; gate OFF/default → neither; unauthorized
sender → neither), AST pins (gate consulted in the requireMention rejection;
audit call strictly after the task write; verdict helper contains no audit
call), and a CLI round trip.

## Live witness (post-restart)

`skills/mention-gate/scripts/witness.py case1|case2|case3 --marker <unique>` —
run on the host with the restarted bridge; the operator sends the test
message from a non-owner account and the script verifies task + audit
outcomes for: gate OFF rejects; gate ON admits an authorized tagged message;
gate ON + unauthorized sender leaves neither task nor audit.

From sonichi/sutando, MIT.

More from sonichi/sutando