Class: Harnex::Runner

Inherits:
Object
  • Object
show all
Defined in:
lib/harnex/commands/run.rb

Constant Summary collapse

DEFAULT_TIMEOUT = 
5.0
TELEMETRY_FLAGS = 
{
  "--project-id" => "project_id",
  "--queue-id" => "queue_id",
  "--entry-id" => "entry_id",
  "--entry-title" => "entry_title",
  "--phase" => "phase",
  "--tier" => "tier",
  "--issue" => "issue",
  "--plan" => "plan",
  "--intent" => "intent",
  "--model" => "model",
  "--effort" => "effort"
}.freeze
TELEMETRY_KEYS_TO_FLAGS = 
TELEMETRY_FLAGS.invert.freeze
TELEMETRY_EQUALS_PREFIXES = 
TELEMETRY_FLAGS.keys.map { |flag| "#{flag}=" }.freeze
KNOWN_FLAGS = 
%w[
  --id --description --detach --tmux --host --port --watch --watch-file
  --stall-after --max-resumes --preset --context --meta --summary-out
  --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
  --require-attribution --auto-stop --fast --legacy-pty --help
].concat(TELEMETRY_FLAGS.keys).freeze
VALUE_FLAGS = 
%w[
  --id --description --host --port --watch --watch-file --stall-after
  --max-resumes --preset --context --meta --summary-out --artifact-report
  --validation-report --cwd --root --timeout --inbox-ttl
].concat(TELEMETRY_FLAGS.keys).freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(argv) ⇒ Runner

Returns a new instance of Runner.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/harnex/commands/run.rb', line 113

def initialize(argv)
  @argv = argv.dup
  @launch_cwd = Dir.pwd
  @options = {
    id: nil,
    description: nil,
    host: DEFAULT_HOST,
    port: nil,
    watch_enabled: false,
    stall_after_s: RunWatcher::DEFAULT_STALL_AFTER_S,
    stall_after_explicit: false,
    max_resumes: RunWatcher::DEFAULT_MAX_RESUMES,
    max_resumes_explicit: false,
    preset: nil,
    watch: nil,
    context: nil,
    meta: nil,
    telemetry: {},
    require_attribution: false,
    summary_out: nil,
    artifact_report: nil,
    cwd: nil,
    root: nil,
    auto_stop: false,
    detach: false,
    tmux: false,
    tmux_name: nil,
    timeout: DEFAULT_TIMEOUT,
    inbox_ttl: default_inbox_ttl,
    fast: false,
    legacy_pty: false,
    help: false
  }
end

Class Method Details

.usage(program_name = "harnex run") ⇒ Object 



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/harnex/commands/run.rb', line 36

def self.usage(program_name = "harnex run")
  <<~TEXT
    Usage: #{program_name} <cli> [options] [--] [cli-args...]

    Options:
      --id ID            Session identifier (default: random two-word ID)
      --description TEXT Short description of what this session is doing
      --detach           Start session in background and return JSON on stdout
      --tmux [NAME]      Run in a tmux window (implies --detach)
      --host HOST        Bind host for the local API (default: #{DEFAULT_HOST})
      --port PORT        Force a specific local API port
      --watch            Enable blocking babysitter mode (foreground only)
      --stall-after DUR  Force-resume threshold (default: #{RunWatcher::DEFAULT_STALL_AFTER_S.to_i}s)
      --max-resumes N    Max forced resumes before escalation (default: #{RunWatcher::DEFAULT_MAX_RESUMES})
      --preset NAME      Watch preset: impl, plan, gate (requires --watch)
      --watch-file PATH  Auto-send a file-change hook on modification
      --context TEXT     Inject as the initial prompt (prepends session header)
      --auto-stop        Stop after the first task completion from --context
      --fast             (codex only) Use Codex service_tier="fast".
                         Default Codex runs force service_tier="flex".
      --meta JSON        Attach parsed JSON metadata to the started event
      --summary-out PATH Append dispatch telemetry summary JSONL to PATH
      --artifact-report PATH
                         Worker-written harnex.artifact_report.v1 JSON sidecar to ingest at exit
      --validation-report PATH
                         Alias for --artifact-report; also exposed as HARNEX_VALIDATION_REPORT_PATH
      --project-id ID    Queue telemetry project id (first-class flags override --meta)
      --queue-id ID      Queue telemetry queue id
      --entry-id ID      Queue telemetry entry id
      --entry-title TEXT Queue telemetry entry title
      --phase TEXT       Queue/work phase telemetry
      --tier TEXT        Queue/work tier telemetry
      --issue ID         Queue/work issue telemetry
      --plan ID          Queue/work plan telemetry
      --intent TEXT      Queue/work intent telemetry
      --model NAME       Requested model metadata (also used for structured dispatch)
      --effort LEVEL     Requested reasoning effort metadata (structured dispatch)
      --require-attribution
                         Fail before launch unless project/phase/intent and one work id are present
      --cwd DIR          Run the wrapped agent from DIR and use DIR as the session root
      --root DIR         Override harnex session/root attribution without changing child cwd
      --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
      --inbox-ttl SECS   Expire queued inbox messages after SECS (default: #{Inbox::DEFAULT_TTL})
      --legacy-pty       (codex only) Use the legacy PTY adapter instead of
                         the JSON-RPC `app-server` adapter. Long-term
                         supported fallback for interactive/TUI use; JSON-RPC
                         remains the default for autonomous dispatches.
      -h, --help         Show this help

    Notes:
      Compatibility: `--watch PATH` and `--watch=PATH` still configure file-hook mode.
      Bare `--watch` enables the babysitter.
      --auto-stop requires --context and fires once after the first completion.
      Explicit --stall-after/--max-resumes values override --preset defaults.
      CLIs with smart prompt detection: #{Adapters.known.join(', ')}
      Any other CLI name is launched with generic wrapping.
      Wrapper options may appear before or after <cli>.

    Common patterns:
      #{program_name} pi --id pi-i-42 --tmux pi-i-42 --context "Read /tmp/task-impl-42.md"
      #{program_name} pi --id pi-i-42 --tmux pi-i-42 --context "Read /tmp/task-impl-42.md" --auto-stop
      #{program_name} pi --id pi-i-42 --watch --preset impl --context "Read /tmp/task-impl-42.md"
      #{program_name} codex --cwd /tmp/public-bundle --id eval-001 --context "Read README.md and write OUTPUT.md" --auto-stop
      #{program_name} pi --id pi-i-52 --artifact-report .harnex/reports/pi-i-52.json --context "Write proof to $HARNEX_ARTIFACT_REPORT_PATH" --auto-stop
      #{program_name} pi --project-id harnex --queue-id queue-005 --entry-id SP-4 --phase implement --intent queue-work --require-attribution --context "Implement SP-4"
      #{program_name} claude --id cl-r-42 --tmux cl-r-42 --description "Review task 42"

    Gotchas:
      Always pair --id and --tmux with the same value for delegated work.
      Passing --tmux without --id creates a random harnex session ID.
      --watch is foreground-only; do not combine it with --tmux or --detach.
      Use -- before child CLI flags when a flag could be parsed by harnex.
      Codex JSON-RPC: pass model as `-c model=NAME`, not `-m NAME`. The
        legacy PTY adapter (--legacy-pty) accepts `-m`.
  TEXT
end

Instance Method Details

#run ⇒ Object

Raises:

  • (OptionParser::MissingArgument) 


148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/harnex/commands/run.rb', line 148

def run
  cli_name, child_args = extract_wrapper_options(@argv)
  if @options[:help]
    puts self.class.usage
    return 0
  end

  raise OptionParser::MissingArgument, "cli" if cli_name.nil?
  validate_auto_stop_context!
  apply_telemetry_options!
  validate_required_attribution!

  repo_root = resolve_run_root(cli_name, child_args)
  @options[:summary_out] = resolve_summary_out(repo_root)
  @options[:artifact_report] = resolve_artifact_report(repo_root)
  @options[:id] ||= Harnex.generate_id(repo_root)
  validate_unique_id!(repo_root)
  effective_child_args = apply_context(apply_codex_service_tier(cli_name, child_args))
  adapter = Harnex.build_adapter(cli_name, effective_child_args, legacy_pty: @options[:legacy_pty])
  @options[:detach] = true if @options[:tmux]
  validate_watch_mode!
  resolve_watch_preset!

  if @options[:watch_enabled]
    run_watch_mode(adapter, repo_root)
  elsif @options[:detach]
    run_detached(adapter, cli_name, child_args, repo_root)
  else
    run_foreground(adapter, repo_root)
  end
end

#run_detached(adapter, cli_name, child_args, repo_root) ⇒ Object 



187
188
189
190
191
192
193
194
195
196
 
# File 'lib/harnex/commands/run.rb', line 187

def run_detached(adapter, cli_name, child_args, repo_root)
  Session.validate_binary!(adapter.build_command)

  if @options[:tmux]
    run_in_tmux(cli_name, child_args, repo_root)
  else
    result = run_headless(adapter, repo_root)
    result[:exit_code]
  end
end

#run_foreground(adapter, repo_root) ⇒ Object 



180
181
182
183
184
185
 
# File 'lib/harnex/commands/run.rb', line 180

def run_foreground(adapter, repo_root)
  session = build_session(adapter, repo_root)
  session.validate_binary!
  warn("harnex: session #{session.id} on #{session.host}:#{session.port}")
  session.run(validate_binary: false)
end

#run_headless(adapter, repo_root, emit_payload: true) ⇒ Object 



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/harnex/commands/run.rb', line 269

def run_headless(adapter, repo_root, emit_payload: true)
  log_dir = File.join(Harnex::STATE_DIR, "logs")
  FileUtils.mkdir_p(log_dir)
  log_path = File.join(log_dir, "#{@options[:id]}.log")

  child_pid = fork do
    Process.setsid
    STDIN.reopen("/dev/null")
    log_file = File.open(log_path, "a")
    STDOUT.reopen(log_file)
    STDERR.reopen(log_file)
    STDOUT.sync = true
    STDERR.sync = true

    session = build_session(adapter, repo_root)
    exit_code = session.run(validate_binary: false)
    exit(exit_code || 1)
  end

  Process.detach(child_pid)

  registry = wait_for_registration(repo_root)
  return { ok: false, exit_code: registration_timeout(@options[:id]) } unless registry

  payload = {
    ok: true,
    id: @options[:id],
    cli: adapter.key,
    pid: registry["pid"],
    port: registry["port"],
    mode: "headless",
    log: log_path,
    output_log_path: Harnex.output_log_path(repo_root, @options[:id])
  }
  payload[:description] = @options[:description] if @options[:description]
  puts JSON.generate(payload) if emit_payload
  { ok: true, exit_code: 0, registry: registry, payload: payload }
end

#run_in_tmux(cli_name, child_args, repo_root) ⇒ Object 



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/harnex/commands/run.rb', line 212

def run_in_tmux(cli_name, child_args, repo_root)
  harnex_bin = File.expand_path("../../../bin/harnex", __dir__)
  tmux_cmd = [harnex_bin, "run", cli_name]
  tmux_cmd += ["--id", @options[:id]]
  tmux_cmd += ["--description", @options[:description]] if @options[:description]
  tmux_cmd += ["--host", @options[:host]]
  tmux_cmd += ["--port", @options[:port].to_s] if @options[:port]
  tmux_cmd += ["--watch-file", @options[:watch]] if @options[:watch]
  tmux_cmd += ["--context", @options[:context]] if @options[:context]
  tmux_cmd << "--auto-stop" if @options[:auto_stop]
  tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
  @options[:telemetry].each do |key, value|
    flag = TELEMETRY_KEYS_TO_FLAGS[key]
    tmux_cmd += [flag, value] if flag && value
  end
  tmux_cmd << "--require-attribution" if @options[:require_attribution]
  tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
  tmux_cmd += ["--artifact-report", @options[:artifact_report]] if @options[:artifact_report]
  tmux_cmd += ["--cwd", @options[:cwd]] if @options[:cwd]
  tmux_cmd += ["--root", @options[:root]] if @options[:root]
  tmux_cmd += ["--inbox-ttl", @options[:inbox_ttl].to_s]
  tmux_cmd << "--fast" if @options[:fast]
  tmux_cmd += ["--legacy-pty"] if @options[:legacy_pty]
  tmux_cmd += ["--"] + child_args unless child_args.empty?

  window_name = @options[:tmux_name] || @options[:id]
  shell_cmd = tmux_cmd.map { |arg| Shellwords.shellescape(arg) }.join(" ")

  tmux_start_cwd = @options[:cwd] || @launch_cwd
  started =
    if ENV["TMUX"]
      system("tmux", "new-window", "-c", tmux_start_cwd, "-n", window_name, "-d", shell_cmd)
    else
      system("tmux", "new-session", "-c", tmux_start_cwd, "-d", "-s", "harnex", "-n", window_name, shell_cmd)
    end

  raise "tmux failed to start #{cli_name.inspect}" unless started

  registry = wait_for_registration(repo_root)
  return registration_timeout(@options[:id]) unless registry
  registry = annotate_tmux_registry(registry)

  payload = {
    ok: true,
    id: @options[:id],
    cli: cli_name,
    pid: registry["pid"],
    port: registry["port"],
    mode: "tmux",
    window: window_name,
    output_log_path: Harnex.output_log_path(repo_root, @options[:id])
  }
  payload[:description] = @options[:description] if @options[:description]
  puts JSON.generate(payload)
  0
end

#run_watch_mode(adapter, repo_root) ⇒ Object 



198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/harnex/commands/run.rb', line 198

def run_watch_mode(adapter, repo_root)
  Session.validate_binary!(adapter.build_command)

  result = run_headless(adapter, repo_root, emit_payload: false)
  return result[:exit_code] unless result[:ok]

  RunWatcher.new(
    id: @options[:id],
    repo_root: repo_root,
    stall_after_s: @options[:stall_after_s],
    max_resumes: @options[:max_resumes]
  ).run
end