module

Arcana::Protocol

Handshake protocol for agent/service communication.

Messages follow a simple envelope convention where the payload contains protocol metadata prefixed with _. This keeps the protocol transparent — any envelope can be a protocol message, and non-protocol envelopes work fine too.

Flow:

  1. Sender sends a request payload
  2. Recipient replies with result, need, or error
  3. If need, sender provides more info and goto 2

Discovery: send a {"tool": "help"} payload (or a Protocol.request wrapping one) to any address to get its capabilities. Services auto-respond via Arcana::Service's help handler; Toolsets return a tools manifest via their auto-registered help tool.

Constants

VERSION = "arcana/1"

Class methods

data(payload : JSON::Any) : JSON::Any | Nil

Extract the data field.

Source
error(message : String, code : String | Nil = nil) : JSON::Any

Signal an error.

Source
error?(payload : JSON::Any) : Bool
Source
message(payload : JSON::Any) : String | Nil

Extract the message field (for need/error).

Source
need(schema : JSON::Any | Nil = nil, questions : Array(String) | Nil = nil, message : String | Nil = nil) : JSON::Any

Signal that more information is needed. Services send their schema. Agents can send natural language questions.

Source
need?(payload : JSON::Any) : Bool
Source
proto?(payload : JSON::Any) : Bool

Is this a protocol-formatted payload?

Source
request(data : JSON::Any) : JSON::Any

Wrap data as a request payload.

Source
request?(payload : JSON::Any) : Bool
Source
result(data : JSON::Any) : JSON::Any

Wrap data as a successful result payload.

Source
result?(payload : JSON::Any) : Bool
Source
status(payload : JSON::Any) : String | Nil

Extract the status field.

Source