Module: Kernai::Protocol

Defined in:
lib/kernai/protocol.rb

Overview

Registry of external protocols an agent can address directly via block types. A protocol is any structured, extensible interface (MCP, A2A, custom in-house systems, …) that doesn’t fit the “local Ruby skill” model: each registered protocol claims a block type, and the Kernel dispatches matching blocks to its handler.

Conceptually: ‘command` invokes a Skill, `<protocol_name>` invokes a Protocol. Both return their payload in <block type=“result” name=“…”>. Kernai itself knows nothing about any specific protocol — adapters register themselves from outside the core.

Defined Under Namespace

Classes: Registration

Constant Summary collapse

CORE_BLOCK_TYPES =

Block types owned by the kernel’s own protocol. Registrations cannot shadow them, otherwise the dispatcher would become ambiguous.

%i[command final plan json result error].freeze

Class Method Summary collapse

Class Method Details

.all ⇒ Object 



60
61
62
 
# File 'lib/kernai/protocol.rb', line 60

def all
  @mutex.synchronize { @handlers.values.map(&:dup) }
end

.documentation_for(name) ⇒ Object 



54
55
56
57
58
 
# File 'lib/kernai/protocol.rb', line 54

def documentation_for(name)
  return nil if name.nil?

  @mutex.synchronize { @handlers[name.to_sym]&.documentation }
end

.handler_for(name) ⇒ Object 



48
49
50
51
52
 
# File 'lib/kernai/protocol.rb', line 48

def handler_for(name)
  return nil if name.nil?

  @mutex.synchronize { @handlers[name.to_sym]&.handler }
end

.names ⇒ Object 



64
65
66
 
# File 'lib/kernai/protocol.rb', line 64

def names
  @mutex.synchronize { @handlers.keys }
end

.register(name, documentation: nil, &handler) ⇒ Object

Raises:

  • (ArgumentError) 


22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/kernai/protocol.rb', line 22

def register(name, documentation: nil, &handler)
  raise ArgumentError, 'protocol name is required' if name.nil? || name.to_s.strip.empty?
  raise ArgumentError, 'protocol handler block is required' unless block_given?

  sym = name.to_sym
  if CORE_BLOCK_TYPES.include?(sym)
    raise ArgumentError, "cannot register protocol ':#{sym}' — reserved core block type"
  end

  @mutex.synchronize do
    @handlers[sym] = Registration.new(
      name: sym,
      documentation: documentation,
      handler: handler
    )
  end

  sym
end

.registered?(name) ⇒ Boolean

Returns:

  • (Boolean) 


42
43
44
45
46
 
# File 'lib/kernai/protocol.rb', line 42

def registered?(name)
  return false if name.nil?

  @mutex.synchronize { @handlers.key?(name.to_sym) }
end

.reset! ⇒ Object 



74
75
76
 
# File 'lib/kernai/protocol.rb', line 74

def reset!
  @mutex.synchronize { @handlers.clear }
end

.unregister(name) ⇒ Object 



68
69
70
71
72
 
# File 'lib/kernai/protocol.rb', line 68

def unregister(name)
  return nil if name.nil?

  @mutex.synchronize { @handlers.delete(name.to_sym) }
end