pi-better-subagents 0.26.2 → 0.27.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 +23 -6
- package/child-operations.ts +1109 -0
- package/child-ownership.ts +12 -1
- package/cleanup.ts +11 -2
- package/docs/usage.md +44 -3
- package/finalization.ts +53 -8
- package/goal-provider.ts +42 -4
- package/index.ts +549 -14
- package/lifecycle.ts +26 -0
- package/navigator.mjs +13 -2
- package/navigator.ts +1 -0
- package/operation-bridge-types.ts +1109 -0
- package/package.json +2 -1
- package/park-checkpoint.ts +61 -0
- package/parse.ts +19 -1
- package/registry.ts +192 -6
- package/session-store.ts +3 -0
- package/shared-execution-policy.ts +2 -0
- package/shared-operation-coordinator/index.ts +113 -0
- package/shared-operation-coordinator/src/errors.ts +75 -0
- package/shared-operation-coordinator/src/operations.ts +376 -0
- package/shared-operation-coordinator/src/outbox.ts +431 -0
- package/shared-operation-coordinator/src/rows.ts +439 -0
- package/shared-operation-coordinator/src/schema.ts +244 -0
- package/shared-operation-coordinator/src/sqlite.ts +239 -0
- package/shared-operation-coordinator/src/store.ts +397 -0
- package/shared-operation-coordinator/src/types.ts +648 -0
- package/shared-operation-coordinator/src/validate.ts +239 -0
- package/shared-operation-coordinator/src/waits.ts +1378 -0
- package/shared-task-exec.ts +9 -0
- package/stop.ts +7 -3
- package/task-guard.ts +22 -3
- package/task-policy.ts +7 -0
- package/worker-operations-host.ts +1226 -0
- package/worker-waits.ts +2549 -0
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
// Generated from packages/operation-coordinator/src/validate.ts. Do not edit directly.
|
|
2
|
+
/**
|
|
3
|
+
* Input validation for the coordinator store.
|
|
4
|
+
*
|
|
5
|
+
* Two rules matter for durability:
|
|
6
|
+
*
|
|
7
|
+
* 1. Every stored string is bounded and single-line, so one record cannot grow
|
|
8
|
+
* without limit or smuggle structured data into a column that is read back.
|
|
9
|
+
* 2. Credential material is refused instead of stored. The API has no field for
|
|
10
|
+
* a token, key or environment value; these checks close the free-text and
|
|
11
|
+
* reference channels (`continuationNote`, `reason`, `summary`, `authorityRef`)
|
|
12
|
+
* that a caller could otherwise use to persist a secret.
|
|
13
|
+
*/
|
|
14
|
+
import { StoreError } from "./errors.ts";
|
|
15
|
+
import type { EvidenceKind, OwnerIdentity, OwnerKind } from "./types.ts";
|
|
16
|
+
|
|
17
|
+
const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,199}$/;
|
|
18
|
+
const ID_LIMITS: Record<string, number> = {
|
|
19
|
+
operationId: 200,
|
|
20
|
+
taskId: 200,
|
|
21
|
+
launchToken: 200,
|
|
22
|
+
sessionId: 200,
|
|
23
|
+
branchId: 200,
|
|
24
|
+
goalId: 200,
|
|
25
|
+
waitId: 200,
|
|
26
|
+
claimId: 200,
|
|
27
|
+
claimToken: 200,
|
|
28
|
+
eventId: 200,
|
|
29
|
+
attemptId: 200,
|
|
30
|
+
checkpointId: 200,
|
|
31
|
+
writerLeaseId: 200,
|
|
32
|
+
hostId: 200,
|
|
33
|
+
runnerId: 200,
|
|
34
|
+
processStartToken: 200,
|
|
35
|
+
ownerId: 200,
|
|
36
|
+
reservedCheckpointId: 200,
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
const TEXT_LIMITS = {
|
|
40
|
+
workspace: 1024,
|
|
41
|
+
ref: 1024,
|
|
42
|
+
continuationNote: 8192,
|
|
43
|
+
note: 8192,
|
|
44
|
+
reason: 1024,
|
|
45
|
+
summary: 2048,
|
|
46
|
+
observerField: 200,
|
|
47
|
+
authorityRef: 512,
|
|
48
|
+
intentRef: 200,
|
|
49
|
+
} as const;
|
|
50
|
+
|
|
51
|
+
const OWNER_KINDS: readonly OwnerKind[] = ["parent-session", "worker-conversation"];
|
|
52
|
+
const EVIDENCE_KINDS: readonly EvidenceKind[] = [
|
|
53
|
+
"terminal-record",
|
|
54
|
+
"log",
|
|
55
|
+
"summary",
|
|
56
|
+
"artifact",
|
|
57
|
+
];
|
|
58
|
+
const IDENTIFIER_FIELD = /^[A-Za-z][A-Za-z0-9._-]*$/;
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* High-confidence secret shapes. Prose notes stay usable; only material that is
|
|
62
|
+
* unambiguously a credential is refused, with the field named in the message.
|
|
63
|
+
*/
|
|
64
|
+
const SECRET_PATTERNS: ReadonlyArray<{ label: string; pattern: RegExp }> = [
|
|
65
|
+
{ label: "a private key block", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
|
|
66
|
+
{ label: "a bearer token", pattern: /\bbearer\s+[A-Za-z0-9._~+/=-]{8,}/i },
|
|
67
|
+
{ label: "a provider api key", pattern: /\b(?:sk|pk|rk|ghp|gho|ghs|ghu|xox[abp])[-_][A-Za-z0-9_-]{12,}/ },
|
|
68
|
+
{ label: "an AWS access key id", pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
|
|
69
|
+
{ label: "a JSON web token", pattern: /\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\./ },
|
|
70
|
+
{
|
|
71
|
+
label: "an environment assignment",
|
|
72
|
+
// Only a name that actually denotes credential material. Generic
|
|
73
|
+
// `NAME=value` evidence (for example `HTTP_STATUS=500`) stays usable.
|
|
74
|
+
pattern: /(?:^|[\s;,(])(?:[A-Za-z0-9]+[_-])*(?:SECRET|TOKEN|PASSWORD|PASSWD|PASSPHRASE|CREDENTIALS?|API[_-]?KEY|ACCESS[_-]?KEY|PRIVATE[_-]?KEY|AUTH[_-]?KEY|SIGNING[_-]?KEY|ENCRYPTION[_-]?KEY)(?:[_-][A-Za-z0-9]+)*\s*[=:]\s*\S+/i,
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
label: "a credential file path",
|
|
78
|
+
pattern: /(?:^|[\s"'(])(?:\.ssh\/id_[a-z0-9]+|\.aws\/credentials|\.netrc|\.npmrc|id_rsa\b)/i,
|
|
79
|
+
},
|
|
80
|
+
];
|
|
81
|
+
|
|
82
|
+
function fail(field: string, detail: string): never {
|
|
83
|
+
throw new StoreError("validation", `Invalid ${field}: ${detail}`);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
function assertPlainString(field: string, value: unknown, max: number): string {
|
|
87
|
+
if (typeof value !== "string") fail(field, "must be a string");
|
|
88
|
+
if (value.length === 0) fail(field, "must not be empty");
|
|
89
|
+
if (value.length > max) fail(field, `must be at most ${max} characters`);
|
|
90
|
+
// Control characters would corrupt a single-line record and hide content.
|
|
91
|
+
// eslint-disable-next-line no-control-regex
|
|
92
|
+
if (/[\u0000-\u001f\u007f]/.test(value)) fail(field, "must be a single line without control characters");
|
|
93
|
+
for (const { label, pattern } of SECRET_PATTERNS) {
|
|
94
|
+
if (pattern.test(value)) fail(field, `must not contain ${label}`);
|
|
95
|
+
}
|
|
96
|
+
return value;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Bounded, single-line, secret-free text for notes, reasons and summaries. */
|
|
100
|
+
export function requireText(field: string, value: unknown, max: number): string {
|
|
101
|
+
return assertPlainString(field, value, max).trim();
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Optional free text: `undefined`, `null` and `""` are recorded as null. */
|
|
105
|
+
export function optionalText(field: string, value: unknown, max: number): string | null {
|
|
106
|
+
if (value === undefined || value === null) return null;
|
|
107
|
+
if (typeof value !== "string") fail(field, "must be a string");
|
|
108
|
+
if (value.trim() === "") return null;
|
|
109
|
+
return assertPlainString(field, value, max).trim();
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Identifier-shaped string (session ids, task ids, operation ids, tokens). */
|
|
113
|
+
export function requireId(field: string, value: unknown): string {
|
|
114
|
+
if (typeof value !== "string") fail(field, "must be a string");
|
|
115
|
+
if (!ID_PATTERN.test(value)) {
|
|
116
|
+
fail(
|
|
117
|
+
field,
|
|
118
|
+
"must start with a letter or digit and contain only letters, digits, and . _ : @ / + -",
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
const max = ID_LIMITS[field] ?? 200;
|
|
122
|
+
if (value.length > max) fail(field, `must be at most ${max} characters`);
|
|
123
|
+
for (const { label, pattern } of SECRET_PATTERNS) {
|
|
124
|
+
if (pattern.test(value)) fail(field, `must not contain ${label}`);
|
|
125
|
+
}
|
|
126
|
+
return value;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** Filesystem path for the store itself. Absolute or `:memory:`. */
|
|
130
|
+
export function requirePath(field: string, value: unknown): string {
|
|
131
|
+
if (typeof value !== "string") fail(field, "must be a string");
|
|
132
|
+
if (value === ":memory:") return value;
|
|
133
|
+
if (value.trim() === "") fail(field, "must not be empty");
|
|
134
|
+
if (value.length > 4096) fail(field, "must be at most 4096 characters");
|
|
135
|
+
// eslint-disable-next-line no-control-regex
|
|
136
|
+
if (/[\u0000-\u001f\u007f]/.test(value)) fail(field, "must not contain control characters");
|
|
137
|
+
for (const { label, pattern } of SECRET_PATTERNS) {
|
|
138
|
+
if (pattern.test(value)) fail(field, `must not contain ${label}`);
|
|
139
|
+
}
|
|
140
|
+
return value;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** Workspace binding: an absolute path that may contain spaces. */
|
|
144
|
+
export function requireWorkspace(value: unknown): string {
|
|
145
|
+
const workspace = assertPlainString("owner.workspace", value, TEXT_LIMITS.workspace).trim();
|
|
146
|
+
if (!workspace.startsWith("/")) fail("owner.workspace", "must be an absolute path");
|
|
147
|
+
return workspace;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
export function requireOwnerKind(field: string, value: unknown): OwnerKind {
|
|
151
|
+
if (!OWNER_KINDS.includes(value as OwnerKind)) {
|
|
152
|
+
fail(field, `must be one of ${OWNER_KINDS.join(", ")}`);
|
|
153
|
+
}
|
|
154
|
+
return value as OwnerKind;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export function requireEvidenceKind(field: string, value: unknown): EvidenceKind {
|
|
158
|
+
if (!EVIDENCE_KINDS.includes(value as EvidenceKind)) {
|
|
159
|
+
fail(field, `must be one of ${EVIDENCE_KINDS.join(", ")}`);
|
|
160
|
+
}
|
|
161
|
+
return value as EvidenceKind;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
export function requireEnum<T extends string>(
|
|
165
|
+
field: string,
|
|
166
|
+
value: unknown,
|
|
167
|
+
allowed: readonly T[],
|
|
168
|
+
): T {
|
|
169
|
+
if (!allowed.includes(value as T)) fail(field, `must be one of ${allowed.join(", ")}`);
|
|
170
|
+
return value as T;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** Counters are non-negative integers; SQLite stores them as INTEGER. */
|
|
174
|
+
export function requireCounter(field: string, value: unknown): number {
|
|
175
|
+
if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
|
|
176
|
+
fail(field, "must be a non-negative integer");
|
|
177
|
+
}
|
|
178
|
+
return value;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
export function requireOptionalCounter(field: string, value: unknown): number | null {
|
|
182
|
+
if (value === undefined || value === null) return null;
|
|
183
|
+
return requireCounter(field, value);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
export function requireBoolean(field: string, value: unknown): boolean {
|
|
187
|
+
if (typeof value !== "boolean") fail(field, "must be a boolean");
|
|
188
|
+
return value;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** Normalised owner identity. Branch and goal bindings are optional but stable. */
|
|
192
|
+
export function normalizeOwner(field: string, value: unknown): OwnerIdentity {
|
|
193
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
194
|
+
fail(field, "must be an object");
|
|
195
|
+
}
|
|
196
|
+
const owner = value as Partial<OwnerIdentity>;
|
|
197
|
+
return {
|
|
198
|
+
kind: requireOwnerKind(`${field}.kind`, owner.kind),
|
|
199
|
+
sessionId: requireId(`${field}.sessionId`, owner.sessionId),
|
|
200
|
+
workspace: requireWorkspace(owner.workspace),
|
|
201
|
+
branchId: owner.branchId === undefined || owner.branchId === null
|
|
202
|
+
? null
|
|
203
|
+
: requireId(`${field}.branchId`, owner.branchId),
|
|
204
|
+
goalId: owner.goalId === undefined || owner.goalId === null
|
|
205
|
+
? null
|
|
206
|
+
: requireId(`${field}.goalId`, owner.goalId),
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
export function requireObserver(field: string, value: unknown): { kind: string; version: string } {
|
|
211
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
212
|
+
fail(field, "must be an object with kind and version");
|
|
213
|
+
}
|
|
214
|
+
const observer = value as { kind?: unknown; version?: unknown };
|
|
215
|
+
const kind = requireText(`${field}.kind`, observer.kind, TEXT_LIMITS.observerField);
|
|
216
|
+
const version = requireText(`${field}.version`, observer.version, TEXT_LIMITS.observerField);
|
|
217
|
+
if (!IDENTIFIER_FIELD.test(kind)) fail(`${field}.kind`, "must be an identifier");
|
|
218
|
+
return { kind, version };
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/** Stable key for one owner identity; the wait uniqueness index uses the same parts. */
|
|
222
|
+
export function ownerKey(owner: OwnerIdentity): string {
|
|
223
|
+
return [owner.kind, owner.sessionId, owner.branchId ?? ""].join("\u0000");
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** Full identity comparison, including the workspace and goal bindings. */
|
|
227
|
+
export function sameOwner(a: OwnerIdentity, b: OwnerIdentity): boolean {
|
|
228
|
+
return a.kind === b.kind
|
|
229
|
+
&& a.sessionId === b.sessionId
|
|
230
|
+
&& a.workspace === b.workspace
|
|
231
|
+
&& (a.branchId ?? null) === (b.branchId ?? null)
|
|
232
|
+
&& (a.goalId ?? null) === (b.goalId ?? null);
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
export function describeOwnerDiff(a: OwnerIdentity, b: OwnerIdentity): string {
|
|
236
|
+
const fields: Array<keyof OwnerIdentity> = ["kind", "sessionId", "workspace", "branchId", "goalId"];
|
|
237
|
+
const differing = fields.filter((field) => (a[field] ?? null) !== (b[field] ?? null));
|
|
238
|
+
return differing.length === 0 ? "none" : differing.join(", ");
|
|
239
|
+
}
|