pi-better-subagents 0.26.0 → 0.26.1
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/cleanup.ts +58 -2
- package/continuation.ts +58 -7
- package/docs/usage.md +76 -9
- package/finalization.ts +1 -1
- package/index.ts +595 -287
- package/output-payload.ts +40 -3
- package/package.json +1 -1
- package/registry.ts +215 -4
- package/shared-callback-batcher.ts +18 -1
- package/shared-failure-observations.ts +78 -24
- package/shared-log-utils.ts +277 -31
- package/stop.ts +60 -2
- package/timing.ts +45 -4
- package/tools.ts +29 -6
package/shared-log-utils.ts
CHANGED
|
@@ -135,7 +135,14 @@ export const OUTPUT_PAGE_DEFAULTS = {
|
|
|
135
135
|
|
|
136
136
|
export type OutputBudgetSurface = keyof typeof OUTPUT_BUDGET_BYTES;
|
|
137
137
|
|
|
138
|
-
|
|
138
|
+
/**
|
|
139
|
+
* Why a supplied cursor was not followed. `cursor-corrupt` means the payload
|
|
140
|
+
* itself failed its integrity check — a hand-copied character, not evidence
|
|
141
|
+
* that the source changed or that the cursor belongs to another scope (#617).
|
|
142
|
+
* A corrupt cursor only resumes from an offset a witness recomputed from the
|
|
143
|
+
* current source proves; otherwise the page restarts at byte 0.
|
|
144
|
+
*/
|
|
145
|
+
export type PageReset = "stale-cursor" | "source-replaced" | "compacted" | "cursor-corrupt";
|
|
139
146
|
export type EvidenceGapKind = "capture" | "retention" | "read";
|
|
140
147
|
export type StatusChange = "none" | "failure" | "content" | "reset";
|
|
141
148
|
export type EnvelopeSectionName =
|
|
@@ -191,6 +198,12 @@ export interface PageResult {
|
|
|
191
198
|
appendReady?: boolean;
|
|
192
199
|
/** Bytes of a trailing, still-incomplete UTF-8 sequence withheld until the writer completes it. */
|
|
193
200
|
pendingBytes?: number;
|
|
201
|
+
/**
|
|
202
|
+
* `backward` marks an end-anchored page: the text ends at the cursor's upper
|
|
203
|
+
* bound, `omittedBytes` counts earlier bytes not shown, and `nextCursor`
|
|
204
|
+
* continues toward the start of the file.
|
|
205
|
+
*/
|
|
206
|
+
direction?: "backward";
|
|
194
207
|
}
|
|
195
208
|
|
|
196
209
|
export interface FilePageRequest extends PageRequest {
|
|
@@ -205,6 +218,14 @@ export interface FilePageRequest extends PageRequest {
|
|
|
205
218
|
captureGaps?: Array<{ bytes: number; detail?: string }>;
|
|
206
219
|
/** Pin pagination to this many leading bytes; defaults to the size at first read. */
|
|
207
220
|
snapshotBytes?: number;
|
|
221
|
+
/**
|
|
222
|
+
* Start an uncursored read from the newest retained byte instead of byte 0
|
|
223
|
+
* (issue #618). The first page is end-anchored and `nextCursor` then pages
|
|
224
|
+
* toward the oldest byte; reaching the start hands back an append-ready
|
|
225
|
+
* cursor. A backward cursor keeps this direction on its own, so the request
|
|
226
|
+
* flag is only needed to start such a pager.
|
|
227
|
+
*/
|
|
228
|
+
direction?: "backward";
|
|
208
229
|
}
|
|
209
230
|
|
|
210
231
|
export interface VerbatimPage {
|
|
@@ -224,6 +245,8 @@ export interface VerbatimPage {
|
|
|
224
245
|
endByte?: number;
|
|
225
246
|
appendReady?: boolean;
|
|
226
247
|
pendingBytes?: number;
|
|
248
|
+
/** `backward` marks an end-anchored page whose `nextCursor` reads earlier bytes. */
|
|
249
|
+
direction?: "backward";
|
|
227
250
|
/** Where `nextCursor` is accepted when that is not the tool that returned it. */
|
|
228
251
|
via?: string;
|
|
229
252
|
}
|
|
@@ -286,10 +309,15 @@ interface CursorPayload {
|
|
|
286
309
|
i?: string;
|
|
287
310
|
h?: string;
|
|
288
311
|
hl?: number;
|
|
312
|
+
/** Position witness: the byte window before the offset (`k: "f"`), or the source snapshot (`k: "t"`). */
|
|
289
313
|
w?: string;
|
|
290
314
|
c?: string;
|
|
291
315
|
f?: string;
|
|
292
316
|
a?: 1;
|
|
317
|
+
/** End-anchored page: `o` is the page's upper bound and `nextCursor` reads earlier bytes. */
|
|
318
|
+
b?: 1;
|
|
319
|
+
/** Integrity tag over every other field; see `cursorIntegrityTag`. */
|
|
320
|
+
x?: string;
|
|
293
321
|
}
|
|
294
322
|
|
|
295
323
|
function positiveInt(value: unknown): number | undefined {
|
|
@@ -438,10 +466,44 @@ function resourceTag(resource: string): string {
|
|
|
438
466
|
return hashBytes(encoder.encode(resource)).slice(0, 16);
|
|
439
467
|
}
|
|
440
468
|
|
|
469
|
+
/**
|
|
470
|
+
* Cursors that carry an offset are tagged, so a hand-copied cursor can be
|
|
471
|
+
* recognised as damaged. Status cursors are not: they hold no offset, a
|
|
472
|
+
* damaged one already falls back to the current facts, and their payload sits
|
|
473
|
+
* in 1 KiB status responses where every cursor byte competes with decision
|
|
474
|
+
* facts (`remote setup: …` was clipped once the cursor grew).
|
|
475
|
+
*/
|
|
476
|
+
function isTaggedCursorKind(kind: CursorPayload["k"]): boolean {
|
|
477
|
+
return kind !== "s";
|
|
478
|
+
}
|
|
479
|
+
|
|
441
480
|
function encodeCursor(payload: CursorPayload): string {
|
|
442
|
-
|
|
481
|
+
const tagged = isTaggedCursorKind(payload.k) ? { ...payload, x: cursorIntegrityTag(payload) } : payload;
|
|
482
|
+
return CURSOR_PREFIX + Buffer.from(JSON.stringify(tagged), "utf8").toString("base64url");
|
|
443
483
|
}
|
|
444
484
|
|
|
485
|
+
/**
|
|
486
|
+
* Integrity tag over every payload field except the tag itself.
|
|
487
|
+
*
|
|
488
|
+
* Cursors are re-typed by the model. One mistyped base64url character used to
|
|
489
|
+
* decode into a payload that still parsed: when the changed field was the
|
|
490
|
+
* source digest the pager reported `source-replaced`, restarted at byte 0 and
|
|
491
|
+
* minted the same cursor again — the caller could never reach the rest of the
|
|
492
|
+
* text (#617). The tag makes a near-miss detectable as corruption instead of
|
|
493
|
+
* being read as a different source.
|
|
494
|
+
*/
|
|
495
|
+
function cursorIntegrityTag(payload: CursorPayload): string {
|
|
496
|
+
const { x: _ignored, ...rest } = payload;
|
|
497
|
+
// 36 bits: enough to catch an accidental edit, and short enough that the
|
|
498
|
+
// cursor stays a small thing to copy.
|
|
499
|
+
return shortHash(encoder.encode(JSON.stringify(rest))).slice(0, 6);
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
/**
|
|
503
|
+
* Structural decode only: a corrupted payload still reports its kind and
|
|
504
|
+
* resource so it can be classified and, where the offset is still meaningful,
|
|
505
|
+
* resumed. `cursorIntegrityOk` is the separate integrity verdict.
|
|
506
|
+
*/
|
|
445
507
|
function decodeCursor(cursor: string | undefined): CursorPayload | undefined {
|
|
446
508
|
if (!cursor || !cursor.startsWith(CURSOR_PREFIX)) return undefined;
|
|
447
509
|
try {
|
|
@@ -453,6 +515,39 @@ function decodeCursor(cursor: string | undefined): CursorPayload | undefined {
|
|
|
453
515
|
return undefined;
|
|
454
516
|
}
|
|
455
517
|
|
|
518
|
+
/** False when any payload field was altered after the cursor was minted. */
|
|
519
|
+
function cursorIntegrityOk(parsed: CursorPayload): boolean {
|
|
520
|
+
if (!isTaggedCursorKind(parsed.k)) return true;
|
|
521
|
+
return typeof parsed.x === "string" && parsed.x === cursorIntegrityTag(parsed);
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
/**
|
|
525
|
+
* Digest of one source snapshot at one offset. A text cursor carries it in `v`
|
|
526
|
+
* and, recomputed against the current text, it answers both questions a
|
|
527
|
+
* continuation needs: is this still the same source, and is this still its
|
|
528
|
+
* offset? A changed source or a shifted offset changes it (#617).
|
|
529
|
+
*/
|
|
530
|
+
function textSnapshotDigest(revision: string, offset: number): string {
|
|
531
|
+
return shortHash(encoder.encode(`t\0${revision}\0${offset}`));
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
/**
|
|
535
|
+
* Second, independent witness of the same fact, stored in `w`: the snapshot,
|
|
536
|
+
* its length, and the offset. Both witnesses are recomputed from the current
|
|
537
|
+
* text, so damage to either one alone still leaves a usable cursor — the
|
|
538
|
+
* reported one-character miscopy keeps the page advancing instead of replaying
|
|
539
|
+
* page 1 forever, while a genuinely replaced or shifted source fails both.
|
|
540
|
+
*/
|
|
541
|
+
function textOffsetWitness(revision: string, offset: number, length: number): string {
|
|
542
|
+
return shortHash(encoder.encode(`t\0${revision}\0${length}\0${offset}`)).slice(0, 6);
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
/** Decoded page offset, or NaN when the field did not survive decoding. */
|
|
546
|
+
function cursorOffset(parsed: CursorPayload): number {
|
|
547
|
+
const o = parsed.o;
|
|
548
|
+
return typeof o === "number" && Number.isFinite(o) ? Math.floor(o) : Number.NaN;
|
|
549
|
+
}
|
|
550
|
+
|
|
456
551
|
export function cursorKind(cursor: string | undefined): "t" | "f" | "s" | "l" | undefined {
|
|
457
552
|
if (cursor?.startsWith(ROW_CURSOR_PREFIX)) return decodeRowCursor(cursor) ? "l" : undefined;
|
|
458
553
|
return decodeCursor(cursor)?.k;
|
|
@@ -491,6 +586,14 @@ function emptyPage(overrides: Partial<PageResult> & Pick<PageResult, "revision"
|
|
|
491
586
|
* Page exact UTF-8 text. Consecutive pages concatenate to the original string.
|
|
492
587
|
* Cursors are caller-owned: the same cursor plus maxBytes always yields the
|
|
493
588
|
* same page, and two callers do not share consumption.
|
|
589
|
+
*
|
|
590
|
+
* A cursor that fails its integrity check is reported as `cursor-corrupt`,
|
|
591
|
+
* never as a replaced source, and never replays page 1 blindly: it resumes at
|
|
592
|
+
* its decoded offset only when a witness recomputed from the current text
|
|
593
|
+
* proves that offset still belongs to the same snapshot. Otherwise — a
|
|
594
|
+
* replaced, grown, or shifted source, a damaged offset, or a cursor from
|
|
595
|
+
* before the witnesses existed — the page restarts at byte 0, so no unread
|
|
596
|
+
* text is skipped (#617).
|
|
494
597
|
*/
|
|
495
598
|
export function pageVerbatimText(text: string, request: PageRequest = {}): PageResult {
|
|
496
599
|
const maxBytes = pagerBudget(request.maxBytes, OUTPUT_BUDGET_BYTES.answer);
|
|
@@ -501,20 +604,43 @@ export function pageVerbatimText(text: string, request: PageRequest = {}): PageR
|
|
|
501
604
|
let reset: PageReset | undefined;
|
|
502
605
|
const parsed = decodeCursor(request.cursor);
|
|
503
606
|
if (request.cursor) {
|
|
504
|
-
if (!parsed || parsed.k !== "t"
|
|
607
|
+
if (!parsed || parsed.k !== "t") {
|
|
608
|
+
reset = "stale-cursor";
|
|
609
|
+
} else if (!cursorIntegrityOk(parsed) || parsed.w === undefined) {
|
|
610
|
+
// A payload without its position witness (a cursor minted before this
|
|
611
|
+
// format) is treated the same as a damaged one: its offset is unproven.
|
|
612
|
+
reset = "cursor-corrupt";
|
|
613
|
+
if ((parsed.r ?? undefined) === resource) {
|
|
614
|
+
const decoded = cursorOffset(parsed);
|
|
615
|
+
const inside = Number.isFinite(decoded) && decoded >= 0 && decoded <= encoded.length;
|
|
616
|
+
// Two independent witnesses of "this snapshot at this offset": either
|
|
617
|
+
// one surviving a single damaged field keeps a static-source cursor
|
|
618
|
+
// moving instead of looping on page 1.
|
|
619
|
+
const witnessed = inside && (
|
|
620
|
+
parsed.v === textSnapshotDigest(revision, decoded)
|
|
621
|
+
|| (parsed.w !== undefined && parsed.w === textOffsetWitness(revision, decoded, encoded.length))
|
|
622
|
+
);
|
|
623
|
+
if (witnessed) offset = decoded;
|
|
624
|
+
}
|
|
625
|
+
} else if ((parsed.r ?? undefined) !== resource) {
|
|
505
626
|
reset = "stale-cursor";
|
|
506
|
-
} else if (parsed.v !== revision) {
|
|
507
|
-
reset = "source-replaced";
|
|
508
627
|
} else {
|
|
509
628
|
offset = Math.min(encoded.length, Math.max(0, Math.floor(parsed.o ?? 0)));
|
|
629
|
+
if (parsed.v !== textSnapshotDigest(revision, offset)) {
|
|
630
|
+
// Same cursor, different text: restart at byte 0 rather than serving
|
|
631
|
+
// bytes from a position that no longer means what it did.
|
|
632
|
+
reset = "source-replaced";
|
|
633
|
+
offset = 0;
|
|
634
|
+
}
|
|
510
635
|
}
|
|
511
636
|
}
|
|
512
637
|
const mint = (o: number): string => encodeCursor({
|
|
513
638
|
k: "t",
|
|
514
639
|
...(resource !== undefined ? { r: resource } : {}),
|
|
515
|
-
v: revision,
|
|
640
|
+
v: textSnapshotDigest(revision, o),
|
|
516
641
|
o,
|
|
517
642
|
n: encoded.length,
|
|
643
|
+
w: textOffsetWitness(revision, o, encoded.length),
|
|
518
644
|
});
|
|
519
645
|
const make = (start: number, end: number): PageResult => ({
|
|
520
646
|
text: decoder.decode(encoded.subarray(start, end)),
|
|
@@ -598,6 +724,35 @@ function fileReadError(
|
|
|
598
724
|
});
|
|
599
725
|
}
|
|
600
726
|
|
|
727
|
+
/**
|
|
728
|
+
* Start byte of an end-anchored page inside `window` (the bytes immediately
|
|
729
|
+
* before its upper bound). A backward page starts just after the first newline
|
|
730
|
+
* that keeps at least half the window, so consecutive pages concatenate; when
|
|
731
|
+
* no such newline exists (one oversized line) it starts on the next whole code
|
|
732
|
+
* point and the page begins mid-line rather than stalling.
|
|
733
|
+
*/
|
|
734
|
+
function backwardPageStart(window: Buffer): number {
|
|
735
|
+
let start = 0;
|
|
736
|
+
while (start < window.length && isContinuation(window[start]!)) start += 1;
|
|
737
|
+
const floor = Math.ceil(window.length / 2);
|
|
738
|
+
for (let i = start; i < floor; i += 1) {
|
|
739
|
+
if (window[i] === NEWLINE) return i + 1;
|
|
740
|
+
}
|
|
741
|
+
return start;
|
|
742
|
+
}
|
|
743
|
+
|
|
744
|
+
/**
|
|
745
|
+
* Largest boundary <= `end` that does not split a UTF-8 sequence, looking only
|
|
746
|
+
* at the bytes retained up to `end`. Used for the newest retained byte, which
|
|
747
|
+
* a writer can leave inside a code point it has not finished emitting.
|
|
748
|
+
*/
|
|
749
|
+
function completeCodePointEnd(fd: number, end: number): number {
|
|
750
|
+
if (end <= 0) return 0;
|
|
751
|
+
const from = Math.max(0, end - 4);
|
|
752
|
+
const tail = readAt(fd, from, end - from);
|
|
753
|
+
return from + utf8SafeEnd(tail, 0, tail.length);
|
|
754
|
+
}
|
|
755
|
+
|
|
601
756
|
/**
|
|
602
757
|
* Page retained file bytes without skipping unread ranges. Snapshot high-water
|
|
603
758
|
* marks keep a page stable while the file appends. Cursors bind the resource
|
|
@@ -640,32 +795,46 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
|
|
|
640
795
|
let appendReady = false;
|
|
641
796
|
|
|
642
797
|
if (request.cursor) {
|
|
643
|
-
if (!parsed || parsed.k !== "f"
|
|
798
|
+
if (!parsed || parsed.k !== "f") {
|
|
644
799
|
reset = "stale-cursor";
|
|
645
|
-
} else if (parsed.i !== identity) {
|
|
646
|
-
reset = "source-replaced";
|
|
647
800
|
} else {
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
reset = "
|
|
660
|
-
} else if (
|
|
661
|
-
|
|
662
|
-
// cursor changed without a declared compaction: rewritten in place,
|
|
663
|
-
// or deleted and recreated on a reused inode with coarse timestamps.
|
|
664
|
-
reset = "source-replaced";
|
|
801
|
+
// A hand-copied cursor is never reported as a replaced source: that was
|
|
802
|
+
// a false claim, and the restart replayed page 1 forever (#617). A
|
|
803
|
+
// damaged payload is also never resumed: its offset *and* its direction
|
|
804
|
+
// come from a payload that failed its integrity check, so the pass
|
|
805
|
+
// restarts at its own anchor (byte 0 forward, the newest byte backward)
|
|
806
|
+
// instead of continuing somewhere the caller never reached (#617 R1).
|
|
807
|
+
const corrupt = !cursorIntegrityOk(parsed);
|
|
808
|
+
const reason = (clean: PageReset): PageReset => (corrupt ? "cursor-corrupt" : clean);
|
|
809
|
+
if (parsed.r !== resource) {
|
|
810
|
+
reset = reason("stale-cursor");
|
|
811
|
+
} else if (parsed.i !== identity) {
|
|
812
|
+
reset = reason("source-replaced");
|
|
813
|
+
} else if (corrupt) {
|
|
814
|
+
reset = "cursor-corrupt";
|
|
665
815
|
} else {
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
816
|
+
const o = Math.max(0, Math.floor(parsed.o ?? 0));
|
|
817
|
+
const n = Math.max(0, Math.floor(parsed.n ?? 0));
|
|
818
|
+
const headLength = Math.max(0, Math.floor(parsed.hl ?? 0));
|
|
819
|
+
const generationChanged = generation !== undefined && parsed.g !== generation;
|
|
820
|
+
const bytesIntact = o <= n
|
|
821
|
+
&& n <= size
|
|
822
|
+
&& headLength <= size
|
|
823
|
+
&& (!parsed.h || shortHash(head.subarray(0, headLength)) === parsed.h)
|
|
824
|
+
&& (o === 0 || windowHash(o) === parsed.w);
|
|
825
|
+
if (generationChanged) {
|
|
826
|
+
// The consumer declared a compaction/replacement of this file.
|
|
827
|
+
reset = "compacted";
|
|
828
|
+
} else if (!bytesIntact) {
|
|
829
|
+
// Same file object as far as stat can tell, but the bytes behind the
|
|
830
|
+
// cursor changed without a declared compaction: rewritten in place,
|
|
831
|
+
// or deleted and recreated on a reused inode with coarse timestamps.
|
|
832
|
+
reset = "source-replaced";
|
|
833
|
+
} else {
|
|
834
|
+
offset = o;
|
|
835
|
+
snapshot = n;
|
|
836
|
+
appendReady = parsed.a === 1;
|
|
837
|
+
}
|
|
669
838
|
}
|
|
670
839
|
}
|
|
671
840
|
}
|
|
@@ -674,7 +843,7 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
|
|
|
674
843
|
snapshot = Math.max(snapshot, initialSnapshot());
|
|
675
844
|
}
|
|
676
845
|
|
|
677
|
-
const mint = (o: number, n: number, append: boolean): string => {
|
|
846
|
+
const mint = (o: number, n: number, append: boolean, back = false): string => {
|
|
678
847
|
const window = windowHash(o);
|
|
679
848
|
return encodeCursor({
|
|
680
849
|
k: "f",
|
|
@@ -687,6 +856,7 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
|
|
|
687
856
|
hl: head.length,
|
|
688
857
|
...(window ? { w: window } : {}),
|
|
689
858
|
...(append ? { a: 1 } : {}),
|
|
859
|
+
...(back ? { b: 1 as const } : {}),
|
|
690
860
|
});
|
|
691
861
|
};
|
|
692
862
|
const base = {
|
|
@@ -694,6 +864,80 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
|
|
|
694
864
|
...(reset ? { reset } : {}),
|
|
695
865
|
};
|
|
696
866
|
|
|
867
|
+
// A backward cursor keeps its own direction (even after a reset, which
|
|
868
|
+
// restarts at the newest bytes); the request flag starts one.
|
|
869
|
+
const backward = parsed?.k === "f" ? parsed.b === 1 : request.direction === "backward";
|
|
870
|
+
if (backward) {
|
|
871
|
+
if (!request.cursor || reset) offset = snapshot;
|
|
872
|
+
if (offset > snapshot) offset = snapshot;
|
|
873
|
+
const mintBackward = (o: number): string => mint(o, snapshot, false, true);
|
|
874
|
+
const revision = fileRevision(generation, identity, snapshot);
|
|
875
|
+
// The newest retained byte can stop inside a code point the writer has not
|
|
876
|
+
// finished. Withhold that suffix like the forward pager does, and anchor
|
|
877
|
+
// the append cursor at its first byte, so the whole character arrives once
|
|
878
|
+
// the writer completes it. Every other page starts where a previous page
|
|
879
|
+
// already aligned.
|
|
880
|
+
const snapshotEnd = completeCodePointEnd(opened, snapshot);
|
|
881
|
+
if (offset <= 0) {
|
|
882
|
+
// Nothing earlier is retained: hand back the forward append-ready cursor.
|
|
883
|
+
return emptyPage({
|
|
884
|
+
revision,
|
|
885
|
+
cursor: mintBackward(0),
|
|
886
|
+
nextCursor: mint(snapshotEnd, snapshotEnd, true),
|
|
887
|
+
totalBytes: snapshot,
|
|
888
|
+
startByte: 0,
|
|
889
|
+
endByte: 0,
|
|
890
|
+
appendReady: true,
|
|
891
|
+
direction: "backward",
|
|
892
|
+
...(snapshotEnd < snapshot ? { pendingBytes: snapshot - snapshotEnd } : {}),
|
|
893
|
+
...base,
|
|
894
|
+
});
|
|
895
|
+
}
|
|
896
|
+
const from = Math.max(0, offset - maxBytes);
|
|
897
|
+
const window = readAt(opened, from, offset - from);
|
|
898
|
+
const withheldFrom = offset === snapshot ? snapshotEnd : offset;
|
|
899
|
+
const pendingBytes = offset - withheldFrom;
|
|
900
|
+
// Byte 0 is always a valid page start; otherwise start at the first line
|
|
901
|
+
// boundary that keeps as much of the window as possible.
|
|
902
|
+
const reachedStart = from === 0;
|
|
903
|
+
const start = reachedStart ? 0 : from + backwardPageStart(window.subarray(0, withheldFrom - from));
|
|
904
|
+
if (!reachedStart && start >= withheldFrom) {
|
|
905
|
+
// Budget is smaller than the next code point behind the cursor: stay put.
|
|
906
|
+
const here = mintBackward(offset);
|
|
907
|
+
return emptyPage({
|
|
908
|
+
revision,
|
|
909
|
+
cursor: here,
|
|
910
|
+
nextCursor: here,
|
|
911
|
+
hasMore: true,
|
|
912
|
+
omittedBytes: offset,
|
|
913
|
+
totalBytes: snapshot,
|
|
914
|
+
startByte: offset,
|
|
915
|
+
endByte: offset,
|
|
916
|
+
direction: "backward",
|
|
917
|
+
...(pendingBytes > 0 ? { pendingBytes } : {}),
|
|
918
|
+
...base,
|
|
919
|
+
});
|
|
920
|
+
}
|
|
921
|
+
return {
|
|
922
|
+
text: decoder.decode(window.subarray(start - from, withheldFrom - from)),
|
|
923
|
+
revision,
|
|
924
|
+
cursor: mintBackward(offset),
|
|
925
|
+
// Reaching the oldest byte hands the whole pass back to forward polling:
|
|
926
|
+
// the append cursor sits on the newest complete code point, so a withheld
|
|
927
|
+
// character is returned whole rather than skipped.
|
|
928
|
+
nextCursor: reachedStart ? mint(snapshotEnd, snapshotEnd, true) : mintBackward(start),
|
|
929
|
+
hasMore: !reachedStart,
|
|
930
|
+
omittedBytes: start,
|
|
931
|
+
totalBytes: snapshot,
|
|
932
|
+
startByte: start,
|
|
933
|
+
endByte: withheldFrom,
|
|
934
|
+
...(reachedStart ? { appendReady: true } : {}),
|
|
935
|
+
...(pendingBytes > 0 ? { pendingBytes } : {}),
|
|
936
|
+
direction: "backward",
|
|
937
|
+
...base,
|
|
938
|
+
};
|
|
939
|
+
}
|
|
940
|
+
|
|
697
941
|
if (offset > snapshot) offset = snapshot;
|
|
698
942
|
if (offset >= snapshot) {
|
|
699
943
|
return emptyPage({
|
|
@@ -1088,7 +1332,9 @@ function formatContinuation(info: {
|
|
|
1088
1332
|
? `omittedRows=${page.omittedRows}`
|
|
1089
1333
|
: `omittedBytes=${page.omittedBytes}`;
|
|
1090
1334
|
const cursor = page.nextCursor ? ` nextCursor=${page.nextCursor}${page.via ? ` (${page.via})` : ""}` : "";
|
|
1091
|
-
|
|
1335
|
+
// End-anchored pages count earlier bytes and continue toward the start.
|
|
1336
|
+
const direction = page.direction === "backward" ? " (newest-first page; nextCursor reads earlier bytes)" : "";
|
|
1337
|
+
lines.push(`hasMore=${page.hasMore} ${amount}${cursor}${direction}`);
|
|
1092
1338
|
} else if (page?.appendReady && page.nextCursor) {
|
|
1093
1339
|
lines.push(`end nextCursor=${page.nextCursor} (reuse to read only bytes appended later)`);
|
|
1094
1340
|
}
|
package/stop.ts
CHANGED
|
@@ -16,6 +16,11 @@
|
|
|
16
16
|
* process-group evidence remains, reread the child log and finalize from
|
|
17
17
|
* coherent terminal evidence (`completed` / `failed`) or record `lost`.
|
|
18
18
|
*
|
|
19
|
+
* Terminal completion (#624): every terminal write here also records the run's
|
|
20
|
+
* pending completion marker, so a stopped, killed, or cleanup-finalized run
|
|
21
|
+
* still produces exactly one completion callback (delivered at the next
|
|
22
|
+
* boundary, or recovered by the next Pi instance after `/reload`).
|
|
23
|
+
*
|
|
19
24
|
* Process-group-only contract (ADR 0002): related work is the captured
|
|
20
25
|
* process group (pgid, falling back to pid for old metadata). Escaped /
|
|
21
26
|
* reparented descendants outside that group are out of contract and are
|
|
@@ -26,6 +31,8 @@ import { realProcessProbe, type ProcessProbe } from "./health.ts";
|
|
|
26
31
|
import { parseRunForLifecycle } from "./parse.ts";
|
|
27
32
|
import {
|
|
28
33
|
effectiveStatus,
|
|
34
|
+
launchAttemptInProgress,
|
|
35
|
+
purgeAbandonedLaunch,
|
|
29
36
|
readMeta,
|
|
30
37
|
writeMeta,
|
|
31
38
|
type RunMeta,
|
|
@@ -35,7 +42,13 @@ import { killProcessTree } from "./spawn.ts";
|
|
|
35
42
|
export type StopOutcome =
|
|
36
43
|
| { action: "stopped"; id: string }
|
|
37
44
|
| { action: "finalized"; id: string; status: "completed" | "failed" | "lost" }
|
|
38
|
-
| { action: "not-running"; id: string; status: string }
|
|
45
|
+
| { action: "not-running"; id: string; status: string }
|
|
46
|
+
| { action: "purged"; id: string }
|
|
47
|
+
/**
|
|
48
|
+
* The id is not debris right now: a concurrent launch either published its
|
|
49
|
+
* metadata or is still preparing it. Nothing was removed.
|
|
50
|
+
*/
|
|
51
|
+
| { action: "preserved"; id: string; status: string };
|
|
39
52
|
|
|
40
53
|
export interface StopDeps {
|
|
41
54
|
/** OS process probe; defaults to the real probe. Tests inject fakes. */
|
|
@@ -66,10 +79,32 @@ function terminateRelatedWork(meta: Pick<RunMeta, "pid" | "pgid">): number | und
|
|
|
66
79
|
return pgid;
|
|
67
80
|
}
|
|
68
81
|
|
|
82
|
+
/**
|
|
83
|
+
* Record the one durable terminal-completion obligation (#624).
|
|
84
|
+
*
|
|
85
|
+
* Every terminal transition owes its caller exactly one completion callback:
|
|
86
|
+
* the callback batcher delivers it once at the next boundary and writes the
|
|
87
|
+
* sent marker, and `/reload` recovers a record that is still marked pending.
|
|
88
|
+
* A stop is a terminal transition like any other, so it must set the marker —
|
|
89
|
+
* otherwise a killed run stays silent now and after `session_start` recovery,
|
|
90
|
+
* which is the case the caller can only notice by polling (or never).
|
|
91
|
+
*
|
|
92
|
+
* `callback:false` runs owe no model message, and an existing marker (sent,
|
|
93
|
+
* suppressed, or already pending) is never moved or reintroduced.
|
|
94
|
+
*/
|
|
95
|
+
function oweTerminalCompletion(meta: RunMeta, now: number): void {
|
|
96
|
+
if (meta.callback === false) return;
|
|
97
|
+
if (meta.completionCallbackPendingAt !== undefined
|
|
98
|
+
|| meta.completionCallbackSentAt !== undefined
|
|
99
|
+
|| meta.completionCallbackSuppressedAt !== undefined) return;
|
|
100
|
+
meta.completionCallbackPendingAt = now;
|
|
101
|
+
}
|
|
102
|
+
|
|
69
103
|
function recordKilled(meta: RunMeta, now: number): StopOutcome {
|
|
70
104
|
meta.status = "killed";
|
|
71
105
|
meta.lifecycleClassification = "killed";
|
|
72
106
|
meta.endedAt = now;
|
|
107
|
+
oweTerminalCompletion(meta, now);
|
|
73
108
|
writeMeta(meta);
|
|
74
109
|
return { action: "stopped", id: meta.id };
|
|
75
110
|
}
|
|
@@ -87,6 +122,7 @@ function finalizeOrphanedWithoutProcess(meta: RunMeta, now: number): StopOutcome
|
|
|
87
122
|
meta.lifecycleClassification = "complete";
|
|
88
123
|
if (meta.exitCode === undefined) meta.exitCode = 0;
|
|
89
124
|
meta.endedAt = now;
|
|
125
|
+
oweTerminalCompletion(meta, now);
|
|
90
126
|
writeMeta(meta);
|
|
91
127
|
return { action: "finalized", id: meta.id, status: "completed" };
|
|
92
128
|
}
|
|
@@ -96,11 +132,15 @@ function finalizeOrphanedWithoutProcess(meta: RunMeta, now: number): StopOutcome
|
|
|
96
132
|
meta.lifecycleClassification = "incomplete_open_tools";
|
|
97
133
|
meta.failureReason = "incomplete-stream";
|
|
98
134
|
meta.endedAt = now;
|
|
135
|
+
oweTerminalCompletion(meta, now);
|
|
99
136
|
writeMeta(meta);
|
|
100
137
|
return { action: "finalized", id: meta.id, status: "failed" };
|
|
101
138
|
}
|
|
102
139
|
|
|
103
140
|
// No coherent terminal completion evidence and no related process remains.
|
|
141
|
+
// `lost` is the one terminal outcome that does NOT owe a completion callback:
|
|
142
|
+
// its dedicated health callback (subagent-health) is the terminal notice, so
|
|
143
|
+
// marking a completion here would report the same run twice.
|
|
104
144
|
meta.status = "lost";
|
|
105
145
|
meta.lifecycleClassification = "lost";
|
|
106
146
|
meta.lostAt = now;
|
|
@@ -131,11 +171,29 @@ function cleanupOrphanedRun(meta: RunMeta, probe: ProcessProbe, now: number): St
|
|
|
131
171
|
* otherwise reread logs and finalize completed/failed/lost.
|
|
132
172
|
* - other statuses → not-running (on-disk record untouched).
|
|
133
173
|
*
|
|
174
|
+
* An id with no metadata is either unknown or an abandoned launch record (a
|
|
175
|
+
* launch that never wrote `meta.json` and never started a child). The latter is
|
|
176
|
+
* purged, so the operator can clear launch debris (#623) without waiting for the
|
|
177
|
+
* sweep's grace period. A concurrent launch that owns the record — published, or
|
|
178
|
+
* still preparing under its claim — is preserved, never deleted (#623 R1).
|
|
179
|
+
* Anything else stays an unknown id.
|
|
180
|
+
*
|
|
134
181
|
* Throws on an unknown id (same contract as the stop tool).
|
|
135
182
|
*/
|
|
136
183
|
export function stopRun(id: string, deps: StopDeps = {}): StopOutcome {
|
|
137
184
|
const meta = readMeta(id);
|
|
138
|
-
if (!meta)
|
|
185
|
+
if (!meta) {
|
|
186
|
+
const purge = purgeAbandonedLaunch(id);
|
|
187
|
+
if (purge === "purged") return { action: "purged", id };
|
|
188
|
+
// The purge re-checks under the run's metadata lock, so a launch may have
|
|
189
|
+
// become visible while we waited. Preserve it and say what it is.
|
|
190
|
+
const published = readMeta(id);
|
|
191
|
+
if (published) return { action: "preserved", id, status: effectiveStatus(published) };
|
|
192
|
+
if (purge === "retained" || launchAttemptInProgress(id)) {
|
|
193
|
+
return { action: "preserved", id, status: "launching" };
|
|
194
|
+
}
|
|
195
|
+
throw new Error(`Unknown run id: ${id}`);
|
|
196
|
+
}
|
|
139
197
|
const probe = deps.probe ?? realProcessProbe;
|
|
140
198
|
const now = typeof deps.now === "function" ? deps.now() : Date.now();
|
|
141
199
|
const status = effectiveStatus(meta);
|
package/timing.ts
CHANGED
|
@@ -26,6 +26,13 @@
|
|
|
26
26
|
* tool call does not count toward the stuck window, so a child in the middle
|
|
27
27
|
* of a 20-minute test run is not stuck. A caller that needs to bound a
|
|
28
28
|
* possibly hung command can opt into a ceiling.
|
|
29
|
+
*
|
|
30
|
+
* Because silence inside a running call is waiting, not being stuck, the
|
|
31
|
+
* parent also records the call it last saw open in the durable timing record
|
|
32
|
+
* (`inFlight`). A later parent (after `/reload`, or after a log rewrite) that
|
|
33
|
+
* can only read a bounded window may not see the call's start; the record is
|
|
34
|
+
* the still-alive evidence that keeps a silent build from being reported as
|
|
35
|
+
* stuck or stopped mid-call (#620).
|
|
29
36
|
*/
|
|
30
37
|
|
|
31
38
|
import { createHash } from "node:crypto";
|
|
@@ -63,6 +70,13 @@ export interface RunTiming {
|
|
|
63
70
|
stuckAnchorAt?: number;
|
|
64
71
|
/** Latest progress seen by the parent (floor for a reload whose log read is bounded). */
|
|
65
72
|
lastProgressAt?: number;
|
|
73
|
+
/**
|
|
74
|
+
* Tool call the parent last observed open, so a bounded reload read cannot
|
|
75
|
+
* turn a child that is waiting on a command into "no progress" (#620).
|
|
76
|
+
* `since` is when the open set became non-empty, which is also the pause
|
|
77
|
+
* start used once its result arrives.
|
|
78
|
+
*/
|
|
79
|
+
inFlight?: { id: string; since: number };
|
|
66
80
|
/** Set when the harness stopped the run. */
|
|
67
81
|
stopReason?: TimingStopReason;
|
|
68
82
|
stoppedAt?: number;
|
|
@@ -189,7 +203,7 @@ export interface ProgressState {
|
|
|
189
203
|
/** Latest event timestamp seen (message provenance only). */
|
|
190
204
|
lastEventAt?: number;
|
|
191
205
|
/** Tool calls started and not yet finished. */
|
|
192
|
-
open: Map<string, { name: string; command?: string; novel: boolean }>;
|
|
206
|
+
open: Map<string, { name: string; command?: string; novel: boolean; seeded?: boolean }>;
|
|
193
207
|
/** Hashes of tool name + normalized arguments already seen in this run (bounded, oldest evicted). */
|
|
194
208
|
seen: Set<string>;
|
|
195
209
|
/** When the open set last went from empty to non-empty. */
|
|
@@ -199,8 +213,20 @@ export interface ProgressState {
|
|
|
199
213
|
lastToolFailed: boolean;
|
|
200
214
|
}
|
|
201
215
|
|
|
202
|
-
|
|
203
|
-
|
|
216
|
+
/**
|
|
217
|
+
* Progress state for a run. `inFlight` seeds the open set from the durable
|
|
218
|
+
* record: the parent knows the child is waiting on that call even when the
|
|
219
|
+
* bounded log read no longer contains its start. A seeded entry carries no
|
|
220
|
+
* arguments, so its result is never mistaken for progress; the call's own
|
|
221
|
+
* result, or a later call's start, supersedes it.
|
|
222
|
+
*/
|
|
223
|
+
export function emptyProgress(startedAt: number, inFlight?: { id?: string; since?: number }): ProgressState {
|
|
224
|
+
const state: ProgressState = { startedAt, open: new Map(), seen: new Set(), pausedMs: 0, lastToolFailed: false };
|
|
225
|
+
if (typeof inFlight?.id === "string" && inFlight.id !== "" && typeof inFlight.since === "number" && Number.isFinite(inFlight.since)) {
|
|
226
|
+
state.open.set(inFlight.id, { name: "", novel: false, seeded: true });
|
|
227
|
+
state.inFlightSince = Math.max(startedAt, inFlight.since);
|
|
228
|
+
}
|
|
229
|
+
return state;
|
|
204
230
|
}
|
|
205
231
|
|
|
206
232
|
|
|
@@ -267,8 +293,23 @@ export function foldProgress(state: ProgressState, event: Record<string, unknown
|
|
|
267
293
|
const id = typeof event.toolCallId === "string" ? event.toolCallId : undefined;
|
|
268
294
|
if (!id) return;
|
|
269
295
|
const args = event.args as { command?: unknown } | undefined;
|
|
270
|
-
if (state.open.size === 0) state.inFlightSince = state.lastEventAt ?? state.startedAt;
|
|
271
296
|
const name = String(event.toolName ?? "");
|
|
297
|
+
// A different call starting means the seeded call finished while the log window
|
|
298
|
+
// was lost: its wait is a pause, not progress. A seed for this same id is
|
|
299
|
+
// replaced by the real event below.
|
|
300
|
+
const seedSince = state.inFlightSince;
|
|
301
|
+
let supersededSeed = false;
|
|
302
|
+
for (const [openId, call] of state.open) {
|
|
303
|
+
if (call.seeded && openId !== id) {
|
|
304
|
+
state.open.delete(openId);
|
|
305
|
+
supersededSeed = true;
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
if (supersededSeed && state.open.size === 0 && seedSince !== undefined) {
|
|
309
|
+
state.pausedMs += Math.max(0, (state.lastEventAt ?? state.startedAt) - seedSince);
|
|
310
|
+
state.inFlightSince = undefined;
|
|
311
|
+
}
|
|
312
|
+
if (state.open.size === 0) state.inFlightSince = state.lastEventAt ?? state.startedAt;
|
|
272
313
|
state.open.set(id, { name, command: typeof args?.command === "string" ? args.command : undefined, novel: remember(state, callKey(name, event.args)) });
|
|
273
314
|
return;
|
|
274
315
|
}
|