@awebai/oats 0.70.0 → 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 +6 -3
- package/docs/capabilities.md +18 -0
- 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 +36 -2
- package/docs/implementation.md +12 -6
- package/docs/release-notes/v0.70.1.md +70 -0
- package/docs/schedules.md +42 -3
- package/docs/upgrading.md +9 -5
- package/lib/core.mjs +116 -31
- package/lib/schedule.mjs +6 -4
- package/lib/session-providers.mjs +7 -5
- package/package.json +1 -1
package/bin/oats.mjs
CHANGED
|
@@ -1153,7 +1153,7 @@ function launchConfigContext(bail) {
|
|
|
1153
1153
|
* a soul) would run under a selection, resolved against the current scoped
|
|
1154
1154
|
* configuration, preflighted, read-only; environment values withheld and
|
|
1155
1155
|
* the prompt named, never the TASK body. */
|
|
1156
|
-
function launchPreview(bail) {
|
|
1156
|
+
async function launchPreview(bail) {
|
|
1157
1157
|
for (const k of ["launch-config", "harness", "runtime", "model"]) if (flag(k) === true) bail("E_BAD_ARGS", `--${k} needs a value`);
|
|
1158
1158
|
const sel = { launchConfig: flag("launch-config"), harness: harnessFlag(), model: flag("model"), yolo: yoloFlag() };
|
|
1159
1159
|
if (sel.harness !== undefined && !LAUNCH_HARNESSES.includes(sel.harness)) bail("E_BAD_ARGS", `--harness must be one of ${LAUNCH_HARNESSES.join(", ")}`);
|
|
@@ -1190,8 +1190,11 @@ function launchPreview(bail) {
|
|
|
1190
1190
|
// The same planner a start uses, in preview mode: failed checks are listed, nothing is touched.
|
|
1191
1191
|
// Its checks read the pane a launch would run in, as a command that only reads can know it (a
|
|
1192
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;
|
|
1193
1196
|
let plan;
|
|
1194
|
-
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); }
|
|
1195
1198
|
const { recipe } = plan;
|
|
1196
1199
|
// A home on a session provider has no command line: its launch is handed to the provider as data
|
|
1197
1200
|
// (`command` and `argv` null, the executable's path null); its environment is listed by name.
|
|
@@ -1206,7 +1209,7 @@ async function launchConfigCmd() {
|
|
|
1206
1209
|
dropAmbientRoot();
|
|
1207
1210
|
const sub = args[1];
|
|
1208
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";
|
|
1209
|
-
if (sub === "preview") { launchPreview(bail); return; }
|
|
1212
|
+
if (sub === "preview") { await launchPreview(bail); return; }
|
|
1210
1213
|
if (!["list", "set", "remove"].includes(sub)) bail("E_USAGE", usage);
|
|
1211
1214
|
const { context: dir, selected } = sub === "list" ? launchConfigContext(bail) : { context: dirFlag(), selected: null };
|
|
1212
1215
|
// Lead decision 2: launch configurations are a HOST choice, declared in the
|
package/docs/capabilities.md
CHANGED
|
@@ -2288,6 +2288,24 @@ from, never print it.
|
|
|
2288
2288
|
problems. A refused spawn runs no hook and leaves no home; a refused
|
|
2289
2289
|
start or restart runs no hook and stops nothing. A check that fails or
|
|
2290
2290
|
answers outside these words is not ready.
|
|
2291
|
+
- **A preview asks it too, with the same planned launch**, so that a launch
|
|
2292
|
+
you would refuse does not read clean in its preview. `check` must only
|
|
2293
|
+
read, and must answer for a home that is not there:
|
|
2294
|
+
- A spawn's preview (`oats spawn --preview`) hands you the home's
|
|
2295
|
+
**planned path, which does not exist yet**, `trees` with its one planned
|
|
2296
|
+
tree and `protected` by name, none of them made. Treat an absent home
|
|
2297
|
+
and absent files as absent, not as an error. Your environment is the
|
|
2298
|
+
spawn's too; `OATS_SOUL` and `OATS_LEVEL` may name directories that are
|
|
2299
|
+
not there yet. Your script then runs from
|
|
2300
|
+
your package's tree in the deployment's module store, as it does for
|
|
2301
|
+
`oats readiness --soul`, not from a home's copy. A refusal fails the
|
|
2302
|
+
preview with the code the spawn would be refused with, and nothing is
|
|
2303
|
+
created. You are given what is left of the preview's budget, and never
|
|
2304
|
+
more than the spawn gives its check. A provider that lives in a member module, which runs only from
|
|
2305
|
+
a spawned home, is not asked: the preview says so in its `warnings`.
|
|
2306
|
+
- A launch's preview (`oats launch-config preview --home`) hands you the
|
|
2307
|
+
home as a start would. A refusal is a failed `backend` item in its
|
|
2308
|
+
`preflight`.
|
|
2291
2309
|
|
|
2292
2310
|
### What the kernel trusts in a provider home
|
|
2293
2311
|
|
|
@@ -0,0 +1,342 @@
|
|
|
1
|
+
# Human IDs: the contract between aweb's primitives and OATS
|
|
2
|
+
|
|
3
|
+
**Status:** DRAFT r2, 2026-11-21 (r1 read by aweb's maintainers and the OATS deployment owner's side). It isn't in force until aweb's maintainers and the
|
|
4
|
+
OATS deployment owner's side approve it on this PR. Items marked **OPEN** are undecided and
|
|
5
|
+
mustn't be built on.
|
|
6
|
+
|
|
7
|
+
**What it is.** aweb lets a person adopt an agent (a "root") so that every agent the root
|
|
8
|
+
creates afterwards carries a verified chain back to that person. OATS consumes this:
|
|
9
|
+
- it creates agents from a root, so new instances inherit the chain;
|
|
10
|
+
- it reads each instance's verified human and shows it as **Owning human**.
|
|
11
|
+
|
|
12
|
+
This record is the one place that says which aweb primitives OATS relies on, exactly how
|
|
13
|
+
OATS calls them, what each side owns, and the gates before anything ships. When aw changes
|
|
14
|
+
one of these primitives, or OATS changes how it uses one, this record changes first.
|
|
15
|
+
|
|
16
|
+
**Sources.**
|
|
17
|
+
- aweb: main `d8d0bfa1e7` (`docs/id-certificates.md`, `docs/identity.md`,
|
|
18
|
+
`docs/cli-integration-contract.md`, `docs/cli-command-reference.md`) and aweb's primitive
|
|
19
|
+
list at that SHA.
|
|
20
|
+
- Cloud: the person's dashboard steps read at Cloud `15591632` (tag v0.8.80) and main
|
|
21
|
+
`234882b7`.
|
|
22
|
+
- OATS: the integration plan v1.7 (`0d8b9e1159c6`), read with oats-aweb main `717d0fd`.
|
|
23
|
+
|
|
24
|
+
Every behaviour below is pinned at **the 1.36.59 cut SHA**, which aweb names when it cuts.
|
|
25
|
+
Commit ids are background only.
|
|
26
|
+
|
|
27
|
+
## 1. Principles both sides keep
|
|
28
|
+
|
|
29
|
+
1. **Opt-in is the adoption itself.** A deployment whose roots nobody adopted changes in
|
|
30
|
+
nothing: no OATS setting, no config key, no new aw requirement.
|
|
31
|
+
2. **People sign; agents never act as people.**
|
|
32
|
+
- No agent holds or uses a person's signing key, or a team-scoped owner/admin API key of
|
|
33
|
+
a person's account (P6's key). This is an OATS rule in its own right.
|
|
34
|
+
- A BYOT team's controller key on the deployment host, which the provider's mint uses
|
|
35
|
+
(`aw init --join-from` signs the local invite with it), is unchanged. It belongs to the
|
|
36
|
+
deployment's user, not to a person's account.
|
|
37
|
+
- aw also refuses every person signature inside an OATS instance or without a terminal
|
|
38
|
+
(`human_approval_required`). That is a safeguard on native person signing, not a
|
|
39
|
+
custody boundary, so OATS doesn't rely on it.
|
|
40
|
+
- The person's adoption acts happen in Cloud's dashboard.
|
|
41
|
+
- OATS's existing operator-run key flows are unchanged: `oats aweb setup`'s provisioning
|
|
42
|
+
key and `resident create`'s dashboard key are typed by the person into a protected
|
|
43
|
+
child environment and never held by an agent.
|
|
44
|
+
3. **Prospective, never retroactive.**
|
|
45
|
+
- Adoption applies from then on.
|
|
46
|
+
- Instances created before it keep their key, ID, certificate, address, mailbox,
|
|
47
|
+
memberships and actual ancestry. Chainless ones read `unknown` / `legacy_no_chain`.
|
|
48
|
+
Ones with older namespace ancestry can read `no_human`, or refuse superseded evidence.
|
|
49
|
+
- Leaving them alone is the deployment owner's choice. OATS doesn't respawn or re-sign
|
|
50
|
+
them.
|
|
51
|
+
4. **Attribution is information.** No OATS behaviour (gating, routing, permission) depends on
|
|
52
|
+
the human. OATS only reads it and shows it.
|
|
53
|
+
5. **aw's answer is the truth.** OATS copies aw's verdicts and refusals as aw gives them. It
|
|
54
|
+
reads them only from aw's `--json` fields (§5), never from prose.
|
|
55
|
+
|
|
56
|
+
## 2. Primitives OATS uses
|
|
57
|
+
|
|
58
|
+
| # | Primitive (aw at the cut SHA) | Who runs it, where | OATS's use |
|
|
59
|
+
|---|---|---|---|
|
|
60
|
+
| P1 | `aw --identity-home <root>/.aw id parent request --domain D --parent H --invitation-id I --out request.json` | An agent, in the root's home, during adoption, with the root's own key | Documented step (PR b). D, H and I are copied from the dashboard's invitation, never derived. Writes and retains the request. Only a genuinely chainless root, or one parented directly by its namespace, can be adopted. A root with person ancestry or an agent parent can't. |
|
|
61
|
+
| P2 | `aw --identity-home <root>/.aw id parent import response.json --domain D` | An agent, in the root's home | Documented step (PR b). Verifies and installs the exact signed response. If these steps become machine-consumed, they add `--json` and follow §4's refusal rules. |
|
|
62
|
+
| P3 | `aw init --join-from=<root> --join-team=<T> --name=<alias> --json --do-not-touch-agents-md` (oats-aweb `bin/oats-aweb.mjs:2541`), `<root>` being the root's workspace directory | The provider's spawn hook, on the root's host, as the deployment's user | Primary identity of every spawned instance (unchanged). After adoption, aw signs the child under the root through the mint's same-machine hosted issuer link. |
|
|
63
|
+
| P4 | `aw team invite --team-id <T> --json` with the root as the selected identity, then `aw --identity-home <home>/.aweb-identity-<label> id team accept-invite --token-stdin --name <alias> --local [--parent <root>/.aw] --json`, the same token on stdin | The provider, joining an instance to an extra team; `<home>/.aweb-identity-<label>` is fresh, or the same retained target on retry | Joined-team identities. aweb confirms `--parent` as the supported, unattended route (native agent-to-agent exchange through a token-scoped creator link, same user and HOME). The child proves the invite's human before membership is submitted. `nearest_human` selects the explicit `--parent` path. That is decided by one bounded P5 read of `<root>/.aw` at join time, falling back to C3's record when the read is `unavailable`. Otherwise `--parent` is omitted: a genuinely chainless root's join is unchanged, and a chained `no_human` root's same-machine join completes through the retained mint link without it. An adopted root on an aw below 1.36.59 stops before minting any invite. That stop is an oats-aweb diagnostic with an OATS-owned code, and a README line names the fix. |
|
|
64
|
+
| P5 | `aw --identity-home <home>/.aw who --json` | The provider | C1 and C2 (§4). |
|
|
65
|
+
| P6 | `aw id team remove-member --namespace D --team NAME --cert-id C [--aweb-url URL] --json` (or `--member`), with a team-scoped owner/admin API key from `--api-key` or `AWEB_API_KEY`, calling `/api/v1/teams/{team_id}/agents/remove-member` | The person, from a terminal (§6) | Membership removal (§6). The documented person-run CLI uses the setup key. The server also accepts signed-in person authority for the same route. A person's signing key is a separate credential. |
|
|
66
|
+
|
|
67
|
+
Person's steps in Cloud (dashboard, signed in, the root's team selected, from the root's
|
|
68
|
+
Chat or Messages pane):
|
|
69
|
+
1. **Adopt**, which creates invitation I and shows I, H and D.
|
|
70
|
+
2. **Upload request.json**, then **Approve and prepare response**.
|
|
71
|
+
3. **Download response.json**.
|
|
72
|
+
|
|
73
|
+
Preconditions:
|
|
74
|
+
- the person has claimed a human ID;
|
|
75
|
+
- they are the root's recorded creator, with an active account and current membership of
|
|
76
|
+
the root's team, or a team admin or owning-organisation owner/admin.
|
|
77
|
+
|
|
78
|
+
OATS doesn't use, and doesn't build on, these aw primitives:
|
|
79
|
+
- `id create --human-parent`;
|
|
80
|
+
- `id child invite/receive/approve` on an OATS host;
|
|
81
|
+
- `id parent refresh`, `--resign` and `install`;
|
|
82
|
+
- `id revoke`;
|
|
83
|
+
- an explicit `team invite --for-human`;
|
|
84
|
+
- global join-from;
|
|
85
|
+
- hosted `--member-global` mint.
|
|
86
|
+
|
|
87
|
+
## 3. aw's rules OATS relies on
|
|
88
|
+
|
|
89
|
+
- **The `aw who --json` shape** is `{id, domain, outcome, human_id, identity_valid, kind, reason, chain?, evidence?}`.
|
|
90
|
+
- `outcome` is one of `nearest_human`, `no_human`, `unknown` or `unavailable`.
|
|
91
|
+
- `human_id` is set only on `nearest_human`.
|
|
92
|
+
- `chain[{id,kind}]` is present only when the chain is verified.
|
|
93
|
+
- `unavailable` (`evidence_unavailable`, `status_expired`) is a value, not a command
|
|
94
|
+
failure.
|
|
95
|
+
- A `did:key` home with no chain reads `unknown` / `legacy_no_chain`.
|
|
96
|
+
- The same fields exist in aw 1.36.58.
|
|
97
|
+
- **Adoption** is once per root key. P1 and P2 cover two cases:
|
|
98
|
+
- first issuance to a genuinely chainless root;
|
|
99
|
+
- one-time replacement of a chain parented directly by the namespace, under the first
|
|
100
|
+
person.
|
|
101
|
+
- Cloud's browser authority and eligibility checks gate either case.
|
|
102
|
+
- A local `did:key` root adopts only through the browser-file flow above. An
|
|
103
|
+
agent-submitted request is refused with `global_agent_required`.
|
|
104
|
+
- One adoption covers one key. A host with several roots needs one adoption per root.
|
|
105
|
+
- **After adoption:**
|
|
106
|
+
- The root's ordinary hosted member invites default to its verified nearest human
|
|
107
|
+
(`for_human`). There is no opt-out: `--for-human` can only name another valid person.
|
|
108
|
+
- A `--join-from` child satisfies it.
|
|
109
|
+
- Spawning needs current evidence: registry status and the namespace's DNS. Valid cached
|
|
110
|
+
evidence can cover a brief outage. Without current evidence, the spawn is refused
|
|
111
|
+
(`evidence_unavailable`) with no fallback.
|
|
112
|
+
- New children are issued in the person's domain.
|
|
113
|
+
- Alias, address form, roster entry and mail and chat routing are unchanged in form.
|
|
114
|
+
- An instance spawned by another instance has the root as its immediate ID parent,
|
|
115
|
+
because OATS selects the root for every mint. Its OATS parent stays in `spawnedBy`.
|
|
116
|
+
- An evidence failure refuses without dropping a presented chain. The code and reason can
|
|
117
|
+
vary with the command and the cause.
|
|
118
|
+
- **Same machine, same HOME, for the unattended route.** The unattended local-link route runs
|
|
119
|
+
both halves of one mint on the root's host, as the same user with the same HOME. The
|
|
120
|
+
retained link lives under the minting process's HOME.
|
|
121
|
+
- **Signature pending.** A fresh recipient of an invite that pins a self-custodial agent
|
|
122
|
+
issuer stops before membership when it has no installed chain and no accessible local
|
|
123
|
+
issuer exchange. That holds whether or not the invite carries `for_human`, so it covers a
|
|
124
|
+
chained `no_human` issuer too.
|
|
125
|
+
- aw keeps the key, the pending invite selection and any prepared request. The stop can
|
|
126
|
+
come before any request is created. No membership is submitted.
|
|
127
|
+
- On 1.36.59 it exits 1 with `error.code` `native_agent_signature_pending` (aweb
|
|
128
|
+
`802f1674`; pending verification of the published final binary at the cut SHA).
|
|
129
|
+
- aw 1.36.58 takes the same stop, but exits 1 with the generic `error.code` `error`, which
|
|
130
|
+
doesn't identify this state.
|
|
131
|
+
|
|
132
|
+
## 4. OATS's side (oats-aweb PR a; docs PR b)
|
|
133
|
+
|
|
134
|
+
**C1, the attribution read.**
|
|
135
|
+
- **When:** at spawn after the mint, and at each start (the launch hook's real pass only,
|
|
136
|
+
never under `OATS_LAUNCH_PREVIEW=1`).
|
|
137
|
+
- **The read:** P5, bounded at 5 s, run once, with no retry. It never refuses and never
|
|
138
|
+
delays beyond the bound.
|
|
139
|
+
- **What it writes:** the kernel's existing `attribution` in the served identity:
|
|
140
|
+
`{mode, human: {id, label}|null, parent: {id}|null}`.
|
|
141
|
+
- **Mapping from aw's `outcome`:**
|
|
142
|
+
- `nearest_human` → `human`. `label` is `human_id`, because aw gives no display name, so
|
|
143
|
+
the Desktop shows the `did:aw`. `parent {id}` is the chain's next link up from the
|
|
144
|
+
instance, that is, the root.
|
|
145
|
+
- `no_human` → `none`.
|
|
146
|
+
- Anything else → `unknown`.
|
|
147
|
+
- `parent` is null when there is no verified chain.
|
|
148
|
+
- **Carry-forward:** a non-zero exit, a timeout, unparseable output or `unavailable` carries
|
|
149
|
+
the previous value forward, or `unknown` if there is none. An answer aw gave replaces the
|
|
150
|
+
previous value.
|
|
151
|
+
|
|
152
|
+
**C2, the root report in `oats aweb setup --check-only --json`.**
|
|
153
|
+
- **Shape:** `roots[]`, one
|
|
154
|
+
`{label, home, attribution: {outcome, humanId|null, reason|null}, warnings: [string]}` per
|
|
155
|
+
roots-map entry. `warnings` carries the aw-version note and C3's warning, and is empty
|
|
156
|
+
otherwise.
|
|
157
|
+
- **The read:** P5 with `--identity-home <root>/.aw`.
|
|
158
|
+
- **A failed read** gives `unavailable` with its reason.
|
|
159
|
+
- **Old aw:** a root that reads `nearest_human` on an aw below 1.36.59 gets a note that
|
|
160
|
+
spawning from it needs 1.36.59.
|
|
161
|
+
|
|
162
|
+
**C3, the adopted-lineage warning.**
|
|
163
|
+
- **The record:** the provider keeps, in its own state, each root's last *verified*
|
|
164
|
+
`nearest_human` observation (the human and when it was seen), keyed by the root's identity
|
|
165
|
+
and key, not by its label. A later `unknown` or `no_human` doesn't erase it. Only a new
|
|
166
|
+
`nearest_human` replaces it. So the warning shows at every spawn and in every check-only
|
|
167
|
+
while the chain stays missing, not only at the first read.
|
|
168
|
+
- **When it warns:** a root with that record now reads `unknown` or `no_human`, whatever the
|
|
169
|
+
reason. Examples are `legacy_no_chain` after a restore from a
|
|
170
|
+
backup taken before adoption, and `revoked` or `root_replaced`.
|
|
171
|
+
- **How:** it warns at spawn and in check-only (C2's `warnings`), naming the root and aw's
|
|
172
|
+
reason.
|
|
173
|
+
- `unavailable` never triggers it, and the record is kept.
|
|
174
|
+
- It never refuses. A stale copied home is never a reason to adopt again.
|
|
175
|
+
|
|
176
|
+
**Signature pending.**
|
|
177
|
+
- A mint stopped as signature pending is left for the operator. Retiring it would delete the
|
|
178
|
+
kept key.
|
|
179
|
+
- PR a recognises it by `native_agent_signature_pending`.
|
|
180
|
+
- The spawn fails as a failed mint does today. When the kernel's compensation runs the
|
|
181
|
+
provider's retire hook, the hook answers `meta: {retired: false, reason: "signature-pending"}`.
|
|
182
|
+
That is an incomplete cleanup, so the kernel keeps the home, marked
|
|
183
|
+
`.oats-rollback-incomplete.json` (the existing rule in [capabilities](../capabilities.md)).
|
|
184
|
+
No kernel or hook-contract change is involved.
|
|
185
|
+
- The hook answers `signature-pending` only while aw still holds the pending mint: the exact
|
|
186
|
+
home, key and pending selection, including any prepared request. Each `oats retire` retry
|
|
187
|
+
runs the hook again. Once aw settles the mint either way, the hook answers what is true and
|
|
188
|
+
a plain retry clears the home. `--force` is not the route.
|
|
189
|
+
- Nothing remints into that home or compensates it away while it is pending.
|
|
190
|
+
- On an aw without the code (1.36.58, or a cut SHA that lacks it), a signature-pending stop
|
|
191
|
+
can only come from a chained issuer. So PR a keeps a home whose mint failed after aw wrote
|
|
192
|
+
a key only when the mint's issuing root isn't genuinely chainless, by P5's read or by C3's
|
|
193
|
+
record. It never parses prose. A mint from a chainless root keeps today's behaviour, where
|
|
194
|
+
retire settles the recorded mint, so a deployment that doesn't adopt changes in nothing.
|
|
195
|
+
- OATS never retries or remints automatically. An explicit operator recovery keeps the exact
|
|
196
|
+
original home, key, token and selection.
|
|
197
|
+
|
|
198
|
+
**Reading aw's refusals** (aweb's `docs/cli-integration-contract.md` at `e6e9f099c5`).
|
|
199
|
+
- PR a branches only on the exit status and the structured fields: `error.code`,
|
|
200
|
+
`error.http_status` and `error.reason`.
|
|
201
|
+
- `error.message` is for display only. A direct ID-certificate refusal carries a bare reason
|
|
202
|
+
there, but commands may wrap it, so no machine behaviour keys on it.
|
|
203
|
+
- A command may wrap an HTTP refusal under its own code and keep `http_status` and `reason`.
|
|
204
|
+
For example, `aw init --join-from` reports a refused invite as `invite_not_created`, and a
|
|
205
|
+
direct `aw team invite` reports it as `http_error`.
|
|
206
|
+
- Tests assert the fields the actual command returns.
|
|
207
|
+
|
|
208
|
+
**The aw floor.**
|
|
209
|
+
- `min` stays 1.36.33, so a deployment that doesn't adopt needs no new aw.
|
|
210
|
+
- `tested` moves to the 1.36.59 final.
|
|
211
|
+
- A deployment that adopts a root needs aw 1.36.59 on that root's host (C2's note; PR b says
|
|
212
|
+
to upgrade before adopting).
|
|
213
|
+
|
|
214
|
+
**Where OATS mints, and the connect rule.**
|
|
215
|
+
- Spawns (including routed spawns, schedules and sandbox seats made by sync) mint through P3
|
|
216
|
+
on the host that runs them, from that host's own root.
|
|
217
|
+
- Joined teams mint through P4.
|
|
218
|
+
- GLOBAL grant seats, retained seats and `setup --create` don't mint from a root.
|
|
219
|
+
- `oats aweb connect <server>`, and `setup --join` with an invite issued by a root on
|
|
220
|
+
another machine, mint a new remote root away from the issuing root.
|
|
221
|
+
- The rule (aweb, at `d8d0bfa1e7`, tested against aw 1.36.58 and the 1.36.59 candidate):
|
|
222
|
+
- A new unattended remote root can't join through an invite from a self-custodial chained
|
|
223
|
+
inviter, whether that inviter reads `nearest_human` or `no_human`, on either aw version.
|
|
224
|
+
That holds before adoption as well as after. aw stops it as signature pending (§3).
|
|
225
|
+
- Only a genuinely chainless inviter (`unknown` / `legacy_no_chain`) gives an invite a new
|
|
226
|
+
remote root can join directly, and that root can be adopted on its own later.
|
|
227
|
+
- With a chained inviter, the supported route is aw's cross-machine file exchange. The
|
|
228
|
+
inviting root agent signs the remote root as its child, with an operator moving the files
|
|
229
|
+
and no person signature. The remote root then belongs to that lineage and can't be
|
|
230
|
+
adopted separately.
|
|
231
|
+
- **Connect** has the inviting root on this host. It reads that root with P5 before
|
|
232
|
+
minting the invite, and refuses a chained inviter unless the operator chose the file
|
|
233
|
+
exchange. An `unavailable` read falls back to C3's record, or with none proceeds with a
|
|
234
|
+
warning.
|
|
235
|
+
- **`setup --join`** with only a token can't read the inviter. aw enforces the rule at
|
|
236
|
+
accept, and OATS keeps the pending home (§4 "Signature pending").
|
|
237
|
+
- Out of scope for this rule: an identity that already has a chain joining a team, and an
|
|
238
|
+
issuer in host-managed custody.
|
|
239
|
+
|
|
240
|
+
## 5. Gates
|
|
241
|
+
|
|
242
|
+
- **G1, aw.** Nothing merges until aw 1.36.59 final is published and PR a's real-binary
|
|
243
|
+
tests pass against the final binary at the cut SHA. Those tests run P3 and same-machine P4
|
|
244
|
+
with their actual argv. They assert that the child's installed leaf binds the retained
|
|
245
|
+
child key and the exact parent, that it verifies to the person, and that P4 without
|
|
246
|
+
`--parent` from a chainless root still joins.
|
|
247
|
+
- Development and CI may use `1.36.59-rc.3`, pinned by integrity.
|
|
248
|
+
- `tested` never points at an RC.
|
|
249
|
+
- **G2, the run.** aweb's Cloud journey case (`cloud-journey-case-acxy7-v1`; original
|
|
250
|
+
case-text hash `85196827b2b0`) runs on a scratch hosted team with a test person, never on
|
|
251
|
+
a live team or a real person's identities.
|
|
252
|
+
- Its first green run is the evidence, recorded with the actual Cloud head, the aw cut SHA
|
|
253
|
+
and a verdict per step. The agreed record (v3) is written from it.
|
|
254
|
+
- Its eight steps:
|
|
255
|
+
1. Before adoption, R mints an early child E.
|
|
256
|
+
2. The person adopts R through the dashboard's invitation, upload and approval, and
|
|
257
|
+
download, with P1 and P2 run in R. R then reads `nearest_human`.
|
|
258
|
+
3. R mints a child C unattended. C verifies to the person, and its chain ends in R then
|
|
259
|
+
C.
|
|
260
|
+
4. A grandchild G is minted unattended. Its chain ends in R then G.
|
|
261
|
+
5. E is unchanged: same ID, key and membership certificate, still `unknown`.
|
|
262
|
+
6. A control child K, minted from an unadopted root R0, matches C in alias, address,
|
|
263
|
+
roster and workspace form. Verified mail and chat flow both ways between C and K.
|
|
264
|
+
7. Revocation, as changed with both sides' agreement from the original "a team admin
|
|
265
|
+
removes R's membership in the dashboard", which the released Cloud lacks (§6):
|
|
266
|
+
- P6 runs against the scratch hosted team and R's exact team certificate.
|
|
267
|
+
- A surviving child reads fresh registry membership and confirms R is absent.
|
|
268
|
+
- The signed-in person reloads Agents and sees the surviving child and R's absence.
|
|
269
|
+
- R's next `aw init --join-from` exits nonzero with `error.code`
|
|
270
|
+
`invite_not_created`, `http_status` 401 and `reason` `certificate_revoked`
|
|
271
|
+
(aw init.go:434-442).
|
|
272
|
+
- The surviving members' certificates, mail and chat history are unchanged.
|
|
273
|
+
- The paired runtime evidence includes P6 run with a fresh dashboard-issued,
|
|
274
|
+
same-team owner or admin setup key, once Cloud's restoration is composed (§6).
|
|
275
|
+
8. Clean-up: scratch memberships removed, scratch identities revoked, receipts checked.
|
|
276
|
+
- **G3, Cloud.** Production Cloud (0.8.80, `15591632`, read from its health endpoint on
|
|
277
|
+
2026-11-21) already has the person's three adoption steps. Adoption on hosted teams still
|
|
278
|
+
waits for aweb's release decision on the Cloud release it pairs with aw 1.36.59, made on
|
|
279
|
+
G2's browser evidence. aweb names that version.
|
|
280
|
+
|
|
281
|
+
## 6. Revocation
|
|
282
|
+
|
|
283
|
+
- There is no per-root undo of an adoption.
|
|
284
|
+
- The control is removing the root's team membership. The way on is a new root with a new
|
|
285
|
+
key.
|
|
286
|
+
- Removing the membership leaves the other members' memberships, mail and history
|
|
287
|
+
unchanged.
|
|
288
|
+
- The person can revoke their whole ID, which ends everything under them. OATS neither does
|
|
289
|
+
nor tests that.
|
|
290
|
+
|
|
291
|
+
**How the membership is removed on a hosted team** (decided by aweb's product owner,
|
|
292
|
+
2026-11-21, relayed by aweb's maintainers in their mail `c05ca697`):
|
|
293
|
+
- The paired Cloud release keeps the existing hosted CLI route, P6. The person who runs it
|
|
294
|
+
is the team's current owner or team admin, using their team's unexpired dashboard setup
|
|
295
|
+
key, with the existing team and person checks.
|
|
296
|
+
- This restores the setup key's authority on that route, which production (`15591632`)
|
|
297
|
+
already gives. Until aweb's maintainers name the restoring SHA and the user-path evidence
|
|
298
|
+
exists, this is a release commitment, not shipped behaviour.
|
|
299
|
+
- There is no dashboard membership-only Remove for a team-only root. Archive and Replace
|
|
300
|
+
remain for permanent agents.
|
|
301
|
+
- The principle: no user path is harder than production, and extra human-assurance security
|
|
302
|
+
is opt-in.
|
|
303
|
+
- Removing the membership affects that team and the root's ability to mint there. The
|
|
304
|
+
signed adoption and identity ancestry stay in place. This is not an undo of adoption.
|
|
305
|
+
|
|
306
|
+
**Current behaviour: the person runs P6.** No agent holds or uses the person's owner or
|
|
307
|
+
admin key (principle 2). The ruling above restores a credential's server authority; it
|
|
308
|
+
grants no exception to principle 2.
|
|
309
|
+
- For the OATS deployment owner's deployments, the person-run P6 step is pending their word,
|
|
310
|
+
because their recorded rule is that agents run every command. PR b's revocation text waits
|
|
311
|
+
on it.
|
|
312
|
+
|
|
313
|
+
**OPEN R: whether to allow delegation later.** An agent running P6 with an owner key the
|
|
314
|
+
person delegates would need a separate ruling.
|
|
315
|
+
|
|
316
|
+
Principle 2 forbids the second unless both OATS owners, aweb's product owner and the OATS
|
|
317
|
+
deployment owner, rule otherwise. Principle 2 binds every OATS deployment, so neither side
|
|
318
|
+
changes it alone.
|
|
319
|
+
|
|
320
|
+
Once that word is in, PR b documents the person-run P6 with the setup key, and no session
|
|
321
|
+
plumbing.
|
|
322
|
+
|
|
323
|
+
## 7. Ownership
|
|
324
|
+
|
|
325
|
+
| Area | Owner | Approves changes |
|
|
326
|
+
|---|---|---|
|
|
327
|
+
| aw primitives P1 to P6, codes, the cut SHA | aweb's maintainers | aweb's maintainers |
|
|
328
|
+
| Cloud's person steps and the paired Cloud release | aweb's Cloud maintainers | aweb's maintainers |
|
|
329
|
+
| The journey case and its verdicts (G2) | aweb's Cloud maintainers | both sides; any change to the case's text comes to OATS first |
|
|
330
|
+
| C1 to C3, the mint flows, the floor (oats-aweb PR a) | the OATS deployment owner's side builds it | the OATS deployment owner's side, then the OATS maintainers at the exact head |
|
|
331
|
+
| Docs and release notes (PR b) | the OATS deployment owner's side | both |
|
|
332
|
+
| This record | the OATS maintainers | both sides, on its PR |
|
|
333
|
+
|
|
334
|
+
## 8. Open items
|
|
335
|
+
|
|
336
|
+
- **A, B: answered** by aweb at `d8d0bfa1e7`, with B tested against aw 1.36.58 and the
|
|
337
|
+
1.36.59 candidate (§2 P4, §3, §4 "Where OATS mints").
|
|
338
|
+
- **C.** `native_agent_signature_pending` is implemented on aweb `802f1674` (exit 1, recovery
|
|
339
|
+
state kept, no membership). Its inclusion is pending verification of the published final
|
|
340
|
+
binary at the cut SHA.
|
|
341
|
+
- **R.** Whether an agent may ever run P6 with a delegated owner key (§6). Today only the
|
|
342
|
+
person runs it. (both OATS owners: aweb's product owner and the OATS deployment owner)
|
package/docs/design/README.md
CHANGED
|
@@ -37,6 +37,8 @@ successor, with a link to its full text.
|
|
|
37
37
|
built): boundaries declared in the workspace's `sandboxes:`, each listing the souls
|
|
38
38
|
it may run, started by `oats sync` on the machines that list them. Placement no
|
|
39
39
|
longer follows a team (r5).
|
|
40
|
+
- [Human IDs contract](2026-11-21-human-ids-contract.md): the aweb human-ID
|
|
41
|
+
primitives OATS relies on, how it calls them, who owns what, and the gates.
|
|
40
42
|
|
|
41
43
|
The Desktop's design brief for designers is in
|
|
42
44
|
[packages/desktop/docs](../../packages/desktop/docs/design-brief.md).
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -2820,10 +2820,38 @@ oats spawn <soul> [the flags of a real spawn] --preview [--max-age <s>] --json
|
|
|
2820
2820
|
```
|
|
2821
2821
|
|
|
2822
2822
|
Feature `spawn-preview-2`, `spawnPreviewApi: 2`. The preview runs every
|
|
2823
|
-
preflight a spawn runs and writes nothing
|
|
2823
|
+
preflight a spawn runs and writes nothing of the deployment's state, on
|
|
2824
|
+
success or refusal (one cache may be filled: a session provider's package
|
|
2825
|
+
tree, below). It reads the
|
|
2824
2826
|
soul from the per-commit cache (`agents/<soul>/souls/<commit12>/`) or fetches
|
|
2825
2827
|
it to a temporary copy (`soulFetched: true`).
|
|
2826
2828
|
|
|
2829
|
+
**A preview on a session provider asks the provider** what the spawn will ask
|
|
2830
|
+
it before any hook runs: its readiness `check`, with the launch that is
|
|
2831
|
+
planned ([check](capabilities.md#check-optional)). No key changes meaning:
|
|
2832
|
+
|
|
2833
|
+
- A launch the provider would refuse **fails the preview** with the code the
|
|
2834
|
+
spawn would be refused with (`E_BACKEND_SANDBOXED_MODE` for a provider that
|
|
2835
|
+
launches only in full mode, `E_BACKEND_NOT_READY` for one that cannot be
|
|
2836
|
+
asked or answers outside the rules), exit 1, as every other refusal of a
|
|
2837
|
+
backend fails it. Nothing is created: not the home, nor the kernel's
|
|
2838
|
+
directory beside it.
|
|
2839
|
+
- The check runs within the preview's one preflight budget. A provider that
|
|
2840
|
+
does not answer in what is left of it leaves `preflight.status: "timeout"`.
|
|
2841
|
+
It is never given longer than a spawn gives its check (20 s). That limit
|
|
2842
|
+
is also the preview's whole budget, so today a check that does not answer
|
|
2843
|
+
in time always reads as `timeout`; were the budget longer than the limit,
|
|
2844
|
+
a check that reached the limit would fail the preview
|
|
2845
|
+
`E_BACKEND_NOT_READY`, as it fails the spawn.
|
|
2846
|
+
- The provider's script runs from its package's tree in the deployment's
|
|
2847
|
+
module store, which the preview fetches there, verified, when it is absent:
|
|
2848
|
+
the one thing a preview may write, a cache `oats readiness --soul` fills the
|
|
2849
|
+
same way. A provider in a **member module** runs only from a spawned home,
|
|
2850
|
+
so it is not asked, and `warnings` carries one line that says so; the spawn
|
|
2851
|
+
still asks it.
|
|
2852
|
+
- A provider that declares no `check`, a tmux launch and a `--no-launch`
|
|
2853
|
+
spawn ask nothing.
|
|
2854
|
+
|
|
2827
2855
|
```json
|
|
2828
2856
|
{"modules":[
|
|
2829
2857
|
{"name":"nw-tools","from":{"kind":"member","repoKey":"github.com/nw/agents","commit":"66566512…"},"layer":null,"private":false,"declares":[],
|
|
@@ -7666,7 +7694,13 @@ hold the listing up. A client has no use for it.
|
|
|
7666
7694
|
**Launch preview.** `oats launch-config preview --home <abs> --json` of a
|
|
7667
7695
|
provider home answers `command: null`, `argv: null` and `executable.path:
|
|
7668
7696
|
null` (its launch is handed to the provider as data), `environment` by name,
|
|
7669
|
-
and a `backend` item in `preflight`.
|
|
7697
|
+
and a `backend` item in `preflight`. The preview asks the provider's `check`
|
|
7698
|
+
with the launch that is planned, as the start will before it stops anything:
|
|
7699
|
+
a launch the provider would refuse is a failed `backend` item (`code`: the
|
|
7700
|
+
start's refusal, `E_BACKEND_*`), and `ok` is false. So is an allowance's path
|
|
7701
|
+
the start would refuse to make (`E_BACKEND_SANDBOX_HOST`); `warnings` carries
|
|
7702
|
+
the start's `sandbox allowances: …` lines. Nothing is stopped, started or
|
|
7703
|
+
created.
|
|
7670
7704
|
|
|
7671
7705
|
### Input
|
|
7672
7706
|
|
package/docs/implementation.md
CHANGED
|
@@ -983,12 +983,18 @@ inherits it (awebai/oats#816):
|
|
|
983
983
|
`writeFixtureExecutable(fx.base, path, content)`, which refuses a path
|
|
984
984
|
outside the fixture's base, one reached through a link, and a symbolic or
|
|
985
985
|
hard link at the path, with nothing written. `fx.inEnv` keeps the PATH of
|
|
986
|
-
the process that runs the tests,
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
986
|
+
the process that runs the tests, where a machine with the harness
|
|
987
|
+
installed has the person's own binary. **An in-process spawn (`fx.spawn`)
|
|
988
|
+
looks for the harness on the fixture's PATH** (#2044): the fixture's inert
|
|
989
|
+
`pi`, `claude` and `codex` are put before the host's directories
|
|
990
|
+
(`fixtureSpawnPath`), after anything the test put in front itself, so a
|
|
991
|
+
test's own fake harness is still the one found and the `launch.executable`
|
|
992
|
+
such a spawn records is inside the fixture. (That is the lookup on this
|
|
993
|
+
process's PATH: a spawn that launches looks on the PATH of the fixture's
|
|
994
|
+
tmux server, and a spawn made without `fx.spawn` keeps the PATH it has.) A test that needs the harness
|
|
995
|
+
of the machine it runs on says so: `fx.spawn(soul, { hostHarness: true })`.
|
|
996
|
+
A spawn whose recorded executable a test will rewrite also asserts
|
|
997
|
+
`insideFixture(fx.base, launch.executable)`. The fixture's
|
|
992
998
|
environment sets `HOME` and the XDG base directories under the base, and
|
|
993
999
|
`GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null` and
|
|
994
1000
|
`GIT_TERMINAL_PROMPT=0`, so no host git
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# OATS 0.70.1
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
A preview on a session provider now asks the provider's own readiness check,
|
|
6
|
+
so it no longer reads clean for a launch the provider then refuses. A
|
|
7
|
+
schedule's save asks the same, with the job's own `yolo`. tmux homes and their
|
|
8
|
+
previews are unchanged.
|
|
9
|
+
|
|
10
|
+
## Upgrade
|
|
11
|
+
|
|
12
|
+
- **The Desktop and the CLI** can be upgraded in either order.
|
|
13
|
+
- **A scheduled or triggered spawn on a provider that launches only in full
|
|
14
|
+
mode (bb's)** needs `yolo: true` in its definition, or a launch
|
|
15
|
+
configuration that sets it. A job without it is now refused when saved, where
|
|
16
|
+
it used to fail at each run.
|
|
17
|
+
|
|
18
|
+
## Changed
|
|
19
|
+
|
|
20
|
+
- **A spawn job on a session provider is checked by the provider when it is
|
|
21
|
+
saved.** A spawn's preview now asks a session provider's `check` with the
|
|
22
|
+
launch that is planned, and `oats schedule add`, `update` and `test` ask
|
|
23
|
+
that preview with the job's own launch selection, its `yolo` included
|
|
24
|
+
([spawn](../schedules.md#kinds)). On a provider that launches only in full
|
|
25
|
+
mode:
|
|
26
|
+
- a job with `yolo: true` is saved and launches, as one whose launch
|
|
27
|
+
configuration sets yolo does (a build with the preview's new check and
|
|
28
|
+
without this change refused the job's own `yolo: true` on `add` and
|
|
29
|
+
`update`, and `oats schedule test` said its soul did not resolve: the
|
|
30
|
+
schedule's preview did not carry it);
|
|
31
|
+
- a job with no `yolo` is refused when saved (`E_SCHEDULE_INVALID`,
|
|
32
|
+
`details.code: "E_BACKEND_SANDBOXED_MODE"`), and `oats schedule test`
|
|
33
|
+
reports it, where it used to fail only at its run. One the
|
|
34
|
+
save did not ask the provider about (its soul was already spawned in
|
|
35
|
+
the deployment, or the provider comes from a member module, which a
|
|
36
|
+
preview does not ask) fails at each run, `launch-failed` with `errorCode:
|
|
37
|
+
"E_BACKEND_SANDBOXED_MODE"`, and leaves no home.
|
|
38
|
+
|
|
39
|
+
## Fixed
|
|
40
|
+
|
|
41
|
+
- **A preview on a session provider no longer reads clean for a launch the
|
|
42
|
+
provider will refuse.** `oats spawn --preview` of a spawn on a session
|
|
43
|
+
provider read complete, with no problem and no warning, and the spawn was
|
|
44
|
+
then refused by the provider's readiness check and undone (with a provider
|
|
45
|
+
that launches only in full mode and no full-mode choice:
|
|
46
|
+
`E_BACKEND_SANDBOXED_MODE`). A preview now asks the provider's `check` with
|
|
47
|
+
the launch that is planned, as the spawn does before any hook runs
|
|
48
|
+
([spawn preview](../desktop-cli-api.md), [check](../capabilities.md#check-optional)):
|
|
49
|
+
- a launch the provider would refuse fails the preview with the spawn's own
|
|
50
|
+
code and creates nothing; a provider that cannot be asked is
|
|
51
|
+
`E_BACKEND_NOT_READY`; one that outlasts the preview's budget leaves
|
|
52
|
+
`preflight.status: "timeout"`;
|
|
53
|
+
- `oats launch-config preview --home` of a provider home asks it too, and
|
|
54
|
+
shows a refusal as a failed `backend` item, with `ok: false`;
|
|
55
|
+
- a provider in a member module, which runs only from a spawned home, is
|
|
56
|
+
not asked: the preview says so in `warnings`.
|
|
57
|
+
|
|
58
|
+
For a provider's author: `check` may now be handed a home that does not
|
|
59
|
+
exist yet (a spawn's preview hands its planned path). It must only read,
|
|
60
|
+
and treat an absent home as absent.
|
|
61
|
+
|
|
62
|
+
## Documentation
|
|
63
|
+
|
|
64
|
+
- **Schedules and triggers on a session provider**
|
|
65
|
+
([Kinds](../schedules.md#kinds), [Triggers](../schedules.md#triggers)): a
|
|
66
|
+
scheduled or triggered spawn on a provider that launches only in full mode
|
|
67
|
+
needs `yolo: true` in its definition, or a launch configuration that sets
|
|
68
|
+
it; a wake is the input of a provider home's session, and never starts a
|
|
69
|
+
stopped provider home. Tests now cover a wake, a scheduled spawn and a
|
|
70
|
+
triggered spawn on a session provider.
|
package/docs/schedules.md
CHANGED
|
@@ -171,11 +171,13 @@ refuses the key on a trigger.
|
|
|
171
171
|
package soul the workspace offers, see `oats souls`), whether or not this
|
|
172
172
|
deployment has spawned it before. `add` and `update` refuse a job whose
|
|
173
173
|
`oats spawn <agent> --preview`, with the job's `launchConfig`, `harness`,
|
|
174
|
-
`model`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
|
|
174
|
+
`model`, `yolo`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
|
|
175
175
|
with spawn's own message and its code in `details.code`), or whose preview
|
|
176
176
|
answer cannot be confirmed; a soul this deployment has already spawned is
|
|
177
177
|
accepted without the preview. `agentsRoot`, when given, must be the deployment's `agents/` root; `repo`
|
|
178
|
-
is the work repository, as `--repo`. `backend` is `tmux
|
|
178
|
+
is the work repository, as `--repo`. `backend` is `tmux`, or the name of a
|
|
179
|
+
[session provider](execution-targets.md#session-providers) of the soul's
|
|
180
|
+
capabilities; `backend: herdr`
|
|
179
181
|
is refused (`E_HERDR_REMOVED`, naming the file and key: Herdr was removed in
|
|
180
182
|
0.31.0), and a stored job that names it is reported invalid and never runs.
|
|
181
183
|
`model` is a model id (a letter or
|
|
@@ -189,6 +191,23 @@ refuses the key on a trigger.
|
|
|
189
191
|
trailing block naming the job and the minute and ending with `oats retire
|
|
190
192
|
--self`. `wake` (`{cron, tz, message}`) attaches a wake schedule to each
|
|
191
193
|
launched instance.
|
|
194
|
+
|
|
195
|
+
**On a session provider** the run's spawn launches through the provider
|
|
196
|
+
`backend` names. A provider that launches only in full mode (bb's does)
|
|
197
|
+
refuses every other launch at its
|
|
198
|
+
[check](capabilities.md#check-optional), `E_BACKEND_SANDBOXED_MODE`. A job
|
|
199
|
+
on such a provider needs `yolo: true` in its definition, or a launch
|
|
200
|
+
configuration that sets it: the job's `launchConfig`, or the deployment's
|
|
201
|
+
[default for the harness](configuration.md#the-harness-default). Without
|
|
202
|
+
it `add` and `update` refuse the job where they ask the preview
|
|
203
|
+
(`E_SCHEDULE_INVALID`, with `details.code: "E_BACKEND_SANDBOXED_MODE"`),
|
|
204
|
+
and `oats schedule test` reports it. A job the save did not ask the
|
|
205
|
+
provider about (its soul was already spawned here, so `add` and `update`
|
|
206
|
+
ask no preview; or the provider comes from a member module, which a
|
|
207
|
+
preview does not ask) fails at each run: the run is recorded
|
|
208
|
+
`launch-failed` with `errorCode: "E_BACKEND_SANDBOXED_MODE"` and the
|
|
209
|
+
provider's message, its spawn is undone and no home is left; the job tries
|
|
210
|
+
again at its next due minute.
|
|
192
211
|
- **command** `{…, cwd, argv}` — runs an oats-only argv (`argv[0]` is `oats`,
|
|
193
212
|
no shell; `oats schedule` itself is refused) in `cwd`, an existing directory
|
|
194
213
|
inside the deployment. The runner tracks any instance the command's
|
|
@@ -221,6 +240,21 @@ refuses the key on a trigger.
|
|
|
221
240
|
again only at due minutes, so a harness that keeps exiting is not restarted
|
|
222
241
|
in a loop. Unobservable or still starting: skipped, delivery kept pending.
|
|
223
242
|
Word wake messages so that receiving one again is harmless.
|
|
243
|
+
|
|
244
|
+
A home on a [session provider](execution-targets.md#session-providers) has
|
|
245
|
+
no terminal: the message is its session's input, sent once through the
|
|
246
|
+
provider, and a live claim holds it the same way. **A wake never starts a
|
|
247
|
+
provider home OATS stopped.** Its input is refused before any provider
|
|
248
|
+
call: the run is `skipped` with `errorCode: "E_SESSION_NOT_RUNNING"`, and
|
|
249
|
+
the delivery stays pending until the home is started (`oats session
|
|
250
|
+
start`). To a session that is lost (gone, and not stopped by OATS) the
|
|
251
|
+
input is a resume, on which the provider restarts the session, counted
|
|
252
|
+
against the home's cap
|
|
253
|
+
([lost sessions](execution-targets.md#session-providers)). An input the provider itself refuses
|
|
254
|
+
(`E_SESSION_PROMPT_OPEN` while its session shows a prompt,
|
|
255
|
+
`E_SESSION_INPUT_QUEUED`) is `skipped` with that `errorCode`: nothing was
|
|
256
|
+
sent, and the pending delivery is tried again at every tick, then delivered
|
|
257
|
+
once.
|
|
224
258
|
- **operation** `{…, operation, home}` — runs a provider operation
|
|
225
259
|
(`<layer>:<name>`, one the capability filling that layer declares) in the
|
|
226
260
|
instance at `home` through `oats operation run <layer>:<name> --home <home>`. The provider is whatever fills that layer
|
|
@@ -299,7 +333,12 @@ when the timer cannot reach it.
|
|
|
299
333
|
request's title and body are untrusted and never reach the task. `teams` (optional) becomes the messaging capability's `join=`
|
|
300
334
|
setting (`E_TRIGGER_TEAMS` when the soul has no messaging capability).
|
|
301
335
|
`launchConfig`, `harness`, `model`, `yolo` and `backend` are as for
|
|
302
|
-
schedules.
|
|
336
|
+
schedules. On a session provider that launches only in full mode (bb's
|
|
337
|
+
does) the spawn needs `yolo: true`, or a launch configuration that sets
|
|
338
|
+
it, as [a schedule's spawn](#kinds) does. Without it each event's spawn
|
|
339
|
+
fails (`spawn-failed`, `E_BACKEND_SANDBOXED_MODE`, kept as the trigger's
|
|
340
|
+
`lastError`), no home is created, and the event stays pending and is tried
|
|
341
|
+
again at each poll.
|
|
303
342
|
- **The instance name** is spawn's own: `<stem>-<purpose>`, where the stem is
|
|
304
343
|
the slug of the soul's agent name (a package soul's is
|
|
305
344
|
`<package>--<soul>`, so its stem is long), read from one `oats spawn <soul>
|
package/docs/upgrading.md
CHANGED
|
@@ -6,12 +6,12 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.70.
|
|
10
|
-
The 0.70.
|
|
9
|
+
The latest version is **OATS 0.70.1** ([release notes](release-notes/v0.70.1.md)).
|
|
10
|
+
The 0.70.1 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.70: the
|
|
11
11
|
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
12
12
|
|
|
13
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
14
|
-
0.70.
|
|
14
|
+
0.70.1,** in the [release notes](release-notes/): it says what to do before
|
|
15
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
16
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
17
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -20,8 +20,8 @@ prints the version you have.
|
|
|
20
20
|
Then, on each host:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
# 0. where the Desktop is installed: Desktop 0.70.
|
|
24
|
-
npm install -g @awebai/oats@0.70.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.70.1, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.70.1 # 1. the CLI
|
|
25
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
26
26
|
oats doctor # 3. in the same deployment
|
|
27
27
|
```
|
|
@@ -217,6 +217,10 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
217
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
218
218
|
here.
|
|
219
219
|
|
|
220
|
+
- **[0.70.1](release-notes/v0.70.1.md#upgrade):** a scheduled or triggered
|
|
221
|
+
spawn on a provider that launches only in full mode (bb's) needs `yolo:
|
|
222
|
+
true`, or a launch configuration that sets it; a job without it is now
|
|
223
|
+
refused when saved.
|
|
220
224
|
- **[0.70.0](release-notes/v0.70.0.md#upgrade):** upgrade the Desktop with
|
|
221
225
|
the CLI: a Desktop of 0.69.18 to 0.69.24 runs the 0.70.0 CLI in its
|
|
222
226
|
reduced, above-tested mode until Desktop 0.70.0 is installed; a Desktop of
|
package/lib/core.mjs
CHANGED
|
@@ -66,10 +66,43 @@ import { assertNoPartialUpgrade, packageRespawnWarning, packageUpgradeDrift, upg
|
|
|
66
66
|
import { refuseHomeOfAnotherUser } from "./home-owner.mjs";
|
|
67
67
|
import { oatsError, afterEndedSteps, afterFirstEffect, asKernelError, BEFORE_EFFECT_CODES, checkHolderByHand, errorCause, ifItDoesNotEnd, isAnswerCode, isDefect, isKernelCode, kernelCode, lifecycleBusy, nothingAfter, reportDefect, OWN_NAME_FAILURES, OWN_START_REMEDY, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
|
|
68
68
|
import { envRows, recordedTeams } from "./teams.mjs";
|
|
69
|
+
import { safeText } from "./refused-text.mjs";
|
|
69
70
|
import { PANE_PATH_FIX, harnessNotOnPanePath, harnessUnavailable, launchConfigAmbiguous, launchConfigUnknown, launchConfigUnknownFix, launchLayers, launchPreferenceUnmatched, launchPreferenceUnmatchedProblem, launchReport, selectionFrom } from "./launch-preference.mjs";
|
|
70
71
|
import { shq, shellWord } from "./shell-word.mjs";
|
|
71
72
|
import { CONFIG_DIR_VAR, HARNESS_FOLDER_VAR, claudeTrusts, codexTrustsRoot, harnessConfigFile, harnessTrustWarning, launchConfigFolder } from "./harness-trust.mjs";
|
|
72
73
|
async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
|
|
74
|
+
/** What a home's record says of the workspace and the teams, from the prepared resolution: the
|
|
75
|
+
* final record's, the spawn-in-progress marker's, and a preview's question to a session provider. */
|
|
76
|
+
const workspaceRecordOf = (prepared) => (prepared ? {
|
|
77
|
+
workspace: { key: prepared.discovery?.key ?? null, name: prepared.discovery?.workspace?.name ?? null, deployment: prepared.deployment ?? null, commit: prepared.discovery?.commit ?? null, resolution: prepared.resolution.revision, standalone: prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(prepared.soulEntry), repoKey: prepared.soulEntry.repoKey, commit: prepared.soulEntry.commit, ...(typeof prepared.soulEntry.package === "string" ? { name: prepared.soulEntry.name, qualifiedName: prepared.soulEntry.qualifiedName, package: { id: prepared.soulEntry.package, version: prepared.soulEntry.version, commit: prepared.soulEntry.commit, digest: prepared.soulEntry.digest, path: prepared.soulEntry.path } } : {}) }, layers: layerRows(prepared.resolution) },
|
|
78
|
+
teams: envRows(prepared.resolution.teams ?? []),
|
|
79
|
+
defaultTeam: structuredClone(prepared.resolution.defaultTeam ?? null),
|
|
80
|
+
} : {});
|
|
81
|
+
/** The soul directory a home records and its hooks and provider calls are handed (OATS_SOUL): for
|
|
82
|
+
* a workspace soul its commit's directory in the per-commit cache, by real path, never the
|
|
83
|
+
* swappable `agents/<name>/soul` pointer; else what that pointer shows now; else `soulDir`.
|
|
84
|
+
* `planned` (a spawn's preview, which may have read the soul from a temporary copy): the
|
|
85
|
+
* per-commit directory the apply will record, though it is not fetched there yet. */
|
|
86
|
+
function homeSoulTargetOf(agent, prepared, soulDir, { planned = false } = {}) {
|
|
87
|
+
if (prepared?.soulEntry?.commit) {
|
|
88
|
+
const perCommit = join(agent._dir, "souls", String(prepared.soulEntry.commit).slice(0, 12));
|
|
89
|
+
if (existsSync(join(perCommit, "soul.yaml"))) return realpathSync(perCommit);
|
|
90
|
+
if (planned) return realPathOrNearest(perCommit);
|
|
91
|
+
}
|
|
92
|
+
// Not prepared (or the cache entry is absent): still never link a swappable pointer —
|
|
93
|
+
// when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
|
|
94
|
+
try {
|
|
95
|
+
if (lstatSync(soulDir).isSymbolicLink()) {
|
|
96
|
+
const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
|
|
97
|
+
const rel = relative(soulsReal, real);
|
|
98
|
+
if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) return real;
|
|
99
|
+
}
|
|
100
|
+
} catch { /* absent souls/ or unreadable link: record the soul dir itself */ }
|
|
101
|
+
return soulDir;
|
|
102
|
+
}
|
|
103
|
+
/** The verified tree of a package module in the deployment's module store (lib/operator-dispatch.mjs
|
|
104
|
+
* ensureModuleTree), for a spawn preview's question to a session provider: no home holds it yet. */
|
|
105
|
+
async function providerTreeDefault(prepared, module) { const m = await import("./operator-dispatch.mjs"); return m.ensureModuleTree(prepared.deployment, module, prepared.lock, { remoteOptions: prepared.remoteOptions }); }
|
|
73
106
|
async function plannedSkillsDefault(prepared) { const m = await import("./instance-resolution.mjs"); return m.plannedPreparedSkills(prepared); }
|
|
74
107
|
// Capability rows for a PREPARED spawn (workspace model): the one function that
|
|
75
108
|
// turns a Resolution's modules into the row shape hooks/environment/requirements/
|
|
@@ -3140,9 +3173,11 @@ function requirementsWithArgsMessage(harness, providers, config, backend = "tmux
|
|
|
3140
3173
|
* expected to have (paneEnvironment's shape, or a function giving it, called only when a check
|
|
3141
3174
|
* needs a name the launch itself does not set); every check here reads it through the one answer
|
|
3142
3175
|
* (launchEnvironment), and says so when it is not established. */
|
|
3143
|
-
export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, noHooks = false, assertRoots, reselect = null, pane }) {
|
|
3176
|
+
export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, noHooks = false, assertRoots, reselect = null, pane, providerCheck = null }) {
|
|
3144
3177
|
assertRoots?.();
|
|
3145
3178
|
const problems = [];
|
|
3179
|
+
// (The home's session provider as it is bound below, for the preview's question to it.)
|
|
3180
|
+
let providerBound = null;
|
|
3146
3181
|
const fail = (check, code, detail) => { if (!preview) throw oatsError(code, detail); problems.push({ check, ok: false, detail, code }); };
|
|
3147
3182
|
// A recorded recipe is validated before anything is observed. A home without
|
|
3148
3183
|
// one predates recipes: there is nothing this kernel plans from.
|
|
@@ -3186,7 +3221,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
|
|
|
3186
3221
|
// The provider's own rules for this launch: the harness is one it runs, and no executable is named.
|
|
3187
3222
|
// The home's modules as they are now, under the spawn's own selection: one name has one
|
|
3188
3223
|
// meaning (E_BACKEND_AMBIGUOUS), and the harness is one the provider runs (E_BACKEND_HARNESS).
|
|
3189
|
-
const bound = homeSessionProvider(home, meta, sessionProvider.capability, sessionProvider.backend);
|
|
3224
|
+
const bound = providerBound = homeSessionProvider(home, meta, sessionProvider.capability, sessionProvider.backend);
|
|
3190
3225
|
let refusal = null;
|
|
3191
3226
|
if (!bound.problem) { try { selectSessionBackend(sessionProvider.backend, Object.values(capabilityManifests(home)).map((m) => ({ id: m.capability, manifest: m })), harness, "nothing was stopped or started"); } catch (e) { if (!isKernelCode(e?.code)) throw e; refusal = e; } }
|
|
3192
3227
|
if (bound.problem) fail("backend", "E_SESSION_START_FAILED", `${meta?.instance || instance || basename(home)} cannot be launched on session backend ${sessionProvider.backend}: ${bound.problem}; nothing was stopped or started`);
|
|
@@ -3293,9 +3328,35 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
|
|
|
3293
3328
|
const { trustHome } = sessionProvider ? { trustHome: false } : launchFolderTrust({ harness, home, meta, yolo: recipe.yolo, launch: trustLaunch, env, configEnv, launchConfig: config?.name });
|
|
3294
3329
|
const command = sessionProvider ? undefined : renderLaunchRecipe(recipe, { home, instance: instance || meta?.instance || basename(home), trustHome });
|
|
3295
3330
|
const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.harness) ? "frozen" : "config") : "config";
|
|
3331
|
+
// A preview of a launch on a session provider asks the provider what the start will ask it
|
|
3332
|
+
// (startProviderSession's askCheck): its `check`, with the launch that is planned, so a launch the
|
|
3333
|
+
// provider would refuse reads refused here and not ready. `check` only reads. `providerCheck`:
|
|
3334
|
+
// `{ sandboxSource }`, the caller's reading of the deployment's configuration (as a start's), from
|
|
3335
|
+
// the command that previews a launch; never from the start's own preview pass, which asks once
|
|
3336
|
+
// itself. Nothing is created: the allowances' paths are not made, nor the kernel's directory.
|
|
3337
|
+
const providerWarnings = [];
|
|
3338
|
+
if (preview && providerCheck && sessionProvider && providerBound?.binding && problems.every((c) => c.ok)) {
|
|
3339
|
+
try {
|
|
3340
|
+
const source = providerCheck.sandboxSource;
|
|
3341
|
+
let sandbox = { unavailable: source?.unavailable ?? "this preview did not resolve the deployment's configuration" };
|
|
3342
|
+
if (source && !source.unavailable) {
|
|
3343
|
+
const allowed = homeSandboxAllowances({ source, home: canonicalHomePath(home), moduleNames: Object.keys(isPlainObject(meta?.modules) ? meta.modules : {}) });
|
|
3344
|
+
for (const { capability, reason } of allowed.skipped ?? []) providerWarnings.push(`sandbox allowances: ${capability} adds no host: ${reason}`);
|
|
3345
|
+
sandbox = sandboxLaunchInput(allowed);
|
|
3346
|
+
// What the start refuses of the paths it would make (E_BACKEND_SANDBOX_HOST): refused here, with nothing made.
|
|
3347
|
+
const refused = sandboxWritePathsRefusal(sandbox.write);
|
|
3348
|
+
if (refused) throw refused;
|
|
3349
|
+
}
|
|
3350
|
+
const notReady = launchReadinessRefusal(providerBound.binding, { launch: plannedLaunch({ home: canonicalHomePath(home), harness, yolo: recipe.yolo, args: recipe.args, sandbox, preview: true }) });
|
|
3351
|
+
if (notReady) problems.push({ check: "backend", ok: false, detail: notReady.message, code: notReady.code });
|
|
3352
|
+
} catch (e) {
|
|
3353
|
+
if (!isKernelCode(e?.code)) throw e;
|
|
3354
|
+
problems.push({ check: "backend", ok: false, detail: e.message, code: e.code });
|
|
3355
|
+
}
|
|
3356
|
+
}
|
|
3296
3357
|
// A preview states what the start will do; the start states it in its own output.
|
|
3297
3358
|
const previewNotices = preview && !sessionProvider ? launchStartNotices(dirname(dirname(dirname(dirname(home)))), harness, command) : [];
|
|
3298
|
-
return { recipe, command, trustHome, declaredEnv, removedEnv, harness, model: model || undefined, modelSource, yolo, config, executable, executablePaneSide, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: [...(hooks.warnings || []), ...previewNotices], previewedHooks: hooks.previewed || [], volatileEnv: hooks.volatileEnv || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}), ...(hooks.dialogClaims ? { hookDialogClaims: hooks.dialogClaims } : {}) };
|
|
3359
|
+
return { recipe, command, trustHome, declaredEnv, removedEnv, harness, model: model || undefined, modelSource, yolo, config, executable, executablePaneSide, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: [...(hooks.warnings || []), ...previewNotices, ...providerWarnings], previewedHooks: hooks.previewed || [], volatileEnv: hooks.volatileEnv || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}), ...(hooks.dialogClaims ? { hookDialogClaims: hooks.dialogClaims } : {}) };
|
|
3299
3360
|
}
|
|
3300
3361
|
/** The names a package probe of `harness` depends on: where its program is found and runs, the
|
|
3301
3362
|
* home directory, and that harness's own selector. */
|
|
@@ -3408,10 +3469,11 @@ function homeTrees(home) {
|
|
|
3408
3469
|
* home's modules (lib/home-integrity.mjs: what the kernel runs, and where the home's hooks point
|
|
3409
3470
|
* the harness), the receipts, the claims and the provider calls in flight. Each is made here
|
|
3410
3471
|
* when it is missing (a deployment's first home), so that a provider that refuses a launch for
|
|
3411
|
-
* a missing one refuses a fault and never a first launch. Never derived from the home's record.
|
|
3412
|
-
|
|
3472
|
+
* a missing one refuses a fault and never a first launch. Never derived from the home's record.
|
|
3473
|
+
* `create: false`: a preview's, which names the same directory and makes nothing. */
|
|
3474
|
+
function homeProtected(home, { create = true } = {}) {
|
|
3413
3475
|
const paths = [instancesRetirementRoot(dirname(canonicalHomePath(home)))];
|
|
3414
|
-
for (const path of paths) mkdirSync(path, { recursive: true, mode: 0o700 });
|
|
3476
|
+
if (create) for (const path of paths) mkdirSync(path, { recursive: true, mode: 0o700 });
|
|
3415
3477
|
return paths;
|
|
3416
3478
|
}
|
|
3417
3479
|
function providerLaunchInput({ home, instance, recipe, env: hostEnv, removed = [], previous = null, sandbox }) {
|
|
@@ -3462,8 +3524,12 @@ const capabilityRuntimeRows = (resolvedCfg) => resolvedCfg.capabilities.map((cap
|
|
|
3462
3524
|
* `{ harness, yolo, args, sandbox, trees, protected }`. `args` are the launch configuration's own: the
|
|
3463
3525
|
* arguments a capability's hooks contribute are not known yet, and reach the launch input only.
|
|
3464
3526
|
* `trees` and `protected` are the launch input's (homeTrees, homeProtected): a provider that
|
|
3465
|
-
* would refuse a launch for either refuses it here, before a restart stops anything.
|
|
3466
|
-
|
|
3527
|
+
* would refuse a launch for either refuses it here, before a restart stops anything.
|
|
3528
|
+
* `preview`: asked by a command that creates nothing (a spawn's preview, whose home does not
|
|
3529
|
+
* exist yet; a launch's): the same paths, with nothing made, and for a home that is not there
|
|
3530
|
+
* the one tree every home has. */
|
|
3531
|
+
const plannedLaunch = ({ home, harness, yolo, args, sandbox, preview = false }) => ({ harness, yolo: yolo ?? null, args: [...(args || [])], ...(sandbox ? { sandbox } : {}),
|
|
3532
|
+
trees: preview && !existsSync(home) ? [join(home, "work")] : homeTrees(home), protected: homeProtected(home, { create: !preview }) });
|
|
3467
3533
|
/** A home's independent session receipt, read to be written again with another `runtime` → `{ path,
|
|
3468
3534
|
* baseline }`. Refused as every writer of it refuses: E_RUNTIME_ENDPOINT_UNKNOWN for a receipt that
|
|
3469
3535
|
* is missing, unreadable, of another home, or that authorises nothing. */
|
|
@@ -3774,7 +3840,7 @@ export async function spawnInstanceAsync(root, agent, o = {}) {
|
|
|
3774
3840
|
const it = spawnBody(root, agent, o);
|
|
3775
3841
|
let step = it.next();
|
|
3776
3842
|
while (!step.done) {
|
|
3777
|
-
//
|
|
3843
|
+
// Each yield hands back a promise-producing thunk; await it and feed the
|
|
3778
3844
|
// result (or throw the failure) back into the body.
|
|
3779
3845
|
try { const value = await step.value(); step = it.next(value); }
|
|
3780
3846
|
catch (e) { step = it.throw(e); }
|
|
@@ -4354,6 +4420,44 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4354
4420
|
if (suggesting) paneCwd = home;
|
|
4355
4421
|
|
|
4356
4422
|
if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
|
|
4423
|
+
// A preview of a spawn on a session provider asks the provider what the apply will ask it before
|
|
4424
|
+
// any hook runs (below, `refusedBeforeHooks`): its `check`, with the launch that is planned. A
|
|
4425
|
+
// launch the provider would refuse fails the preview with the apply's own code, as every other
|
|
4426
|
+
// refusal of a backend does; nothing is created. `check` only reads.
|
|
4427
|
+
// - The home does not exist yet: the check is handed its planned path, and the kernel's
|
|
4428
|
+
// directory (`protected`) by name, not made.
|
|
4429
|
+
// - The provider's script runs from its package's verified tree in the deployment's module
|
|
4430
|
+
// store (as `oats readiness --soul` runs it), fetched there when it is absent. A provider in
|
|
4431
|
+
// a member module runs only from a spawned home: the preview says it was not asked.
|
|
4432
|
+
// - It runs within what is left of the preview's one budget; a provider that does not answer
|
|
4433
|
+
// in it leaves the preflight a `timeout`.
|
|
4434
|
+
// A provider that declares no check has nothing to be asked, here as at the apply.
|
|
4435
|
+
let previewCheckWarning = null;
|
|
4436
|
+
if (o.preview === true && launch && provider && provider.provider?.commands?.check) {
|
|
4437
|
+
const said = `${provider.capability}'s session provider ${backend}`, notAsked = (why) => `${said} was not asked whether it can take this launch (${why}): the spawn asks it before any hook runs, and refuses what it refuses`;
|
|
4438
|
+
const module = (o.prepared.resolution?.modules || []).find((m) => m.name === provider.capability);
|
|
4439
|
+
let dir = null, unread = null;
|
|
4440
|
+
if (module?.from?.kind === "package") { try { dir = yield () => (o.providerTree ?? providerTreeDefault)(o.prepared, module); } catch (e) { unread = safeText(e?.message ?? e, 300); } }
|
|
4441
|
+
const left = preflightStarted + preflightBudgetMs - Date.now();
|
|
4442
|
+
if (module?.from?.kind !== "package") previewCheckWarning = notAsked("a provider in a member module runs only from a spawned home");
|
|
4443
|
+
else if (!dir) previewCheckWarning = notAsked(`its package's tree could not be read${unread ? `: ${unread}` : ""}`);
|
|
4444
|
+
else if (left <= 0) preflight.status = "timeout";
|
|
4445
|
+
else {
|
|
4446
|
+
const rows = capabilityRuntimeRows(resolvedCfg), row = rows.find((c) => c.id === provider.capability);
|
|
4447
|
+
// The provider's environment is the apply's: the soul directory the home will record (not a
|
|
4448
|
+
// preview's temporary copy of the soul), and the capability's level, which is the home.
|
|
4449
|
+
const planned = { agent: agent.name, instance, home, soulDir: homeSoulTargetOf(agent, o.prepared, soulDir, { planned: true }), harness, capabilityRuntime: rows, ...workspaceRecordOf(o.prepared) };
|
|
4450
|
+
const binding = { home, meta: planned, capability: provider.capability, name: backend, provider: provider.provider, moduleDir: dir, digest: null, soulId: preparedSoulIdOf(o.prepared.soulEntry),
|
|
4451
|
+
cap: { id: provider.capability, layer: row?.layer ?? "", level: row?.level ?? home, settings: isPlainObject(row?.settings) ? row.settings : {}, settingsOrigins: isPlainObject(row?.settingsOrigins) ? row.settingsOrigins : {} } };
|
|
4452
|
+
// (Never longer than the apply gives it: a check slower than its own limit is refused there.)
|
|
4453
|
+
const own = sessionProviderTimeout("check");
|
|
4454
|
+
const notReady = launchReadinessRefusal(binding, { timeoutMs: Math.min(left, own), launch: plannedLaunch({ home, harness, yolo, args: launchConfig?.args, sandbox: sandboxLaunchInput(sandbox), preview: true }) });
|
|
4455
|
+
// Ended by the budget: the preflight did not finish. Ended by its own limit: the apply's refusal.
|
|
4456
|
+
if (notReady?.timedOut && left <= own) preflight.status = "timeout";
|
|
4457
|
+
else if (notReady) throw Object.assign(oatsError(notReady.code, `${instance} would not be launched: ${notReady.message}; nothing was created`), { details: { backend, capability: provider.capability } });
|
|
4458
|
+
}
|
|
4459
|
+
preflight.elapsedMs = Date.now() - preflightStarted;
|
|
4460
|
+
}
|
|
4357
4461
|
// K6: everything a spawn decides is decided by here — and nothing has been
|
|
4358
4462
|
// touched. Branch/base for a worktree are named now (not after mkdir) so the
|
|
4359
4463
|
// preview and the apply agree on them; `o.baseRef` selects the start point.
|
|
@@ -4425,7 +4529,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4425
4529
|
const preparedSettingsOrigins = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloadOrigins?.[m.name] ?? {})]));
|
|
4426
4530
|
// The preview's warnings are strings: the launchPromptAnswers notice, then what a module declares and this kernel ignores.
|
|
4427
4531
|
// The development-channel statement is the apply's: no launch hook runs here, so the argv is unknown.
|
|
4428
|
-
const previewWarnings = [...(launchPromptNotice ? [launchPromptNotice] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution)), ...[previewReadWarning()].filter(Boolean)];
|
|
4532
|
+
const previewWarnings = [...(launchPromptNotice ? [launchPromptNotice] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution)), ...[previewReadWarning(), previewCheckWarning].filter(Boolean)];
|
|
4429
4533
|
const preparedSettings = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloads?.[m.name] && typeof o.prepared.resolution.payloads[m.name] === "object" ? o.prepared.resolution.payloads[m.name] : {})]));
|
|
4430
4534
|
return deliver({
|
|
4431
4535
|
// Team model v2: the soul's teams here (unmapped rows included) and its default — the choice a
|
|
@@ -4606,22 +4710,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4606
4710
|
// including a preview's). The record names ITS commit's directory by realpath — never
|
|
4607
4711
|
// the pointer — so a later fetch can move "current" without changing what a running
|
|
4608
4712
|
// instance's hooks see (decision 7); the OKF hook's owner pin stays valid.
|
|
4609
|
-
|
|
4610
|
-
if (o.prepared?.soulEntry?.commit) {
|
|
4611
|
-
const perCommit = join(agent._dir, "souls", String(o.prepared.soulEntry.commit).slice(0, 12));
|
|
4612
|
-
if (existsSync(join(perCommit, "soul.yaml"))) homeSoulTarget = realpathSync(perCommit);
|
|
4613
|
-
}
|
|
4614
|
-
if (homeSoulTarget === soulDir) {
|
|
4615
|
-
// Not prepared (or the cache entry is absent): still never link a swappable pointer —
|
|
4616
|
-
// when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
|
|
4617
|
-
try {
|
|
4618
|
-
if (lstatSync(soulDir).isSymbolicLink()) {
|
|
4619
|
-
const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
|
|
4620
|
-
const rel = relative(soulsReal, real);
|
|
4621
|
-
if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) homeSoulTarget = real;
|
|
4622
|
-
}
|
|
4623
|
-
} catch { /* absent souls/ or unreadable link: record the soul dir itself */ }
|
|
4624
|
-
}
|
|
4713
|
+
const homeSoulTarget = homeSoulTargetOf(agent, o.prepared, soulDir);
|
|
4625
4714
|
if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
|
|
4626
4715
|
|
|
4627
4716
|
// Skills: module skills were copied WHOLE and FLAT into <home>/.agents/skills/<skill>/
|
|
@@ -4837,11 +4926,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4837
4926
|
// rows only) and the default, recorded as EVIDENCE beside `providers` (never inside that
|
|
4838
4927
|
// capability-keyed map). A home's hooks and operations get the LIVE set (liveTeams); this is
|
|
4839
4928
|
// what they fall back to when the workspace cannot answer.
|
|
4840
|
-
const workspaceRecord = o.prepared
|
|
4841
|
-
workspace: { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) },
|
|
4842
|
-
teams: envRows(o.prepared.resolution.teams ?? []),
|
|
4843
|
-
defaultTeam: structuredClone(o.prepared.resolution.defaultTeam ?? null),
|
|
4844
|
-
} : {};
|
|
4929
|
+
const workspaceRecord = workspaceRecordOf(o.prepared);
|
|
4845
4930
|
// #796: the `worktree` hooks this spawn fires (work: worktree only), their run, and the
|
|
4846
4931
|
// in-progress marker that covers a parent killed while its spawn or worktree hooks run.
|
|
4847
4932
|
const treeHooks = work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities) : [];
|
package/lib/schedule.mjs
CHANGED
|
@@ -610,8 +610,8 @@ export function resolveScheduledAgent(ws, def) {
|
|
|
610
610
|
/** The save-time check of a local spawn job's soul (`add`, `update`): refuse what `oats spawn`
|
|
611
611
|
* would refuse. A soul already under the agents root is accepted without a child, so offline
|
|
612
612
|
* adds and stale cached souls stay accepted; any other name goes through spawn's own preview,
|
|
613
|
-
* with the job's selectors (a selector the run needs, such as its repo, would
|
|
614
|
-
* the preview's checks). */
|
|
613
|
+
* with the job's selectors (a selector the run needs, such as its repo or its yolo, would
|
|
614
|
+
* otherwise fail the preview's checks). */
|
|
615
615
|
function confirmScheduledSoul(ws, def, io) {
|
|
616
616
|
const { root, discover } = resolveScheduledAgent(ws, def);
|
|
617
617
|
if (findAgent(root, def.agent)) return;
|
|
@@ -704,7 +704,9 @@ export function workspaceSpawnContext(ws) {
|
|
|
704
704
|
catch (e) { return { kind: "local", local: null, dir: ws, error: { code: e.code || "E_WORKSPACE_SCHEMA", message: e.message } }; }
|
|
705
705
|
}
|
|
706
706
|
/** The `oats spawn` selectors a spawn job's run passes (beside its purpose, task and launch
|
|
707
|
-
*
|
|
707
|
+
* flag), its yolo among them, so a preview checks what the run will: one builder for the run
|
|
708
|
+
* and its previews. (The yolo is the run's own: a session provider's check is asked with the
|
|
709
|
+
* launch that is planned, and one that launches only in full mode refuses a job by it.)
|
|
708
710
|
* Every value travels as ONE `--flag=value` token. */
|
|
709
711
|
function spawnSelectorArgs(opts) {
|
|
710
712
|
const argv = [];
|
|
@@ -713,6 +715,7 @@ function spawnSelectorArgs(opts) {
|
|
|
713
715
|
if (opts.model) argv.push(`--model=${opts.model}`);
|
|
714
716
|
if (opts.backend) argv.push(`--backend=${opts.backend}`);
|
|
715
717
|
if (opts.repo) argv.push(`--repo=${opts.repo}`);
|
|
718
|
+
if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
|
|
716
719
|
return argv;
|
|
717
720
|
}
|
|
718
721
|
/** The kernel's own `oats spawn <agent> --preview --json` in the deployment, with the job's
|
|
@@ -751,7 +754,6 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
|
|
|
751
754
|
// the soul is the one positional, and an option-shaped one is refused.
|
|
752
755
|
if (String(agent.name).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(agent.name)} is not a soul name`, { field: "agent" });
|
|
753
756
|
const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json", ...spawnSelectorArgs(opts)];
|
|
754
|
-
if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
|
|
755
757
|
if (opts.launch === false) argv.push("--no-launch");
|
|
756
758
|
// The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
|
|
757
759
|
mkdirSync(join(stateDir(ws), "tasks"), { recursive: true });
|
|
@@ -502,7 +502,8 @@ const codeMessages = (list) => Array.isArray(list) && list.every((x) => exactKey
|
|
|
502
502
|
export function checkProviderSession(binding, input, { io, timeoutMs = sessionProviderTimeout("check") } = {}) {
|
|
503
503
|
if (!binding.provider.commands.check) return null;
|
|
504
504
|
const answer = callSessionProvider(binding, "check", input, { io, timeoutMs });
|
|
505
|
-
|
|
505
|
+
// (`timedOut`: it did not answer in the time it was given, which a preview counts against its budget.)
|
|
506
|
+
if (!answer.ok) return { unavailable: providerSaid(answer), ...(answer.timedOut ? { timedOut: true } : {}) };
|
|
506
507
|
const r = answer.result;
|
|
507
508
|
const sound = exactKeys(r, ["status", "problems"], ["warnings"]) && CHECK_STATUSES.includes(r.status) && codeMessages(r.problems) && (r.warnings === undefined || codeMessages(r.warnings)) && !(r.status === "ready" && r.problems.length);
|
|
508
509
|
if (!sound) return { unavailable: `${binding.capability}'s session provider ${binding.name} answered check with a result that is not { status, problems, warnings? } in the readiness words` };
|
|
@@ -517,12 +518,13 @@ export function checkProviderSession(binding, input, { io, timeoutMs = sessionPr
|
|
|
517
518
|
* is planned, `{ harness, yolo, args, sandbox }` as its launch input will carry them, so a provider
|
|
518
519
|
* can refuse HERE what it would refuse at the launch (a session it would sandbox whose allowances
|
|
519
520
|
* are `unavailable` or have `missing` entries: only it knows its mode), before a restart stops
|
|
520
|
-
* anything.
|
|
521
|
-
|
|
522
|
-
|
|
521
|
+
* anything. `timeoutMs`: a preview's, what is left of its budget; the refusal of a provider that
|
|
522
|
+
* did not answer in time carries `timedOut`. */
|
|
523
|
+
export function launchReadinessRefusal(binding, { io, launch, timeoutMs } = {}) {
|
|
524
|
+
const checked = checkProviderSession(binding, { home: binding.home, soul: null, settings: binding.cap.settings, ...(launch ? { launch } : {}) }, { io, ...(timeoutMs === undefined ? {} : { timeoutMs }) });
|
|
523
525
|
if (checked === null || checked.result?.status === "ready") return null;
|
|
524
526
|
const said = `${binding.capability}'s session provider ${binding.name}`;
|
|
525
|
-
if (checked.unavailable) return { code: "E_BACKEND_NOT_READY", message: `${said} is not ready: its readiness could not be read (${checked.unavailable})
|
|
527
|
+
if (checked.unavailable) return { code: "E_BACKEND_NOT_READY", message: `${said} is not ready: its readiness could not be read (${checked.unavailable})`, ...(checked.timedOut ? { timedOut: true } : {}) };
|
|
526
528
|
const own = checked.result.problems.find((x) => /^E_BACKEND_[A-Z0-9_]{1,50}$/.test(x.code));
|
|
527
529
|
return { code: own?.code ?? "E_BACKEND_NOT_READY", message: `${said} is not ready (${checked.result.status})${checked.result.problems.length ? `: ${checked.result.problems.map((x) => `${x.code}: ${x.message}`).join("; ")}` : ""}` };
|
|
528
530
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.70.
|
|
3
|
+
"version": "0.70.1",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|