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,175 +0,0 @@
1
- # Codex `app-server` adapter
2
-
3
- harnex 0.6.0 talks to Codex over JSON-RPC 2.0 instead of scraping a
4
- PTY pane. The adapter spawns `codex app-server` as a subprocess,
5
- exchanges newline-delimited JSON-RPC messages on stdin/stdout, and
6
- fans server notifications into the harnex events log.
7
-
8
- ## Transport
9
-
10
- - Subprocess: `codex app-server` (CLI ≥ 0.128.0 — verify with
11
- `harnex doctor`).
12
- - Wire format: one JSON object per line.
13
- - Encoding: UTF-8.
14
- - One `Adapter#transport` value: `:stdio_jsonrpc`.
15
-
16
- ## Handshake
17
-
18
- Mirrors `codex-plugin-cc/plugins/codex/scripts/lib/app-server.mjs`.
19
-
20
- ```ruby
21
- client.request("initialize", {
22
- clientInfo: { title: "harnex", name: "harnex", version: Harnex::VERSION },
23
- capabilities: {
24
- experimentalApi: false,
25
- optOutNotificationMethods: %w[
26
- item/agentMessage/delta
27
- item/reasoning/summaryTextDelta
28
- item/reasoning/summaryPartAdded
29
- item/reasoning/textDelta
30
- ]
31
- }
32
- })
33
- client.notify("initialized", {})
34
- ```
35
-
36
- After the handshake the client is ready to issue `thread/start` and
37
- `turn/start` requests.
38
-
39
- ## Notification → event mapping
40
-
41
- | Server notification | harnex event | Notes |
42
- |-----------------------------|--------------------|-------|
43
- | `thread/started` | (metadata) | Stashes `threadId` |
44
- | `turn/started` | `turn_started` | Carries `turnId` |
45
- | `turn/completed` | `task_complete` or `task_failed` | Failed/interrupted statuses emit `task_failed` with the Codex error. A completed `--context` turn emits `task_complete` only with structured command/tool activity or a Git delta; otherwise it emits typed `completed_no_activity`. Harnex writes the observed-state receipt before the successful event. |
46
- | `item/started` | (silent) | Streaming deltas opted out |
47
- | `item/completed` | `item_completed` + synthesized transcript | See "tmux/STDOUT" below |
48
- | `error` | `error` | Turn-level Codex error notification; preserves nested `error.message` and does not count as a transport disconnect. |
49
- | `thread/status/changed` | (state only) | Drives state machine |
50
- | `thread/tokenUsage/updated` | (status field) | Surfaced via `harnex status --json` |
51
- | `thread/compacted` | `compaction` | Increments `compactions` counter |
52
- | `account/rateLimits/updated`| (silent, status) | Visible in `status --json` |
53
-
54
- ### How disconnects are detected
55
-
56
- Disconnects are detected from subprocess exit / EOF on stdout and parse errors
57
- when the server emits a malformed line. Request-level JSON-RPC error responses
58
- reject only the in-flight request; they do not by themselves imply that the
59
- transport disconnected. Schema-defined `error` notifications are turn-level
60
- Codex errors and feed `last_error` / `task_failed` rather than the disconnect
61
- counter.
62
-
63
- Unexpected transport loss emits `disconnected` and increments
64
- `auto_disconnects`. Normal auto-stop teardown after `task_complete` /
65
- `task_failed` is treated as a clean structured close. There is no need for the
66
- screen-text regex that the legacy adapter relied on.
67
-
68
- ## tmux / STDOUT — synthesized transcript
69
-
70
- Without a PTY, `harnex run codex --tmux` and `harnex pane --id …`
71
- would otherwise see an empty pane. The JSON-RPC path renders a
72
- synthesized transcript built from `item/completed` notifications:
73
-
74
- - `agent_message` items render their text payload
75
- - `tool_call` items render as `tool: <name> <one-line summary>`
76
-
77
- The synthesized transcript is written to BOTH the output log AND
78
- STDOUT, so:
79
-
80
- - `harnex run codex` (foreground) — user sees the transcript live
81
- - `harnex run codex --tmux` — the tmux window shows the transcript
82
- - `harnex pane --id <session>` — captures the synthesized text
83
- - `harnex logs --id <session>` — replays the same transcript
84
-
85
- For interactive debugging where the original Codex TUI is wanted,
86
- `codex resume <thread-id>` opens the same thread in a real Codex
87
- CLI.
88
-
89
- ## `harnex wait --until done` / `task_complete` / `task_failed`
90
-
91
- For unattended monitors, block until Codex work completes, fails, or the session exits:
92
-
93
- ```
94
- harnex wait --id cx-i-242 --until done --timeout 300
95
- ```
96
-
97
- When you need the exact successful structured turn event, wait for `task_complete`:
98
-
99
- ```
100
- harnex wait --id cx-i-242 --until task_complete --timeout 300
101
- ```
102
-
103
- `--until done` returns non-zero when it sees `task_failed` or failed terminal
104
- telemetry. This includes acknowledgment-only autonomous `--context` turns
105
- (`outcome_class=completed_no_activity`) and the rare receipt-write failure
106
- (`report_invalid`). Harnex classifies completion from app-server item counters
107
- and Git state; it does not inspect final-answer prose or trust worker claims.
108
- The task-complete/task-failed waiters
109
- tail the events JSONL — not the API socket — so they keep working across
110
- restarts and are adapter-agnostic.
111
-
112
- Every blind dispatch receives a harness-authored receipt. No worker report is
113
- required: Harnex captures command exits, Git state, completion, and usage, then
114
- writes `HARNEX_ARTIFACT_REPORT_PATH` before emitting `task_complete`. Use
115
- `--artifact-report PATH` only to choose a fixed destination; otherwise the
116
- status/end row points to the default state-directory path. Review workers may
117
- write advisory summary/verdict/P1-P3 counts to `HARNEX_ARTIFACT_CLAIMS_PATH`.
118
- Claims and report-shaped `agentMessage` text cannot satisfy the activity gate.
119
- Consumers can run `harnex artifact-report validate PATH --final` afterward.
120
-
121
- ## `harnex doctor`
122
-
123
- Verifies the Codex CLI is installed and at version ≥ 0.128.0. JSON
124
- output, exit 0 if healthy.
125
-
126
- ```
127
- $ harnex doctor
128
- {"ok":true,"checks":[{"name":"codex","required":">= 0.128.0","ok":true,"found":"0.128.0"}]}
129
- ```
130
-
131
- ## Long-term fallback: `--legacy-pty`
132
-
133
- The pre-0.6.0 PTY adapter remains available as a long-term supported
134
- fallback:
135
-
136
- ```
137
- harnex run codex --legacy-pty
138
- ```
139
-
140
- It's the right tool when you want the full Codex TUI live in tmux —
141
- status bars, tool diffs, ANSI panels — that the headless `app-server`
142
- backend doesn't render. JSON-RPC remains the default and is recommended
143
- for autonomous worker dispatches; legacy-pty is for interactive/TUI use.
144
-
145
- ## Troubleshooting
146
-
147
- - **`task_complete` never fires.** Check `harnex events --id <session>` first:
148
- failed Codex turns emit `task_failed` with the provider/model error. If there
149
- is neither `task_complete` nor `task_failed`, run `harnex doctor`; Codex <
150
- 0.128.0 is unsupported.
151
- - **Empty tmux pane.** Codex hasn't emitted any `item/completed`
152
- yet — the agent is reasoning. The pane fills as soon as the
153
- first item completes.
154
- - **`task_failed` immediately after dispatch.** Check
155
- `harnex events --id <session>`. Provider/model failures retain their Codex
156
- error message. `completed_no_activity` means the turn ended with no
157
- command/tool or Git activity. `report_invalid` now primarily identifies a
158
- harness receipt-write failure; old rows may still contain the legacy
159
- `report_missing` / `report_rejected` classes. Common provider failures
160
- include auth environment variables (for example `OPENAI_API_KEY` /
161
- `AZURE_OPENAI_API_KEY`) and model unavailability.
162
-
163
- ## Schema fixtures
164
-
165
- `test/fixtures/codex_appserver/schema/` holds hand-pruned subsets
166
- of `ServerNotification` and `ClientRequest` for the methods harnex
167
- issues / consumes. Regenerate via:
168
-
169
- ```
170
- codex app-server generate-json-schema --out /tmp/codex-schema-X
171
- ```
172
-
173
- then re-prune. The full bundle is ~3 MB; the pruned subsets are
174
- < 50 KB and serve as a compact reference for what's actually wired
175
- through the adapter.
@@ -1,160 +0,0 @@
1
- module Harnex
2
- module Adapters
3
- class Codex < Base
4
- SUBMIT_DELAY_MS = 75
5
- SUBMIT_DELAY_PER_KB_MS = 50
6
- SEND_WAIT_SECONDS = 2.0
7
-
8
- def initialize(extra_args = [])
9
- super("codex", extra_args)
10
- @banner_seen = false
11
- end
12
-
13
- def provider
14
- "openai"
15
- end
16
-
17
- def base_command
18
- [
19
- "codex",
20
- "--dangerously-bypass-approvals-and-sandbox",
21
- "--no-alt-screen"
22
- ]
23
- end
24
-
25
- def infer_repo_path(argv)
26
- index = 0
27
- while index < argv.length
28
- arg = argv[index]
29
- case arg
30
- when "-C", "--cd"
31
- next_value = argv[index + 1]
32
- return next_value if next_value
33
- break
34
- when /\A-C(.+)\z/
35
- return Regexp.last_match(1)
36
- end
37
- index += 1
38
- end
39
-
40
- Dir.pwd
41
- end
42
-
43
- def input_state(screen_text)
44
- lines = recent_lines(screen_text)
45
- if lines.any? { |line| line.include?("OpenAI Codex") || line.include?("gpt-") }
46
- @banner_seen = true
47
- end
48
- return super unless @banner_seen
49
-
50
- if lines.any? { |line| prompt_line?(line) }
51
- {
52
- state: "prompt",
53
- input_ready: true
54
- }
55
- else
56
- {
57
- state: "session",
58
- input_ready: nil
59
- }
60
- end
61
- end
62
-
63
- def usage_telemetry_supported?
64
- true
65
- end
66
-
67
- def parse_session_summary(transcript_tail)
68
- summary = empty_session_summary
69
- text = transcript_tail.to_s
70
-
71
- if (match = text.match(/Token usage:\s+total=([\d,]+)\s+input=([\d,]+)(?:\s+\(\+\s+([\d,]+)\s+cached\))?\s+output=([\d,]+)(?:\s+\(reasoning\s+([\d,]+)\))?/))
72
- summary[:total_tokens] = parse_token_count(match[1])
73
- summary[:input_tokens] = parse_token_count(match[2])
74
- summary[:cached_tokens] = parse_token_count(match[3])
75
- summary[:output_tokens] = parse_token_count(match[4])
76
- summary[:reasoning_tokens] = parse_token_count(match[5])
77
- end
78
-
79
- if (match = text.match(/codex resume\s+([0-9a-f-]{36})/))
80
- summary[:agent_session_id] = match[1]
81
- end
82
-
83
- summary
84
- end
85
-
86
- def send_wait_seconds(submit:, enter_only:)
87
- return 0.0 unless submit
88
- return 0.0 if enter_only
89
-
90
- SEND_WAIT_SECONDS
91
- end
92
-
93
- def wait_for_sendable_state?(state, submit:, enter_only:)
94
- return false unless submit
95
- return false if enter_only
96
-
97
- state[:input_ready] != true
98
- end
99
-
100
- def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false)
101
- state = input_state(screen_text)
102
- if !force && submit && !enter_only && state[:input_ready] != true
103
- raise ArgumentError, blocked_message(state, enter_only: enter_only)
104
- end
105
-
106
- steps = []
107
- unless enter_only
108
- body = text.to_s
109
- steps << { text: body, newline: false } unless body.empty?
110
- end
111
-
112
- if submit || enter_only
113
- step = { text: submit_bytes, newline: false }
114
- step[:delay_ms] = submit_delay_ms(text) if steps.any?
115
- steps << step
116
- end
117
-
118
- {
119
- steps: steps,
120
- input_state: state,
121
- force: force
122
- }
123
- end
124
-
125
- def inject_exit(writer)
126
- super(writer, delay_ms: SUBMIT_DELAY_MS)
127
- end
128
-
129
- protected
130
-
131
- def empty_session_summary
132
- {
133
- input_tokens: nil,
134
- output_tokens: nil,
135
- reasoning_tokens: nil,
136
- cached_tokens: nil,
137
- total_tokens: nil,
138
- agent_session_id: nil
139
- }
140
- end
141
-
142
- def parse_token_count(value)
143
- return nil if value.nil?
144
-
145
- Integer(value.delete(","))
146
- end
147
-
148
- def submit_delay_ms(text)
149
- extra = (text.to_s.bytesize / 1024.0 * SUBMIT_DELAY_PER_KB_MS).ceil
150
- SUBMIT_DELAY_MS + extra
151
- end
152
-
153
- def blocked_message(state, enter_only:)
154
- return super if enter_only
155
-
156
- "Codex is not at a prompt; wait and retry or use `harnex send --force` (state: #{state[:state]})"
157
- end
158
- end
159
- end
160
- end