praxo-core 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4975c4a8d241b094789de25f7bf80ab08b442d154abb816c7bb54b30c5400784
4
- data.tar.gz: d43f996a431634a84484de307d0dd4668e8052d99d61c2f8fdc7853683e51760
3
+ metadata.gz: 6b720116e91a4927eacec6a64291d1f9d7ae845e6d1d3e2f55af7dfeb11a21bd
4
+ data.tar.gz: a4da48da732eb8cf41a303ad09a8d91d0ba0d17e4d6a57da1d2a9c7fe2bd1305
5
5
  SHA512:
6
- metadata.gz: a9f62729753be864c1bf4f19cc8fa1536f418944efb39d81cf43c0c10e9066a737132bbe64465ea1a3a4434c9adca191678f05a011543da64e7339dc178f9818
7
- data.tar.gz: 6117c0418bb0e50d88683ef9bbbdc6d836f18d48cb3b167f5410dc35a7c05d83914dc84a95805a69f2f5a71b8258000a26d4b299fcb9c1124d278f6cd0dedb10
6
+ metadata.gz: 69c1fb1c50aaa2ca8adb3e55030a12f2563be7e974e0c92967e6cda12167803d945b83d6a1968c1be3eda23f0f17e7c3ccd17869a45149d2f5a6c456dad61880
7
+ data.tar.gz: c688bf1bbae8f98aa6a6890822213806203a20d77fedea103376b0dedb64c9d9a42bfc99eb8f7e628820a7cebd3c975056ee4eb9eec86d9321065a15f9840620
data/README.md CHANGED
@@ -21,7 +21,7 @@ reference implementation.
21
21
  - Registry introduction: [REGISTRY.md](https://github.com/axisvela/praxo-core/blob/main/language/ruby/REGISTRY.md)
22
22
  - Machine-readable entry: [llms.txt](https://github.com/axisvela/praxo-core/blob/main/language/ruby/llms.txt) and [llms.md](https://github.com/axisvela/praxo-core/blob/main/language/ruby/llms.md)
23
23
  - Coding-agent contract: [docs/getting-started/coding-agents.md](https://github.com/axisvela/praxo-core/blob/main/docs/getting-started/coding-agents.md)
24
- - Registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.4.1)
24
+ - Registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.5.0)
25
25
 
26
26
  ## Install
27
27
 
@@ -132,5 +132,5 @@ before emitting.
132
132
 
133
133
  ## Release
134
134
 
135
- Tag shape: `ruby/v0.4.1`. The tag targets `SPEC_VERSION` `0.2.0`. See
135
+ Tag shape: `ruby/v0.7.0`. The tag targets `SPEC_VERSION` `0.2.0`. See
136
136
  [CHANGELOG.md](CHANGELOG.md) for per-release changes and compatibility notes.
data/REGISTRY.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # PRAXO-CORE Ruby Registry Introduction
2
2
 
3
- **Status:** published; split source repository. Source version `0.5.0`, source
4
- tag `ruby/v0.5.0`. Published registry version: `0.4.1`. Registry
3
+ **Status:** published; split source repository. Source version `0.7.0`, source
4
+ tag `ruby/v0.7.0`. Published registry version: `0.5.0`. Registry
5
5
  pages are release snapshots; verify the published version before relying on a
6
6
  feature.
7
7
 
@@ -14,16 +14,29 @@ PRAXO-CORE is an embeddable, MIT-licensed agent framework. This gem is its nativ
14
14
  | Field | Value |
15
15
  | --- | --- |
16
16
  | Package | `praxo-core` |
17
- | Registry | [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.4.1) |
18
- | Source version | `0.5.0` |
19
- | Published registry version | `0.4.1` |
17
+ | Registry | [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.5.0) |
18
+ | Source version | `0.7.0` |
19
+ | Published registry version | `0.5.0` |
20
20
  | Install (published) | `gem install praxo-core` |
21
21
  | Install (source/release prepared) | `gem install praxo-core` |
22
- | Source tag | `ruby/v0.5.0` |
22
+ | Source tag | `ruby/v0.7.0` |
23
23
  | Tier | Core |
24
24
  | Contract | `SPEC_VERSION` `0.2.0` |
25
25
  | Documentation | https://axisvela.github.io/praxo-core/languages/ruby/ |
26
26
 
27
+ ## Capabilities and Status
28
+
29
+ | Adapter | Status | Detail |
30
+ | --- | --- | --- |
31
+ | OpenAI-compatible model | native | `Praxo::Adapters::OpenAICompatible` |
32
+ | Anthropic model | native | `Praxo::Adapters::Anthropic`; injectable transport |
33
+ | Gemini model | native | `Praxo::Adapters::Gemini`; injectable transport |
34
+ | MCP client | native | `Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26 |
35
+ | Harmovela sink | native | `Praxo::Adapters::HarmovelaSink` |
36
+ | OpenTelemetry sink | native (transport seam) | `OtelSink`; caller supplies OTLP/HTTP transport |
37
+ | Subagent delegation | native | `Delegation::SubagentManager` |
38
+ | Retriever | native | `Document`, `FuncRetriever` |
39
+
27
40
  ## Coding-agent entry
28
41
 
29
42
  - [llms.txt](llms.txt): compact machine-readable entry for this language.
data/api/0.6.0.txt ADDED
@@ -0,0 +1,122 @@
1
+ # PRAXO-CORE Ruby API 0.6.0
2
+ # SPEC_VERSION 0.2.0
3
+
4
+ class AgentOptions
5
+ class CallLimit
6
+ class CheckpointAllowlist
7
+ class ContextBudget
8
+ class Error
9
+ class FilterSink
10
+ class FuncTool
11
+ class MemoryStore
12
+ class MultiSink
13
+ class PathChecker
14
+ class PiiRedactor
15
+ class Runner
16
+ class StaticModel
17
+ class StructuredOutput
18
+ class ToolRegistry
19
+ class ToolSelection
20
+ def action
21
+ def after_run
22
+ def allowed?
23
+ def allows?
24
+ def apply
25
+ def apply_interrupt
26
+ def array
27
+ def as_int
28
+ def as_object
29
+ def as_string
30
+ def authorize
31
+ def before_model
32
+ def before_run
33
+ def before_tool
34
+ def bool
35
+ def check
36
+ def check_cancelled
37
+ def check_enum
38
+ def check_keys
39
+ def compact
40
+ def content_block
41
+ def decision
42
+ def emit
43
+ def emit_stream
44
+ def equals
45
+ def error
46
+ def error_code
47
+ def estimate_tokens
48
+ def event
49
+ def execute_tool
50
+ def extract_json
51
+ def fallback_model
52
+ def filter
53
+ def generate
54
+ def get
55
+ def has?
56
+ def initialize
57
+ def int
58
+ def interrupt
59
+ def interrupt_decision
60
+ def invoke
61
+ def invoke_tool
62
+ def invoke_tools
63
+ def marshal
64
+ def memory_record
65
+ def message
66
+ def message_assistant
67
+ def message_text
68
+ def message_tool
69
+ def message_wire
70
+ def parse
71
+ def parse_input_json
72
+ def parse_json_call
73
+ def parse_manifest
74
+ def parse_plain
75
+ def parse_tag
76
+ def parse_toolcall
77
+ def parse_xml
78
+ def plus
79
+ def prepare_tool
80
+ def put
81
+ def redact
82
+ def redact_value
83
+ def register
84
+ def reject
85
+ def request
86
+ def resolve_path
87
+ def response
88
+ def run
89
+ def run_agent
90
+ def run_result
91
+ def search
92
+ def session
93
+ def specs
94
+ def stream_part
95
+ def string
96
+ def stringify
97
+ def strip_markup
98
+ def structured_apply
99
+ def text_present
100
+ def tool_call
101
+ def tool_spec
102
+ def truncate_to_tokens
103
+ def unmarshal
104
+ def usage
105
+ def validate
106
+ def visit
107
+ def visit_array
108
+ def visit_boolean
109
+ def visit_number
110
+ def visit_object
111
+ def visit_string
112
+ def within?
113
+ module Agent
114
+ module Json
115
+ module JsonSchema
116
+ module Middleware
117
+ module Models
118
+ module Plugin
119
+ module Praxo
120
+ module Runtime
121
+ module SSE
122
+ module Toolcall
data/api/0.7.0.txt ADDED
@@ -0,0 +1,135 @@
1
+ # PRAXO-CORE Ruby API 0.7.0
2
+ # SPEC_VERSION 0.2.0
3
+
4
+ class AgentOptions
5
+ class CallLimit
6
+ class CheckpointAllowlist
7
+ class ContextBudget
8
+ class Error
9
+ class FilterSink
10
+ class FuncRetriever
11
+ class FuncTool
12
+ class MemoryStore
13
+ class MultiSink
14
+ class PathChecker
15
+ class PiiRedactor
16
+ class Runner
17
+ class StaticModel
18
+ class StructuredOutput
19
+ class SubagentManager
20
+ class ToolRegistry
21
+ class ToolSelection
22
+ def action
23
+ def after_run
24
+ def allowed?
25
+ def allows?
26
+ def apply
27
+ def apply_interrupt
28
+ def array
29
+ def as_int
30
+ def as_object
31
+ def as_string
32
+ def authorize
33
+ def before_model
34
+ def before_run
35
+ def before_tool
36
+ def bool
37
+ def cancel
38
+ def check
39
+ def check_cancelled
40
+ def check_enum
41
+ def check_keys
42
+ def compact
43
+ def content_block
44
+ def copy
45
+ def decision
46
+ def emit
47
+ def emit_stream
48
+ def equals
49
+ def error
50
+ def error_code
51
+ def estimate_tokens
52
+ def event
53
+ def execute
54
+ def execute_tool
55
+ def extract_json
56
+ def fallback_model
57
+ def filter
58
+ def generate
59
+ def get
60
+ def has?
61
+ def initialize
62
+ def int
63
+ def interrupt
64
+ def interrupt_decision
65
+ def invoke
66
+ def invoke_tool
67
+ def invoke_tools
68
+ def launch
69
+ def marshal
70
+ def memory_record
71
+ def message
72
+ def message_assistant
73
+ def message_text
74
+ def message_tool
75
+ def message_wire
76
+ def parse
77
+ def parse_input_json
78
+ def parse_json_call
79
+ def parse_manifest
80
+ def parse_plain
81
+ def parse_tag
82
+ def parse_toolcall
83
+ def parse_xml
84
+ def plus
85
+ def prepare_tool
86
+ def put
87
+ def redact
88
+ def redact_value
89
+ def register
90
+ def reject
91
+ def request
92
+ def resolve_path
93
+ def response
94
+ def retrieve
95
+ def run
96
+ def run_agent
97
+ def run_result
98
+ def search
99
+ def session
100
+ def set
101
+ def specs
102
+ def stream_part
103
+ def string
104
+ def stringify
105
+ def strip_markup
106
+ def structured_apply
107
+ def text_present
108
+ def timestamp
109
+ def to_wire
110
+ def tool_call
111
+ def tool_spec
112
+ def truncate_to_tokens
113
+ def unmarshal
114
+ def update
115
+ def usage
116
+ def validate
117
+ def visit
118
+ def visit_array
119
+ def visit_boolean
120
+ def visit_number
121
+ def visit_object
122
+ def visit_string
123
+ def wait
124
+ def within?
125
+ module Agent
126
+ module Delegation
127
+ module Json
128
+ module JsonSchema
129
+ module Middleware
130
+ module Models
131
+ module Plugin
132
+ module Praxo
133
+ module Runtime
134
+ module SSE
135
+ module Toolcall
@@ -10,13 +10,16 @@ module Praxo
10
10
 
11
11
  attr_reader :protocol_version, :server_info
12
12
 
13
- def initialize(command: nil, args: [], env: {}, timeout: 5, reader: nil, writer: nil)
13
+ def initialize(command: nil, args: [], env: {}, timeout: 5, reader: nil, writer: nil,
14
+ transport: nil, protocol_version: DEFAULT_PROTOCOL_VERSION)
14
15
  @command = command
15
16
  @args = args
16
17
  @env = env
17
18
  @timeout = timeout
18
19
  @reader = reader
19
20
  @writer = writer
21
+ @transport = transport
22
+ @protocol_version = protocol_version
20
23
  @next_id = 0
21
24
  @closed = false
22
25
  @connected = false
@@ -25,7 +28,7 @@ module Praxo
25
28
  def start
26
29
  return self if @connected
27
30
 
28
- if @reader.nil? || @writer.nil?
31
+ if @transport.nil? && (@reader.nil? || @writer.nil?)
29
32
  raise Praxo::Error.new('MCP_TRANSPORT', 'mcp: command is required') if @command.nil?
30
33
 
31
34
  @stdin, @stdout, @stderr, @wait = Open3.popen3(@env, @command, *@args)
@@ -33,9 +36,9 @@ module Praxo
33
36
  @reader = @stdout
34
37
  end
35
38
  result = request('initialize', {
36
- protocolVersion: DEFAULT_PROTOCOL_VERSION,
39
+ protocolVersion: @protocol_version,
37
40
  capabilities: {},
38
- clientInfo: { name: 'praxo-core', version: '0.5.0' }
41
+ clientInfo: { name: 'praxo-core', version: '0.6.0' }
39
42
  })
40
43
  version = result.is_a?(Hash) ? result['protocolVersion'] : nil
41
44
  if version.nil? || version.empty?
@@ -92,6 +95,15 @@ module Praxo
92
95
  return if @closed
93
96
 
94
97
  @closed = true
98
+ if @transport
99
+ begin
100
+ @transport.close
101
+ rescue StandardError
102
+ nil
103
+ end
104
+ @connected = false
105
+ return
106
+ end
95
107
  begin
96
108
  @writer.close if @writer && !@writer.closed?
97
109
  rescue IOError
@@ -125,6 +137,8 @@ module Praxo
125
137
  def request(method, params, timeout: nil)
126
138
  raise Praxo::Error.new('MCP_CLOSED', 'mcp: client is closed') if @closed
127
139
 
140
+ return @transport.request(method, params, timeout: timeout || @timeout) if @transport
141
+
128
142
  @next_id += 1
129
143
  id = @next_id
130
144
  write({ jsonrpc: '2.0', id: id, method: method, params: params })
@@ -157,6 +171,7 @@ module Praxo
157
171
 
158
172
  def notify(method, params)
159
173
  return if @closed
174
+ return @transport.notify(method, params) if @transport
160
175
 
161
176
  write({ jsonrpc: '2.0', method: method, params: params })
162
177
  end
@@ -0,0 +1,158 @@
1
+ require 'json'
2
+ require 'net/http'
3
+ require 'uri'
4
+
5
+ module Praxo
6
+ module Adapters
7
+ # Streamable HTTP MCP transport (2025-03-26).
8
+ class HttpMCPTransport
9
+ def initialize(endpoint, headers: {}, protocol_version: '2025-03-26', timeout: 30)
10
+ @uri = URI.parse(endpoint)
11
+ unless %w[http https].include?(@uri.scheme)
12
+ raise Praxo::Error.new('MCP_TRANSPORT', 'mcp: invalid HTTP endpoint')
13
+ end
14
+ if @uri.scheme == 'http' && !self.class.loopback?(@uri.host)
15
+ raise Praxo::Error.new('MCP_TRANSPORT', 'mcp: HTTP endpoint must use HTTPS')
16
+ end
17
+
18
+ @headers = headers
19
+ @protocol_version = protocol_version
20
+ @timeout = timeout
21
+ @session_id = ''
22
+ @next_id = 0
23
+ @closed = false
24
+ end
25
+
26
+ def request(method, params, timeout: nil)
27
+ raise Praxo::Error.new('MCP_CLOSED', 'mcp: client is closed') if @closed
28
+
29
+ @next_id += 1
30
+ message = {
31
+ jsonrpc: '2.0',
32
+ id: @next_id,
33
+ method: method,
34
+ params: params
35
+ }
36
+ response = post(message, timeout || @timeout)
37
+ if response['error']
38
+ detail = response['error'].is_a?(Hash) ? response['error']['message'] : 'JSON-RPC error'
39
+ raise Praxo::Error.new('MCP_RPC', "mcp: #{method} failed: #{detail}")
40
+ end
41
+ result = response['result'] || {}
42
+ unless result.is_a?(Hash)
43
+ raise Praxo::Error.new('MCP_PROTOCOL', "mcp: #{method} result must be an object")
44
+ end
45
+ result
46
+ end
47
+
48
+ def notify(method, params)
49
+ return if @closed
50
+
51
+ post({ jsonrpc: '2.0', method: method, params: params }, @timeout)
52
+ end
53
+
54
+ def close
55
+ return if @closed
56
+
57
+ @closed = true
58
+ return if @session_id.empty?
59
+
60
+ begin
61
+ request = Net::HTTP::Delete.new(@uri)
62
+ apply_headers(request)
63
+ Net::HTTP.start(
64
+ @uri.host,
65
+ @uri.port,
66
+ use_ssl: @uri.scheme == 'https',
67
+ read_timeout: @timeout
68
+ ) { |http| http.request(request) }
69
+ rescue StandardError
70
+ nil
71
+ end
72
+ end
73
+
74
+ def self.loopback?(host)
75
+ value = host.to_s.downcase
76
+ ['localhost', '127.0.0.1', '::1', '[::1]'].include?(value) || value.start_with?('127.')
77
+ end
78
+
79
+ private
80
+
81
+ def post(message, timeout)
82
+ request = Net::HTTP::Post.new(@uri)
83
+ request.body = JSON.generate(message)
84
+ apply_headers(request)
85
+ response = Net::HTTP.start(
86
+ @uri.host,
87
+ @uri.port,
88
+ use_ssl: @uri.scheme == 'https',
89
+ read_timeout: timeout
90
+ ) { |http| http.request(request) }
91
+ session = response['mcp-session-id']
92
+ @session_id = session unless session.nil? || session.empty?
93
+ status = response.code.to_i
94
+ body = response.body.to_s
95
+ return {} if [202, 204].include?(status) || body.strip.empty?
96
+ if status < 200 || status >= 300
97
+ raise Praxo::Error.new('MCP_TRANSPORT', "mcp: HTTP #{status}: #{body[0, 512]}")
98
+ end
99
+
100
+ decoded = if response['content-type'].to_s.downcase.include?('text/event-stream')
101
+ parse_sse(body, message[:id] || message['id'])
102
+ else
103
+ parse_json(body, message[:id] || message['id'])
104
+ end
105
+ version = decoded.dig('result', 'protocolVersion')
106
+ @protocol_version = version if version.is_a?(String) && !version.empty?
107
+ decoded
108
+ end
109
+
110
+ def apply_headers(request)
111
+ request['Content-Type'] = 'application/json'
112
+ request['Accept'] = 'application/json, text/event-stream'
113
+ request['MCP-Protocol-Version'] = @protocol_version
114
+ request['MCP-Session-Id'] = @session_id unless @session_id.empty?
115
+ @headers.each { |key, value| request[key] = value }
116
+ end
117
+
118
+ def parse_json(body, id)
119
+ decoded = JSON.parse(body)
120
+ raise Praxo::Error.new('MCP_PROTOCOL', 'mcp: server sent invalid JSON') unless decoded.is_a?(Hash)
121
+
122
+ decoded
123
+ rescue JSON::ParserError
124
+ raise Praxo::Error.new('MCP_PROTOCOL', 'mcp: server sent invalid JSON')
125
+ end
126
+
127
+ def parse_sse(body, id)
128
+ messages = []
129
+ data = []
130
+ body.split(/\r\n|\n|\r/).each do |line|
131
+ if line.empty?
132
+ unless data.empty?
133
+ messages << decode_message(data.join("\n"))
134
+ data = []
135
+ end
136
+ next
137
+ end
138
+ next if line.start_with?(':')
139
+ data << line[5..].to_s.lstrip if line.start_with?('data:')
140
+ end
141
+ messages << decode_message(data.join("\n")) unless data.empty?
142
+ return messages.find { |item| item['id'] == id } || messages.first unless messages.empty?
143
+
144
+ raise Praxo::Error.new('MCP_PROTOCOL', 'mcp: response contained no message')
145
+ end
146
+
147
+ def decode_message(text)
148
+ decoded = JSON.parse(text)
149
+ unless decoded.is_a?(Hash)
150
+ raise Praxo::Error.new('MCP_PROTOCOL', 'mcp: server sent a non-object message')
151
+ end
152
+ decoded
153
+ rescue JSON::ParserError
154
+ raise Praxo::Error.new('MCP_PROTOCOL', 'mcp: server sent invalid SSE JSON')
155
+ end
156
+ end
157
+ end
158
+ end
@@ -0,0 +1,121 @@
1
+ require 'net/http'
2
+ require 'time'
3
+ require 'uri'
4
+ require_relative '../errors'
5
+ require_relative '../json'
6
+
7
+ module Praxo
8
+ module Adapters
9
+ class OtelSink
10
+ MAX_BODY = 512
11
+
12
+ def initialize(endpoint: 'http://127.0.0.1:4318/v1/traces',
13
+ service_name: 'praxo-core', transport: nil,
14
+ allowed_data_keys: [], timeout: 10)
15
+ @endpoint = endpoint.to_s.empty? ? 'http://127.0.0.1:4318/v1/traces' : endpoint
16
+ @service_name = service_name.to_s.empty? ? 'praxo-core' : service_name
17
+ @transport = transport
18
+ @allowed_data_keys = Array(allowed_data_keys).map(&:to_s)
19
+ @timeout = timeout
20
+ end
21
+
22
+ def emit(event)
23
+ now = Time.now.utc
24
+ stamp = otel_stamp(event, now)
25
+ nanos = now.to_i * 1_000_000_000 + now.nsec
26
+ data = event.data || {}
27
+ key = [event.session_id, event.run_id, event.type,
28
+ Json.stringify(data)].join('|')
29
+ trace_id = [2166136261, 3307539480, 1540483477, 2807494644]
30
+ .map { |seed| hex32(fnv1a(key, seed)) }.join
31
+ span_key = "#{key}|span"
32
+ span_id = [2166136261, 3307539480]
33
+ .map { |seed| hex32(fnv1a(span_key, seed)) }.join
34
+ attributes = [attribute('praxo.event.type', event.type)]
35
+ if event.session_id && !event.session_id.empty?
36
+ attributes << attribute('praxo.session.id', event.session_id)
37
+ end
38
+ if event.run_id && !event.run_id.empty?
39
+ attributes << attribute('praxo.run.id', event.run_id)
40
+ end
41
+ attributes << attribute('praxo.event.at', stamp)
42
+ @allowed_data_keys.each do |name|
43
+ next unless data.key?(name)
44
+
45
+ attributes << attribute("praxo.event.data.#{name}", otel_text(data[name]))
46
+ end
47
+ payload = {
48
+ 'resourceSpans' => [{
49
+ 'resource' => {
50
+ 'attributes' => [attribute('service.name', @service_name)]
51
+ },
52
+ 'scopeSpans' => [{
53
+ 'scope' => { 'name' => 'praxo-core' },
54
+ 'spans' => [{
55
+ 'traceId' => trace_id,
56
+ 'spanId' => span_id,
57
+ 'name' => "praxo.#{event.type}",
58
+ 'kind' => 1,
59
+ 'startTimeUnixNano' => nanos.to_s,
60
+ 'endTimeUnixNano' => nanos.to_s,
61
+ 'attributes' => attributes
62
+ }]
63
+ }]
64
+ }]
65
+ }
66
+ body = Json.stringify(payload)
67
+ headers = { 'content-type' => 'application/json' }
68
+ status, response_body = @transport ? @transport.call(@endpoint, body, headers) : post(body, headers)
69
+ return if status.to_i >= 200 && status.to_i < 300
70
+
71
+ bounded = response_body.to_s[0, MAX_BODY]
72
+ Praxo.error('OTEL_HTTP', "otel: HTTP #{status}: #{bounded}")
73
+ end
74
+
75
+ private
76
+
77
+ def otel_stamp(event, now)
78
+ if event.respond_to?(:at) && event.at
79
+ event.at.to_s
80
+ else
81
+ now.iso8601(9)
82
+ end
83
+ end
84
+
85
+ def attribute(key, value)
86
+ { 'key' => key, 'value' => { 'stringValue' => value.to_s } }
87
+ end
88
+
89
+ def otel_text(value)
90
+ value.is_a?(String) ? value : Json.stringify(value)
91
+ end
92
+
93
+ def fnv1a(text, seed)
94
+ value = seed & 0xFFFFFFFF
95
+ text.to_s.bytes.each do |byte|
96
+ value ^= byte
97
+ value = (value * 16_777_619) & 0xFFFFFFFF
98
+ end
99
+ value
100
+ end
101
+
102
+ def hex32(value)
103
+ format('%08x', value & 0xFFFFFFFF)
104
+ end
105
+
106
+ def post(body, headers)
107
+ uri = URI.parse(@endpoint)
108
+ request = Net::HTTP::Post.new(uri)
109
+ headers.each { |key, value| request[key] = value }
110
+ request.body = body
111
+ response = Net::HTTP.start(
112
+ uri.host,
113
+ uri.port,
114
+ use_ssl: uri.scheme == 'https',
115
+ read_timeout: @timeout
116
+ ) { |http| http.request(request) }
117
+ [response.code.to_i, response.body.to_s]
118
+ end
119
+ end
120
+ end
121
+ end
@@ -0,0 +1,150 @@
1
+ require_relative 'errors'
2
+
3
+ module Praxo
4
+ module Delegation
5
+ SubagentRequest = Struct.new(
6
+ :parent_session_id, :agent_id, :prompt, :context, :mode, :history,
7
+ keyword_init: true
8
+ )
9
+ SubagentResult = Struct.new(
10
+ :task_id, :agent_id, :output, :usage, keyword_init: true
11
+ )
12
+ SubagentTask = Struct.new(
13
+ :id, :parent_session_id, :agent_id, :mode, :status, :output, :error,
14
+ :created_at, :updated_at, keyword_init: true
15
+ )
16
+
17
+ class SubagentManager
18
+ TERMINAL = %w[completed failed canceled].freeze
19
+
20
+ def initialize(runner)
21
+ @runner = runner
22
+ @tasks = {}
23
+ @mutex = Mutex.new
24
+ @condition = ConditionVariable.new
25
+ @sequence = 0
26
+ end
27
+
28
+ def launch(request)
29
+ raise Praxo::Error.new('SUBAGENT_INVALID', 'agent: subagent runner is required') if @runner.nil?
30
+
31
+ parent = request.parent_session_id.to_s
32
+ agent = request.agent_id.to_s
33
+ if parent.empty? || agent.empty?
34
+ raise Praxo::Error.new(
35
+ 'SUBAGENT_INVALID',
36
+ 'agent: subagent parent session and agent id are required'
37
+ )
38
+ end
39
+ id = @mutex.synchronize { @sequence += 1; "subagent-#{@sequence}" }
40
+ now = timestamp
41
+ task = SubagentTask.new(
42
+ id: id, parent_session_id: parent, agent_id: agent,
43
+ mode: request.mode || 'isolated', status: 'queued',
44
+ output: '', error: '', created_at: now, updated_at: now
45
+ )
46
+ @mutex.synchronize { @tasks[id] = { task: task, done: false } }
47
+ Thread.new { execute(id, request) }
48
+ copy(task)
49
+ end
50
+
51
+ def check(task_id)
52
+ @mutex.synchronize do
53
+ state = @tasks[task_id]
54
+ state.nil? ? nil : copy(state[:task])
55
+ end
56
+ end
57
+
58
+ def wait(task_id, timeout = nil)
59
+ deadline = timeout.nil? ? nil : Time.now + timeout
60
+ @mutex.synchronize do
61
+ state = @tasks[task_id]
62
+ raise Praxo::Error.new('SUBAGENT_NOT_FOUND', "agent: unknown subagent task \"#{task_id}\"") if state.nil?
63
+
64
+ until state[:done]
65
+ if deadline.nil?
66
+ @condition.wait(@mutex)
67
+ else
68
+ remaining = deadline - Time.now
69
+ if remaining <= 0
70
+ raise Praxo::Error.new(
71
+ 'SUBAGENT_TIMEOUT',
72
+ 'agent: subagent wait timed out'
73
+ )
74
+ end
75
+ @condition.wait(@mutex, remaining)
76
+ end
77
+ end
78
+ copy(state[:task])
79
+ end
80
+ end
81
+
82
+ def update(task_id, prompt)
83
+ unless @runner.respond_to?(:update)
84
+ raise Praxo::Error.new(
85
+ 'SUBAGENT_UPDATE_UNSUPPORTED',
86
+ 'agent: subagent update unsupported'
87
+ )
88
+ end
89
+ @mutex.synchronize do
90
+ state = @tasks[task_id]
91
+ raise Praxo::Error.new('SUBAGENT_NOT_FOUND', "agent: unknown subagent task \"#{task_id}\"") if state.nil?
92
+ unless state[:task].status == 'running'
93
+ raise Praxo::Error.new(
94
+ 'SUBAGENT_NOT_RUNNING',
95
+ "agent: subagent task \"#{task_id}\" is not running"
96
+ )
97
+ end
98
+ end
99
+ @runner.update(task_id, prompt)
100
+ end
101
+
102
+ def cancel(task_id)
103
+ @mutex.synchronize do
104
+ state = @tasks[task_id]
105
+ raise Praxo::Error.new('SUBAGENT_NOT_FOUND', "agent: unknown subagent task \"#{task_id}\"") if state.nil?
106
+ return if TERMINAL.include?(state[:task].status)
107
+
108
+ state[:task].status = 'canceled'
109
+ state[:task].updated_at = timestamp
110
+ state[:done] = true
111
+ @condition.broadcast
112
+ end
113
+ end
114
+
115
+ private
116
+
117
+ def execute(task_id, request)
118
+ set(task_id, 'running')
119
+ result = @runner.run(request)
120
+ set(task_id, 'completed', output: result.output.to_s)
121
+ rescue StandardError => error
122
+ set(task_id, 'failed', error: error.message)
123
+ end
124
+
125
+ def set(task_id, status, output: '', error: '')
126
+ @mutex.synchronize do
127
+ state = @tasks[task_id]
128
+ return if state.nil? || TERMINAL.include?(state[:task].status)
129
+
130
+ state[:task].status = status
131
+ state[:task].output = output
132
+ state[:task].error = error
133
+ state[:task].updated_at = timestamp
134
+ if TERMINAL.include?(status)
135
+ state[:done] = true
136
+ @condition.broadcast
137
+ end
138
+ end
139
+ end
140
+
141
+ def copy(task)
142
+ SubagentTask.new(**task.to_h)
143
+ end
144
+
145
+ def timestamp
146
+ Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
147
+ end
148
+ end
149
+ end
150
+ end
@@ -0,0 +1,22 @@
1
+ module Praxo
2
+ Document = Struct.new(:id, :content, :metadata, :score, keyword_init: true) do
3
+ def to_wire
4
+ out = { 'id' => id, 'content' => content }
5
+ out['metadata'] = metadata if metadata && !metadata.empty?
6
+ out['score'] = score if score && score != 0
7
+ out
8
+ end
9
+ end
10
+
11
+ class FuncRetriever
12
+ def initialize(&block)
13
+ raise ArgumentError, 'retriever: block is required' unless block
14
+
15
+ @block = block
16
+ end
17
+
18
+ def retrieve(query, limit)
19
+ @block.call(query.to_s, limit.to_i)
20
+ end
21
+ end
22
+ end
data/lib/praxo.rb CHANGED
@@ -12,4 +12,8 @@ require_relative 'praxo/adapters/openai_compatible'
12
12
  require_relative 'praxo/adapters/anthropic'
13
13
  require_relative 'praxo/adapters/gemini'
14
14
  require_relative 'praxo/adapters/mcp'
15
+ require_relative 'praxo/adapters/mcp_http'
15
16
  require_relative 'praxo/adapters/harmovela_sink'
17
+ require_relative 'praxo/retriever'
18
+ require_relative 'praxo/delegation'
19
+ require_relative 'praxo/adapters/otel_sink'
data/llms.md CHANGED
@@ -7,16 +7,27 @@
7
7
  ## Package
8
8
 
9
9
  - package: `praxo-core`
10
- - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.4.1)
11
- - source_version: `0.5.0`
12
- - published_version: `0.4.1`
10
+ - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.5.0)
11
+ - source_version: `0.7.0`
12
+ - published_version: `0.5.0`
13
13
  - install_published: `gem install praxo-core`
14
14
  - install_source: `gem install praxo-core`
15
- - source_tag: `ruby/v0.5.0`
15
+ - source_tag: `ruby/v0.7.0`
16
16
  - tier: Core
17
17
  - contract: `SPEC_VERSION` `0.2.0`
18
18
  - documentation: https://axisvela.github.io/praxo-core/languages/ruby/
19
19
 
20
+ ## Capabilities and Status
21
+
22
+ - OpenAI-compatible model: native (`Praxo::Adapters::OpenAICompatible`)
23
+ - Anthropic model: native (`Praxo::Adapters::Anthropic`; injectable transport)
24
+ - Gemini model: native (`Praxo::Adapters::Gemini`; injectable transport)
25
+ - MCP client: native (`Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26)
26
+ - Harmovela sink: native (`Praxo::Adapters::HarmovelaSink`)
27
+ - OpenTelemetry sink: native (transport seam) (`OtelSink`; caller supplies OTLP/HTTP transport)
28
+ - Subagent delegation: native (`Delegation::SubagentManager`)
29
+ - Retriever: native (`Document`, `FuncRetriever`)
30
+
20
31
  ## Start
21
32
 
22
33
  - README: `README.md`
data/llms.txt CHANGED
@@ -7,16 +7,27 @@
7
7
  # Package
8
8
 
9
9
  - package: `praxo-core`
10
- - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.4.1)
11
- - source_version: `0.5.0`
12
- - published_version: `0.4.1`
10
+ - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.5.0)
11
+ - source_version: `0.7.0`
12
+ - published_version: `0.5.0`
13
13
  - install_published: `gem install praxo-core`
14
14
  - install_source: `gem install praxo-core`
15
- - source_tag: `ruby/v0.5.0`
15
+ - source_tag: `ruby/v0.7.0`
16
16
  - tier: Core
17
17
  - contract: `SPEC_VERSION` `0.2.0`
18
18
  - documentation: https://axisvela.github.io/praxo-core/languages/ruby/
19
19
 
20
+ # Capabilities and Status
21
+
22
+ - OpenAI-compatible model: native (`Praxo::Adapters::OpenAICompatible`)
23
+ - Anthropic model: native (`Praxo::Adapters::Anthropic`; injectable transport)
24
+ - Gemini model: native (`Praxo::Adapters::Gemini`; injectable transport)
25
+ - MCP client: native (`Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26)
26
+ - Harmovela sink: native (`Praxo::Adapters::HarmovelaSink`)
27
+ - OpenTelemetry sink: native (transport seam) (`OtelSink`; caller supplies OTLP/HTTP transport)
28
+ - Subagent delegation: native (`Delegation::SubagentManager`)
29
+ - Retriever: native (`Document`, `FuncRetriever`)
30
+
20
31
  # Start
21
32
 
22
33
  - README: `README.md`
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: praxo-core
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AxisVela
@@ -26,19 +26,25 @@ files:
26
26
  - api/0.4.0.txt
27
27
  - api/0.4.1.txt
28
28
  - api/0.5.0.txt
29
+ - api/0.6.0.txt
30
+ - api/0.7.0.txt
29
31
  - lib/praxo.rb
30
32
  - lib/praxo/adapters/anthropic.rb
31
33
  - lib/praxo/adapters/gemini.rb
32
34
  - lib/praxo/adapters/harmovela_sink.rb
33
35
  - lib/praxo/adapters/mcp.rb
36
+ - lib/praxo/adapters/mcp_http.rb
34
37
  - lib/praxo/adapters/openai_compatible.rb
38
+ - lib/praxo/adapters/otel_sink.rb
35
39
  - lib/praxo/agent.rb
40
+ - lib/praxo/delegation.rb
36
41
  - lib/praxo/errors.rb
37
42
  - lib/praxo/json.rb
38
43
  - lib/praxo/jsonschema.rb
39
44
  - lib/praxo/middleware.rb
40
45
  - lib/praxo/models.rb
41
46
  - lib/praxo/plugin.rb
47
+ - lib/praxo/retriever.rb
42
48
  - lib/praxo/runtime.rb
43
49
  - lib/praxo/sse.rb
44
50
  - lib/praxo/toolcall.rb