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
data/docs/codex-appserver.md
DELETED
|
@@ -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
|