@sjawhar/pi-envoy 11.4.0 → 11.5.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/README.md +242 -0
- package/dist/dispatch.js +401 -64
- package/dist/envoy.js +2385 -117
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -220,3 +220,245 @@ EOF
|
|
|
220
220
|
Lifecycle and scope decisions between Legion roles go through `envoy_publish` to the owning
|
|
221
221
|
architect's role topic; Dispatch is for durable questions to the human and the shared
|
|
222
222
|
document, not for coordination between roles.
|
|
223
|
+
|
|
224
|
+
## AskGate
|
|
225
|
+
|
|
226
|
+
AskGate reviews each Dispatch write of a session's main agent before the write posts. One model
|
|
227
|
+
call judges the write against the rules in `extensions/askgate/rules.md` and answers `allow` or
|
|
228
|
+
`revise`. A `revise` answer carries the reason and the fix. The gate reviews these calls:
|
|
229
|
+
|
|
230
|
+
- `dispatch ask`, `dispatch message`, `dispatch edit-ask`, `dispatch comment`, `dispatch doc-edit`
|
|
231
|
+
and `dispatch request-approval`
|
|
232
|
+
- `dispatch issue` with `--spec` or `--spec-file`
|
|
233
|
+
- `dispatch artifact` when it uploads a markdown document: inline text (`--content`,
|
|
234
|
+
`--content-file`), a `--path` file whose name ends in `.md` or `.markdown`, or a `--name` that
|
|
235
|
+
ends in `.md`
|
|
236
|
+
|
|
237
|
+
Every other Dispatch command is outside the gate, and its text posts unreviewed: among them
|
|
238
|
+
`dispatch issue-update --reason`, `dispatch resolve-ask --reason` and `dispatch suggest`.
|
|
239
|
+
|
|
240
|
+
The gate reads the arguments from the command's own `--dry-run`. An upload that reads its name
|
|
241
|
+
from a file (`--name-file`) is decided from the name the dry run prints. `--path-file` is refused:
|
|
242
|
+
its content names a file the gate does not read before Dispatch opens it. An upload whose name or
|
|
243
|
+
path holds an expansion (`"$NAME"`) is outside the form the gate reads. The gate reads each file
|
|
244
|
+
whose text the write posts, a `--<field>-file` operand and an upload's `--path`, in place, shows
|
|
245
|
+
those bytes to the model, and runs the call as written. The marker it mints binds the sha256 of
|
|
246
|
+
each file. Before the write posts, the CLI reads each file again and refuses one whose bytes
|
|
247
|
+
changed after the review, and an upload sends the bytes the CLI read for that check. An `--image`
|
|
248
|
+
file is not one of them: the model reads the path, not the picture. The file must be a regular
|
|
249
|
+
file. The gate refuses a missing file, a directory, a device and a FIFO before it reads them, and
|
|
250
|
+
a path that reaches a file descriptor of whichever process opens it (`/dev/stdin`, `/dev/fd/N`,
|
|
251
|
+
`/proc/self/fd/N`, `/proc/thread-self/fd/N`, `/proc/<n>/fd/N`, and any link to one): AskGate
|
|
252
|
+
would open it in Oh My Pi's process and the command in its shell. For text from standard input,
|
|
253
|
+
use `--<field>-file -` with a quoted here-document. For an upload, that is `--content-file -`:
|
|
254
|
+
the CLI reads `--path -` as a file named `-`. The gate cuts all arguments at 64 KiB as one JSON
|
|
255
|
+
block, so it reviews only part of a long document. It judges an upload against content failure
|
|
256
|
+
10 alone: a plan or a report is long by nature. An upload of any other file is not reviewed. A
|
|
257
|
+
`task` subagent is not reviewed.
|
|
258
|
+
|
|
259
|
+
**A file a call of the same message writes.** Oh My Pi runs the gate for every call of a message
|
|
260
|
+
before any call of that message runs. So the gate reads a file before an earlier call of the same
|
|
261
|
+
message writes or edits it. A file that is not there yet is refused in `block` mode with the
|
|
262
|
+
advice to send the call again in a later message; in `warn` mode the call runs unreviewed, with
|
|
263
|
+
that advice as its note. A file that an earlier call changed is refused by the CLI in `block` mode
|
|
264
|
+
(`… AskGate reviews the calls of a message before any of them runs, so it did not review that
|
|
265
|
+
change. Send the call again in a later message.`); in `warn` mode it posts with a
|
|
266
|
+
`dispatch: warning:` line. Write or edit a file in one message, and send the write that posts it
|
|
267
|
+
in the next.
|
|
268
|
+
|
|
269
|
+
**The form the gate reads.** One `dispatch` call, alone in the bash call:
|
|
270
|
+
|
|
271
|
+
```
|
|
272
|
+
[cd <literal path> && ] dispatch <subcommand> <literal words…> [2>&1] [<<'DELIM' … DELIM] [| head|tail [-n N]]
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
- The program is `dispatch` by name, or a literal path that ends in it.
|
|
276
|
+
- Every word is literal. Outside quotes a word holds only letters, digits and `._/+@%:,=-`, so no
|
|
277
|
+
`$`, backtick, `~`, `*`, `?`, `[`, `{`, `}` or backslash. Single quotes make every character
|
|
278
|
+
literal. Inside double quotes there is no `$`, backtick or backslash. A quoted word may run over
|
|
279
|
+
several lines.
|
|
280
|
+
- A backslash at the end of a line continues the command, as bash reads it.
|
|
281
|
+
- One `cd <literal path> &&` may stand before it, and one `2>&1` after it.
|
|
282
|
+
- One here-document may feed it, with its delimiter in quotes (`<<'EOF'` or `<<"EOF"`), before or
|
|
283
|
+
after the `2>&1`. Its body is on the lines after the line that opens it.
|
|
284
|
+
- One trailing pipe stage may read its output: `head` or `tail`, alone or with `-n N`, `-nN` or
|
|
285
|
+
`-N`. The dry run leaves it out.
|
|
286
|
+
- Nothing else is in the call: no second command, no other pipe, no `;`, `&&`, `||` or `&`, no
|
|
287
|
+
assignment, no other redirect and no comment.
|
|
288
|
+
|
|
289
|
+
**Everything else runs, and the `dispatch` command enforces the review.** The gate reads no other
|
|
290
|
+
form and refuses none: a call outside the literal grammar runs as written. What holds it back is
|
|
291
|
+
the CLI. For each literal call it lets run, the gate mints a single-use marker; the CLI posts a
|
|
292
|
+
gated write only when it consumes one, so a write sent any other way is refused in `block` mode:
|
|
293
|
+
|
|
294
|
+
- **The record.** While the gate is bound, pi-envoy keeps one owner-only file for its process in
|
|
295
|
+
the `askgate/` directory of the CLI's state directory of each session id it binds
|
|
296
|
+
(`<state>/sessions/<id>/askgate/<pid>-<start>.json`, where `<state>` is `DISPATCH_STATE_DIR`,
|
|
297
|
+
else `$XDG_STATE_HOME/dispatch`, else `~/.local/state/dispatch`). It names the Oh My Pi process,
|
|
298
|
+
its Linux start time, and the process's owner-only marker store. Each process writes and removes
|
|
299
|
+
only its own file, so two processes that bind one session never drop each other. pi-envoy sets
|
|
300
|
+
`DISPATCH_STATE_DIR` in the session's environment when it is not set, so a command that changes
|
|
301
|
+
`HOME` or `XDG_STATE_HOME` still finds the record. A record of a session the process switched
|
|
302
|
+
away from stays until the process exits, since a shell or an eval kernel started before the
|
|
303
|
+
switch still acts as that session. A record whose process is gone, or whose pid another process
|
|
304
|
+
now holds, is inert, and the CLI's session pruning keeps a directory whose record is live. A
|
|
305
|
+
record pi-envoy cannot write is a notice in the session, at start or at a switch.
|
|
306
|
+
- **The marker.** The gate mints one file in the store for each literal call it lets run, created
|
|
307
|
+
owner-only and exclusively. It binds the exact argument vector the CLI receives and, behind a
|
|
308
|
+
review or a deliberate pass (a rebuttal, a breaker trip, a halt, another provider), the digest
|
|
309
|
+
of the arguments the dry run printed and the sha256 of each file the argv names, as the gate
|
|
310
|
+
read it. A call no verdict stands behind, and a `task` subagent's literal call, get a marker of
|
|
311
|
+
the argument vector alone. Nothing of it is in the command the agent sees. A marker goes when
|
|
312
|
+
its call ends, is refused or the session shuts down; a backgrounded call keeps its marker until
|
|
313
|
+
shutdown, and a marker older than two hours, longer than any tool's time limit, is refused and
|
|
314
|
+
removed. The process removes its store when it exits; the CLI's daily session pruning removes
|
|
315
|
+
the store of a process that is gone and that nothing changed for two hours.
|
|
316
|
+
- **The check.** After `--help`, `--dry-run` and the session and Dispatch settings, and before a
|
|
317
|
+
gated write posts, the CLI reads the session's record. With a live one it reads each file the
|
|
318
|
+
argv names once and consumes one matching marker by unlinking it: exactly one process wins, so a
|
|
319
|
+
marker posts one write and a replay finds none. In `block` mode a write with no matching marker
|
|
320
|
+
is refused (`dispatch <command> was not called: AskGate is on for this session, …`, which names
|
|
321
|
+
the form to send, or, for a file that changed after the review, says to send the call again in a
|
|
322
|
+
later message). In `warn` mode the CLI first records the write in the session's ledger, refuses
|
|
323
|
+
it when the ledger cannot take that line, and then posts it with a `dispatch: warning:` line.
|
|
324
|
+
Either way pi-envoy records an `advisor-gate` entry with outcome `unmarked`. A record that cannot
|
|
325
|
+
be read, or that names a store that is gone, is a refusal. A session no live record names needs
|
|
326
|
+
no marker: a terminal, CI, Claude Code, OpenCode, a pod without pi-envoy, a session with no
|
|
327
|
+
Dispatch and one with `askgate.enabled: false`.
|
|
328
|
+
- **The cause note.** When a `bash` call outside the literal form holds a `dispatch` word and a
|
|
329
|
+
gated subcommand, and its result holds the CLI's refusal (or warn-mode warning) of a write with
|
|
330
|
+
no marker, the gate appends an `AskGate note:` to that result. It names the first cause it found
|
|
331
|
+
in the call, with the call's own text (an expansion in a value, a double-quoted value over lines
|
|
332
|
+
with an expansion in it, a program that runs the write such as `xargs` or `timeout`, a pipe, a
|
|
333
|
+
second command, an assignment, a redirect), and the change that puts the write in the literal
|
|
334
|
+
form. The note is help only: the gate refuses nothing for it.
|
|
335
|
+
|
|
336
|
+
The gated writes are the same list for the gate and the CLI (`gatedWrite` in
|
|
337
|
+
`@legion/envoy-client/askgate-marker`): the six commands above, an `issue` with a spec and an
|
|
338
|
+
`artifact` that uploads a markdown document. `--help`, `--dry-run` and every other command need no
|
|
339
|
+
marker. So a pipe to a program other than one trailing `head` or `tail`, a loop, a variable,
|
|
340
|
+
`xargs`, an alias, a script, `python3 -c`, `node -e`, or a process an eval cell starts runs, and
|
|
341
|
+
its gated write is refused by the CLI in `block` mode with the form to send; a call that holds no
|
|
342
|
+
Dispatch write, such as a commit message or a search pattern that names one, runs and posts
|
|
343
|
+
nothing. A literal call whose last command gives no argument vector is refused in `block` mode. A
|
|
344
|
+
gate that did not load refuses each literal call at the hook, so those never reach the CLI; it
|
|
345
|
+
writes the record and mints nothing, so every gated write that does reach the CLI — one outside the
|
|
346
|
+
literal form, and a subagent's literal one — is refused where the session set `OMP_ASKGATE=block`,
|
|
347
|
+
and at the warn default posts with a warning and an `unmarked` entry.
|
|
348
|
+
|
|
349
|
+
**Where the gate binds.** AskGate binds only in a session that has Dispatch, judged at load from
|
|
350
|
+
the session's own envoy.json and the variables over it (`DISPATCH_URL` and the other Dispatch
|
|
351
|
+
variables), with a checkout's `.envoy/envoy.json` able to turn it on and never off: a checkout that
|
|
352
|
+
names its own server and token gives the session a Dispatch, and one that turns off the Dispatch of
|
|
353
|
+
its own directory leaves the gate bound, since a later command can still pass that with
|
|
354
|
+
`DISPATCH_URL`. A session or a pod with no Dispatch has no write to review, so it gets no gate, no
|
|
355
|
+
record and no refusal. The test runs once, at load: a session that turns Dispatch on afterwards has
|
|
356
|
+
no gate until it is started again.
|
|
357
|
+
|
|
358
|
+
**The switch.** In a session with Dispatch, AskGate runs unless the session's own envoy.json turns
|
|
359
|
+
it off. Write this top-level section beside `dispatch`:
|
|
360
|
+
|
|
361
|
+
```json
|
|
362
|
+
{ "askgate": { "enabled": false } }
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
No section, or `enabled: true`, keeps it on. A checkout's `.envoy/envoy.json` cannot set it, and a
|
|
366
|
+
checkout's `dispatch.enabled: false` does not turn it off. A section that does not parse keeps
|
|
367
|
+
AskGate on, and the start notice names the file.
|
|
368
|
+
|
|
369
|
+
**The modes.** A model's revise verdict and the CLI's marker checks have separate defaults. A revise
|
|
370
|
+
verdict blocks by default: the write does not post. `OMP_ASKGATE=warn`, or a session whose latest
|
|
371
|
+
`experiments` entry turns its `askgate_block` arm off, lets the write post with the reason. The
|
|
372
|
+
CLI's checks warn by default: a gated write with no matching marker, a file changed after the
|
|
373
|
+
review, and a file missing when the gate ran each post with a warning and an `unmarked` or
|
|
374
|
+
`unreadable` entry that the report counts. They refuse only when the session chose block
|
|
375
|
+
explicitly: `OMP_ASKGATE=block`, or, with no such variable, an `experiments` entry whose arm is on.
|
|
376
|
+
AskGate ignores any other value of `OMP_ASKGATE`, `off` included, and the first review shows one
|
|
377
|
+
notice that names `askgate.enabled` as the switch. The gate writes the checks' mode into the
|
|
378
|
+
session's own record (not a process-wide file, so a process that binds two sessions keeps each
|
|
379
|
+
one's mode, and a switch never changes another session's) at each main-agent `bash` or `eval`
|
|
380
|
+
call, where the CLI reads it, and a record with no mode is warn. pi-envoy also writes
|
|
381
|
+
`OMP_ASKGATE=block` into the record at the bind, so a session that chose block that way stays at
|
|
382
|
+
block even when its gate does not load. A later bind of a session id that recorded block (a switch
|
|
383
|
+
back to it, or a branch or host move that keeps the id) keeps block, so its mode never goes back to
|
|
384
|
+
warn before the gate's next call. An `experiments` arm alone does not reach the record at the
|
|
385
|
+
bind: only the loaded gate reads the arm, so a session that chose block through the arm alone has
|
|
386
|
+
no mode on disk until the gate's first main-agent `bash` or `eval` call, and none at all when the
|
|
387
|
+
gate does not load — a write outside the literal form there posts with a warning. **An operator
|
|
388
|
+
who selects block through the arm should also set `OMP_ASKGATE=block` for a hard guarantee**,
|
|
389
|
+
which holds from the session's start and through a failed load. Two other refusals follow neither
|
|
390
|
+
mode: no model role, and a gate that did not load, which refuses each literal call it would review
|
|
391
|
+
in both modes, since neither can review anything.
|
|
392
|
+
|
|
393
|
+
**The model.** The gate asks the session's `askgate` model role (`modelRoles.askgate`). When that
|
|
394
|
+
role is not set, it asks the `default` role. A model that answers with an error passes the request
|
|
395
|
+
to the next model of that role's `retry.fallbackChains` chain, on the same provider. When neither
|
|
396
|
+
role resolves, the gate refuses the write in both modes and names the two roles. A session whose
|
|
397
|
+
main model is on another provider than the gate's model is not reviewed: its transcript stays on
|
|
398
|
+
that provider.
|
|
399
|
+
|
|
400
|
+
**When a write posts unreviewed.** Each of these lets the write out, records an `advisor-gate`
|
|
401
|
+
entry with its outcome, and hands the agent a note that says the write went out unreviewed and
|
|
402
|
+
why. The note reaches a headless session too:
|
|
403
|
+
|
|
404
|
+
| Outcome | What happened |
|
|
405
|
+
| --- | --- |
|
|
406
|
+
| `timeout` | the review did not answer within its deadline |
|
|
407
|
+
| `error` | the review failed: a model error, a handler exception, or a dry run that failed |
|
|
408
|
+
| `no-verdict` | the model answered with no verdict the gate could read |
|
|
409
|
+
| `halted` | three calls in a row reached no verdict, and the gate is paused for the session |
|
|
410
|
+
| `skipped` | the session's main model is on another provider than the gate's |
|
|
411
|
+
| `rebuttal` | the agent sent `--advisor-rebuttal <line>`, which is recorded and removed |
|
|
412
|
+
| `breaker` | a third attempt on one target after two revise verdicts |
|
|
413
|
+
| `unreadable` (warn mode) | a file the literal call names was missing or not a regular file when the gate ran |
|
|
414
|
+
| `abandoned` (warn mode) | the call or the run ended before the review answered |
|
|
415
|
+
| `shutdown` (warn mode) | the session shut down before the review answered |
|
|
416
|
+
| `unmarked` (warn mode) | the CLI found no marker for a gated write sent in another form |
|
|
417
|
+
|
|
418
|
+
Where the mode that applies is `block` (the verdict's for `abandoned` and `shutdown`, the checks'
|
|
419
|
+
for `unreadable` and `unmarked`), those outcomes refuse the call instead. Only
|
|
420
|
+
`askgate.enabled: false`, and a session with no Dispatch, are silent. Each outcome after a failure
|
|
421
|
+
runs the agent's own command as written: a gate that fails breaks no valid write.
|
|
422
|
+
|
|
423
|
+
**The time limit.** `OMP_ASKGATE_TIMEOUT_MS` sets the review's time limit. The default is 90 s. The
|
|
424
|
+
gate holds the limit 5 s under `extensionHandlers.toolCallTimeoutMs`, the host's limit for one
|
|
425
|
+
`tool_call` handler. That key is 30 s by default, so the limit is then 25 s. A review of a long
|
|
426
|
+
session often takes longer than 25 s, and a review that times out lets the write post. Three
|
|
427
|
+
timeouts in a row stop the gate for the rest of the session. Set the key to 120000 or more in the
|
|
428
|
+
session's settings, for example in `~/.omp/agent/config.yml` or an overlay in `PI_CONFIG_FILES`:
|
|
429
|
+
|
|
430
|
+
```yaml
|
|
431
|
+
extensionHandlers:
|
|
432
|
+
toolCallTimeoutMs: 120000
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
When the limit is under 30 s, the gate logs one warning at start that names the key, the host's
|
|
436
|
+
limit and the review's limit. It still reviews each write.
|
|
437
|
+
|
|
438
|
+
`OMP_ASKGATE_DUMP` names a file that gets each review's two prompts. Every gated call writes one
|
|
439
|
+
`advisor-gate` entry into the session's transcript, and `scripts/askgate-report.ts` reports over
|
|
440
|
+
those entries: what the gate sent back and what the reviews cost, a count for each outcome, and
|
|
441
|
+
every session that had a write the gate did not review, with its counts. The report counts a
|
|
442
|
+
write as **sent back** when the gate did not pass it as sent: every entry whose decision is
|
|
443
|
+
`revise` — a revise verdict, `no-model-role`, and in block mode `abandoned`, `shutdown` and
|
|
444
|
+
`unmarked` — and every `unreadable`, `unmarked` or `load-failed` entry, whatever its mode, counted
|
|
445
|
+
over every gated call, since some of them never reach a review; as a **refusal** when the write did
|
|
446
|
+
not post (one sent back in block mode, and `no-model-role` and `load-failed`, which refuse in warn
|
|
447
|
+
mode too); and as **unreviewed** when it posted with no review behind it, which is every `allow`
|
|
448
|
+
whose outcome is no verdict (the table above, a rebuttal, a breaker trip and warn mode's
|
|
449
|
+
`abandoned` and `shutdown` included).
|
|
450
|
+
|
|
451
|
+
**What AskGate is not.** AskGate reviews the writes of a cooperating agent, so that a write that
|
|
452
|
+
breaks its rules comes back with the reason before it posts. It is no sandbox. A process that
|
|
453
|
+
runs as the same user as the session defeats it: it can set `askgate.enabled` to false in its own
|
|
454
|
+
envoy.json, or point the session at another envoy.json with `OMP_PROFILE`, `PI_CODING_AGENT_DIR`,
|
|
455
|
+
`ENVOY_CONFIG_FILE`, `XDG_CONFIG_HOME` or `HOME` in the launching shell.
|
|
456
|
+
|
|
457
|
+
The CLI's check holds only for the CLI. It does not cover a direct HTTP request to Dispatch with
|
|
458
|
+
the session's token, an older or a different `dispatch` binary, or a same-user process that
|
|
459
|
+
removes the record or a marker file, sets `DISPATCH_STATE_DIR` or `DISPATCH_SESSION_ID` itself to
|
|
460
|
+
act as another state directory or session id, or otherwise goes around the CLI. claude-envoy has
|
|
461
|
+
no Dispatch write tool over MCP: Claude Code writes through the same CLI
|
|
462
|
+
under host `claude`, where AskGate keeps no record, so nothing there asks for a marker. Use the
|
|
463
|
+
gate for the writes of an agent that wants the review, and not as a boundary against a program
|
|
464
|
+
that wants around it.
|