@harness-reins/linux-x64 0.0.0-stage → 0.9.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.
- package/dist/reins/_internal/base_library.zip +0 -0
- package/dist/reins/_internal/harness_reins/_build.txt +1 -0
- package/dist/reins/_internal/harness_reins/assets/skills/claude/SKILL.md +140 -0
- package/dist/reins/_internal/harness_reins/assets/skills/codex/SKILL.md +88 -0
- package/dist/reins/_internal/harness_reins/assets/skills/pi/SKILL.md +98 -0
- package/dist/reins/_internal/harness_reins/assets/skills/reference/SKILL.md +812 -0
- package/dist/reins/_internal/harness_reins/assets/skills/reference/agents/openai.yaml +4 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/desktop-package-launch.py +263 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/invoke-desktop-package.ps1 +14 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/probe-desktop-launch.py +217 -0
- package/dist/reins/_internal/harness_reins/harness/codex/desktop/windows_assets/start-desktop-bridge.ps1 +449 -0
- package/dist/reins/_internal/harness_reins/harness/pi/extension/reins-callback.js +272 -0
- package/dist/reins/_internal/harness_reins/owners/windows_scheduler.ps1 +156 -0
- package/dist/reins/_internal/harness_reins/templates/test.md +38 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/INSTALLER +1 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/METADATA +13 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/RECORD +199 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/REQUESTED +0 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/WHEEL +5 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/direct_url.json +1 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/entry_points.txt +3 -0
- package/dist/reins/_internal/harness_reins-0.9.0.dist-info/top_level.txt +1 -0
- package/dist/reins/_internal/lib-dynload/_bisect.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_blake2.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_bz2.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_cn.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_hk.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_iso2022.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_jp.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_kr.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_codecs_tw.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_contextvars.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_csv.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_ctypes.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_datetime.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_decimal.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_hashlib.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_heapq.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_json.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_lzma.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_md5.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_multibytecodec.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_opcode.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_pickle.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_posixsubprocess.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_random.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_sha1.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_sha2.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_sha3.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_socket.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_ssl.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_statistics.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_struct.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/_uuid.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/array.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/binascii.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/fcntl.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/grp.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/math.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/pyexpat.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/resource.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/select.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/termios.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/unicodedata.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/lib-dynload/zlib.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/_internal/libbz2.so.1.0 +0 -0
- package/dist/reins/_internal/libcrypto.so.1.1 +0 -0
- package/dist/reins/_internal/libffi.so.7 +0 -0
- package/dist/reins/_internal/liblzma.so.5 +0 -0
- package/dist/reins/_internal/libpython3.12.so.1.0 +0 -0
- package/dist/reins/_internal/libssl.so.1.1 +0 -0
- package/dist/reins/_internal/libuuid.so.1 +0 -0
- package/dist/reins/_internal/libz.so.1 +0 -0
- package/dist/reins/_internal/yaml/_yaml.cpython-312-x86_64-linux-gnu.so +0 -0
- package/dist/reins/reins +0 -0
- package/package.json +14 -4
- package/README.md +0 -3
|
Binary file
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
fe8eb0450082
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: harness-reins
|
|
3
|
+
description: Run long jobs (training, benchmarks, builds, test suites, deployments, data jobs, child agents) under Harness Reins (reins) so they outlive this turn, and get woken in this same Claude Code session when they finish via a background `reins wait`. Use instead of sleeping, polling logs, or leaving a job owned by the Bash tool whenever a command may take about a minute or longer. Also covers handling an `[reins-status]` repair block and acknowledging `[reins]` results.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Harness Reins for Claude Code
|
|
7
|
+
|
|
8
|
+
Reins hands a long command to an independent OS task owner (launchd on macOS, systemd on Linux,
|
|
9
|
+
Task Scheduler on Windows) and queues a callback when it exits. In Claude Code you receive that
|
|
10
|
+
callback **in this live session** by running `reins wait` as a background Bash command: Claude Code
|
|
11
|
+
wakes you when a background command exits, and `reins wait` exits as soon as the callback is ready.
|
|
12
|
+
|
|
13
|
+
The full reference (all flags, platforms, recovery and goals) is in [REFERENCE.md](REFERENCE.md).
|
|
14
|
+
Read it only when you need details beyond this page. It is shared with other agents; where it
|
|
15
|
+
differs from this page about callback delivery, this page applies to Claude Code.
|
|
16
|
+
|
|
17
|
+
## When to use it
|
|
18
|
+
|
|
19
|
+
- Reliably done within 60 seconds → run it in the foreground once. No Reins.
|
|
20
|
+
- About a minute or longer, uncertain duration, or might need a second check → `reins run` from the start.
|
|
21
|
+
- Never keep a job alive by polling it with `sleep`/`tail`, and never leave a long job owned by a
|
|
22
|
+
`run_in_background` Bash shell: it dies with the session and is not recovered.
|
|
23
|
+
|
|
24
|
+
## The workflow
|
|
25
|
+
|
|
26
|
+
1. **Submit** (foreground; returns in a second or two):
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
reins run --cwd "$PWD" --task "train model" -- python train.py --config configs/exp.yaml
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
stderr prints the task id, backend, log path, and a ready-made line:
|
|
33
|
+
`reins: Claude Code live callback: run in the background (run_in_background): .../reins wait --queue-dir ... --task <id>`
|
|
34
|
+
|
|
35
|
+
If it instead says the callback `arrives through the reins channel`, this session was started with
|
|
36
|
+
`reins claude`: skip step 2. The callback is pushed into this session as a
|
|
37
|
+
`<channel source="reins">` event; handle it as in step 3.
|
|
38
|
+
|
|
39
|
+
2. **Wait** — run exactly that `reins wait ... --task <id>` command with the Bash tool's
|
|
40
|
+
`run_in_background: true`. Do not run it in the foreground (it blocks until the job ends), and do
|
|
41
|
+
not poll its output. Then tell the user what is running and end your turn, or carry on with other
|
|
42
|
+
work.
|
|
43
|
+
|
|
44
|
+
If the Bash tool has no `run_in_background` (background tasks are disabled; `reins run` then says
|
|
45
|
+
so instead of printing a wait command), skip the wait: tell the user what is running and end your
|
|
46
|
+
turn. When the job finishes, Reins resumes this session headlessly and the callback arrives as the
|
|
47
|
+
next message.
|
|
48
|
+
|
|
49
|
+
3. **Wake up** — when the job finishes, the background command exits and prints a callback:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
[reins] <task-id>-c1
|
|
53
|
+
Task: train model
|
|
54
|
+
Result: exited 0 · 2h 3m 32s
|
|
55
|
+
From: run on systemd-user
|
|
56
|
+
Files: <task dir>/ (attempt-1.log)
|
|
57
|
+
Details: <path> (as needed | read before acting)
|
|
58
|
+
Session: <this session id> (only)
|
|
59
|
+
ACK after inspection: reins ack <task-id>-c1
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Read the background command's output, inspect the log and artifacts (read Details first when it
|
|
63
|
+
says "read before acting"), decide `continue | stop_success | stop_blocked | ask_user`, then run
|
|
64
|
+
the `reins ack ...` command from the callback. ACK means "received and inspected", not "goal done".
|
|
65
|
+
An exit code is process status, not proof that tests passed.
|
|
66
|
+
|
|
67
|
+
4. **Next step** — if you launch follow-up work, submit it with `reins run` again and start a new
|
|
68
|
+
background `reins wait --task <new-id>`. Inspect existing processes and outputs first: delivery is
|
|
69
|
+
at-least-once.
|
|
70
|
+
|
|
71
|
+
## Other entry points
|
|
72
|
+
|
|
73
|
+
- **Fresh child agent** (independent review, test authoring, a parallel fix):
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
reins agent claude --cwd "$PWD" --name parser-review -- "Inspect parser.py and report concrete defects."
|
|
77
|
+
reins agent codex --template test --name parser-tests -- "Test the contract in docs/parser.md."
|
|
78
|
+
reins agent continue <task-or-callback-id> --name recheck -- "I fixed those; review parser.py again."
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Every child needs `--name`. `reins agent continue <id>` reuses the same child with what it already
|
|
82
|
+
learned; `reins agent fork <id>` branches from it. `<id>` is the task ID, the callback ID, or the
|
|
83
|
+
node's full name; prefer IDs. See `reins context show <node>` for summaries;
|
|
84
|
+
never read a child's raw session.
|
|
85
|
+
|
|
86
|
+
Then background `reins wait --task <id>` exactly as for `reins run`. The child's result path is in the
|
|
87
|
+
callback. A Claude child needs a standalone `claude` CLI that is signed in (`claude auth status`);
|
|
88
|
+
the Claude desktop app's bundled CLI cannot authenticate on its own.
|
|
89
|
+
|
|
90
|
+
- **Work already owned elsewhere** (tmux, screen, Slurm, a script): add `reins done` at its end.
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
set +e; python train.py; status=$?
|
|
94
|
+
reins done --cwd "$PWD" --task "train model" --command "python train.py" --exit-code "$status"
|
|
95
|
+
exit "$status"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The callback id is not known in advance, so start a background `reins wait` with no `--task`: it
|
|
99
|
+
delivers the next unacknowledged callback bound to this session.
|
|
100
|
+
|
|
101
|
+
## Rules
|
|
102
|
+
|
|
103
|
+
- **After `--` comes one command, not shell code**: for `;`, `&&`, pipes or redirection use
|
|
104
|
+
`-- bash -c '...'` (`reins run --task check -- bash -c 'sleep 720; python3 report.py'`).
|
|
105
|
+
- **Heredoc scripts work**: input piped into `reins run` (`-- python3 - <<'EOF'`) becomes the task's
|
|
106
|
+
stdin. Without piped input the task's stdin is empty.
|
|
107
|
+
- **Session binding is automatic** from `CLAUDE_CODE_SESSION_ID`. Never invent a session id. `reins wait` refuses to run without a session.
|
|
108
|
+
- **One wait, one wake-up.** A wait exits after printing what it found; start a new one for the next
|
|
109
|
+
task. Every unacknowledged callback of this session keeps coming back until you ACK it.
|
|
110
|
+
- **If the session closes**, nothing is lost: when no waiter is alive, the Reins daemon falls back to a
|
|
111
|
+
headless `claude -p --resume <session>` from the session's original directory. That fallback needs
|
|
112
|
+
a signed-in standalone CLI; otherwise the callback stays queued and the next `reins wait` from this
|
|
113
|
+
session (or `reins status`) picks it up. After a live delivery, the daemon waits 30 minutes for the
|
|
114
|
+
ACK before it falls back.
|
|
115
|
+
- `reins wait` exists only for Claude Code. It refuses to run without `CLAUDE_CODE_SESSION_ID` and
|
|
116
|
+
never touches callbacks bound to other agents.
|
|
117
|
+
- **Do not** call `claude -p --resume` yourself, add `--via-daemon`, or invent launch flags. Callback
|
|
118
|
+
problems never change the task's own exit code unless the user asks for `--strict`.
|
|
119
|
+
- **Long objectives with several stages**: use `reins goal start|check|ack` with a YAML plan file, see
|
|
120
|
+
REFERENCE.md ("Goal acknowledgement"). Callback ACK never completes a goal.
|
|
121
|
+
|
|
122
|
+
## `[reins-status]` blocks
|
|
123
|
+
|
|
124
|
+
If `reins run`, `reins agent` or `reins done` prints JSON between `[reins-status]` and `[/reins-status]`, it is
|
|
125
|
+
addressed to you: fix the listed configuration issues yourself (do not hand routine setup back to the
|
|
126
|
+
user), run its `recheck_command`, then continue. Check `work.state` first — `task_persisted` or
|
|
127
|
+
`callback_queued` means the work already exists: repair around that id and **do not submit it again**.
|
|
128
|
+
For an explicit check: `reins doctor --agent claude --session "$CLAUDE_CODE_SESSION_ID"`.
|
|
129
|
+
|
|
130
|
+
## Install and verify
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
python3 -m pip install "git+https://github.com/lz59970062/harness-reins.git"
|
|
134
|
+
reins setup --force --enable --now
|
|
135
|
+
reins doctor --agent claude --session "$CLAUDE_CODE_SESSION_ID"
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Useful commands: `reins status` (unacknowledged callbacks), `reins cancel --id <id>`,
|
|
139
|
+
`reins retry --id <id>` (re-deliver a result without rerunning the task),
|
|
140
|
+
`tail -f <task log>` when the user asks to watch progress.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: harness-reins
|
|
3
|
+
description: Run long jobs (training, benchmarks, builds, test suites, deployments, data jobs, child agents) under Harness Reins (reins) so they outlive this turn, then end the turn; Reins starts a new turn in this same Codex thread with the result. Use instead of sleeping, polling logs, waiting on a running exec session, or blocking a tool call whenever a command or a wait for time to pass may take about a minute or longer. Also covers handling an `[reins-status]` repair block and acknowledging `[reins]` results.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Harness Reins for Codex
|
|
7
|
+
|
|
8
|
+
Reins hands a long command to an independent OS task owner (systemd on Linux, launchd on macOS,
|
|
9
|
+
Task Scheduler on Windows; `screen` as fallback) and queues a callback when it exits. When this
|
|
10
|
+
thread is idle, Reins delivers the callback **as a new turn in this same thread**: `codex exec
|
|
11
|
+
resume` for CLI sessions, the shared App Server for Codex Desktop. You do not wait for it; you end
|
|
12
|
+
your turn and the result comes back to you.
|
|
13
|
+
|
|
14
|
+
The full reference (all flags, platforms, Desktop modes, recovery and goals) is in
|
|
15
|
+
[REFERENCE.md](REFERENCE.md). Read it only when you need details beyond this page; where it
|
|
16
|
+
differs from this page about callback delivery, this page applies to Codex.
|
|
17
|
+
|
|
18
|
+
Reins resumes this thread with the permissions recorded when you submit (`workspace-write`,
|
|
19
|
+
`on-request` by default). If this session runs without a sandbox (for example
|
|
20
|
+
`--dangerously-bypass-approvals-and-sandbox` in a container), submit with
|
|
21
|
+
`--sandbox-mode danger-full-access --approval-policy never` (or have `REINS_SANDBOX_MODE` and
|
|
22
|
+
`REINS_APPROVAL_POLICY` set) so the resumed turn can still run commands and ACK.
|
|
23
|
+
|
|
24
|
+
## When to use it
|
|
25
|
+
|
|
26
|
+
- Reliably done within 60 seconds → run it in the foreground once. No Reins.
|
|
27
|
+
- About a minute or longer, uncertain duration, or might need a second check → `reins run` from the start.
|
|
28
|
+
- Waiting for time to pass (a real-time clock, a schedule, a cooldown) is a long job too: submit the
|
|
29
|
+
wait, `reins run --cwd "$PWD" --task "wait for hour 12" -- sleep 900`.
|
|
30
|
+
- Never wait inside this turn: no `sleep` longer than about a minute, no loops of `sleep` plus a
|
|
31
|
+
status or log check, no long `yield_time_ms` or repeated empty `write_stdin` on a running exec
|
|
32
|
+
session, no `tail -f`/`tail --pid`, and no `reins wait` (that is for Claude Code background
|
|
33
|
+
commands). Never start long jobs with `&`, `nohup` or `setsid`: Reins owns them.
|
|
34
|
+
|
|
35
|
+
## The workflow
|
|
36
|
+
|
|
37
|
+
1. **Submit** (returns in a second or two):
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
reins run --cwd "$PWD" --task "train model" -- python train.py --config configs/exp.yaml
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Inside Codex, Reins binds the callback to this thread through `$CODEX_THREAD_ID`. stderr prints
|
|
44
|
+
the task id, backend and log path. The command after `--` is argv, not shell code: use
|
|
45
|
+
`-- bash -c '...'` for pipes, `&&` or redirection.
|
|
46
|
+
|
|
47
|
+
2. **End your turn.** Do any independent work first, then finish with a short message saying what
|
|
48
|
+
is running and what you will do with the result. In `codex exec` this exits Codex; Reins resumes
|
|
49
|
+
this thread when the task ends. Submitting several tasks before ending the turn is fine: each
|
|
50
|
+
arrives as its own callback.
|
|
51
|
+
|
|
52
|
+
3. **Handle the callback** — it arrives as the user message of a new turn:
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
[reins] <task-id>-c1
|
|
56
|
+
Task: train model
|
|
57
|
+
Result: exited 0 · 2h 3m 32s
|
|
58
|
+
From: run on systemd-user
|
|
59
|
+
Files: <task dir>/ (attempt-1.log)
|
|
60
|
+
Details: <path> (as needed | read before acting)
|
|
61
|
+
Session: <this thread> (only)
|
|
62
|
+
ACK after inspection: reins ack <task-id>-c1
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Inspect the log and artifacts (read Details first when it says "read before acting"), decide
|
|
66
|
+
`continue | stop_success | stop_blocked | ask_user`, then run the `reins ack ...` command from
|
|
67
|
+
the callback. ACK means "received and inspected", not "goal done". An exit code is process
|
|
68
|
+
status, not proof that tests passed. Delivery is at-least-once: check existing processes and
|
|
69
|
+
outputs before relaunching anything. ACK **every** callback. If more work is needed, submit it
|
|
70
|
+
with `reins run` and end the turn again.
|
|
71
|
+
|
|
72
|
+
4. **Stop a task early** by killing its process (`pkill -f '<its command>'`); `reins cancel` cancels
|
|
73
|
+
only the callback, not the workload. The callback still arrives with the exit status; ACK it.
|
|
74
|
+
|
|
75
|
+
## Other entry points
|
|
76
|
+
|
|
77
|
+
- `reins agent codex|claude|pi --cwd "$PWD" --name <name> -- "<prompt>"` — a child agent; its result
|
|
78
|
+
comes back as a callback here. `reins agent continue <node>` or `fork <node>` reuses what that child
|
|
79
|
+
learned; `reins context show <node>` gives summaries (never read its raw session).
|
|
80
|
+
- `reins done --cwd "$PWD" --task "..." --exit-code 0` — report work you are already supervising.
|
|
81
|
+
- `reins status --state pending --state running` — inspect tasks and callbacks once; do not poll it.
|
|
82
|
+
|
|
83
|
+
## `[reins-status]` blocks
|
|
84
|
+
|
|
85
|
+
Reins prints an `[reins-status]` JSON block when something needs attention. You own the repair: follow
|
|
86
|
+
`repair_command`, then `recheck_command`. `callback_queued` or `task_persisted` means the work
|
|
87
|
+
already exists — repair delivery around that id and **do not submit it again**. Do not run
|
|
88
|
+
`codex exec resume` yourself from a tool call; Reins owns delivery.
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: harness-reins
|
|
3
|
+
description: Run long jobs (training, benchmarks, builds, test suites, deployments, data jobs, child agents) under Harness Reins (reins) so they outlive this run, and get the result steered back into this same Pi session when they finish. Use instead of sleeping, polling logs, or blocking a tool call whenever a command or a wait for time to pass may take about a minute or longer. Also covers handling an `[reins-status]` repair block and acknowledging `[reins]` results.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Harness Reins for Pi
|
|
7
|
+
|
|
8
|
+
Reins hands a long command to an independent OS task owner (systemd on Linux, launchd on macOS,
|
|
9
|
+
Task Scheduler on Windows; `screen` as fallback) and queues a callback when it exits. Reins's Pi
|
|
10
|
+
extension delivers that callback **into this live Pi process** through Pi's native steering:
|
|
11
|
+
while you are busy it arrives after the current tool batch, before your next model call; while
|
|
12
|
+
idle it starts a normal turn. You do not need to wait, poll, or end your run to receive it.
|
|
13
|
+
|
|
14
|
+
The full reference (all flags, platforms, recovery and goals) is in [REFERENCE.md](REFERENCE.md).
|
|
15
|
+
Read it only when you need details beyond this page. It is shared with other agents; where it
|
|
16
|
+
differs from this page about callback delivery, this page applies to Pi.
|
|
17
|
+
|
|
18
|
+
## When to use it
|
|
19
|
+
|
|
20
|
+
- Reliably done within 60 seconds → run it in the foreground once. No Reins.
|
|
21
|
+
- About a minute or longer, uncertain duration, or might need a second check → `reins run` from the start.
|
|
22
|
+
- Waiting for time to pass (a real-time clock, a schedule, a cooldown) is a long job too: submit the
|
|
23
|
+
wait, `reins run --cwd "$PWD" --task "wait for hour 12" -- sleep 900`, instead of `sleep 900` in a
|
|
24
|
+
tool call. Pi's shell has no time limit, so a long foreground `sleep` will not fail; it blocks
|
|
25
|
+
you and every callback steered to you until it returns.
|
|
26
|
+
- Never `sleep` longer than about a minute in a tool call, never loop `sleep` + status/log checks,
|
|
27
|
+
and never start long jobs with `&`, `nohup` or `setsid`: Reins owns them and tells you when they end.
|
|
28
|
+
|
|
29
|
+
## The workflow
|
|
30
|
+
|
|
31
|
+
1. **Submit** (returns in a second or two):
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
reins run --cwd "$PWD" --task "train model" -- python train.py --config configs/exp.yaml
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Inside Pi's shell, Reins binds the callback to this session's absolute `$PI_SESSION_FILE`
|
|
38
|
+
automatically. stderr prints the task id, backend and log path.
|
|
39
|
+
|
|
40
|
+
2. **Keep working** on independent work, or tell the user what is running and stop. There is
|
|
41
|
+
nothing to wait on: the callback is pushed to you. Do not poll the task: one look at its log to
|
|
42
|
+
check early progress is fine, but do not wait in a tool call for it to change. With several tasks
|
|
43
|
+
running, each finished one arrives as its own callback. In print mode (`pi -p`) a managed session
|
|
44
|
+
(`reins pi`) exits when you stop and Reins resumes it with the callback, so ending your answer is the
|
|
45
|
+
right way to wait.
|
|
46
|
+
|
|
47
|
+
3. **Handle the callback** — it arrives as a user message:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
[reins] <task-id>-c1
|
|
51
|
+
Task: train model
|
|
52
|
+
Result: exited 0 · 2h 3m 32s
|
|
53
|
+
From: run on systemd-user
|
|
54
|
+
Files: <task dir>/ (attempt-1.log)
|
|
55
|
+
Details: <path> (as needed | read before acting)
|
|
56
|
+
Session: <this session file> (only)
|
|
57
|
+
ACK after inspection: reins ack <task-id>-c1
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Inspect the log and artifacts (read Details first when it says "read before acting"), decide
|
|
61
|
+
`continue | stop_success | stop_blocked | ask_user`, then run the `reins ack ...` command from
|
|
62
|
+
the callback. ACK means "received and inspected", not "goal done". An exit code is process
|
|
63
|
+
status, not proof that tests passed. Delivery is at-least-once: check existing processes and
|
|
64
|
+
outputs before relaunching anything.
|
|
65
|
+
|
|
66
|
+
ACK **every** callback, including ones that arrive back to back while you handle another. A
|
|
67
|
+
callback that names "Earlier callbacks ... never ACKed" lists ids you missed: inspect each and
|
|
68
|
+
run its `reins ack`.
|
|
69
|
+
|
|
70
|
+
4. **Stop a task early** by killing its process (`pkill -f '<its command>'`); `reins cancel` cancels
|
|
71
|
+
only the callback, not the workload. The callback still arrives with the exit status; ACK it.
|
|
72
|
+
|
|
73
|
+
## Ordinary and managed Pi sessions
|
|
74
|
+
|
|
75
|
+
- **Ordinary Pi** (started as `pi`, with the extension installed) receives callbacks only while
|
|
76
|
+
it is running. If this process exits before ACKing a delivered callback, Reins marks it for manual
|
|
77
|
+
recovery instead of replaying it; when Pi was closed before delivery, reopen the session and run
|
|
78
|
+
`reins retry --id <callback-id>`.
|
|
79
|
+
- **Managed Pi** (`reins pi --cwd "$PWD"` or `reins pi --session /absolute/session.jsonl`) locks the
|
|
80
|
+
session file for its lifetime. After it fully exits, Reins may deliver a pending callback by
|
|
81
|
+
resuming the same file in print mode. Managed sessions are pinned: restart `reins pi` to switch,
|
|
82
|
+
fork or reload.
|
|
83
|
+
|
|
84
|
+
## Other entry points
|
|
85
|
+
|
|
86
|
+
- `reins agent codex|claude|pi --cwd "$PWD" --name <name> -- "<prompt>"` — a child agent; its result
|
|
87
|
+
comes back as a callback here. `reins agent continue <node>` or `fork <node>` reuses what that child
|
|
88
|
+
learned; `reins context show <node>` gives summaries (never read its raw session).
|
|
89
|
+
- `reins done --cwd "$PWD" --task "..." --exit-code 0` — report work you are already supervising.
|
|
90
|
+
- `reins status --state pending --state running` — inspect tasks and callbacks.
|
|
91
|
+
|
|
92
|
+
## `[reins-status]` blocks
|
|
93
|
+
|
|
94
|
+
Reins prints an `[reins-status]` JSON block when something needs attention. You own the repair: follow
|
|
95
|
+
`repair_command`, then `recheck_command`. `callback_queued` or `task_persisted` means the work
|
|
96
|
+
already exists — repair delivery around that id and **do not submit it again**. For Pi, a blocked
|
|
97
|
+
route usually means the extension is not loaded: `reins install-pi-extension`, then `/reload` (or
|
|
98
|
+
restart Pi), then recheck with `reins doctor --agent pi --session "$PI_SESSION_FILE"`.
|