@awebai/oats 0.69.24 → 0.70.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/bin/oats.mjs +62 -6
- package/docs/capabilities.md +374 -18
- package/docs/capability-manifest.schema.json +30 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
- package/docs/design/2026-11-21-human-ids-contract.md +342 -0
- package/docs/design/README.md +2 -0
- package/docs/desktop-cli-api.md +111 -4
- package/docs/execution-targets.md +24 -1
- package/docs/implementation.md +26 -3
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/release-notes/v0.70.1.md +70 -0
- package/docs/schedules.md +42 -3
- package/docs/souls-and-instances.md +12 -0
- package/docs/trust-model.md +8 -1
- package/docs/upgrading.md +16 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +10 -1
- package/lib/core.mjs +408 -66
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +2 -1
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +64 -10
- package/lib/instance-listing.mjs +5 -1
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/remote.mjs +33 -1
- package/lib/retire-admission.mjs +7 -0
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +6 -4
- package/lib/servers.mjs +10 -1
- package/lib/session-inspect.mjs +20 -75
- package/lib/session-providers.mjs +68 -19
- package/lib/session-receipt.mjs +93 -0
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package.json +1 -1
package/bin/oats.mjs
CHANGED
|
@@ -721,6 +721,19 @@ async function homeLiveTeams(home) {
|
|
|
721
721
|
return Array.isArray(teams) ? { teams, defaultTeam, teamsSource: source } : {};
|
|
722
722
|
}
|
|
723
723
|
|
|
724
|
+
/** For a start or a restart of a home on a session provider: the deployment's configuration its
|
|
725
|
+
* sandbox allowances are computed from (lib/instance-resolution.mjs homeSandboxSource), read now.
|
|
726
|
+
* → `{ sandboxSource }`, or `{}` for a tmux home, which reads nothing. (A `--resume` launches
|
|
727
|
+
* nothing on a provider, and reads nothing either.) The home's record only says whether to read:
|
|
728
|
+
* which deployment and which soul are the home's path's to say. */
|
|
729
|
+
async function homeSandboxSourceOf(home) {
|
|
730
|
+
let meta;
|
|
731
|
+
try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); } catch { return {}; }
|
|
732
|
+
const { recordsSessionProvider } = await import("../lib/session-providers.mjs");
|
|
733
|
+
if (!recordsSessionProvider(meta)) return {};
|
|
734
|
+
const { homeSandboxSource } = await import("../lib/instance-resolution.mjs");
|
|
735
|
+
return { sandboxSource: await homeSandboxSource(home, { remoteOptions: remoteOptionsFromEnv() }) };
|
|
736
|
+
}
|
|
724
737
|
/** For `--reselect-launch`: what the home's launch layers need of the workspace to say which keys of
|
|
725
738
|
* souls.launch name no soul (lib/core.mjs homeLaunchLayers), read only when they need it and the layers
|
|
726
739
|
* decide (`named`: --harness names the launch, so no key is consulted). A home the start will refuse
|
|
@@ -838,6 +851,9 @@ async function workspaceOperation(t, { bail, address, layer, opName }) {
|
|
|
838
851
|
const [script, ...rest] = spec.trim().split(/\s+/);
|
|
839
852
|
const abs = lp?.executable(script);
|
|
840
853
|
if (!abs) return bail("E_CAPABILITY_BROKEN", `${mod.name} ${op.command}: script not found (${script})`);
|
|
854
|
+
// A provider home's own copy is never run: the kernel runs its copy of it (a guard; `dir` is that copy).
|
|
855
|
+
const untrustedCopy = lp.dir ? (await import("../lib/home-integrity.mjs")).moduleCopyProblemAt(lp.dir) : null;
|
|
856
|
+
if (untrustedCopy) return bail("E_CAPABILITY_BLOCKED", `${address} was not run: ${untrustedCopy}`);
|
|
841
857
|
const settings = lp.settings;
|
|
842
858
|
const cwd = op.context === "home" ? t.home : t.deployment;
|
|
843
859
|
const env = { ...lp.env(mod.name, settings), OATS_OPERATION: address, OATS_CONTEXT: t.deployment, OATS_ROOT: t.agentsRoot, PI_AGENTS_ROOT: t.agentsRoot };
|
|
@@ -1137,7 +1153,7 @@ function launchConfigContext(bail) {
|
|
|
1137
1153
|
* a soul) would run under a selection, resolved against the current scoped
|
|
1138
1154
|
* configuration, preflighted, read-only; environment values withheld and
|
|
1139
1155
|
* the prompt named, never the TASK body. */
|
|
1140
|
-
function launchPreview(bail) {
|
|
1156
|
+
async function launchPreview(bail) {
|
|
1141
1157
|
for (const k of ["launch-config", "harness", "runtime", "model"]) if (flag(k) === true) bail("E_BAD_ARGS", `--${k} needs a value`);
|
|
1142
1158
|
const sel = { launchConfig: flag("launch-config"), harness: harnessFlag(), model: flag("model"), yolo: yoloFlag() };
|
|
1143
1159
|
if (sel.harness !== undefined && !LAUNCH_HARNESSES.includes(sel.harness)) bail("E_BAD_ARGS", `--harness must be one of ${LAUNCH_HARNESSES.join(", ")}`);
|
|
@@ -1174,8 +1190,11 @@ function launchPreview(bail) {
|
|
|
1174
1190
|
// The same planner a start uses, in preview mode: failed checks are listed, nothing is touched.
|
|
1175
1191
|
// Its checks read the pane a launch would run in, as a command that only reads can know it (a
|
|
1176
1192
|
// home's recorded session, a soul's session default; with no server running, not established).
|
|
1193
|
+
// A home on a session provider: its provider is asked what a start will ask it (its check, with
|
|
1194
|
+
// the launch that is planned), from the deployment's configuration as it is now, as a start reads it.
|
|
1195
|
+
const providerCheck = meta ? await homeSandboxSourceOf(home) : null;
|
|
1177
1196
|
let plan;
|
|
1178
|
-
try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }) }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
|
|
1197
|
+
try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }), providerCheck }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
|
|
1179
1198
|
const { recipe } = plan;
|
|
1180
1199
|
// A home on a session provider has no command line: its launch is handed to the provider as data
|
|
1181
1200
|
// (`command` and `argv` null, the executable's path null); its environment is listed by name.
|
|
@@ -1190,7 +1209,7 @@ async function launchConfigCmd() {
|
|
|
1190
1209
|
dropAmbientRoot();
|
|
1191
1210
|
const sub = args[1];
|
|
1192
1211
|
const usage = "usage: oats launch-config list [--dir <scope> | --home <abs> | --soul <name> [--dir <scope>] [--agents-root <abs>]] [--json] | set <name> --file <json> [--keep-env] [--dir <scope>] [--json] | remove <name> [--dir <scope>] [--json] | preview (--home <abs> | --soul <name> [--dir <scope>]) [--launch-config <name>|none] [--harness r] [--model m] [--yolo|--no-yolo] --json";
|
|
1193
|
-
if (sub === "preview") { launchPreview(bail); return; }
|
|
1212
|
+
if (sub === "preview") { await launchPreview(bail); return; }
|
|
1194
1213
|
if (!["list", "set", "remove"].includes(sub)) bail("E_USAGE", usage);
|
|
1195
1214
|
const { context: dir, selected } = sub === "list" ? launchConfigContext(bail) : { context: dirFlag(), selected: null };
|
|
1196
1215
|
// Lead decision 2: launch configurations are a HOST choice, declared in the
|
|
@@ -1779,6 +1798,7 @@ async function readinessCmd() {
|
|
|
1779
1798
|
}
|
|
1780
1799
|
if (doc.policy) console.log(` policy: child spawns ${doc.policy.childSpawns.allowed ? "allowed" : "disabled"} (${doc.policy.childSpawns.origin.kind}${doc.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${doc.policy.worktrees.allowed === null ? "unknown" : doc.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
|
|
1781
1800
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
1801
|
+
printSandboxAllowances(doc.sandbox, " ");
|
|
1782
1802
|
for (const n of doc.notes) console.log(` note: ${terminalText(n)}`);
|
|
1783
1803
|
return;
|
|
1784
1804
|
}
|
|
@@ -2638,6 +2658,15 @@ async function capabilityShowCmd(bail) {
|
|
|
2638
2658
|
}
|
|
2639
2659
|
for (const p of doc.sessionProviderProblems ?? []) console.log(` session provider problem: ${p.pointer} — ${safeText(p.message, 300)}`);
|
|
2640
2660
|
}
|
|
2661
|
+
if (doc.sandboxDomains !== undefined) {
|
|
2662
|
+
// As declared, made safe to print: the settings whose hosts a session provider's sandbox may be widened by.
|
|
2663
|
+
const { safeText } = await import("../lib/refused-text.mjs");
|
|
2664
|
+
// A `{ setting }` line: the setting's host. A `{ settingFile, urls }` line: the hosts in the file the setting names.
|
|
2665
|
+
const lines = Array.isArray(doc.sandboxDomains) ? doc.sandboxDomains.map((l) => (typeof l?.setting === "string" ? `the host of setting ${safeText(l.setting, 80)}${l.optional === true ? " (optional)" : ""}`
|
|
2666
|
+
: typeof l?.settingFile === "string" ? `the hosts in the file of setting ${safeText(l.settingFile, 80)} at ${safeText(String(l.urls ?? "?"), 200)}` : "?")) : null;
|
|
2667
|
+
console.log(` sandbox domains: ${lines ? lines.join("; ") : "(malformed — see sandbox domain problems)"}`);
|
|
2668
|
+
for (const p of doc.sandboxDomainProblems ?? []) console.log(` sandbox domain problem: ${safeText(p, 300)}`);
|
|
2669
|
+
}
|
|
2641
2670
|
for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
|
|
2642
2671
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
2643
2672
|
console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
|
|
@@ -2780,6 +2809,9 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
|
|
|
2780
2809
|
if (s && (verbose || s.status !== "current")) console.log(` ${soulDriftLine(s, a.name)}`);
|
|
2781
2810
|
const rows = ws?.drift.get(key) || [];
|
|
2782
2811
|
for (const r of rows) if (verbose || r.status !== "current") console.log(` ${driftLine(r)}`);
|
|
2812
|
+
// A provider home: the kernel runs its own copy of the home's modules; said when the home's
|
|
2813
|
+
// own record of them is not the receipt's, and always with --verbose.
|
|
2814
|
+
if (i.moduleCopy && (verbose || i.moduleCopy.homeCopy === "differs")) console.log(` modules: the kernel runs its own copy${i.moduleCopy.homeCopy === "differs" ? `; the home's own record differs${i.moduleCopy.differs.length ? ` for ${i.moduleCopy.differs.join(", ")}` : ""} (oats readiness --home ${i.home} compares the files)` : "; the home's record of them is the same"}`);
|
|
2783
2815
|
}
|
|
2784
2816
|
for (const f of a.retireFailures || []) {
|
|
2785
2817
|
console.log(` ! deferred retirement of ${f.instance} FAILED${f.completedAt ? ` at ${f.completedAt}` : ""}: ${f.error || (f.incomplete || []).join("; ") || "see result file"} — retry with \`oats retire ${f.instance}\``);
|
|
@@ -2812,6 +2844,21 @@ function namingLine(naming) {
|
|
|
2812
2844
|
if (naming?.source === "numbered") return `numbered (${terminalText(naming.reason)}: ${terminalText(naming.message)})`;
|
|
2813
2845
|
return null;
|
|
2814
2846
|
}
|
|
2847
|
+
/** What a session provider may widen its harness's sandbox by (lib/sandbox-allowances.mjs), as a
|
|
2848
|
+
* spawn preview and readiness say it in text: each host with who asked for it, each path with its
|
|
2849
|
+
* reason, what is missing, what was left out or not read; or why there is none. Nothing for a
|
|
2850
|
+
* launch that has none (tmux). */
|
|
2851
|
+
function printSandboxAllowances(sb, indent = "") {
|
|
2852
|
+
if (!sb) return;
|
|
2853
|
+
if (sb.unavailable) { console.log(`${indent}sandbox allowances: none could be computed (${terminalText(sb.unavailable)})`); return; }
|
|
2854
|
+
if (sb.refused) { console.log(`${indent}sandbox allowances: refused (${sb.refused.code}): ${terminalText(sb.refused.message)}`); return; }
|
|
2855
|
+
console.log(`${indent}sandbox allowances:`);
|
|
2856
|
+
for (const d of sb.domains) console.log(`${indent} host ${terminalText(d.host)} asked by ${terminalText(d.capability)} (setting ${terminalText(d.setting)}${d.team ? `, for team ${terminalText(d.team)}, which this instance may join` : ""})`);
|
|
2857
|
+
for (const w of sb.write) console.log(`${indent} path ${terminalText(w.path)} asked by the kernel (${terminalText(w.reason)})`);
|
|
2858
|
+
for (const m of sb.missing) console.log(`${indent} missing${m.optional ? " (optional)" : ""}: ${terminalText(m.capability)} setting ${terminalText(m.setting)}${m.team === null ? " has no value" : ` has no entry for team ${terminalText(m.team)}${m.defaultTeam ? " (the default team)" : ""}`}`);
|
|
2859
|
+
for (const k of sb.skipped ?? []) console.log(`${indent} left out: ${terminalText(k.capability)}: ${terminalText(k.reason)}`);
|
|
2860
|
+
for (const u of sb.unread ?? []) console.log(`${indent} not read: ${terminalText(u.capability)} setting ${terminalText(u.setting)}: ${terminalText(u.reason)}`);
|
|
2861
|
+
}
|
|
2815
2862
|
/** A spawn preview's text: the local one, or a host's answer to a routed
|
|
2816
2863
|
* preview (`server`, its id), which this side printed the same way (#610). */
|
|
2817
2864
|
function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
@@ -2822,6 +2869,7 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
|
2822
2869
|
{ const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
|
|
2823
2870
|
if (r.background === true) console.log(`list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
|
|
2824
2871
|
if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
|
|
2872
|
+
printSandboxAllowances(r.sandbox);
|
|
2825
2873
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
2826
2874
|
}
|
|
2827
2875
|
async function spawnCmd() {
|
|
@@ -3659,7 +3707,7 @@ async function sessionCmd() {
|
|
|
3659
3707
|
// upgrade that runs (it holds the claim) the start is busy, not a partial upgrade: that one is
|
|
3660
3708
|
// left to the claim. A resume is always refused under the claim.
|
|
3661
3709
|
if (!resume && !upgradeHoldsClaim(home)) assertNoPartialUpgrade(home);
|
|
3662
|
-
const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), ...(resume ? { resume: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
|
|
3710
|
+
const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(resume ? {} : await homeSandboxSourceOf(home)), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), ...(resume ? { resume: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
|
|
3663
3711
|
if (args[1] === "restart") {
|
|
3664
3712
|
const grace = flag("stop-grace");
|
|
3665
3713
|
if (grace !== undefined) { if (grace === true || !/^\d+$/.test(String(grace)) || Number(grace) < 1 || Number(grace) > 300) bad("--stop-grace needs a number of seconds (1..300) to wait for the harness after SIGTERM"); opts.stopGraceMs = Number(grace) * 1000; }
|
|
@@ -4114,8 +4162,13 @@ async function capabilityCommand() {
|
|
|
4114
4162
|
try {
|
|
4115
4163
|
if (metaFile && existsSync(metaFile)) {
|
|
4116
4164
|
const meta = JSON.parse(readFileSync(metaFile, "utf8"));
|
|
4117
|
-
|
|
4118
|
-
|
|
4165
|
+
// A provider home's capabilities and their settings are its receipt's, never its own
|
|
4166
|
+
// record's, which its agent can write (lib/home-integrity.mjs).
|
|
4167
|
+
const { capabilityRuntimeOf, providerHomeTrust } = await import("../lib/home-integrity.mjs");
|
|
4168
|
+
const trust = providerHomeTrust(instanceHome);
|
|
4169
|
+
const rows = trust ? capabilityRuntimeOf(instanceHome, meta, trust) : meta.capabilities || [];
|
|
4170
|
+
activeIds = rows.map((c) => c.id);
|
|
4171
|
+
for (const c of rows) { capSettings[c.id] = c.settings || {}; capOrigins[c.id] = c.settingsOrigins || {}; }
|
|
4119
4172
|
// Workspace-model homes only (lead decision c3 Q2).
|
|
4120
4173
|
if (isCapturedHome(meta)) { const e = capturedHomeRefusal(instanceHome, "nothing was dispatched"); bail(e.code, e.message, e.details); }
|
|
4121
4174
|
if (!isWorkspaceHome(meta)) { const e = preWorkspaceHome(instanceHome, "nothing was dispatched"); bail(e.code, e.message); }
|
|
@@ -4208,6 +4261,9 @@ async function capabilityCommand() {
|
|
|
4208
4261
|
try { abs = capabilityExecutablePath(withDir, script); }
|
|
4209
4262
|
catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
|
|
4210
4263
|
if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
|
|
4264
|
+
// A provider home's own copy is never run: the kernel runs its copy of it (a guard; `dir` is that copy).
|
|
4265
|
+
const untrustedCopy = (await import("../lib/home-integrity.mjs")).moduleCopyProblemAt(dir);
|
|
4266
|
+
if (untrustedCopy) bail("E_CAPABILITY_BLOCKED", `oats ${cmd} ${sub} was not run: ${untrustedCopy}`);
|
|
4211
4267
|
// The soul the command acts for → { dir, cleanup, agent, id }: a home's recorded soul directory, or
|
|
4212
4268
|
// (operator dispatch) the soul read at its resolved commit, whose temporary copy goes when this
|
|
4213
4269
|
// process exits; with its name and stable id, as the soul's lifecycle hooks get them.
|