@awebai/oats 0.69.24 → 0.70.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/bin/oats.mjs +56 -3
- package/docs/capabilities.md +356 -18
- package/docs/capability-manifest.schema.json +30 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
- package/docs/desktop-cli-api.md +75 -2
- package/docs/execution-targets.md +24 -1
- package/docs/implementation.md +20 -3
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +12 -0
- package/docs/trust-model.md +8 -1
- package/docs/upgrading.md +12 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +10 -1
- package/lib/core.mjs +298 -41
- 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/servers.mjs +10 -1
- package/lib/session-inspect.mjs +20 -75
- package/lib/session-providers.mjs +64 -17
- 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 };
|
|
@@ -1779,6 +1795,7 @@ async function readinessCmd() {
|
|
|
1779
1795
|
}
|
|
1780
1796
|
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
1797
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
1798
|
+
printSandboxAllowances(doc.sandbox, " ");
|
|
1782
1799
|
for (const n of doc.notes) console.log(` note: ${terminalText(n)}`);
|
|
1783
1800
|
return;
|
|
1784
1801
|
}
|
|
@@ -2638,6 +2655,15 @@ async function capabilityShowCmd(bail) {
|
|
|
2638
2655
|
}
|
|
2639
2656
|
for (const p of doc.sessionProviderProblems ?? []) console.log(` session provider problem: ${p.pointer} — ${safeText(p.message, 300)}`);
|
|
2640
2657
|
}
|
|
2658
|
+
if (doc.sandboxDomains !== undefined) {
|
|
2659
|
+
// As declared, made safe to print: the settings whose hosts a session provider's sandbox may be widened by.
|
|
2660
|
+
const { safeText } = await import("../lib/refused-text.mjs");
|
|
2661
|
+
// A `{ setting }` line: the setting's host. A `{ settingFile, urls }` line: the hosts in the file the setting names.
|
|
2662
|
+
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)" : ""}`
|
|
2663
|
+
: typeof l?.settingFile === "string" ? `the hosts in the file of setting ${safeText(l.settingFile, 80)} at ${safeText(String(l.urls ?? "?"), 200)}` : "?")) : null;
|
|
2664
|
+
console.log(` sandbox domains: ${lines ? lines.join("; ") : "(malformed — see sandbox domain problems)"}`);
|
|
2665
|
+
for (const p of doc.sandboxDomainProblems ?? []) console.log(` sandbox domain problem: ${safeText(p, 300)}`);
|
|
2666
|
+
}
|
|
2641
2667
|
for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
|
|
2642
2668
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
2643
2669
|
console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
|
|
@@ -2780,6 +2806,9 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
|
|
|
2780
2806
|
if (s && (verbose || s.status !== "current")) console.log(` ${soulDriftLine(s, a.name)}`);
|
|
2781
2807
|
const rows = ws?.drift.get(key) || [];
|
|
2782
2808
|
for (const r of rows) if (verbose || r.status !== "current") console.log(` ${driftLine(r)}`);
|
|
2809
|
+
// A provider home: the kernel runs its own copy of the home's modules; said when the home's
|
|
2810
|
+
// own record of them is not the receipt's, and always with --verbose.
|
|
2811
|
+
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
2812
|
}
|
|
2784
2813
|
for (const f of a.retireFailures || []) {
|
|
2785
2814
|
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 +2841,21 @@ function namingLine(naming) {
|
|
|
2812
2841
|
if (naming?.source === "numbered") return `numbered (${terminalText(naming.reason)}: ${terminalText(naming.message)})`;
|
|
2813
2842
|
return null;
|
|
2814
2843
|
}
|
|
2844
|
+
/** What a session provider may widen its harness's sandbox by (lib/sandbox-allowances.mjs), as a
|
|
2845
|
+
* spawn preview and readiness say it in text: each host with who asked for it, each path with its
|
|
2846
|
+
* reason, what is missing, what was left out or not read; or why there is none. Nothing for a
|
|
2847
|
+
* launch that has none (tmux). */
|
|
2848
|
+
function printSandboxAllowances(sb, indent = "") {
|
|
2849
|
+
if (!sb) return;
|
|
2850
|
+
if (sb.unavailable) { console.log(`${indent}sandbox allowances: none could be computed (${terminalText(sb.unavailable)})`); return; }
|
|
2851
|
+
if (sb.refused) { console.log(`${indent}sandbox allowances: refused (${sb.refused.code}): ${terminalText(sb.refused.message)}`); return; }
|
|
2852
|
+
console.log(`${indent}sandbox allowances:`);
|
|
2853
|
+
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` : ""})`);
|
|
2854
|
+
for (const w of sb.write) console.log(`${indent} path ${terminalText(w.path)} asked by the kernel (${terminalText(w.reason)})`);
|
|
2855
|
+
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)" : ""}`}`);
|
|
2856
|
+
for (const k of sb.skipped ?? []) console.log(`${indent} left out: ${terminalText(k.capability)}: ${terminalText(k.reason)}`);
|
|
2857
|
+
for (const u of sb.unread ?? []) console.log(`${indent} not read: ${terminalText(u.capability)} setting ${terminalText(u.setting)}: ${terminalText(u.reason)}`);
|
|
2858
|
+
}
|
|
2815
2859
|
/** A spawn preview's text: the local one, or a host's answer to a routed
|
|
2816
2860
|
* preview (`server`, its id), which this side printed the same way (#610). */
|
|
2817
2861
|
function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
@@ -2822,6 +2866,7 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
|
2822
2866
|
{ const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
|
|
2823
2867
|
if (r.background === true) console.log(`list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
|
|
2824
2868
|
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");
|
|
2869
|
+
printSandboxAllowances(r.sandbox);
|
|
2825
2870
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
2826
2871
|
}
|
|
2827
2872
|
async function spawnCmd() {
|
|
@@ -3659,7 +3704,7 @@ async function sessionCmd() {
|
|
|
3659
3704
|
// upgrade that runs (it holds the claim) the start is busy, not a partial upgrade: that one is
|
|
3660
3705
|
// left to the claim. A resume is always refused under the claim.
|
|
3661
3706
|
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)) };
|
|
3707
|
+
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
3708
|
if (args[1] === "restart") {
|
|
3664
3709
|
const grace = flag("stop-grace");
|
|
3665
3710
|
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 +4159,13 @@ async function capabilityCommand() {
|
|
|
4114
4159
|
try {
|
|
4115
4160
|
if (metaFile && existsSync(metaFile)) {
|
|
4116
4161
|
const meta = JSON.parse(readFileSync(metaFile, "utf8"));
|
|
4117
|
-
|
|
4118
|
-
|
|
4162
|
+
// A provider home's capabilities and their settings are its receipt's, never its own
|
|
4163
|
+
// record's, which its agent can write (lib/home-integrity.mjs).
|
|
4164
|
+
const { capabilityRuntimeOf, providerHomeTrust } = await import("../lib/home-integrity.mjs");
|
|
4165
|
+
const trust = providerHomeTrust(instanceHome);
|
|
4166
|
+
const rows = trust ? capabilityRuntimeOf(instanceHome, meta, trust) : meta.capabilities || [];
|
|
4167
|
+
activeIds = rows.map((c) => c.id);
|
|
4168
|
+
for (const c of rows) { capSettings[c.id] = c.settings || {}; capOrigins[c.id] = c.settingsOrigins || {}; }
|
|
4119
4169
|
// Workspace-model homes only (lead decision c3 Q2).
|
|
4120
4170
|
if (isCapturedHome(meta)) { const e = capturedHomeRefusal(instanceHome, "nothing was dispatched"); bail(e.code, e.message, e.details); }
|
|
4121
4171
|
if (!isWorkspaceHome(meta)) { const e = preWorkspaceHome(instanceHome, "nothing was dispatched"); bail(e.code, e.message); }
|
|
@@ -4208,6 +4258,9 @@ async function capabilityCommand() {
|
|
|
4208
4258
|
try { abs = capabilityExecutablePath(withDir, script); }
|
|
4209
4259
|
catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
|
|
4210
4260
|
if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
|
|
4261
|
+
// A provider home's own copy is never run: the kernel runs its copy of it (a guard; `dir` is that copy).
|
|
4262
|
+
const untrustedCopy = (await import("../lib/home-integrity.mjs")).moduleCopyProblemAt(dir);
|
|
4263
|
+
if (untrustedCopy) bail("E_CAPABILITY_BLOCKED", `oats ${cmd} ${sub} was not run: ${untrustedCopy}`);
|
|
4211
4264
|
// The soul the command acts for → { dir, cleanup, agent, id }: a home's recorded soul directory, or
|
|
4212
4265
|
// (operator dispatch) the soul read at its resolved commit, whose temporary copy goes when this
|
|
4213
4266
|
// process exits; with its name and stable id, as the soul's lifecycle hooks get them.
|
package/docs/capabilities.md
CHANGED
|
@@ -664,7 +664,14 @@ preview (only a preview-aware hook does, below); on a real run
|
|
|
664
664
|
backend the instance launches on, `tmux` or the name of a
|
|
665
665
|
[session provider](#session-providers-sessionproviders). A spawn that launches
|
|
666
666
|
nothing (`--no-launch`) sets it too: it is what a later start launches on. A
|
|
667
|
-
kernel without the feature sets none, which means tmux. A
|
|
667
|
+
kernel without the feature sets none, which means tmux. A launch hook also
|
|
668
|
+
gets `OATS_PREVIOUS_BACKEND`: the backend the home was last launched on, as the
|
|
669
|
+
kernel recorded it outside the home (its session receipt), `tmux` or a session
|
|
670
|
+
provider's name. It is absent at a home's first launch, and it is never read
|
|
671
|
+
from the home's own record, which the home's agent can write. A capability
|
|
672
|
+
that keeps files of its own in a home for one backend (a session provider's
|
|
673
|
+
settings file) removes them only when this variable names that backend, and
|
|
674
|
+
removes nothing when it is absent. A worktree hook also gets the tree
|
|
668
675
|
variables of [The worktree event](#the-worktree-event).
|
|
669
676
|
|
|
670
677
|
A spawn or launch hook also gets `OATS_HARNESS_EXECUTABLE`, for every harness
|
|
@@ -1036,7 +1043,10 @@ into the capture hooks and the capture service's unit. In the third case
|
|
|
1036
1043
|
|
|
1037
1044
|
`OATS_EVENT=upgrade` lets a staged destination package module adopt the state
|
|
1038
1045
|
of a stopped instance, for `oats instance upgrade` and `--undo`. It runs from
|
|
1039
|
-
the staged new copy
|
|
1046
|
+
the staged new copy (in a home on a session provider: from the kernel's own
|
|
1047
|
+
copy of the new module, see
|
|
1048
|
+
[What the kernel trusts in a provider home](#what-the-kernel-trusts-in-a-provider-home)),
|
|
1049
|
+
with the usual lifecycle environment plus:
|
|
1040
1050
|
|
|
1041
1051
|
- `OATS_UPGRADE_PHASE`: `plan` or `apply`;
|
|
1042
1052
|
- `OATS_META`: the old recorded `capabilityMeta[capability]`;
|
|
@@ -1045,7 +1055,10 @@ the staged new copy, with the usual lifecycle environment plus:
|
|
|
1045
1055
|
- `OATS_UPGRADE_TO`: JSON containing the locked destination entry;
|
|
1046
1056
|
- `OATS_UPGRADE_MODULE_DIR`: the module's final `<home>/.oats/modules/<cap>`
|
|
1047
1057
|
directory. Register host artifacts against this path, never the staging path,
|
|
1048
|
-
which is removed after the move.
|
|
1058
|
+
which is removed after the move. In a home on a session provider, in the
|
|
1059
|
+
`apply` phase, it is the kernel's copy of the module, which is where the
|
|
1060
|
+
module's code runs from then on (in `plan`, where nothing is registered,
|
|
1061
|
+
it is the home's path).
|
|
1049
1062
|
|
|
1050
1063
|
In `plan`, the hook is read-only. It prints `{"adopt":true}`, or
|
|
1051
1064
|
`{"adopt":false,"reason":"…","remedy":"…"}`. A module with recorded
|
|
@@ -1267,7 +1280,8 @@ claim and holds no scheduled wake. The board is in
|
|
|
1267
1280
|
**The Claude Code emitter.** For a Claude instance, oats.core's spawn and
|
|
1268
1281
|
launch hooks (`bin/oats-core.mjs`, preview-aware) write Claude Code hooks
|
|
1269
1282
|
into the home's project settings, `<home>/.claude/settings.json`. Each one
|
|
1270
|
-
runs `bin/claude-waiting.sh` from the home's module copy
|
|
1283
|
+
runs `bin/claude-waiting.sh` from the home's module copy (in a home on a
|
|
1284
|
+
session provider: from the kernel's copy of it), which calls
|
|
1271
1285
|
`oats instance waiting set|clear --producer oats.core`:
|
|
1272
1286
|
|
|
1273
1287
|
| Claude Code event | Matcher | Action |
|
|
@@ -1538,8 +1552,9 @@ home whose oats.core moves to it is upgraded rather than respawned. The
|
|
|
1538
1552
|
hook that runs is the destination's, so this covers homes spawned on any
|
|
1539
1553
|
earlier oats.core, with or without the emitter. oats.core records no
|
|
1540
1554
|
capability metadata, and its settings entries name the module copy's path,
|
|
1541
|
-
`.oats/modules/oats.core`, which an upgrade keeps
|
|
1542
|
-
|
|
1555
|
+
`.oats/modules/oats.core`, which an upgrade keeps (in a home on a session
|
|
1556
|
+
provider they name the kernel's copy, whose path an upgrade changes); the
|
|
1557
|
+
next start's launch hook rewrites them. So `plan` adopts a home whose recorded
|
|
1543
1558
|
`capabilityMeta["oats.core"]` is absent or `{}`, or a falsy value (`null`,
|
|
1544
1559
|
`false`, `0`, `""`), which the kernel passes in `OATS_META` as `{}`. It
|
|
1545
1560
|
refuses any other value as state it cannot vouch for, with the remedy
|
|
@@ -1707,7 +1722,8 @@ spawn's fail-closed hooks.
|
|
|
1707
1722
|
```
|
|
1708
1723
|
|
|
1709
1724
|
**Invocation.** The kernel runs the command's script with `node`, from the
|
|
1710
|
-
module directory. That is the home's module copy for `--home
|
|
1725
|
+
module directory. That is the home's module copy for `--home` (the kernel's
|
|
1726
|
+
copy of it, for a home on a session provider), or the
|
|
1711
1727
|
deployment's verified module store for `--soul`. The script must resolve inside
|
|
1712
1728
|
the module and be a regular file. The command's words after the script are
|
|
1713
1729
|
passed as arguments; no shell is involved.
|
|
@@ -1988,6 +2004,7 @@ claims, the refusals and the JSON answers. What an operator sees is in
|
|
|
1988
2004
|
"sessionProviders": {
|
|
1989
2005
|
"bb": {
|
|
1990
2006
|
"description": "Runs the agent as a bb thread",
|
|
2007
|
+
"wire": "1.3",
|
|
1991
2008
|
"harnesses": ["claude"],
|
|
1992
2009
|
"commands": { "launch": "session-launch", "inspect": "session-inspect", "input": "session-input",
|
|
1993
2010
|
"stop": "session-stop", "inspectMany": "session-inspect-many" }
|
|
@@ -2005,6 +2022,17 @@ claims, the refusals and the JSON answers. What an operator sees is in
|
|
|
2005
2022
|
- **`harnesses`** lists the harnesses the provider runs (1 to 16 names). A
|
|
2006
2023
|
spawn or a start on another one is refused `E_BACKEND_HARNESS`.
|
|
2007
2024
|
- **`description`** is optional: one line of at most 200 characters.
|
|
2025
|
+
- **`wire`** is the version of this wire the provider speaks: `"1.3"`. The
|
|
2026
|
+
kernel calls only a provider that declares its own version. One that
|
|
2027
|
+
declares another, or none (a provider written before the key: wire 1.2),
|
|
2028
|
+
is refused `E_BACKEND_WIRE`, naming both versions, before anything is
|
|
2029
|
+
created, recorded, stopped or started: a spawn, a start, a stop (an
|
|
2030
|
+
operator's and the host's) and an input alike. Its homes' sessions read
|
|
2031
|
+
unavailable, and are never recorded as stopped by a provider that was not
|
|
2032
|
+
asked. A retire of such a home cannot ask it either: it goes on when no
|
|
2033
|
+
process works in the home, with a warning that names the provider's own
|
|
2034
|
+
tooling. Every request carries the kernel's version (`"wire"`), so refuse
|
|
2035
|
+
a request that carries none or another, with the same code.
|
|
2008
2036
|
- No other key.
|
|
2009
2037
|
|
|
2010
2038
|
**Containment.** A malformed `sessionProviders` never refuses the capability:
|
|
@@ -2023,8 +2051,10 @@ the instance being spawned. Two of them declaring the same name is
|
|
|
2023
2051
|
|
|
2024
2052
|
### The call
|
|
2025
2053
|
|
|
2026
|
-
Every call runs the **
|
|
2027
|
-
|
|
2054
|
+
Every call runs the **kernel's copy** of the home's capability, kept outside
|
|
2055
|
+
the home, never the home's own copy
|
|
2056
|
+
([What the kernel trusts in a provider home](#what-the-kernel-trusts-in-a-provider-home)):
|
|
2057
|
+
`node <instances>/.oats-retirement/modules/…/<capability>/<script> <args>`. **Its working
|
|
2028
2058
|
directory is not the home** (it is the filesystem root): read the home from
|
|
2029
2059
|
the request (`input.home`) or `OATS_INSTANCE_HOME`, and leave
|
|
2030
2060
|
nothing of the call's own running in the home (the session's processes work
|
|
@@ -2038,7 +2068,7 @@ retires the home, and a provider's call must never be one of them.
|
|
|
2038
2068
|
`OATS_META`, `OATS_CLI_BIN` and the rest, with `OATS_EVENT=session` and
|
|
2039
2069
|
`OATS_BACKEND=<name>`.
|
|
2040
2070
|
- **stdin:** one JSON request,
|
|
2041
|
-
`{ "schemaVersion": 1, "phase": "session", "capability": "<id>", "provider": "<name>", "verb": "<verb>", "input": { … } }`.
|
|
2071
|
+
`{ "schemaVersion": 1, "wire": "1.3", "phase": "session", "capability": "<id>", "provider": "<name>", "verb": "<verb>", "input": { … } }`.
|
|
2042
2072
|
- **stdout:** exactly one JSON document of at most 1 MiB, the same five header
|
|
2043
2073
|
keys echoed, then `"ok": true, "result": { … }` or
|
|
2044
2074
|
`"ok": false, "error": { "code": "E_…", "message": "…" }`. No other key.
|
|
@@ -2088,7 +2118,10 @@ In:
|
|
|
2088
2118
|
"pathPrepend": ["/abs/home/.oats/bin"],
|
|
2089
2119
|
"args": ["--flag", "value"],
|
|
2090
2120
|
"promptFile": "/abs/home/TASK.md",
|
|
2091
|
-
"previous": null
|
|
2121
|
+
"previous": null,
|
|
2122
|
+
"sandbox": { "domains": [], "write": [ { "path": "/abs/deployment/.agents/events", "reason": "oats events" } ], "missing": [] },
|
|
2123
|
+
"trees": ["/abs/home/work", "/abs/home/.work-docs"],
|
|
2124
|
+
"protected": ["/abs/deployment/agents/dev/instances/.oats-retirement"] }
|
|
2092
2125
|
```
|
|
2093
2126
|
|
|
2094
2127
|
- `env` is every variable the launch sets, in the order a tmux launch sets
|
|
@@ -2115,6 +2148,35 @@ In:
|
|
|
2115
2148
|
just before, always (a restart's stop, once more for a home OATS had
|
|
2116
2149
|
stopped, and for a session you answered as gone too: an input that reached
|
|
2117
2150
|
it since may have had you restart it).
|
|
2151
|
+
- `sandbox` is what you may widen your harness's sandbox by, and nothing
|
|
2152
|
+
else: [Sandbox allowances](#sandbox-allowances-sandboxdomains-the-launch-inputs-sandbox).
|
|
2153
|
+
- `trees` is the home's trees, as absolute paths: `<home>/work`, always and
|
|
2154
|
+
first, then every extra tree of the home (`oats worktree add`). An extra
|
|
2155
|
+
tree is what Git itself says is one, a registered linked worktree of a
|
|
2156
|
+
repository outside the home, read with the kernel's own hardened Git;
|
|
2157
|
+
nothing in the home's `instance.json` names a tree. A provider that runs
|
|
2158
|
+
its harness in a sandbox keeps each tree's `.git` pointer, and the
|
|
2159
|
+
`config` and `hooks` of its Git directory and of its common directory,
|
|
2160
|
+
unwritable from the session, and refuses a launch it would sandbox without
|
|
2161
|
+
`trees`. One limit to know: the list of a repository's worktrees is in its
|
|
2162
|
+
common Git directory, so a session that can write there can take a tree
|
|
2163
|
+
off the list, and that tree is then no longer sent. `<home>/work` always
|
|
2164
|
+
is.
|
|
2165
|
+
- `protected` is the kernel's own state for this home, as absolute paths of
|
|
2166
|
+
directories: **paths a sandboxed agent must never write, and that a
|
|
2167
|
+
provider must not block reading or executing.** Today it is one entry,
|
|
2168
|
+
`<instances>/.oats-retirement/`, which holds the kernel's copies of the
|
|
2169
|
+
home's modules (what it runs, and what the home's hooks hand the harness
|
|
2170
|
+
to run), the receipts, the lifecycle claims and the records of provider
|
|
2171
|
+
commands in flight
|
|
2172
|
+
([What the kernel trusts in a provider home](#what-the-kernel-trusts-in-a-provider-home)).
|
|
2173
|
+
The kernel makes each directory before it asks you anything, so one that
|
|
2174
|
+
is missing is a fault, not a first launch. It is never derived from the
|
|
2175
|
+
home. A provider that runs its harness in a sandbox denies writes to each
|
|
2176
|
+
entry, leaves it readable and executable at the same path, and refuses a
|
|
2177
|
+
launch it would sandbox when `protected` is absent or an entry is not an
|
|
2178
|
+
absolute path of a directory. (`trees` and `protected` were added to wire
|
|
2179
|
+
1.3 without a new version only because no release carries a provider yet.)
|
|
2118
2180
|
|
|
2119
2181
|
**A provider that cannot carry an env entry, an argument or `unset`
|
|
2120
2182
|
refuses, naming it** (`E_BACKEND_LAUNCH_ENV`, `E_BACKEND_LAUNCH_ARG`). It
|
|
@@ -2162,7 +2224,8 @@ an `http` or `https` `url` of at most 2000, without credentials.
|
|
|
2162
2224
|
`{ "homes": [ { "home", "instance", "endpoint" } ] }`, at most 200. Out:
|
|
2163
2225
|
`{ "results": [ … ] }`, one per home in the same order, each an inspect
|
|
2164
2226
|
result or `{ "error": { "code", "message" } }`. `oats status` calls it once
|
|
2165
|
-
per group of homes that share the capability's module copy (same
|
|
2227
|
+
per group of homes that share the capability's module copy (the same
|
|
2228
|
+
source, as each home's receipt records it),
|
|
2166
2229
|
the provider and the settings; the call's environment is the group's first
|
|
2167
2230
|
home's. Each entry is judged as one `inspect` answer would be. A batch that
|
|
2168
2231
|
fails or is not one result per home, and an entry that is neither a result
|
|
@@ -2203,7 +2266,12 @@ started by a killed spawn is ever stopped.
|
|
|
2203
2266
|
### check (optional)
|
|
2204
2267
|
|
|
2205
2268
|
The provider's readiness. In: `{ "home": "/abs/home" | null, "soul": "<name>" | null, "settings": { … } }`:
|
|
2206
|
-
a home, or, before any home exists, a soul
|
|
2269
|
+
a home, or, before any home exists, a soul; and, before a launch,
|
|
2270
|
+
`"launch": { "harness", "yolo", "args", "sandbox", "trees", "protected" }`, the launch that is
|
|
2271
|
+
planned: the harness, yolo, the allowances, the trees and the protected paths as its launch input will
|
|
2272
|
+
carry them, and in `args` the launch configuration's own arguments. **The
|
|
2273
|
+
arguments a capability's hooks contribute are not in it**: the check runs
|
|
2274
|
+
before any hook, and those reach the launch input only. Out:
|
|
2207
2275
|
`{ "status": "ready" | "needs-configuration" | "authorization-required" | "unavailable", "problems": [ { "code", "message" } ], "warnings": [ { "code", "message" } ] }`
|
|
2208
2276
|
(`warnings` optional; no problem on `ready`). Say where a credential comes
|
|
2209
2277
|
from, never print it.
|
|
@@ -2212,11 +2280,281 @@ from, never print it.
|
|
|
2212
2280
|
binding check's answer has: for a home, its own backend's, required; for a
|
|
2213
2281
|
soul, each provider its capabilities offer, not required (the soul can
|
|
2214
2282
|
launch on tmux).
|
|
2215
|
-
- **The kernel asks it
|
|
2216
|
-
|
|
2217
|
-
|
|
2218
|
-
|
|
2219
|
-
|
|
2283
|
+
- **The kernel asks it before every launch, and before any hook runs** (a
|
|
2284
|
+
spawn's before its spawn hooks, a start's and a restart's before their
|
|
2285
|
+
launch hooks and before a restart's stop). A status other than `ready`
|
|
2286
|
+
refuses the launch: with the first problem's code when that is an
|
|
2287
|
+
`E_BACKEND_*` code, else `E_BACKEND_NOT_READY`, the message carrying your
|
|
2288
|
+
problems. A refused spawn runs no hook and leaves no home; a refused
|
|
2289
|
+
start or restart runs no hook and stops nothing. A check that fails or
|
|
2290
|
+
answers outside these words is not ready.
|
|
2291
|
+
|
|
2292
|
+
### What the kernel trusts in a provider home
|
|
2293
|
+
|
|
2294
|
+
A provider may run its harness in a sandbox that still lets the agent write
|
|
2295
|
+
its own home. The kernel that runs the home's hooks and your commands runs
|
|
2296
|
+
outside any sandbox, as the operator, while that agent runs. So, for a home
|
|
2297
|
+
on a session provider, **the kernel runs nothing that is in the home, and
|
|
2298
|
+
takes no capability setting from it**:
|
|
2299
|
+
|
|
2300
|
+
- **The kernel keeps its own copy of the home's modules, outside the home,**
|
|
2301
|
+
at `<instances>/.oats-retirement/modules/<hash of the home>/<store>/<capability>/`,
|
|
2302
|
+
beside the home's receipt. The spawn makes it from the copies it
|
|
2303
|
+
materialised, once, before it asks you anything and before any hook of
|
|
2304
|
+
the spawn runs. Every lifecycle hook
|
|
2305
|
+
and worktree hook, every one of your commands, every capability's
|
|
2306
|
+
readiness check and every command or operation dispatched in the home is
|
|
2307
|
+
run from that copy, and the home's manifests are read there. The copies
|
|
2308
|
+
under `<home>/.oats/modules/` stay where they are, for the agent and its
|
|
2309
|
+
harness (its skills, what the harness runs inside its sandbox). The kernel
|
|
2310
|
+
never runs them, and reads nothing it acts on from them, so nothing the agent does to them,
|
|
2311
|
+
at rest or while the kernel is running a command, changes what the kernel
|
|
2312
|
+
runs. (A copy in the home that is checked and then run can be exchanged
|
|
2313
|
+
between the two by the session that writes the home. That is why the
|
|
2314
|
+
kernel keeps a copy instead of checking the home's.)
|
|
2315
|
+
- **The receipt records the home's composition.** The home's receipt
|
|
2316
|
+
(`<instances>/.oats-retirement/baselines/`) carries `composition`: which
|
|
2317
|
+
store holds the kernel's copies, which modules the home has and where each
|
|
2318
|
+
came from, and the capability rows the spawn resolved from the deployment
|
|
2319
|
+
(each capability's settings, their origins, its level, and its hook
|
|
2320
|
+
commands, which name the kernel's copy).
|
|
2321
|
+
- **A capability's settings and hook commands are the receipt's.**
|
|
2322
|
+
`OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, which hooks a capability has and
|
|
2323
|
+
the command of each come from the receipt's rows, never from
|
|
2324
|
+
`instance.json` (`capabilityRuntime`, `capabilities`, `providers`, the
|
|
2325
|
+
settings recorded with each launch contribution) nor from a rollback
|
|
2326
|
+
marker. A capability the home's record adds is no capability of the
|
|
2327
|
+
home, at a launch, at a retire and at an upgrade alike.
|
|
2328
|
+
- **Retirement removes the kernel's copy** with the home, and so does the
|
|
2329
|
+
rollback of a spawn that fails. A home that is kept (a retire that could
|
|
2330
|
+
not finish, a quarantined spawn) keeps its copy, so that its cleanup can
|
|
2331
|
+
run. A spawn takes away whatever an earlier home left at its path, the
|
|
2332
|
+
receipt and the copies, before anything reads them.
|
|
2333
|
+
- **An upgrade** (`oats instance upgrade`) makes the kernel's copies for the
|
|
2334
|
+
upgraded home in a new store beside the old one, before any upgrade hook
|
|
2335
|
+
runs: each moved module from the upgrade's staged copy, once that is found
|
|
2336
|
+
to be the one the upgrade verified against the lock, and every other
|
|
2337
|
+
module from the kernel's own current copy. Each upgrade hook runs from the
|
|
2338
|
+
kernel's copy. The receipt is then written once, naming the new store and
|
|
2339
|
+
the new rows together, and keeping the pair it replaced as `previous`.
|
|
2340
|
+
**An upgrade that fails or is interrupted before that write leaves the old
|
|
2341
|
+
copy and the old capability rows, together**; after it, the new ones.
|
|
2342
|
+
There is no moment at which the rows name one version and the kernel runs
|
|
2343
|
+
another. A store is removed only once a move is complete, after the
|
|
2344
|
+
receipt's write: the one before the previous. A move that fails after
|
|
2345
|
+
that write and is rolled back puts the earlier receipt back whole, from
|
|
2346
|
+
the kernel's own memory of it and never from a copy kept in the home,
|
|
2347
|
+
with the stores it names still there.
|
|
2348
|
+
- **An undo** (`oats instance upgrade --undo`) writes the receipt once,
|
|
2349
|
+
naming the previous store and the previous rows again; the newer store is
|
|
2350
|
+
removed after that write. The hook an undo runs is the kernel's previous
|
|
2351
|
+
copy's. The home's own copies are restored from what the home kept, as
|
|
2352
|
+
for every home: they are the agent's. One previous move is kept, so one
|
|
2353
|
+
undo is possible.
|
|
2354
|
+
- **An upgrade that was interrupted is not resumed** for such a home: its
|
|
2355
|
+
journal is in the home, where the agent can write. The kernel's side is
|
|
2356
|
+
whole either way (the old pair, or the new one once the receipt was
|
|
2357
|
+
written); the home's own copies may be half moved, which
|
|
2358
|
+
`moduleCopy.homeCopy` on its status row then says. Such a home is not
|
|
2359
|
+
started again: the remedy is to retire it and spawn it again. The upgrade
|
|
2360
|
+
takes its module set and each module's source from the receipt: a module
|
|
2361
|
+
only the home's record names refuses it.
|
|
2362
|
+
- **When the kernel has no copy.** A home whose receipt has no
|
|
2363
|
+
`composition` (a kernel from before this spawned it), or whose kernel
|
|
2364
|
+
copy of a module is gone, runs nothing of that module. The call is
|
|
2365
|
+
refused with a sentence that names the module; a read (`oats session
|
|
2366
|
+
inspect`, a status row, the sweep's plan, readiness) shows the home
|
|
2367
|
+
**unavailable** (`E_SESSION_UNAVAILABLE`; `running: null`,
|
|
2368
|
+
`runtimeState: "unreachable"`), never stopped; a hook of that module that
|
|
2369
|
+
an event has, and that cannot run, counts as a failed required hook, so a
|
|
2370
|
+
retire names it and removes the home only with `--force`. The home's own
|
|
2371
|
+
copy is never run in its place. The remedy is to retire the instance and
|
|
2372
|
+
spawn it again: with `--force` for a home whose receipt has no
|
|
2373
|
+
`composition` (none of its retire hooks can be identified), and for one
|
|
2374
|
+
that lacks the kernel's copy of a capability that has a retire hook; a
|
|
2375
|
+
plain retire where that capability has none.
|
|
2376
|
+
- **What `oats status` and drift report.** The drift rows (`modules`) read
|
|
2377
|
+
the home's own record of which modules it holds, from where and at which
|
|
2378
|
+
version, as for every home. A provider home's status row also carries
|
|
2379
|
+
`moduleCopy`: that the kernel runs its own copy (`runs: "kernel-copy"`),
|
|
2380
|
+
and whether the home's record of its modules is the kernel's
|
|
2381
|
+
(`homeCopy: "same" | "differs"`, with the modules that differ). That
|
|
2382
|
+
compares records, not files: `oats readiness --home` compares the files
|
|
2383
|
+
(`kernelCopies.differing`). Both are added, optional keys
|
|
2384
|
+
([desktop-cli-api.md](desktop-cli-api.md)). After an upgrade both are the
|
|
2385
|
+
new version. After an upgrade that was interrupted between moving the
|
|
2386
|
+
home's copies and writing the receipt, drift can say `current` while the
|
|
2387
|
+
kernel still runs the earlier copy: `moduleCopy.homeCopy` then says
|
|
2388
|
+
`differs`, naming the modules.
|
|
2389
|
+
|
|
2390
|
+
Your own part, if you sandbox: **keep `<instances>/.oats-retirement/`
|
|
2391
|
+
unwritable from the session**, by the harness's shell and by its file tools
|
|
2392
|
+
alike, and **keep it readable, and its `modules/` executable**, from the
|
|
2393
|
+
session, at the same path: a hook records paths of its own files there for
|
|
2394
|
+
the harness to run (as `oats.core`'s launch hook hands Claude Code the
|
|
2395
|
+
script its hooks run), and the harness runs them inside the sandbox. The
|
|
2396
|
+
launch input names the directory in `protected` ([launch](#launch)). The
|
|
2397
|
+
directory holds the kernel's copies of the modules, the receipts (the
|
|
2398
|
+
composition above, the session's endpoint), the lifecycle claims and the
|
|
2399
|
+
kernel's records of provider commands in flight. A session that can write
|
|
2400
|
+
there can make the kernel run anything. The kernel cannot check this for
|
|
2401
|
+
you: it does not run your sandbox.
|
|
2402
|
+
|
|
2403
|
+
What this does not cover: other fields of `instance.json` still reach hooks
|
|
2404
|
+
and your commands (the recorded teams, the harness, the soul directory,
|
|
2405
|
+
`OATS_META`, and the recorded launch: its harness, its arguments and
|
|
2406
|
+
environment, and the launch arguments and environment names each
|
|
2407
|
+
capability's hooks contributed). Nothing here makes a provider's sandboxed
|
|
2408
|
+
mode a security boundary between an agent and the operator's account.
|
|
2409
|
+
|
|
2410
|
+
**For a capability's author.** In a provider home your hooks and commands
|
|
2411
|
+
run from the kernel's copy of your capability, not from
|
|
2412
|
+
`<home>/.oats/modules/<your capability>/`. Find the home by
|
|
2413
|
+
`OATS_INSTANCE_HOME`, never by your own location, and never write beside
|
|
2414
|
+
your own code: what your code writes belongs in the home. A file of your
|
|
2415
|
+
own that you find by your own location is the kernel's copy of it. When a
|
|
2416
|
+
hook hands such a path to the harness (as `oats.core`'s launch hook hands
|
|
2417
|
+
Claude Code the script its hooks run), the harness runs what the kernel
|
|
2418
|
+
keeps, which the agent cannot rewrite where the provider keeps that
|
|
2419
|
+
directory unwritable. The path changes at an upgrade (the copies move to a
|
|
2420
|
+
new store), so write it again at every launch, as a launch hook does.
|
|
2421
|
+
|
|
2422
|
+
A tmux home is unchanged, and why: its agent already runs unsandboxed as
|
|
2423
|
+
the operator, and can do directly whatever a module it rewrote could. Its
|
|
2424
|
+
receipt gains no key, the kernel keeps no copy of its modules, and they are
|
|
2425
|
+
run from the home as before.
|
|
2426
|
+
|
|
2427
|
+
Every Git the kernel runs over a provider home's trees, or over their
|
|
2428
|
+
repository, runs with the repository's hooks and its file monitor off
|
|
2429
|
+
(`-c core.fsmonitor=false -c core.hooksPath=/dev/null`): the reads and a
|
|
2430
|
+
retire, as for every home, and also the spawn's `git worktree add`, its
|
|
2431
|
+
rollback, and `oats worktree add` and `remove`.
|
|
2432
|
+
|
|
2433
|
+
### Sandbox allowances (`sandboxDomains`, the launch input's `sandbox`)
|
|
2434
|
+
|
|
2435
|
+
A provider may run its harness in a sandbox. What an instance needs from
|
|
2436
|
+
outside that sandbox is decided by the kernel, from the deployment's
|
|
2437
|
+
configuration, and handed to the provider with every launch:
|
|
2438
|
+
|
|
2439
|
+
```json
|
|
2440
|
+
"sandbox": { "domains": [ { "host": "app.example.org", "capability": "oats.aweb", "setting": "services" } ],
|
|
2441
|
+
"write": [ { "path": "/abs/deployment/.agents/events", "reason": "oats events" } ],
|
|
2442
|
+
"missing": [ { "capability": "oats.aweb", "setting": "services", "team": "ops:acme.example", "defaultTeam": false } ] }
|
|
2443
|
+
```
|
|
2444
|
+
|
|
2445
|
+
- **`domains`** are exact hosts (`host` or `host:port`, lower case; never a
|
|
2446
|
+
wildcard, a scheme or a path), each with the capability and the setting
|
|
2447
|
+
that asked for it. **Only the capability that fills the instance's
|
|
2448
|
+
messaging, knowledge or tasks slot can ask**, and only through its
|
|
2449
|
+
manifest:
|
|
2450
|
+
|
|
2451
|
+
```json
|
|
2452
|
+
"layer": "messaging",
|
|
2453
|
+
"sandboxDomains": [ { "setting": "services" }, { "setting": "registryHost", "optional": true } ]
|
|
2454
|
+
```
|
|
2455
|
+
|
|
2456
|
+
Each line names one of the capability's own settings. Its value is a URL
|
|
2457
|
+
(its host is taken), a bare host, or a map from team id to one of those,
|
|
2458
|
+
of which only the entries of the instance's own teams are read (the teams
|
|
2459
|
+
a spawn preview shows for the soul). A value that is set and gives no plain
|
|
2460
|
+
host refuses the launch, `E_BACKEND_SANDBOX_HOST`, naming the capability
|
|
2461
|
+
and the setting. So does the line on a capability that fills none of the
|
|
2462
|
+
three slots: it is never dropped. `"optional": true` says the session
|
|
2463
|
+
works without that host.
|
|
2464
|
+
|
|
2465
|
+
A line may instead name a file: `{ "settingFile": "<setting>", "urls":
|
|
2466
|
+
"<JSON pointer>" }`. The setting's value is the path of a JSON file of the
|
|
2467
|
+
deployment, and each string at the pointer (one segment may be `*`: every
|
|
2468
|
+
key, every element) that is a URL or a git remote (`git@host:path`) gives
|
|
2469
|
+
its host. The file is the deployment's own: inside the deployment, never
|
|
2470
|
+
inside an instance home or a path the allowances make writable, reached
|
|
2471
|
+
through no symbolic link anywhere along its path (otherwise
|
|
2472
|
+
`E_BACKEND_SANDBOX_HOST`); a regular file with one name (a file that has a
|
|
2473
|
+
second hard link when it is read is not read; keep the file where a
|
|
2474
|
+
session cannot link or write it) of at most 64 KiB, strict JSON, at most
|
|
2475
|
+
16 hosts. An absolute path may spell the deployment's own directory
|
|
2476
|
+
through a link; from the first place it enters the deployment, no link is
|
|
2477
|
+
allowed. A file that is missing or is none of that gives no host,
|
|
2478
|
+
is named in the answer and in readiness (`unread`), and the launch goes on.
|
|
2479
|
+
**A host of a general forge opens that whole forge to the agent**, not
|
|
2480
|
+
only the repository named: say so where you document your line.
|
|
2481
|
+
- **`write`** are exact absolute paths, the kernel's own, never a
|
|
2482
|
+
capability's: the deployment's events directory, where `oats instance
|
|
2483
|
+
attention` appends. The kernel creates each before your launch: an
|
|
2484
|
+
allowance on a path that does not exist does not let a sandboxed agent
|
|
2485
|
+
create it. Each is a real directory at exactly that path: one reached
|
|
2486
|
+
through a symbolic link refuses the launch (`E_BACKEND_SANDBOX_HOST`).
|
|
2487
|
+
- **`missing`** is always there, `[]` when nothing is missing: what a line
|
|
2488
|
+
names and the deployment's configuration does not hold. `team` is the id
|
|
2489
|
+
of a team of the instance with no entry in a map, or `null` for a setting
|
|
2490
|
+
with no value at all. `defaultTeam` is `true` on the row of the soul's
|
|
2491
|
+
default team and on a row with `team: null`, `false` on another team's.
|
|
2492
|
+
A row of an optional line carries `"optional": true`. The kernel adds no
|
|
2493
|
+
host for these and refuses nothing.
|
|
2494
|
+
|
|
2495
|
+
**Nothing else adds a host or a path:** not hook output, not an environment
|
|
2496
|
+
variable, not a launch argument, not a task. A setting given to one spawn
|
|
2497
|
+
(`oats spawn … --provider <capability> <setting>=…`) is such an argument: a
|
|
2498
|
+
spawn that gives a setting a `sandboxDomains` line names is refused
|
|
2499
|
+
(`E_BACKEND_SANDBOX_HOST`), so that no host comes from it and the next start
|
|
2500
|
+
does not quietly resolve another. The values come from the
|
|
2501
|
+
deployment's configuration as a spawn preview resolves it (the workspace,
|
|
2502
|
+
the deployment's own settings, the soul's payload), **never from a file in
|
|
2503
|
+
the instance home**, which a sandboxed agent can write.
|
|
2504
|
+
|
|
2505
|
+
**What the provider does with it** is its own rule, because only it knows
|
|
2506
|
+
whether it sandboxes this launch: widen the sandbox by exactly `domains` and
|
|
2507
|
+
`write`; **refuse a launch you would sandbox** when `missing` holds a row
|
|
2508
|
+
that is not optional and whose `defaultTeam` is `true` (the other rows are
|
|
2509
|
+
for your readiness: say what the agent cannot reach), or when `sandbox` is
|
|
2510
|
+
`{ "unavailable": "<why>" }`
|
|
2511
|
+
(below), with an `E_BACKEND_*` code; write nothing for a launch you do not
|
|
2512
|
+
sandbox. Answer those refusals in `check` too, which is handed the planned
|
|
2513
|
+
launch (`"launch": { "harness", "yolo", "args", "sandbox" }`, absent on a
|
|
2514
|
+
readiness read): the kernel asks it before any hook runs and before a
|
|
2515
|
+
restart stops anything.
|
|
2516
|
+
|
|
2517
|
+
**A start or a restart of an existing home** resolves the deployment's
|
|
2518
|
+
configuration again, for the home's soul, **without reaching any remote**:
|
|
2519
|
+
the workspace and each repository are read **as this host last read them**
|
|
2520
|
+
(the commits any `oats` command that reads the workspace last saw here, from
|
|
2521
|
+
this host's cache), and the deployment's own `oats-local.yaml` and lock as
|
|
2522
|
+
they are now. So a launch never waits on the network or fails with it; a
|
|
2523
|
+
setting a person or a setup command writes to `oats-local.yaml` reaches the
|
|
2524
|
+
home at its next launch; and a change committed to the workspace reaches it
|
|
2525
|
+
once a command on this host has read the workspace (`oats status`, a spawn
|
|
2526
|
+
preview). A soul disabled for spawning on
|
|
2527
|
+
this machine (`souls.disabled`) still has its homes' allowances. **Which
|
|
2528
|
+
deployment and which soul that is comes from where the home is, never from
|
|
2529
|
+
what is in it**: the deployment is the
|
|
2530
|
+
directory four levels above the home (`<deployment>/agents/<agent>/instances/<instance>`,
|
|
2531
|
+
as its real path) and must hold its own `oats-local.yaml`; the soul is the
|
|
2532
|
+
one the workspace offers whose agent directory is `<agent>`. The home's
|
|
2533
|
+
`instance.json` decides neither. Hosts are taken only for capabilities that
|
|
2534
|
+
are also the home's modules, as the home records them: that record can only
|
|
2535
|
+
leave a host of the deployment's list out, never add one. A slot's provider
|
|
2536
|
+
of the deployment that is not one of them adds none and is named (`skipped`,
|
|
2537
|
+
and a warning of the start). When
|
|
2538
|
+
the deployment's configuration cannot be resolved (a member repository that
|
|
2539
|
+
this host's cache does not hold, a soul the workspace no longer offers, two
|
|
2540
|
+
souls of the workspace that share the home's agent directory (the same bare
|
|
2541
|
+
name: rename one, or take one out of the workspace), a home whose real
|
|
2542
|
+
path is not under a deployment because its agents root is reached through a
|
|
2543
|
+
link), the launch input
|
|
2544
|
+
carries `"sandbox": { "unavailable": "<the cause>" }` in place of the three
|
|
2545
|
+
lists, and the kernel refuses nothing: a provider that would sandbox the
|
|
2546
|
+
session does.
|
|
2547
|
+
|
|
2548
|
+
`oats spawn --preview`, a start's and a restart's answer and `oats readiness
|
|
2549
|
+
--home` list each host with who asked for it and each path with its reason.
|
|
2550
|
+
A host taken from a map is listed with its team: a team the instance **may
|
|
2551
|
+
join** (one the deployment allows its soul), which is not to say it has
|
|
2552
|
+
joined it. The launch input carries no team.
|
|
2553
|
+
A tmux launch has no `sandbox`, and reads no `sandboxDomains`.
|
|
2554
|
+
|
|
2555
|
+
**A kernel from before session providers ignores `sandboxDomains`**: it
|
|
2556
|
+
neither refuses the manifest nor acts on the line. The line costs an older
|
|
2557
|
+
deployment nothing and gives it nothing.
|
|
2220
2558
|
|
|
2221
2559
|
### Requirements by backend (`requires[].backends`)
|
|
2222
2560
|
|