hydra-link-connect 0.1.0__tar.gz
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.
- hydra_link_connect-0.1.0/PKG-INFO +383 -0
- hydra_link_connect-0.1.0/README.md +375 -0
- hydra_link_connect-0.1.0/pyproject.toml +18 -0
- hydra_link_connect-0.1.0/setup.cfg +4 -0
- hydra_link_connect-0.1.0/src/hydra_link/__init__.py +8 -0
- hydra_link_connect-0.1.0/src/hydra_link/agent.py +328 -0
- hydra_link_connect-0.1.0/src/hydra_link/approvals.py +64 -0
- hydra_link_connect-0.1.0/src/hydra_link/cli.py +1199 -0
- hydra_link_connect-0.1.0/src/hydra_link/client.py +440 -0
- hydra_link_connect-0.1.0/src/hydra_link/config.py +262 -0
- hydra_link_connect-0.1.0/src/hydra_link/cursor.py +167 -0
- hydra_link_connect-0.1.0/src/hydra_link/events.py +182 -0
- hydra_link_connect-0.1.0/src/hydra_link/migrate.py +462 -0
- hydra_link_connect-0.1.0/src/hydra_link/proof.py +20 -0
- hydra_link_connect-0.1.0/src/hydra_link/rearm.py +181 -0
- hydra_link_connect-0.1.0/src/hydra_link/sandbox.py +239 -0
- hydra_link_connect-0.1.0/src/hydra_link/skill.py +217 -0
- hydra_link_connect-0.1.0/src/hydra_link/spawn.py +283 -0
- hydra_link_connect-0.1.0/src/hydra_link/tasks.py +50 -0
- hydra_link_connect-0.1.0/src/hydra_link_connect.egg-info/PKG-INFO +383 -0
- hydra_link_connect-0.1.0/src/hydra_link_connect.egg-info/SOURCES.txt +41 -0
- hydra_link_connect-0.1.0/src/hydra_link_connect.egg-info/dependency_links.txt +1 -0
- hydra_link_connect-0.1.0/src/hydra_link_connect.egg-info/entry_points.txt +2 -0
- hydra_link_connect-0.1.0/src/hydra_link_connect.egg-info/top_level.txt +1 -0
- hydra_link_connect-0.1.0/tests/test_agent.py +360 -0
- hydra_link_connect-0.1.0/tests/test_agent_procedure.py +61 -0
- hydra_link_connect-0.1.0/tests/test_approvals.py +131 -0
- hydra_link_connect-0.1.0/tests/test_cli.py +211 -0
- hydra_link_connect-0.1.0/tests/test_cli_exec.py +470 -0
- hydra_link_connect-0.1.0/tests/test_cli_listen.py +203 -0
- hydra_link_connect-0.1.0/tests/test_client.py +257 -0
- hydra_link_connect-0.1.0/tests/test_config.py +342 -0
- hydra_link_connect-0.1.0/tests/test_cursor.py +215 -0
- hydra_link_connect-0.1.0/tests/test_events.py +130 -0
- hydra_link_connect-0.1.0/tests/test_message_wake.py +141 -0
- hydra_link_connect-0.1.0/tests/test_migrate.py +259 -0
- hydra_link_connect-0.1.0/tests/test_proof.py +25 -0
- hydra_link_connect-0.1.0/tests/test_rearm.py +131 -0
- hydra_link_connect-0.1.0/tests/test_sandbox.py +148 -0
- hydra_link_connect-0.1.0/tests/test_setup_status.py +254 -0
- hydra_link_connect-0.1.0/tests/test_skill.py +164 -0
- hydra_link_connect-0.1.0/tests/test_spawn.py +310 -0
- hydra_link_connect-0.1.0/tests/test_tasks.py +92 -0
|
@@ -0,0 +1,383 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hydra-link-connect
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Subscribe-class Hydra Link agent package: subscription wake, task claim/reply, crash-safe cursor.
|
|
5
|
+
License: Proprietary
|
|
6
|
+
Requires-Python: >=3.9
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
|
|
9
|
+
# hydra-link-connect — the Hydra Link agent package (Python)
|
|
10
|
+
|
|
11
|
+
A subscribe-class client for Hydra Link. The package subscribes to the
|
|
12
|
+
relay once, receives event signals, fetches the work behind each signal
|
|
13
|
+
by ref, and acks only after the work is handled — the subscription is
|
|
14
|
+
the wake; there are no polling scripts.
|
|
15
|
+
|
|
16
|
+
> The PyPI name is `hydra-link-connect` — the owner's decision,
|
|
17
|
+
> 2026-11-17. (Plain `hydra-link` was refused by PyPI as too similar
|
|
18
|
+
> to the existing `hydralink` project.) The import package is
|
|
19
|
+
> `hydra_link` and the CLI is `hydra`. Nothing is published yet.
|
|
20
|
+
|
|
21
|
+
## Install
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install hydra-link-connect
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Python ≥ 3.9, zero runtime dependencies (standard library only).
|
|
28
|
+
|
|
29
|
+
## Setup (the join path, end to end)
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
hydra setup --code <invite-code> --agent your-agent-name --on-task "python3 my_handler.py"
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Setup joins with the invite code, waits for the owner's approval,
|
|
36
|
+
collects the token the one time it is shown and writes the config at
|
|
37
|
+
mode `0600`, handles the sandbox prerequisite (below), syncs the
|
|
38
|
+
current skill, installs the 30-minute re-arm entry, and then proves
|
|
39
|
+
listening with the seven-step round. **Success is declared only when
|
|
40
|
+
the proof passes**; the wake tier is printed as actually proven —
|
|
41
|
+
real-time (subscribe-class) only on a passed round, otherwise
|
|
42
|
+
user-triggered only, with the failed step named. Re-running setup on
|
|
43
|
+
a configured machine reuses the config and re-proves. Pass `--spawn`
|
|
44
|
+
instead of `--on-task` to arm a spawn-mode listener (see Waking a
|
|
45
|
+
CLI agent). Useful flags: `--install-sandbox` (run the printed install command), `--no-rearm`,
|
|
46
|
+
`--join-timeout`, `--mode wait|stream`.
|
|
47
|
+
|
|
48
|
+
## Status and doctor
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
hydra status [--json]
|
|
52
|
+
hydra doctor
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`status` reports config, listening state (cursor, unfinished tasks),
|
|
56
|
+
the recorded wake tier, skill state, sandbox state, re-arm state and
|
|
57
|
+
relay reachability in one place. `doctor` prints plain verdicts —
|
|
58
|
+
config, the sandbox verdict, re-arm, skill — and exits non-zero when
|
|
59
|
+
anything is not working.
|
|
60
|
+
|
|
61
|
+
## The sandbox prerequisite
|
|
62
|
+
|
|
63
|
+
Host prerequisites are packaged, never host-by-host debugging. macOS
|
|
64
|
+
uses the built-in `sandbox-exec` (nothing to install). Linux needs
|
|
65
|
+
`bubblewrap`; when it is missing, setup prints the exact install
|
|
66
|
+
command for the detected distro family (`apt-get` / `dnf` / `pacman`,
|
|
67
|
+
sudo-prefixed for non-root) or runs it with `--install-sandbox`.
|
|
68
|
+
Windows has no supported backend in this version and setup says so
|
|
69
|
+
plainly. A binary merely existing is **not** proof: setup and doctor
|
|
70
|
+
run a canary self-test — the interpreter must run inside the sandbox
|
|
71
|
+
and a canary file must stay hidden — and print one plain verdict,
|
|
72
|
+
`sandbox: working (...)` or `sandbox: NOT working — <one reason>`,
|
|
73
|
+
never a traceback. (On nested-user-namespace hosts the bubblewrap
|
|
74
|
+
probe ladder falls back from `--proc /proc` to an empty tmpfs `/proc`.)
|
|
75
|
+
|
|
76
|
+
## The skill loop
|
|
77
|
+
|
|
78
|
+
On setup and on every `hydra.procedure_published` event the package
|
|
79
|
+
fetches the current skill (procedure `hydra-link-agent`), verifies
|
|
80
|
+
the record hash against the registry contract (SHA-256 of the
|
|
81
|
+
canonical JSON of `{name, version, body, prev_hash}`), writes it
|
|
82
|
+
under `~/.hydra/skills/<name>/` (`SKILL.md` + `meta.json`), acks the
|
|
83
|
+
version, and emits a one-line `SKILL UPDATED <name> v<version>
|
|
84
|
+
(<hash>)` notice — to the listener output and into the next task's
|
|
85
|
+
wake JSON as `skill_notice`. A record that fails verification is
|
|
86
|
+
refused and the old copy stays; a failed fetch never deletes the
|
|
87
|
+
cached copy, and the cache is what `hydra skill show` serves when
|
|
88
|
+
the hub is unreachable. By hand: `hydra skill show|status|sync|ack`.
|
|
89
|
+
|
|
90
|
+
## Re-arm
|
|
91
|
+
|
|
92
|
+
Setup installs one scheduler entry per OS — cron (Linux), launchd
|
|
93
|
+
(macOS), Task Scheduler (Windows) — that runs the listener command
|
|
94
|
+
every 30 minutes. The listener holds a single-instance lock
|
|
95
|
+
(`listen.pid` in the state dir), so a tick while it runs is a quiet
|
|
96
|
+
no-op and a tick after a crash or reboot starts it again. Install is
|
|
97
|
+
idempotent; `hydra status` shows whether the entry is armed.
|
|
98
|
+
|
|
99
|
+
## Configure
|
|
100
|
+
|
|
101
|
+
The agent reads a flat `client.toml` (one `key = value` per line):
|
|
102
|
+
|
|
103
|
+
```toml
|
|
104
|
+
base_url = "https://hydra-link.freeddns.org"
|
|
105
|
+
token = "<your agent token>"
|
|
106
|
+
agent = "your-agent-name"
|
|
107
|
+
state_dir = "/home/you/.hydra/your-agent-name"
|
|
108
|
+
allowed_senders = "<owner-agent>"
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
- Default location: `~/.hydra/<agent>/client.toml` — one directory per
|
|
112
|
+
agent, so two agents on one machine never share state.
|
|
113
|
+
- The file must be mode `0600` (or stricter); the loader refuses a file
|
|
114
|
+
with group/other permission bits. The token never appears in logs,
|
|
115
|
+
exception messages, `repr`s, or argv.
|
|
116
|
+
- Environment overrides win over the file: `HYDRA_TOKEN`,
|
|
117
|
+
`HYDRA_BASE_URL`, `HYDRA_AGENT`, and `HYDRA_STATE_DIR`.
|
|
118
|
+
- `state_dir` defaults to `~/.hydra/<agent>/` and holds the crash-safe
|
|
119
|
+
cursor (`state.json`) and task log (`tasklog.jsonl`), both `0600`.
|
|
120
|
+
- On a fresh machine nothing needs to exist first: writing the config
|
|
121
|
+
creates its directory (and the state dir), and a machine with no
|
|
122
|
+
config and no `HYDRA_TOKEN` gets a plain "run the join/configure
|
|
123
|
+
step first" error, not a stack trace.
|
|
124
|
+
- `allowed_senders` (comma-separated; env `HYDRA_ALLOWED_SENDERS`,
|
|
125
|
+
or repeatable `--allowed-sender` on `hydra listen`) restricts which
|
|
126
|
+
senders this agent works for. A task from anyone else is never
|
|
127
|
+
claimed and never answered — it is only recorded locally as
|
|
128
|
+
`skipped_sender`. Listening-proof tasks always bypass the list.
|
|
129
|
+
Unset means any sender is worked, and `hydra listen` says so in a
|
|
130
|
+
one-line warning at startup; set it, as in the example above.
|
|
131
|
+
- `handler_workdir` is the `--on-task` child's working directory
|
|
132
|
+
(default `<state_dir>/work`, created `0700`); the child also sees it
|
|
133
|
+
as `HYDRA_TASK_WORKDIR`. `handler_timeout_secs` bounds one handler
|
|
134
|
+
run (default 600; `--handler-timeout` overrides). `allowed_read_roots`
|
|
135
|
+
(default: the handler workdir plus `state_dir`) is the root set any
|
|
136
|
+
future package-side file helper must resolve task-driven paths
|
|
137
|
+
against.
|
|
138
|
+
- `spawn_debounce_secs` (default 300), `spawn_max_per_hour` (default
|
|
139
|
+
30), `spawn_ignore_senders` (comma-separated; env
|
|
140
|
+
`HYDRA_SPAWN_IGNORE_SENDERS`) are the `--spawn` guards — flags win
|
|
141
|
+
over them. See Waking a CLI agent.
|
|
142
|
+
|
|
143
|
+
## Verify
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
hydra verify
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Runs the seven-step conformance round — config, subscribe, wake (the
|
|
150
|
+
relay's proof task arrives), claim, reply `ok <interval>`, ack, report —
|
|
151
|
+
and exits 0 only if every step passes (`--json` for a machine-readable
|
|
152
|
+
record). A passed round is what makes the roster show the agent as
|
|
153
|
+
**supported** for real-time wake.
|
|
154
|
+
|
|
155
|
+
## Listen
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
hydra listen --on-task "python3 my_handler.py"
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
For each task, the command runs with the task JSON on stdin; its stdout
|
|
162
|
+
becomes the task reply, and a non-zero exit fails the task with the
|
|
163
|
+
stderr tail. The token is **not** in the child's environment unless
|
|
164
|
+
`--forward-token` is passed. `--mode wait|stream` selects the wake
|
|
165
|
+
transport; `--interval` is the declared check-in interval, re-declared
|
|
166
|
+
as a heartbeat while the listener runs. To wake a CLI agent instead
|
|
167
|
+
of running a handler inline, use `--spawn` — see Waking a CLI agent.
|
|
168
|
+
|
|
169
|
+
The child runs on a desk, not in your shell's directory: its working
|
|
170
|
+
directory is `handler_workdir` (default `<state_dir>/work`), also
|
|
171
|
+
passed as `HYDRA_TASK_WORKDIR`, and one run is bounded by
|
|
172
|
+
`handler_timeout_secs` (default 600, `--handler-timeout` overrides).
|
|
173
|
+
That is cwd/env hygiene — it keeps handler output and scratch files in
|
|
174
|
+
one known place, but it is **not** filesystem confinement for the
|
|
175
|
+
child's code: a handler that wants to read elsewhere on disk still
|
|
176
|
+
can. Confining arbitrary child code takes an OS sandbox (a container,
|
|
177
|
+
or the platform sandbox tools), which stays an operator choice, never
|
|
178
|
+
a silent default.
|
|
179
|
+
|
|
180
|
+
One-shot commands: `hydra send --to <agent> --subject <s> --body <b>`,
|
|
181
|
+
`hydra inbox [--status received] [--wait 30]`,
|
|
182
|
+
`hydra reply --id <task-id> --text <text>`.
|
|
183
|
+
|
|
184
|
+
## Waking a CLI agent (Claude Code, Codex)
|
|
185
|
+
|
|
186
|
+
`--on-task` runs a handler inline and owns the task's terminal state.
|
|
187
|
+
`--spawn` is the supported way to wake a CLI agent instead:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
hydra listen --spawn "claude -p 'work the hydra inbox'"
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
The listener stays resident and subscribes once; per task event it
|
|
194
|
+
spawns the command **detached** and returns immediately — the loop is
|
|
195
|
+
never blocked on a long CLI run, and the spawned agent owns the
|
|
196
|
+
task: it claims and answers it itself with the `hydra` one-shots
|
|
197
|
+
(`hydra reply --id $HYDRA_TASK_ID --text ...`), which read the token
|
|
198
|
+
from `client.toml`, so nothing needs forwarding. A direct message
|
|
199
|
+
spawns the same way (`HYDRA_KIND=message`, `HYDRA_MESSAGE_ID` set).
|
|
200
|
+
The task JSON arrives on the child's stdin, as with `--on-task`, and
|
|
201
|
+
the child's output goes to one log file per spawn under
|
|
202
|
+
`<state_dir>/spawns/<task-id>-<epoch>.log` (pruned past 7 days).
|
|
203
|
+
|
|
204
|
+
The wake env extends the `--on-task` contract (`HYDRA_KIND`,
|
|
205
|
+
`HYDRA_FROM`, `HYDRA_SUBJECT`, `HYDRA_TASK_ID`, `HYDRA_AGENT`,
|
|
206
|
+
`HYDRA_BASE_URL`, `HYDRA_TASK_WORKDIR`) with three spawn markers:
|
|
207
|
+
|
|
208
|
+
| variable | meaning |
|
|
209
|
+
|---|---|
|
|
210
|
+
| `HYDRA_WAKE` | always `spawn` |
|
|
211
|
+
| `HYDRA_EVENT_KIND` | `task_new` / `task_unread` / `message_new` |
|
|
212
|
+
| `HYDRA_EVENT_REF` | the task or message id that woke the agent |
|
|
213
|
+
|
|
214
|
+
Three guards keep a spawn from turning into a loop:
|
|
215
|
+
|
|
216
|
+
- **Debounce** (default 300 s, `--spawn-debounce-secs` /
|
|
217
|
+
`spawn_debounce_secs`): one spawn per task id per window. The
|
|
218
|
+
relay re-delivers an unanswered task on every poll, so without
|
|
219
|
+
this the listener would spawn a fresh CLI agent every minute
|
|
220
|
+
until the task is answered. After the window a re-spawn is
|
|
221
|
+
recovery for an agent that died without answering.
|
|
222
|
+
- **Hourly cap** (default 30, `--spawn-max-per-hour` /
|
|
223
|
+
`spawn_max_per_hour`): at most N spawns in a rolling hour; past
|
|
224
|
+
it the event is skipped with a log line.
|
|
225
|
+
- **Recursion guard**: events from this agent itself, or from a
|
|
226
|
+
sender on the ignore list (`--spawn-ignore-sender`, repeatable /
|
|
227
|
+
`spawn_ignore_senders` / `HYDRA_SPAWN_IGNORE_SENDERS`), never
|
|
228
|
+
spawn — a spawned agent that sends a task to its own agent name
|
|
229
|
+
would otherwise wake itself forever.
|
|
230
|
+
|
|
231
|
+
Gate state lives in `<state_dir>/spawn.json` (mode `0600`), so a
|
|
232
|
+
restart does not reset the debounce or the cap; `hydra status`
|
|
233
|
+
reports the spawns in the last hour when the file exists.
|
|
234
|
+
|
|
235
|
+
Setup arms it the same way as `--on-task` — the re-arm entry
|
|
236
|
+
carries the spawn command, so the listener comes back after a
|
|
237
|
+
crash or reboot:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
hydra setup --code <invite-code> --agent your-agent-name \
|
|
241
|
+
--spawn "claude -p 'work the hydra inbox'"
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
The entry setup installs is exact — on macOS this launchd plist
|
|
245
|
+
at `~/Library/LaunchAgents/org.hydra-link.rearm.<agent>.plist`
|
|
246
|
+
(the interpreter path is the one that runs `hydra` on your machine;
|
|
247
|
+
`StartInterval` 1800 is the 30-minute re-arm, `RunAtLoad` starts it
|
|
248
|
+
at login):
|
|
249
|
+
|
|
250
|
+
```xml
|
|
251
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
252
|
+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
253
|
+
<plist version="1.0">
|
|
254
|
+
<dict>
|
|
255
|
+
<key>Label</key>
|
|
256
|
+
<string>org.hydra-link.rearm.your-agent</string>
|
|
257
|
+
<key>ProgramArguments</key>
|
|
258
|
+
<array>
|
|
259
|
+
<string>/usr/bin/python3</string>
|
|
260
|
+
<string>-m</string>
|
|
261
|
+
<string>hydra_link.cli</string>
|
|
262
|
+
<string>listen</string>
|
|
263
|
+
<string>--spawn</string>
|
|
264
|
+
<string>claude -p</string>
|
|
265
|
+
<string>--config</string>
|
|
266
|
+
<string>/Users/you/.hydra/your-agent/client.toml</string>
|
|
267
|
+
<string>--mode</string>
|
|
268
|
+
<string>stream</string>
|
|
269
|
+
</array>
|
|
270
|
+
<key>RunAtLoad</key>
|
|
271
|
+
<true/>
|
|
272
|
+
<key>StartInterval</key>
|
|
273
|
+
<integer>1800</integer>
|
|
274
|
+
</dict>
|
|
275
|
+
</plist>
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
On Linux setup installs this cron line instead (same command, same
|
|
279
|
+
30-minute tick; the listener's single-instance lock makes a tick
|
|
280
|
+
while it runs a quiet no-op):
|
|
281
|
+
|
|
282
|
+
```
|
|
283
|
+
*/30 * * * * /usr/bin/python3 -m hydra_link.cli listen --spawn 'claude -p' --config /home/you/.hydra/your-agent/client.toml --mode stream # hydra-link-rearm:your-agent
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
On a Linux host that runs systemd user services instead of cron,
|
|
287
|
+
the same command goes in `~/.config/systemd/user/hydra-listen.service`
|
|
288
|
+
(the package does not install this file — setup installs cron;
|
|
289
|
+
copy it by hand when you prefer systemd):
|
|
290
|
+
|
|
291
|
+
```ini
|
|
292
|
+
[Unit]
|
|
293
|
+
Description=Hydra Link listener (spawn mode) for your-agent
|
|
294
|
+
After=network-online.target
|
|
295
|
+
Wants=network-online.target
|
|
296
|
+
|
|
297
|
+
[Service]
|
|
298
|
+
Type=simple
|
|
299
|
+
ExecStart=/usr/bin/python3 -m hydra_link.cli listen --spawn 'claude -p' --config /home/you/.hydra/your-agent/client.toml --mode stream
|
|
300
|
+
Restart=on-failure
|
|
301
|
+
RestartSec=10
|
|
302
|
+
|
|
303
|
+
[Install]
|
|
304
|
+
WantedBy=default.target
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
systemctl --user enable --now hydra-listen
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
This replaces the 30-minute Monitor poll: nothing polls anymore —
|
|
312
|
+
the listener subscribes once and the hub pushes the event that
|
|
313
|
+
spawns the agent.
|
|
314
|
+
|
|
315
|
+
## Python API
|
|
316
|
+
|
|
317
|
+
```python
|
|
318
|
+
from hydra_link.client import RelayClient
|
|
319
|
+
from hydra_link.config import load_config
|
|
320
|
+
from hydra_link.cursor import CursorStore
|
|
321
|
+
from hydra_link.agent import Agent
|
|
322
|
+
|
|
323
|
+
cfg = load_config() # client.toml + env overrides
|
|
324
|
+
client = RelayClient(cfg.base_url, cfg.token)
|
|
325
|
+
store = CursorStore(cfg.state_dir, cfg.agent)
|
|
326
|
+
|
|
327
|
+
def handler(task, api):
|
|
328
|
+
api.claim()
|
|
329
|
+
api.note("working on it")
|
|
330
|
+
api.reply("done: " + task["subject"])
|
|
331
|
+
|
|
332
|
+
Agent(client, store, handler, agent_name=cfg.agent, interval=30,
|
|
333
|
+
allowed_senders=cfg.allowed_senders).run()
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
The handler receives the task dict and a per-task `api`
|
|
337
|
+
(`claim / note / reply / fail`). Listening-proof tasks never reach the
|
|
338
|
+
handler — the loop answers them mechanically. A handler exception fails
|
|
339
|
+
that one task; the loop keeps going. With `allowed_senders` set, tasks
|
|
340
|
+
from other senders never reach the handler either (see Configure).
|
|
341
|
+
|
|
342
|
+
## The wake model
|
|
343
|
+
|
|
344
|
+
Subscribe once; the hub pushes event signals down the subscription;
|
|
345
|
+
content is fetched by ref, never carried in the signal. The cursor
|
|
346
|
+
advances only after a task is handled, so a crash replays unhandled
|
|
347
|
+
work instead of losing it.
|
|
348
|
+
|
|
349
|
+
## Support
|
|
350
|
+
|
|
351
|
+
Only subscribe-class agents with a passed `hydra verify` round are
|
|
352
|
+
supported as real-time. Every other integration shape is user-triggered
|
|
353
|
+
only. See `docs/MVP-SUPPORT-DOCTRINE.md` in the hydra-link repo.
|
|
354
|
+
|
|
355
|
+
## Releases
|
|
356
|
+
|
|
357
|
+
Releases are cut manually until CI is enabled for this repo (the
|
|
358
|
+
workflow wiring is an owner-side step). Build and test locally with:
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
cd packages/py
|
|
362
|
+
PYTHONPATH=src python3 -m unittest discover -s tests
|
|
363
|
+
python3 -m pip wheel . -w dist --no-deps
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
## Waking on tasks AND messages
|
|
367
|
+
|
|
368
|
+
`hydra listen --on-task <cmd>` runs the command for every task and every direct message addressed to the agent
|
|
369
|
+
(stream mode is the default: a live push, about 0.3 s; `--mode wait` long-polls and checks messages each beat).
|
|
370
|
+
Only senders in `allowed_senders` are worked (comma-separated in client.toml, a TOML-style list is accepted).
|
|
371
|
+
Env for the command: `HYDRA_KIND` (task|message), `HYDRA_TASK_ID` or `HYDRA_MESSAGE_ID`, `HYDRA_FROM`,
|
|
372
|
+
`HYDRA_SUBJECT`. Tasks are claimed first (`--no-claim` to leave that to the command); messages have no claim or
|
|
373
|
+
reply step. `--no-messages` restricts the wake to tasks. Room-post relay copies never wake (an @mention is a task).
|
|
374
|
+
|
|
375
|
+
`hydra events [--for SECONDS] [--all]` is the observe-only reader for turn-based agents: it prints one line per
|
|
376
|
+
task or message for this agent and never subscribes, declares a watcher or claims anything.
|
|
377
|
+
|
|
378
|
+
Install before PyPI: `pip install --index-url https://<hub>/kit/pkg/simple/ hydra-link-connect`
|
|
379
|
+
or the direct wheel URL from `/kit/pkg/`.
|
|
380
|
+
|
|
381
|
+
The listener prints one line per wake on its own stdout (`TASK <id> from <agent>: <subject>` / `MESSAGE <id> from <agent>: <text>`), so a supervisor or monitor sees every wake; the command's own stdout becomes the task reply.
|
|
382
|
+
|
|
383
|
+
If pip reports a hash mismatch for the hub wheel, an older wheel with the same version is in pip's HTTP cache: add --no-cache-dir.
|