@awebai/oats 0.69.20 → 0.69.22
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/container.md +311 -4
- package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
- package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
- package/docs/desktop-cli-api.md +80 -0
- package/docs/desktop.md +404 -177
- package/docs/implementation.md +15 -2
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/official-catalog.md +44 -1
- package/docs/packages.md +2 -2
- package/docs/release-lane.md +8 -6
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/release-notes/v0.69.22.md +221 -0
- package/docs/servers.md +5 -1
- package/docs/souls-and-instances.md +11 -0
- package/docs/tui.md +44 -4
- package/docs/upgrading.md +16 -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/above-tested.mjs +3 -2
- package/packages/client/capability-list.mjs +69 -0
- package/packages/client/capability-origin.mjs +54 -0
- package/packages/client/cli-adapter.mjs +9 -1
- package/packages/client/deployment-data.mjs +3 -0
- package/packages/client/deployment-panel.mjs +2 -0
- package/packages/client/home-board.mjs +50 -0
- package/packages/client/instance-pin.mjs +28 -0
- package/packages/client/instance-record-outcome.mjs +31 -0
- package/packages/client/instance-tree.mjs +62 -20
- package/packages/client/keymap.mjs +11 -3
- package/packages/client/remote-roster.mjs +8 -1
- package/packages/client/roster-row-facts.mjs +50 -0
- package/packages/client/roster-sections.mjs +10 -7
- package/packages/client/soul-role.mjs +44 -0
- package/packages/client/waiting-on-you.mjs +10 -0
- package/packages/tui/lib/actions.mjs +11 -4
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/main.mjs +16 -2
- package/packages/tui/lib/model.mjs +48 -5
- package/packages/tui/lib/store.mjs +28 -2
- package/skills/oats-getting-started/SKILL.md +283 -30
package/docs/tui.md
CHANGED
|
@@ -182,7 +182,9 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
182
182
|
place when it gains or loses one. Under one parent, the instances that do
|
|
183
183
|
its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
|
|
184
184
|
come first, then the others, each part newest first, as the Desktop lists
|
|
185
|
-
them.
|
|
185
|
+
them. Pinned instances come before all of these, at every level, and an
|
|
186
|
+
instance with a pinned one below it counts as pinned
|
|
187
|
+
([Pinning](#pinning)). An empty row stands between each run
|
|
186
188
|
of instances related to no other and the group before or after it. The
|
|
187
189
|
indent alone says which instance is under which: no mark is drawn for
|
|
188
190
|
it. A row whose instances are folded away (`h`) says how many after its
|
|
@@ -744,9 +746,14 @@ The panel can be split in two **groups**, side by side or one above the
|
|
|
744
746
|
other. Each group is a panel of [tabs](#tabs) of its own: a tab bar, a shown
|
|
745
747
|
tab and the marks of its hidden ones.
|
|
746
748
|
|
|
747
|
-
- **
|
|
748
|
-
|
|
749
|
-
|
|
749
|
+
- **The list out of the way.** The leader then `b` gives the shown terminal the
|
|
750
|
+
whole screen with the focus, and again gives the list back with the focus (the
|
|
751
|
+
Desktop's `b` hides its sidebar; the list is the TUI's). With no terminal shown
|
|
752
|
+
it does nothing.
|
|
753
|
+
- **Splitting.** The leader then `|` (or `h`) splits the panel side by side, and the
|
|
754
|
+
leader then `-` (or `v`) one above the other; in the Instances view `|` and `-`
|
|
755
|
+
do the same without the leader. (`h` and `v` are Herdr's letters, shared with the
|
|
756
|
+
Desktop since its UI rework.) The tabs open stay in the first group
|
|
750
757
|
(left, or top). The second group starts empty and is the focused group.
|
|
751
758
|
- A split needs a tab open, and none starting.
|
|
752
759
|
- **There are at most two groups.** With two, the split keys do nothing,
|
|
@@ -1301,6 +1308,38 @@ The exit status never depends on it.
|
|
|
1301
1308
|
there can leave `.oats-stop-pending.json` in the agent's home, and then
|
|
1302
1309
|
the agent can be started but not stopped while that file exists.
|
|
1303
1310
|
|
|
1311
|
+
## Pinning
|
|
1312
|
+
|
|
1313
|
+
`p` pins the selected instance to the top of its machine's list, or unpins a
|
|
1314
|
+
pinned one. It runs `oats instance pin <name> on|off` at once, with no
|
|
1315
|
+
confirmation: a pin changes only the order, and `p` again undoes it. The line
|
|
1316
|
+
under the sidebar's title says `Pinning <name>…`, then the result, and the
|
|
1317
|
+
list is read again, so the row moves.
|
|
1318
|
+
|
|
1319
|
+
- **The order** is the Desktop's, from the same code. Pinned instances come
|
|
1320
|
+
first at every level: the groups of a machine's list, the instances of a
|
|
1321
|
+
group, and the children of one parent. An instance counts as pinned when
|
|
1322
|
+
it or any instance below it is, so pinning a child lifts its whole group,
|
|
1323
|
+
and the path down to it rises among its siblings. Among pinned instances,
|
|
1324
|
+
and among the others, the order is spawn time, newest first. Under one
|
|
1325
|
+
parent, the instances that do its work still come first. A pinned
|
|
1326
|
+
background instance leads the Background section. A filter never
|
|
1327
|
+
reorders the list. The palette lists the instances you opened most
|
|
1328
|
+
recently first, as before, and the others in this order.
|
|
1329
|
+
- **Shared.** The pin is kept in the instance's home, so everyone who views
|
|
1330
|
+
that machine sees it, in the TUI, the Desktop and another machine's view.
|
|
1331
|
+
There is no pin of your own.
|
|
1332
|
+
- **When `p` does nothing**, the line says why: this OATS doesn't list the
|
|
1333
|
+
`instance-pin` feature (then `oats instance pin <name> on|off` needs a
|
|
1334
|
+
newer OATS too), the instance is held by a spawn or a retire, or its pin
|
|
1335
|
+
is still changing. For an instance on another machine whose OATS doesn't
|
|
1336
|
+
list the feature, the kernel refuses before it sends anything, and the
|
|
1337
|
+
line gives its words.
|
|
1338
|
+
- **The key.** `p` is a default key from this version on. A `tui.json` that
|
|
1339
|
+
gives `p` to another action is refused at the start, with a line that
|
|
1340
|
+
names the key and both actions: move that action to another key, or give
|
|
1341
|
+
`pin` another key (or none) in `tui.json`.
|
|
1342
|
+
|
|
1304
1343
|
## Resuming lost sessions
|
|
1305
1344
|
|
|
1306
1345
|
After a shutdown, a reboot or a crash, the instances that were running have
|
|
@@ -1472,6 +1511,7 @@ that kind.
|
|
|
1472
1511
|
| close the empty group | – | – | – | – | – | `x` |
|
|
1473
1512
|
| stop, restart, start, retire | `X`, `R`, `S`, `D` | – | – | – | – | `X`, `R`, `S`, `D` |
|
|
1474
1513
|
| spawn another of the soul | `N` | – | – | – | – | `N` |
|
|
1514
|
+
| pin or unpin (`oats tui` only; the Desktop's is in the row's menu) | `p` | – | – | – | – | – |
|
|
1475
1515
|
| the Instances, Souls, Capabilities views | `1`, `2`, `3` | – | – | – | – | `1`, `2`, `3` |
|
|
1476
1516
|
| the help | `?` | – | – | – | – | `?` |
|
|
1477
1517
|
| the list | `Esc` | – | – | – | – | `Esc` |
|
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.22** ([release notes](release-notes/v0.69.22.md)).
|
|
10
|
+
The 0.69.22 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.22,** 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.22, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.69.22 # 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,17 @@ 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.22](release-notes/v0.69.22.md#upgrade):** the catalog pins
|
|
221
|
+
oats.aweb 1.45.0; `setup --install-aw` installs the tested aw by default.
|
|
222
|
+
The Desktop's leader is Ctrl+Space (Ctrl+X a click away; a leader you set is
|
|
223
|
+
kept). A `tui.json` that binds `p` to another action moves it. Respawn
|
|
224
|
+
instances to take the new module.
|
|
225
|
+
- **[0.69.21](release-notes/v0.69.21.md#upgrade):** the catalog pins
|
|
226
|
+
oats.aweb 1.43.0. A deployment on a non-public aw registry runs
|
|
227
|
+
`oats aweb setup --registry <origin>`, reruns `oats aweb resident create`,
|
|
228
|
+
reinstalls the wake service and restarts its homes; exported aw selectors no
|
|
229
|
+
longer reach aw. Respawn grant seats whose resident or default team changed.
|
|
230
|
+
Respawn instances to take the new module.
|
|
220
231
|
- **[0.69.20](release-notes/v0.69.20.md#upgrade):** the catalog pins
|
|
221
232
|
oats.okf 6.2.0 and oats.framework 1.26.0. Retiring an old home whose
|
|
222
233
|
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.22",
|
|
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",
|
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
Why these and not others: the four traced cases on #1879 (schedule edit at 0.40, Remove at 0.49 and
|
|
10
10
|
0.53, the Stop outcome at 0.52) all sit where the Desktop words a consequence itself or writes a whole
|
|
11
11
|
definition. What stays on is a read, a terminal, or a change fenced by the kernel's own answer: Spawn
|
|
12
|
-
applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour
|
|
13
|
-
background report only an answer the Desktop reads in full (each fails closed on a shape it does not
|
|
12
|
+
applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour,
|
|
13
|
+
background and pin report only an answer the Desktop reads in full (each fails closed on a shape it does not
|
|
14
14
|
know).
|
|
15
15
|
|
|
16
16
|
Enforcement is not the renderer's. Every place an operation enters the backend asks
|
|
@@ -65,6 +65,7 @@ export const OPERATIONS = Object.freeze({
|
|
|
65
65
|
// ── An instance's own record.
|
|
66
66
|
'POST /api/instance-color': allowed("colour: one field of the instance's own record, the answer read in full"),
|
|
67
67
|
'POST /api/instance-background': allowed("background: one field of the instance's own record, the answer read in full"),
|
|
68
|
+
'POST /api/instance-pin': allowed("pin: one field of the instance's own record, the answer read in full"),
|
|
68
69
|
// ── Reads.
|
|
69
70
|
'POST /api/instance-git git': read('git'),
|
|
70
71
|
'POST /api/instance-git diff': read('git'),
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/** The workspace's capabilities as one flat list, as both clients draw it (the Desktop UI rework, slice 3b: "show
|
|
2
|
+
* core and other ones as really the same"). Core capabilities (a knowledge, messaging or tasks `layer`) come first
|
|
3
|
+
* in that order, then every other one by name. Each entry carries what its row says: its core slot, whether it
|
|
4
|
+
* is one of the workspace's defaults (`oats workspace status` `defaults`), and who made it (capability-origin.mjs).
|
|
5
|
+
* Nothing is inferred: a default is matched to a row only by the name and the source the kernel reports, and
|
|
6
|
+
* with no reported `defaults` no row is called a default. Pure and DOM-free. */
|
|
7
|
+
import { sameRepo } from './repo-moves.mjs';
|
|
8
|
+
import { memberNames, hostKeyOf, matchCapabilities } from './capability-rows.mjs';
|
|
9
|
+
import { capabilityOrigin } from './capability-origin.mjs';
|
|
10
|
+
|
|
11
|
+
/** The core slots, in the one order every surface shows them. */
|
|
12
|
+
export const CORE_LAYERS = Object.freeze(['knowledge', 'messaging', 'tasks']);
|
|
13
|
+
|
|
14
|
+
const record = v => !!v && typeof v === 'object' && !Array.isArray(v);
|
|
15
|
+
const text = v => typeof v === 'string' && v ? v : null;
|
|
16
|
+
const list = v => Array.isArray(v) ? v : [];
|
|
17
|
+
|
|
18
|
+
/** Whether a declared default (`{ name, from }`: `from` is "package", "here" or a member key) names this row. */
|
|
19
|
+
export function defaultNames(entry, row, hostKey = null) {
|
|
20
|
+
if (!record(entry) || entry.name !== row?.name) return false;
|
|
21
|
+
if (entry.from === 'package') return row.kind === 'package';
|
|
22
|
+
if (entry.from === 'here') return row.kind === 'member' && !!text(hostKey) && sameRepo(row.repoKey, hostKey);
|
|
23
|
+
if (text(entry.from)) return row.kind === 'member' && sameRepo(row.repoKey, entry.from);
|
|
24
|
+
return false;
|
|
25
|
+
}
|
|
26
|
+
/** The row's place in the workspace's defaults: 'on' (every soul starts with it), 'off' (the workspace turns it
|
|
27
|
+
* off), or null (not a default, or no defaults reported). A turned-off entry reports no source: it is matched by
|
|
28
|
+
* name. A slot default fills its core slot (`defaults.slots.<layer>`). */
|
|
29
|
+
export function defaultState(status, row) {
|
|
30
|
+
const defaults = status?.defaults;
|
|
31
|
+
if (!record(defaults) || !row) return null;
|
|
32
|
+
const hostKey = hostKeyOf(status);
|
|
33
|
+
for (const cap of list(defaults.capabilities)) {
|
|
34
|
+
if (!record(cap) || cap.name !== row.name) continue;
|
|
35
|
+
if (cap.off === true) return 'off';
|
|
36
|
+
if (defaultNames(cap, row, hostKey)) return 'on';
|
|
37
|
+
}
|
|
38
|
+
const slot = text(row.layer) && record(defaults.slots) ? defaults.slots[row.layer] : null;
|
|
39
|
+
return record(slot) && defaultNames(slot, row, hostKey) ? 'on' : null;
|
|
40
|
+
}
|
|
41
|
+
/** The rank of a row in the list: a core slot's index, else after every core one. */
|
|
42
|
+
const rank = row => { const at = CORE_LAYERS.indexOf(row?.layer); return at < 0 ? CORE_LAYERS.length : at; };
|
|
43
|
+
|
|
44
|
+
/** The list's entries, in drawn order: `{ row, core, default, origin }`. `core`: the row's core slot or null;
|
|
45
|
+
* `default`: defaultState; `origin`: capabilityOrigin. `query` narrows by name (matchCapabilities). */
|
|
46
|
+
export function capabilityList(rows, status, { query = '' } = {}) {
|
|
47
|
+
const names = memberNames(status);
|
|
48
|
+
return matchCapabilities(list(rows), query)
|
|
49
|
+
.map(row => ({ row, core: CORE_LAYERS.includes(row.layer) ? row.layer : null, default: defaultState(status, row), origin: capabilityOrigin(row, status, names) }))
|
|
50
|
+
.sort((a, b) => rank(a.row) - rank(b.row) || String(a.row.name).localeCompare(String(b.row.name)) || a.origin.by.localeCompare(b.origin.by));
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** What the list's lead sentence needs, from the reported defaults: null when the kernel reports none (no claim).
|
|
54
|
+
* `empty`: the workspace sets no default at all. `emptySlots`: the core slots no default fills (by a slot or a
|
|
55
|
+
* named capability of that layer), in CORE_LAYERS order. `unlisted`: the declared defaults no catalog row
|
|
56
|
+
* matches (`{ name, off }`), so the list cannot show them as rows; a turned-off one is unlisted when no row has
|
|
57
|
+
* its name. */
|
|
58
|
+
export function defaultsSummary(status, rows) {
|
|
59
|
+
const defaults = status?.defaults;
|
|
60
|
+
if (!record(defaults)) return null;
|
|
61
|
+
const hostKey = hostKeyOf(status), all = list(rows);
|
|
62
|
+
const slots = CORE_LAYERS.map(layer => [layer, record(defaults.slots) && record(defaults.slots[layer]) && text(defaults.slots[layer].name) ? defaults.slots[layer] : null]);
|
|
63
|
+
const caps = list(defaults.capabilities).filter(cap => record(cap) && text(cap.name));
|
|
64
|
+
const listed = entry => entry.off === true ? all.some(row => row?.name === entry.name) : all.some(row => defaultNames(entry, row, hostKey));
|
|
65
|
+
const filled = new Set(slots.filter(([, value]) => value).map(([layer]) => layer));
|
|
66
|
+
for (const cap of caps) if (cap.off !== true) for (const row of all) if (defaultNames(cap, row, hostKey) && CORE_LAYERS.includes(row.layer)) filled.add(row.layer);
|
|
67
|
+
const unlisted = [...slots.filter(([, value]) => value).map(([, value]) => value), ...caps].filter(entry => !listed(entry)).map(entry => ({ name: entry.name, off: entry.off === true }));
|
|
68
|
+
return { empty: !filled.size && !caps.length, emptySlots: CORE_LAYERS.filter(layer => !filled.has(layer)), unlisted };
|
|
69
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/** Who made a capability, as both clients say it on a capability row (the Desktop UI rework, D24): "official"
|
|
2
|
+
* (a small ✓ whose words say which fact made it official: "Official: in the OATS catalog" or "Official: from the
|
|
3
|
+
* OATS repository") or "by <source>". The words say only what the rule shows: "verified" or "published by OATS" is a
|
|
4
|
+
* trust claim a client rule can't make (dec-feb06c322c75, "listed is not trusted"); a kernel fact for "official" is
|
|
5
|
+
* oats-project/oats#1981. Decided from facts the kernel
|
|
6
|
+
* already reports, never from a name (an `oats.` prefix proves nothing) and never from a new field:
|
|
7
|
+
*
|
|
8
|
+
* - a **package** capability is official when `oats workspace status` reports its package pinned from the
|
|
9
|
+
* catalog (`packages[].source` is `catalog:<id>`): only the reviewed official catalog makes a package
|
|
10
|
+
* pinnable by id (docs/packages.md, docs/official-catalog.md). Caveat: `OATS_PACKAGE_CATALOG` can point a kernel
|
|
11
|
+
* at another catalog file, and status does not say which one was read. An operator who points it elsewhere gets the
|
|
12
|
+
* ✓ for that catalog's packages: their choice (the effort's lead, 2026-11-19).
|
|
13
|
+
* A package pinned by `git:<repo>@<ref>` is "by <repo>", whatever its id;
|
|
14
|
+
* - a **member** capability is official when its repository is the OATS repository itself
|
|
15
|
+
* (github.com/oats-project/oats, or its old key github.com/awebai/oats: repo-moves.mjs);
|
|
16
|
+
* - anything else (another member, an external source, a package status does not list) is "by <source>".
|
|
17
|
+
*
|
|
18
|
+
* Pure and DOM-free; the words are ORIGIN_COPY so no client writes its own. */
|
|
19
|
+
import { sameRepo } from './repo-moves.mjs';
|
|
20
|
+
import { capabilitySource, memberNames } from './capability-rows.mjs';
|
|
21
|
+
|
|
22
|
+
/** The OATS repository's key (its moved spelling is the same repository: sameRepo). */
|
|
23
|
+
export const OATS_REPO_KEY = 'github.com/oats-project/oats';
|
|
24
|
+
|
|
25
|
+
export const ORIGIN_COPY = Object.freeze({
|
|
26
|
+
official: 'OATS',
|
|
27
|
+
// The mark's words per the fact that made it official (`reason`): its tooltip and its accessible name.
|
|
28
|
+
officialTitle: Object.freeze({ catalog: 'Official: in the OATS catalog', 'oats-repo': 'Official: from the OATS repository' }),
|
|
29
|
+
by: source => `by ${source}`,
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
const text = v => typeof v === 'string' && v ? v : null;
|
|
33
|
+
const list = v => Array.isArray(v) ? v : [];
|
|
34
|
+
/** `git:<repo>@<ref>` → the repository's last path segment, without `.git`; null for anything else. */
|
|
35
|
+
function gitRepoName(source) {
|
|
36
|
+
const m = /^git:(.+)@[^@]*$/.exec(source || '');
|
|
37
|
+
if (!m) return null;
|
|
38
|
+
return m[1].replace(/\.git$/, '').split(/[/:]/).filter(Boolean).pop() || null;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** `{ official, by, reason }` for a catalog row (`oats capabilities`, or a soul's resolved capability in the same
|
|
42
|
+
* shape). `by` is the source as words ("OATS" when official); `reason` is the fact that decided it: 'catalog'
|
|
43
|
+
* (a package pinned from the catalog), 'oats-repo' (a member capability of the OATS repository), else null.
|
|
44
|
+
* `status`: workspace status (packages[] and members[]); `names`: memberNames(status) when the caller holds it. */
|
|
45
|
+
export function capabilityOrigin(row, status, names = memberNames(status)) {
|
|
46
|
+
if (row?.kind === 'package') {
|
|
47
|
+
const pkg = list(status?.packages).find(p => p?.id === row.package);
|
|
48
|
+
const source = text(pkg?.source);
|
|
49
|
+
if (source && source.startsWith('catalog:')) return { official: true, by: ORIGIN_COPY.official, reason: 'catalog' };
|
|
50
|
+
return { official: false, by: gitRepoName(source) || text(row.package) || text(row.name) || 'a package', reason: null };
|
|
51
|
+
}
|
|
52
|
+
if (row?.kind === 'member' && text(row.repoKey) && sameRepo(row.repoKey, OATS_REPO_KEY)) return { official: true, by: ORIGIN_COPY.official, reason: 'oats-repo' };
|
|
53
|
+
return { official: false, by: capabilitySource(row || {}, names).label, reason: null };
|
|
54
|
+
}
|
|
@@ -655,7 +655,7 @@ export function operationArgs(args) {
|
|
|
655
655
|
}
|
|
656
656
|
/** A verb that writes one field of an instance's own record: `oats instance <verb> <instance> <values…> --home <home>
|
|
657
657
|
* (--dir <context> | --server <server>) --json`, addressed as `oats instance stop` is (lifecycle-cli.mjs: a routed
|
|
658
|
-
* command never carries --dir). Shared by `instance color` and `instance
|
|
658
|
+
* command never carries --dir). Shared by `instance color`, `instance background` and `instance pin` (server/instance-record.mjs);
|
|
659
659
|
* each checks its own value first. Anything out of shape is refused here and nothing runs. A read's deadline:
|
|
660
660
|
* 30 s, 45 s routed. The envelope comes back as the kernel printed it; the caller decodes it. */
|
|
661
661
|
function runInstanceRecord(bin, { instance, home, context, server }, verb, values, io) {
|
|
@@ -686,6 +686,14 @@ export async function cliInstanceBackground(bin, args, io = {}) {
|
|
|
686
686
|
if (typeof background !== "boolean") return instanceRecordRefused();
|
|
687
687
|
return runInstanceRecord(bin, args, "background", [background ? "on" : "off"], io);
|
|
688
688
|
}
|
|
689
|
+
/** Whether an instance is pinned (feature instance-pin): `oats instance pin <instance> (on | off) …`
|
|
690
|
+
* (runInstanceRecord). `pinned` is a boolean; anything else is refused here and nothing runs. Over `--server`, a
|
|
691
|
+
* host without the feature refuses it (E_REMOTE_INCOMPATIBLE). */
|
|
692
|
+
export async function cliInstancePin(bin, args, io = {}) {
|
|
693
|
+
const { pinned } = args;
|
|
694
|
+
if (typeof pinned !== "boolean") return instanceRecordRefused();
|
|
695
|
+
return runInstanceRecord(bin, args, "pin", [pinned ? "on" : "off"], io);
|
|
696
|
+
}
|
|
689
697
|
|
|
690
698
|
/** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
|
|
691
699
|
* gates the flags (also `instructions`, `skills` and `composedSkills`), so an undeclared kernel gets the flagless argv even when a value is given. */
|
|
@@ -227,6 +227,9 @@ export function deploymentStatusData(document, deployment) {
|
|
|
227
227
|
// Feature instance-background (#1579): the row is placed in the Background section. Exactly true only; any
|
|
228
228
|
// other value is dropped, never checked: the row stays in the main tree.
|
|
229
229
|
if (own(instance, 'background') && instance.background === true) row.background = true;
|
|
230
|
+
// Feature instance-pin: the row is listed first in its machine's list (instance-tree.mjs rowPinned). Exactly
|
|
231
|
+
// true only; any other value is dropped, never checked: the row keeps the roster's order.
|
|
232
|
+
if (own(instance, 'pinned') && instance.pinned === true) row.pinned = true;
|
|
230
233
|
// #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
|
|
231
234
|
// any other value is dropped, never checked: the row stays an ordinary one.
|
|
232
235
|
if (own(instance, 'spawnInProgress') && instance.spawnInProgress === true) row.spawnInProgress = true;
|
|
@@ -139,6 +139,8 @@ export function panelInstance(i) {
|
|
|
139
139
|
...(instanceColor(i) !== null ? { color: instanceColor(i) } : {}),
|
|
140
140
|
// Feature instance-background (#1579): exactly true, else absent (instance-tree.mjs backgroundPlacement).
|
|
141
141
|
...(i.background === true ? { background: true } : {}),
|
|
142
|
+
// Feature instance-pin: exactly true, else absent (instance-tree.mjs rowPinned).
|
|
143
|
+
...(i.pinned === true ? { pinned: true } : {}),
|
|
142
144
|
team: i.team || null,
|
|
143
145
|
};
|
|
144
146
|
}
|