@awebai/oats 0.69.22 → 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.
Files changed (54) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +206 -228
  5. package/docs/design/2026-11-19-sandboxes.md +878 -0
  6. package/docs/design/README.md +3 -0
  7. package/docs/desktop-cli-api.md +416 -72
  8. package/docs/desktop.md +60 -17
  9. package/docs/implementation.md +1 -1
  10. package/docs/integrations.md +3 -3
  11. package/docs/knowledge-capability-authoring.md +10 -7
  12. package/docs/knowledge-reference/acceptance.md +21 -19
  13. package/docs/knowledge-reference/adoption.md +18 -4
  14. package/docs/knowledge-reference/model.md +11 -9
  15. package/docs/knowledge-reference/package-craft.md +2 -2
  16. package/docs/knowledge-reference/proposal.md +117 -0
  17. package/docs/knowledge-reference/provider-mapping.md +10 -10
  18. package/docs/knowledge-reference/reader-capture.md +26 -22
  19. package/docs/knowledge-theory.md +1 -1
  20. package/docs/knowledge.md +5 -5
  21. package/docs/official-catalog.md +4 -4
  22. package/docs/packages.md +13 -13
  23. package/docs/release-notes/v0.69.23.md +231 -0
  24. package/docs/servers.md +10 -6
  25. package/docs/souls-and-instances.md +51 -22
  26. package/docs/tui.md +4 -3
  27. package/docs/upgrading.md +12 -5
  28. package/docs/workspaces.md +2 -2
  29. package/lib/argv.mjs +6 -2
  30. package/lib/capability-contract.mjs +2 -2
  31. package/lib/command-flags.mjs +39 -2
  32. package/lib/core.mjs +25 -14
  33. package/lib/instance-board.mjs +337 -0
  34. package/lib/instance-events.mjs +48 -10
  35. package/lib/instance-lifecycle.mjs +19 -15
  36. package/lib/instance-listing.mjs +18 -10
  37. package/lib/instance-related-work.mjs +143 -0
  38. package/lib/kernel-features.mjs +4 -1
  39. package/lib/servers.mjs +123 -13
  40. package/package-catalog.json +3 -3
  41. package/package.json +1 -1
  42. package/packages/client/deployment-data.mjs +4 -2
  43. package/packages/client/deployment-panel.mjs +2 -1
  44. package/packages/client/instance-tree.mjs +34 -4
  45. package/packages/client/keymap.mjs +5 -0
  46. package/packages/client/mail-contract.mjs +130 -0
  47. package/packages/client/panel-views.mjs +7 -7
  48. package/packages/client/related-work.mjs +84 -0
  49. package/packages/client/remote-roster.mjs +4 -3
  50. package/packages/client/workspace-cli.mjs +13 -2
  51. package/skills/oats-getting-started/SKILL.md +11 -8
  52. package/docs/knowledge-reference/harvester.md +0 -109
  53. package/lib/instance-same-work.mjs +0 -67
  54. package/packages/client/same-work.mjs +0 -49
package/docs/container.md CHANGED
@@ -19,9 +19,9 @@ container is one trust group ([trust-model.md](trust-model.md)):
19
19
  rewrite the launch configurations in `/state/deploy` and the schedule
20
20
  registry in `/state/home`, rewrite the wake registrations under
21
21
  `/state/home/.config/aw/wake`, and stop sshd, `oats host run`, the wake
22
- broker or its supervisor. With the optional bb server, each agent can also
23
- read and drive every bb thread and read bb's database
24
- ([A bb server for the team](#a-bb-server-for-the-team)).
22
+ broker or its supervisor. With an optional child, each agent can also
23
+ reach every loopback port the child holds
24
+ ([An optional child](#an-optional-child)).
25
25
  - **It holds one team, never several.** Agents that must not be able to read
26
26
  each other's identities or affect each other's work get separate
27
27
  containers. Nothing in OATS makes sharing one safe.
@@ -154,7 +154,7 @@ Supply these plain variables to the bundle's env file:
154
154
  | `AGENT_CA_FILE` | Optional absolute public PEM path from `agents.caFile`; selects `compose.agent.trust.yaml`. |
155
155
  | `AGENT_MIRRORS_DIR` | Optional absolute mirror directory from `agents.mirrorsDir`; selects `compose.agent.mirrors.yaml`. |
156
156
  | `AGENTS_NETWORK`, `AGENT_IP` | Installer-created external network and container address. |
157
- | `AGENT_BB` | Optional; exactly `1` when `compose.agent.bb.yaml` is included, for acceptance. `AGENT_IMAGE` is then an image built from `container/agent-bb`. |
157
+ | `AGENT_CHILD` | Optional; the name of the declared child, when the derived image's fragment is included, for acceptance. `AGENT_IMAGE` is then that derived image. |
158
158
 
159
159
  The bundle owns the network, resolver, forwarder, firewall and their bypass
160
160
  checks. The agent service publishes no ports and sets no DNS or extra-hosts
@@ -184,10 +184,10 @@ start with the same approved anchors.
184
184
  A successful probe using an explicit CA does not establish that the
185
185
  real broker trusts it; prove that through the deployment's HTTPS registry.
186
186
 
187
- Include `compose.agent.bb.yaml` only for a team that runs a bb server. It sets
188
- exactly one fixed environment entry, `AGENT_BB: "1"`, and adds no mount, port,
189
- network or capability
190
- ([A bb server for the team](#a-bb-server-for-the-team)).
187
+ A derived image that declares a child ships a fragment of its own. Include it
188
+ only for a team that runs that child. It sets exactly one fixed environment
189
+ entry, `AGENT_CHILD: "<name>"`, and adds no mount, port, network or
190
+ capability ([An optional child](#an-optional-child)).
191
191
 
192
192
  Include `compose.agent.mirrors.yaml` only when `agents.mirrorsDir` is configured.
193
193
  The operator provisions and refreshes the bare mirrors outside the container,
@@ -525,7 +525,7 @@ container may do. Give them an identity with the write role only on the
525
525
  knowledge repository, its token in a file named by
526
526
  `settings.oats.okf.github-token-file`, and keep the identity that merges to
527
527
  the accepted branch outside the container. oats.okf's
528
- [Bringing up a deployment's knowledge store](https://github.com/oats-project/oats-okf/blob/v6.2.0/README.md#bringing-up-a-deployments-knowledge-store)
528
+ [Bringing up a deployment's knowledge store](https://github.com/oats-project/oats-okf/blob/v6.3.0/README.md#bringing-up-a-deployments-knowledge-store)
529
529
  (oats.okf 6.2 and later) has each step; run its
530
530
  `oats okf setup --check` in the container to check them.
531
531
 
@@ -603,9 +603,9 @@ What the image's files fix for that:
603
603
  run alone and keeps the wake broker alive until host run finishes stopping
604
604
  the agents. Then it stops sshd and the broker in parallel, allowing sshd three seconds
605
605
  and the broker six seconds before escalation. The broker budget preserves
606
- its channel children's five-second delivery drain. With a bb server, bb is
607
- stopped in that same step, with eight seconds, so it runs until host run
608
- has stopped the agents. A broker or
606
+ its channel children's five-second delivery drain. A declared child is
607
+ stopped in that same step, with its declared `stopMs` (at most eight
608
+ seconds), so it runs until host run has stopped the agents. A broker or
609
609
  host-run exit is reported and drains the other children before a nonzero
610
610
  container exit, so
611
611
  the restart policy can restart it. The broker runs as the agent uid; its
@@ -655,222 +655,189 @@ or, in the container, `oats schedule host install --register-only --dir
655
655
  systemd user manager. The registry is in `/state/home`, so it persists
656
656
  across container runs.
657
657
 
658
- ## A bb server for the team
659
-
660
- [bb](https://github.com/get-bb/bb) (npm `bb-app`, MIT) is a server that runs
661
- coding agents as threads and shows them in a web, desktop and phone app. A
662
- team can run one bb server in its container, supervised beside the wake
663
- broker, sshd and `oats host run`. It is opt-in: a container that does not
664
- ask for it runs exactly as before, and the team image holds no bb.
665
-
666
- The server is unused until agents are spawned with the bb session provider,
667
- which arrives with a later kernel. Until then it starts, listens and holds
668
- no thread of OATS's.
669
-
670
- **This is experimental.** The bb image (`container/agent-bb`),
671
- `compose.agent.bb.yaml` and the relay will move to the bb package repository
672
- once it exists. There is no compatibility promise on those paths, on
673
- `AGENT_BB` or on the image's recipe, so that move will not be a breaking
674
- change.
675
-
676
- ### Turning it on
677
-
678
- Two things, together:
679
-
680
- 1. **The derived image.** `container/agent-bb/` builds on a team image and
681
- adds only `bb-app`, at the one version its committed `package.json` and
682
- `package-lock.json` pin, installed with `npm ci --ignore-scripts`: no
683
- lifecycle script, no rebuild, no OS package. bb's native modules are the
684
- prebuilt ones in its locked packages. It keeps the team image's
685
- entrypoint, user, `HOME` and environment, and bb runs the Claude Code that
686
- image already holds, `/usr/local/bin/claude`: the derived image adds no
687
- second one. It is about 280 MB larger.
688
-
689
- ```sh
690
- docker build --platform linux/amd64 \
691
- --build-arg AGENT_IMAGE=oats-agent:reviewed \
692
- -t oats-agent-bb:reviewed container/agent-bb
693
- ```
694
-
695
- Select it with `AGENT_IMAGE`. To change bb's version, change its one
696
- dependency version, regenerate that directory's lock with npm 11 or later
697
- (`npm install --package-lock-only --ignore-scripts`; npm 10 drops the
698
- `libc` field of platform packages, and `npm ci` then also installs their
699
- musl builds), review both files and build a new image.
700
-
701
- 2. **The fragment.** Append `-f container/agent/compose.agent.bb.yaml` to
702
- the Compose commands. It sets `AGENT_BB: "1"` and nothing else. Export
703
- `AGENT_BB=1` with the other variables when you run acceptance.
704
-
705
- bb's version is pinned in this image's `container/agent-bb/package.json`.
706
- When the bb session provider arrives, its `version` setting in the
707
- deployment is a second pin, and its `E_BACKEND_VERSION` check, at readiness
708
- and at launch, is what keeps the two equal.
709
-
710
- The supervisor reads `AGENT_BB` once, at start. Unset or empty, it does
711
- what it did before. Any value but `1` is refused at start. Nothing else
712
- about bb is configurable: its arguments, its address and its environment
713
- are fixed in the image.
714
-
715
- ### What runs
716
-
717
- After the broker is ready and before sshd and host run, the supervisor
718
- starts `bb-app --no-in-app-updates --server-bind-host 127.0.0.1`. Its
719
- environment is the supervisor's own plus two entries:
720
-
721
- - `BB_TELEMETRY=false`: telemetry is off.
722
- - `CLAUDE_CODE_OAUTH_TOKEN`, read from `/etc/agent-login/claude-token` when
723
- that file exists, so bb's Claude threads use the team's inference token.
724
- The supervisor reads the file once and gives the value to bb alone: never
725
- to the broker, sshd or host run, never in an argument or a log line. With
726
- no file, or an empty one, bb starts without the variable. The file must
727
- hold the token on one line: a token with whitespace inside it (a space, a
728
- tab, a line break) is refused at start, before any child, since bb would report ready while
729
- every model call failed.
730
-
731
- bb reads its environment once, when it starts. After replacing the token,
732
- restart the container; restart the agents as
733
- [After changing a credential](#after-changing-a-credential) says.
734
-
735
- In a team container, spawn bb agents with `--yolo` (bb's full mode): the
736
- container is the boundary, as it is for tmux agents there. bb's sandboxed
737
- modes need bubblewrap, which the image does not carry; without it every
738
- command waits for a person in bb, so an agent cannot answer mail unattended.
739
-
740
- bb keeps its data in its default directory, `/state/home/.bb`. It needs no
741
- getbb.app account. At start it looks up `getbb.app` and
742
- `registry.npmjs.org`; the egress boundary refuses both and bb works without
743
- them, so neither needs an allowlist entry. A thread's model calls go through
744
- the egress boundary as an agent's do.
745
-
746
- Push notifications need a service outside the container. Keep them off:
747
-
748
- ```sh
749
- ssh team-agent bb plugin disable push-notifications
658
+ <!-- docs/release-notes/v0.69.22.md links here under this section's former
659
+ name, "A bb server for the team": the anchor keeps those links whole. -->
660
+ <a id="a-bb-server-for-the-team"></a>
661
+ ## An optional child
662
+
663
+ A derived image can add one more supervised process to the team container:
664
+ a server its agents use on loopback, say. The base image runs none. The
665
+ mechanism has two halves, and they belong to different people:
666
+
667
+ - **The declaration is the image's.** A derived image holds one file,
668
+ `/etc/agent-child.json`, that says what to run. It is root's file on the
669
+ read-only root, so only an image build can write it.
670
+ - **The switch is the deployment's.** The Compose fragment that ships with
671
+ the derived image sets one fixed environment entry,
672
+ `AGENT_CHILD: "<name>"`. Without it nothing starts, and a declaration in
673
+ the image is inert: the supervisor reads no file and runs as it does on the
674
+ base image.
675
+
676
+ One child, not a list: a second one is a new decision.
677
+
678
+ The image that runs a [bb](https://github.com/get-bb/bb) server this way,
679
+ its relay and its operator docs live in
680
+ [oats-project/oats-bb](https://github.com/oats-project/oats-bb); this
681
+ repository holds no product's image. bb, the optional child that oats-bb
682
+ ships, is documented
683
+ [there](https://github.com/oats-project/oats-bb/blob/main/container/README.md):
684
+ the threads of one bb can write each other's storage, and bb's sandboxed
685
+ modes are not a security boundary. `AGENT_BB`, `container/agent-bb`,
686
+ `compose.agent.bb.yaml` and the relay shipped in 0.69.22 as experimental,
687
+ with no compatibility promise, and are gone without an alias: a container
688
+ that still sets `AGENT_BB` is refused at start with a line naming
689
+ `AGENT_CHILD`.
690
+
691
+ **A child's loopback ports are reachable by every agent in the container.**
692
+ Whatever the child serves there, with whatever login it does or does not
693
+ ask for, belongs to the container's one trust group
694
+ ([One team, one trust group](#one-team-one-trust-group)). The service still
695
+ publishes no port.
696
+
697
+ ### The declaration
698
+
699
+ `/etc/agent-child.json` is JSON of at most 16 KiB, with a closed grammar:
700
+ every key below is required unless marked, and an unknown key is refused.
701
+
702
+ ```json
703
+ { "name": "example",
704
+ "command": ["/usr/local/bin/example-server", "--bind", "127.0.0.1"],
705
+ "env": { "EXAMPLE_TELEMETRY": "false" },
706
+ "envFromFile": { "EXAMPLE_TOKEN": "/etc/agent-login/example-token" },
707
+ "ready": { "url": "http://127.0.0.1:39000/status", "field": "ready" },
708
+ "listen": [39000],
709
+ "version": { "command": ["/usr/local/bin/example", "--version"], "file": "/opt/agent-child/version" },
710
+ "stopMs": 5000 }
750
711
  ```
751
712
 
752
- ### Trust
753
-
754
- bb's API has no login. It listens on the container's loopback only: on
755
- ports 38886 (the server) and 38887 (its host daemon), and on one more
756
- loopback port that bb picks at each start. The service publishes no port.
757
- Inside the container that changes what the trust group shares
758
- ([One team, one trust group](#one-team-one-trust-group)):
759
-
760
- - Any agent can read and drive every bb thread: read it, send it a message,
761
- start one, stop one.
762
- - Any agent can read bb's database under `/state/home/.bb`. It holds every
763
- conversation of every thread. It is on `/state`, so it outlives the
764
- container and is in any copy of the volume, and OATS never trims it
765
- ([Where conversations are stored](#where-conversations-are-stored)).
766
- - The token in bb's environment is the one every agent can already read.
767
- - Any agent, one in a sandboxed bb thread included, can write every other
768
- thread's storage: the threads of one bb share bb's thread-storage
769
- directory under `/state/home/.bb`, and bb's own sandbox settings leave
770
- the whole thread-storage directory writable. (They keep bb's database and
771
- auth files read-only to a sandboxed thread.)
772
- - bb's sandboxed permission modes (`auto`, `accept-edits`) are not a
773
- security boundary. They limit accidents, not a determined agent: an agent
774
- in such a mode can write its own instance home, which holds code that OATS
775
- and the harness later run outside the sandbox. Treat an agent in a
776
- sandboxed mode as able to do what any agent in the container can. OATS
777
- counts no harness's sandbox as a boundary
778
- ([What OATS does not promise](trust-model.md#what-oats-does-not-promise)).
779
-
780
- One bb serves one container. Never share one across teams, and never point
781
- two containers at one `/state`.
782
-
783
- ### Reaching it
784
-
785
- bb listens only inside the container, and sshd's forwarding stays off. The
786
- operator reaches bb over the SSH route they already have
787
- ([OATS over SSH](#oats-over-ssh)), with a small relay that runs on the
788
- operator's machine. It is in the checkout, never in an image, and needs only
789
- Node and `ssh`:
790
-
791
- ```sh
792
- node container/agent-bb/relay.mjs --ssh team-agent --listen 48886
793
- ```
794
-
795
- It listens on `127.0.0.1:48886` and nowhere else; it refuses any other
796
- address. Each connection becomes one SSH command channel to the container,
797
- whose command pipes to bb on `127.0.0.1:38886` there. The relay keeps up to
798
- nine channels on one SSH connection of its own (sshd allows ten sessions per
799
- connection) and opens a separate connection for each one beyond that. If that
800
- shared connection ends, it starts it again; meanwhile new connections work,
801
- each on a connection of its own. TERM or Ctrl+C closes the listener and
802
- every channel. Use one local port per team.
803
-
804
- - **Desktop app, on the same machine.** Server menu, Add Server,
805
- `http://127.0.0.1:48886`. Add one server per team and name it. Nothing
806
- is set in bb.
807
- - **Phone, or another machine.** Serve the relay's port under HTTPS on your
808
- own tailnet, one port per team (Tailscale Serve:
809
- `tailscale serve --bg --https=443 http://127.0.0.1:48886`). bb refuses a
810
- name it was not told about, so set it once, over the SSH route:
811
-
812
- ```sh
813
- ssh team-agent bb-app config set BB_APP_URL 'https://<name>[:port]'
814
- ```
815
-
816
- Then add one Direct profile per team in the app, with that URL.
713
+ | Key | Grammar | Meaning |
714
+ | --- | --- | --- |
715
+ | `name` | 1 to 20 lowercase letters, digits or dashes; not `broker`, `sshd`, `host-run`, `status` or `supervisor`, the base's own names in the log | What the supervisor's lines call the child, and the value `AGENT_CHILD` must have. |
716
+ | `command` | A non-empty array of strings; `command[0]` an absolute path that exists and whose real path is outside `/state`, `/work`, `/tmp`, `/run`, `/outbox` and `/dev/shm` | The child's argv, exactly. No shell. The supervisor resolves `command[0]` once, at start, refuses a file inside a writable mount, and runs that resolved file under its declared name at the start and at every restart, so a link on the way that an agent could re-point is never followed again. |
717
+ | `env` | An object of strings; names match `[A-Z_][A-Z0-9_]*` | Literal variables added to the child's environment. May be `{}`. |
718
+ | `envFromFile` | Optional. An object of variable name to a file directly under `/etc/agent-login/`; names as for `env`, and no name in both | Variables whose value is the file's content, read once at start ([below](#envfromfile)). |
719
+ | `ready.url` | `http://127.0.0.1:<port>/<path>`, the port one of `listen`; the path of letters, digits and `._~/?&=%-` | Where the supervisor asks whether the child is ready. |
720
+ | `ready.field` | A letter or underscore, then letters, digits or underscores; at most 64 characters | The top-level field of the JSON answer that must be `true`. |
721
+ | `listen` | A non-empty array of distinct ports from 1024 to 65535, without 2222 | The loopback TCP ports the child holds. Acceptance requires each. |
722
+ | `version.command` | A non-empty array of strings; `command[0]` an absolute path | A command that prints the child's version. |
723
+ | `version.file` | An absolute path | A file the image writes at build time with that same version: one printable line of at most 64 characters, in a file of at most 256 bytes. Acceptance compares the two, so it needs no checkout of the image's repository. |
724
+ | `stopMs` | A whole number from 1000 to 8000 | How long the child gets after SIGTERM before SIGKILL. |
725
+
726
+ Neither `env` nor `envFromFile` may set `PATH`, `HOME`, `LD_PRELOAD`,
727
+ `NSS_WRAPPER_PASSWD`, `NSS_WRAPPER_GROUP`, `NODE_OPTIONS` or `AGENT_CHILD`:
728
+ the image, the entrypoint and the switch set those.
729
+
730
+ Nothing else is declarable. The order, the start timeout, the restart policy
731
+ and the process group are the base image's
732
+ ([What the supervisor does](#what-the-supervisor-does)).
733
+
734
+ ### envFromFile
735
+
736
+ One rule for every entry. The supervisor reads each file once, before any
737
+ child starts:
738
+
739
+ - **No such file:** the child starts without that variable, even when the
740
+ supervisor's own environment holds one of that name: an `envFromFile`
741
+ name comes from its file or not at all.
742
+ - **Empty after trimming:** the same, with one line that names the variable.
743
+ - **Any other read error:** the start is refused.
744
+ - **Whitespace or a NUL byte inside the trimmed value** (a second line, a
745
+ space, a tab, a file saved as UTF-16):
746
+ the start is refused with `the file for <VARIABLE> must hold its value on
747
+ one line`. A file with two lines is never passed on in part.
748
+
749
+ The value reaches the declared child's environment and nothing else: no
750
+ line the supervisor writes, no argument, no other child. The child reads its
751
+ environment when it starts, so after replacing a file under the login mount,
752
+ restart the container ([After changing a credential](#after-changing-a-credential)).
753
+ Every agent can already read the login mount.
754
+
755
+ ### What the supervisor does
756
+
757
+ With `AGENT_CHILD` set, the supervisor reads the declaration once, before
758
+ any child, and then:
759
+
760
+ 1. Starts the wake broker and waits for it, as on the base image.
761
+ 2. Asks `ready.url` once, for at most a second. Whatever accepts that
762
+ connection before the child exists is another process, whether it answers
763
+ ready, not ready or nothing, and refuses the start. A refused connection
764
+ is the only pass: an attempt that cannot tell whether anybody listens
765
+ refuses the start too.
766
+ 3. Starts the child: the resolved `command[0]` with argv exactly `command`,
767
+ the supervisor's own environment without the `envFromFile` names, plus
768
+ `env`, plus the `envFromFile` values that were read, in a process group
769
+ of its own.
770
+ 4. Asks `ready.url` until it answers 200 with JSON whose top-level
771
+ `ready.field` is `true` while the child it started is still alive, for up
772
+ to 30 seconds. It then writes `agent-supervisor: <name> ready (<field>:
773
+ true)`.
774
+ 5. Starts sshd and `oats host run`.
775
+
776
+ On SIGTERM, host run goes first, and the child keeps running while host run
777
+ stops the agents. Then sshd, the broker and the child are stopped side by
778
+ side; the child gets SIGTERM and `stopMs` before SIGKILL.
779
+
780
+ The stop budget holds for whatever an image declares, since `stopMs` is
781
+ capped: at most 35 seconds for host run (10 + 5 + 20), then the slowest of
782
+ sshd (3 seconds), the broker (6) and the child (at most 8), 43 seconds in
783
+ all inside the 50-second stop grace. `test/agent-container.test.mjs` pins
784
+ that sum against the supervisor's exported budgets, the cap and the Compose
785
+ file, with 5 seconds to spare.
817
786
 
818
- **Whoever reaches the relay's port, or that name, runs commands in that
819
- team's container**: bb starts agents and terminals for anyone who can talk to
820
- it. So the operator's machine, and the tailnet's access rules for that name,
821
- become part of the team's boundary. Never use Tailscale Funnel or any public
822
- address for it, and never make the relay listen wider.
787
+ ### When it fails
823
788
 
824
- The relay's `127.0.0.1` port, like bb's own in the container, has no
825
- login: every local user of the operator's machine can reach it, and so can
826
- run commands in the team's container. Run the relay only on a machine whose
827
- only user is the operator.
789
+ Each refusal at start is one fixed line on standard error, exit 1, before
790
+ any child starts. A line names the key at fault and never a value from the
791
+ file.
792
+
793
+ - **`AGENT_CHILD` on an image without a declaration**, the base image
794
+ included: `AGENT_CHILD needs an image that declares a child in
795
+ /etc/agent-child.json`. Select the derived image with `AGENT_IMAGE`.
796
+ - **A declaration that is not the image's own file:** a symlink, not a
797
+ regular file, not owned by uid 0, or writable by its group or by others.
798
+ Over 16 KiB, or not JSON, is refused too. The supervisor runs as the
799
+ agent, so the file must be readable by everyone (mode 0644 or 0444): one
800
+ it cannot open is refused with `/etc/agent-child.json could not be read
801
+ (<code>)`.
802
+ - **A declaration outside the grammar:** `/etc/agent-child.json: <key>
803
+ <what it must be>`, for an unknown or missing key and for every value the
804
+ table above rules out.
805
+ - **A `name` that differs from `AGENT_CHILD`.** The fragment and the image
806
+ must be the same product's.
807
+ - **A command that does not exist, or resolves under a writable mount.**
808
+ - **An `envFromFile` file that cannot be read, or holds whitespace inside
809
+ its value** ([above](#envfromfile)).
810
+ - **`AGENT_BB` set to anything:** `AGENT_BB is gone: use an image that
811
+ declares its child and AGENT_CHILD (the bb image now lives in
812
+ oats-project/oats-bb)`.
813
+ - **The child is not ready.** A child that exits before it is ready, 30
814
+ seconds without a ready answer (one that arrives later does not count), or
815
+ anything listening on `ready.url` before the child starts
816
+ fails the container start: neither sshd nor host run starts, the exit is
817
+ nonzero and the restart policy starts the container again.
818
+ - **The child ends later.** That is not a container failure. The supervisor
819
+ writes `agent-supervisor: <name> exited (<code or signal>)`, sends SIGKILL
820
+ to what is left of the child's process group, and starts the child again
821
+ after 1 second, doubling to 60 seconds, and from 1 second again once a
822
+ child has stayed up five minutes. sshd, the broker, host run and the
823
+ agents keep running.
824
+ - **Stopping.** A child that had to be killed after `stopMs`, or that ended
825
+ while host run was still stopping agents, makes the stop a failed one. A
826
+ restart that was pending at SIGTERM starts no further child.
828
827
 
829
828
  ### Limits
830
829
 
831
- bb counts toward the container's limits. Add to `AGENT_MEMORY` and
832
- `AGENT_PIDS` about 650 MB and 180 pids for bb itself, and about 200 MB and
833
- 30 pids for each live thread.
834
-
835
- ### When it fails
836
-
837
- - **`AGENT_BB=1` on an image without bb.** The supervisor refuses at start,
838
- before any child: one line naming `container/agent-bb`, exit 1. Select the
839
- derived image.
840
- - **bb is not ready.** The supervisor polls the host daemon's status
841
- (`http://127.0.0.1:38887/status`) until it says `connected: true` and the
842
- bb process it started is still alive, for up to 30 seconds. A bb that
843
- exits first, a timeout, or a status that already answers before bb starts
844
- fails the container start: neither sshd nor host run starts, the exit is
845
- nonzero and the restart policy starts the container again. An unreadable
846
- token file, or one whose token has whitespace inside it, fails the start
847
- too, before any child.
848
- - **bb ends later.** That is not a container failure. The supervisor
849
- writes `agent-supervisor: bb exited (<code or signal>)`, removes what bb's
850
- launcher left running, and starts bb again after 1 second, doubling to 60
851
- seconds, and from 1 second again once a bb has stayed up five minutes.
852
- sshd, the broker, host run and the agents keep running. A thread's
853
- process ends with its bb, and the thread itself is kept: the next bb lists
854
- it idle, and a message to it (`bb thread tell`) starts a new turn. bb's
855
- own lookups of provider versions (`npm view`) are the one thing seen to
856
- outlive a killed bb, until their own lookup fails or times out; they hold no
857
- port.
858
- - **Stopping.** Host run goes first, as without bb, and bb keeps running
859
- while it stops the agents. Then sshd, the broker and bb are stopped side by
860
- side; bb gets SIGTERM and eight seconds before SIGKILL. A bb that had to be
861
- killed, or that ended while host run was still stopping agents, makes the
862
- stop a failed one. The whole order fits the 50-second stop grace: at most
863
- 35 seconds for host run and 8 for the slowest of the three.
830
+ The child counts toward the container's limits. A derived image's docs say
831
+ what to add to `AGENT_MEMORY` and `AGENT_PIDS` for it.
864
832
 
865
833
  ### What was run
866
834
 
867
- Run on amd64, in the real image under the Compose flags: the build, bb ready
868
- at start, a bb restart after `kill` and after `kill -9`, each followed by a
869
- new turn in a thread made before it (on a mock model; after the `kill -9`
870
- the thread's Claude process was gone within a second), the ordered stop,
871
- acceptance with the fragment, and the relay with the real `ssh` (the bb web
872
- page and API through it). **NOT RUN:** arm64; a real Claude token or a real
873
- model; Tailscale Serve; the desktop and phone apps; push notifications.
835
+ Run on amd64, in the base image and a fixture derived image
836
+ (`test/fixtures/agent-child`) under the Compose flags: the build, the child
837
+ ready at start between the broker and sshd, a restart after `kill` and after
838
+ `kill -9`, the ordered `docker stop`, and acceptance with and without
839
+ `AGENT_CHILD`. **NOT RUN:** arm64; any real product's image, which its own
840
+ repository proves.
874
841
 
875
842
  ## Acceptance and evidence
876
843
 
@@ -904,12 +871,18 @@ variables. It resolves `AGENT_IMAGE` independently and requires that image's
904
871
  ID, reference and start command, and its complete environment (printing only
905
872
  names of differing variables). Other comparisons include supplementary
906
873
  groups, namespace overrides, sysctls, published ports, resolver overrides
907
- and the single network/address. With `AGENT_BB=1` exported it admits the bb
908
- fragment's one environment entry, reads the container's listening TCP
909
- sockets and requires every one to be on a loopback address except sshd's
910
- port 2222, with bb's two ports among them, and requires `bb --version` to
911
- equal `container/agent-bb`'s pin. Without it, a container that has `AGENT_BB`
912
- set is refused. The stop timeout must be 50 seconds and the
874
+ and the single network/address. With `AGENT_CHILD=<name>` exported it admits
875
+ that one environment entry and reads `/etc/agent-child.json` from the
876
+ running container. It requires the file to be a regular file owned by root,
877
+ not a symlink and not writable by its group, by others or by the agent, to
878
+ pass the supervisor's grammar and to declare that name. It reads the
879
+ container's listening TCP sockets and requires every declared `listen` port
880
+ on loopback and nothing beyond loopback except sshd's port 2222. It runs
881
+ `version.command` in the container, requires its output to equal the
882
+ trimmed content of `version.file`, and reports that version. Without
883
+ `AGENT_CHILD`, a container that has it set is refused. A container that has
884
+ `AGENT_BB`, or an image that sets `AGENT_CHILD` itself, is refused either
885
+ way. The stop timeout must be 50 seconds and the
913
886
  healthcheck the service file's, so a container made before either was set
914
887
  is refused until it is recreated. The OCI runtime must match the daemon's
915
888
  independently read default; shared memory stays at Docker's 64 MiB default,
@@ -1008,10 +981,15 @@ network and fixture paths on success or failure. This is image acceptance;
1008
981
  it provisions no seat or inference token. The script's `NOT RUN` items
1009
982
  remain outside this check.
1010
983
 
1011
- The same job then builds `container/agent-bb` from the image it just
1012
- accepted, with no registry in between, and runs the same fixture and the
1013
- same unmodified acceptance once more with `compose.agent.bb.yaml`. The bb
1014
- image is not exported or published.
984
+ The same job then proves the optional child with a fixture derived image,
985
+ `test/fixtures/agent-child`: a dependency-free Node HTTP server on one
986
+ loopback port, its declaration and its version file. It builds that image
987
+ from the image it just accepted, with no registry in between, and runs the
988
+ same fixture and the same unmodified acceptance once more with
989
+ `AGENT_CHILD` set: alone, then with the inputs and the outbox fragments. It
990
+ also requires acceptance without `AGENT_CHILD` to refuse that container.
991
+ The fixture is outside `container/agent`, so it is never in the base
992
+ image's build context, and it is not exported or published.
1015
993
 
1016
994
  The `publish-team-image` job in
1017
995
  [Release](../.github/workflows/release.yml) waits for the existing `publish`