harnex 0.12.0 → 0.29.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.
Files changed (73) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +592 -0
  3. data/GUIDE.md +222 -68
  4. data/README.md +78 -48
  5. data/TECHNICAL.md +235 -98
  6. data/agents/gpt.md +60 -0
  7. data/docs/agents.md +119 -0
  8. data/docs/dispatch-telemetry.md +184 -50
  9. data/docs/events.md +20 -7
  10. data/docs/lanes.md +202 -0
  11. data/docs/mcp.md +102 -0
  12. data/docs/pi-rpc.md +81 -7
  13. data/docs/upgrading-to-0.29.md +87 -0
  14. data/guides/01_dispatch.md +101 -34
  15. data/guides/04_monitoring.md +223 -25
  16. data/guides/05_naming.md +0 -1
  17. data/guides/06_claude.md +96 -0
  18. data/lib/harnex/adapters/base.rb +4 -8
  19. data/lib/harnex/adapters/pi.rb +92 -12
  20. data/lib/harnex/adapters.rb +1 -16
  21. data/lib/harnex/artifact_report.rb +206 -12
  22. data/lib/harnex/cli.rb +68 -50
  23. data/lib/harnex/commands/ask.rb +278 -0
  24. data/lib/harnex/commands/delegate.rb +202 -0
  25. data/lib/harnex/commands/doctor.rb +34 -36
  26. data/lib/harnex/commands/events.rb +3 -3
  27. data/lib/harnex/commands/history.rb +2 -8
  28. data/lib/harnex/commands/land.rb +150 -0
  29. data/lib/harnex/commands/lanes.rb +84 -0
  30. data/lib/harnex/commands/logs.rb +3 -3
  31. data/lib/harnex/commands/mcp.rb +208 -0
  32. data/lib/harnex/commands/orchestration.rb +88 -9
  33. data/lib/harnex/commands/pane.rb +3 -3
  34. data/lib/harnex/commands/preflight.rb +566 -0
  35. data/lib/harnex/commands/reply.rb +125 -0
  36. data/lib/harnex/commands/result.rb +108 -0
  37. data/lib/harnex/commands/run.rb +248 -64
  38. data/lib/harnex/commands/send.rb +121 -16
  39. data/lib/harnex/commands/status.rb +32 -4
  40. data/lib/harnex/commands/stop.rb +14 -4
  41. data/lib/harnex/commands/telemetry.rb +19 -1
  42. data/lib/harnex/commands/wait.rb +421 -56
  43. data/lib/harnex/commands/watch.rb +134 -21
  44. data/lib/harnex/context_file.rb +85 -0
  45. data/lib/harnex/core.rb +100 -15
  46. data/lib/harnex/dispatch_history.rb +157 -10
  47. data/lib/harnex/lanes.rb +513 -0
  48. data/lib/harnex/mcp.rb +362 -0
  49. data/lib/harnex/orchestration.rb +128 -5
  50. data/lib/harnex/owned_process_group.rb +50 -0
  51. data/lib/harnex/owner_stream.rb +399 -0
  52. data/lib/harnex/pricing.rb +4 -9
  53. data/lib/harnex/runtime/activity_tracker.rb +107 -0
  54. data/lib/harnex/runtime/api_server.rb +11 -1
  55. data/lib/harnex/runtime/completion_notifier.rb +90 -11
  56. data/lib/harnex/runtime/inbox.rb +26 -7
  57. data/lib/harnex/runtime/message.rb +5 -2
  58. data/lib/harnex/runtime/runtime_budget.rb +96 -0
  59. data/lib/harnex/runtime/session.rb +684 -294
  60. data/lib/harnex/runtime/stop_request.rb +39 -0
  61. data/lib/harnex/stall.rb +46 -0
  62. data/lib/harnex/telemetry_reconciler.rb +42 -20
  63. data/lib/harnex/terminal_status.rb +5 -5
  64. data/lib/harnex/version.rb +2 -2
  65. data/lib/harnex.rb +16 -0
  66. data/recipes/01_fire_and_watch.md +14 -14
  67. data/recipes/02_chain_implement.md +35 -31
  68. data/recipes/03_buddy.md +1 -1
  69. metadata +34 -12
  70. data/docs/codex-appserver.md +0 -175
  71. data/lib/harnex/adapters/codex.rb +0 -160
  72. data/lib/harnex/adapters/codex_appserver.rb +0 -407
  73. data/lib/harnex/codex/app_server/client.rb +0 -347
@@ -1,347 +0,0 @@
1
- require "json"
2
- require "open3"
3
-
4
- module Harnex
5
- module Codex
6
- module AppServer
7
- # Extracted from Adapters::CodexAppServer per issue #41 Slice A.
8
- # Pure move; behavior unchanged.
9
- class Client
10
- attr_reader :pid
11
-
12
- def initialize(read_io:, write_io:, pid: nil)
13
- @read_io = read_io
14
- @write_io = write_io
15
- @pid = pid
16
- @next_id = 1
17
- @pending = {}
18
- @id_mutex = Mutex.new
19
- @write_mutex = Mutex.new
20
- @notification_handler = nil
21
- @request_handler = nil
22
- @disconnect_handler = nil
23
- @disconnect_signaled = false
24
- @closed = false
25
- @reader_thread = nil
26
- end
27
-
28
- def on_notification(&block)
29
- @notification_handler = block
30
- end
31
-
32
- # Handler for server-initiated requests (id + method). The block
33
- # receives (method, params) and returns the response body for the
34
- # JSON-RPC `result` field, or nil to reject with -32601.
35
- def on_request(&block)
36
- @request_handler = block
37
- end
38
-
39
- def on_disconnect(&block)
40
- @disconnect_handler = block
41
- end
42
-
43
- def start
44
- @reader_thread = Thread.new { read_loop }
45
- end
46
-
47
- def request(method, params = {})
48
- raise "codex_appserver client is closed" if @closed
49
-
50
- queue = Queue.new
51
- id = @id_mutex.synchronize do
52
- assigned = @next_id
53
- @next_id += 1
54
- @pending[assigned] = queue
55
- assigned
56
- end
57
-
58
- write_line({ jsonrpc: "2.0", id: id, method: method, params: params })
59
- result = queue.pop
60
- raise result if result.is_a?(Exception)
61
-
62
- result
63
- end
64
-
65
- def notify(method, params = {})
66
- return if @closed
67
-
68
- write_line({ jsonrpc: "2.0", method: method, params: params })
69
- end
70
-
71
- def close
72
- return if @closed
73
-
74
- @closed = true
75
-
76
- @id_mutex.synchronize do
77
- @pending.each_value { |q| q.push(StandardError.new("codex_appserver client closed")) }
78
- @pending.clear
79
- end
80
-
81
- begin
82
- @write_io.close unless @write_io.closed?
83
- rescue IOError
84
- nil
85
- end
86
-
87
- if @pid && process_alive?(@pid)
88
- sleep 0.05
89
- begin
90
- Process.kill("TERM", @pid)
91
- rescue Errno::ESRCH
92
- nil
93
- end
94
- end
95
-
96
- @reader_thread&.join(2)
97
- end
98
-
99
- def terminate_process(term_grace_seconds:, kill_grace_seconds:)
100
- return false unless @pid
101
-
102
- begin
103
- Process.kill("TERM", @pid)
104
- rescue Errno::ESRCH
105
- return true
106
- end
107
-
108
- return true if wait_for_process_exit(@pid, term_grace_seconds)
109
-
110
- begin
111
- Process.kill("KILL", @pid)
112
- rescue Errno::ESRCH
113
- return true
114
- end
115
-
116
- wait_for_process_exit(@pid, kill_grace_seconds)
117
- end
118
-
119
- # Plan 30 Phase 2 — deployment-fallback subprocess restart.
120
- #
121
- # Spawns a `codex app-server` subprocess against a deployment_config
122
- # and wraps it in a fresh Client. Caller is responsible for wiring
123
- # handlers and running the JSON-RPC handshake — or use
124
- # `spawn_with_fallback` for the full restart-with-resume flow.
125
- def self.spawn(deployment_config:)
126
- command = deployment_config[:command] || deployment_config["command"]
127
- raise ArgumentError, "deployment_config requires :command" if command.nil? || Array(command).empty?
128
-
129
- env = deployment_config[:env] || deployment_config["env"] || {}
130
- cwd = deployment_config[:cwd] || deployment_config["cwd"]
131
-
132
- opts = {}
133
- opts[:chdir] = cwd if cwd
134
-
135
- stdin_io, stdout_io, _stderr_io, wait_thr = Open3.popen3(env, *Array(command), **opts)
136
- new(read_io: stdout_io, write_io: stdin_io, pid: wait_thr.pid)
137
- end
138
-
139
- # Plan 30 Phase 2 — full subprocess restart for deployment fallback.
140
- #
141
- # Spawns a new subprocess against the alternate deployment, wires
142
- # the supplied handlers, runs the initialize handshake, and resumes
143
- # the prior threadId. Returns the started Client.
144
- #
145
- # Handlers are installed *before* the reader thread starts so no
146
- # post-handshake notification is dropped.
147
- def self.spawn_with_fallback(prior_thread_id:, deployment_config:, handshake_params:,
148
- notification_handler: nil, request_handler: nil,
149
- disconnect_handler: nil)
150
- raise ArgumentError, "prior_thread_id required" if prior_thread_id.nil? || prior_thread_id.to_s.empty?
151
-
152
- client = spawn(deployment_config: deployment_config)
153
- client.on_notification(&notification_handler) if notification_handler
154
- client.on_request(&request_handler) if request_handler
155
- client.on_disconnect(&disconnect_handler) if disconnect_handler
156
- client.start
157
-
158
- begin
159
- client.request("initialize", handshake_params)
160
- client.notify("initialized", {})
161
- client.request("thread/resume", { threadId: prior_thread_id })
162
- rescue StandardError
163
- client.close
164
- raise
165
- end
166
-
167
- client
168
- end
169
-
170
- # Plan 30 Phase 2 — graceful stop ahead of a deployment switch.
171
- #
172
- # Best-effort: issues `turn/interrupt` for any in-flight turn
173
- # (bounded by interrupt_grace_seconds), drains pending RPC, and
174
- # tears the subprocess down with the same TERM/KILL escalation
175
- # used by `terminate_process`.
176
- def stop_for_fallback(in_flight_turn: nil,
177
- term_grace_seconds: 0.5,
178
- kill_grace_seconds: 1.0,
179
- interrupt_grace_seconds: 0.5)
180
- if in_flight_turn && !@closed
181
- interrupt_thread = Thread.new do
182
- begin
183
- request("turn/interrupt", in_flight_turn)
184
- rescue StandardError
185
- nil
186
- end
187
- end
188
- interrupt_thread.kill unless interrupt_thread.join(interrupt_grace_seconds)
189
- end
190
-
191
- return true if @closed
192
-
193
- @closed = true
194
-
195
- fail_pending_requests(StandardError.new("codex_appserver client closed for fallback"))
196
-
197
- begin
198
- @write_io.close unless @write_io.closed?
199
- rescue IOError
200
- nil
201
- end
202
-
203
- terminated =
204
- if @pid
205
- terminate_process(
206
- term_grace_seconds: term_grace_seconds,
207
- kill_grace_seconds: kill_grace_seconds
208
- )
209
- else
210
- true
211
- end
212
-
213
- @reader_thread&.join(2)
214
- terminated
215
- end
216
-
217
- private
218
-
219
- def write_line(message)
220
- @write_mutex.synchronize do
221
- @write_io.write(JSON.generate(message))
222
- @write_io.write("\n")
223
- @write_io.flush
224
- end
225
- rescue Errno::EPIPE, IOError
226
- signal_disconnect(nil)
227
- end
228
-
229
- def read_loop
230
- buffer = +""
231
- loop do
232
- chunk = @read_io.readpartial(4096)
233
- buffer << chunk
234
- while (idx = buffer.index("\n"))
235
- line = buffer.slice!(0, idx + 1).chomp
236
- next if line.strip.empty?
237
-
238
- handle_line(line)
239
- end
240
- end
241
- rescue EOFError, IOError, Errno::EIO
242
- nil
243
- ensure
244
- signal_disconnect(nil)
245
- end
246
-
247
- def handle_line(line)
248
- message = JSON.parse(line)
249
- rescue JSON::ParserError => e
250
- signal_disconnect(e)
251
- return
252
- else
253
- dispatch_message(message)
254
- end
255
-
256
- def dispatch_message(message)
257
- if message["id"] && message["method"]
258
- handle_server_request(message)
259
- return
260
- end
261
-
262
- if message.key?("id")
263
- pending = @id_mutex.synchronize { @pending.delete(message["id"]) }
264
- return unless pending
265
-
266
- if message["error"]
267
- err_msg = message.dig("error", "message") || "RPC error"
268
- pending.push(StandardError.new(err_msg))
269
- else
270
- pending.push(message["result"] || {})
271
- end
272
- return
273
- end
274
-
275
- @notification_handler&.call(message) if message["method"]
276
- end
277
-
278
- def handle_server_request(message)
279
- result =
280
- begin
281
- @request_handler&.call(message["method"], message["params"] || {})
282
- rescue StandardError
283
- nil
284
- end
285
-
286
- if result.nil?
287
- write_line({
288
- jsonrpc: "2.0",
289
- id: message["id"],
290
- error: { code: -32601, message: "Unsupported server request: #{message['method']}" }
291
- })
292
- else
293
- write_line({
294
- jsonrpc: "2.0",
295
- id: message["id"],
296
- result: result
297
- })
298
- end
299
- end
300
-
301
- def signal_disconnect(error)
302
- return if @disconnect_signaled
303
-
304
- @disconnect_signaled = true
305
- fail_pending_requests(error)
306
- @disconnect_handler&.call(error)
307
- end
308
-
309
- def fail_pending_requests(error)
310
- exception =
311
- if error.is_a?(Exception)
312
- error
313
- else
314
- message = error.is_a?(Hash) ? error["message"] : nil
315
- StandardError.new(message.to_s.empty? ? "codex_appserver disconnected" : message.to_s)
316
- end
317
-
318
- @id_mutex.synchronize do
319
- @pending.each_value { |queue| queue.push(exception) }
320
- @pending.clear
321
- end
322
- end
323
-
324
- def process_alive?(pid)
325
- Process.kill(0, pid)
326
- true
327
- rescue Errno::ESRCH, Errno::EPERM
328
- false
329
- end
330
-
331
- def wait_for_process_exit(pid, timeout_seconds)
332
- deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds.to_f
333
- loop do
334
- return true unless process_alive?(pid)
335
-
336
- remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
337
- break if remaining <= 0
338
-
339
- sleep([0.05, remaining].min)
340
- end
341
-
342
- !process_alive?(pid)
343
- end
344
- end
345
- end
346
- end
347
- end