pi-better-subagents 0.25.1 → 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/README.md +1 -1
- package/batch.mjs +12 -3
- package/catalog-runtime.ts +6 -2
- package/cleanup.ts +176 -28
- package/continuation.ts +98 -15
- package/docs/usage.md +149 -69
- package/finalization.ts +1 -1
- package/index.ts +864 -468
- package/list.mjs +19 -3
- package/list.ts +1 -0
- package/output-payload.ts +40 -3
- package/package.json +1 -1
- package/registry.ts +347 -20
- package/session-selection.ts +35 -0
- package/session-store.ts +410 -0
- 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 +51 -29
- package/workspace-scope.ts +50 -0
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
|
|
|
12
12
|
|
|
13
13
|
## Core Features
|
|
14
14
|
- Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
|
|
15
|
-
-
|
|
15
|
+
- Continue a saved conversation with `subagent_spawn({ session_id, prompt })`, or use `session_name` for a unique name in the current folder. Sessions persist by default. Lists show session IDs and search locally; `all:true` searches globally. Batch jobs use the same selectors. See [continuing a saved conversation](docs/usage.md#continuing-a-saved-conversation).
|
|
16
16
|
- Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
|
|
17
17
|
- Opt-in OS task sandboxing on macOS and Linux.
|
|
18
18
|
- Explicit tool allowlists for child sessions.
|
package/batch.mjs
CHANGED
|
@@ -25,7 +25,7 @@ export const batchLaunchOutputSchema = {
|
|
|
25
25
|
type: "array",
|
|
26
26
|
items: {
|
|
27
27
|
type: "object",
|
|
28
|
-
properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, id: { type: "string" }, modelNote: { type: "string" } },
|
|
28
|
+
properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, id: { type: "string" }, sessionId: { type: "string" }, continuedFrom: { type: "string" }, modelNote: { type: "string" } },
|
|
29
29
|
required: ["job", "name", "id"],
|
|
30
30
|
additionalProperties: false,
|
|
31
31
|
},
|
|
@@ -94,6 +94,10 @@ export function mergeJobOptions(shared, job) {
|
|
|
94
94
|
git_clone_workspace: job.git_clone_workspace ?? shared?.git_clone_workspace,
|
|
95
95
|
approve: job.approve ?? shared?.approve,
|
|
96
96
|
allow_nested: job.allow_nested ?? shared?.allow_nested,
|
|
97
|
+
// Native session id selected for this JOB only. A shared value would make
|
|
98
|
+
// every job contend for the same conversation writer, so it is not inherited.
|
|
99
|
+
session_id: typeof job.session_id === "string" ? job.session_id : undefined,
|
|
100
|
+
session_name: typeof job.session_name === "string" ? job.session_name : undefined,
|
|
97
101
|
// Harness timing; an explicit null means "not set", so it falls through to shared.
|
|
98
102
|
deadline_minutes: job.deadline_minutes ?? shared?.deadline_minutes,
|
|
99
103
|
grace_minutes: job.grace_minutes ?? shared?.grace_minutes,
|
|
@@ -149,6 +153,11 @@ export function validateBatchPlan({ shared, jobs, onCapacity, config }) {
|
|
|
149
153
|
if (typeof job.prompt !== "string" || job.prompt.trim() === "") {
|
|
150
154
|
throw new Error(`job ${i + 1} is missing a non-empty prompt.`);
|
|
151
155
|
}
|
|
156
|
+
if (job.session_id !== undefined && job.session_name !== undefined) throw new Error(`job ${i + 1}: pass either session_id or session_name, not both.`);
|
|
157
|
+
if (job.session_name !== undefined && (typeof job.session_name !== "string" || job.session_name.trim() === "")) throw new Error(`job ${i + 1} session_name must be a non-empty name.`);
|
|
158
|
+
if (job.session_id !== undefined && (typeof job.session_id !== "string" || job.session_id.trim() === "")) {
|
|
159
|
+
throw new Error(`job ${i + 1} session_id must be a non-empty native session id.`);
|
|
160
|
+
}
|
|
152
161
|
if (seenPrompts.has(job.prompt)) {
|
|
153
162
|
// Duplicate prompts are allowed, but a batch with every prompt
|
|
154
163
|
// identical is a common mistake; warn via the error path only when
|
|
@@ -273,8 +282,8 @@ export function formatBatchLaunchResponse({ batchId, batchName, launched, skippe
|
|
|
273
282
|
lines.push(
|
|
274
283
|
`Batch ${label} launched ${launched.length} subagent(s):`,
|
|
275
284
|
);
|
|
276
|
-
for (const { name, id, modelNote } of launched) {
|
|
277
|
-
lines.push(`• ${name} → ${id}${modelNote ? ` · ${modelNote}` : ""}`);
|
|
285
|
+
for (const { name, id, sessionId, modelNote } of launched) {
|
|
286
|
+
lines.push(`• ${name} → ${id}${sessionId && sessionId !== id ? ` (session ${sessionId})` : ""}${modelNote ? ` · ${modelNote}` : ""}`);
|
|
278
287
|
}
|
|
279
288
|
}
|
|
280
289
|
|
package/catalog-runtime.ts
CHANGED
|
@@ -222,12 +222,16 @@ export async function clarifyCatalogRequest(
|
|
|
222
222
|
const normalized = jobs.map((job, index) => ({
|
|
223
223
|
job: { ...job, catalogJobIndex: index },
|
|
224
224
|
index,
|
|
225
|
-
|
|
226
|
-
|
|
225
|
+
continuation: job.session_id !== undefined || job.session_name !== undefined,
|
|
226
|
+
agent: job.session_id !== undefined || job.session_name !== undefined ? undefined : agentIdOf(job),
|
|
227
|
+
roles: job.session_id !== undefined || job.session_name !== undefined ? [] : roleIdsOf(job),
|
|
227
228
|
}));
|
|
228
229
|
const clean: CatalogJobFields[] = [];
|
|
229
230
|
const pending: { job: CatalogJobFields; index: number; agent?: string; roles: string[] }[] = [];
|
|
230
231
|
for (const item of normalized) {
|
|
232
|
+
// Saved conversations keep their launch recipe. Repeated selectors are
|
|
233
|
+
// checked against that recipe at admission, never clarified or expanded.
|
|
234
|
+
if (item.continuation) { clean.push(item.job); continue; }
|
|
231
235
|
if (item.roles.length > 1 || (item.agent && item.roles.length > 0)) pending.push(item);
|
|
232
236
|
else clean.push(withSelector(item.job, { agent: item.agent, role: item.roles[0] }));
|
|
233
237
|
}
|
package/cleanup.ts
CHANGED
|
@@ -9,11 +9,15 @@ import {
|
|
|
9
9
|
} from "node:fs";
|
|
10
10
|
import { join, relative, sep } from "node:path";
|
|
11
11
|
import {
|
|
12
|
+
ABANDONED_LAUNCH_GRACE_MS,
|
|
13
|
+
abandonedLaunchRecord,
|
|
12
14
|
baseDir,
|
|
13
15
|
listMetas,
|
|
16
|
+
observeArchivePublication,
|
|
14
17
|
ownedByThisParent,
|
|
15
18
|
orphanedTaskRuntimeProvenance,
|
|
16
19
|
processStartToken,
|
|
20
|
+
purgeAbandonedLaunch,
|
|
17
21
|
readMeta,
|
|
18
22
|
removeMetaArtifacts,
|
|
19
23
|
removeRunDirectory,
|
|
@@ -35,6 +39,7 @@ import {
|
|
|
35
39
|
withConversationMutation,
|
|
36
40
|
} from "./continuation.ts";
|
|
37
41
|
import { processExists } from "./spawn.ts";
|
|
42
|
+
import { archiveCompletedAttempt, archivePublicationPending, listArchivedAttempts } from "./session-store.ts";
|
|
38
43
|
|
|
39
44
|
export const DEFAULT_CLEANUP_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
|
|
40
45
|
|
|
@@ -80,6 +85,14 @@ export interface DailyCleanupResult {
|
|
|
80
85
|
dateKey: string;
|
|
81
86
|
removedRunDirs: number;
|
|
82
87
|
removedSessionPaths: number;
|
|
88
|
+
/** Launch attempts that never produced a run, reclaimed on this pass. */
|
|
89
|
+
removedAbandonedLaunches: number;
|
|
90
|
+
errors: string[];
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** Outcome of the launch-debris sweep alone (unit-testable, no daily marker). */
|
|
94
|
+
export interface AbandonedLaunchSweepResult {
|
|
95
|
+
removed: string[];
|
|
83
96
|
errors: string[];
|
|
84
97
|
}
|
|
85
98
|
|
|
@@ -346,6 +359,70 @@ function planCleanupOccupancy(
|
|
|
346
359
|
interface CleanupScope {
|
|
347
360
|
occupancy: CleanupOccupancy;
|
|
348
361
|
runIdsBySession: Map<string, string[]>;
|
|
362
|
+
/**
|
|
363
|
+
* Conversations whose saved session and launch recipe live in durable
|
|
364
|
+
* storage. Their history and owned clone workspace never age out; only the
|
|
365
|
+
* volatile log, metadata, and task scratch are reclaimed.
|
|
366
|
+
*/
|
|
367
|
+
persistent: ReadonlySet<string>;
|
|
368
|
+
/**
|
|
369
|
+
* Completed attempts whose compact durable record is still unpublished. The
|
|
370
|
+
* volatile run directory holds the only copy of the recipe, so both bounds
|
|
371
|
+
* retain the whole run until a sweep can publish it.
|
|
372
|
+
*/
|
|
373
|
+
archivePending: ReadonlySet<string>;
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* Conversations with a durable continuation record: a completed attempt saved
|
|
378
|
+
* its compact metadata and frozen recipe under the Pi agent directory. Their
|
|
379
|
+
* saved history and owned clone workspace are kept indefinitely; only the
|
|
380
|
+
* volatile log, metadata, and task scratch are reclaimed.
|
|
381
|
+
*
|
|
382
|
+
* A completed durable-layout attempt whose compact record could not be published
|
|
383
|
+
* belongs here too: it is not resumable yet, but its recipe, saved history, and
|
|
384
|
+
* clone are the only copy of that conversation.
|
|
385
|
+
*
|
|
386
|
+
* Legacy attempts (recipes pointing at the old temporary session directory, or
|
|
387
|
+
* fixtures without a recipe) never publish that record and keep the existing
|
|
388
|
+
* reclaimable behavior. A conversation that only ever failed is not resumable,
|
|
389
|
+
* so its artifacts stay ordinary aged history and do not pin a clone forever.
|
|
390
|
+
*/
|
|
391
|
+
function persistentSessionIds(
|
|
392
|
+
metas: readonly RunMeta[],
|
|
393
|
+
archivePending: ReadonlySet<string>,
|
|
394
|
+
): Set<string> {
|
|
395
|
+
const sessions = new Set(listArchivedAttempts().map((meta) => meta.sessionId));
|
|
396
|
+
for (const meta of metas) {
|
|
397
|
+
if (archivePending.has(meta.id)) sessions.add(meta.sessionId);
|
|
398
|
+
}
|
|
399
|
+
return sessions;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* Retry publication of every completed attempt whose compact durable record is
|
|
404
|
+
* missing, BEFORE either bound decides what to delete.
|
|
405
|
+
*
|
|
406
|
+
* The volatile run directory is the only place a completed attempt's recipe
|
|
407
|
+
* lives until that record is published, so this pass is what makes the age and
|
|
408
|
+
* size bounds safe: while it keeps failing, the runs it names are retained (see
|
|
409
|
+
* `CleanupScope.archivePending`), and once it succeeds they are ordinary
|
|
410
|
+
* persistent conversations whose raw logs may be reclaimed.
|
|
411
|
+
*
|
|
412
|
+
* Returns the run ids still unpublished.
|
|
413
|
+
*/
|
|
414
|
+
function retryPendingArchives(metas: readonly RunMeta[]): Set<string> {
|
|
415
|
+
const pending = new Set<string>();
|
|
416
|
+
for (const meta of metas) {
|
|
417
|
+
if (!archivePublicationPending(meta)) continue;
|
|
418
|
+
try {
|
|
419
|
+
if (archiveCompletedAttempt(meta)) observeArchivePublication(meta.id);
|
|
420
|
+
} catch (error) {
|
|
421
|
+
observeArchivePublication(meta.id, error);
|
|
422
|
+
}
|
|
423
|
+
if (archivePublicationPending(meta)) pending.add(meta.id);
|
|
424
|
+
}
|
|
425
|
+
return pending;
|
|
349
426
|
}
|
|
350
427
|
|
|
351
428
|
function runIdsBySession(metas: readonly RunMeta[]): Map<string, string[]> {
|
|
@@ -457,7 +534,7 @@ function cleanRunDirs(cutoff: number, scope: CleanupScope, errors: string[]): nu
|
|
|
457
534
|
const dir = runDir(id);
|
|
458
535
|
const meta = readMeta(id);
|
|
459
536
|
if (meta) {
|
|
460
|
-
if (!ageSweepEligible(meta, cutoff, retained, scope
|
|
537
|
+
if (!ageSweepEligible(meta, cutoff, retained, scope)) continue;
|
|
461
538
|
if (removeAgedRunArtifacts(meta, cutoff, retained, scope, errors)) removed += 1;
|
|
462
539
|
continue;
|
|
463
540
|
}
|
|
@@ -480,13 +557,15 @@ function ageSweepEligible(
|
|
|
480
557
|
meta: RunMeta,
|
|
481
558
|
cutoff: number,
|
|
482
559
|
retained: ReadonlySet<string>,
|
|
483
|
-
|
|
560
|
+
scope: CleanupScope,
|
|
484
561
|
): boolean {
|
|
485
562
|
if (!TERMINAL_CLEANUP_STATUSES.has(meta.status)) return false;
|
|
486
563
|
if (retained.has(meta.sessionId)) return false;
|
|
564
|
+
// The run directory still holds the only copy of this conversation's recipe.
|
|
565
|
+
if (scope.archivePending.has(meta.id)) return false;
|
|
487
566
|
// A released conversation can still be in use: a later attempt may run
|
|
488
567
|
// inside this root's clone, or a stop/kill may not have landed.
|
|
489
|
-
if (occupancy.runIds.has(meta.id)) return false;
|
|
568
|
+
if (scope.occupancy.runIds.has(meta.id)) return false;
|
|
490
569
|
return terminalTimestamp(meta) < cutoff;
|
|
491
570
|
}
|
|
492
571
|
|
|
@@ -515,8 +594,8 @@ function removeAgedRunArtifacts(
|
|
|
515
594
|
return withConversationSerialization(meta.sessionId, () => {
|
|
516
595
|
if (!conversationQuiescentUnderLock(meta.sessionId, runIds)) return false;
|
|
517
596
|
const fresh = readMeta(meta.id) ?? meta;
|
|
518
|
-
if (!ageSweepEligible(fresh, cutoff, retained, scope
|
|
519
|
-
if (removeMetaArtifacts(fresh)) return true;
|
|
597
|
+
if (!ageSweepEligible(fresh, cutoff, retained, scope)) return false;
|
|
598
|
+
if (removeMetaArtifacts(fresh, { keepWorkspace: scope.persistent.has(fresh.sessionId) })) return true;
|
|
520
599
|
errors.push(`${runDir(meta.id)}: could not remove run artifacts`);
|
|
521
600
|
return false;
|
|
522
601
|
}, () => false);
|
|
@@ -528,8 +607,8 @@ function removeAgedRunArtifacts(
|
|
|
528
607
|
* `<timestamp>_<sessionId>.jsonl` name, or the bare conversation name. History
|
|
529
608
|
* that resolves to nothing this sweep knows stays on the ordinary path.
|
|
530
609
|
*/
|
|
531
|
-
function sessionIdForPath(path: string, serialized: ReadonlySet<string>): string | undefined {
|
|
532
|
-
const rel = relative(
|
|
610
|
+
function sessionIdForPath(root: string, path: string, serialized: ReadonlySet<string>): string | undefined {
|
|
611
|
+
const rel = relative(root, path);
|
|
533
612
|
if (!rel || rel.startsWith("..")) return undefined;
|
|
534
613
|
const known = [...new Set(pathNameCandidates(rel.split(sep)))].filter((candidate) => serialized.has(candidate));
|
|
535
614
|
// Two different tracked conversations in one path is not a layout this
|
|
@@ -553,12 +632,13 @@ function* pathNameCandidates(parts: readonly string[]): Generator<string> {
|
|
|
553
632
|
* when this sweep tracks that conversation.
|
|
554
633
|
*/
|
|
555
634
|
function removeSessionPath(
|
|
635
|
+
root: string,
|
|
556
636
|
path: string,
|
|
557
637
|
serialized: ReadonlySet<string>,
|
|
558
638
|
scope: CleanupScope,
|
|
559
639
|
errors: string[],
|
|
560
640
|
): boolean {
|
|
561
|
-
const sessionId = sessionIdForPath(path, serialized);
|
|
641
|
+
const sessionId = sessionIdForPath(root, path, serialized);
|
|
562
642
|
if (!sessionId) return removePath(path, errors);
|
|
563
643
|
const runIds = scope.runIdsBySession.get(sessionId) ?? [];
|
|
564
644
|
return withConversationSerialization(sessionId, () => {
|
|
@@ -567,7 +647,7 @@ function removeSessionPath(
|
|
|
567
647
|
}, () => false);
|
|
568
648
|
}
|
|
569
649
|
|
|
570
|
-
function activeSessionIds(metas: RunMeta[], occupancy: CleanupOccupancy): Set<string> {
|
|
650
|
+
function activeSessionIds(metas: RunMeta[], occupancy: CleanupOccupancy, persistent: ReadonlySet<string>): Set<string> {
|
|
571
651
|
const active = new Set<string>(occupancy.sessions);
|
|
572
652
|
for (const meta of metas) {
|
|
573
653
|
if (meta.status === "running" || meta.status === "orphaned") active.add(meta.sessionId);
|
|
@@ -575,12 +655,14 @@ function activeSessionIds(metas: RunMeta[], occupancy: CleanupOccupancy): Set<st
|
|
|
575
655
|
// A retained completed conversation is not active work, but its saved
|
|
576
656
|
// session file is the history a continuation reopens.
|
|
577
657
|
for (const sessionId of retainedSessionIds()) active.add(sessionId);
|
|
658
|
+
// Durable conversations never expire with the volatile sweeps either.
|
|
659
|
+
for (const sessionId of persistent) active.add(sessionId);
|
|
578
660
|
return active;
|
|
579
661
|
}
|
|
580
662
|
|
|
581
|
-
function pathMentionsActiveSession(path: string, active: Set<string>): boolean {
|
|
663
|
+
function pathMentionsActiveSession(root: string, path: string, active: Set<string>): boolean {
|
|
582
664
|
if (active.size === 0) return false;
|
|
583
|
-
const rel = relative(
|
|
665
|
+
const rel = relative(root, path);
|
|
584
666
|
for (const sessionId of active) {
|
|
585
667
|
if (sessionId && rel.includes(sessionId)) return true;
|
|
586
668
|
}
|
|
@@ -588,6 +670,7 @@ function pathMentionsActiveSession(path: string, active: Set<string>): boolean {
|
|
|
588
670
|
}
|
|
589
671
|
|
|
590
672
|
function cleanSessionTree(
|
|
673
|
+
root: string,
|
|
591
674
|
cutoff: number,
|
|
592
675
|
active: Set<string>,
|
|
593
676
|
protectedPaths: readonly string[],
|
|
@@ -595,7 +678,6 @@ function cleanSessionTree(
|
|
|
595
678
|
serialized: ReadonlySet<string>,
|
|
596
679
|
errors: string[],
|
|
597
680
|
): number {
|
|
598
|
-
const root = sessionsDir();
|
|
599
681
|
if (!existsSync(root)) return 0;
|
|
600
682
|
let removed = 0;
|
|
601
683
|
|
|
@@ -614,10 +696,10 @@ function cleanSessionTree(
|
|
|
614
696
|
if (entry.isDirectory()) {
|
|
615
697
|
const childEmpty = visit(path);
|
|
616
698
|
if (childEmpty
|
|
617
|
-
&& !pathMentionsActiveSession(path, active)
|
|
699
|
+
&& !pathMentionsActiveSession(root, path, active)
|
|
618
700
|
&& !pathOverlapsProtected(path, protectedPaths)) {
|
|
619
701
|
const mtimeMs = safeStatMtime(path);
|
|
620
|
-
if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(path, serialized, scope, errors)) {
|
|
702
|
+
if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(root, path, serialized, scope, errors)) {
|
|
621
703
|
removed += 1;
|
|
622
704
|
continue;
|
|
623
705
|
}
|
|
@@ -626,12 +708,12 @@ function cleanSessionTree(
|
|
|
626
708
|
continue;
|
|
627
709
|
}
|
|
628
710
|
|
|
629
|
-
if (pathMentionsActiveSession(path, active) || pathOverlapsProtected(path, protectedPaths)) {
|
|
711
|
+
if (pathMentionsActiveSession(root, path, active) || pathOverlapsProtected(path, protectedPaths)) {
|
|
630
712
|
empty = false;
|
|
631
713
|
continue;
|
|
632
714
|
}
|
|
633
715
|
const mtimeMs = safeStatMtime(path);
|
|
634
|
-
if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(path, serialized, scope, errors)) {
|
|
716
|
+
if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(root, path, serialized, scope, errors)) {
|
|
635
717
|
removed += 1;
|
|
636
718
|
continue;
|
|
637
719
|
}
|
|
@@ -644,31 +726,90 @@ function cleanSessionTree(
|
|
|
644
726
|
return removed;
|
|
645
727
|
}
|
|
646
728
|
|
|
729
|
+
/**
|
|
730
|
+
* Reclaim launch attempts that never produced a supervised run (#623).
|
|
731
|
+
*
|
|
732
|
+
* A launch that throws while preparing (or a pi that dies in that window) can
|
|
733
|
+
* leave a run directory with only `prompt.md` and a sandbox `control/` dir: no
|
|
734
|
+
* `meta.json`, no `output.log`. Such a directory is unreadable run evidence
|
|
735
|
+
* forever and skews `subagent_list` counts, so it is reclaimed once it is older
|
|
736
|
+
* than {@link ABANDONED_LAUNCH_GRACE_MS}. The grace is the only guard needed:
|
|
737
|
+
* launch preparation is synchronous and short, and a directory with a log is
|
|
738
|
+
* never debris (the child may have started and its output is real evidence).
|
|
739
|
+
*
|
|
740
|
+
* Age alone is not an ownership proof: `purgeAbandonedLaunch` re-classifies and
|
|
741
|
+
* removes under the run's metadata lock, and a launch claim owned by a live
|
|
742
|
+
* process makes the record not-debris at any age, so a preparer that is paused
|
|
743
|
+
* past the grace is preserved and the sweep never deletes a live attempt's
|
|
744
|
+
* artifacts (#623 R1). A record a writer retained is left for the next sweep
|
|
745
|
+
* with an error so the retention stays visible.
|
|
746
|
+
*
|
|
747
|
+
* Runs before the daily marker in {@link runDailyCleanupOnce}, so every launch
|
|
748
|
+
* reclaims earlier debris instead of waiting for the next day's sweep.
|
|
749
|
+
* Best-effort; never throws into its caller.
|
|
750
|
+
*/
|
|
751
|
+
export function sweepAbandonedLaunches(options: { now?: number; graceMs?: number } = {}): AbandonedLaunchSweepResult {
|
|
752
|
+
const now = options.now ?? Date.now();
|
|
753
|
+
const grace = Number.isFinite(options.graceMs) && options.graceMs! >= 0 ? options.graceMs! : ABANDONED_LAUNCH_GRACE_MS;
|
|
754
|
+
const cutoff = now - grace;
|
|
755
|
+
let ids: string[];
|
|
756
|
+
try {
|
|
757
|
+
ids = readdirSync(join(baseDir(), "runs"));
|
|
758
|
+
} catch {
|
|
759
|
+
return { removed: [], errors: [] };
|
|
760
|
+
}
|
|
761
|
+
const removed: string[] = [];
|
|
762
|
+
const errors: string[] = [];
|
|
763
|
+
for (const id of ids) {
|
|
764
|
+
const attempt = abandonedLaunchRecord(id);
|
|
765
|
+
if (!attempt || attempt.mtimeMs >= cutoff) continue;
|
|
766
|
+
const purge = purgeAbandonedLaunch(id);
|
|
767
|
+
if (purge === "purged") removed.push(id);
|
|
768
|
+
else if (purge === "retained") errors.push(`${runDir(id)}: abandoned launch record could not be removed (in use, or its lock is unavailable)`);
|
|
769
|
+
}
|
|
770
|
+
return { removed, errors };
|
|
771
|
+
}
|
|
772
|
+
|
|
647
773
|
export function runDailyCleanupOnce(options: DailyCleanupOptions = {}): DailyCleanupResult {
|
|
648
774
|
const now = options.now ?? Date.now();
|
|
775
|
+
const abandoned = sweepAbandonedLaunches({ now });
|
|
649
776
|
const dateKey = localDateKey(now);
|
|
650
777
|
const state = readCleanupState();
|
|
651
778
|
if (state.lastLocalDate === dateKey) {
|
|
652
|
-
return { ran: false, dateKey, removedRunDirs: 0, removedSessionPaths: 0, errors: [] };
|
|
779
|
+
return { ran: false, dateKey, removedRunDirs: 0, removedSessionPaths: 0, removedAbandonedLaunches: abandoned.removed.length, errors: [...abandoned.errors] };
|
|
653
780
|
}
|
|
654
781
|
|
|
655
782
|
const errors: string[] = [];
|
|
656
783
|
const terminalRetention = retentionMs(options.terminalRunRetentionMs, options.config?.cleanupTerminalRunRetentionMs);
|
|
657
784
|
const sessionRetention = retentionMs(options.sessionRetentionMs, options.config?.cleanupSessionRetentionMs);
|
|
658
785
|
const metas = listMetas();
|
|
786
|
+
// Publish any outstanding compact record before this sweep reclaims the only
|
|
787
|
+
// copy of a completed attempt's recipe.
|
|
788
|
+
const archivePending = retryPendingArchives(metas);
|
|
789
|
+
const persistent = persistentSessionIds(metas, archivePending);
|
|
659
790
|
const scope: CleanupScope = {
|
|
660
791
|
occupancy: planCleanupOccupancy(metas, options.protect),
|
|
661
792
|
runIdsBySession: runIdsBySession(metas),
|
|
793
|
+
persistent,
|
|
794
|
+
archivePending,
|
|
662
795
|
};
|
|
663
796
|
const removedRunDirs = cleanRunDirs(now - terminalRetention, scope, errors);
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
797
|
+
// Native saved history is durable regardless of the latest attempt status.
|
|
798
|
+
// Sweep only legacy temporary sessions; eligibility to resume must never
|
|
799
|
+
// determine whether a durable native conversation is kept.
|
|
800
|
+
const sessionRoots = [join(baseDir(), "sessions")];
|
|
801
|
+
let removedSessionPaths = 0;
|
|
802
|
+
for (const root of sessionRoots) {
|
|
803
|
+
removedSessionPaths += cleanSessionTree(
|
|
804
|
+
root,
|
|
805
|
+
now - sessionRetention,
|
|
806
|
+
activeSessionIds(metas, scope.occupancy, persistent),
|
|
807
|
+
scope.occupancy.paths,
|
|
808
|
+
scope,
|
|
809
|
+
serializedConversations(metas),
|
|
810
|
+
errors,
|
|
811
|
+
);
|
|
812
|
+
}
|
|
672
813
|
|
|
673
814
|
try {
|
|
674
815
|
writeCleanupState({ lastLocalDate: dateKey, lastRunAt: now });
|
|
@@ -676,7 +817,7 @@ export function runDailyCleanupOnce(options: DailyCleanupOptions = {}): DailyCle
|
|
|
676
817
|
errors.push(`${cleanupStatePath()}: ${err instanceof Error ? err.message : String(err)}`);
|
|
677
818
|
}
|
|
678
819
|
|
|
679
|
-
return { ran: true, dateKey, removedRunDirs, removedSessionPaths, errors };
|
|
820
|
+
return { ran: true, dateKey, removedRunDirs, removedSessionPaths, removedAbandonedLaunches: abandoned.removed.length, errors: [...abandoned.errors, ...errors] };
|
|
680
821
|
}
|
|
681
822
|
|
|
682
823
|
/** Bytes held under one run directory. Best-effort; unreadable entries count 0. */
|
|
@@ -767,6 +908,10 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
|
|
|
767
908
|
?? (Number.isFinite(configured) && configured! > 0 ? configured! : DEFAULT_MAX_REGISTRY_BYTES);
|
|
768
909
|
|
|
769
910
|
const errors: string[] = [];
|
|
911
|
+
// Same ordering as the age sweep: retry archival first, so a run whose
|
|
912
|
+
// recipe only exists in its volatile directory is never a removal candidate.
|
|
913
|
+
const metas = listMetas();
|
|
914
|
+
const archivePending = retryPendingArchives(metas);
|
|
770
915
|
const entries = collectSizeCapEntries();
|
|
771
916
|
// Retained conversations and their workspaces are exempt from the byte
|
|
772
917
|
// bound until the owner releases them; a size sweep must not delete the
|
|
@@ -776,17 +921,20 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
|
|
|
776
921
|
// Occupancy costs a metadata scan and lease reads, so it is only computed
|
|
777
922
|
// when this sweep would actually remove something.
|
|
778
923
|
const totalBytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
|
|
779
|
-
const metas = listMetas();
|
|
780
924
|
const occupancy = totalBytes > maxBytes ? planCleanupOccupancy(metas, options.protect) : undefined;
|
|
781
925
|
const protectedIds = new Set([
|
|
782
926
|
...(options.protectedIds ?? ownRunIds(metas)),
|
|
783
927
|
...retainedRunIds(metas),
|
|
784
928
|
...(occupancy?.runIds ?? []),
|
|
929
|
+
// An unpublished compact record is the recipe's only copy.
|
|
930
|
+
...archivePending,
|
|
785
931
|
]);
|
|
786
932
|
const plan = planRegistrySizeCap(entries, { maxBytes, protectedIds });
|
|
787
933
|
const scope: CleanupScope = {
|
|
788
934
|
occupancy: occupancy ?? { sessions: new Set(), runIds: new Set(), paths: [] },
|
|
789
935
|
runIdsBySession: runIdsBySession(metas),
|
|
936
|
+
persistent: persistentSessionIds(metas, archivePending),
|
|
937
|
+
archivePending,
|
|
790
938
|
};
|
|
791
939
|
const bytesById = new Map(entries.map((entry) => [entry.id, entry.bytes]));
|
|
792
940
|
const removed: string[] = [];
|
|
@@ -830,7 +978,7 @@ function removeSizeCappedRun(
|
|
|
830
978
|
const fresh = readMeta(id) ?? meta;
|
|
831
979
|
if (!TERMINAL_CLEANUP_STATUSES.has(fresh.status)) return "retained";
|
|
832
980
|
if (scope.occupancy.runIds.has(fresh.id)) return "retained";
|
|
833
|
-
if (removeMetaArtifacts(fresh)) return "removed";
|
|
981
|
+
if (removeMetaArtifacts(fresh, { keepWorkspace: scope.persistent.has(fresh.sessionId) })) return "removed";
|
|
834
982
|
errors.push(`${runDir(id)}: could not remove run artifacts`);
|
|
835
983
|
return "failed";
|
|
836
984
|
}, () => "retained");
|
package/continuation.ts
CHANGED
|
@@ -1,11 +1,17 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Subagent continuation.
|
|
3
3
|
*
|
|
4
4
|
* A subagent attempt is one detached `pi -p` process; its conversation is a
|
|
5
5
|
* saved native session JSONL that outlives the process. Continuation keeps the
|
|
6
6
|
* conversation and allocates a NEW attempt, so old logs, results, callback
|
|
7
7
|
* markers, and timing records stay intact under their own run id.
|
|
8
8
|
*
|
|
9
|
+
* A completed attempt and an interrupted attempt stopped by `subagent_stop`
|
|
10
|
+
* (status `killed`) are both continuable: stopping ends an execution, not the
|
|
11
|
+
* saved conversation or the uncommitted workspace it leaves behind. The stopped
|
|
12
|
+
* attempt is never rewritten; the next attempt keeps `rootRunId` and records
|
|
13
|
+
* `resumedFrom`, so the interruption and its recovery stay distinguishable.
|
|
14
|
+
*
|
|
9
15
|
* This module owns the four seams that decision needs and that the rest of the
|
|
10
16
|
* package must not duplicate:
|
|
11
17
|
*
|
|
@@ -18,9 +24,19 @@
|
|
|
18
24
|
* clean/nesting/approval intent, confinement, model, effort, role identity,
|
|
19
25
|
* workspace intent) on run metadata.
|
|
20
26
|
* 3. **Explicit retention.** `retain_session` records a bounded promise that a
|
|
21
|
-
* completed conversation and its workspace stay out of cleanup until
|
|
22
|
-
*
|
|
23
|
-
* system-temp reaping can still remove it; a missing
|
|
27
|
+
* completed conversation and its workspace stay out of cleanup until a
|
|
28
|
+
* foreground session releases it. Retention lives in the existing runtime
|
|
29
|
+
* storage, so system-temp reaping can still remove it; a missing
|
|
30
|
+
* conversation refuses.
|
|
31
|
+
*
|
|
32
|
+
* Foreground-session ownership is provenance, not an authorization boundary:
|
|
33
|
+
* Pi sessions are ordinary files on disk, so any foreground session that can
|
|
34
|
+
* name a continuable attempt with a verifiable saved conversation, workspace,
|
|
35
|
+
* and launch recipe may continue it (or release its optional retention). The new
|
|
36
|
+
* attempt records the INVOKING foreground as its callback origin and its
|
|
37
|
+
* permission admission is re-resolved from the current profile, so continuing
|
|
38
|
+
* transfers the run to the caller instead of borrowing the original owner's
|
|
39
|
+
* authority.
|
|
24
40
|
* 4. **Conversation writer lease.** A cross-process token lease held from
|
|
25
41
|
* admission through child lifetime and finalization. Duplicate continuations
|
|
26
42
|
* of one conversation admit exactly one writer. Lease-path and retention
|
|
@@ -66,6 +82,7 @@ import {
|
|
|
66
82
|
type RunStatus,
|
|
67
83
|
} from "./registry.ts";
|
|
68
84
|
import { processExists } from "./spawn.ts";
|
|
85
|
+
import { durableSubagentRoot } from "./session-store.ts";
|
|
69
86
|
|
|
70
87
|
const nodeRequire = createRequire(import.meta.url);
|
|
71
88
|
|
|
@@ -231,7 +248,11 @@ export interface RetentionRecord {
|
|
|
231
248
|
ownerRunId: string;
|
|
232
249
|
/** Canonical workspace kept available for continuation. */
|
|
233
250
|
workspace: string;
|
|
234
|
-
/**
|
|
251
|
+
/**
|
|
252
|
+
* Foreground session that first retained this conversation. Provenance for
|
|
253
|
+
* diagnostics only: retention is optional convenience, not a tenancy
|
|
254
|
+
* boundary, so any foreground session may release it.
|
|
255
|
+
*/
|
|
235
256
|
ownerOrigin: RunCallbackOrigin;
|
|
236
257
|
retainedAt: number;
|
|
237
258
|
lastAttemptId: string;
|
|
@@ -398,7 +419,14 @@ export function markRetentionReleased(
|
|
|
398
419
|
|
|
399
420
|
// ---- ownership and continuation plan ------------------------------------
|
|
400
421
|
|
|
401
|
-
/**
|
|
422
|
+
/**
|
|
423
|
+
* True when `origin` is the foreground session recorded on the run.
|
|
424
|
+
*
|
|
425
|
+
* This is a provenance/labelling helper, deliberately NOT an admission gate: a
|
|
426
|
+
* different foreground session may continue a continuable attempt (see the
|
|
427
|
+
* module header). Callers that need to route a notification use it to decide
|
|
428
|
+
* which foreground a run belongs to, not to deny an operation.
|
|
429
|
+
*/
|
|
402
430
|
export function ownedByOrigin(meta: RunMeta, origin: RunCallbackOrigin | undefined): boolean {
|
|
403
431
|
const recorded = meta.callbackOrigin;
|
|
404
432
|
if (!origin?.sessionId || typeof origin.cwd !== "string") return false;
|
|
@@ -429,7 +457,42 @@ function isActiveAttempt(meta: RunMeta): boolean {
|
|
|
429
457
|
}
|
|
430
458
|
|
|
431
459
|
/**
|
|
432
|
-
*
|
|
460
|
+
* Terminal statuses whose saved conversation may be reopened by a new attempt.
|
|
461
|
+
* A stopped (`killed`) run is an interrupted execution, not a destroyed
|
|
462
|
+
* conversation; other terminal outcomes keep their existing refusal.
|
|
463
|
+
*/
|
|
464
|
+
const CONTINUABLE_STATUSES: ReadonlySet<RunStatus> = new Set(["completed", "killed"]);
|
|
465
|
+
|
|
466
|
+
/**
|
|
467
|
+
* A recorded writer that may still be appending to the conversation.
|
|
468
|
+
*
|
|
469
|
+
* A fresh launch opens a brand-new session and takes no lease, so a killed
|
|
470
|
+
* attempt can be recorded terminal while its child is still alive (for example
|
|
471
|
+
* SIGTERM is pending behind SIGSTOP). In that state no lease blocks the next
|
|
472
|
+
* writer. Check the prior attempt explicitly — the active-sibling scan excludes
|
|
473
|
+
* it — plus every same-conversation attempt that is not known to have exited.
|
|
474
|
+
* `completed`/`failed` attempts are omitted because their compact durable
|
|
475
|
+
* records drop the process-start identity, so a recycled pid could otherwise
|
|
476
|
+
* block an unrelated conversation. `recordedWriterLive` applies the same pid
|
|
477
|
+
* and start-token evidence the conversation lease uses.
|
|
478
|
+
*/
|
|
479
|
+
function findLiveConversationWriter(
|
|
480
|
+
prior: RunMeta,
|
|
481
|
+
others: readonly RunMeta[],
|
|
482
|
+
probe?: LeaseProbe,
|
|
483
|
+
): RunMeta | undefined {
|
|
484
|
+
const candidates = [
|
|
485
|
+
prior,
|
|
486
|
+
...others.filter((meta) => meta.sessionId === prior.sessionId
|
|
487
|
+
&& meta.id !== prior.id
|
|
488
|
+
&& meta.status !== "completed"
|
|
489
|
+
&& meta.status !== "failed"),
|
|
490
|
+
];
|
|
491
|
+
return candidates.find((meta) => recordedWriterLive(meta, probe));
|
|
492
|
+
}
|
|
493
|
+
|
|
494
|
+
/**
|
|
495
|
+
* Validate one continuable attempt for continuation and return the exact
|
|
433
496
|
* conversation plus frozen recipe to relaunch. Every refusal is fail-closed:
|
|
434
497
|
* nothing is spawned and no history is created or replaced.
|
|
435
498
|
*/
|
|
@@ -438,13 +501,19 @@ export function planContinuation(options: {
|
|
|
438
501
|
prior: RunMeta | undefined;
|
|
439
502
|
origin: RunCallbackOrigin | undefined;
|
|
440
503
|
others: readonly RunMeta[];
|
|
504
|
+
/** Process-identity seam for the recorded-writer check. */
|
|
505
|
+
probe?: LeaseProbe;
|
|
441
506
|
}): ContinuationPlan {
|
|
442
507
|
const { id, prior, origin, others } = options;
|
|
443
508
|
if (!prior) throw refusal(id, "no such run id.");
|
|
509
|
+
// The invoking foreground is still required, because the new attempt's
|
|
510
|
+
// completion callback and navigator entry are routed to it. It is not
|
|
511
|
+
// required to be the attempt's original owner: the saved session, workspace,
|
|
512
|
+
// and recipe are the thing being continued, and Pi sessions are shared
|
|
513
|
+
// on-disk state rather than a per-foreground boundary.
|
|
444
514
|
if (!origin?.sessionId) throw refusal(id, "the active foreground session identity is unavailable.");
|
|
445
|
-
if (!
|
|
446
|
-
|
|
447
|
-
throw refusal(id, `its status is ${prior.status}; only a completed run can be continued. Stop or launch a new run instead.`);
|
|
515
|
+
if (!CONTINUABLE_STATUSES.has(prior.status)) {
|
|
516
|
+
throw refusal(id, `its status is ${prior.status}; only a completed or stopped run can be continued. Stop a running attempt or launch a new run instead.`);
|
|
448
517
|
}
|
|
449
518
|
const recipe = prior.recipe;
|
|
450
519
|
if (!recipe || recipe.version !== 1) throw refusal(id, "it was launched before continuation support, so no launch recipe was saved.");
|
|
@@ -454,6 +523,14 @@ export function planContinuation(options: {
|
|
|
454
523
|
const active = others.find((meta) => meta.sessionId === prior.sessionId && meta.id !== prior.id && isActiveAttempt(meta));
|
|
455
524
|
if (active) throw refusal(id, `attempt ${active.id} is still active in the same conversation; stop it first.`);
|
|
456
525
|
|
|
526
|
+
// A killed record means stop was requested, not that the writer exited. A
|
|
527
|
+
// fresh launch has no lease, so this check is the only admission barrier
|
|
528
|
+
// while the prior child can still append to the saved conversation.
|
|
529
|
+
const writer = findLiveConversationWriter(prior, others, options.probe);
|
|
530
|
+
if (writer) {
|
|
531
|
+
throw refusal(id, `attempt ${writer.id} is still active and may still be writing the conversation (pid ${writer.pid}); wait for it to exit before continuing.`);
|
|
532
|
+
}
|
|
533
|
+
|
|
457
534
|
let workspaceIsDir = false;
|
|
458
535
|
try { workspaceIsDir = statSync(recipe.cwd).isDirectory(); } catch { workspaceIsDir = false; }
|
|
459
536
|
if (!workspaceIsDir) throw refusal(id, `its workspace ${recipe.cwd} is missing.`);
|
|
@@ -490,13 +567,13 @@ export function planRetentionRelease(options: {
|
|
|
490
567
|
}): RetentionRecord {
|
|
491
568
|
const { id, prior, origin, others } = options;
|
|
492
569
|
if (!prior) throw new ContinuationError(`Cannot release ${id}: no such run id.`);
|
|
570
|
+
// Release is the same on-disk convenience promise as continuation: any
|
|
571
|
+
// foreground that can name the attempt may drop optional retention. The
|
|
572
|
+
// invoking identity is still required, because the record keeps `releasedBy`
|
|
573
|
+
// and the decision must be attributable to a real foreground session.
|
|
493
574
|
if (!origin?.sessionId) throw new ContinuationError(`Cannot release ${id}: the active foreground session identity is unavailable.`);
|
|
494
|
-
if (!ownedByOrigin(prior, origin)) throw new ContinuationError(`Cannot release ${id}: only its owning foreground session may change retention.`);
|
|
495
575
|
const record = readRetention(prior.sessionId);
|
|
496
576
|
if (!record) throw new ContinuationError(`Cannot release ${id}: it was not launched with retain_session, so it has no retained conversation.`);
|
|
497
|
-
if (!record.ownerOrigin.sessionId || record.ownerOrigin.sessionId !== origin.sessionId || record.ownerOrigin.cwd !== origin.cwd) {
|
|
498
|
-
throw new ContinuationError(`Cannot release ${id}: only the foreground session that retained this conversation may release it.`);
|
|
499
|
-
}
|
|
500
577
|
if (record.releasedAt !== undefined) {
|
|
501
578
|
throw new ContinuationError(`Cannot release ${id}: its retention was already released at ${new Date(record.releasedAt).toISOString()}.`);
|
|
502
579
|
}
|
|
@@ -541,8 +618,14 @@ const ADMISSION_LOCK_WAIT_MS = 0;
|
|
|
541
618
|
const RELEASE_LOCK_WAIT_MS = 1_000;
|
|
542
619
|
const RETENTION_LOCK_WAIT_MS = 1_000;
|
|
543
620
|
|
|
621
|
+
/**
|
|
622
|
+
* Stable writer-lease root, independent of TMPDIR: a conversation is ordinary
|
|
623
|
+
* on-disk Pi state, so a foreground that restarts under a different temp root
|
|
624
|
+
* must still see the one writer slot. Retention records stay in the volatile
|
|
625
|
+
* registry as before.
|
|
626
|
+
*/
|
|
544
627
|
export function conversationLeaseDir(): string {
|
|
545
|
-
return join(
|
|
628
|
+
return join(durableSubagentRoot(), "conversation-leases");
|
|
546
629
|
}
|
|
547
630
|
|
|
548
631
|
function leasePathFor(sessionId: string): string {
|