agent-harness 0.44.41 → 0.45.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: b2db7196758b674a453ebbd3d80801a4a99a263cd2b882229b00ad35670df5a0
4
- data.tar.gz: '0958fd2f98cbc1ed6bede11948648ab4f0e63484616fd820fc4ca150eb784754'
3
+ metadata.gz: 4f2004d675674e14c6e5a576cf0be58500a35ddbcdd6d471b06b4b923396ec10
4
+ data.tar.gz: 5956bd3ac995b7b826a358e2e9cd8aba877c3543f424ffce1fa713c528bffd9f
5
5
  SHA512:
6
- metadata.gz: d55dfa100bf3c7bb89d00800f35692610bf2910e343a4ddbb0b2d9a71792583c6b5811efa0cf454ce2eeb902175dbbe09bc65900df60f3562caf8da1120ab2c9
7
- data.tar.gz: ce6d513734809e9f3a1c724c64b58afeb2854c34e1d70637eb36c4f51476df1ae3d9638b4adfefefd01c87d059e00ed1f119f62143f6647fba6c23b472982cee
6
+ metadata.gz: dead89358aec49e2d5c60e0f80580b5000e01eb71ce1628b37362ff3421e85d00752b83aa94dad0d4fa0ee05e065d5b9172fc961cf53ed1c05e8554298907c9f
7
+ data.tar.gz: 249c4e9743254ee4b9dda86150378269bdc8c86553bbc69a0002aa6c2aa3c5db91a4b797526f0e6e044f7ce5ffb3701d9b929b4ae91ad7e27be2cdcd60afea8a
@@ -1,3 +1,3 @@
1
1
  {
2
- ".": "0.44.41"
2
+ ".": "0.45.0"
3
3
  }
data/CHANGELOG.md CHANGED
@@ -16,6 +16,13 @@
16
16
 
17
17
  * close the RDR-072 upstream epic from #437's retained-scope evidence while keeping unpublished capabilities and downstream adoption behind their explicit release and integration gates ([#430](https://github.com/viamin/agent-harness/issues/430)).
18
18
 
19
+ ## [0.45.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.44.41...agent-harness/v0.45.0) (2026-11-21)
20
+
21
+
22
+ ### Features
23
+
24
+ * **api:** provide a public JSON codec for chat transport events and results ([#555](https://github.com/viamin/agent-harness/issues/555)) ([7cfe3cb](https://github.com/viamin/agent-harness/commit/7cfe3cb1303014d51d8855e814657685e21dffbe))
25
+
19
26
  ## [0.44.41](https://github.com/viamin/agent-harness/compare/agent-harness/v0.44.40...agent-harness/v0.44.41) (2026-11-21)
20
27
 
21
28
 
@@ -74,6 +74,44 @@ tool calls with `status: :partial`; incomplete calls MUST NOT be executed.
74
74
  Schema success is determined by the locally validated parsed value and does not
75
75
  require conversational prose.
76
76
 
77
+ ### JSON wire codec
78
+
79
+ `AgentHarness::Api::ChatWireCodec` is the public boundary for relaying these
80
+ events and results through JSON. `dump_event`/`load_event` and
81
+ `dump_result`/`load_result` produce and consume a versioned envelope. The lower
82
+ level `to_wire(value, kind:)` and `from_wire(wire, expected_kind:)` helpers are
83
+ available when a container protocol already owns JSON generation or parsing.
84
+
85
+ For a JSONL container, write one event per line and a final result line:
86
+
87
+ ```ruby
88
+ codec = AgentHarness::Api::ChatWireCodec
89
+ result = AgentHarness::Api::ChatTransport.new.call(request) do |event|
90
+ output.puts(codec.dump_event(event))
91
+ end
92
+ output.puts(codec.dump_result(result))
93
+
94
+ # In the parent process:
95
+ record = JSON.parse(line)
96
+ case record.fetch("kind")
97
+ when "event" then handle_event(codec.from_wire(record, expected_kind: :event))
98
+ when "result" then result = codec.from_wire(record, expected_kind: :result)
99
+ end
100
+ ```
101
+
102
+ Wire version `1` is the compatibility boundary. Additive object members may be
103
+ added without changing the version; version-1 readers ignore members they do
104
+ not own. Removing or renaming fields, changing field meaning, or adding an enum
105
+ value requires a new wire version. Readers reject unsupported versions and
106
+ unknown contract enums with `ChatWireCodec::ProtocolError`.
107
+
108
+ The decoder has byte, nesting, and node-count limits suitable for an untrusted
109
+ container boundary. Its errors describe only the failed contract rule and
110
+ never echo values from the payload. It restores symbols only for documented
111
+ contract enums and keys. In particular, `parsed`, `provider_state`, and
112
+ `arguments_json` remain opaque: enum-looking strings inside tool arguments,
113
+ application values, or provider continuation data stay strings. The codec does
114
+ not load Rails, execute tools, or grant tool approval.
77
115
  Streamed tool-call arguments are emitted as raw, appendable JSON fragments
78
116
  correlated to one `tool_call_started` event per provider call, and cumulative
79
117
  provider token counts are emitted as deduplicated `usage_updated` events. An
@@ -0,0 +1,288 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require_relative "attempt_report"
5
+
6
+ module AgentHarness
7
+ module Api
8
+ # Versioned JSON wire codec for ChatTransport events and terminal results.
9
+ # It restores only fields owned by the public chat contract; parsed tool
10
+ # values and provider continuation state remain opaque JSON values.
11
+ module ChatWireCodec
12
+ VERSION = 1
13
+ DEFAULT_MAX_BYTES = 4 * 1024 * 1024
14
+ DEFAULT_MAX_DEPTH = 64
15
+ DEFAULT_MAX_NODES = 50_000
16
+
17
+ EVENT_TYPES = %i[
18
+ response_started text_delta tool_call_started tool_call_delta tool_call_completed
19
+ usage_updated attempt_completed fallback_selected response_completed response_failed response_cancelled
20
+ ].freeze
21
+ RESULT_STATUSES = %i[succeeded partial failed cancelled].freeze
22
+ TOOL_STATUSES = %i[completed incomplete].freeze
23
+ PROVIDERS = %i[anthropic openai].freeze
24
+ PROTOCOLS = %i[messages responses chat_completions].freeze
25
+ AUTHENTICATION_MODES = %i[api_key].freeze
26
+ FINISH_REASONS = %i[stop tool_calls max_tokens length content_filter refusal].freeze
27
+ ERROR_CATEGORIES = %i[
28
+ transient authentication authorization billing invalid_request unsupported invalid_response
29
+ context_length configuration cancelled unknown
30
+ ].freeze
31
+ ERROR_CODES = %i[
32
+ timeout connection_failed rate_limited server_error service_unavailable overloaded
33
+ invalid_credential permission_denied billing_unavailable context_length_exceeded invalid_request
34
+ unsupported_capability structured_output_not_supported invalid_tool_arguments invalid_json invalid_schema
35
+ refusal truncated_output empty_response invalid_configuration cancelled unclassified_provider_error
36
+ ].freeze
37
+ USAGE_KEYS = AttemptReport::USAGE_KEYS
38
+ COST_KEYS = AttemptReport::COST_KEYS + %i[currency source priced_at]
39
+ RESULT_KEYS = %i[
40
+ request_id provider model protocol authentication_mode status content parsed tool_calls provider_state
41
+ finish_reason refusal usage error attempts provider_request_id
42
+ ].freeze
43
+ EVENT_KEYS = %i[
44
+ type request_id attempt_id sequence candidate content id provider_id name arguments_json
45
+ input_tokens output_tokens cache_read_tokens cache_write_tokens thinking_tokens total_tokens
46
+ attempt from to error result
47
+ ].freeze
48
+
49
+ class ProtocolError < StandardError; end
50
+
51
+ module_function
52
+
53
+ def dump_event(event, **limits) = JSON.generate(to_wire(event, kind: :event, **limits))
54
+ def dump_result(result, **limits) = JSON.generate(to_wire(result, kind: :result, **limits))
55
+ def load_event(json, **limits) = load(json, expected_kind: :event, **limits)
56
+ def load_result(json, **limits) = load(json, expected_kind: :result, **limits)
57
+
58
+ def to_wire(value, kind:, **limits)
59
+ wire = JSON.parse(JSON.generate(version: VERSION, kind: kind.to_s, payload: value))
60
+ from_wire(wire, expected_kind: kind, **limits)
61
+ wire
62
+ rescue ProtocolError
63
+ raise
64
+ rescue JSON::GeneratorError, TypeError
65
+ invalid!("value is not JSON-compatible")
66
+ end
67
+
68
+ def from_wire(wire, expected_kind: nil, max_bytes: DEFAULT_MAX_BYTES,
69
+ max_depth: DEFAULT_MAX_DEPTH, max_nodes: DEFAULT_MAX_NODES)
70
+ bound_structure!(wire, max_bytes:, max_depth:, max_nodes:)
71
+ envelope = object!(wire, "envelope")
72
+ invalid!("unsupported version") unless fetch(envelope, :version) == VERSION
73
+ kind = enum(fetch(envelope, :kind), %i[event result], "payload kind")
74
+ invalid!("unexpected payload kind") if expected_kind && kind != expected_kind.to_sym
75
+
76
+ payload = fetch(envelope, :payload)
77
+ (kind == :event) ? decode_event(payload) : decode_result(payload)
78
+ rescue ProtocolError
79
+ raise
80
+ rescue NoMethodError, TypeError, ArgumentError
81
+ invalid!("invalid structure")
82
+ end
83
+
84
+ def load(json, expected_kind:, max_bytes: DEFAULT_MAX_BYTES, **limits)
85
+ invalid!("input must be a JSON string") unless json.is_a?(String)
86
+ invalid!("input exceeds byte limit") if json.bytesize > max_bytes
87
+
88
+ from_wire(JSON.parse(json, max_nesting: limits.fetch(:max_depth, DEFAULT_MAX_DEPTH)),
89
+ expected_kind:, max_bytes:, **limits)
90
+ rescue JSON::ParserError
91
+ invalid!("malformed JSON")
92
+ end
93
+ private_class_method :load
94
+
95
+ def decode_event(payload)
96
+ source = object!(payload, "event")
97
+ event = copy_keys(source, EVENT_KEYS)
98
+ event[:type] = enum(event[:type], EVENT_TYPES, "event type")
99
+ required!(event, :request_id, "event")
100
+ required!(event, :attempt_id, "event")
101
+ positive_integer!(event[:sequence], "event sequence")
102
+ event[:candidate] = decode_candidate(event[:candidate]) if event.key?(:candidate)
103
+ event[:from] = decode_candidate(event[:from]) if event.key?(:from)
104
+ event[:to] = decode_candidate(event[:to]) if event.key?(:to)
105
+ event[:error] = decode_error(event[:error]) if event[:error]
106
+ event[:attempt] = decode_attempt(event[:attempt]) if event.key?(:attempt)
107
+ event[:result] = decode_result(event[:result]) if event.key?(:result)
108
+ validate_event_payload!(event)
109
+ event
110
+ end
111
+ private_class_method :decode_event
112
+
113
+ def validate_event_payload!(event)
114
+ required = case event[:type]
115
+ when :response_started then %i[candidate]
116
+ when :text_delta then %i[content]
117
+ when :tool_call_started then %i[id name]
118
+ when :tool_call_delta then %i[id arguments_json]
119
+ when :tool_call_completed then %i[id name arguments_json]
120
+ when :attempt_completed then %i[attempt]
121
+ when :fallback_selected then %i[from to error]
122
+ when :response_completed, :response_failed, :response_cancelled then %i[result]
123
+ else []
124
+ end
125
+ required.each { |key| required!(event, key, "#{event[:type]} event") }
126
+ end
127
+ private_class_method :validate_event_payload!
128
+
129
+ def decode_result(payload)
130
+ source = object!(payload, "result")
131
+ result = copy_keys(source, RESULT_KEYS)
132
+ required!(result, :request_id, "result")
133
+ result[:status] = enum(result[:status], RESULT_STATUSES, "result status")
134
+ result[:provider] = nullable_enum(result[:provider], PROVIDERS, "result provider")
135
+ result[:protocol] = nullable_enum(result[:protocol], PROTOCOLS, "result protocol")
136
+ result[:authentication_mode] = nullable_enum(result[:authentication_mode], AUTHENTICATION_MODES,
137
+ "result authentication mode")
138
+ result[:finish_reason] = nullable_enum(result[:finish_reason], FINISH_REASONS, "result finish reason")
139
+ result[:refusal] = boolean(result[:refusal], "result refusal") if result.key?(:refusal)
140
+ result[:usage] = decode_usage(result[:usage]) if result[:usage]
141
+ result[:error] = decode_error(result[:error]) if result[:error]
142
+ result[:tool_calls] = array!(result[:tool_calls], "result tool_calls").map { |call| decode_tool_call(call) }
143
+ result[:attempts] = array!(result[:attempts], "result attempts").map { |attempt| decode_attempt(attempt) }
144
+ result
145
+ end
146
+ private_class_method :decode_result
147
+
148
+ def decode_candidate(value)
149
+ candidate = copy_keys(object!(value, "candidate"), %i[provider model protocol authentication_mode])
150
+ candidate[:provider] = enum(candidate[:provider], PROVIDERS, "candidate provider")
151
+ candidate[:protocol] = enum(candidate[:protocol], PROTOCOLS, "candidate protocol")
152
+ candidate[:authentication_mode] = enum(candidate[:authentication_mode], AUTHENTICATION_MODES,
153
+ "candidate authentication mode")
154
+ candidate
155
+ end
156
+ private_class_method :decode_candidate
157
+
158
+ def decode_tool_call(value)
159
+ call = copy_keys(object!(value, "tool call"), %i[id provider_id name arguments_json status])
160
+ %i[id name arguments_json].each { |key| required!(call, key, "tool call") }
161
+ call[:status] = enum(call[:status], TOOL_STATUSES, "tool call status")
162
+ call
163
+ end
164
+ private_class_method :decode_tool_call
165
+
166
+ def decode_attempt(value)
167
+ attempt = copy_keys(object!(value, "attempt"), %i[
168
+ attempt_id request_id number provider model status started_at finished_at usage cost provider_reported
169
+ finish_reason refusal error
170
+ ])
171
+ attempt[:provider] = enum(attempt[:provider], PROVIDERS, "attempt provider")
172
+ attempt[:status] = enum(attempt[:status], AttemptReport::STATUSES, "attempt status")
173
+ attempt[:usage] = decode_usage(attempt[:usage]) if attempt[:usage]
174
+ attempt[:cost] = decode_cost(attempt[:cost]) if attempt[:cost]
175
+ if attempt.key?(:finish_reason)
176
+ attempt[:finish_reason] = nullable_enum(attempt[:finish_reason], FINISH_REASONS, "attempt finish reason")
177
+ end
178
+ attempt[:refusal] = boolean(attempt[:refusal], "attempt refusal") if attempt.key?(:refusal)
179
+ attempt[:error] = decode_error(attempt[:error]) if attempt[:error]
180
+ diagnostics = attempt.slice(:finish_reason, :refusal)
181
+ report = AttemptReport.from_h(attempt.except(:finish_reason, :refusal)).to_h
182
+ report.merge(diagnostics).merge(error: attempt[:error])
183
+ rescue ArgumentError
184
+ invalid!("invalid attempt report")
185
+ end
186
+ private_class_method :decode_attempt
187
+
188
+ def decode_usage(value) = copy_keys(object!(value, "usage"), USAGE_KEYS)
189
+
190
+ def decode_cost(value)
191
+ cost = copy_keys(object!(value, "cost"), COST_KEYS)
192
+ cost[:source] = enum(cost[:source], %i[provider_reported estimated], "cost source")
193
+ cost
194
+ end
195
+ private_class_method :decode_cost
196
+
197
+ def decode_error(value)
198
+ error = copy_keys(object!(value, "error"), %i[
199
+ category code retryable message retry_after_seconds finish_reason refusal
200
+ ])
201
+ error[:category] = enum(error[:category], ERROR_CATEGORIES, "error category")
202
+ error[:code] = enum(error[:code], ERROR_CODES, "error code")
203
+ if error.key?(:finish_reason)
204
+ error[:finish_reason] = nullable_enum(error[:finish_reason], FINISH_REASONS, "error finish reason")
205
+ end
206
+ error[:refusal] = boolean(error[:refusal], "error refusal") if error.key?(:refusal)
207
+ error
208
+ end
209
+ private_class_method :decode_error
210
+
211
+ def bound_structure!(root, max_bytes:, max_depth:, max_nodes:)
212
+ invalid!("invalid limits") unless [max_bytes, max_depth, max_nodes].all? { |limit| limit.is_a?(Integer) && limit.positive? }
213
+ nodes = 0
214
+ bytes = 0
215
+ pending = [[root, 1]]
216
+ until pending.empty?
217
+ value, depth = pending.pop
218
+ invalid!("nesting exceeds limit") if depth > max_depth
219
+ nodes += 1
220
+ invalid!("node count exceeds limit") if nodes > max_nodes
221
+ bytes += value.bytesize if value.is_a?(String)
222
+ value.each_key { |key| bytes += key.bytesize if key.is_a?(String) } if value.is_a?(Hash)
223
+ invalid!("content exceeds byte limit") if bytes > max_bytes
224
+ children = if value.is_a?(Hash)
225
+ value.values
226
+ elsif value.is_a?(Array)
227
+ value
228
+ else
229
+ []
230
+ end
231
+ children.each { |child| pending << [child, depth + 1] }
232
+ end
233
+ end
234
+ private_class_method :bound_structure!
235
+
236
+ def object!(value, name)
237
+ invalid!("#{name} must be an object") unless value.is_a?(Hash)
238
+ value
239
+ end
240
+ private_class_method :object!
241
+
242
+ def array!(value, name)
243
+ invalid!("#{name} must be an array") unless value.is_a?(Array)
244
+ value
245
+ end
246
+ private_class_method :array!
247
+
248
+ def copy_keys(source, keys)
249
+ keys.each_with_object({}) do |key, result|
250
+ result[key] = fetch(source, key) if source.key?(key) || source.key?(key.to_s)
251
+ end
252
+ end
253
+ private_class_method :copy_keys
254
+
255
+ def fetch(source, key) = source.key?(key) ? source[key] : source[key.to_s]
256
+ private_class_method :fetch
257
+
258
+ def enum(value, allowed, name)
259
+ match = allowed.find { |entry| entry.to_s == value.to_s }
260
+ invalid!("invalid #{name}") unless match
261
+ match
262
+ end
263
+ private_class_method :enum
264
+
265
+ def nullable_enum(value, allowed, name) = value.nil? ? nil : enum(value, allowed, name)
266
+ private_class_method :nullable_enum
267
+
268
+ def boolean(value, name)
269
+ invalid!("invalid #{name}") unless value == true || value == false
270
+ value
271
+ end
272
+ private_class_method :boolean
273
+
274
+ def required!(hash, key, name)
275
+ invalid!("missing #{name} #{key}") if !hash.key?(key) || hash[key].nil? || hash[key] == ""
276
+ end
277
+ private_class_method :required!
278
+
279
+ def positive_integer!(value, name)
280
+ invalid!("invalid #{name}") unless value.is_a?(Integer) && value.positive?
281
+ end
282
+ private_class_method :positive_integer!
283
+
284
+ def invalid!(reason) = raise(ProtocolError, "invalid chat wire payload: #{reason}")
285
+ private_class_method :invalid!
286
+ end
287
+ end
288
+ end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module AgentHarness
4
- VERSION = "0.44.41"
4
+ VERSION = "0.45.0"
5
5
  end
data/lib/agent_harness.rb CHANGED
@@ -472,6 +472,7 @@ require_relative "agent_harness/text_transport"
472
472
  require_relative "agent_harness/openai_compatible_transport"
473
473
  require_relative "agent_harness/conversation"
474
474
  require_relative "agent_harness/api/attempt_report"
475
+ require_relative "agent_harness/api/chat_wire_codec"
475
476
  require_relative "agent_harness/api/chat_transport"
476
477
  require_relative "agent_harness/api/schema_response"
477
478
  require_relative "agent_harness/quota_status"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: agent-harness
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.44.41
4
+ version: 0.45.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Bart Agapinan
@@ -145,6 +145,7 @@ files:
145
145
  - lib/agent_harness.rb
146
146
  - lib/agent_harness/api/attempt_report.rb
147
147
  - lib/agent_harness/api/chat_transport.rb
148
+ - lib/agent_harness/api/chat_wire_codec.rb
148
149
  - lib/agent_harness/api/provider_error_detail.rb
149
150
  - lib/agent_harness/api/ruby_llm_chat_adapter.rb
150
151
  - lib/agent_harness/api/schema_response.rb