pi-better-subagents 0.35.0 → 0.37.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 +13 -11
- package/assignment-outcomes.ts +9 -6
- package/assignment-report.ts +103 -19
- package/batch.mjs +14 -5
- package/bin/recover-workspace.mjs +19 -0
- package/catalog-host-admission.ts +19 -3
- package/catalog-preferences.ts +1 -1
- package/catalog-resolver.ts +35 -1
- package/catalog-store.ts +27 -20
- package/child-apply-patch.ts +13 -0
- package/child-dependencies.mjs +25 -12
- package/child-operations.ts +80 -1
- package/child-preflight.mjs +8 -2
- package/child-process-list.ts +8 -0
- package/cleanup.ts +10 -2
- package/config.ts +53 -3
- package/continuation-authority.ts +3 -1
- package/continuation-runtime.ts +88 -0
- package/continuation.ts +4 -2
- package/docs/usage.md +92 -81
- package/extensions.mjs +11 -13
- package/failures.ts +10 -2
- package/finalization.ts +21 -1
- package/goal-provider.ts +44 -2
- package/health-observation.ts +43 -48
- package/index.ts +417 -155
- package/isolated-workspace.ts +557 -0
- package/launch-context.ts +23 -0
- package/launch-digest.mjs +6 -0
- package/list.mjs +2 -2
- package/log-cursor.ts +91 -15
- package/managed-launch-bootstrap.mjs +2 -2
- package/managed-launch-client.ts +28 -8
- package/managed-launch-host.ts +168 -15
- package/managed-launch-journal.mjs +1 -5
- package/managed-launch-port.ts +4 -0
- package/operation-bridge-types.ts +27 -2
- package/output-payload.ts +26 -12
- package/owned-exit.ts +12 -0
- package/package.json +4 -2
- package/parse.ts +57 -10
- package/permission-policy.ts +41 -8
- package/process-identity.d.mts +1 -0
- package/process-identity.mjs +29 -0
- package/registry.ts +77 -38
- package/retained-result.ts +65 -0
- package/runtime-client/artifacts/darwin-arm64.gz +0 -0
- package/runtime-client/artifacts/darwin-arm64.json +1 -1
- package/runtime-client/artifacts/darwin-x64.gz +0 -0
- package/runtime-client/artifacts/darwin-x64.json +1 -1
- package/runtime-client/artifacts/linux-arm64.gz +0 -0
- package/runtime-client/artifacts/linux-arm64.json +1 -1
- package/runtime-client/artifacts/linux-x64.gz +0 -0
- package/runtime-client/artifacts/linux-x64.json +1 -1
- package/runtime-client/src/runtime/client.mjs +30 -3
- package/runtime-client/src/runtime/root.mjs +5 -2
- package/runtime-client/src/runtime/work-client.mjs +150 -7
- package/session-selection.ts +2 -1
- package/session-store.ts +9 -0
- package/settings-page.ts +147 -108
- package/shared-callback-batcher.ts +11 -2
- package/shared-catalog.ts +29 -21
- package/shared-navigator-panels.ts +26 -4
- package/shared-navigator.ts +244 -40
- package/shared-operation-coordinator/assignment-inbox.mjs +118 -0
- package/shared-operation-coordinator/assignment-observation.mjs +43 -35
- package/shared-operation-coordinator/src/assignment-changes.ts +73 -0
- package/shared-operation-coordinator/src/assignment-outcomes.ts +2 -0
- package/shared-operation-coordinator/src/background-requests.ts +14 -3
- package/shared-operation-coordinator/src/discovery.ts +5 -3
- package/shared-operation-coordinator/src/operations.ts +50 -2
- package/shared-operation-coordinator/src/outbox.ts +9 -0
- package/shared-operation-coordinator/src/result-supervision.ts +12 -0
- package/shared-operation-coordinator/src/rows.ts +2 -0
- package/shared-operation-coordinator/src/schema.ts +40 -24
- package/shared-operation-coordinator/src/store.ts +40 -8
- package/shared-operation-coordinator/src/subagent-launch.ts +24 -1
- package/shared-operation-coordinator/src/types.ts +5 -1
- package/shared-sandbox-core.ts +1 -1
- package/shared-task-exec.ts +12 -1
- package/shared-task-process-identity.ts +126 -0
- package/shared-task-process-list.ts +8 -2
- package/shared-task-sandbox.ts +5 -3
- package/shared-task-tools.ts +8 -5
- package/shared-work-client.d.mts +10 -0
- package/shared-work-client.mjs +150 -7
- package/subagent-tools.ts +28 -34
- package/task-guard.ts +13 -1
- package/task-policy.ts +8 -2
- package/timing.ts +10 -1
- package/tools.ts +4 -7
- package/work-observation.ts +91 -17
- package/worker-operations-host.ts +12 -4
- package/worker-waits.ts +93 -34
- package/workspace-files.ts +114 -0
- package/workspace-scope.ts +6 -0
- package/worktree-feedback.ts +77 -0
package/README.md
CHANGED
|
@@ -31,7 +31,8 @@ The API is `runtime-client/src/runtime/client.mjs`, exporting `ensureRuntime`.
|
|
|
31
31
|
- Explicit tool allowlists for child sessions, and `skills` for prompt exposure: omit it to keep user-catalog discovery, pass `[]` for no skills, or pass absolute `SKILL.md` paths for exactly those. See [skill exposure](docs/usage.md#skill-exposure).
|
|
32
32
|
- Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
|
|
33
33
|
- Live background-work navigator for active runs.
|
|
34
|
-
-
|
|
34
|
+
- Git writers start in separate Clones by default. **Git workspace** in `/subagents settings` also offers Worktree. Results carry the working directory or a recoverable copy, including incomplete work. [Workspace recovery](docs/usage.md#git-workspaces)
|
|
35
|
+
- Harness-owned run timing: every run gets independent factual alerts for a tool call left open (5 min) and for no progress (10 min), plus a 60-minute hard timeout. Choose a duration or **No limit** under **Run timeout** in `/subagents settings`. Soft deadlines remain opt-in. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`, globally in `config.json` / `PI_SUBAGENT_*_MINUTES`, or in `/subagents settings`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-tool-wait-stuck).
|
|
35
36
|
|
|
36
37
|
Every single or batch launch automatically joins one shared supervision watcher in the
|
|
37
38
|
foreground Pi process. The last active run's exit or stop tears it down; a later
|
|
@@ -41,6 +42,8 @@ alerts retain supervision until their handoff is handled, so lost work is not si
|
|
|
41
42
|
|
|
42
43
|
## Worker Ownership
|
|
43
44
|
|
|
45
|
+
Every subagent follows the same contract for preserving work and delivering results to its parent. It applies to read-only investigations as well as tasks that create or change files. [Subagent lifecycle, preservation and delivery](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/adr/0007-subagent-lifecycle.md)
|
|
46
|
+
|
|
44
47
|
Every child launch, including clean, batch and unsandboxed launches, loads a Pi
|
|
45
48
|
hook that keeps external CI/PR monitoring with its coordinator. Workers finish
|
|
46
49
|
their assigned implementation or diagnosis, run focused checks, push only when
|
|
@@ -87,25 +90,24 @@ pi -e npm:pi-better-subagents
|
|
|
87
90
|
|
|
88
91
|
Sandboxing starts Off for fresh settings, including standalone subagents without published settings. Explicit saved profiles and session choices remain unchanged. Set `sandbox:true` for a confined launch; `sandbox:false` cannot bypass a human-enabled Subagents profile.
|
|
89
92
|
|
|
90
|
-
Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or newer. `/sandbox` controls the independent Subagents profile, which each launch freezes. Pi handles its own startup, authentication, and provider connection; task tools obey the selected file, command, and network permissions. Outside project defaults to Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). Confined children admit `read`, `write`, `edit`, and policy-permitted `bash` or guarded `run_application`, the guarded `apply_patch` (Codex patches that follow the file rules), and the
|
|
93
|
+
Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or newer. `/sandbox` controls the independent Subagents profile, which each launch freezes. Pi handles its own startup, authentication, and provider connection; task tools obey the selected file, command, and network permissions. Outside project defaults to Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). Confined children admit `read`, `write`, `edit`, and policy-permitted `bash` or guarded `run_application`, the guarded `apply_patch` (Codex patches that follow the file rules), and the selected extension tools with verified providers (defaults include `web_fetch` and `web_search`), which run outside the file rules. Other requested tools are reported as unavailable, with the reason. For direct applications without shell scripts, set Subagents → Sandbox On, Run applications On, Shell scripts Off, and Command time limit to 10 min in `/sandbox`, then press Ctrl+S. This is an explicit choice, not the default. New launches capture the policy; running children keep theirs. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox) for the runtime boundary and supported configurations.
|
|
91
94
|
|
|
92
95
|
## Delegation Modes
|
|
93
96
|
|
|
94
97
|
The user config sets `delegationMode` to `manual`, `adaptive` (default), or
|
|
95
98
|
`coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
|
|
96
|
-
for delegation mode, the concurrent-subagent cap (default 6),
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
99
|
+
for delegation mode, the concurrent-subagent cap (default 6), and Git workspace
|
|
100
|
+
(Clone or Worktree). Run timeout supports a duration or **No limit**. The
|
|
101
|
+
tool-wait alert (default 5 minutes) and no-progress alert (default 10 minutes)
|
|
102
|
+
have separate intervals. Enter `0` to turn an alert off. Skill exposure cycles between Discover automatically and No skill
|
|
100
103
|
catalog. The Selected skills row opens the same searchable checkbox picker used
|
|
101
104
|
by `/agents`: it lists loaded skills by name and description, Space toggles one,
|
|
102
105
|
Enter applies, and typing filters without dropping checked items. Saved paths
|
|
103
106
|
missing from discovery stay visible as unavailable and survive apply. Zero
|
|
104
107
|
checked applies No skill catalog, not discovery. Manual Add skill path remains
|
|
105
|
-
available. The
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
exposure as defaults, and Reset to defaults clears session overrides, including
|
|
108
|
+
available. The Skill exposure row shows where the current skill setting comes from. The session choice controls the next launch before Ctrl+S, and
|
|
109
|
+
edits persist across reloads. Ctrl+S saves delegation, workspace, timing, and skill
|
|
110
|
+
settings as defaults, and Reset to defaults clears session overrides, including
|
|
109
111
|
the skill list. Agents opens the same catalog as `/agents`; a definition that inherits
|
|
110
112
|
skill exposure shows whether the live value comes from this session, saved
|
|
111
113
|
config, or discovery, and an invalid draft is marked invalid rather than shown
|
|
@@ -194,7 +196,7 @@ The projection exposes an opaque semantic `revision`, readable `reason`, attempt
|
|
|
194
196
|
identity, process status, termination evidence and retained evidence references.
|
|
195
197
|
Compare revisions for equality; unchanged observations keep the same revision.
|
|
196
198
|
Unavailable or unsupported coordinator reads report Waiting with an unverified
|
|
197
|
-
reason. See the [projection contract](
|
|
199
|
+
reason. See the [projection contract](https://github.com/1aboveio/pi-better-harness/blob/main/docs/adr/0022-assignment-progress-projection.md).
|
|
198
200
|
|
|
199
201
|
- Repository: https://github.com/1aboveio/pi-better-harness
|
|
200
202
|
- Detailed notes: https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md
|
package/assignment-outcomes.ts
CHANGED
|
@@ -3,12 +3,12 @@ import { randomUUID } from "node:crypto";
|
|
|
3
3
|
import { isDeepStrictEqual } from "node:util";
|
|
4
4
|
import { join, relative, isAbsolute, dirname, resolve } from "node:path";
|
|
5
5
|
import { openSync, closeSync, fstatSync, readSync, realpathSync, constants } from "node:fs";
|
|
6
|
-
import { openStore, ownerDiff,
|
|
6
|
+
import { openStore, ownerDiff, type OwnerIdentity, type AssignmentOutcomeRecord } from "./shared-operation-coordinator/index.ts";
|
|
7
7
|
import type { RunMeta } from "./registry.ts";
|
|
8
8
|
import { processStartToken, readMeta } from "./registry.ts";
|
|
9
9
|
import type { PermissionSnapshot } from "./permission-policy.ts";
|
|
10
10
|
import { credentialFilePaths } from "./shared-sandbox-core.ts";
|
|
11
|
-
import { readAssignmentReport } from "./assignment-report.ts";
|
|
11
|
+
import { assignmentReportOutcomeReason, readAssignmentReport } from "./assignment-report.ts";
|
|
12
12
|
|
|
13
13
|
export const ASSIGNMENT_OUTCOMES_VERSION = 1;
|
|
14
14
|
const closedHosts = (globalThis as typeof globalThis & { __assignmentOutcomeClosedHosts?: Set<string> }).__assignmentOutcomeClosedHosts ??= new Set<string>();
|
|
@@ -93,9 +93,10 @@ export function commitAssignmentTerminal(meta: RunMeta, recoveryFailure = false)
|
|
|
93
93
|
: !invalidReport && waits.some((w) => w.acknowledgement?.disposition === "assignment-complete"));
|
|
94
94
|
try { return store.recordAssignmentOutcome({ ...binding, revision: 1,
|
|
95
95
|
outcome: complete ? "succeeded" : meta.status === "killed" ? "cancelled" : "failed",
|
|
96
|
-
reason: meta.failureReason || invalidReport || (meta.status === "completed" && report ? report
|
|
96
|
+
reason: (meta.failureReason || invalidReport || (meta.status === "completed" && report ? assignmentReportOutcomeReason(report) : complete ? "Assigned work and required interpretation are complete."
|
|
97
|
+
: meta.status === "completed" && meta.assignmentReportRejection ? `Assignment report rejected: ${meta.assignmentReportRejection.reason}`
|
|
97
98
|
: meta.status === "completed" ? "Assignment completion is unverified: the attempt exited without an evidence-backed completion decision. Inspect retained output and continue unfinished work or report a concrete blocker."
|
|
98
|
-
: `Assignment ended ${meta.status}; retained attempt evidence is available.`),
|
|
99
|
+
: `Assignment ended ${meta.status}; retained attempt evidence is available.`)).slice(0, 8192),
|
|
99
100
|
processUncertain: meta.status === "lost" || typeof meta.exitCode !== "number"
|
|
100
101
|
|| waits.some((w) => w.dependencies.some((d) => d.terminalRevision === 0)
|
|
101
102
|
|| store.listResumeClaims({ waitId: w.waitId, generation: w.generation, state: "published" }).length > 0),
|
|
@@ -106,10 +107,12 @@ export function commitAssignmentTerminal(meta: RunMeta, recoveryFailure = false)
|
|
|
106
107
|
}); } catch (error) {
|
|
107
108
|
// A competing finalizer may commit after our initial read. The store
|
|
108
109
|
// still refuses rewrites; return only the same captured binding's winner.
|
|
109
|
-
|
|
110
|
+
// Borrowed runtime stores use a different coordinator module's StoreError constructor.
|
|
111
|
+
if (error instanceof Error && error.name === "StoreError" && "code" in error
|
|
112
|
+
&& error.code === "validation" && error.message === "A terminal assignment cannot be rewritten or reopened.") {
|
|
110
113
|
const winner = store.getAssignmentOutcome(binding.assignmentId);
|
|
111
114
|
const current = readMeta(meta.id);
|
|
112
|
-
if (winner && winner.assignmentId === binding.assignmentId && ownerDiff(winner.owner, binding.owner) === "none"
|
|
115
|
+
if (winner && winner.assignmentId === binding.assignmentId && winner.revision === 1 && ownerDiff(winner.owner, binding.owner) === "none"
|
|
113
116
|
&& ownerDiff(winner.recipient, binding.recipient) === "none"
|
|
114
117
|
&& current?.assignment?.assignmentId === binding.assignmentId
|
|
115
118
|
&& ownerDiff(current.assignment.owner, binding.owner) === "none" && ownerDiff(current.assignment.recipient, binding.recipient) === "none"
|
package/assignment-report.ts
CHANGED
|
@@ -5,6 +5,8 @@ import { homedir } from "node:os";
|
|
|
5
5
|
import { runDir, writeMeta, type RunMeta } from "./registry.ts";
|
|
6
6
|
import { credentialFilePaths } from "./shared-sandbox-core.ts";
|
|
7
7
|
import type { PermissionSnapshot, PermissionProfile } from "./permission-policy.ts";
|
|
8
|
+
import { OperationBridgeError, redactSecret } from "./operation-bridge-types.ts";
|
|
9
|
+
import { requireText } from "./shared-operation-coordinator/src/validate.ts";
|
|
8
10
|
|
|
9
11
|
const hash = (bytes: string | Buffer) => createHash("sha256").update(bytes).digest("hex");
|
|
10
12
|
const inside = (root: string, path: string) => { const rel = relative(root, path); return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)); };
|
|
@@ -20,15 +22,62 @@ function retainedBytes(path: string, limit: number): Buffer {
|
|
|
20
22
|
}
|
|
21
23
|
export interface AssignmentReport {
|
|
22
24
|
version: 1; assignmentId: string; attemptId: string; requestDigest: string; status: "complete" | "incomplete"; reason: string;
|
|
23
|
-
|
|
25
|
+
remainingWork?: string[];
|
|
26
|
+
blocker?: { kind: "permission" | "external-input"; reason: string };
|
|
27
|
+
evidence: Array<{ path: string; digest: string; source: string; explanation: string; range?: { offset: number; bytes: number; sourceBytes: number } }>;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
interface ReportInput {
|
|
31
|
+
status: string; reason: string;
|
|
32
|
+
remaining_work?: string[];
|
|
33
|
+
blocker?: AssignmentReport["blocker"];
|
|
34
|
+
evidence: Array<{ path: string; explanation: string; offset?: number; max_bytes?: number }>;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export function assignmentReportOutcomeReason(report: AssignmentReport): string {
|
|
38
|
+
if (report.status === "complete") return report.reason;
|
|
39
|
+
return (`Assignment incomplete: ${report.reason}`
|
|
40
|
+
+ (report.blocker ? ` Blocked (${report.blocker.kind}): ${report.blocker.reason}.` : "")
|
|
41
|
+
+ (report.remainingWork ? ` Remaining work: ${report.remainingWork.join("; ")}.` : "")).slice(0, 8192);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function validateReportText(report: AssignmentReport): void {
|
|
45
|
+
requireText("report.reason", report.reason, 2048);
|
|
46
|
+
for (const item of report.remainingWork ?? []) requireText("report.remaining_work", item, 1024);
|
|
47
|
+
if (report.blocker) requireText("report.blocker.reason", report.blocker.reason, 1024);
|
|
48
|
+
for (const evidence of report.evidence) requireText("report.evidence.explanation", evidence.explanation, 1024);
|
|
49
|
+
requireText("report.outcome_reason", assignmentReportOutcomeReason(report), 8192);
|
|
24
50
|
}
|
|
25
51
|
|
|
26
52
|
/** Runs synchronously under the authenticated handler: no yield between authority and persistence. */
|
|
27
53
|
export function recordAssignmentReport(id: string, input: unknown, assertAuthority: () => RunMeta, current?: PermissionSnapshot) {
|
|
28
54
|
const meta = assertAuthority();
|
|
29
|
-
|
|
55
|
+
try { return retainAssignmentReport(id, input, meta, assertAuthority, current); }
|
|
56
|
+
catch (error) {
|
|
57
|
+
// Refused input is not a committed report: the same writer may correct it.
|
|
58
|
+
// Recheck the live writer before retaining even diagnostic metadata.
|
|
59
|
+
recordAssignmentReportRejection(error instanceof Error ? error.message : String(error), assertAuthority);
|
|
60
|
+
throw error;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Also used for authenticated bridge refusals that never enter the report handler. */
|
|
65
|
+
export function recordAssignmentReportRejection(reason: string, assertAuthority: () => RunMeta): void {
|
|
66
|
+
const latest = assertAuthority();
|
|
67
|
+
if (!latest.assignmentReport) writeMeta({ ...latest, assignmentReportRejection: {
|
|
68
|
+
reason: redactSecret(reason), rejectedAt: Date.now(),
|
|
69
|
+
} });
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function retainAssignmentReport(id: string, input: unknown, meta: RunMeta, assertAuthority: () => RunMeta, current?: PermissionSnapshot) {
|
|
73
|
+
const report = input as ReportInput;
|
|
30
74
|
if (!["complete", "incomplete"].includes(report.status) || !report.reason?.trim() || report.reason.length > 2048
|
|
31
75
|
|| !Array.isArray(report.evidence) || report.evidence.length < 1 || report.evidence.length > 4) throw new Error("Invalid assignment report.");
|
|
76
|
+
if (report.remaining_work !== undefined && (!Array.isArray(report.remaining_work) || report.remaining_work.length < 1 || report.remaining_work.length > 8
|
|
77
|
+
|| report.remaining_work.some((item) => typeof item !== "string" || !item.trim() || item.length > 1024))) throw new Error("Remaining work needs 1 to 8 bounded descriptions.");
|
|
78
|
+
if (report.blocker && (!["permission", "external-input"].includes(report.blocker.kind) || !report.blocker.reason?.trim()
|
|
79
|
+
|| report.blocker.reason.length > 1024)) throw new Error("A blocker needs its permission or external-input kind and a concrete reason.");
|
|
80
|
+
if (report.status === "complete" && (report.remaining_work || report.blocker)) throw new Error("A complete assignment cannot have remaining work or a blocker.");
|
|
32
81
|
const root = realpathSync(meta.cwd);
|
|
33
82
|
const directory = join(runDir(id), "assignment-report-v1");
|
|
34
83
|
const captured = (meta.operations?.policy.sandbox as { permissions?: Partial<PermissionProfile> } | null)?.permissions;
|
|
@@ -37,28 +86,23 @@ export function recordAssignmentReport(id: string, input: unknown, assertAuthori
|
|
|
37
86
|
if (policy?.enabled && policy.projectFiles !== "read" && policy.projectFiles !== "read-write") throw new Error("Current assignment evidence read permission refused.");
|
|
38
87
|
}
|
|
39
88
|
if (meta.operations?.policy.sandbox && !current?.permissions) throw new Error("Current assignment evidence read authority unavailable.");
|
|
40
|
-
|
|
89
|
+
// Keep the legacy digest for whole-file reports without the additive fields.
|
|
90
|
+
const request: unknown[] = [report.status, report.reason, report.evidence.map((e) => e.offset === undefined && e.max_bytes === undefined
|
|
91
|
+
? [e.path, e.explanation] : [e.path, e.explanation, e.offset ?? 0, e.max_bytes])];
|
|
92
|
+
if (report.remaining_work || report.blocker) request.push([report.remaining_work ?? null,
|
|
93
|
+
report.blocker ? [report.blocker.kind, report.blocker.reason] : null]);
|
|
94
|
+
const requestDigest = hash(JSON.stringify(request));
|
|
41
95
|
if (meta.assignmentReport) {
|
|
42
96
|
const accepted = readAssignmentReport(meta)!;
|
|
43
97
|
if (accepted.requestDigest !== requestDigest) throw new Error("Conflicting assignment report refused.");
|
|
44
98
|
return { reportId: meta.assignmentReport.digest, status: accepted.status, note: "Report retained. Assignment terminalization after exit and exact parent disposition remain separate." };
|
|
45
99
|
}
|
|
46
|
-
const snapshots = report.evidence.map((e) =>
|
|
47
|
-
if (!e.path || !e.explanation?.trim() || e.explanation.length > 1024) throw new Error("Evidence needs a bounded explanation.");
|
|
48
|
-
const source = realpathSync(resolve(root, e.path));
|
|
49
|
-
if (!inside(root, source) || credentialFilePaths(homedir()).some((p) => inside(p, source))) throw new Error("Foreign or credential assignment evidence refused.");
|
|
50
|
-
const fd = openSync(source, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
51
|
-
try {
|
|
52
|
-
const stat = fstatSync(fd);
|
|
53
|
-
if (!stat.isFile() || stat.size > 65536) throw new Error("Assignment evidence must be a file of at most 65536 bytes.");
|
|
54
|
-
const bytes = Buffer.alloc(stat.size);
|
|
55
|
-
if (readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length) throw new Error("Assignment evidence changed during capture.");
|
|
56
|
-
return { bytes, digest: hash(bytes), source, explanation: e.explanation };
|
|
57
|
-
} finally { closeSync(fd); }
|
|
58
|
-
});
|
|
100
|
+
const snapshots = report.evidence.map((e) => captureEvidence(root, e));
|
|
59
101
|
const retained: AssignmentReport = { version: 1, assignmentId: meta.assignment!.assignmentId, attemptId: id, requestDigest,
|
|
60
102
|
status: report.status as AssignmentReport["status"], reason: report.reason,
|
|
61
|
-
|
|
103
|
+
...(report.remaining_work ? { remainingWork: report.remaining_work } : {}), ...(report.blocker ? { blocker: report.blocker } : {}),
|
|
104
|
+
evidence: snapshots.map(({ digest, source, explanation, range }) => ({ path: join(directory, digest), digest, source, explanation, ...(range ? { range } : {}) })) };
|
|
105
|
+
validateReportText(retained);
|
|
62
106
|
const text = JSON.stringify(retained);
|
|
63
107
|
if (Buffer.byteLength(text) > 65536) throw new Error("Assignment report exceeds its retained metadata bound.");
|
|
64
108
|
const digest = hash(text);
|
|
@@ -71,11 +115,44 @@ export function recordAssignmentReport(id: string, input: unknown, assertAuthori
|
|
|
71
115
|
for (const snapshot of snapshots) writeFileSync(join(directory, snapshot.digest), snapshot.bytes, { mode: 0o600 });
|
|
72
116
|
const path = join(directory, `${digest}.json`);
|
|
73
117
|
writeFileSync(path, text, { mode: 0o600 });
|
|
74
|
-
|
|
118
|
+
const updated = { ...latest, assignmentReport: { version: 1 as const, assignmentId: retained.assignmentId, attemptId: id, digest, path } };
|
|
119
|
+
delete updated.assignmentReportRejection;
|
|
120
|
+
writeMeta(updated);
|
|
75
121
|
}
|
|
76
122
|
return { reportId: digest, status: report.status, note: "Report retained. Assignment terminalization after exit and exact parent disposition remain separate." };
|
|
77
123
|
}
|
|
78
124
|
|
|
125
|
+
function captureEvidence(root: string, e: ReportInput["evidence"][number]) {
|
|
126
|
+
try {
|
|
127
|
+
if (!e.path || !e.explanation?.trim() || e.explanation.length > 1024) throw new Error("Evidence needs a bounded explanation.");
|
|
128
|
+
const source = realpathSync(resolve(root, e.path));
|
|
129
|
+
if (credentialFilePaths(homedir()).some((p) => inside(p, source))) throw new Error("Foreign or credential assignment evidence refused.");
|
|
130
|
+
if (!inside(root, source)) throw new Error(`Foreign assignment evidence refused: the source must resolve inside the assigned workspace ${JSON.stringify(root)}. A sibling directory is outside this boundary. Use an existing workspace file or place the reportable artifact inside the workspace, then retry.`);
|
|
131
|
+
const fd = openSync(source, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
132
|
+
try {
|
|
133
|
+
const stat = fstatSync(fd);
|
|
134
|
+
if (!stat.isFile()) throw new Error(`Assignment evidence ${JSON.stringify(e.path)} must be a regular file.`);
|
|
135
|
+
const offset = e.offset ?? 0;
|
|
136
|
+
if (!Number.isSafeInteger(offset) || offset < 0 || offset > stat.size || (offset === stat.size && offset !== 0)
|
|
137
|
+
|| (e.offset !== undefined && e.max_bytes === undefined)
|
|
138
|
+
|| (e.max_bytes !== undefined && (!Number.isSafeInteger(e.max_bytes) || e.max_bytes < 1 || e.max_bytes > 65536))) {
|
|
139
|
+
throw new Error(`Invalid assignment evidence range for ${JSON.stringify(e.path)} (${stat.size} bytes). Use offset within the file and max_bytes from 1 through 65536.`);
|
|
140
|
+
}
|
|
141
|
+
if (e.max_bytes === undefined && stat.size > 65536) {
|
|
142
|
+
throw new Error(`Assignment evidence ${JSON.stringify(e.path)} is ${stat.size} bytes; the retained limit is 65536 bytes. Retry with offset and max_bytes (at most 65536) for the relevant excerpt.`);
|
|
143
|
+
}
|
|
144
|
+
const bytes = Buffer.alloc(Math.min(stat.size - offset, e.max_bytes ?? stat.size));
|
|
145
|
+
if (readSync(fd, bytes, 0, bytes.length, offset) !== bytes.length) throw new Error("Assignment evidence changed during capture.");
|
|
146
|
+
const after = fstatSync(fd);
|
|
147
|
+
if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) throw new Error("Assignment evidence changed during capture.");
|
|
148
|
+
return { bytes, digest: hash(bytes), source, explanation: e.explanation,
|
|
149
|
+
...(e.max_bytes === undefined ? {} : { range: { offset, bytes: bytes.length, sourceBytes: stat.size } }) };
|
|
150
|
+
} finally { closeSync(fd); }
|
|
151
|
+
} catch (error) {
|
|
152
|
+
throw new OperationBridgeError("tool-error", error instanceof Error ? error.message : String(error), true);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
79
156
|
export function readAssignmentReport(meta: RunMeta): AssignmentReport | null {
|
|
80
157
|
const ref = meta.assignmentReport;
|
|
81
158
|
if (!ref) return null;
|
|
@@ -86,7 +163,14 @@ export function readAssignmentReport(meta: RunMeta): AssignmentReport | null {
|
|
|
86
163
|
const report = JSON.parse(text) as AssignmentReport;
|
|
87
164
|
if (report.version !== 1 || report.assignmentId !== ref.assignmentId || report.attemptId !== meta.id) throw new Error("Foreign assignment report.");
|
|
88
165
|
for (const e of report.evidence) {
|
|
89
|
-
if (!/^[a-f0-9]{64}$/.test(e.digest) || e.path !== join(runDir(meta.id), "assignment-report-v1", e.digest)
|
|
166
|
+
if (!/^[a-f0-9]{64}$/.test(e.digest) || e.path !== join(runDir(meta.id), "assignment-report-v1", e.digest)) throw new Error("Retained assignment evidence changed.");
|
|
167
|
+
const bytes = retainedBytes(e.path, 65536);
|
|
168
|
+
if (hash(bytes) !== e.digest || (e.range && (!Number.isSafeInteger(e.range.offset) || e.range.offset < 0
|
|
169
|
+
|| !Number.isSafeInteger(e.range.sourceBytes) || e.range.sourceBytes < 0 || e.range.bytes !== bytes.length
|
|
170
|
+
|| e.range.offset + e.range.bytes > e.range.sourceBytes))) throw new Error("Retained assignment evidence changed.");
|
|
90
171
|
}
|
|
172
|
+
// Older accepted reports may contain prose the terminal store cannot retain.
|
|
173
|
+
// Treat those as unverified evidence rather than throwing during finalization.
|
|
174
|
+
validateReportText(report);
|
|
91
175
|
return report;
|
|
92
176
|
}
|
package/batch.mjs
CHANGED
|
@@ -94,13 +94,15 @@ export function mergeJobOptions(shared, job) {
|
|
|
94
94
|
cwd: job.cwd ?? shared?.cwd,
|
|
95
95
|
// Same semantics as subagent_spawn: shared and per-job values must reach
|
|
96
96
|
// spawnSubagentRun so batch jobs can request disposable clone workspaces.
|
|
97
|
+
isolation: job.isolation ?? shared?.isolation,
|
|
98
|
+
recover_in_clone: job.recover_in_clone,
|
|
97
99
|
git_clone_workspace: job.git_clone_workspace ?? shared?.git_clone_workspace,
|
|
98
100
|
approve: job.approve ?? shared?.approve,
|
|
99
101
|
allow_nested: job.allow_nested ?? shared?.allow_nested,
|
|
100
102
|
// Native session id selected for this JOB only. A shared value would make
|
|
101
103
|
// every job contend for the same conversation writer, so it is not inherited.
|
|
102
|
-
session_id: typeof job.session_id === "string" ? job.session_id : undefined,
|
|
103
|
-
session_name: typeof job.session_name === "string" ? job.session_name : undefined,
|
|
104
|
+
session_id: typeof job.session_id === "string" ? normalizeSessionSelector(job.session_id) : undefined,
|
|
105
|
+
session_name: typeof job.session_name === "string" ? normalizeSessionSelector(job.session_name) : undefined,
|
|
104
106
|
// Harness timing; an explicit null means "not set", so it falls through to shared.
|
|
105
107
|
deadline_minutes: job.deadline_minutes ?? shared?.deadline_minutes,
|
|
106
108
|
grace_minutes: job.grace_minutes ?? shared?.grace_minutes,
|
|
@@ -113,6 +115,11 @@ export function mergeJobOptions(shared, job) {
|
|
|
113
115
|
};
|
|
114
116
|
}
|
|
115
117
|
|
|
118
|
+
/** Keep nonblank selectors exact. Only a blank string is equivalent to omission. */
|
|
119
|
+
export function normalizeSessionSelector(value) {
|
|
120
|
+
return typeof value === "string" && value.trim() === "" ? undefined : value;
|
|
121
|
+
}
|
|
122
|
+
|
|
116
123
|
function catalogText(value) {
|
|
117
124
|
return typeof value === "string" && value.trim() !== "" ? value : undefined;
|
|
118
125
|
}
|
|
@@ -157,9 +164,11 @@ export function validateBatchPlan({ shared, jobs, onCapacity, config }) {
|
|
|
157
164
|
if (typeof job.prompt !== "string" || job.prompt.trim() === "") {
|
|
158
165
|
throw new Error(`job ${i + 1} is missing a non-empty prompt.`);
|
|
159
166
|
}
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
if (
|
|
167
|
+
const sessionId = normalizeSessionSelector(job.session_id);
|
|
168
|
+
const sessionName = normalizeSessionSelector(job.session_name);
|
|
169
|
+
if (sessionId !== undefined && sessionName !== undefined) throw new Error(`job ${i + 1}: pass either session_id or session_name, not both.`);
|
|
170
|
+
if (sessionName !== undefined && typeof sessionName !== "string") throw new Error(`job ${i + 1} session_name must be a non-empty name.`);
|
|
171
|
+
if (sessionId !== undefined && typeof sessionId !== "string") {
|
|
163
172
|
throw new Error(`job ${i + 1} session_id must be a non-empty native session id.`);
|
|
164
173
|
}
|
|
165
174
|
if (seenPrompts.has(job.prompt)) {
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Recover a separate checkout, including failed runs that cannot start another writer.
|
|
3
|
+
import { tsImport } from "tsx/esm/api";
|
|
4
|
+
const { readMeta } = await tsImport("../registry.ts", import.meta.url);
|
|
5
|
+
const { readRetainedResult } = await tsImport("../retained-result.ts", import.meta.url);
|
|
6
|
+
const { exportWorkspace } = await tsImport("../isolated-workspace.ts", import.meta.url);
|
|
7
|
+
try {
|
|
8
|
+
const [, , id, destination] = process.argv;
|
|
9
|
+
if (!/^sa_[a-z0-9]+_[a-z0-9]+$/i.test(id ?? "") || !destination || process.argv.length !== 4) {
|
|
10
|
+
throw new Error("Usage: pi-subagents-recover <run-id> <new-directory>");
|
|
11
|
+
}
|
|
12
|
+
const meta = readRetainedResult(id) ?? readMeta(id);
|
|
13
|
+
if (!meta?.recipe?.workspace) throw new Error("No saved Git workspace for " + id);
|
|
14
|
+
exportWorkspace(meta.recipe.workspace, id, destination);
|
|
15
|
+
console.log("Recovered " + id + " to " + destination);
|
|
16
|
+
} catch (error) {
|
|
17
|
+
console.error(error.message);
|
|
18
|
+
process.exitCode = 1;
|
|
19
|
+
}
|
|
@@ -2,7 +2,7 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
|
|
|
2
2
|
import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
3
3
|
import { join } from "node:path";
|
|
4
4
|
import { processStartToken } from "./registry.ts";
|
|
5
|
-
import { WorkClient } from "./shared-work-client.mjs";
|
|
5
|
+
import { WorkClient, connectWorkClient } from "./shared-work-client.mjs";
|
|
6
6
|
import type { AgentSessionOverrides } from "./agent-session-settings.ts";
|
|
7
7
|
import { overlayDigest } from "./catalog-overlay.ts";
|
|
8
8
|
export { overlayDigest } from "./catalog-overlay.ts";
|
|
@@ -13,6 +13,8 @@ export function createCatalogHostAdapter() {
|
|
|
13
13
|
let live: { client: WorkClient; path: string; key: string; authority: Record<string, unknown> } | undefined;
|
|
14
14
|
let timer: ReturnType<typeof setInterval> | undefined;
|
|
15
15
|
let epoch = 0;
|
|
16
|
+
let pendingConnection: AbortController | undefined;
|
|
17
|
+
let refreshPending = false;
|
|
16
18
|
let admitting: Promise<Record<string, unknown> | undefined> = Promise.resolve(undefined);
|
|
17
19
|
|
|
18
20
|
/** Fixed Pi adapter only. Never exposed as a tool or socket issuance operation. */
|
|
@@ -22,6 +24,7 @@ export function createCatalogHostAdapter() {
|
|
|
22
24
|
|
|
23
25
|
function closeCatalogHost() {
|
|
24
26
|
epoch++;
|
|
27
|
+
pendingConnection?.abort(); pendingConnection = undefined;
|
|
25
28
|
clearInterval(timer); timer = undefined;
|
|
26
29
|
if (live) { live.client.close(); rmSync(live.path, { force: true }); live = undefined; }
|
|
27
30
|
current = undefined;
|
|
@@ -48,9 +51,13 @@ export function createCatalogHostAdapter() {
|
|
|
48
51
|
const id = randomUUID(), secret = randomBytes(32).toString("hex"), generation = randomUUID();
|
|
49
52
|
const path = join(root, `${id}.json`), staging = join(root, `.${id}`);
|
|
50
53
|
const authority = { id, secret, generation, cwd: scope.cwd, sessionId: scope.sessionId, branchId: scope.branchId };
|
|
51
|
-
const
|
|
54
|
+
const controller = new AbortController();
|
|
55
|
+
pendingConnection = controller;
|
|
56
|
+
const client = await connectWorkClient(socketPath, agentDir, ["runtime-catalog-v1"], { signal: controller.signal })
|
|
57
|
+
.finally(() => { if (pendingConnection === controller) pendingConnection = undefined; });
|
|
52
58
|
try {
|
|
53
59
|
const hello = await client.ready;
|
|
60
|
+
if (epoch !== admittedEpoch || !current) throw new Error("catalog-host-revoked");
|
|
54
61
|
const pidStartTime = processStartToken(process.pid);
|
|
55
62
|
if (!pidStartTime) throw new Error("catalog-host-identity-unavailable");
|
|
56
63
|
writeFileSync(staging, JSON.stringify({ version: 1, id, generation, serverInstance: hello.instanceId, pid: process.pid, pidStartTime, secretHash: hash(secret), ...scope }), { mode: 0o600, flag: "wx" });
|
|
@@ -58,7 +65,16 @@ export function createCatalogHostAdapter() {
|
|
|
58
65
|
await client.request("runtime_bind_catalog_host", { authority });
|
|
59
66
|
if (epoch !== admittedEpoch || !current) throw new Error("catalog-host-revoked");
|
|
60
67
|
live = { client, path, key, authority };
|
|
61
|
-
if (!timer) {
|
|
68
|
+
if (!timer) {
|
|
69
|
+
timer = setInterval(() => {
|
|
70
|
+
if (refreshPending) return;
|
|
71
|
+
refreshPending = true;
|
|
72
|
+
void catalogHostAuthority(agentDir, current?.ctx.cwd ?? cwd, socketPath)
|
|
73
|
+
.catch(() => { if (epoch === admittedEpoch) closeCatalogHost(); })
|
|
74
|
+
.finally(() => { refreshPending = false; });
|
|
75
|
+
}, 500);
|
|
76
|
+
timer.unref();
|
|
77
|
+
}
|
|
62
78
|
return authority;
|
|
63
79
|
} catch (error) { client.close(); rmSync(path, { force: true }); rmSync(staging, { force: true }); throw error; }
|
|
64
80
|
}
|
package/catalog-preferences.ts
CHANGED
|
@@ -32,7 +32,7 @@ function preferences(id: string, value: unknown): CatalogPreference {
|
|
|
32
32
|
}
|
|
33
33
|
|
|
34
34
|
function snapshot(values: CatalogPreferences): { settings: CatalogPreferences; digest: string } {
|
|
35
|
-
const settings = Object.freeze(Object.fromEntries(Object.keys(values).sort().map(id => [id, values[id]])));
|
|
35
|
+
const settings = Object.freeze(Object.fromEntries(Object.keys(values).sort().map(id => [id, values[id]!])));
|
|
36
36
|
return { settings, digest: createHash("sha256").update(JSON.stringify(settings)).digest("hex") };
|
|
37
37
|
}
|
|
38
38
|
|
package/catalog-resolver.ts
CHANGED
|
@@ -218,7 +218,41 @@ export function inspectCatalog(snapshot: CatalogSnapshot, id: string): CatalogIn
|
|
|
218
218
|
};
|
|
219
219
|
}
|
|
220
220
|
|
|
221
|
+
export const catalogResolutionMetrics = { assemblies: 0, hits: 0 };
|
|
222
|
+
const resolutions = new Map<string, Resolution>();
|
|
223
|
+
|
|
224
|
+
function resolveCached(snapshot: CatalogSnapshot, id: string, compute: () => Resolution): Resolution {
|
|
225
|
+
const entry = findEntry(snapshot, id);
|
|
226
|
+
if (!entry) return compute();
|
|
227
|
+
const roleId = entry.definition?.kind === "agent" ? entry.definition.roleId : undefined;
|
|
228
|
+
const role = roleId ? findEntry(snapshot, roleId) : undefined;
|
|
229
|
+
// Only the selected definition, its base role and their own preferences contribute.
|
|
230
|
+
const key = JSON.stringify([{ ...entry, unused: undefined }, role && { ...role, unused: undefined }, snapshot.savedSettings?.[id], roleId && snapshot.savedSettings?.[roleId],
|
|
231
|
+
snapshot.sessionSettings?.[id], roleId && snapshot.sessionSettings?.[roleId]]);
|
|
232
|
+
const cached = resolutions.get(key);
|
|
233
|
+
if (cached) {
|
|
234
|
+
catalogResolutionMetrics.hits++;
|
|
235
|
+
const result = structuredClone(cached);
|
|
236
|
+
result.entry = entry;
|
|
237
|
+
if (result.effective) result.effective.snapshotDigest = snapshot.digest;
|
|
238
|
+
return result;
|
|
239
|
+
}
|
|
240
|
+
catalogResolutionMetrics.assemblies++;
|
|
241
|
+
const result = compute();
|
|
242
|
+
if (new TextEncoder().encode(key).byteLength <= 64 * 1024) resolutions.set(key, structuredClone(result));
|
|
243
|
+
if (resolutions.size > 512) resolutions.delete(resolutions.keys().next().value!);
|
|
244
|
+
return result;
|
|
245
|
+
}
|
|
246
|
+
|
|
221
247
|
function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
|
|
248
|
+
return resolveCached(snapshot, roleId, () => resolveRoleUncached(snapshot, roleId));
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
function resolveAgent(snapshot: CatalogSnapshot, agentId: string): Resolution {
|
|
252
|
+
return resolveCached(snapshot, agentId, () => resolveAgentUncached(snapshot, agentId));
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
function resolveRoleUncached(snapshot: CatalogSnapshot, roleId: string): Resolution {
|
|
222
256
|
const entry = findEntry(snapshot, roleId);
|
|
223
257
|
if (!entry || entry.kind !== "role") {
|
|
224
258
|
return {
|
|
@@ -268,7 +302,7 @@ function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
|
|
|
268
302
|
};
|
|
269
303
|
}
|
|
270
304
|
|
|
271
|
-
function
|
|
305
|
+
function resolveAgentUncached(snapshot: CatalogSnapshot, agentId: string): Resolution {
|
|
272
306
|
const entry = findEntry(snapshot, agentId);
|
|
273
307
|
if (!entry || entry.kind !== "agent") {
|
|
274
308
|
return {
|