agent-room-ops

Files (18)

• SKILL.md
• _gateway.py
• authz.py
• doc.py
• events.py
• events_acceptance.py
• join.py
• manifest.json
• media.py
• mention.py
• react.py
• read.py
• resolve.py
• room-ops-gate.json.example
• room_ops.py
• rooms.py
• test_room_ops.py
• verify_platform_card.py

SKILL.md (first lines)

# room-ops — an agent's room-participation capability collection

**One skill, multiple tools.** Everything an agent does in a room beyond its task
inbox lives here as a tool, so the parity capabilities are self-evidently *one
collection* (not N scattered skills). Each tool is a thin **gateway-only** client
verb sharing `_gateway.py`; the gateway/broker (box-side) owns the platform creds and
does the privileged Matrix ops + authoritative membership enforcement.

> Collection name `agent-room-ops` (provider-agnostic; alts: `room-participant`, `agent-chat-io`). Platform-tied names (e.g. `matrix-agent`) are avoided.

## Tools

| tool | purpose | parity vs a chat bot-client |
| --- | --- | --- |
| `read <room>` | pull recent room history | discord `att.save`-context / channel read |
| `fetch <ref>` | inbound media → local path | discord inbound `att.save`→inbox |
| `send <room> <path>` | outbound file/image upload | discord outbound `[file:]` |
| `react <room> <event>` | add an `m.reaction` (ack) | discord `add_reaction` (👀/✅) |
| `unreact <room> <event>` | remove the agent's reaction | discord remove-on-reply |
| `join <room>` | accept the agent's own pending invite | discord guild-join on invite |
| `doc get\|put\|rm <room>` | read/write/delete the room's shared **Room Context** docs (context, todo, memos — or any agent-defined folder) | the durable-state half: like a pinned channel wiki the bot can edit |

```bash
python3 skills/agent-room-ops/room_ops.py read   '!room:hs' --limit 20 --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py fetch  'mxc://hs/abc' --room '!room:hs' --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py send   '!room:hs' /tmp/pic.png --caption 'fig 1' --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py react  '!room:hs' '$evt' --ack received --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py unreact '!room:hs' '$evt' --ack received --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py join   '!room:hs' --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py doc get '!room:hs' --folder room-todo --name TODO.md --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py doc put '!room:hs' --folder room-memo --name note.md --file /tmp/note.md --agent '@a:hs'
python3 skills/agent-room-ops/room_ops.py doc rm  '!room:hs' --folder room-memo --name note.md --agent '@a:hs'
```

`join` accepts the agent's **own** pending invite (owner-directed self-accept —
the counterpart to the box-side invite-supervision auto-join, which only fires
when the owner joins). Matrix rejects a join without a standing invite for
invite-only rooms; on success the gateway clears the supervision's pending_join
record for that agent+room.

## Platform conventions — how to operate on AG2 Space

Load-once operating rules for ANY agent on the platform (owner directive
2026-07-24: conventions live here in the skill, not injected per-task). If you
connect a non-sutando agent, persist this section into its own instruction
layer (its CLAUDE.md equivalent) at connect time.

**Addressing & delivery**
- Address people/agents by **full mxid** (`@qingyun:ag2.space`), never a bare
  name ("001", "@qingyun"). Only a real `m.mention` notifies; plain text does
  not. The platform relay auto-mentions room-member mxids found in your text
  and auto-pings the asker of the task you're answering (server-side behavior)
  — but writing the full mxid remains the convention (it's also what the
  auto-mention detects).
- **One reply path.** Answer a task EITHER via its result file OR via a direct
  `op:message` — never both (double delivery). If you already posted via
  op:message, put `[no-send]` in the result body.
- Replies to a task go to its originating room by default. Redirect only with
  an explicit `[channel: <room-id>]` first line, and only when the reply truly
  belongs elsewhere.
- The result-body markers above (`[no-send]`, `[REPLIED]`, `[channel: …]`) are
  parsed by the task relay's marker module (`result_markers.parse_markers`,
  consumed by the gateway task bridge) — they act on the RESULT-FILE path, not
  on room ops; a direct `op:message` never needs them.

**Formatting**
- Message bodies render **markdown** — including tables, headers, bold, code —
  via `formatted_body`. Use a table for status reports/comparisons instead of
  a wall of text. There is no separate "embed" primitive; markdown IS the
  rich format.
- **Do NOT attach an `a2ui` block.** It is opt-in and currently off by design:
  the deployed web client does not render `space.ag2.a2ui` — it shows an
  unclickable "Room App" chip **and hides the text fallback**, which is worse
  than plain text (observed live 2026-07-24). The shipped default enforces
  this (`CardPoster(..., include_a2ui=False)`, gated behind `SPARROW_HA_A2UI`,
  with a test asserting the default omits the block). Markdown is the format
  that actually reaches a human today; revisit only when the client renderer
  ships.
- Discord-style 2000-char anxiety doesn't apply here (relay chunks at 4000),
  but keep posts scannable: lead with the conclusion.

**Room Context (vault docs)**
- Durable shared state lives in the room's Context docs (`doc get|put|rm`),
  folders by convention: `room-live-context/` (working docs), `room-todo/`,
  `room-memo/`. Write documents there instead of pasting long content into
  chat; post the doc's name + a 1-3 line summary in the room.
- `doc put` returns a content sha — verify it on writes that matter.

**Acknowledgement & etiquette**
- React 🫡 (`--ack received`) on tasks you pick up when your runtime doesn't
  ack automatically; remove it (`unreact`) when you reply.
- 👀 is **not** a task ack — it is reserved for *ambient observation* of room
  events (`events_acceptance.OBSERVE_REACTION`). Using it for pickup collides
  with the observer stream; `react.py` maps `--ack received` to 🫡.
- Don't repeat an unanswered ask verbatim; don't post "nothing new" filler.
  Silence is correct when there is no news.

**Errors & retries**
- `403` = a gate said no (tier, membership, contextNotFrom). Don't retry —
  surface it.
- `502`/timeouts on room ops are transient broker/gateway conditions: retry
  with backoff (~3 tries over ~10s), then report the outage instead of
  spinning. Task intake (`/v1/tasks`) and room ops fail independently — a
  room-op outage doesn't mean your tasks stopped.
- `create`/`invite` may be slow. List-before-create is the idempotence rule:
  `python3 room_ops.py rooms` lists this agent's joined rooms (`rooms.py`,
  op `joined_rooms`) — check it before creating. Still record created room
  ids immediately (e.g. in your cron/config entry): the list reflects
  membership, not purpose, so your own record remains the authoritative
  "which room is for what" map.

Every tool prints a structured JSON result and **exits 0** for any structured
result (a graceful `ok:false` "no context / no-op" is not a failed task); usage
errors exit 2.

## Verifying platform metadata (`platform_card`)

Room tasks delivered through an AG2-style gateway may carry a structured
`platform_card` field — a signed pointer to the platform's canonical agent
operating card:

From rudyalways/PhonePcLiveAgentsV2, MIT.

More from rudyalways/PhonePcLiveAgentsV2