@awebai/oats 0.69.20 → 0.69.21
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 +26 -3
- package/docs/capabilities.md +1 -1
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +80 -0
- package/docs/desktop.md +106 -65
- package/docs/implementation.md +1 -1
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +2 -2
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/servers.md +5 -1
- package/docs/souls-and-instances.md +11 -0
- package/docs/upgrading.md +11 -5
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +1 -0
- package/lib/core.mjs +5 -3
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +16 -0
- package/lib/instance-listing.mjs +8 -4
- package/lib/instance-pin.mjs +59 -0
- package/lib/kernel-features.mjs +1 -1
- package/lib/servers.mjs +8 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/roster-row-facts.mjs +50 -0
- package/skills/oats-getting-started/SKILL.md +210 -27
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# OATS 0.69.21
|
|
2
|
+
|
|
3
|
+
The official catalog pins oats.aweb 1.43.0: a private aw registry is admitted
|
|
4
|
+
by one host setting, aw children no longer take exported selectors, and grant
|
|
5
|
+
seats stay in their recorded team. Instances can be pinned to the top of their
|
|
6
|
+
machine's list (`oats instance pin`). The Desktop's sidebar is reworked: two-line
|
|
7
|
+
rows, groups that start collapsed, no lineage lines, and a new foot. The
|
|
8
|
+
getting-started skill sets up a workspace on the person's own aweb server.
|
|
9
|
+
|
|
10
|
+
## Upgrade
|
|
11
|
+
|
|
12
|
+
- **Either order of the Desktop and the CLI works** from a Desktop newer than
|
|
13
|
+
0.69.17 ([Either order works](../upgrading.md#either-order-works)). A
|
|
14
|
+
Desktop of 0.69.17 or older still goes first.
|
|
15
|
+
- **Package pin:** oats.aweb 1.43.0 (from 1.42.1). oats.framework stays
|
|
16
|
+
1.26.0 and oats.okf 6.2.0. `oats sync` takes it.
|
|
17
|
+
|
|
18
|
+
What a deployment must change, from oats.aweb's 1.43.0 entry:
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
- **On a non-public aw registry:**
|
|
22
|
+
1. Run `oats aweb setup --registry <origin>` in the deployment.
|
|
23
|
+
2. Rerun `oats aweb resident create <name>` for each resident.
|
|
24
|
+
3. Run `oats aweb wake install` from your own shell.
|
|
25
|
+
4. Restart the homes.
|
|
26
|
+
|
|
27
|
+
Until then, setup, spawn, join, launch and readiness refuse with
|
|
28
|
+
`registry-setting-required`. A deployment on the public registry changes
|
|
29
|
+
nothing.
|
|
30
|
+
- **Exported aw selectors no longer reach aw:** `AWEB_IDENTITY_HOME`,
|
|
31
|
+
`AWEB_URL`, `AWEB_API_KEY`, `AWEB_ROLE_NAME`, `AWEB_ROLE`,
|
|
32
|
+
`AWID_REGISTRY_URL`. If you exported them for ordinary lifecycle commands,
|
|
33
|
+
record the service in the selected aw home instead, and a private registry
|
|
34
|
+
in the setting above.
|
|
35
|
+
- **Grant seats:**
|
|
36
|
+
- A grant seat with `.oats-aweb/seat.json` whose `identity.resident` or
|
|
37
|
+
default team has changed refuses start: respawn it.
|
|
38
|
+
- A home that an earlier release renewed into another team needs the
|
|
39
|
+
printed manual revoke, then `oats retire <instance> --force`.
|
|
40
|
+
- **Retained seats:** a symlinked `identity.source`, or a link or special
|
|
41
|
+
file in the copied authority, now refuses. Point it at the real directory.
|
|
42
|
+
- **Scripts:**
|
|
43
|
+
- `oats aweb setup --check-only --json` answers `member:null` with a nonzero
|
|
44
|
+
exit when the membership can't be read.
|
|
45
|
+
- `join --plan` fails with `E_SETUP_MEMBERSHIP` for an unreadable root.
|
|
46
|
+
- `setup --create`, and `setup --join` without a token, refuse while the
|
|
47
|
+
default root's membership can't be read.
|
|
48
|
+
- An unavailable username fails as `E_SETUP_USERNAME_UNAVAILABLE`, where it
|
|
49
|
+
was `E_SETUP_NATIVE`.
|
|
50
|
+
|
|
51
|
+
**Respawn instances** to take the new oats.aweb module, or move a stopped
|
|
52
|
+
home with `oats instance upgrade`. A running instance keeps the module it was
|
|
53
|
+
composed with.
|
|
54
|
+
|
|
55
|
+
## Added
|
|
56
|
+
|
|
57
|
+
- **The `oats-getting-started` skill sets up a new workspace on the
|
|
58
|
+
person's own aweb server** (#1774, #1775). Step 1's messaging line names
|
|
59
|
+
hosted aweb as the default, "unless you run your own aweb server". The
|
|
60
|
+
own-server answer collects
|
|
61
|
+
three things, none of them secret: the namespace domain the person
|
|
62
|
+
controls, the server's public URL, and whether the server uses the public
|
|
63
|
+
AWID registry. A server on a private registry is not set up yet: the
|
|
64
|
+
branch stops before writing anything, says it needs `oats.aweb` with
|
|
65
|
+
`oats aweb setup --registry` (awebai/oats-aweb#284), and offers hosted
|
|
66
|
+
aweb. It also names the prerequisites, which stay on the person's side:
|
|
67
|
+
the namespace's controller key on this computer, its `_awid` DNS record,
|
|
68
|
+
and the server reachable. Then:
|
|
69
|
+
- The skill reads the version `oats.aweb` was tested with (`tested` in
|
|
70
|
+
its `aw-compat.json`, read at the catalog's exact `oats.aweb` ref, never
|
|
71
|
+
`main`) and compares the installed `aw` with it, in `oats.aweb`'s own
|
|
72
|
+
version order. A missing or older `aw` is replaced by `tested`: the skill
|
|
73
|
+
checks the version `aw` prints, and that the program `file` reports is
|
|
74
|
+
for this machine's architecture. A newer `aw` is kept, since another
|
|
75
|
+
deployment may need it, and the hand-over says "aw X is newer than the
|
|
76
|
+
tested Y; kept". On an OATS release whose `oats.aweb` is older than
|
|
77
|
+
`v1.42.1`, the branch stops and offers hosted aweb.
|
|
78
|
+
- The workspace commits the team `<workspace>:<namespace>` as its only
|
|
79
|
+
team and its default. It writes no hosted `default:…aweb.ai` team and no
|
|
80
|
+
`localTeams`.
|
|
81
|
+
- Step 9 checks the DNS record read-only
|
|
82
|
+
(`aw id namespace check-txt`), then creates the team with
|
|
83
|
+
`oats aweb setup --create <workspace> --namespace <domain> --name <workspace>-root`,
|
|
84
|
+
registered with the person's server. It reports where the team key
|
|
85
|
+
lives (the path, never the key), and checks membership before the
|
|
86
|
+
spawn.
|
|
87
|
+
|
|
88
|
+
The skill never makes the namespace's controller key, and never asks for
|
|
89
|
+
`AWEB_API_KEY`. Hosted aweb is unchanged: it installs the latest `aw` and
|
|
90
|
+
records its version. The join of an existing workspace and the machine
|
|
91
|
+
found-list are unchanged, and don't offer the own-server branch.
|
|
92
|
+
|
|
93
|
+
- **Pin an instance at the top of its machine's list** (feature `instance-pin`).
|
|
94
|
+
`oats instance pin <instance> on|off` records or removes the pin, locally or
|
|
95
|
+
with `--server`. Its answer is `{ instancePinApi: 1, instance, home, pinned,
|
|
96
|
+
changed }`; `home` names the home it resolved, so a routed or `--home` pin
|
|
97
|
+
says which one it pinned.
|
|
98
|
+
- The pin is shared. It is kept in the instance's home, so everyone who views
|
|
99
|
+
that machine sees it: the Desktop, the TUI and another machine's routed
|
|
100
|
+
view. There is no per-viewer pin. In 0.69.21 the pin is set and read with
|
|
101
|
+
the CLI only: the Desktop and the TUI show pins, and set them, from the
|
|
102
|
+
next release.
|
|
103
|
+
- The home keeps it in `.oats-pinned.json` through restart, stop, resume and
|
|
104
|
+
`oats instance upgrade`, and a retire removes it with the home. Retire never
|
|
105
|
+
counts the file as work, and a capability cannot declare it.
|
|
106
|
+
- `pinned: true` appears on `oats status --json` rows, on `oats server roster
|
|
107
|
+
--json` rows (only when the host's row says exactly `true`) and on
|
|
108
|
+
`oats inspect --home`. The key is absent when the instance is not pinned.
|
|
109
|
+
- No spawn flag or `soul.yaml` key pins an instance: a pin is a person's
|
|
110
|
+
choice about the view. A routed pin needs a host that lists `instance-pin`.
|
|
111
|
+
|
|
112
|
+
See
|
|
113
|
+
[Pinned instances](../desktop-cli-api.md#pinned-instances-oats-instance-pin).
|
|
114
|
+
|
|
115
|
+
## Changed
|
|
116
|
+
|
|
117
|
+
- **Getting started names an unavailable aweb username.** With an oats.aweb
|
|
118
|
+
that answers `E_SETUP_USERNAME_UNAVAILABLE` (awebai/oats-aweb#286), the
|
|
119
|
+
`oats-getting-started` skill's signup step knows that nothing was created:
|
|
120
|
+
it asks the person for another `N`, or, on a machine found-list, tells
|
|
121
|
+
them why and stops. `E_SETUP_NATIVE` no longer reads as "most likely
|
|
122
|
+
taken"; on an older oats.aweb a taken `N` still fails that way.
|
|
123
|
+
|
|
124
|
+
- **The catalog pins oats.aweb 1.43.0** (awebai/oats-aweb, tag `v1.43.0`), up
|
|
125
|
+
from 1.42.1. It still requires OATS >=0.68.0; the aw floor stays 1.36.33 and
|
|
126
|
+
the tested aw 1.36.58.
|
|
127
|
+
- **Registry admission is one host setting.** A private aw registry is
|
|
128
|
+
admitted only by `settings.oats.aweb.registry`, which
|
|
129
|
+
`oats aweb setup --registry <origin>` records in `oats-local.yaml`. A saved
|
|
130
|
+
`registry_url` and an exported `AWID_REGISTRY_URL` are locators only.
|
|
131
|
+
- **aw children ignore exported selectors.** Each takes only what a call
|
|
132
|
+
passes by name. A malformed `OATS_SETTINGS` refuses instead of using
|
|
133
|
+
defaults.
|
|
134
|
+
- **A grant seat's calls stay in its recorded team,** and its
|
|
135
|
+
`.oats-aweb/seat.json` owns that team. An empty grant seat now completes
|
|
136
|
+
retire with the documented `nothing-to-delete` outcome.
|
|
137
|
+
- **Membership and custody reads fail closed.** An unreadable read is
|
|
138
|
+
unknown, never "not a member".
|
|
139
|
+
- **Setup** names an unavailable username, and points a new account at
|
|
140
|
+
`claim-human`. `--invite-stdin` reads the token without echo on a
|
|
141
|
+
terminal, and `oats aweb invite --out <file>` writes it to a new
|
|
142
|
+
owner-only file.
|
|
143
|
+
|
|
144
|
+
- **The Desktop's sidebar reads more calmly.** An agent's row is two lines: its name, then its soul and the machine it runs on ("oats-expert · falcon": this computer's own rows by its `host.name` in `oats-local.yaml`, else "This Mac"), in a 44px row with its dot centred. The repository, branch, pull request and harness badge are no longer on the row, and the row has no hover card and no tools on hover: the instance panel shows the repository, branch, harness and model, and a new **Needs input** section with the reason an agent waits, how long it has waited and its message; the row's context menu (right-click, Shift+F10 or the Menu key) opens its pull request (**Open pull request…**) and starts a stopped agent (**Start…**). Until the panel serves an agent whose terminal isn't open, the row's tooltip says its repository, branch, harness and model; with the keyboard alone those show once its terminal is open. The roster draws no lines between agents any more: a child is indented under its parent, a little space separates each group from the next, and a screen reader hears "under <parent>" (with "same work" for a child doing its parent's work) and "sibling of <name>". The order and the needs-input marks are unchanged, and the command palette keeps its lines. **Workspace overview** and **Automations** are pinned rows under the list of workspaces, and **Automations** shows a red dot, which a screen reader hears as "a run failed", while a schedule's last run failed. The foot shows **N need you** (it takes you to the first agent that needs you), **New agent** and **?** (the keyboard shortcuts). An empty roster says "No agents yet" and the key that starts one. The CLI and the docs still say "instance". See [the sidebar](../desktop.md#workspaces) and [its instance tree](../desktop.md#the-sidebars-instance-tree).
|
|
145
|
+
|
|
146
|
+
- **The Desktop's sidebar shows the top-level instances only until you open one.** An instance with children has a chevron before its name, with the number of instances under it. Click the chevron to show or hide its group; a click elsewhere on the row still opens its terminal, and Right and Left still open and close the focused row. Every instance at the top of the tree starts collapsed in each new window (except one still being set up or retired, or whose retire failed, which stays open), and an instance inside a group starts open. A collapsed instance still shows "! N below" for the hidden instances that need input. **Show in roster**, `--instance` and a spawn from the Desktop open the rows above the instance they show. The TUI's list is unchanged and still shows every instance open ([The sidebar's instance tree](../desktop.md#the-sidebars-instance-tree)).
|
|
147
|
+
|
|
148
|
+
## Fixed
|
|
149
|
+
|
|
150
|
+
- **The getting-started skill reads a failed join from what ran.** Its last messaging check (step 9, item 5) no longer says a run left the root outside the team when no root was made. After the signup or the labelled join it says no root was made or recorded, and a team create that recorded no root is rerun unchanged. Before the person's join window opens, the agent lists the per-team roots and compares the list afterwards, so a root from an earlier join is not read as this one. It compares the team's label as the provider writes the folder name: lowercase, `_` and `.` as `-`. When the window shows no `E_SETUP_` code, the agent asks for the window's last line. The agent still never sees the join's output, never reruns it, and asks for no secret ([#1746](https://github.com/oats-project/oats/issues/1746)).
|
|
151
|
+
|
|
152
|
+
## Removed
|
|
153
|
+
|
|
154
|
+
- **Show only the current workspace.** The list of workspaces always shows every workspace: the toggle, its ⌥⇧⌘O / Ctrl+Alt+Shift+O (which reaches a terminal's program again) and its palette command are gone, and a choice saved for it is ignored.
|
|
155
|
+
- **The sidebar's settings cog, its Hide sidebar button and its brand mark.** Theme, font and keyboard shortcuts are in the command palette (**Theme: choose…**, **Font: choose…**, **Shortcuts: edit keyboard shortcuts…**) and on the foot's **?**; the sidebar still hides with ⌘B / Ctrl+Shift+B, the palette's **Sidebar: toggle (hide/show)** and **Show sidebar**.
|
package/docs/servers.md
CHANGED
|
@@ -478,6 +478,7 @@ schedule's spec still travel as arguments.
|
|
|
478
478
|
| `instance stop --plan\|--apply`, `retire --plan`, `retire --plan-revision … --idempotency-key …` | the instance's home | `lifecycle-plans` (`lifecycleApi: 1`) |
|
|
479
479
|
| `instance color` | the instance's home | `instance-color` |
|
|
480
480
|
| `instance background` | the instance's home | `instance-background` |
|
|
481
|
+
| `instance pin` | the instance's home | `instance-pin` |
|
|
481
482
|
| `instance same-work` | the instance's home | `instance-same-work` |
|
|
482
483
|
|
|
483
484
|
`instance suggest-name` and `instance upgrade` are never routed: `--server` is
|
|
@@ -648,7 +649,10 @@ way, through the kernel's own read of it, and a value that read refuses is
|
|
|
648
649
|
dropped ([`retire`](desktop-cli-api.md#row-retire)). `sameWork` (feature
|
|
649
650
|
`instance-same-work`, the instance does the same work as its parent) is
|
|
650
651
|
relayed only when the host's row has `sameWork: true`, and is absent
|
|
651
|
-
otherwise ([`sameWork`](desktop-cli-api.md#row-same-work)).
|
|
652
|
+
otherwise ([`sameWork`](desktop-cli-api.md#row-same-work)). `pinned` (feature
|
|
653
|
+
`instance-pin`, the instance is pinned at the top of its machine's list) is
|
|
654
|
+
relayed only when the host's row has exactly `pinned: true`, and is absent
|
|
655
|
+
otherwise ([`pinned`](desktop-cli-api.md#row-pinned)). A removed or edited registration keeps
|
|
652
656
|
its group from the saved routes. State is pulled on every call, from every
|
|
653
657
|
group at once: each probe has its own deadline, `--per-target` (default 20 s)
|
|
654
658
|
capped by `--budget` (default 45 s, the deadline of the whole answer), and a
|
|
@@ -483,6 +483,17 @@ instance with the flag on carries `sameWork: true` on its `oats status
|
|
|
483
483
|
remote relay are in
|
|
484
484
|
[desktop-cli-api.md](desktop-cli-api.md#same-work-as-the-parent-oats-instance-same-work).
|
|
485
485
|
|
|
486
|
+
`oats instance pin <instance> on|off` (feature `instance-pin`) pins an
|
|
487
|
+
instance at the top of its machine's list, or removes the pin, addressed as
|
|
488
|
+
`oats instance background` addresses it and routed with `--server`. The pin
|
|
489
|
+
is the home's own file, `.oats-pinned.json`, so it is shared: every client of
|
|
490
|
+
that machine (the Desktop, the TUI, another machine's routed view) reads it
|
|
491
|
+
from the `pinned: true` on the instance's row and lists it first. It survives
|
|
492
|
+
a restart, a stop and a start, a resume and `oats instance upgrade`, and a
|
|
493
|
+
retire removes it with the home. No spawn flag or `soul.yaml` key sets it.
|
|
494
|
+
The answer and the errors are in
|
|
495
|
+
[desktop-cli-api.md](desktop-cli-api.md#pinned-instances-oats-instance-pin).
|
|
496
|
+
|
|
486
497
|
`spawnOrigin` records the caller independently of these links. For new spawns
|
|
487
498
|
from OATS 0.64.0, it is `instance` when the caller's `OATS_INSTANCE` and/or
|
|
488
499
|
`OATS_INSTANCE_HOME` resolve consistently to an extant home in this deployment;
|
package/docs/upgrading.md
CHANGED
|
@@ -6,12 +6,12 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.69.
|
|
10
|
-
The 0.69.
|
|
9
|
+
The latest version is **OATS 0.69.21** ([release notes](release-notes/v0.69.21.md)).
|
|
10
|
+
The 0.69.21 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
|
|
11
11
|
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
12
12
|
|
|
13
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
14
|
-
0.69.
|
|
14
|
+
0.69.21,** in the [release notes](release-notes/): it says what to do before
|
|
15
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
16
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
17
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -20,8 +20,8 @@ prints the version you have.
|
|
|
20
20
|
Then, on each host:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
# 0. where the Desktop is installed: Desktop 0.69.
|
|
24
|
-
npm install -g @awebai/oats@0.69.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.69.21, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.69.21 # 1. the CLI
|
|
25
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
26
26
|
oats doctor # 3. in the same deployment
|
|
27
27
|
```
|
|
@@ -217,6 +217,12 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
217
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
218
218
|
here.
|
|
219
219
|
|
|
220
|
+
- **[0.69.21](release-notes/v0.69.21.md#upgrade):** the catalog pins
|
|
221
|
+
oats.aweb 1.43.0. A deployment on a non-public aw registry runs
|
|
222
|
+
`oats aweb setup --registry <origin>`, reruns `oats aweb resident create`,
|
|
223
|
+
reinstalls the wake service and restarts its homes; exported aw selectors no
|
|
224
|
+
longer reach aw. Respawn grant seats whose resident or default team changed.
|
|
225
|
+
Respawn instances to take the new module.
|
|
220
226
|
- **[0.69.20](release-notes/v0.69.20.md#upgrade):** the catalog pins
|
|
221
227
|
oats.okf 6.2.0 and oats.framework 1.26.0. Retiring an old home whose
|
|
222
228
|
recorded cleanup hooks cannot run is refused; clean up its external state,
|
|
@@ -181,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
|
|
|
181
181
|
* declaration may not cover them: these exact names, and every exact name
|
|
182
182
|
* starting with one of these prefixes (the events log; the stop, restart and
|
|
183
183
|
* start receipts and locks; the rollback marker; AGENTS.md backups; the
|
|
184
|
-
* attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
|
|
184
|
+
* attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the pin, `.oats-pinned.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
|
|
185
185
|
* home entry MUST be added here and to the `not` patterns of
|
|
186
186
|
* `retirement.disposable.home` in docs/capability-manifest.schema.json. A
|
|
187
187
|
* prefix declaration can reach none of them except through `.oats-`, which is
|
|
188
188
|
* refused whole; `.oats-<provider>` as an exact name stays declarable. */
|
|
189
189
|
const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
|
|
190
|
-
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-same-work"];
|
|
190
|
+
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-pinned", ".oats-same-work"];
|
|
191
191
|
|
|
192
192
|
/** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
|
|
193
193
|
* name or prefix), "kernel-owned", or undefined when it is sound. */
|
package/lib/command-flags.mjs
CHANGED
|
@@ -102,6 +102,7 @@ export const COMMAND_FLAGS = Object.freeze([
|
|
|
102
102
|
{ command: "instance color", operands: ["instance", "color"], required: 1, values: INSTANCE_RECORD_VALUES, switches: ["--clear", "--json"],
|
|
103
103
|
usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
|
|
104
104
|
onOff("background"),
|
|
105
|
+
onOff("pin"),
|
|
105
106
|
onOff("same-work"),
|
|
106
107
|
waiting("set"),
|
|
107
108
|
waiting("clear"),
|
package/lib/core.mjs
CHANGED
|
@@ -98,6 +98,7 @@ import { systemTool } from "./system-tools.mjs";
|
|
|
98
98
|
import { SCOPE_ENV_NAMES, agentScope, agentScopeArgv, agentScopeUnit, creatorPlacement, serverScopePlan, serverScopeUnit, serverScopeWarning } from "./tmux-server-scope.mjs";
|
|
99
99
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
100
100
|
import { readInstanceBackground, writeInstanceBackground } from "./instance-background.mjs";
|
|
101
|
+
import { PIN_FILE } from "./instance-pin.mjs";
|
|
101
102
|
import { SAME_WORK_FILE, writeSameWork } from "./instance-same-work.mjs";
|
|
102
103
|
import { HOST_STOP_REASON, readStartExited, sessionEndOf, START_EXITED_FILE, STOP_RECEIPT_FILE } from "./session-end.mjs";
|
|
103
104
|
import { thisBoot } from "./session-seen.mjs";
|
|
@@ -5474,13 +5475,14 @@ function retireGitProbe(repo, args, { encoding } = {}) {
|
|
|
5474
5475
|
* as its own (`retirement.disposable.home`: KERNEL_HOME_NAMES and
|
|
5475
5476
|
* KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
|
|
5476
5477
|
// `.oats-color.json` (feature instance-color) and `.oats-background.json` (feature instance-background) are
|
|
5477
|
-
// presentation anyone may change at any time: never work.
|
|
5478
|
+
// presentation anyone may change at any time: never work. `.oats-pinned.json` (feature instance-pin) is
|
|
5479
|
+
// presentation of the same kind.
|
|
5478
5480
|
// `.oats-same-work.json` (feature instance-same-work) is kernel presentation of the same kind.
|
|
5479
5481
|
// `.oats-start-exited` (lib/session-end.mjs) is the window's record of how the harness ended: every
|
|
5480
5482
|
// launched home whose harness ever ended holds it.
|
|
5481
5483
|
// `.oats-start-env.json` and its key (lib/start-env.mjs) are written at every start that renders a
|
|
5482
5484
|
// recipe, after the spawn's baseline: every launched home holds them.
|
|
5483
|
-
const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
|
|
5485
|
+
const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", PIN_FILE, SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
|
|
5484
5486
|
// `instance.json.tmp-<pid>` is what a process killed between the two steps of writeJsonAtomic leaves
|
|
5485
5487
|
// of the record: not a hidden name, so a capability cannot declare it (disposableHomeRootProblem).
|
|
5486
5488
|
const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/, /^instance\.json\.tmp-\d+$/, START_ENV_TMP, LAUNCH_ENV_HANDOFF];
|
|
@@ -9557,7 +9559,7 @@ const claimCommand = (action) => action === "resume" ? "oats session start --res
|
|
|
9557
9559
|
/** What each verb that meets a held claim says it did not do: the words its refusals end with,
|
|
9558
9560
|
* before any effect. After a takeover ended a dead holder's step, every verb says the same
|
|
9559
9561
|
* (lib/errors.mjs nothingAfter). */
|
|
9560
|
-
const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance same-work": "the flag was not changed", "instance background": "the background was not changed" };
|
|
9562
|
+
const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance same-work": "the flag was not changed", "instance background": "the background was not changed", "instance pin": "the pin was not changed" };
|
|
9561
9563
|
|
|
9562
9564
|
/** The refusals of `arriving` ("retire", "stop", "upgrade", "resume", "start", or "worktree add", which
|
|
9563
9565
|
* reads the claim and does not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks
|
package/lib/instance-inspect.mjs
CHANGED
|
@@ -30,6 +30,7 @@ import { readLockIfPresent } from "./packages.mjs";
|
|
|
30
30
|
import { composeSoulInstructions } from "./soul-composition.mjs";
|
|
31
31
|
import { readInstanceColor } from "./instance-color.mjs";
|
|
32
32
|
import { readInstanceBackground } from "./instance-background.mjs";
|
|
33
|
+
import { readInstancePin } from "./instance-pin.mjs";
|
|
33
34
|
/** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
|
|
34
35
|
const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
|
|
35
36
|
import { parseStrictJson } from "./canonical-json.mjs";
|
|
@@ -543,6 +544,8 @@ export function inspectDocument(t, { kernel }) {
|
|
|
543
544
|
color: readInstanceColor(t.home),
|
|
544
545
|
// Feature instance-background: `true` while the home holds a valid record, absent otherwise (as on a row).
|
|
545
546
|
...(readInstanceBackground(t.home) ? { background: true } : {}),
|
|
547
|
+
// Feature instance-pin: `true` while the home holds a valid pin, absent otherwise (as on a row).
|
|
548
|
+
...(readInstancePin(t.home) ? { pinned: true } : {}),
|
|
546
549
|
resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
|
|
547
550
|
...(m ? { identity: servedIdentityOf(m) } : {}),
|
|
548
551
|
problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.skillsProblems || []), ...(t.composedSkillsProblems || []), ...(t.discoveryError ? [t.discoveryError] : []),
|
|
@@ -20,6 +20,7 @@ import { afterFirstEffect, isAnswerCode, kernelCode, lifecycleBusy, oatsError, r
|
|
|
20
20
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
21
21
|
import { INSTANCE_COLOR_API, INSTANCE_COLORS, writeInstanceColor } from "./instance-color.mjs";
|
|
22
22
|
import { INSTANCE_BACKGROUND_API, writeInstanceBackground } from "./instance-background.mjs";
|
|
23
|
+
import { INSTANCE_PIN_API, writeInstancePin } from "./instance-pin.mjs";
|
|
23
24
|
import { sameWorkOf, writeSameWork } from "./instance-same-work.mjs";
|
|
24
25
|
import { resolveInstance } from "./instance-address.mjs";
|
|
25
26
|
export { resolveInstance } from "./instance-address.mjs";
|
|
@@ -94,6 +95,21 @@ export function setInstanceBackground(ctx, root, name, { home, background }) {
|
|
|
94
95
|
return { instanceBackgroundApi: INSTANCE_BACKGROUND_API, instance: name, home: me.home, background, changed };
|
|
95
96
|
}
|
|
96
97
|
|
|
98
|
+
/** `oats instance pin <instance> on|off` (feature instance-pin): pin the home `name` resolves to at the top of
|
|
99
|
+
* its machine's list, or remove its pin, with the authority and the refusals of `instance background` above
|
|
100
|
+
* (setInstanceBackground), a stopped home included. The pin is the home's, so every viewer of the machine
|
|
101
|
+
* sees it. `pinned` is a boolean; the caller refused anything else.
|
|
102
|
+
* → `{ instancePinApi, instance, home, pinned, changed }`. */
|
|
103
|
+
export function setInstancePin(ctx, root, name, { home, pinned }) {
|
|
104
|
+
if (typeof pinned !== "boolean") throw oatsError("E_BAD_ARGS", "pinned must be on or off");
|
|
105
|
+
const me = resolveTarget(ctx, root, name, { home });
|
|
106
|
+
if (existsSync(join(me.home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${me.home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire); the pin was not changed`);
|
|
107
|
+
if (existsSync(retirePendingMarkerPath(me.home))) throw oatsError("E_INSTANCE_RETIRING", `${name} is being retired; the pin was not changed`);
|
|
108
|
+
refuseBesideRetire("instance pin", me.home);
|
|
109
|
+
const { changed } = writeInstancePin(me.home, pinned);
|
|
110
|
+
return { instancePinApi: INSTANCE_PIN_API, instance: name, home: me.home, pinned, changed };
|
|
111
|
+
}
|
|
112
|
+
|
|
97
113
|
/** `oats instance same-work <instance> on|off` (feature instance-same-work, awebai/oats#1577): bind the flag
|
|
98
114
|
* of the home `name` resolves to to its recorded parent (`on`), or remove it (`off`). Addressed, and refused
|
|
99
115
|
* beside a retire or in a quarantined home, exactly as setInstanceColor is. `on` needs a recorded
|
package/lib/instance-listing.mjs
CHANGED
|
@@ -15,6 +15,7 @@ import { isInstant as isInstantString, readRetireState } from "./retire-state.mj
|
|
|
15
15
|
import { herdrInstanceRemoved, oatsError } from "./errors.mjs";
|
|
16
16
|
import { readInstanceColor } from "./instance-color.mjs";
|
|
17
17
|
import { readInstanceBackground } from "./instance-background.mjs";
|
|
18
|
+
import { readInstancePin } from "./instance-pin.mjs";
|
|
18
19
|
import { sameWorkOf } from "./instance-same-work.mjs";
|
|
19
20
|
import { readSpawnedBy } from "./spawned-by.mjs";
|
|
20
21
|
import { sessionEndOf } from "./session-end.mjs";
|
|
@@ -349,9 +350,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
349
350
|
try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
|
|
350
351
|
catch { waitingOnYou = null; }
|
|
351
352
|
}
|
|
352
|
-
// `retire` is only ever the value read above, and `background` and `sameWork` the home's own
|
|
353
|
-
// (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
|
|
354
|
-
|
|
353
|
+
// `retire` is only ever the value read above, and `background`, `pinned` and `sameWork` the home's own
|
|
354
|
+
// records (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
|
|
355
|
+
// for it.
|
|
356
|
+
const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, sameWork: _recordedSameWork, ...recorded } = meta;
|
|
355
357
|
// `spawnedBy` (feature spawn-attribution) is the record's own, read in place by its rule (lib/spawned-by.mjs):
|
|
356
358
|
// a malformed one is null, and a home spawned before the feature has no key.
|
|
357
359
|
if (Object.hasOwn(recorded, "spawnedBy")) recorded.spawnedBy = readSpawnedBy(recorded.spawnedBy);
|
|
@@ -361,10 +363,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
361
363
|
const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? sessionEndOf(home, meta) : null;
|
|
362
364
|
// Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
|
|
363
365
|
// null, after the record so that nothing in instance.json stands in for it.
|
|
366
|
+
// Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
|
|
367
|
+
// otherwise, never false.
|
|
364
368
|
// Feature instance-same-work: `sameWork: true` only while the home's flag is bound to the parent
|
|
365
369
|
// its readable record names (lib/instance-same-work.mjs sameWorkOf); absent otherwise, never false.
|
|
366
370
|
const sameWork = record.state === "record" && sameWorkOf(home, meta.parentInstance);
|
|
367
|
-
return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
371
|
+
return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
368
372
|
|
|
369
373
|
});
|
|
370
374
|
};
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/** Whether an instance is pinned (feature instance-pin): presentation like the colour
|
|
2
|
+
* (lib/instance-color.mjs) and background (lib/instance-background.mjs), never identity or policy. A client
|
|
3
|
+
* of the machine lists a pinned instance at the top of its list; nothing else about the instance changes.
|
|
4
|
+
* The pin is the home's, so it is shared: everyone who views that machine sees it. It is a home file of
|
|
5
|
+
* its own, `<home>/.oats-pinned.json`, so that a start or restart, which rewrites instance.json, can never
|
|
6
|
+
* lose it, and retire removes it with the home.
|
|
7
|
+
*
|
|
8
|
+
* The record is `{ pinnedApi: 1, at }` (present means pinned), written atomically (writeThroughPrivateFile)
|
|
9
|
+
* at mode 0600; absent means not pinned, and `off` removes the file. A reader takes a regular file only,
|
|
10
|
+
* without following a link, up to RECORD_MAX bytes: anything that is not a valid record reads as not
|
|
11
|
+
* pinned (false), never an error. Dependency-free: the status rows, inspect and the command all read and
|
|
12
|
+
* write it through here. */
|
|
13
|
+
import { lstatSync, rmSync } from "node:fs";
|
|
14
|
+
import { join } from "node:path";
|
|
15
|
+
import { readFileHead } from "./bounded-read.mjs";
|
|
16
|
+
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
17
|
+
|
|
18
|
+
/** The record's own version, and the command answer's. */
|
|
19
|
+
export const PIN_API = 1;
|
|
20
|
+
export const INSTANCE_PIN_API = 1;
|
|
21
|
+
/** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
|
|
22
|
+
* fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
|
|
23
|
+
export const PIN_FILE = ".oats-pinned.json";
|
|
24
|
+
/** A record larger than this is not one. */
|
|
25
|
+
export const RECORD_MAX = 4096;
|
|
26
|
+
|
|
27
|
+
/** Whether `home` records itself pinned: false for no file, not a regular file (a link is never followed),
|
|
28
|
+
* over RECORD_MAX bytes, unreadable, not a JSON object or another pinnedApi. Never throws. */
|
|
29
|
+
export function readInstancePin(home) {
|
|
30
|
+
try {
|
|
31
|
+
const { bytes, size } = readFileHead(join(home, PIN_FILE), RECORD_MAX + 1);
|
|
32
|
+
if (size > RECORD_MAX) return false;
|
|
33
|
+
const record = JSON.parse(bytes.toString("utf8"));
|
|
34
|
+
return !!record && typeof record === "object" && !Array.isArray(record) && record.pinnedApi === PIN_API;
|
|
35
|
+
} catch { return false; }
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Pin `home` (`on` true), or remove its pin (`on` false). → `{ pinned, changed }`. A home already pinned is
|
|
39
|
+
* no change: nothing is written. `off` removes whatever stands at the name (a link or an invalid record
|
|
40
|
+
* included) and is a change only when the home read as pinned. The caller holds the right to change the
|
|
41
|
+
* home. */
|
|
42
|
+
export function writeInstancePin(home, on, { now = () => new Date() } = {}) {
|
|
43
|
+
const path = join(home, PIN_FILE);
|
|
44
|
+
const before = readInstancePin(home);
|
|
45
|
+
// What stands at the name, never followed: null for nothing. The name is kernel-owned, so a directory
|
|
46
|
+
// there is no one's work: `off` removes it, and `on` removes it before the record is renamed into place
|
|
47
|
+
// (a rename cannot replace a directory).
|
|
48
|
+
let standing = null;
|
|
49
|
+
try { standing = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
|
|
50
|
+
if (!on) {
|
|
51
|
+
if (standing) rmSync(path, { force: true, recursive: standing.isDirectory() });
|
|
52
|
+
return { pinned: false, changed: before };
|
|
53
|
+
}
|
|
54
|
+
if (before) return { pinned: true, changed: false };
|
|
55
|
+
if (standing?.isDirectory()) rmSync(path, { force: true, recursive: true });
|
|
56
|
+
const bytes = JSON.stringify({ pinnedApi: PIN_API, at: now().toISOString() }) + "\n";
|
|
57
|
+
writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
|
|
58
|
+
return { pinned: true, changed: true };
|
|
59
|
+
}
|
package/lib/kernel-features.mjs
CHANGED
|
@@ -8,6 +8,6 @@ import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
|
|
|
8
8
|
/** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
|
|
9
9
|
* its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
|
|
10
10
|
export const SPAWN_TASK_STDIN_FEATURE = "spawn-task-stdin";
|
|
11
|
-
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE]);
|
|
11
|
+
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE]);
|
|
12
12
|
/** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
|
|
13
13
|
export const READER_API = 1;
|
package/lib/servers.mjs
CHANGED
|
@@ -936,6 +936,8 @@ const HOST_SURFACES = {
|
|
|
936
936
|
"instance color": { feature: "instance-color" },
|
|
937
937
|
// Feature instance-background: the same (its answer's instanceBackgroundApi is not a probe key).
|
|
938
938
|
"instance background": { feature: "instance-background" },
|
|
939
|
+
// Feature instance-pin: the feature alone, as instance background.
|
|
940
|
+
"instance pin": { feature: "instance-pin" },
|
|
939
941
|
// Feature instance-same-work: the feature alone, as instance color.
|
|
940
942
|
"instance same-work": { feature: "instance-same-work" },
|
|
941
943
|
};
|
|
@@ -946,7 +948,7 @@ function requireSurface(remote, target, surface) {
|
|
|
946
948
|
}
|
|
947
949
|
}
|
|
948
950
|
|
|
949
|
-
/** `readiness`, `instance events|git|diff|stop|color|background|same-work` and `retire --plan` on the
|
|
951
|
+
/** `readiness`, `instance events|git|diff|stop|color|background|pin|same-work` and `retire --plan` on the
|
|
950
952
|
* host: the instance is addressed as every routed session command addresses
|
|
951
953
|
* it (its name through a saved route or the host's roster, or an exact
|
|
952
954
|
* --home), the scope is an explicit --dir on the host or the registered
|
|
@@ -955,7 +957,7 @@ function requireSurface(remote, target, surface) {
|
|
|
955
957
|
function routeHostSurface(serverId, cmd, oatsArgs, io) {
|
|
956
958
|
const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
|
|
957
959
|
const surface = HOST_SURFACES[key];
|
|
958
|
-
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background and same-work only (not ${key})`);
|
|
960
|
+
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and same-work only (not ${key})`);
|
|
959
961
|
const args = [...oatsArgs];
|
|
960
962
|
const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
|
|
961
963
|
const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
|
|
@@ -1016,6 +1018,9 @@ const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: re
|
|
|
1016
1018
|
/** `background` (feature instance-background) only as `true`, relayed ONLY when the host's row says exactly
|
|
1017
1019
|
* that: absent is the only reading of "not background", so any other value is dropped, never false. */
|
|
1018
1020
|
const rowBackground = (i) => (i.background === true ? { background: true } : {});
|
|
1021
|
+
/** `pinned` (feature instance-pin) as `background`: relayed ONLY when the host's row says exactly `true`;
|
|
1022
|
+
* absent is the only reading of "not pinned", so any other value (`"true"`, `1`) is dropped, never false. */
|
|
1023
|
+
const rowPinned = (i) => (i.pinned === true ? { pinned: true } : {});
|
|
1019
1024
|
/** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
|
|
1020
1025
|
* key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
|
|
1021
1026
|
* only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
|
|
@@ -1134,7 +1139,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
1134
1139
|
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
|
|
1135
1140
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
1136
1141
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
1137
|
-
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i), ...rowSessionEnd(i),
|
|
1142
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowSameWork(i), ...rowSessionEnd(i),
|
|
1138
1143
|
// Every row the host reports is addressed by its home, saved
|
|
1139
1144
|
// route or not; savedRoute says only that it was spawned from here.
|
|
1140
1145
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
package/package-catalog.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.69.
|
|
3
|
+
"version": "0.69.21",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/** The two text facts of an instance row in a sidebar roster (the Desktop UI rework, slice 1), shared so the
|
|
2
|
+
* Terminal UI can draw the same row: line 1 the display name, line 2 `<soul> · <machine>`.
|
|
3
|
+
*
|
|
4
|
+
* rosterRowFacts(row, terms, { deployments, here }) -> { name, detail, soul, machine }
|
|
5
|
+
*
|
|
6
|
+
* name the instance name as words (instance-display-name.mjs), else the name as reported, else ''
|
|
7
|
+
* soul the row's soul (`agent`), one display line, else null (a forgotten or malformed row)
|
|
8
|
+
* machine where the row runs: the machine of the deployment the row is tagged with (`deployment.id` among
|
|
9
|
+
* `deployments`, a view's), else a remote server row's label (remote-address.mjs `serverLabel`), else
|
|
10
|
+
* this machine: its own name when the caller knows it (`here`, the host name the kernel reports for this
|
|
11
|
+
* machine), else `terms.thisMachine` (client-terms.mjs). A row of this machine's own deployment is this
|
|
12
|
+
* machine's too, whatever label the deployment carries. A view's row may carry `server` and a repository
|
|
13
|
+
* in `repoName`, so its deployment's machine comes first. Always a label: a row that names no machine is
|
|
14
|
+
* this machine's
|
|
15
|
+
* detail `soul · machine`, or the machine alone when no soul is known
|
|
16
|
+
*
|
|
17
|
+
* The facts only: no state, no reason, no repository, no harness. A row whose machine didn't answer keeps both
|
|
18
|
+
* lines; its state is the dot's and its reason the row's description. Display only, never an identity: the real
|
|
19
|
+
* name stays wherever it identifies the instance. Pure: no DOM, no IO. */
|
|
20
|
+
import { instanceDisplayName } from './instance-display-name.mjs';
|
|
21
|
+
import { serverLabel } from './remote-address.mjs';
|
|
22
|
+
import { displayLine, DETAIL_WITHHELD } from './display-text.mjs';
|
|
23
|
+
import { requireTerms } from './client-terms.mjs';
|
|
24
|
+
|
|
25
|
+
/** One display line, or null for nothing to show (absent, not text, withheld). */
|
|
26
|
+
const shown = (value) => {
|
|
27
|
+
const line = typeof value === 'string' ? displayLine(value) : null;
|
|
28
|
+
return line && line !== DETAIL_WITHHELD ? line : null;
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
/** The machine label of `row`, in `terms` (see the module's comment). */
|
|
32
|
+
export function rowMachine(row, terms, { deployments = [], here = null } = {}) {
|
|
33
|
+
requireTerms(terms, 'rowMachine');
|
|
34
|
+
const id = typeof row?.deployment?.id === 'string' ? row.deployment.id : null;
|
|
35
|
+
const deployment = id && Array.isArray(deployments) ? deployments.find((d) => d?.id === id) : null;
|
|
36
|
+
const server = typeof row?.server === 'string' && row.server ? shown(serverLabel(row)) ?? shown(row.server) : null;
|
|
37
|
+
const thisMachine = shown(here) ?? terms.thisMachine;
|
|
38
|
+
if (deployment?.local === true) return thisMachine;
|
|
39
|
+
return shown(deployment?.machine) ?? server ?? thisMachine;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The row's two lines and their parts. */
|
|
43
|
+
export function rosterRowFacts(row, terms, { deployments = [], here = null } = {}) {
|
|
44
|
+
requireTerms(terms, 'rosterRowFacts');
|
|
45
|
+
const instance = typeof row?.instance === 'string' ? row.instance : '';
|
|
46
|
+
const name = instanceDisplayName(instance) || instance;
|
|
47
|
+
const soul = shown(row?.agent);
|
|
48
|
+
const machine = rowMachine(row, terms, { deployments, here });
|
|
49
|
+
return { name, detail: [soul, machine].filter(Boolean).join(' · '), soul, machine };
|
|
50
|
+
}
|