pi-better-subagents 0.26.1 → 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-dependencies.mjs +161 -0
- package/child-operations.ts +1109 -0
- package/child-ownership.ts +12 -1
- package/child-preflight.mjs +22 -0
- package/child-runtime.mjs +57 -0
- package/cleanup.ts +11 -2
- package/config.ts +8 -4
- package/docs/usage.md +44 -3
- package/extensions.mjs +1 -0
- package/finalization.ts +53 -8
- package/goal-provider.ts +42 -4
- package/index.ts +574 -25
- 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/task-runtime.mjs +2 -1
- package/worker-operations-host.ts +1226 -0
- package/worker-waits.ts +2549 -0
package/README.md
CHANGED
|
@@ -36,12 +36,29 @@ authorized, write the result, and return. Pending CI is a valid handoff, not a p
|
|
|
36
36
|
The hook refuses recognized `gh run watch`, `gh pr checks --watch`, and bundled
|
|
37
37
|
delivery-watcher commands through `bash` and `run_application`. Short status reads,
|
|
38
38
|
failed-log retrieval, and legitimate long local tests and builds remain allowed.
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
39
|
+
Workers retain ownership of their assigned validation. When Background Tasks is
|
|
40
|
+
loaded, default workers receive a guarded bridge to supervised local operations.
|
|
41
|
+
They launch a known long command with `bg_task_spawn`, continue independent work,
|
|
42
|
+
and call `wait_for_operations` when only the operation remains. The worker saves
|
|
43
|
+
the wait result and exits, releasing its capacity slot. Once the operation settles,
|
|
44
|
+
the same conversation resumes to read the evidence, acknowledge its interpretation,
|
|
45
|
+
and finish the assignment. A completed parked attempt does not complete the assignment.
|
|
46
|
+
|
|
47
|
+
When the guarded bridge is unavailable, workers hand back the exact command, cwd,
|
|
48
|
+
required environment variable names (never secret values), current evidence and
|
|
49
|
+
remaining validation. The coordinator runs the command through background tools
|
|
50
|
+
and inspects its terminal result. Shell polling and detachment are not substitutes.
|
|
51
|
+
|
|
52
|
+
Explicit tool exclusions and clean loadouts remain authoritative. The bridge does
|
|
53
|
+
not expand permissions: an operation must satisfy both the captured worker policy
|
|
54
|
+
and the current Background Tasks policy. Parking requires Pi SDK 0.82.1 or later,
|
|
55
|
+
a saved conversation, and a registered continuation adapter. If any prerequisite
|
|
56
|
+
cannot be proved, parking is refused or held with a reason.
|
|
57
|
+
|
|
58
|
+
The coordinator owns established command-only jobs and external delivery waits.
|
|
59
|
+
Use `watch_delivery` for supported merge observation. Recognized external watcher
|
|
60
|
+
commands remain refused in workers, including through their background bridge.
|
|
61
|
+
Command permissions and timeouts are unchanged.
|
|
45
62
|
|
|
46
63
|
## Install
|
|
47
64
|
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/** Declared child dependency closure. Reading a contract never initializes its extension. */
|
|
2
|
+
import { readFileSync, existsSync, statSync, realpathSync } from 'node:fs';
|
|
3
|
+
import { dirname, join, resolve, isAbsolute } from 'node:path';
|
|
4
|
+
import { createRequire } from 'node:module';
|
|
5
|
+
import { pathToFileURL, fileURLToPath } from 'node:url';
|
|
6
|
+
import { createHash } from 'node:crypto';
|
|
7
|
+
import { BUILTIN_PROVIDER_EXTENSIONS, providerOf } from './extensions.mjs';
|
|
8
|
+
|
|
9
|
+
export function packageRoot(path) {
|
|
10
|
+
let dir = statSync(path).isDirectory() ? path : dirname(path);
|
|
11
|
+
while (!existsSync(join(dir, 'package.json'))) {
|
|
12
|
+
const parent = dirname(dir);
|
|
13
|
+
if (parent === dir) return undefined;
|
|
14
|
+
dir = parent;
|
|
15
|
+
}
|
|
16
|
+
return realpathSync(dir);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Search the declaring package's dependencies first, then the caller's installed roots. */
|
|
20
|
+
export function installedPackage(name, roots) {
|
|
21
|
+
for (const root of roots.filter(Boolean)) {
|
|
22
|
+
let dir = root;
|
|
23
|
+
while (true) {
|
|
24
|
+
const candidate = join(dir, 'node_modules', name);
|
|
25
|
+
if (existsSync(join(candidate, 'package.json'))) return realpathSync(candidate);
|
|
26
|
+
const parent = dirname(dir);
|
|
27
|
+
if (parent === dir) break;
|
|
28
|
+
dir = parent;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export async function loadContract(path) {
|
|
34
|
+
// Use the host's TS loader, with fresh module state for every declaration read.
|
|
35
|
+
const sdkRequire = createRequire(fileURLToPath(import.meta.resolve('@earendil-works/pi-coding-agent')));
|
|
36
|
+
const { createJiti } = await import(pathToFileURL(sdkRequire.resolve('jiti')).href);
|
|
37
|
+
return createJiti(import.meta.url, { tryNative: false, fsCache: false, moduleCache: false })
|
|
38
|
+
.import(path, { default: true });
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function strings(value, label) {
|
|
42
|
+
if (!Array.isArray(value) || value.some(x => typeof x !== 'string' || !x.trim()))
|
|
43
|
+
throw new Error(`Invalid child declaration: ${label} must be an array of nonempty strings.`);
|
|
44
|
+
return value;
|
|
45
|
+
}
|
|
46
|
+
export function validateRequirements(value) {
|
|
47
|
+
if (!value || typeof value !== 'object') throw new Error('Invalid childRequirements result.');
|
|
48
|
+
strings(value.providers, 'providers');
|
|
49
|
+
if (!Array.isArray(value.modelGroups)) throw new Error('Invalid childRequirements modelGroups.');
|
|
50
|
+
for (const group of value.modelGroups) {
|
|
51
|
+
if (!group || typeof group.provider !== 'string' || !group.provider.trim()) throw new Error('Invalid model group provider.');
|
|
52
|
+
strings(group.ids, 'modelGroups.ids');
|
|
53
|
+
if (group.prefix !== undefined && (typeof group.prefix !== 'string' || !group.prefix)) throw new Error('Invalid model group prefix.');
|
|
54
|
+
if (!group.ids.length && !group.prefix) throw new Error('Empty child model group.');
|
|
55
|
+
}
|
|
56
|
+
return value;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export function fingerprint(path) {
|
|
60
|
+
return existsSync(path) ? createHash('sha256').update(readFileSync(path)).digest('hex') : null;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// Credential refresh and catalog caches are runtime state, not dependency configuration.
|
|
64
|
+
const CONFIG_INPUTS = ['settings.json', 'harness-settings.json', 'model-router.json', 'models.json'];
|
|
65
|
+
export function configSnapshot(directories) {
|
|
66
|
+
return directories.map(dir => ({ dir, files: CONFIG_INPUTS.map(name => ({ name, hash: fingerprint(join(dir, name)) })) }));
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export async function resolveChildClosure({ resolution, model, virtual = false, config = {}, resolvePath,
|
|
70
|
+
load = loadContract, configPaths = [] }) {
|
|
71
|
+
const result = { ...resolution, specs: [], reasons: { ...resolution.reasons }, paths: {}, declarations: [],
|
|
72
|
+
providers: [], modelGroups: [], fingerprints: configPaths.map(path => ({ path, hash: fingerprint(path) })) };
|
|
73
|
+
if (resolution.mode !== 'isolated') {
|
|
74
|
+
if (virtual) throw new Error(`Virtual model ${model} requires isolated mode with a declared supplier; ${resolution.mode} mode is unsupported.`);
|
|
75
|
+
return { ...result, specs: resolution.specs, paths: Object.fromEntries(resolution.specs.map(spec => {
|
|
76
|
+
const path = resolvePath(spec);
|
|
77
|
+
if (!path) throw new Error(`Child dependency ${spec} is not installed.`);
|
|
78
|
+
return [spec, path];
|
|
79
|
+
})) };
|
|
80
|
+
}
|
|
81
|
+
const providerMap = { ...BUILTIN_PROVIDER_EXTENSIONS, ...(config.providerExtensions ?? {}) };
|
|
82
|
+
const active = [], done = new Set();
|
|
83
|
+
let ownsVirtual = false;
|
|
84
|
+
const visit = async (spec, from) => {
|
|
85
|
+
const path = resolvePath(spec, from);
|
|
86
|
+
if (!path) throw new Error(`Child dependency ${spec}${from ? ` required by ${from}` : ''} is not installed.`);
|
|
87
|
+
const root = packageRoot(path);
|
|
88
|
+
const identity = root ?? realpathSync(path);
|
|
89
|
+
if (active.includes(identity)) throw new Error(`Child dependency cycle: ${[...active, identity].join(' -> ')}`);
|
|
90
|
+
if (done.has(identity)) return;
|
|
91
|
+
active.push(identity);
|
|
92
|
+
// Two packages may declare the same relative spec against different roots.
|
|
93
|
+
const key = result.paths[spec] && result.paths[spec] !== path ? path : spec;
|
|
94
|
+
result.specs.push(key); result.paths[key] = path;
|
|
95
|
+
if (root) {
|
|
96
|
+
const manifestPath = join(root, 'package.json');
|
|
97
|
+
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
|
|
98
|
+
result.fingerprints.push({ path: manifestPath, hash: fingerprint(manifestPath) });
|
|
99
|
+
const declaration = manifest.pi ?? {};
|
|
100
|
+
for (const dependency of strings(declaration.childDependencies ?? [], 'pi.childDependencies')) await visit(dependency, root);
|
|
101
|
+
if (declaration.childRequirements !== undefined) {
|
|
102
|
+
if (typeof declaration.childRequirements !== 'string' || isAbsolute(declaration.childRequirements)) throw new Error(`Invalid childRequirements path in ${root}`);
|
|
103
|
+
const entry = resolve(root, declaration.childRequirements);
|
|
104
|
+
if (!entry.startsWith(root + '/')) throw new Error(`childRequirements escapes ${root}`);
|
|
105
|
+
const fn = await load(entry);
|
|
106
|
+
if (typeof fn !== 'function') throw new Error(`childRequirements in ${root} has no default function.`);
|
|
107
|
+
const requirements = await fn({ model });
|
|
108
|
+
result.fingerprints.push({ path: entry, hash: fingerprint(entry) });
|
|
109
|
+
result.declarations.push({ entry, requirements: requirements ?? null });
|
|
110
|
+
if (requirements !== undefined) {
|
|
111
|
+
validateRequirements(requirements);
|
|
112
|
+
if ((resolution.reasons[spec] ?? []).includes(`provider:${providerOf(model)}`)) ownsVirtual = true;
|
|
113
|
+
result.providers.push(...requirements.providers);
|
|
114
|
+
result.modelGroups.push(...requirements.modelGroups);
|
|
115
|
+
for (const provider of requirements.providers) {
|
|
116
|
+
const mapped = providerMap[provider];
|
|
117
|
+
for (const supplier of typeof mapped === 'string' ? [mapped] : mapped ?? []) await visit(supplier, root);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
active.pop(); done.add(identity);
|
|
123
|
+
};
|
|
124
|
+
for (const spec of resolution.specs) await visit(spec);
|
|
125
|
+
if (virtual && !ownsVirtual) throw new Error(`Virtual model ${model} has no mapped supplier with a childRequirements contract for this selection.`);
|
|
126
|
+
result.providers = [...new Set(result.providers)];
|
|
127
|
+
return result;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Both passes start with declared roots; expanded specs retain their declaring context only inside a traversal. */
|
|
131
|
+
export async function resolveChildLaunch(options, trustedPaths = []) {
|
|
132
|
+
const resolution = await resolveChildClosure(options);
|
|
133
|
+
const fullResolution = await resolveChildClosure({ ...options, resolution: {
|
|
134
|
+
...options.resolution, specs: [...options.resolution.specs, ...new Set(trustedPaths)],
|
|
135
|
+
} });
|
|
136
|
+
return { resolution, fullResolution };
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Validate actual child registration, never the parent's catalog. Groups require one physical candidate. */
|
|
140
|
+
export async function checkChildPreflight(plan, { registry, tools, model }, load = loadContract) {
|
|
141
|
+
if (plan.configSnapshot && JSON.stringify(configSnapshot(plan.configSnapshot.map(item => item.dir))) !== JSON.stringify(plan.configSnapshot))
|
|
142
|
+
throw new Error('Child configuration drift: agent or project JSON configuration changed. Launch again.');
|
|
143
|
+
for (const item of plan.fingerprints) if (fingerprint(item.path) !== item.hash)
|
|
144
|
+
throw new Error(`Child configuration/declaration drift: ${item.path}. Launch again with current configuration.`);
|
|
145
|
+
for (const declaration of plan.declarations) {
|
|
146
|
+
const fn = await load(declaration.entry);
|
|
147
|
+
const current = await fn({ model: plan.model });
|
|
148
|
+
if (JSON.stringify(current ?? null) !== JSON.stringify(declaration.requirements))
|
|
149
|
+
throw new Error(`Child requirements changed: ${declaration.entry}. Launch again.`);
|
|
150
|
+
}
|
|
151
|
+
if (plan.model && (!model || `${model.provider}/${model.id}` !== plan.model)) throw new Error(`Selected child model ${plan.model} is missing or changed.`);
|
|
152
|
+
const available = registry.getAvailable();
|
|
153
|
+
if (plan.model && !available.some(m => `${m.provider}/${m.id}` === plan.model))
|
|
154
|
+
throw new Error(`Selected child model ${plan.model} is not available; check its provider and credentials.`);
|
|
155
|
+
for (const provider of plan.providers) if (!available.some(m => m.provider === provider && m.api !== 'pi-virtual'))
|
|
156
|
+
throw new Error(`Child requires available provider ${provider}; check its extension and credentials.`);
|
|
157
|
+
for (const group of plan.modelGroups) if (!available.some(m => m.provider === group.provider && m.api !== 'pi-virtual' &&
|
|
158
|
+
(group.ids.includes(m.id) || (group.prefix && m.id.startsWith(group.prefix)))))
|
|
159
|
+
throw new Error(`Child has no available candidate for ${group.provider}: ${group.ids.join(', ')}${group.prefix ? ` (prefix ${group.prefix})` : ''}. Check extension, models and credentials.`);
|
|
160
|
+
for (const tool of plan.tools) if (!tools.includes(tool)) throw new Error(`Child requested tool ${tool} is unavailable.`);
|
|
161
|
+
}
|