@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.
- package/bin/oats.mjs +131 -23
- package/docs/capabilities.md +12 -2
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +206 -228
- 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 +60 -17
- package/docs/implementation.md +1 -1
- 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 +4 -4
- package/docs/packages.md +13 -13
- 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 +4 -3
- package/docs/upgrading.md +12 -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/deployment-data.mjs +4 -2
- package/packages/client/deployment-panel.mjs +2 -1
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- 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 +4 -3
- package/packages/client/workspace-cli.mjs +13 -2
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- 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
|
|
23
|
-
|
|
24
|
-
([
|
|
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
|
-
| `
|
|
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
|
-
|
|
188
|
-
|
|
189
|
-
network or
|
|
190
|
-
([
|
|
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.
|
|
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.
|
|
607
|
-
stopped in that same step, with
|
|
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
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
**
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
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
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
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
|
-
|
|
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
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
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
|
-
|
|
832
|
-
|
|
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
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
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 `
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
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
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
image
|
|
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`
|