AtlatestRenderedmarkdown

apiary / treeCLAUDE.md

Read the source

Readme

Apiary — AI Worker Instructions

Apiary is an MCP server for Enclave-based agent coordination. Read this file before making changes.

Define ordering discipline

Every Sigil library file in apiary follows this order inside (begin ...):

  1. Type / struct definitions
  2. Constants
  3. Pure helpers (no upward references)
  4. Internal procedures (may call helpers)
  5. Public entry points
  6. Tool registration functions LAST (they reference everything above)

Forward references from tool-registration functions to helpers defined later in the file have caused silent crashes in related Sigil work. With this discipline, those bugs cannot recur — the offending code wouldn't compile.

Trusted set filter

Every bot applies the same channel-message filter:

trusted_set = {owner} ∪ {reports-to} ∪ {subordinates} ∪ {listened peers}

IF sender ∈ trusted_set THEN
  IF message starts with "@<my-nick>: "     → deliver as mention
  IF message starts with "@<other-nick>: "  → ignore
  ELSE                                       → deliver as broadcast
ELSE
  ignore

A bot does NOT receive its own messages — apiary suppresses self-echo before MCP delivery.

Mention syntax

Strict @<nick>: <body> in IRC. The @ is mandatory and disambiguates from any colon use in bodies. Apiary adds the @ automatically when an agent calls send-channel mention: "<nick>". MCP-delivered messages do NOT use @ — they use <sender>: <body> format because apiary controls that side end-to-end.

Build conventions

  • sigil build apiary -c release --backend bytecode for releases (the native backend currently breaks on a sigil-crypto ABI drift; bytecode-release is the workaround until that's fixed).
  • Always force-rebuild with --force when changing code that may be cached: sigil build apiary -c release --backend bytecode --force.
  • Confirm the build touched changed files: look for COMPILE apiary/<file>.sgl in the build output.

Testing

Local smoke harness at test/smoke.sh boots a throwaway local enclave server, runs apiary against it, and exercises:

  • Bridge connect + reconnect presence
  • Trusted-set filtering (broadcast / mention to me / mention to other / non-trusted sender)
  • listen-peer / unlisten-peer mechanics
  • Group-based voicing
  • MCP sender-mention rewriting
  • Self-echo suppression
  • Tool registration completeness for both leader and worker modes

Unit tests in test/*.sgl for individual module behavior.

License & Copyright

BSD-3-Clause.