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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +592 -0
- data/GUIDE.md +222 -68
- data/README.md +78 -48
- data/TECHNICAL.md +235 -98
- data/agents/gpt.md +60 -0
- data/docs/agents.md +119 -0
- data/docs/dispatch-telemetry.md +184 -50
- data/docs/events.md +20 -7
- data/docs/lanes.md +202 -0
- data/docs/mcp.md +102 -0
- data/docs/pi-rpc.md +81 -7
- data/docs/upgrading-to-0.29.md +87 -0
- data/guides/01_dispatch.md +101 -34
- data/guides/04_monitoring.md +223 -25
- data/guides/05_naming.md +0 -1
- data/guides/06_claude.md +96 -0
- data/lib/harnex/adapters/base.rb +4 -8
- data/lib/harnex/adapters/pi.rb +92 -12
- data/lib/harnex/adapters.rb +1 -16
- data/lib/harnex/artifact_report.rb +206 -12
- data/lib/harnex/cli.rb +68 -50
- data/lib/harnex/commands/ask.rb +278 -0
- data/lib/harnex/commands/delegate.rb +202 -0
- data/lib/harnex/commands/doctor.rb +34 -36
- data/lib/harnex/commands/events.rb +3 -3
- data/lib/harnex/commands/history.rb +2 -8
- data/lib/harnex/commands/land.rb +150 -0
- data/lib/harnex/commands/lanes.rb +84 -0
- data/lib/harnex/commands/logs.rb +3 -3
- data/lib/harnex/commands/mcp.rb +208 -0
- data/lib/harnex/commands/orchestration.rb +88 -9
- data/lib/harnex/commands/pane.rb +3 -3
- data/lib/harnex/commands/preflight.rb +566 -0
- data/lib/harnex/commands/reply.rb +125 -0
- data/lib/harnex/commands/result.rb +108 -0
- data/lib/harnex/commands/run.rb +248 -64
- data/lib/harnex/commands/send.rb +121 -16
- data/lib/harnex/commands/status.rb +32 -4
- data/lib/harnex/commands/stop.rb +14 -4
- data/lib/harnex/commands/telemetry.rb +19 -1
- data/lib/harnex/commands/wait.rb +421 -56
- data/lib/harnex/commands/watch.rb +134 -21
- data/lib/harnex/context_file.rb +85 -0
- data/lib/harnex/core.rb +100 -15
- data/lib/harnex/dispatch_history.rb +157 -10
- data/lib/harnex/lanes.rb +513 -0
- data/lib/harnex/mcp.rb +362 -0
- data/lib/harnex/orchestration.rb +128 -5
- data/lib/harnex/owned_process_group.rb +50 -0
- data/lib/harnex/owner_stream.rb +399 -0
- data/lib/harnex/pricing.rb +4 -9
- data/lib/harnex/runtime/activity_tracker.rb +107 -0
- data/lib/harnex/runtime/api_server.rb +11 -1
- data/lib/harnex/runtime/completion_notifier.rb +90 -11
- data/lib/harnex/runtime/inbox.rb +26 -7
- data/lib/harnex/runtime/message.rb +5 -2
- data/lib/harnex/runtime/runtime_budget.rb +96 -0
- data/lib/harnex/runtime/session.rb +684 -294
- data/lib/harnex/runtime/stop_request.rb +39 -0
- data/lib/harnex/stall.rb +46 -0
- data/lib/harnex/telemetry_reconciler.rb +42 -20
- data/lib/harnex/terminal_status.rb +5 -5
- data/lib/harnex/version.rb +2 -2
- data/lib/harnex.rb +16 -0
- data/recipes/01_fire_and_watch.md +14 -14
- data/recipes/02_chain_implement.md +35 -31
- data/recipes/03_buddy.md +1 -1
- metadata +34 -12
- data/docs/codex-appserver.md +0 -175
- data/lib/harnex/adapters/codex.rb +0 -160
- data/lib/harnex/adapters/codex_appserver.rb +0 -407
- 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]
|
|
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:
|
|
117
|
+
dispatch_path: dispatch_path,
|
|
93
118
|
samples_path: options[:samples],
|
|
94
|
-
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
|
-
|
|
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
|
-
]
|
|
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)
|
data/lib/harnex/commands/pane.rb
CHANGED
|
@@ -22,9 +22,9 @@ module Harnex
|
|
|
22
22
|
-h, --help Show this help
|
|
23
23
|
|
|
24
24
|
Common patterns:
|
|
25
|
-
#{program_name} --id
|
|
26
|
-
#{program_name} --id
|
|
27
|
-
#{program_name} --id
|
|
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.
|