@mcsherrylabs/pi-meerkat

Pi agent extension: announce a channel you control onto the meerkat announcements registry, and search what others have announced. Owns the announcement wire contract; wraps @mcsherrylabs/pi-evolver for the chain and the content cache.

Packages

Package details

extensionskill

Install @mcsherrylabs/pi-meerkat from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@mcsherrylabs/pi-meerkat

Package: @mcsherrylabs/pi-meerkat
Version: 0.4.3
Published: Oct 9, 2026
Downloads: 1,338/mo · 52/wk
Author: alanmcsherry
License: Apache-2.0
Types: extension, skill
Size: 92.4 KB
Dependencies: 3 dependencies · 0 peers

Pi manifest JSON

{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@mcsherrylabs/pi-meerkat

Pi agent tools for the meerkat announcements registry: announce a channel you control, and search what others have announced.

pi-meerkat  ──▶  @mcsherrylabs/pi-evolver  ──▶  @mcsherrylabs/evolver-client
  the service's verbs      chain + content, generic        the wire

Why this is a separate package

pi-evolver forbids a tool from naming a channel, a ledger or a service, and fails its build for it — a draft of its content tool was rejected for the word "announcement". That rule is what keeps it chain-generic, and it is also what says where a service's own verbs belong: here, in the service's own repository, installed by whoever wants them. A new service becomes usable by an agent with nothing central edited.

Tools

tool	what it answers
`meerkat_summary`	start here — counts, kinds, keywords, misses, and which channel this registry indexes
`meerkat_services`	search by keyword or free text
`meerkat_service`	one entry in full, with its `provenance`
`meerkat_detail`	the announced document, digest-verified by the registry
`meerkat_rejections`	why an announcement was refused
`meerkat_announce`	describe a channel you control, optionally with a document
`meerkat_inbox`	what arrived on a channel this node subscribes to and no handler claimed — the event inbox

Three things that are deliberate

The document is published before the announcement, inside the tool. An announcement names its document by key and digest. Announce first and the entry refers to bytes that exist nowhere — permanently unfetchable, indistinguishable from a document that is merely slow, and every detail document on this estate was in that state until it was found. Two composable tools would put that ordering in a model's hands. meerkat_announce takes the text.

The document is published OPEN. Anyone who obtains the key may read it. That is right for a public index, and with the announcements channel no longer carrying a DA group there is no group left to grant to. Do not announce anything whose disclosure depends on a key staying private.

The channel is configuration, not a parameter. REGISTRY_CHANNEL — the same variable the registry reads, so the two cannot disagree. A model with a free-text channel field will eventually fill it from something it read, and an announcement is charged and permanent.

Configuration

variable	what
`MEERKAT_URL`	the event processor's read server — the registry's routes and the inbox — e.g. `http://registry:8090`. `REGISTRY_URL`, its name before 0.3.0, is refused: every read answers `misconfigured` until it is renamed
`REGISTRY_CHANNEL`	the channel to announce onto and read (default `ce.meerkat.announcements`)
`EVOLVER_URL`, `EVOLVER_IDENTITY`, `EVOLVER_KEY_PATH`	from pi-evolver — who signs
`EVOLVER_CONTENT_URL`	from pi-evolver — required only to announce a document

The read tools need no chain at all: an agent with no signing key can still search the index.

The contract lives here

src/contract.ts is the announcement wire format — bounds, types and the body builder. It is in this package rather than in the app so a client can announce without depending on the whole registry, and so there is one encoding rather than two. Pure: no chain, no clock, no I/O.

npm run check:contract   # the encoding and every bound, with nothing running
npm run check:surface    # the tool table's properties

Version 0.4.2 pins pi-evolver 0.9.0 and evolver-client 0.19.0 to share the corrected identity-key lookup. Configure the agent API endpoint to evolver-node v0.24.1+ before using that lookup. The announcement and inbox contracts are unchanged.