@awebai/oats 0.69.21 → 0.69.23
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 +131 -23
- package/docs/capabilities.md +12 -2
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +290 -5
- package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
- package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
- package/docs/design/2026-11-19-sandboxes.md +878 -0
- package/docs/design/README.md +3 -0
- package/docs/desktop-cli-api.md +416 -72
- package/docs/desktop.md +377 -148
- package/docs/implementation.md +15 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +117 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +47 -4
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +8 -6
- package/docs/release-notes/v0.69.22.md +221 -0
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +51 -22
- package/docs/tui.md +48 -7
- package/docs/upgrading.md +17 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +39 -2
- package/lib/core.mjs +25 -14
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-lifecycle.mjs +19 -15
- package/lib/instance-listing.mjs +18 -10
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +4 -1
- package/lib/servers.mjs +123 -13
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/above-tested.mjs +3 -2
- package/packages/client/capability-list.mjs +69 -0
- package/packages/client/capability-origin.mjs +54 -0
- package/packages/client/cli-adapter.mjs +9 -1
- package/packages/client/deployment-data.mjs +7 -2
- package/packages/client/deployment-panel.mjs +4 -1
- package/packages/client/home-board.mjs +50 -0
- package/packages/client/instance-pin.mjs +28 -0
- package/packages/client/instance-record-outcome.mjs +31 -0
- package/packages/client/instance-tree.mjs +96 -24
- package/packages/client/keymap.mjs +16 -3
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +11 -3
- package/packages/client/roster-sections.mjs +10 -7
- package/packages/client/soul-role.mjs +44 -0
- package/packages/client/waiting-on-you.mjs +10 -0
- package/packages/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/actions.mjs +11 -4
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/main.mjs +16 -2
- package/packages/tui/lib/model.mjs +48 -5
- package/packages/tui/lib/store.mjs +28 -2
- package/skills/oats-getting-started/SKILL.md +97 -24
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
|
@@ -0,0 +1,878 @@
|
|
|
1
|
+
# Sandboxes: boundaries declared in the workspace, started by `oats sync`
|
|
2
|
+
|
|
3
|
+
**Status:** contracts decided, 2026-11-19. The product owner's side and aweb's maintainers agreed
|
|
4
|
+
C1–C10 and C3b as written at 0849ef12, with aweb's maintainers' four changes, which
|
|
5
|
+
the product owner's side accepted: the registry setting (C3, C6), a keyed `seat` (C4), the receipt of the host's
|
|
6
|
+
`remove-member` (C6) and the credential-mount probe (C8). The connector half of C9
|
|
7
|
+
stays designed only. Nothing is built yet. **Revised after review round 1** (marked
|
|
8
|
+
"(r1)" below): existing host homes, lifecycle calls made inside a sandbox, C4's
|
|
9
|
+
per-act wire shapes and provider selection, shared team aliases, mount overlap, the
|
|
10
|
+
first use's GitHub API route, managed server registrations, and the missing refusal
|
|
11
|
+
codes. Both sides decided those, with two precisions from aweb's maintainers, and decided the
|
|
12
|
+
`forge` egress role for the GitHub API. **Revised again after review round 2** (marked
|
|
13
|
+
"(r2)"): every real agent bind is checked, `status` mutates nothing, the routed
|
|
14
|
+
spawn's exact sequence and seat binding, the seat's service descriptor, provider state
|
|
15
|
+
scoped per deployment, a team not yet created, and the seat option's key. Both sides
|
|
16
|
+
decided the r2 additions, with `sandbox-state-orphaned`. **Revised after review round
|
|
17
|
+
3** (marked "(r3)"): the apply is bound to the preview's `decision.revision`; the seat
|
|
18
|
+
plan needs only the spawn key; the spawn hook learns the apply's key; the kernel keeps
|
|
19
|
+
the full routed request for replay; mint recovery; hardlinked credentials; the
|
|
20
|
+
resolvers are host infrastructure; the protected-sources input shape; and the `forge`
|
|
21
|
+
role's Host guarantee corrected to what a TLS pass-through can enforce. Both sides
|
|
22
|
+
decided the r3 contracts, with the domain-fronting risk statement and the pending
|
|
23
|
+
request's custody. **Revised after review round 4** (marked "(r4)"): the apply
|
|
24
|
+
evidence `bind` acts on, and the fence that keeps a replay away from an interrupted
|
|
25
|
+
delivery. **Revised after the round-4 delta read** (marked "(r4d)"): a seat is
|
|
26
|
+
released only on proof that no home can hold it, and the readiness and ordering text
|
|
27
|
+
that follows from that. A later change to a contract goes back to
|
|
28
|
+
both sides (the lane map's "Contract changes" line). When this record and a reference
|
|
29
|
+
page disagree after it is built, the reference page wins.
|
|
30
|
+
|
|
31
|
+
## The goal
|
|
32
|
+
|
|
33
|
+
One machine runs `oats sync` on a deployment, and the sandboxes that deployment lists
|
|
34
|
+
are built and started, with their boundaries declared once in the workspace. The first
|
|
35
|
+
use is scheduled knowledge-base ingestor agents on a cloud machine: they read untrusted
|
|
36
|
+
content, so they must not reach the engineers' agents, credentials or network.
|
|
37
|
+
|
|
38
|
+
**Done means:** on a Linux machine with Docker, a workspace that declares one sandbox,
|
|
39
|
+
and a deployment whose local file lists it, `oats sync` builds and starts the sandbox.
|
|
40
|
+
A workspace schedule whose `runsOn` names that machine spawns its soul inside the
|
|
41
|
+
sandbox, with an identity minted on the host. The agent can message only its own team,
|
|
42
|
+
reach only the declared destinations and read only the declared credentials. Retiring
|
|
43
|
+
it removes its identity from the team. Delisting the sandbox stops it and destroys
|
|
44
|
+
nothing. All of this is shown by a live rehearsal and by the tests pinned in each spec.
|
|
45
|
+
|
|
46
|
+
## Decided with the product owner
|
|
47
|
+
|
|
48
|
+
- **A team is membership and messaging. A sandbox is the boundary** (its local state,
|
|
49
|
+
credentials and egress). In v1 a team has at most one sandbox, so the two coincide by
|
|
50
|
+
default. They stay separate primitives: a later layout can split one team across
|
|
51
|
+
sandboxes by relaxing validation, with no change to the file format and no identity
|
|
52
|
+
remint (decided 2026-11-19, agreeing to aweb's maintainers' requirement of 2026-11-18).
|
|
53
|
+
- **Credentials in v1 are read-only files** mounted into the sandbox. Every agent in it
|
|
54
|
+
can read them, which is acceptable with one team per sandbox (decided 2026-11-19).
|
|
55
|
+
- **OATS does not create or delete machines in v1.** Sync builds and starts listed
|
|
56
|
+
sandboxes on a machine that already exists. Creating machines comes later, as a
|
|
57
|
+
provider capability (decided 2026-11-19).
|
|
58
|
+
- **Both broker contracts are designed in this effort**: one for secrets, one for
|
|
59
|
+
connectors (decided 2026-11-18). Credential files remain the way to start.
|
|
60
|
+
- **Messaging isolation is by server:** each isolated team gets its own aweb server
|
|
61
|
+
with federation outbound off. This needs no aw contract change (decided 2026-11-17).
|
|
62
|
+
- **Kept as they are:** the word "team"; the schedule file, with `runsOn` naming the
|
|
63
|
+
machine and no lease; a sandbox does not list its own souls; there is no workspace
|
|
64
|
+
list of shared deployments.
|
|
65
|
+
|
|
66
|
+
## What exists today, and what this builds on
|
|
67
|
+
|
|
68
|
+
- `container/agent` is one team's container. It runs every agent, sshd, the wake
|
|
69
|
+
broker and `oats host run` as one user, with its own OATS deployment at
|
|
70
|
+
`/state/deploy`, reached from the host as an OATS server over SSH
|
|
71
|
+
([container.md](../container.md)).
|
|
72
|
+
- Its egress component has five base roles (aweb, registry, secrets, logs, signer), of
|
|
73
|
+
which a policy may declare a subset (#1955); teamctl's profile declares four of them
|
|
74
|
+
(all but signer). It adds two optional external roles, `source` (`https://github.com`)
|
|
75
|
+
and `model` (`https://api.anthropic.com`). It does not take arbitrary origins
|
|
76
|
+
([egress README](../../container/agent/egress/README.md)). The Compose boundary probe
|
|
77
|
+
takes a `namePrefix` and reports `--json` receipts (#1958).
|
|
78
|
+
- aweb's team bundle, `deploy/team` (`teamctl`, aweb's maintainers), renders one
|
|
79
|
+
`deployment.yaml` into an aweb server, the egress proxy and the agent container. It
|
|
80
|
+
sets `AWEB_FEDERATION_OUTBOUND` to `off` by default. `teamctl start` probes the
|
|
81
|
+
boundary, brings up the agent, and exits 3 on purpose with the agents held: it admits
|
|
82
|
+
no seat.
|
|
83
|
+
- Seats: today a container agent takes a retained seat (`identity.source`) that the
|
|
84
|
+
operator provisioned. oats.aweb mints an instance's identity with
|
|
85
|
+
`aw init --join-from <root> --join-team <team>`, which works only where the team key
|
|
86
|
+
is, and at retire it prints `aw id team remove-member` rather than running it.
|
|
87
|
+
- The kernel has no Docker code, and must not gain any: provider behaviour belongs in a
|
|
88
|
+
capability.
|
|
89
|
+
- `oats-workspace.yaml` and `oats-local.yaml` are closed schemas. An older kernel
|
|
90
|
+
refuses a new root key with `E_WORKSPACE_SCHEMA` and, for the workspace file, an
|
|
91
|
+
"upgrade OATS" hint.
|
|
92
|
+
- A `run: spawn` schedule spawns on the host its `runsOn` matches (`host.name`). A
|
|
93
|
+
remote spawn (`--server`) runs preview and apply on the server's kernel, and the home
|
|
94
|
+
lives there.
|
|
95
|
+
|
|
96
|
+
## The design
|
|
97
|
+
|
|
98
|
+
### Who does what
|
|
99
|
+
|
|
100
|
+
| Piece | Owner | Does |
|
|
101
|
+
| --- | --- | --- |
|
|
102
|
+
| Declaration, validation, placement, CLI verbs, sync | the kernel (lane:product) | Reads `sandboxes:`, refuses the ways round the boundary, decides where a soul runs, calls the sandbox provider, and reports. No Docker. |
|
|
103
|
+
| Sandbox provider | a new capability, `oats.aweb-sandbox`, in the oats-aweb package | Turns a sandbox into teamctl input, runs teamctl, registers the sandbox as a server, prepares the in-sandbox deployment, mints and delivers seats, removes members at retire. |
|
|
104
|
+
| The team bundle | teamctl, aweb `deploy/team` (aweb's maintainers) | Three new inputs: the credential mount, the protected-sources file and the `forge` role (C8). |
|
|
105
|
+
| The agent image and Compose | `container/agent` (lane:juan) | A read-only credential mount fragment (C8). |
|
|
106
|
+
|
|
107
|
+
### Placement
|
|
108
|
+
|
|
109
|
+
A soul runs in sandbox S when its resolved default team is S's team. Otherwise it runs
|
|
110
|
+
on the host, as today. Placement is derived in v1; explicit placement, if it ever comes,
|
|
111
|
+
is declared in the workspace and never in a machine's local file.
|
|
112
|
+
|
|
113
|
+
- On a host that lists S and has it started, a spawn of such a soul (by hand, or by a
|
|
114
|
+
schedule tick) is routed into S, as a remote spawn through S's server registration.
|
|
115
|
+
S1 builds on #1912's floor (lane:juan, held): the task goes on stdin, the apply is
|
|
116
|
+
bound to its preview and keyed, and a host below 0.69.15 is refused. This costs
|
|
117
|
+
nothing, because the sandbox's kernel must already be the release with `sandboxes`.
|
|
118
|
+
S1 may be built now, but does not merge before #1912. If #1912 is withdrawn, S1 itself requires the same
|
|
119
|
+
three properties of the sandbox's kernel, rather than relying on today's fallbacks.
|
|
120
|
+
- On a host that does not list S, the spawn is refused with `E_SANDBOX_NOT_HERE`, naming
|
|
121
|
+
S and the local key that would list it. A sandboxed soul never falls back to the host.
|
|
122
|
+
- Inside S, its deployment refuses to spawn any soul not placed in S
|
|
123
|
+
(`E_SANDBOX_PLACEMENT`).
|
|
124
|
+
|
|
125
|
+
### The clock
|
|
126
|
+
|
|
127
|
+
There is one clock per machine, and it is the host's. A schedule runs on the host its
|
|
128
|
+
`runsOn` names, and its spawn is routed into the sandbox. The in-sandbox deployment
|
|
129
|
+
registers no deployment for ticking, so its `oats host run` keeps only the resume sweep
|
|
130
|
+
and the ordered stop, and ticks nothing. This replaces the container's clock; it does
|
|
131
|
+
not add a second one.
|
|
132
|
+
|
|
133
|
+
### Identities
|
|
134
|
+
|
|
135
|
+
Every instance in a sandbox has its own identity, minted on the host at spawn and
|
|
136
|
+
removed at retire. The team's controller key and team key stay on the host, under the
|
|
137
|
+
operator's account, and never enter the container.
|
|
138
|
+
|
|
139
|
+
1. Before routing the spawn, the provider mints the instance's identity on the host
|
|
140
|
+
from the host's root for the sandbox team (`roots[T]`), into a private staging
|
|
141
|
+
directory. Where the sandbox team's registry is private, the host deployment sets
|
|
142
|
+
`settings.oats.aweb.registry` for the mint (C3).
|
|
143
|
+
2. It delivers the identity's authority files (the same list retained seats copy
|
|
144
|
+
today) and a seat descriptor into the sandbox's state, at
|
|
145
|
+
`/state/seats/<seat-id>/`, and deletes the staging copy. The seat ID is derived from
|
|
146
|
+
the routed spawn's idempotency key, so a seat directory names one spawn, never an
|
|
147
|
+
instance name that can be reused (r2).
|
|
148
|
+
3. The remote spawn takes that seat as a one-use seat (C6). The agent's own private key
|
|
149
|
+
is then inside the container, which is what aweb's answer requires: there is no
|
|
150
|
+
alternative short of a grant home, and that route is untested.
|
|
151
|
+
4. At retire, the routed retire removes the home and releases the seat. The provider
|
|
152
|
+
then runs `aw id team remove-member` on the host, where the controller key is,
|
|
153
|
+
instead of printing it.
|
|
154
|
+
|
|
155
|
+
The exact order of a routed spawn, with the value each step binds (r2, r3):
|
|
156
|
+
|
|
157
|
+
1. The kernel makes the spawn's idempotency key (`spawnKey`) and asks the provider for
|
|
158
|
+
a seat plan (`plan`, target `seat`, with `instance: {soul, spawnKey}`). The plan is
|
|
159
|
+
read-only and needs no instance name: it answers the seat ID (derived from
|
|
160
|
+
`spawnKey`), its path and the `spawnProvider` options. Its `planRevision` fences
|
|
161
|
+
only the sandbox's provider state and `spawnKey`.
|
|
162
|
+
2. The kernel runs the remote preview **with those options**. The preview chooses the
|
|
163
|
+
instance name when the caller gave none (a schedule passes `--purpose`, not
|
|
164
|
+
`--name`), and answers `decision.revision`, `D`, the hash of the whole decision
|
|
165
|
+
that the apply's `--expect-decision` must match, as #1912 requires. The in-sandbox
|
|
166
|
+
kernel admits a preview that carries a seat option without reading the seat; only
|
|
167
|
+
an apply needs it.
|
|
168
|
+
3. **Before anything is minted, the kernel keeps the whole routed request** (r3,
|
|
169
|
+
contract): server, `spawnKey`, `D`, the exact argv and provider options, and the
|
|
170
|
+
task text, in `~/.oats/remote/<server>/pending/<spawnKey>.json` (0600, under the
|
|
171
|
+
operator account, beside today's remote snapshots). It holds the task text, which
|
|
172
|
+
#1912 took off argv for a reason, so: it is removed as soon as its seat settles
|
|
173
|
+
(bound, released, or refused terminally); it is never copied into a receipt, a log
|
|
174
|
+
or the ledger; and readiness reports one older than 24 hours as
|
|
175
|
+
`sandbox-pending-stale`, naming the spawn key, never the task. S1 pins a test that
|
|
176
|
+
its content never reaches a receipt, a log or a readiness line.
|
|
177
|
+
4. The kernel runs `seat` with the plan's revision, `spawnKey` and
|
|
178
|
+
`instance: {name, soul, decision: D}`. The name and `D` are inputs to the mint, not
|
|
179
|
+
part of the plan's revision. The provider writes the ledger entry (`minting`, with
|
|
180
|
+
`spawnKey`, `D`, the alias it will mint and the seat ID) before it mints, mints,
|
|
181
|
+
records the certificate ID, delivers, and moves the entry to `delivered`.
|
|
182
|
+
5. The kernel runs the remote apply with `--expect-decision D` and
|
|
183
|
+
`--idempotency-key spawnKey`, from the kept request, with the same provider options
|
|
184
|
+
as the preview. No provider input changes between 2 and 5.
|
|
185
|
+
6. The kernel passes the apply's own answer to the provider (`bind`, C4), which acts
|
|
186
|
+
on it by this table (r4, contract):
|
|
187
|
+
|
|
188
|
+
| The apply's answer | Evidence | The seat |
|
|
189
|
+
| --- | --- | --- |
|
|
190
|
+
| Success, or the keyed replay of one | the home's `capabilityMeta["oats.aweb"].seat`, `{seatApi:1, seatId, certificateId, spawnKey}`, written by oats.aweb's spawn hook once the seat is connected, matching the ledger entry | `active` |
|
|
191
|
+
| `E_DECISION_STALE` | the kernel's key recovery found no home holding `spawnKey` and refused before placing anything; the descriptor admits only that key (C6), so no home holds the seat | released (`spawn-failed`) |
|
|
192
|
+
| `E_REQUIRED_HOOK_FAILED` or `E_HOOK_ENVIRONMENT_CONTRACT` whose details carry no `unconfirmed: true` (r4d) | the spawn's rollback confirmed its home is gone, so no home holds the seat, whatever the hook did before it failed (oats.aweb's `seat-binding` refusal arrives this way) | released (`spawn-failed`) |
|
|
193
|
+
| `E_IDEMPOTENCY_CONFLICT` (r4d) | a home already holds `spawnKey` under another decision and may hold the seat | stays `delivered` |
|
|
194
|
+
| `E_SPAWN_INCOMPLETE`, a hook failure with `unconfirmed: true`, a failed or uncertain seat connect, any other refusal, or no answer | none of these proves that no home holds the seat | stays `delivered` |
|
|
195
|
+
|
|
196
|
+
A seat is released only on proof that no home can hold it (r4d): releasing revokes
|
|
197
|
+
the member, which is right for a seat that no home holds, used or not, and wrong
|
|
198
|
+
for one a live home holds. Before such a release the provider deletes any copy at
|
|
199
|
+
`/state/seats/<seat-id>/` through the server route. If that deletion cannot be
|
|
200
|
+
confirmed, the entry stays `delivered`, the kept request is deleted (its refusal
|
|
201
|
+
was terminal), and readiness reports `sandbox-seat-unsettled`. The server route's
|
|
202
|
+
"copy deleted" answer comes from the sandbox, so it is untrusted input: it can
|
|
203
|
+
release only a seat of that sandbox's own ledger, and a false "deleted" can at
|
|
204
|
+
worst revoke that sandbox's own member, never another's (r4d). `ok: false` alone is
|
|
205
|
+
never evidence, and the provider reads no field of a refusal beyond its code and
|
|
206
|
+
`unconfirmed`. S1 pins that the routed apply's answer, and its keyed replay, carry
|
|
207
|
+
the new home's `capabilityMeta`; that the routed answer carries the host's refusal
|
|
208
|
+
code and its `unconfirmed` detail unchanged; that `E_DECISION_STALE` is raised
|
|
209
|
+
only when no home holds the key, before any placement or hook; and that a required
|
|
210
|
+
hook's failure carries `unconfirmed: true` whenever the rollback could not confirm
|
|
211
|
+
the home gone. S2 pins the meta oats.aweb writes and a `bind` test per row,
|
|
212
|
+
including a prior home holding the key under another decision
|
|
213
|
+
(`E_IDEMPOTENCY_CONFLICT`: the member is kept) and a failed copy deletion.
|
|
214
|
+
7. **The kernel settles a `delivered` seat** (r3, r4): `oats sandbox reconcile`, and
|
|
215
|
+
so sync, first runs the provider's `reconcile` act, which settles interrupted mints
|
|
216
|
+
and deliveries (below) and answers the ledger's seats. Only then does it replay a
|
|
217
|
+
kept request, and only one whose ledger entry that answer shows durably
|
|
218
|
+
`delivered`: a kept request whose entry is `minting` or `mint-uncertain` is never
|
|
219
|
+
applied or replayed, and one whose seat was released is deleted. Each replay is
|
|
220
|
+
unchanged, keyed by its `spawnKey`, and its answer goes to `bind` as in 6. A replay of an apply that was
|
|
221
|
+
never sent is that apply, with its task, and a stale `D` refuses it terminally. The
|
|
222
|
+
provider never builds or replays a spawn itself. Absence of the instance's name, or
|
|
223
|
+
an unused seat directory, is never evidence. A `delivered` seat with no kept request
|
|
224
|
+
stays `delivered`, and readiness reports `sandbox-seat-unsettled`.
|
|
225
|
+
|
|
226
|
+
**A mint whose outcome is uncertain (r3, contract).** An entry found in `minting` was
|
|
227
|
+
interrupted, and the registry may hold an identity whose result was never recorded, or
|
|
228
|
+
a seat copy may already have landed in the sandbox before the `delivered` write (r4).
|
|
229
|
+
The next mutating act reads the certificate ID from the staging copy, if one is there,
|
|
230
|
+
into the entry before it deletes that copy, and moves the entry to `mint-uncertain`.
|
|
231
|
+
With a certificate ID, it first deletes any copy at `/state/seats/<seat-id>/` through
|
|
232
|
+
the server route, then releases the seat (reason `spawn-failed`): no apply was sent
|
|
233
|
+
for it, because the apply follows the `delivered` write and its kept request is
|
|
234
|
+
fenced (step 7). If that copy cannot be confirmed deleted, the entry stays
|
|
235
|
+
`mint-uncertain` and is reported as unsettled. A pinned test kills the provider
|
|
236
|
+
between the copy landing and the `delivered` write, then runs reconcile and an
|
|
237
|
+
otherwise no-op sync: no home is created, the copy is gone and the member is
|
|
238
|
+
removed. Without one, the entry stays `mint-uncertain`, readiness
|
|
239
|
+
reports `sandbox-seat-unsettled` naming the alias, and the operator checks the team's
|
|
240
|
+
members. A replay of that `seat` key answers `unknown` and never mints again. A test
|
|
241
|
+
pins a kill after registration and before the receipt.
|
|
242
|
+
|
|
243
|
+
### Lifecycle calls made inside a sandbox (r1)
|
|
244
|
+
|
|
245
|
+
Minting and removing identities need the host's keys, so in v1 the host is the only
|
|
246
|
+
place a sandboxed instance is spawned from, and the host finishes every retire:
|
|
247
|
+
|
|
248
|
+
- **Spawn inside the sandbox.** The in-sandbox deployment has no root for the team.
|
|
249
|
+
Its kernel accepts a spawn only when it carries a host-delivered seat (the routed
|
|
250
|
+
spawn's `identity.seat`, C4 and C6). Any other spawn there, by an agent or by hand,
|
|
251
|
+
is refused with `E_SANDBOX_PLACEMENT`, reason `spawn-from-host`, whose remedy is to
|
|
252
|
+
spawn from the host. A sandboxed agent that needs a helper asks for one; it cannot
|
|
253
|
+
start one.
|
|
254
|
+
- **Retire inside the sandbox** (`oats retire --self`, or a retire run there by hand)
|
|
255
|
+
works as today: the home goes, and oats.aweb prints the `remove-member` command it
|
|
256
|
+
cannot run. The host completes it through the provider's `reconcile` act (C4), which
|
|
257
|
+
`oats sandbox start` and sync run for each listed sandbox, under the sandbox's lock.
|
|
258
|
+
`status` only observes (r2).
|
|
259
|
+
- **The sandbox's report is untrusted input.** Reconcile reads the sandbox's instances
|
|
260
|
+
through the server route, and that report comes from inside the boundary. So it can
|
|
261
|
+
only move seats of that sandbox's own ledger toward `released`, and it triggers no
|
|
262
|
+
other act. A seat is released by reconcile only when all of these hold: its entry is
|
|
263
|
+
`active` (never `minting`, `delivered` or `removal-uncertain`), the report lists no
|
|
264
|
+
home holding its seat ID, and its seat directory is gone. The release's receipt
|
|
265
|
+
records that the sandbox's report drove it (reason `reconcile`), so it can be told
|
|
266
|
+
from a retire's removal. A test pins that a report naming a seat of another
|
|
267
|
+
sandbox, or an unknown certificate, changes nothing.
|
|
268
|
+
- **Retire from the host** (`oats retire <name> --server sandbox-<name>`, or the
|
|
269
|
+
kernel routing a retire of a sandboxed instance) runs the remote retire, then the
|
|
270
|
+
provider's `release` act (C4) for that seat at once (reason `retired`).
|
|
271
|
+
- **The ledger** lives in the provider's state on the host, scoped to the deployment
|
|
272
|
+
(C7): `~/.oats/sandboxes/<deployment-key>/<sandbox>/seats.json`, one entry per seat:
|
|
273
|
+
seat ID, `spawnKey`, `D`, instance, alias, certificate ID, team, state (`minting`,
|
|
274
|
+
`mint-uncertain`, `delivered`, `active`, `removing`, `released`,
|
|
275
|
+
`removal-uncertain`), and the receipt
|
|
276
|
+
of each step. It outlives the remote home, and is the only evidence
|
|
277
|
+
`remove-member` acts on.
|
|
278
|
+
- **Removal is written before it runs (r2).** The provider moves an entry to
|
|
279
|
+
`removing`, durably, before it calls `remove-member`, then to `released` or
|
|
280
|
+
`removal-uncertain` with the receipt. An entry found in `removing` was interrupted:
|
|
281
|
+
it becomes `removal-uncertain`, and is never removed again automatically (C6).
|
|
282
|
+
- **Compensation.** If the mint succeeds but delivery fails, the provider releases
|
|
283
|
+
the seat at once (reason `spawn-failed`) and deletes any delivered copy. After
|
|
284
|
+
delivery, only step 6 or 7 above settles the seat.
|
|
285
|
+
|
|
286
|
+
### Credentials (v1)
|
|
287
|
+
|
|
288
|
+
The workspace names a sandbox's credentials. The host's local file says where each
|
|
289
|
+
value is. The provider mounts each named file read-only at `/run/oats-credentials/<name>`
|
|
290
|
+
in that sandbox's agent container only. Nothing else gets a mount, and an undeclared or
|
|
291
|
+
missing credential refuses the start. A capability inside the sandbox reads a credential
|
|
292
|
+
through its own file setting (for example `settings.oats.okf.github-token-file`), which
|
|
293
|
+
the provider writes into the in-sandbox local file from the host's settings for that
|
|
294
|
+
sandbox.
|
|
295
|
+
|
|
296
|
+
**No other mount may expose them (r1, r2).** A credential source is a regular file,
|
|
297
|
+
read through its real path; a symlink is resolved, and one that leads to anything but
|
|
298
|
+
a regular file is refused (`E_SANDBOX_CREDENTIAL`, reason `not-a-file`). The bind
|
|
299
|
+
source is the resolved path. A credential source with more than one hard link is
|
|
300
|
+
refused too (reason `hardlinked`, r3, contract): a second link could sit inside another
|
|
301
|
+
sandbox's work directory, where no path check sees it. This applies to every source in
|
|
302
|
+
the host's `credentials`, used or not, at every sandbox's start; the container's own
|
|
303
|
+
acceptance already refuses a public CA with more than one link. A pinned test puts a
|
|
304
|
+
hard link of one sandbox's credential in another sandbox's work directory.
|
|
305
|
+
|
|
306
|
+
The provider derives a protected inventory, in two parts:
|
|
307
|
+
|
|
308
|
+
- **Hard-denied:** the host's team roots (`roots`), the seat staging directory, the
|
|
309
|
+
provider's own state (`~/.oats/sandboxes`) and the host deployment directory. No
|
|
310
|
+
bind may equal, contain or lie inside one of these, a declared credential included:
|
|
311
|
+
a credential source inside a team root is refused.
|
|
312
|
+
- **Credential sources:** every source in the host's `credentials`, whether a listed
|
|
313
|
+
sandbox declares it or not (an unused one, or one of a delisted sandbox, included),
|
|
314
|
+
and every other sandbox's state, work and mirror directories. Only the exact
|
|
315
|
+
read-only bind of a credential this sandbox declares, at
|
|
316
|
+
`/run/oats-credentials/<name>`, is excepted.
|
|
317
|
+
|
|
318
|
+
The check runs on **every bind of the real agent container**, before any agent runs
|
|
319
|
+
(r2): the provider renders the teamctl deployment and checks each agent bind source in
|
|
320
|
+
the rendered configuration (the state, work and mirror directories, the harness login
|
|
321
|
+
directory from `agents.secrets`, the authorized-keys file, and the credential binds),
|
|
322
|
+
then the container's own mount acceptance checks the started agent's actual mounts
|
|
323
|
+
against the same inventory before any seat is admitted (C8). Today's boundary probe
|
|
324
|
+
substitutes an empty login directory, so it cannot stand in for this check. The
|
|
325
|
+
started-agent check reads the agent container by its exact identity (the container ID
|
|
326
|
+
teamctl's start returned, or an ownership label as in #1958), never by name alone: a
|
|
327
|
+
same-named container that is not this sandbox's refuses admission (a pinned negative
|
|
328
|
+
in S2 and S3). A failing
|
|
329
|
+
bind refuses the start (`E_SANDBOX_MOUNT`, reason `overlap`, naming both paths), and so
|
|
330
|
+
do two sandboxes sharing any such directory. Pinned negative tests: a work or mirror
|
|
331
|
+
directory containing an unused credential; one containing a delisted sandbox's
|
|
332
|
+
credential; a harness login directory pointing at a team root.
|
|
333
|
+
|
|
334
|
+
**The first use's GitHub API route: the `forge` role (decided).** `source` admits
|
|
335
|
+
`https://github.com` only, and a knowledge proposer also calls `https://api.github.com`
|
|
336
|
+
(OKF's own setup check requires both). Both sides decided a third external role for
|
|
337
|
+
it:
|
|
338
|
+
|
|
339
|
+
- `forge` selects exactly `https://api.github.com`, defaults to false and, like the
|
|
340
|
+
other external roles, needs `egress.external.resolvers`. Its wrapper input is
|
|
341
|
+
`egress.external.forge` (teamctl's schema), its policy entry
|
|
342
|
+
`externalTargets.forge.origin`, and the component checks the exact origin again.
|
|
343
|
+
- **What it guarantees (r3, contract: corrects a decided item).** External roles are
|
|
344
|
+
TLS pass-through: the proxy routes on the SNI and never sees the encrypted
|
|
345
|
+
Host/`:authority` (egress README, "Optional external source and model roles").
|
|
346
|
+
So `forge`'s guarantee is the external roles' own: exact SNI `api.github.com` and a
|
|
347
|
+
validated public destination. The probe tests what the proxy enforces: an
|
|
348
|
+
unlisted SNI is refused, and `api.github.com` resolves only to the proxy. **The
|
|
349
|
+
risk that remains:** with SNI `api.github.com` admitted, the connection reaches
|
|
350
|
+
whatever GitHub's front end for that name serves to a Host it accepts; domain
|
|
351
|
+
fronting is not refused here. So the one-repository credential is the control that
|
|
352
|
+
matters. A Host
|
|
353
|
+
that differs from the SNI inside the encrypted stream, on a `forge` or another
|
|
354
|
+
admitted connection, is not refused by this component; whether GitHub serves it is
|
|
355
|
+
GitHub's. Refusing it would need TLS interception, which this record does not
|
|
356
|
+
propose. This statement replaced the earlier "SNI/Host mismatch" item; both sides
|
|
357
|
+
decided it in r3, with the risk statement above.
|
|
358
|
+
- The external-egress image test and the boundary probe name the hosts that stay
|
|
359
|
+
refused: `uploads.github.com`, `codeload.github.com`, `raw.githubusercontent.com`,
|
|
360
|
+
`objects.githubusercontent.com` and `gist.github.com`.
|
|
361
|
+
- **The credential is scoped to one repository, as a requirement.** With a token the
|
|
362
|
+
API can write, and the boundary limits services, not accounts. So the sandbox's
|
|
363
|
+
proposal credential (`knowledge-propose` in C1's example) must be scoped to the one
|
|
364
|
+
knowledge-base repository, as a push credential is today. The egress README's role
|
|
365
|
+
section, this section and the first use's setup steps all say so.
|
|
366
|
+
- C1's `egress` set becomes `{model, source, forge}`. `forge` has its own feature,
|
|
367
|
+
`sandbox-egress-forge`, because a kernel that already has `sandboxes` refuses the new
|
|
368
|
+
value through C1's closed set: a workspace uses `forge` only once every one of its
|
|
369
|
+
hosts lists that feature.
|
|
370
|
+
- Order: the egress component and teamctl first, on lane:juan (aweb's maintainers launch
|
|
371
|
+
that developer once this record is final); then C1's value, on the kernel side.
|
|
372
|
+
|
|
373
|
+
### What sync does
|
|
374
|
+
|
|
375
|
+
After its current steps (the lock, package souls, the automation snapshot), `oats sync`
|
|
376
|
+
reconciles each sandbox the local file lists:
|
|
377
|
+
|
|
378
|
+
- not built, or built from other inputs: build and start it;
|
|
379
|
+
- stopped: start it;
|
|
380
|
+
- running with the same inputs: no infrastructure change (`action: "none"`).
|
|
381
|
+
|
|
382
|
+
Whatever the action, sync then reconciles each listed, running sandbox's seats
|
|
383
|
+
(`oats sandbox reconcile`'s work: the provider's `reconcile` act, then the replay of
|
|
384
|
+
each kept request whose entry it answers durably `delivered`, as in step 7 of the
|
|
385
|
+
Identities section) (r4d), so a self-retire is completed by the next sync even when nothing else changed
|
|
386
|
+
(r3). A pinned test: a self-retire, then an otherwise no-op sync, removes the member.
|
|
387
|
+
|
|
388
|
+
A sandbox declared in the workspace but not listed locally is never started. A sandbox
|
|
389
|
+
listed earlier and now delisted is stopped, never destroyed. The provider keeps the
|
|
390
|
+
last declaration it started each sandbox with in its own state, so a sandbox whose
|
|
391
|
+
workspace entry was removed together with its local listing is still stopped, from
|
|
392
|
+
that record (r1). `oats sync --plan` shows
|
|
393
|
+
these actions and performs none. A failed sandbox does not undo the lock. It is reported
|
|
394
|
+
in `problems`, and sync exits nonzero.
|
|
395
|
+
|
|
396
|
+
teamctl's exit 3 ("agents held") is the expected end of a start. The provider reports
|
|
397
|
+
it as `ready`: in this design seats are admitted per spawn, never at start.
|
|
398
|
+
|
|
399
|
+
### Images
|
|
400
|
+
|
|
401
|
+
In v1 the agent and egress image digests are host facts in the teamctl deployment file.
|
|
402
|
+
teamctl already requires the digest form. The image is not yet published: the release
|
|
403
|
+
job is disabled pending the registry decision. Once the release lane publishes it, the
|
|
404
|
+
digest moves into the lock with the release. That is a lock format change, proposed
|
|
405
|
+
then, not here.
|
|
406
|
+
|
|
407
|
+
## The contracts (decided)
|
|
408
|
+
|
|
409
|
+
### C1. Workspace `sandboxes:` (new root key)
|
|
410
|
+
|
|
411
|
+
```yaml
|
|
412
|
+
teams:
|
|
413
|
+
ingest-team: { team: "ingest:example.org" }
|
|
414
|
+
souls:
|
|
415
|
+
knowledge/knowledge-ingestor: { default: ingest-team }
|
|
416
|
+
sandboxes:
|
|
417
|
+
ingest:
|
|
418
|
+
team: ingest-team # one sandbox per team in v1
|
|
419
|
+
egress: [model, source, forge] # closed set, added to the base routes
|
|
420
|
+
credentials: [sources-read, knowledge-propose] # names only
|
|
421
|
+
description: Knowledge ingestors # optional
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
- The name matches `^[a-z0-9]$|^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$`. `team` must be a label in
|
|
425
|
+
this file's `teams:`, and no other sandbox may name it (v1).
|
|
426
|
+
- `egress` is a subset of `{model, source, forge}` (`forge` behind feature
|
|
427
|
+
`sandbox-egress-forge`), because those are the external roles the egress component
|
|
428
|
+
supports. Adding another destination is a change to the egress
|
|
429
|
+
component, not a free-form list.
|
|
430
|
+
- `credentials` names match `^[a-z0-9][a-z0-9-]{0,62}$`, and are distinct.
|
|
431
|
+
- **A team not yet created (r2).** A shared team may omit its provider id (declared,
|
|
432
|
+
not created). A sandbox may name such a team: the workspace stays valid, so other
|
|
433
|
+
hosts are not refused. Its start refuses (`E_SANDBOX_TEAM`, reason
|
|
434
|
+
`team-not-created`), and so does a routed spawn, with the existing remedy: its owner
|
|
435
|
+
runs `oats aweb setup`, then commits the id. The id is never inferred from the label
|
|
436
|
+
or an active team. Until it is set, C2's checks compare the label.
|
|
437
|
+
- `team` is required. `egress` and `credentials` are optional and default to `[]`;
|
|
438
|
+
`egress` entries are distinct. A duplicate in either list is refused (reason
|
|
439
|
+
`duplicate-entry`) (r1).
|
|
440
|
+
- It is closed (`additionalProperties: false`), like every workspace block. An older
|
|
441
|
+
kernel refuses the file with `E_WORKSPACE_SCHEMA` and its existing "upgrade OATS"
|
|
442
|
+
hint, which is the error that tells existing deployments what to do.
|
|
443
|
+
- **Adding it breaks every older host of the workspace, not only the sandbox host.**
|
|
444
|
+
Every host reads the shared file, so the first commit that adds `sandboxes:` makes
|
|
445
|
+
each host on an older kernel refuse the whole workspace. A workspace adds the block
|
|
446
|
+
only once every one of its hosts runs the release that has feature `sandboxes`. The
|
|
447
|
+
person who commits it checks that first: the kernel cannot see another person's host.
|
|
448
|
+
The release notes' Upgrade section and the reference page that owns the workspace
|
|
449
|
+
file ([workspaces.md](../workspaces.md)) both say this, and give the check:
|
|
450
|
+
`oats version --json` on each host lists `sandboxes`.
|
|
451
|
+
- Feature `sandboxes` in `oats version --json`.
|
|
452
|
+
|
|
453
|
+
### C2. The three ways round a sandbox are refused (aweb's maintainers' edge cases)
|
|
454
|
+
|
|
455
|
+
All are refused when the workspace file is read, with `E_WORKSPACE_SCHEMA` and a reason
|
|
456
|
+
code:
|
|
457
|
+
|
|
458
|
+
1. **A sandboxed team as a soul's extra team** (`teams: [ingest-team]`): refused, reason
|
|
459
|
+
`sandboxed-team-not-default`. The `"any"` value means every shared team without a
|
|
460
|
+
sandbox. An explicitly declared bridge is not in v1.
|
|
461
|
+
2. **A sandboxed team reached through a wildcard or the default:** a `"*"` or
|
|
462
|
+
`<member>/*` entry whose `default` is a sandboxed team, and a workspace `defaultTeam`
|
|
463
|
+
that is one, are refused (reason `sandboxed-team-by-wildcard`). A sandboxed team is
|
|
464
|
+
reached only through a named soul (`<member>/<soul>`).
|
|
465
|
+
3. **A local override:** an `oats-local.yaml` cannot move a sandboxed soul. Local files
|
|
466
|
+
have no soul-to-team mapping today, and a local `defaultTeam` already loses to a
|
|
467
|
+
soul's `souls:` default. A local team may not reuse a sandboxed team's label or
|
|
468
|
+
provider id (reason `sandboxed-team-local`).
|
|
469
|
+
4. **A shared alias (r1):** two shared labels may today name one provider id. A
|
|
470
|
+
sandboxed team's provider id must be named by exactly one shared label; another
|
|
471
|
+
shared label with that id is refused (reason `sandboxed-team-alias`). Every check
|
|
472
|
+
above, and placement, compare provider ids, never labels alone, so two sandboxes
|
|
473
|
+
cannot name one team through two labels either (reason `sandbox-team-taken`).
|
|
474
|
+
|
|
475
|
+
### C3. `oats-local.yaml`: `sandboxes` and `credentials` (new root keys)
|
|
476
|
+
|
|
477
|
+
```yaml
|
|
478
|
+
host: { name: cloud-1 }
|
|
479
|
+
sandboxes: [ingest] # the sandboxes this machine runs
|
|
480
|
+
credentials:
|
|
481
|
+
sources-read: { fromFile: /srv/oats-operator/credentials/sources-read }
|
|
482
|
+
knowledge-propose: { fromFile: /srv/oats-operator/credentials/knowledge-propose }
|
|
483
|
+
settings:
|
|
484
|
+
oats.aweb-sandbox:
|
|
485
|
+
sandboxes:
|
|
486
|
+
ingest:
|
|
487
|
+
deployment: /srv/oats-operator/ingest/deployment.yaml # teamctl host facts
|
|
488
|
+
settings:
|
|
489
|
+
oats.aweb: { registry: https://registry.example.org } # private registry only
|
|
490
|
+
oats.okf: { github-token-file: /run/oats-credentials/knowledge-propose }
|
|
491
|
+
oats.aweb: { registry: https://registry.example.org } # the host-side mint (C6)
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
- `sandboxes` lists distinct names that the workspace declares. An unknown name is
|
|
495
|
+
refused (`E_WORKSPACE_SCHEMA`, reason `sandbox-unknown`), a duplicate likewise
|
|
496
|
+
(`duplicate-entry`), and so is a listed sandbox with no `host.name` (reason
|
|
497
|
+
`sandbox-host-name-required`) (r1).
|
|
498
|
+
- `credentials` uses the kernel's existing `fromFile` form. A listed sandbox whose
|
|
499
|
+
declared credential has no source here refuses its start, naming the credential.
|
|
500
|
+
- The teamctl file holds infrastructure only (images, network, ports, state directory,
|
|
501
|
+
limits). The provider refuses a file that sets a boundary field the workspace owns
|
|
502
|
+
(`team.id`, the role booleans `egress.external.source`, `.model` and `.forge`,
|
|
503
|
+
`aweb.federationOutbound`): boundaries are declared once. The refusal is
|
|
504
|
+
`E_SANDBOX_DEPLOYMENT`, reason `boundary-field`, naming the field (r1). The
|
|
505
|
+
resolvers the external roles need, `egress.external.resolvers`, are host
|
|
506
|
+
infrastructure and stay in the teamctl file; a sandbox whose workspace egress names
|
|
507
|
+
an external role and whose file gives no resolvers refuses its start (reason
|
|
508
|
+
`resolvers-required`) (r3, contract). The provider writes the role booleans from
|
|
509
|
+
the workspace. Example: `egress: { external: { resolvers: [1.1.1.1, 9.9.9.9] } }`
|
|
510
|
+
in the teamctl file, with C1's `egress: [model, source, forge]`.
|
|
511
|
+
- **A private registry.** oats.aweb refuses an ambient `AWID_REGISTRY_URL`
|
|
512
|
+
(awebai/oats-aweb#284), so where the sandbox team's registry is private the setting
|
|
513
|
+
is written twice: `settings.oats.aweb.registry` on the host deployment, for the mint
|
|
514
|
+
and for `remove-member` (C6), and the same key in the sandbox's `settings`, which the
|
|
515
|
+
provider writes into the in-sandbox local file. Without the in-sandbox one, the
|
|
516
|
+
in-sandbox spawn refuses with `registry-setting-required`.
|
|
517
|
+
|
|
518
|
+
### C3b. `oats-local.yaml` inside a sandbox: `sandbox: { self: <name> }` (new root key)
|
|
519
|
+
|
|
520
|
+
The provider writes it into the in-sandbox deployment's local file. It is a contract of
|
|
521
|
+
its own because a kernel reads it:
|
|
522
|
+
|
|
523
|
+
- `self` must name a sandbox the workspace declares. That deployment then spawns only
|
|
524
|
+
souls placed in that sandbox, and refuses others with `E_SANDBOX_PLACEMENT`.
|
|
525
|
+
- It may not be combined with `sandboxes:` (a sandbox runs no sandboxes),
|
|
526
|
+
`credentials:` (credentials reach it as mounts only), local `teams:` or local
|
|
527
|
+
`defaultTeam`. Each combination is refused with `E_WORKSPACE_SCHEMA`, reason
|
|
528
|
+
`sandbox-self-conflict`.
|
|
529
|
+
- An older kernel refuses the key as unknown. That is why the agent image's kernel is
|
|
530
|
+
the release that has feature `sandboxes`.
|
|
531
|
+
|
|
532
|
+
### C4. The kernel–provider hook: `sandbox`
|
|
533
|
+
|
|
534
|
+
A new capability hook event, `sandbox`.
|
|
535
|
+
|
|
536
|
+
**Which capability provides it (r1).** Sandbox acts run at deployment level, with no
|
|
537
|
+
soul. The candidates are the capabilities the workspace's `defaults` compose (the
|
|
538
|
+
same resolution a spawn uses, without a soul's layer) whose manifest declares the
|
|
539
|
+
`sandbox` hook. Exactly one must exist: none refuses any sandbox act with
|
|
540
|
+
`E_SANDBOX_PROVIDER`, reason `none`; two or more, reason `ambiguous`, naming them. Its
|
|
541
|
+
settings are its manifest defaults, then the workspace defaults, then the host's
|
|
542
|
+
`settings.<capability>` in `oats-local.yaml`, merged as for a spawn.
|
|
543
|
+
|
|
544
|
+
**The call.** The kernel runs the hook with `OATS_SANDBOX_ACT` set to `plan`, `start`,
|
|
545
|
+
`stop`, `status`, `reconcile`, `seat`, `bind` or `release`, one JSON request on stdin, and reads one JSON
|
|
546
|
+
answer on stdout. The kernel holds a per-sandbox lock around every act but `plan` and
|
|
547
|
+
`status`, so two mutating acts on one sandbox never run at once (a second gets
|
|
548
|
+
`E_LIFECYCLE_BUSY`). The lock, the plan revisions and the idempotency keys are all
|
|
549
|
+
scoped to the deployment and the sandbox (C7's deployment key) (r2). A
|
|
550
|
+
hook that exits nonzero, times out or prints anything but one valid answer is read as
|
|
551
|
+
`state: "unknown"` with problem `E_SANDBOX_PROVIDER`, reason `hook-failed`.
|
|
552
|
+
|
|
553
|
+
**Every request** carries:
|
|
554
|
+
|
|
555
|
+
```json
|
|
556
|
+
{"sandboxApi":1,"act":"start","sandbox":"ingest","host":"cloud-1",
|
|
557
|
+
"team":{"label":"ingest-team","id":"ingest:example.org"},
|
|
558
|
+
"egress":["model","source"],
|
|
559
|
+
"credentials":[{"name":"sources-read","path":"/srv/…"}],
|
|
560
|
+
"workspace":{"url":"…","commit":"…","lock":"<sha256>"}}
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
and by act:
|
|
564
|
+
|
|
565
|
+
| Act | Extra request fields | Answer fields beyond the envelope |
|
|
566
|
+
| --- | --- | --- |
|
|
567
|
+
| `plan` | `target`: `start`, `stop`, `reconcile`, `seat`, `bind` or `release`; for target `seat`, `instance: {soul, spawnKey}`; for `bind` and `release`, the `instance` fields of that act | `planRevision`, `actions: [{step, detail}]`; for target `seat` also `seat: {id, path}` and `spawnProvider: {capability, options: {<key>: <value>}}` |
|
|
568
|
+
| `start`, `stop`, `reconcile` | `planRevision`, `idempotencyKey` | `server`; for `reconcile`, `seats` as in `status` |
|
|
569
|
+
| `status` | none | `server`, `seats: [{seatId, instance, alias, certificateId, state}]` |
|
|
570
|
+
| `seat` | `planRevision`, `idempotencyKey`, `instance: {name, soul, spawnKey, decision}` (`decision` is `D`, the remote preview's `decision.revision`) | `seat: {id, path, alias, certificateId, team}` |
|
|
571
|
+
| `bind` | `planRevision`, `idempotencyKey`, `instance: {name, spawnKey}`, `apply`: the routed apply's answer as the kernel received it | `seat: {id, certificateId, state}` |
|
|
572
|
+
| `release` | `planRevision`, `idempotencyKey`, `instance: {name, seatId}`, `reason`: `retired` or `spawn-failed` | `seat: {id, certificateId, state}` |
|
|
573
|
+
|
|
574
|
+
**The envelope** of every answer:
|
|
575
|
+
|
|
576
|
+
```json
|
|
577
|
+
{"sandboxApi":1,"act":"…","state":"ready|stopped|absent|failed|unknown|stale",
|
|
578
|
+
"receipts":[{"step":"render|probe|start|register|deploy|mint|deliver|remove","ok":true,"detail":"…"}],
|
|
579
|
+
"problem":{"code":"…","reason":"…","message":"…","remedy":"…"}}
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
- `plan` and `status` are read-only: they change no state, delete no staging and remove
|
|
583
|
+
no member (r2). Every other act mutates, and runs under the lock.
|
|
584
|
+
- `plan` is read-only. Its `planRevision` binds the request's inputs and the
|
|
585
|
+
provider's own state for that sandbox (and, for `seat` and `release`, that
|
|
586
|
+
instance's ledger entry).
|
|
587
|
+
- **The provider owns revisions and receipts.** It checks `planRevision` on every
|
|
588
|
+
act that carries one, and answers `state: "stale"` with a fresh plan in `plan`; the
|
|
589
|
+
kernel reports that as `E_PLAN_STALE` with the fresh plan, on the pattern of `oats
|
|
590
|
+
instance stop`. It keeps each `idempotencyKey`'s receipt in its state on the host,
|
|
591
|
+
and the same key replays that receipt and changes nothing.
|
|
592
|
+
- `seat` mints and delivers one instance's seat, in the order the Identities section
|
|
593
|
+
gives. A replay of its key returns the same seat, or `unknown`, and never mints a
|
|
594
|
+
second identity. The kernel passes the seat plan's `spawnProvider` to the final
|
|
595
|
+
preview and to the apply alike, as `--provider <capability> <key>=<value>`, one per
|
|
596
|
+
option, so the kernel names no messaging provider. Dotted keys nest, so oats.aweb
|
|
597
|
+
answers `{capability: "oats.aweb", options: {"identity.seat": "<path>"}}`, which sets
|
|
598
|
+
its `identity.seat` (C6) (r2).
|
|
599
|
+
- `bind` and `reconcile` settle seats as the Identities and Lifecycle sections say:
|
|
600
|
+
`bind` from the routed apply's answer or the kernel's keyed replay of it (for
|
|
601
|
+
`delivered` seats), `reconcile` from the sandbox's untrusted report (for `active`
|
|
602
|
+
seats) and the interrupted-mint rule. The provider runs no spawn. The
|
|
603
|
+
staging sweep for a killed hook runs in the mutating acts only: under the lock no
|
|
604
|
+
`seat` can be running, so any staging copy found is a leftover.
|
|
605
|
+
- An act whose outcome is uncertain answers `unknown`, never `ready`.
|
|
606
|
+
|
|
607
|
+
### C5. CLI and JSON
|
|
608
|
+
|
|
609
|
+
- `oats sandbox status [--json]`, `oats sandbox start|stop <name> (--plan | --plan-revision <r> --idempotency-key <k>)`.
|
|
610
|
+
- `oats sandbox status --json` answers
|
|
611
|
+
`{sandboxApi:1, host, sandboxes:[{name, team:{label,id}, listedHere, state, server, egress, credentials:[{name, source:"present"|"missing"}], problems}]}`.
|
|
612
|
+
- `oats sandbox start|stop <name> --plan --json` answers
|
|
613
|
+
`{sandboxApi:1, sandbox, act, planRevision, actions}`; the apply answers
|
|
614
|
+
`{sandboxApi:1, sandbox, act, state, server, receipts, problems}`, and a stale
|
|
615
|
+
revision refuses `E_PLAN_STALE` with the fresh plan in its detail (r1).
|
|
616
|
+
- `oats sync --json` gains `sandboxes` with the same entries plus `action`
|
|
617
|
+
(`build|start|stop|none`). The field is additive, so `syncApi` stays 1.
|
|
618
|
+
- `oats status --json` gains `placement: {sandbox, seatId}` on each instance placed in
|
|
619
|
+
one; `seatId` is the seat its home took (r2).
|
|
620
|
+
- `oats sandbox status --json`'s entries also carry `seats` (as C4's `status`), and
|
|
621
|
+
`oats sandbox reconcile <name> (--plan | --plan-revision <r> --idempotency-key <k>)`
|
|
622
|
+
runs on its own what sync runs for each sandbox: the `reconcile` act, then the
|
|
623
|
+
replays of the kept requests whose entries it answers durably `delivered` (r2, r3,
|
|
624
|
+
r4d).
|
|
625
|
+
- **That these are additive must be shown, not assumed.** The readers of sync's answer
|
|
626
|
+
are `packages/desktop/server/workspace-sync.mjs`,
|
|
627
|
+
`packages/desktop/renderer/workspace-sync-view.mjs`,
|
|
628
|
+
`packages/client/deployment-data.mjs` and `packages/client/workspace-cli.mjs`. The
|
|
629
|
+
readers of the status answer are the client's roster readers and the warm reader. S1
|
|
630
|
+
lists every reader it finds, with file and line, and pins one test per reader feeding
|
|
631
|
+
it an answer with the new fields. If a reader refuses unknown fields, the change is
|
|
632
|
+
not additive: that answer's API version goes up, and the reader changes first, in its
|
|
633
|
+
own PR.
|
|
634
|
+
|
|
635
|
+
### C6. oats.aweb settings and behaviour
|
|
636
|
+
|
|
637
|
+
- `identity.seat` (new): an absolute path to a one-use seat delivered by the host. The
|
|
638
|
+
spawn copies it the way it copies `identity.source`, takes no retained-seat lock, and
|
|
639
|
+
deletes the delivered copy after connecting. It is refused together with
|
|
640
|
+
`identity.source` and with global mode. A preview reads nothing from it; an apply
|
|
641
|
+
needs it.
|
|
642
|
+
- **The seat descriptor (r2).** The retained route reads its service from the
|
|
643
|
+
source's `workspace.yaml`, which is not an authority file. A delivered seat instead
|
|
644
|
+
carries `seat.json`, written by the host at mint:
|
|
645
|
+
`{seatApi:1, seatId, spawnKey, service, team, alias, certificateId}`, where `service`
|
|
646
|
+
is the aweb origin of the sandbox's own server (the egress `aweb` role's origin).
|
|
647
|
+
The spawn reads its service from that descriptor only, never from `OATS_AWEB_URL` or
|
|
648
|
+
a copied coordination workspace, and checks it: `team` equals the team the spawn
|
|
649
|
+
resolved, `alias` equals the instance name, `spawnKey` equals the apply's key, and
|
|
650
|
+
`service` is a plain https origin. The apply's key reaches the spawn hook through a
|
|
651
|
+
new, generic hook variable, `OATS_SPAWN_IDEMPOTENCY_KEY`, set by the kernel on a
|
|
652
|
+
keyed apply and absent otherwise (r3, contract: the hook environment; S1 sets it and
|
|
653
|
+
pins it, S2 consumes it). An unkeyed apply with `identity.seat` is refused (reason
|
|
654
|
+
`seat-binding`, field `spawnKey`); the provider never takes the expected key from
|
|
655
|
+
the descriptor it validates. A missing, malformed or contradictory descriptor
|
|
656
|
+
refuses the spawn (reason `seat-binding`, naming the field). The host's registry pin
|
|
657
|
+
is a separate setting (C3), never the service.
|
|
658
|
+
- Retire, for an identity minted by the host for a sandbox: the host runs
|
|
659
|
+
`aw id team remove-member` with the controller key it holds, and reports it, from
|
|
660
|
+
the routed retire or from reconcile (the Lifecycle section). It
|
|
661
|
+
removes by the certificate ID that the mint recorded, never by alias. It removes only
|
|
662
|
+
an identity listed in the provider's ledger of seats this host minted for this
|
|
663
|
+
sandbox. An identity it did not mint is never removed, and is reported instead. It
|
|
664
|
+
uses the host's configured registry pin (`settings.oats.aweb.registry`, C3), and
|
|
665
|
+
records its receipt in the retire's meta. A failure, or an outcome it cannot be sure
|
|
666
|
+
of, keeps today's recorded command and warning, and is never retried automatically.
|
|
667
|
+
- Between mint and delivery, the instance's private key sits in the host's staging
|
|
668
|
+
directory (0700, under the operator account). `seat` deletes the staging copy on
|
|
669
|
+
every path: success, a failed mint, a failed delivery, a timeout and an interrupted
|
|
670
|
+
hook. The next mutating act (C4) finds and removes a copy left by a killed hook, and
|
|
671
|
+
reports it; `status` only reports it (r2). One test per path pins this.
|
|
672
|
+
- `oats.aweb-sandbox` (new capability, same package): its settings are
|
|
673
|
+
`sandboxes.<name>.deployment` and `sandboxes.<name>.settings` (C3).
|
|
674
|
+
|
|
675
|
+
### C7. The sandbox's server registration
|
|
676
|
+
|
|
677
|
+
The provider registers each started sandbox as server `sandbox-<name>`, using the
|
|
678
|
+
existing Docker-context SSH relay from container.md.
|
|
679
|
+
|
|
680
|
+
- It uses only the fields `servers.json` accepts today (`sshHost`, `workspace`,
|
|
681
|
+
`oatsPath`, `path`), so an older kernel still reads the file. Anything else the
|
|
682
|
+
provider keeps goes in its own state, never in `servers.json`.
|
|
683
|
+
- The `sshHost` alias lives in an OpenSSH file the provider owns,
|
|
684
|
+
`~/.oats/sandboxes/ssh_config`, which holds the relay, the per-sandbox operator key
|
|
685
|
+
it generates and the known-hosts file it provisions from the sandbox's host key. The
|
|
686
|
+
operator adds one `Include` of that file to their own SSH configuration once. Readiness
|
|
687
|
+
reports `sandbox-ssh-include-missing` until they have.
|
|
688
|
+
- The `sandbox-` prefix is reserved. A new `oats server add|connect` with that prefix is
|
|
689
|
+
refused (`E_SERVER_INVALID`, reason `reserved-prefix`). A `sandbox-*` server that is
|
|
690
|
+
already registered is reported by `oats sandbox status`, not refused: refusing
|
|
691
|
+
configuration that was accepted before would itself be a contract change. The provider
|
|
692
|
+
will not adopt or overwrite it, and that sandbox's start refuses, naming the server
|
|
693
|
+
(`E_SANDBOX_SERVER`, reason `server-taken`).
|
|
694
|
+
- **Its own registration is not "already registered" (r1).** The provider records
|
|
695
|
+
each registration it made in its state, with the `servers.json` entry it wrote. A
|
|
696
|
+
`sandbox-<name>` server that matches its record is its own: a restart reuses it, and
|
|
697
|
+
stop and delisting keep it and the record, so the sandbox can start again. Only a
|
|
698
|
+
`sandbox-*` server with no matching record counts as taken.
|
|
699
|
+
- **Scoped to the deployment (r2).** `servers.json`, the SSH file and the provider's
|
|
700
|
+
state are per OS user, and two deployments of that user may each declare a sandbox
|
|
701
|
+
of the same name. So the provider's state lives under a deployment key, the first 16
|
|
702
|
+
hex digits of the SHA-256 of the host deployment directory's real path:
|
|
703
|
+
`~/.oats/sandboxes/<deployment-key>/<sandbox>/`. The registration record names its
|
|
704
|
+
deployment key. A `sandbox-<name>` server recorded for another deployment key is
|
|
705
|
+
never reused, stopped or overwritten: this deployment's start refuses
|
|
706
|
+
(`E_SANDBOX_SERVER`, reason `server-owned-elsewhere`, naming the other deployment
|
|
707
|
+
directory). The public name stays `sandbox-<name>`.
|
|
708
|
+
- **A moved deployment.** Moving or renaming the deployment directory changes its key
|
|
709
|
+
and orphans its sandboxes' ledger, lock and receipts. Readiness reports
|
|
710
|
+
`sandbox-state-orphaned` when provider state under another key holds a sandbox this
|
|
711
|
+
deployment lists, naming the old key. It is never adopted automatically; the remedy
|
|
712
|
+
names moving the directory back, or the manual adoption step S2 specifies.
|
|
713
|
+
|
|
714
|
+
### C8. teamctl and the container (aweb's maintainers)
|
|
715
|
+
|
|
716
|
+
- **Credential mount:** a new teamctl input, `agents.credentials`, a map from name to a
|
|
717
|
+
host file. It is rendered as read-only binds at `/run/oats-credentials/<name>` through a
|
|
718
|
+
new `container/agent/compose.agent.credentials.yaml` fragment. teamctl's
|
|
719
|
+
`agents.secrets` stays the harness login only.
|
|
720
|
+
- **Probe:** the boundary probe asserts that each credential mount is read-only, that
|
|
721
|
+
it lies only under `/run/oats-credentials`, and that no undeclared credential path is
|
|
722
|
+
mounted. Its receipt joins the probe's `--json` receipts (#1958).
|
|
723
|
+
- **Protected sources (r1, r2, r3):** the provider writes one JSON file per start,
|
|
724
|
+
`{"protectedSourcesApi":1, "hardDenied":[<path>], "credentialSources":[<path>],
|
|
725
|
+
"declaredBinds":[{"source":<path>,"target":"/run/oats-credentials/<name>"}]}`, with
|
|
726
|
+
real paths, and gives it to teamctl as a new input, `agents.protectedSourcesFile`
|
|
727
|
+
(contract: teamctl's schema, aweb's maintainers). teamctl passes it to the container's
|
|
728
|
+
mount acceptance, which takes those three parts and, on the started
|
|
729
|
+
agent's actual mounts, asserts that no bind equals, contains or lies inside a
|
|
730
|
+
protected path, the declared credential binds being the only exception to the
|
|
731
|
+
credential-source part. It runs before any seat is admitted.
|
|
732
|
+
- **Optional, later:** a slimmer profile without Secrets and Logs. v1 runs with
|
|
733
|
+
teamctl's four base routes.
|
|
734
|
+
- teamctl's changes are these three inputs: `agents.credentials`,
|
|
735
|
+
`agents.protectedSourcesFile` and `egress.external.forge`. OATS reads its exit codes
|
|
736
|
+
as they are.
|
|
737
|
+
|
|
738
|
+
### C9. Broker contracts (designed now, built against the first real provider)
|
|
739
|
+
|
|
740
|
+
Both follow aweb's three rules. An agent never reads or exports a value. Approval is a
|
|
741
|
+
state with a reference, and the same request is resubmitted under the same request ID.
|
|
742
|
+
Authority, custody, approval, where execution happens, audit and withholding all stay
|
|
743
|
+
with the provider. Inside a sandbox, an agent reaches a broker through the sandbox's
|
|
744
|
+
egress routes only.
|
|
745
|
+
|
|
746
|
+
- **Secrets:** `oats credential list [--json]` shows only the names the caller is
|
|
747
|
+
granted. `oats credential use <name> --action <action> --request-id <id> [--input-file <f>] --json`
|
|
748
|
+
answers `{requestId, state: "done"|"awaiting-approval"|"refused"|"unknown"|"withheld", approvalRef?, result?}`.
|
|
749
|
+
There is no verb that returns a value. A capability implements the contract through a
|
|
750
|
+
`credential-broker` hook with the same request and answer.
|
|
751
|
+
- **Connectors:** a sandbox may list `connectors: [<name>]` in C1, a later optional
|
|
752
|
+
key. `oats connector call <name> <operation> --request-id <id> [--input-file <f>] --json`
|
|
753
|
+
takes the same outcome states, through a `connector-broker` hook. aweb has no
|
|
754
|
+
connectors broker built or filed, and whether one is planned is for aweb's maintainers to say. The
|
|
755
|
+
shape is offered so that a provider-neutral gateway can implement it. It stays
|
|
756
|
+
designed only, and is not built, until aweb's maintainers say whether aweb plans a connectors
|
|
757
|
+
broker and a provider exists.
|
|
758
|
+
- **Order:** both contracts are agreed in this record. Each is built when its first real
|
|
759
|
+
provider ships, and checked against that provider's interface before it is released.
|
|
760
|
+
This keeps the product owner's decision to design both now, and aweb's maintainers' point that a public
|
|
761
|
+
contract must not take its shape from one unshipped product.
|
|
762
|
+
- **What S4's spec settles before it is built (r1),** each a contract both sides
|
|
763
|
+
agree: the `credential list` JSON and its hook request; how the broker capability
|
|
764
|
+
is selected, and the no-provider refusal; how the caller and its grant are bound
|
|
765
|
+
to a request; the scope of a request ID, and what a resubmission with the same ID
|
|
766
|
+
but a different payload gets; and how `result` is kept free of secret values.
|
|
767
|
+
Agreement on this outline is not permission for a provider to choose those.
|
|
768
|
+
- **A change the provider forces is a contract decision.** If checking against the
|
|
769
|
+
first real provider shows the agreed shape must change, the change goes back to both
|
|
770
|
+
sides as a contract decision before it is built. It is never a doc edit.
|
|
771
|
+
|
|
772
|
+
### C10. Readiness reports; the acts refuse
|
|
773
|
+
|
|
774
|
+
`oats readiness` reports, and refuses nothing. Its new items are:
|
|
775
|
+
|
|
776
|
+
- `sandbox-listed-not-running`;
|
|
777
|
+
- `sandbox-credential-missing`;
|
|
778
|
+
- `sandbox-host-agents`: a deployment that lists a sandbox has host-placed instances,
|
|
779
|
+
running or stopped;
|
|
780
|
+
- `sandbox-provider-missing`;
|
|
781
|
+
- `sandbox-ssh-include-missing`;
|
|
782
|
+
- `sandbox-seat-unsettled`: a `mint-uncertain` seat, with or without a certificate
|
|
783
|
+
ID (r4d: one whose delivered copy could not be confirmed deleted stays here); a
|
|
784
|
+
`delivered` seat with no kept request, including one whose release waits on a copy
|
|
785
|
+
deletion that could not be confirmed; or a `delivered` seat whose last replay
|
|
786
|
+
answered `E_IDEMPOTENCY_CONFLICT` or `E_SPAWN_INCOMPLETE` (r2, r3, r4d). A pinned
|
|
787
|
+
negative: a known certificate ID whose copy deletion fails gives no replay, no home,
|
|
788
|
+
and this item;
|
|
789
|
+
- `sandbox-state-orphaned`: provider state under another deployment key for a
|
|
790
|
+
sandbox this deployment lists (r2);
|
|
791
|
+
- `sandbox-pending-stale`: a kept routed request older than 24 hours, named by its
|
|
792
|
+
spawn key, never its task (r3).
|
|
793
|
+
|
|
794
|
+
The refusals belong to the acts:
|
|
795
|
+
|
|
796
|
+
| Condition | Refused by | Code |
|
|
797
|
+
| --- | --- | --- |
|
|
798
|
+
| Listed sandbox, no provider | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_PROVIDER` |
|
|
799
|
+
| A declared credential with no source, or a missing source file | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL` |
|
|
800
|
+
| A host-placed spawn in a deployment that lists a sandbox | `oats spawn`, a schedule's spawn | `E_SANDBOX_HOST_AGENT` |
|
|
801
|
+
| Starting, restarting or resuming a host-placed home there (r1) | `oats session start`, the resume sweep | `E_SANDBOX_HOST_AGENT` |
|
|
802
|
+
| A running or unreadable host-placed home when a sandbox starts (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_HOST_AGENT` |
|
|
803
|
+
| A spawn inside a sandbox without a host-delivered seat (r1) | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT`, `spawn-from-host` |
|
|
804
|
+
| A teamctl file that sets a boundary field (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `boundary-field` |
|
|
805
|
+
| A mount that overlaps a protected path, or shared sandbox state (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_MOUNT`, `overlap` |
|
|
806
|
+
| A credential source that is not a regular file (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `not-a-file` |
|
|
807
|
+
| A credential source with more than one hard link (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `hardlinked` |
|
|
808
|
+
| An external egress role with no resolvers in the teamctl file (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `resolvers-required` |
|
|
809
|
+
| An unkeyed apply carrying `identity.seat` (r3) | the in-sandbox apply | `seat-binding` (oats.aweb), field `spawnKey` |
|
|
810
|
+
| `sandbox-<name>` registered by someone else (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-taken` |
|
|
811
|
+
| `sandbox-<name>` owned by another deployment (r2) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-owned-elsewhere` |
|
|
812
|
+
| The sandbox's team has no provider id yet (r2) | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_TEAM`, `team-not-created` |
|
|
813
|
+
| A delivered seat with a missing or contradictory descriptor (r2) | the in-sandbox apply | `seat-binding` (oats.aweb) |
|
|
814
|
+
| No provider, or more than one (r1) | every sandbox act | `E_SANDBOX_PROVIDER`, `none` or `ambiguous` |
|
|
815
|
+
| A sandboxed soul on a host that does not list or run its sandbox | `oats spawn`, a schedule's spawn | `E_SANDBOX_NOT_HERE` |
|
|
816
|
+
| A soul not placed in this sandbox, inside it | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT` |
|
|
817
|
+
|
|
818
|
+
**Why `E_SANDBOX_HOST_AGENT`.** The controller key and the credential sources sit under
|
|
819
|
+
the account that runs the deployment, because that account mints the seats. A host-side
|
|
820
|
+
agent of the same deployment would run as that account and could read them. So in v1, a
|
|
821
|
+
deployment that lists a sandbox runs every agent in a sandbox. Agents that belong on the
|
|
822
|
+
host run from another deployment, under another OS user. This replaces checking file
|
|
823
|
+
modes against users, which cannot be proved from inside one account.
|
|
824
|
+
|
|
825
|
+
## Left out of v1
|
|
826
|
+
|
|
827
|
+
- Creating or deleting machines.
|
|
828
|
+
- Several sandboxes for one team, and explicit placement.
|
|
829
|
+
- A bridge soul between a sandboxed team and another team.
|
|
830
|
+
- Human IDs by default and `oats sandbox adopt`. These wait on aweb's maintainers' decision
|
|
831
|
+
on reversing "strictly opt-in" (#1665). Adoption is specified once
|
|
832
|
+
those are settled.
|
|
833
|
+
- Kubernetes. The provider contract (C4) is platform-neutral, and v1's provider is
|
|
834
|
+
Compose through teamctl.
|
|
835
|
+
- Publishing the image, and its digest in the lock.
|
|
836
|
+
|
|
837
|
+
## Alternatives rejected
|
|
838
|
+
|
|
839
|
+
- **A groups block with its own soul list:** it writes the soul-to-team mapping twice.
|
|
840
|
+
- **Sandbox fields inside team entries:** no named container would remain to list, build
|
|
841
|
+
or show.
|
|
842
|
+
- **`hostedBy: everyone` for containers:** Docker could start on a laptop that never
|
|
843
|
+
asked for it.
|
|
844
|
+
- **A sandbox that lists its own souls and gets an automatic team:** rejected by the product owner.
|
|
845
|
+
- **Docker in the kernel:** the kernel stays runtime-neutral; the provider owns
|
|
846
|
+
containers.
|
|
847
|
+
- **The container's own clock beside the host's:** two owners of one schedule.
|
|
848
|
+
- **Free-form egress origins:** the egress component's guarantee rests on a closed set
|
|
849
|
+
of roles.
|
|
850
|
+
- **Credentials through teamctl's `agents.secrets`:** that mount is the harness login
|
|
851
|
+
only, by its own contract.
|
|
852
|
+
- **A lease service for schedules:** none exists, and `runsOn` already names one host.
|
|
853
|
+
|
|
854
|
+
## Delivery
|
|
855
|
+
|
|
856
|
+
| Spec | Surface | Lane | Builds first |
|
|
857
|
+
| --- | --- | --- | --- |
|
|
858
|
+
| S1 Kernel: C1, C2, C3, C4's caller, C5, C10, placement and routing | `lib/`, `bin/`, schemas, `docs/` | lane:product | first; built now, merged after #1912's hold lifts |
|
|
859
|
+
| S2 Provider: `oats.aweb-sandbox`, C4's hook, C6, C7, the registry setting (C3) | the oats-aweb package | lane:setup, aweb's maintainers read first | after S1's contract is merged |
|
|
860
|
+
| S3 Credential mount and the `forge` role: C8, the egress component, teamctl's inputs | `container/agent`, and teamctl on aweb's maintainers' side | lane:juan | in parallel with S1 |
|
|
861
|
+
| S4 Broker contracts: C9 docs, then the client verbs | `docs/`, `lib/` | lane:product | after the first real provider |
|
|
862
|
+
|
|
863
|
+
Each spec carries its own reference pages and a release-notes entry of its own under
|
|
864
|
+
`docs/release-notes/next/` (r1):
|
|
865
|
+
|
|
866
|
+
- S1: [workspaces.md](../workspaces.md) (`sandboxes:`, the rollout rule, C2's
|
|
867
|
+
refusals), [configuration.md](../configuration.md) (C3, C3b), [capabilities.md](../capabilities.md)
|
|
868
|
+
and the manifest schema (the `sandbox` hook, C4), the CLI and JSON pages (C5),
|
|
869
|
+
[servers.md](../servers.md) (the reserved prefix, C7), and readiness (C10).
|
|
870
|
+
- S2: the oats-aweb package's own docs (`identity.seat`, the registry setting,
|
|
871
|
+
`oats.aweb-sandbox`'s settings, the ledger and reconcile).
|
|
872
|
+
- S3: [container.md](../container.md) (the credential fragment and its probe) and
|
|
873
|
+
teamctl's docs on aweb's maintainers' side.
|
|
874
|
+
- S4: the broker contracts' reference page, when it is built.
|
|
875
|
+
|
|
876
|
+
The live rehearsal runs on a disposable Linux Docker host, never on a person's machine.
|
|
877
|
+
It covers every "done means" line, with the egress and boundary probes' receipts kept as
|
|
878
|
+
evidence.
|