@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.
Files changed (38) hide show
  1. package/bin/oats.mjs +62 -6
  2. package/docs/capabilities.md +374 -18
  3. package/docs/capability-manifest.schema.json +30 -0
  4. package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
  5. package/docs/design/2026-11-21-human-ids-contract.md +342 -0
  6. package/docs/design/README.md +2 -0
  7. package/docs/desktop-cli-api.md +111 -4
  8. package/docs/execution-targets.md +24 -1
  9. package/docs/implementation.md +26 -3
  10. package/docs/release-notes/v0.70.0.md +155 -0
  11. package/docs/release-notes/v0.70.1.md +70 -0
  12. package/docs/schedules.md +42 -3
  13. package/docs/souls-and-instances.md +12 -0
  14. package/docs/trust-model.md +8 -1
  15. package/docs/upgrading.md +16 -5
  16. package/lib/automation-scope.mjs +1 -1
  17. package/lib/capability-show.mjs +10 -1
  18. package/lib/core.mjs +408 -66
  19. package/lib/home-integrity.mjs +329 -0
  20. package/lib/hook-env.mjs +2 -1
  21. package/lib/instance-events.mjs +32 -5
  22. package/lib/instance-git.mjs +9 -0
  23. package/lib/instance-inspect.mjs +64 -10
  24. package/lib/instance-listing.mjs +5 -1
  25. package/lib/instance-resolution.mjs +85 -2
  26. package/lib/instance-upgrade.mjs +170 -14
  27. package/lib/remote.mjs +33 -1
  28. package/lib/retire-admission.mjs +7 -0
  29. package/lib/sandbox-allowances.mjs +329 -0
  30. package/lib/schedule.mjs +6 -4
  31. package/lib/servers.mjs +10 -1
  32. package/lib/session-inspect.mjs +20 -75
  33. package/lib/session-providers.mjs +68 -19
  34. package/lib/session-receipt.mjs +93 -0
  35. package/lib/upgrade-state.mjs +6 -1
  36. package/lib/worktree-hooks.mjs +18 -2
  37. package/lib/worktree.mjs +21 -7
  38. 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
- activeIds = (meta.capabilities || []).map((c) => c.id);
4118
- for (const c of meta.capabilities || []) { capSettings[c.id] = c.settings || {}; capOrigins[c.id] = c.settingsOrigins || {}; }
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.