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
@@ -7,7 +7,8 @@ module Harnex
7
7
  <<~TEXT
8
8
  Usage:
9
9
  #{program_name} sample --out PATH --run-id ID --generation-id ID [options]
10
- #{program_name} report --dispatch PATH --run-id ID [--samples PATH] [--json]
10
+ #{program_name} report --dispatch PATH (--run-id ID | --queue-id ID) [--samples PATH]
11
+ [--failure-budget N] [--budget-unit attempts|families] [--fatal-classes A,B] [--json]
11
12
 
12
13
  Sample options:
13
14
  --project-id ID
@@ -37,8 +38,25 @@ module Harnex
37
38
  --dispatch PATH Dispatch summary JSONL
38
39
  --samples PATH External primary sample JSONL
39
40
  --run-id ID Logical orchestration run id
41
+ --queue-id ID Queue id (alone, or narrowing --run-id)
42
+ --include-preflight Count `harnex preflight` rows (excluded by default)
43
+ --failure-budget N Exit 3 once N fatal worker failures are counted
44
+ --budget-unit UNIT attempts (default) or families (retries joined
45
+ by parent attempt/dispatch id count once)
46
+ --fatal-classes A,B Outcome classes that consume the budget
47
+ (default: the classes marked * below)
40
48
  --json Output the full report JSON
41
49
  -h, --help Show this help
50
+
51
+ Worker outcome classes (dispatch row outcome.class):
52
+ completed completed_with_proof completed_with_activity
53
+ proof completed_no_activity* report_missing report_invalid report_rejected
54
+ process task_failed* provider_capacity* boot_failure* permission_prompt*
55
+ timeout* process_failed* stopped_by_caller
56
+ fallback unknown
57
+ The budget is a ledger, not a breaker: enforcement stays with the caller.
58
+ Exit codes: 0 report printed (within budget), 1 error, 2 usage error,
59
+ 3 budget breached.
42
60
  TEXT
43
61
  end
44
62
 
@@ -82,23 +100,64 @@ module Harnex
82
100
  end
83
101
 
84
102
  def run_report(argv)
85
- options = { json: false }
103
+ options = { json: false, include_preflight: false }
86
104
  report_parser(options).parse!(argv)
87
105
  if options[:help]
88
106
  puts self.class.usage
89
107
  return 0
90
108
  end
109
+ if blank?(options[:run_id]) && blank?(options[:queue_id])
110
+ raise OptionParser::MissingArgument, "--run-id or --queue-id"
111
+ end
112
+
113
+ dispatch_path = required_option(options[:dispatch], "--dispatch")
114
+ raise ArgumentError, "dispatch file not found: #{dispatch_path}" unless File.file?(dispatch_path)
115
+
91
116
  report = Harnex::Orchestration.report(
92
- dispatch_path: required_option(options[:dispatch], "--dispatch"),
117
+ dispatch_path: dispatch_path,
93
118
  samples_path: options[:samples],
94
- run_id: required_option(options[:run_id], "--run-id")
119
+ run_id: blank?(options[:run_id]) ? nil : options[:run_id],
120
+ queue_id: blank?(options[:queue_id]) ? nil : options[:queue_id],
121
+ budget: report_budget(options),
122
+ include_preflight: options[:include_preflight]
95
123
  )
96
124
  if options[:json]
97
125
  puts JSON.generate(report)
98
126
  else
99
127
  puts render_report(report)
100
128
  end
101
- 0
129
+ report.dig("failure_budget", "breached") ? BUDGET_BREACHED_EXIT : 0
130
+ end
131
+
132
+ # Distinct from 1 (errors) and 2 (usage errors from bin/harnex).
133
+ BUDGET_BREACHED_EXIT = 3
134
+
135
+ def report_budget(options)
136
+ if options[:failure_budget].nil?
137
+ if options[:budget_unit] || options[:fatal_classes]
138
+ raise OptionParser::InvalidArgument, "--budget-unit/--fatal-classes need --failure-budget"
139
+ end
140
+ return nil
141
+ end
142
+
143
+ limit = Integer(options[:failure_budget], exception: false)
144
+ raise OptionParser::InvalidArgument, "--failure-budget must be a positive integer" unless limit&.positive?
145
+
146
+ unit = options[:budget_unit] || "attempts"
147
+ unless Harnex::Orchestration::BUDGET_UNITS.include?(unit)
148
+ raise OptionParser::InvalidArgument, "--budget-unit must be attempts or families"
149
+ end
150
+
151
+ fatal = options[:fatal_classes]&.split(",")&.map(&:strip)&.reject(&:empty?)
152
+ unknown = Array(fatal) - Harnex::Session::OUTCOME_CLASSES
153
+ raise OptionParser::InvalidArgument, "unknown outcome class: #{unknown.join(', ')}" unless unknown.empty?
154
+ raise OptionParser::InvalidArgument, "--fatal-classes needs at least one class" if fatal && fatal.empty?
155
+
156
+ { limit: limit, unit: unit, fatal_classes: fatal }
157
+ end
158
+
159
+ def blank?(value)
160
+ value.to_s.strip.empty?
102
161
  end
103
162
 
104
163
  def sample_parser(options)
@@ -135,10 +194,15 @@ module Harnex
135
194
 
136
195
  def report_parser(options)
137
196
  OptionParser.new do |opts|
138
- opts.banner = "Usage: harnex orchestration report --dispatch PATH --run-id ID [options]"
197
+ opts.banner = "Usage: harnex orchestration report --dispatch PATH (--run-id ID | --queue-id ID) [options]"
139
198
  opts.on("--dispatch PATH") { |value| options[:dispatch] = value }
140
199
  opts.on("--samples PATH") { |value| options[:samples] = value }
141
200
  opts.on("--run-id ID") { |value| options[:run_id] = value }
201
+ opts.on("--queue-id ID") { |value| options[:queue_id] = value }
202
+ opts.on("--include-preflight") { options[:include_preflight] = true }
203
+ opts.on("--failure-budget N") { |value| options[:failure_budget] = value }
204
+ opts.on("--budget-unit UNIT") { |value| options[:budget_unit] = value }
205
+ opts.on("--fatal-classes LIST") { |value| options[:fatal_classes] = value }
142
206
  opts.on("--json") { options[:json] = true }
143
207
  opts.on("-h", "--help") { options[:help] = true }
144
208
  end
@@ -155,12 +219,27 @@ module Harnex
155
219
  primary = report.fetch("primary")
156
220
  workers = report.fetch("workers")
157
221
  ratios = report.fetch("ratios")
158
- [
159
- "Run: #{report.fetch('orchestration_run_id')}",
222
+ classes = workers.fetch("outcome_classes")
223
+ lines = [
224
+ "Run: #{format_value(report.fetch('orchestration_run_id'))} queue=#{format_value(report['queue_id'])}",
160
225
  "Primary: generations=#{primary.fetch('generation_count')} usage=#{primary.dig('usage', 'status')} total_tokens=#{format_value(primary.dig('usage', 'total_tokens'))} peak_context=#{format_value(primary.dig('context', 'peak_tokens'))} tool_calls=#{primary.fetch('tool_calls')}",
161
226
  "Workers: dispatches=#{workers.fetch('dispatches')} usage=#{workers.dig('usage', 'status')} active_s=#{workers.fetch('active_s')} accepted=#{workers.dig('outcomes', 'accepted')} rejected=#{workers.dig('outcomes', 'rejected')} blocked=#{workers.dig('outcomes', 'blocked')} unknown=#{workers.dig('outcomes', 'unknown')}",
227
+ "Outcome classes: #{format_counts(classes.fetch('attempts'))} " \
228
+ "(families=#{classes.fetch('family_count')}: #{format_counts(classes.fetch('families'))})",
162
229
  "Ratios: primary_tokens_per_accepted_entry=#{format_value(ratios.fetch('primary_total_tokens_per_accepted_entry'))} primary_tool_calls_per_accepted_entry=#{format_value(ratios.fetch('primary_tool_calls_per_accepted_entry'))}"
163
- ].join("\n")
230
+ ]
231
+ if (budget = report["failure_budget"])
232
+ verdict = budget.fetch("breached") ? "BREACHED" : "within budget"
233
+ lines << "Failure budget: #{budget.fetch('consumed')}/#{budget.fetch('limit')} #{budget.fetch('unit')} " \
234
+ "(fatal attempts=#{budget.fetch('fatal_attempts')} families=#{budget.fetch('fatal_families')}) #{verdict}"
235
+ end
236
+ lines.join("\n")
237
+ end
238
+
239
+ def format_counts(counts)
240
+ return "-" if counts.empty?
241
+
242
+ counts.map { |klass, count| "#{klass}=#{count}" }.join(" ")
164
243
  end
165
244
 
166
245
  def format_value(value)
@@ -22,9 +22,9 @@ module Harnex
22
22
  -h, --help Show this help
23
23
 
24
24
  Common patterns:
25
- #{program_name} --id cx-i-42 --lines 40
26
- #{program_name} --id cx-i-42 --lines 40 --json
27
- #{program_name} --id cx-i-42 --follow --interval 2
25
+ #{program_name} --id pi-i-42 --lines 40
26
+ #{program_name} --id pi-i-42 --lines 40 --json
27
+ #{program_name} --id pi-i-42 --follow --interval 2
28
28
 
29
29
  Gotchas:
30
30
  pane requires a tmux-backed session.