Capabilities

A capability is a named, integer-versioned set of tools. Each tool declares a transfer mechanism and JSON Schemas generated by schemars: one for the request, one for the response, and — for streaming tools — one for the stream item.

Announcing

Announcement is an ordinary request, available to either peer after hello_ack:

{ "t": "req", "id": 1, "method": "zyris.announce", "params": {
  "capabilities": [
    { "name": "terminal", "version": 3,
      "tools": [
        { "name": "exec", "description": "Run a command to completion.",
          "transfer": "unary",
          "request_schema": { }, "response_schema": { } },
        { "name": "open_stream", "description": "Open an interactive PTY output stream.",
          "transfer": "uni_stream",
          "request_schema": { }, "response_schema": { }, "item_schema": { } } ] } ] } }

{ "t": "res", "id": 1, "result": {
  "accepted": ["terminal"],
  "rejected": [ { "name": "attacca_api", "reason": "reserved" } ] } }

A tool descriptor may also carry a call_limit — how long a caller should wait for the answer, in seconds, or unlimited. When it is absent the caller applies its own default.

Rules

• zyris.announce is full-replacement and idempotent. Announcing again without a capability that was announced before revokes it; changing capabilities mid-session is just a new announce. Revocation fails in-flight calls on that capability with capability_unavailable.
• Calling a tool of a capability the peer has not announced fails with capability_not_announced.
• A deployment may reserve capability names to itself, rejecting them from nodes with capability_rejected, reason reserved.
• A node may announce two versions of the same capability at once, as two entries.
• Additive tool changes within a version are permitted. Consumers discover tools by descriptor.

Attacca's reserved capability

Attacca reserves exactly one name, attacca_api. It rejects that name from any node and announces it itself immediately after hello_ack. The current zyris-attacca surface lists all tools regardless of the credential grant; tools other than me are scope-checked per call. An announcement is not authorization. See scope checking.

The capability is declared in the zyris-attacca crate. It is the deployment's surface, not the wire's, and the one capability a node only ever calls — which is why it is a crate of its own rather than part of the standard catalogue. See Consuming attacca_api.