@sjawhar/pi-envoy 13.7.0 → 13.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/README.md +261 -35
- package/dist/dispatch.js +722 -41
- package/dist/envoy.js +2542 -352
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -84,9 +84,14 @@ items that do not fit are left out, and its last line says how many and that `di
|
|
|
84
84
|
prints them all. It is read on every request and waits at most 800 ms for Dispatch. Past that,
|
|
85
85
|
or when the read fails, the request carries the last list read, with the time it was read and why
|
|
86
86
|
this read failed, or, when no list read has an item from the last 72 hours, one line saying the
|
|
87
|
-
list could not be read and why. A Dispatch
|
|
88
|
-
|
|
89
|
-
|
|
87
|
+
list could not be read and why. A Dispatch build older than the answers route answers it with its
|
|
88
|
+
own `404 NOT_FOUND` "no route for …". Against that Dispatch a request carries no such line, since
|
|
89
|
+
`dispatch answers` cannot read it either; a list read before from it is still carried, its
|
|
90
|
+
left-out line naming no command; the log says once per session that the Dispatch has no answers
|
|
91
|
+
route; and that Dispatch is not asked again for 5 minutes. Any other answer, a proxy's 404 page or
|
|
92
|
+
a 200 that is no answers list included, is a failed read. The list sits at the tail so that a
|
|
93
|
+
change in it costs only its own tokens: the cached conversation before it is sent byte for byte as
|
|
94
|
+
before.
|
|
90
95
|
|
|
91
96
|
Oh My Pi also builds requests that are not turns of the conversation from it; those carry the
|
|
92
97
|
skill but no list, and wait on no read: a side turn (a Dispatch BTW, the stop-time self-check,
|
|
@@ -253,9 +258,11 @@ document, not for coordination between roles.
|
|
|
253
258
|
|
|
254
259
|
## AskGate
|
|
255
260
|
|
|
256
|
-
AskGate reviews each Dispatch write of a session's main agent before the write posts.
|
|
257
|
-
call judges the write against the rules in `extensions/askgate/rules.md` and
|
|
258
|
-
`revise`. A `revise` answer carries the reason and the fix.
|
|
261
|
+
AskGate reviews each Dispatch write of a session's main agent before the write posts. The charter
|
|
262
|
+
check, one model call, judges the write against the rules in `extensions/askgate/rules.md` and
|
|
263
|
+
answers `allow` or `revise`. A `revise` answer carries the reason and the fix. A call that opens a
|
|
264
|
+
new ask for a person also gets the rules check (below), a second model call beside it. The gate
|
|
265
|
+
reviews these calls:
|
|
259
266
|
|
|
260
267
|
- `dispatch ask`, `dispatch message`, `dispatch edit-ask`, `dispatch comment`, `dispatch doc-edit`
|
|
261
268
|
and `dispatch request-approval`
|
|
@@ -299,7 +306,7 @@ in the next.
|
|
|
299
306
|
**The form the gate reads.** One `dispatch` call, alone in the bash call:
|
|
300
307
|
|
|
301
308
|
```
|
|
302
|
-
[cd <literal path> && ] dispatch <subcommand> <literal words…> [2>&1] [<<'DELIM' … DELIM] [| head|tail [-n N]]
|
|
309
|
+
[cd <literal path> && ] dispatch <subcommand> <literal words…> [2>&1] [<<'DELIM' … DELIM] [| head|tail [-n N]] [# --advisor-rebuttal '<line>']
|
|
303
310
|
```
|
|
304
311
|
|
|
305
312
|
- The program is `dispatch` by name, or a literal path that ends in it.
|
|
@@ -313,8 +320,13 @@ in the next.
|
|
|
313
320
|
after the `2>&1`. Its body is on the lines after the line that opens it.
|
|
314
321
|
- One trailing pipe stage may read its output: `head` or `tail`, alone or with `-n N`, `-nN` or
|
|
315
322
|
`-N`. The dry run leaves it out.
|
|
323
|
+
- One shell comment may stand where the command's line ends — after its last word and after every
|
|
324
|
+
`2>&1`, here-document opener and `head` or `tail` stage, which is where bash reads one — and
|
|
325
|
+
only when its words are override flags alone (`# --advisor-rebuttal '<line>'`, the form the gate
|
|
326
|
+
hands a rebutted command back in). It is read as those overrides, and no part of what runs:
|
|
327
|
+
`commandArgv` never holds it, so the marker binds the words bash hands the CLI.
|
|
316
328
|
- Nothing else is in the call: no second command, no other pipe, no `;`, `&&`, `||` or `&`, no
|
|
317
|
-
assignment, no other redirect and no comment.
|
|
329
|
+
assignment, no other redirect and no other comment.
|
|
318
330
|
|
|
319
331
|
**Everything else runs, and the `dispatch` command enforces the review.** The gate reads no other
|
|
320
332
|
form and refuses none: a call outside the literal grammar runs as written. What holds it back is
|
|
@@ -360,8 +372,18 @@ gated write only when it consumes one, so a write sent any other way is refused
|
|
|
360
372
|
no marker, the gate appends an `AskGate note:` to that result. It names the first cause it found
|
|
361
373
|
in the call, with the call's own text (an expansion in a value, a double-quoted value over lines
|
|
362
374
|
with an expansion in it, a program that runs the write such as `xargs` or `timeout`, a pipe, a
|
|
363
|
-
second command, an assignment, a redirect
|
|
364
|
-
form.
|
|
375
|
+
second command, an assignment, a redirect, a comment that is no override), and the change that
|
|
376
|
+
puts the write in the literal form. For a comment it says that AskGate reads a `#` only where
|
|
377
|
+
the command's line ends and only when its words are override flags alone. The note is
|
|
378
|
+
help only: the gate refuses nothing for it.
|
|
379
|
+
- **The unmarked write that carries an ask.** The `unmarked` entry reaches only this machine's
|
|
380
|
+
disk. Where such a write carries at least one ask for a person, the CLI counts those asks from
|
|
381
|
+
the write's own text (`newAsks` in `@legion/envoy-client/askgate-new-asks`) and writes the count
|
|
382
|
+
into the session's ledger as `asksCarried`, and pi-envoy publishes one decision record for it on
|
|
383
|
+
Dispatch (below), with the tool, the mode and that count and no ask text. The count is of the
|
|
384
|
+
asks the write carries, so a re-upload of ask blocks the stored version already holds counts
|
|
385
|
+
them as carried: in `warn` mode the write has already posted when the ledger is read, so a read
|
|
386
|
+
of the stored version would see the new text and count nothing.
|
|
365
387
|
|
|
366
388
|
The gated writes are the same list for the gate and the CLI (`gatedWrite` in
|
|
367
389
|
`@legion/envoy-client/askgate-marker`): the six commands above, an `issue` with a spec and an
|
|
@@ -416,12 +438,75 @@ bind: only the loaded gate reads the arm, so a session that chose block through
|
|
|
416
438
|
no mode on disk until the gate's first main-agent `bash` or `eval` call, and none at all when the
|
|
417
439
|
gate does not load — a write outside the literal form there posts with a warning. **An operator
|
|
418
440
|
who selects block through the arm should also set `OMP_ASKGATE=block` for a hard guarantee**,
|
|
419
|
-
which holds from the session's start and through a failed load.
|
|
420
|
-
mode:
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
441
|
+
which holds from the session's start and through a failed load. Three refusals follow neither
|
|
442
|
+
mode: a match of the rules check (below), which refuses the write in both modes; no model role;
|
|
443
|
+
and a gate that did not load, the last two refusing each literal call they would review in both
|
|
444
|
+
modes, since neither can review anything.
|
|
445
|
+
|
|
446
|
+
**The rules check.** A call that opens a new ask for the person gets a second model call, beside
|
|
447
|
+
the charter call and on the same chain, deadline and transcript. That call knows two rules
|
|
448
|
+
(`extensions/askgate/rule-check.md`) and judges only the new asks:
|
|
449
|
+
|
|
450
|
+
- No change: the ask's own recommendation is to change nothing, such as to keep things as they
|
|
451
|
+
are, to take no action or to keep the current design.
|
|
452
|
+
- Untried access: the ask asks the person to do a step with their own hands (run a command,
|
|
453
|
+
change a setting, grant access, sign in), or says that only the person can do the step. The
|
|
454
|
+
rule matches only when neither the ask nor the transcript shows that the agent tried the step
|
|
455
|
+
with the access it has or can request. A step that needs the person's security key, a sign-in
|
|
456
|
+
to their own account in a browser, a payment or their own decision does not match. An ask that
|
|
457
|
+
also asks the person to choose between options with different outcomes does not match.
|
|
458
|
+
|
|
459
|
+
A new ask is a `dispatch ask`, an ask block that a `dispatch doc-edit` inserts, a block that it
|
|
460
|
+
retypes into an ask, an ask block in a `dispatch issue` spec, or an ask block in a markdown
|
|
461
|
+
upload whose `#id` the document does not already hold. When that document cannot be read, an
|
|
462
|
+
upload's ask blocks that carry an `#id` are left out — a stored version may hold any of them —
|
|
463
|
+
and only the blocks with no id are judged, so a re-upload of an unchanged document is never
|
|
464
|
+
refused for an ask block it already held.
|
|
465
|
+
|
|
466
|
+
The rules check runs only on a call the gate reads, which is the literal form above. A call in
|
|
467
|
+
any other form reaches no gate at all: the CLI refuses it in `block` mode and posts it with a
|
|
468
|
+
warning in `warn` mode, and the rules check never sees it. Where such a write carries an ask, the
|
|
469
|
+
Dispatch record below counts it.
|
|
470
|
+
|
|
471
|
+
A match refuses the call in `warn` mode and in `block` mode, so no part of the call posts and no
|
|
472
|
+
marker is minted for it. The refusal names the matching asks, each with its rule and the words
|
|
473
|
+
that match. It says what to do instead and how to send the call anyway. The agent sends the call
|
|
474
|
+
anyway in one of three ways:
|
|
475
|
+
|
|
476
|
+
- `--advisor-rebuttal '<line>'` on a `dispatch` command.
|
|
477
|
+
- `"advisor_rebuttal": "<line>"` in a device's JSON.
|
|
478
|
+
- The third attempt at the same thing on the same target: after the gate refuses one thing twice
|
|
479
|
+
on one target, it sends the third call that holds it without review. A thing is each new ask a
|
|
480
|
+
call opens, or the call as a whole when it opens none. A charter refusal counts on every thing
|
|
481
|
+
of the call, and a rules refusal counts on the asks it refused. Only a refusal counts: in `warn`
|
|
482
|
+
mode a charter `revise` sends the call, so it never moves the breaker, while a match of the
|
|
483
|
+
rules check refuses the call in either mode and always does. A call that opens an ask refused
|
|
484
|
+
once, or never, on that target is reviewed like any other, however often the gate refused other
|
|
485
|
+
asks there, and a call that opens no ask counts its own refusals, whatever asks were refused
|
|
486
|
+
there before it. An allow, a rebuttal or the third attempt starts every count on the target
|
|
487
|
+
again.
|
|
488
|
+
|
|
489
|
+
A rebuttal sends the call with no review by either check, and the entry records the line. The
|
|
490
|
+
CLI takes no such flag, so the gate moves it into a shell comment where the command's line ends,
|
|
491
|
+
after everything that runs, where the agent's record of its call still shows it and dispatch never
|
|
492
|
+
sees it; that command sent again is read as the same rebuttal and comes back unchanged. The
|
|
493
|
+
comment stands at the end of the command's line because that is the one place bash reads it as a
|
|
494
|
+
comment at all: every word of it is quoted, which keeps the comment's own quotes paired, but
|
|
495
|
+
nowhere else would that quoting hold — written where a single-quoted value is still open, the
|
|
496
|
+
quotes would pair around the agent's line and leave it outside them. The gate reads the commented
|
|
497
|
+
command back as the same call before it hands it over: an override no
|
|
498
|
+
word of the grammar can carry — a line holding both a `'` and a `$`, or a newline — is removed
|
|
499
|
+
instead, and the acknowledgement says so. A device takes no such field, so the gate removes it
|
|
500
|
+
before the call runs and says so. Either way the acknowledgement
|
|
501
|
+
quotes the override exactly as the agent sent it. A rules call that ends in an error, a timeout or
|
|
502
|
+
an answer that does not parse refuses nothing: the charter check decides. The third such rules
|
|
503
|
+
call in a row writes one warning, saying that the new asks of those three calls went unchecked and
|
|
504
|
+
that the check still runs on each new ask, to the host's plain log, shows it as a notice in a
|
|
505
|
+
session with a UI, and adds it to that call's own result. It is not one of the notices a session
|
|
506
|
+
shows at its start.
|
|
507
|
+
|
|
508
|
+
**The model.** Both checks ask the session's `askgate` model role (`modelRoles.askgate`). When that
|
|
509
|
+
role is not set, they ask the `default` role. A model that answers with an error passes the request
|
|
425
510
|
to the next model of that role's `retry.fallbackChains` chain, on the same provider. When neither
|
|
426
511
|
role resolves, the gate refuses the write in both modes and names the two roles. A session whose
|
|
427
512
|
main model is on another provider than the gate's model is not reviewed: its transcript stays on
|
|
@@ -438,8 +523,8 @@ why. The note reaches a headless session too:
|
|
|
438
523
|
| `no-verdict` | the model answered with no verdict the gate could read |
|
|
439
524
|
| `halted` | three calls in a row reached no verdict, and the gate is paused for the session |
|
|
440
525
|
| `skipped` | the session's main model is on another provider than the gate's |
|
|
441
|
-
| `rebuttal` | the agent sent `--advisor-rebuttal <line>`, which is recorded and removed |
|
|
442
|
-
| `breaker` |
|
|
526
|
+
| `rebuttal` | the agent sent `--advisor-rebuttal <line>`, which is recorded and kept only as a shell comment, or `"advisor_rebuttal"`, which is recorded and removed |
|
|
527
|
+
| `breaker` | the third attempt at one thing on one target, after the gate refused it twice there |
|
|
443
528
|
| `unreadable` (warn mode) | a file the literal call names was missing or not a regular file when the gate ran |
|
|
444
529
|
| `abandoned` (warn mode) | the call or the run ended before the review answered |
|
|
445
530
|
| `shutdown` (warn mode) | the session shut down before the review answered |
|
|
@@ -451,11 +536,14 @@ for `unreadable` and `unmarked`), those outcomes refuse the call instead. Only
|
|
|
451
536
|
runs the agent's own command as written: a gate that fails breaks no valid write.
|
|
452
537
|
|
|
453
538
|
**The time limit.** `OMP_ASKGATE_TIMEOUT_MS` sets the review's time limit. The default is 90 s. The
|
|
454
|
-
gate holds the limit 5
|
|
455
|
-
`tool_call` handler
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
539
|
+
gate holds the limit 5,000 ms under `extensionHandlers.toolCallTimeoutMs`, the host's limit for
|
|
540
|
+
one `tool_call` handler: the room its handler still needs once the limit passes, for the aborted
|
|
541
|
+
call's usage report and for the entry. The Dispatch record below is no part of it, since it runs
|
|
542
|
+
after the handler has returned. That key is 30 s by
|
|
543
|
+
default, so the limit is then 25,000 ms. A review of a long session can take longer than 25 s,
|
|
544
|
+
and a review that times out lets the write post. Three timeouts in a row stop the gate for the
|
|
545
|
+
rest of the session. Set the key to 120000 or more in the session's settings, for example in
|
|
546
|
+
`~/.omp/agent/config.yml` or an overlay in `PI_CONFIG_FILES`:
|
|
459
547
|
|
|
460
548
|
```yaml
|
|
461
549
|
extensionHandlers:
|
|
@@ -463,20 +551,158 @@ extensionHandlers:
|
|
|
463
551
|
```
|
|
464
552
|
|
|
465
553
|
When the limit is under 30 s, the gate logs one warning at start that names the key, the host's
|
|
466
|
-
limit and the review's limit. It still reviews each write.
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
554
|
+
limit and the review's limit. It still reviews each write. The key must be at least 15,000 ms,
|
|
555
|
+
since the gate does not bind on a limit that leaves under 10 s for a verdict. A session set under
|
|
556
|
+
15,000 ms gets a gate that does not load, and a gate that did not load refuses every Dispatch
|
|
557
|
+
write it would have reviewed.
|
|
558
|
+
|
|
559
|
+
`OMP_ASKGATE_DUMP` names a file that gets the two prompts of each model call.
|
|
560
|
+
|
|
561
|
+
**The record.** Every gated call writes one `advisor-gate` entry into the session's transcript.
|
|
562
|
+
Every entry whose arguments the gate read carries `target`, the call's target in readable form:
|
|
563
|
+
the tool name, then each of `issue`, `ask`, `artifact`, `project` and `in_reply_to` that the input
|
|
564
|
+
carries, as `dispatch_ask issue=ACME-1`. An `unreadable` entry, and the `unmarked` entry pi-envoy
|
|
565
|
+
writes from the CLI's own ledger line, carry none: neither has the arguments to name one. The
|
|
566
|
+
third attempt (`outcome: "breaker"`) counts the refusals of
|
|
567
|
+
one thing on one such target, and `revisesForKey` counts every `revise` on it, the `warn` ones
|
|
568
|
+
included, since its counts last started again. A call that opens a new ask adds the fields of the
|
|
569
|
+
rules check:
|
|
570
|
+
|
|
571
|
+
- `rule`: `no_change` or `untried_access`, the rule that the first matching ask broke. The gate
|
|
572
|
+
sets it exactly when the rules check refused the call.
|
|
573
|
+
- `ruleAsk`: the number of that ask in the rules request, from 1.
|
|
574
|
+
- `ruleQuote`: the words of that ask that the rules call quoted.
|
|
575
|
+
- `ruleOutcome`: how the rules check ended: `match`, `none`, `error`, `timeout`, `no-verdict`,
|
|
576
|
+
`abandoned`, `shutdown` or `unjudged`. The gate sets it on each gated call that opens a new ask
|
|
577
|
+
and reached the model call. `unjudged` is the one with no model call: an upload whose stored
|
|
578
|
+
version the gate could not read and whose every ask block carries an `#id`, so it judged none
|
|
579
|
+
of the call's asks. The call is not refused for it; the charter check decides alone.
|
|
580
|
+
- `ruleModel`: the `provider/id` that answered the rules call.
|
|
581
|
+
- `ruleLatencyMs`: the time of the rules check, its document read included. `charterLatencyMs` is
|
|
582
|
+
the charter check's own time on the same clock; the two calls run side by side, so each says
|
|
583
|
+
what it cost of the entry's whole `latencyMs`.
|
|
584
|
+
- `ruleTextMissing`: `true` when the gate could not read the text of an ask and judged the ask
|
|
585
|
+
without it. A failed read of an upload's stored version never sets it: no ask of an upload
|
|
586
|
+
loses its own text.
|
|
587
|
+
- `ruleError`: the error text for `error` (the provider's, or the check's own when it fails before
|
|
588
|
+
a model answers), `timeout` for a timeout, and `no-verdict` for an answer that does not parse.
|
|
589
|
+
- `ruleAsksCut`: how many asks the request cut. The request lists every new ask, and aims to keep
|
|
590
|
+
the list within 32 KiB: each ask's text gets an equal share of it, at most 8 KiB, and an ask cut
|
|
591
|
+
to its share keeps its start and its end, where the rules read. The gate never leaves an ask out,
|
|
592
|
+
or cuts one below its start and its end, to stay within that bound: a write of very many ask
|
|
593
|
+
blocks, over a hundred, makes a longer request. An ask's `#id` is cut to 128 bytes.
|
|
594
|
+
- `ruleAsksPartial`: `true` when the call was judged on part of its asks, or on none of them
|
|
595
|
+
(`ruleOutcome: "unjudged"`): the gate could not read the document an upload replaces, so the ask
|
|
596
|
+
blocks carrying an `#id` were left out of the check.
|
|
597
|
+
- `mintSkipped`: `call-ended`, on a call whose decision let the write out and whose own tool ended
|
|
598
|
+
while the gate still held it. No marker was minted, since no command of that call can run.
|
|
599
|
+
|
|
600
|
+
`decision` is `revise` on a rules refusal in `warn` mode too. The gate refused a call exactly when
|
|
601
|
+
`decision` is `revise` and one of these is true: `verdictMode` is `block`, `outcome` is
|
|
602
|
+
`no-model-role` or `load-failed`, or `rule` is set. An `unreadable` or `unmarked` entry is a
|
|
603
|
+
refusal in `block` mode only, where its `decision` is `revise`; in `warn` mode its `decision` is
|
|
604
|
+
`allow`, and the write went out with the note that it was unreviewed. To find the refusals that
|
|
605
|
+
the agent overrode, join each rules refusal to the next entry with the same `target`. The agent
|
|
606
|
+
overrode the refusal when that entry's `outcome` is `rebuttal` or `breaker`.
|
|
607
|
+
|
|
608
|
+
`scripts/askgate-report.ts` reports over those entries: what the gate sent back and what the
|
|
609
|
+
reviews cost, a count for each outcome, every session that had a write the gate did not review,
|
|
610
|
+
with its counts, the markers it skipped, the outcomes and errors of the rules check, and the rules
|
|
611
|
+
refusals that the agent overrode. The report counts a write as **sent back** when the gate did not
|
|
612
|
+
pass it as sent: every entry whose decision is `revise` — a revise verdict, a rules refusal,
|
|
613
|
+
`no-model-role`, and in block mode `abandoned`, `shutdown` and `unmarked` — and every
|
|
614
|
+
`unreadable`, `unmarked` or `load-failed` entry, whatever its mode, counted over every gated call,
|
|
615
|
+
since some of them never reach a review; as a **refusal** when the write did not post (one sent
|
|
616
|
+
back in block mode, and `no-model-role`, `load-failed` and a rules refusal, which refuse in warn
|
|
477
617
|
mode too); and as **unreviewed** when it posted with no review behind it, which is every `allow`
|
|
478
618
|
whose outcome is no verdict (the table above, a rebuttal, a breaker trip and warn mode's
|
|
479
|
-
`abandoned` and `shutdown` included).
|
|
619
|
+
`unreadable`, `unmarked`, `abandoned` and `shutdown` included).
|
|
620
|
+
|
|
621
|
+
**The Dispatch record.** The entry above reaches only the machine the session ran on. A session
|
|
622
|
+
that counts the rule decisions over a fortnight — a standing session holding a Dispatch token and
|
|
623
|
+
nothing else — reads them from Dispatch instead: every gated call whose rules check ran (every
|
|
624
|
+
entry with a `ruleOutcome`), every call the agent sent anyway (a rebuttal or the breaker, whose
|
|
625
|
+
record has `ruleOutcome: null` and the refusal's own `target`), and every write that reached the
|
|
626
|
+
CLI outside the form the gate reads and carried an ask for a person (`outcome: "unmarked"`, with
|
|
627
|
+
`asksCarried` above zero) are published to a Dispatch project document of the session's own,
|
|
628
|
+
`askgate-decisions-<session id>.md`.
|
|
629
|
+
|
|
630
|
+
- **What it carries.** The time, the session, `id` (the gated call's tool call id, and for an
|
|
631
|
+
unmarked write the CLI ledger line's place in its tool call, so a reader counts one decision
|
|
632
|
+
once), `source` (`pod` for a Legion role's session, which `LEGION_ISSUE` names, and `machine`
|
|
633
|
+
for every other), the project, `tool`, `target`, `rule`, `ruleOutcome`, `ruleError`,
|
|
634
|
+
`ruleTextMissing`, `ruleAsksCut`, `ruleAsksPartial`, `decision`, `outcome`, `verdictMode`,
|
|
635
|
+
`asksCarried`, `ruleLatencyMs`, `charterLatencyMs` and the plugin's version. **No ask text and
|
|
636
|
+
no quote leaves the session**, so nothing a person wrote travels with the counts.
|
|
637
|
+
- **Which project.** `OMP_ASKGATE_RECORD_PROJECT`, else `LEGION_PROJECT` (a Legion pod has no
|
|
638
|
+
envoy.json, so its environment is the only setting it can carry), else no record at all and no
|
|
639
|
+
Dispatch call.
|
|
640
|
+
- **When.** Once the call has been answered: the gate appends the call's `advisor-gate` entry,
|
|
641
|
+
returns, and then hands the record to the session's recorder, so no review is ever cut short to
|
|
642
|
+
pay for it. It never changes the decision. The write runs until Dispatch has answered it or the
|
|
643
|
+
session's shutdown cuts it — the client asks again under the call's own `Idempotency-Key`, and
|
|
644
|
+
nothing retries it from outside — so a Dispatch that is slow under load is waited
|
|
645
|
+
out rather than given up. A record that fails or that the shutdown cuts writes one line to the
|
|
646
|
+
host's log and appends one `advisor-gate-record` entry, carrying `toolCallId`, `tool`,
|
|
647
|
+
`recordError` and, for an unmarked write, the record's own `recordId`; the decision's own entry
|
|
648
|
+
stands as written. Once the session is shutting down, the one `session_shutdown` handler the
|
|
649
|
+
gate binds gives the records 1.25 s from that moment and then cuts them, whether or not the
|
|
650
|
+
gate loaded, and the gate's own handler waits for what is still pending inside the 1.5 s it
|
|
651
|
+
holds shutdown for, so a record still lands, and the entry of one that could not, before the
|
|
652
|
+
session is sealed; a record cut that way says the shutdown cut it. An unmarked write's record is
|
|
653
|
+
started from the `tool_result` the CLI's line reached, after that write's `advisor-gate` entry
|
|
654
|
+
is appended and awaited by nothing of the tool result, which returns while the record is still
|
|
655
|
+
in flight: the records of a session are written one at a time and each has the client's own
|
|
656
|
+
deadline, so a Dispatch that does not answer would otherwise stall every such write. It goes
|
|
657
|
+
through the one recorder the gate's own records use.
|
|
658
|
+
- **One document per session, written once and appended to.** The document's create carries a
|
|
659
|
+
header paragraph and no record; every record, the session's first included, is a fenced JSON
|
|
660
|
+
line appended through `docEdit`. That rule is what keeps a record safe, because an upload of a
|
|
661
|
+
name Dispatch already holds stores a new version of that document and the reader reads the
|
|
662
|
+
latest version alone, so a second upload would erase every record appended since the first. A
|
|
663
|
+
process holding no id for the session — a fresh process serving it, or one whose create was cut
|
|
664
|
+
— reads the document by its name, one request of a few bytes, and appends to that; it creates
|
|
665
|
+
one only where that read answers 404. The create carries an `Idempotency-Key` of the document's
|
|
666
|
+
own, `askgate-doc.` and the sha256 of the project and the name, and a body fixed for the
|
|
667
|
+
session — the header alone, with no record, no time and no plugin version in it — so every
|
|
668
|
+
attempt of it, in this process or another, is one intent Dispatch runs once: it replays a key
|
|
669
|
+
that finished, answers `409 KEY_IN_FLIGHT` while the first run lives, `409 KEY_COMMITTED` where
|
|
670
|
+
that run landed and lost its answer, and `422 KEY_REUSED` for a different body, and the last two
|
|
671
|
+
send the recorder back to the read and then to the append. Each append carries a key of its own,
|
|
672
|
+
the sha256 of the session and the record's id, so an append Dispatch ran late is replayed to its
|
|
673
|
+
next attempt rather than written twice; the same record sent again with another time in its body
|
|
674
|
+
gets `422 KEY_REUSED`, is not written, and is counted as not confirmed. Keys
|
|
675
|
+
belong to the login that sent them, and every Legion pod writes under the shared agent token,
|
|
676
|
+
which is one login for all of them (`requestKeyLogin`,
|
|
677
|
+
`packages/envoy/internal/dispatch/api/request_keys.go`); Dispatch keeps a key 24 h
|
|
678
|
+
(`IdempotencyKeyTTL`), well past the 10 minutes a create's run can hold it
|
|
679
|
+
(`keyedHandlerLimit`). The records of one session are written one at a time, each sent once the
|
|
680
|
+
one before it has settled, and each carries the time the gate made it, which is what the reader
|
|
681
|
+
counts and sorts by: a write given up on this side may still be running on Dispatch's while the
|
|
682
|
+
next is sent, so the order they land in is not the order they were made.
|
|
683
|
+
- **What is lost, and what is counted.** A session killed between a decision and its write loses
|
|
684
|
+
that one record, and a session that never reached a gated call writes no document. A record
|
|
685
|
+
that fails, or that the shutdown cuts, is unconfirmed too — and one given up that way may have
|
|
686
|
+
landed all the same, so a record the session could not confirm can still be in the document,
|
|
687
|
+
where the reader counts it once by its `id` and counts the second copy as a duplicate. What no
|
|
688
|
+
longer happens: a create given up here and committed on Dispatch after later records were
|
|
689
|
+
written cannot replace them, since every create of that document is the one keyed create, and
|
|
690
|
+
two processes writing one session's first record at the same moment make that same one create
|
|
691
|
+
between them. What the
|
|
692
|
+
machine could not get Dispatch to confirm is counted on the machine's own side: `--sessions`
|
|
693
|
+
counts the entries carrying a `recordError` as **decision records not confirmed**, an upper
|
|
694
|
+
bound on what the day's `--dispatch-project` counts cannot hold.
|
|
695
|
+
|
|
696
|
+
`scripts/askgate-report.ts --dispatch-project <KEY> --since <RFC 3339> [--json]` reads those
|
|
697
|
+
documents and prints the day's refusals by rule, the refusals the agent overrode, the calls
|
|
698
|
+
judged on part of their asks and those that judged none, the unmarked writes by mode with the asks
|
|
699
|
+
they carried, and the rules-call error rate, each split by `source`, with the documents and lines
|
|
700
|
+
it could not read, and the records it read twice, counted beside them. An unmarked write is in no
|
|
701
|
+
rules-call count and in no override count: no check judged it. Its `asksCarried` counts every ask
|
|
702
|
+
and ask block the write carries, so a re-upload of blocks a stored version already holds counts
|
|
703
|
+
them as carried. The same script's `--sessions <dir>` mode still reports the entries on disk, the
|
|
704
|
+
decision records not confirmed among them. Each flag is given once: the
|
|
705
|
+
script refuses a flag given twice by name, rather than reading only its last value.
|
|
480
706
|
|
|
481
707
|
**What AskGate is not.** AskGate reviews the writes of a cooperating agent, so that a write that
|
|
482
708
|
breaks its rules comes back with the reason before it posts. It is no sandbox. A process that
|