Class: Harnex::Waiter

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

Constant Summary collapse

POLL_INTERVAL = 
0.5
EVENT_POLL_INTERVAL = 
0.1
EXIT_STATUS_GRACE_SECONDS_DEFAULT = 
5.0
EXIT_STATUS_GRACE_POLL_INTERVAL = 
0.05
FINAL_EVENT_GRACE_SECONDS = 
5.0
EVENT_PREDICATES = 
%w[task_complete task_failed].freeze
LEGACY_EVENT_TYPES = 
%w[agent_state exited task_complete task_failed].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(argv) ⇒ Waiter

Returns a new instance of Waiter.



54
55
56
57
58
59
60
61
62
63
 
# File 'lib/harnex/commands/wait.rb', line 54

def initialize(argv)
  @argv = argv.dup
  @options = {
    id: nil,
    until_state: nil,
    repo_path: Dir.pwd,
    timeout: nil,
    help: false
  }
end

Class Method Details

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



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/harnex/commands/wait.rb', line 17

def self.usage(program_name = "harnex wait")
  <<~TEXT
    Usage: #{program_name} [options]

    Options:
      --id ID         Session ID to wait for (required)
      --until STATE   Wait until session reaches STATE. Supported:
                        done            (work fence — task_complete,
                                         task_failed, or terminal exit,
                                         whichever comes first)
                        task_complete   (events JSONL — fires on
                                         successful turn completion)
                        task_failed     (events JSONL — fires on
                                         failed turn completion)
                        <other>         (agent_state HTTP poll, e.g.
                                         "prompt", "busy")
                      Without --until, waits for session exit (default).
      --repo PATH     Resolve session using PATH's repo root (default: current repo)
      --timeout SECS  Maximum time to wait in seconds (default: unlimited)
      -h, --help      Show this help

    Common patterns:
      #{program_name} --id cx-i-42 --until done --timeout 900
      #{program_name} --id cx-i-42 --until task_complete --timeout 900
      #{program_name} --id cx-i-42 --until prompt --timeout 120
      #{program_name} --id cx-i-42

    Gotchas:
      done is the safest work-level fence for monitors.
      task_complete/task_failed are event predicates; prompt/busy are live state polls.
      Prompt state alone does not prove work acceptance. Verify artifacts/tests.
      Exit waits can resolve from terminal summary rows when live registry/
      exit-status files are already gone.
      Without --timeout, wait can block indefinitely.
  TEXT
end

Instance Method Details

#run ⇒ Object 



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/harnex/commands/wait.rb', line 65

def run
  parser.parse!(@argv)
  if @options[:help]
    puts self.class.usage
    return 0
  end

  raise "--id is required for harnex wait" unless @options[:id]

  if @options[:until_state]
    case @options[:until_state]
    when "done"
      wait_until_done
    when *EVENT_PREDICATES
      wait_until_event(@options[:until_state])
    else
      wait_until_state
    end
  else
    wait_until_exit
  end
end