@awebai/oats 0.56.0 → 0.57.1
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 +18 -10
- package/docs/configuration.md +17 -27
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +25 -4
- package/docs/execution-targets.md +6 -1
- package/docs/implementation.md +106 -5
- package/docs/integrations.md +8 -4
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +333 -95
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/session-viewer.mjs +29 -4
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/instance-lifecycle.mjs +10 -3
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +11 -6
- package/packages/client/spawn-apply.mjs +212 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +152 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/tui/README.md +43 -13
- package/packages/tui/lib/actions.mjs +18 -2
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +241 -55
- package/packages/tui/lib/model.mjs +230 -29
- package/packages/tui/lib/panel.mjs +955 -0
- package/packages/tui/lib/read.mjs +134 -24
- package/packages/tui/lib/store.mjs +184 -31
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +153 -37
- package/packages/tui/lib/views/help.mjs +22 -14
- package/skills/oats-getting-started/SKILL.md +4 -3
- package/packages/tui/lib/open.mjs +0 -45
package/bin/oats.mjs
CHANGED
|
@@ -2936,7 +2936,7 @@ async function spawnCmd() {
|
|
|
2936
2936
|
...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
|
|
2937
2937
|
// Directory execution uses deployment configuration, not an ambient Git
|
|
2938
2938
|
// checkout (especially when invoked via --dir from a source instance).
|
|
2939
|
-
// An attached instance's repository is
|
|
2939
|
+
// An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
|
|
2940
2940
|
repo: preparedRepo !== undefined ? preparedRepo : ["directory", "attached"].includes(requestedWork || agent.work)
|
|
2941
2941
|
? repo : repo || defaultRepo(workspaceOf(root)) || defaultRepo(process.cwd()),
|
|
2942
2942
|
work: requestedWork, workDir, harness: harnessFlag(), backend, yolo, model: flag("model"), branch,
|
|
@@ -3090,13 +3090,15 @@ function retireCmd() {
|
|
|
3090
3090
|
revalidate = () => {
|
|
3091
3091
|
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
|
|
3092
3092
|
if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
|
|
3093
|
-
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
|
|
3093
|
+
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
|
|
3094
3094
|
};
|
|
3095
3095
|
} else {
|
|
3096
3096
|
// A plain or --self retire reads its recorded children the same way: under the claim, as they
|
|
3097
3097
|
// are when the retire starts (an earlier retire that kept the home has repaired lineage by
|
|
3098
3098
|
// then), and none when there are none.
|
|
3099
|
-
|
|
3099
|
+
// The instances the plan lists under `ambiguous` go with them: the retire does not act on
|
|
3100
|
+
// them, and says what it left the ones attached to a tree it moved or removed with.
|
|
3101
|
+
revalidate = () => { const recorded = descendantsOf(root, name); return { ...(recorded.length ? { children: recorded } : {}), ...(recorded.ambiguous?.length ? { ambiguous: recorded.ambiguous } : {}) }; };
|
|
3100
3102
|
}
|
|
3101
3103
|
let r;
|
|
3102
3104
|
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
|
|
@@ -3155,9 +3157,11 @@ function retireCmd() {
|
|
|
3155
3157
|
process.exit(1);
|
|
3156
3158
|
}
|
|
3157
3159
|
console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
|
|
3158
|
-
// An attached child the retire repointed to
|
|
3159
|
-
|
|
3160
|
-
|
|
3160
|
+
// An attached child the retire repointed to a retained worktree, work/ (#718) or an extra tree
|
|
3161
|
+
// (#964), as its link now reads.
|
|
3162
|
+
const retainedAt = [...(r.retention?.worktree === "retained" ? [r.retention.movedTo] : []), ...(r.extraWorktrees || []).filter((t) => t.outcome === "retained").map((t) => t.movedTo)];
|
|
3163
|
+
const followsWorktree = (k) => { try { const to = readlinkSync(join(k.home, "work")); return retainedAt.includes(to) ? to : null; } catch { return null; } };
|
|
3164
|
+
for (const k of r.childrenStopped || []) { const to = followsWorktree(k); console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}${to ? `; its work now links to the retained worktree ${to}` : ""}`); }
|
|
3161
3165
|
// Preserving work and not saying so leaves the operator believing it is gone,
|
|
3162
3166
|
// which is most of the harm of deleting it. Name the classes and the path.
|
|
3163
3167
|
for (const line of workRecoveryLines(r)) console.log(line);
|
|
@@ -4665,9 +4669,11 @@ Usage:
|
|
|
4665
4669
|
oats tui [--dir <path>] [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md):
|
|
4666
4670
|
the instances of the workspace of the deployment at or
|
|
4667
4671
|
above <path> (default: where you are), on this machine
|
|
4668
|
-
and on the machines registered here
|
|
4669
|
-
|
|
4670
|
-
|
|
4672
|
+
and on the machines registered here. Enter opens an agent's
|
|
4673
|
+
terminal; it stops, starts, restarts and retires them after a
|
|
4674
|
+
confirmation. ? help, w workspaces, q quit. Needs a terminal on
|
|
4675
|
+
stdin and stdout and has no --json form; --ascii = ASCII rules
|
|
4676
|
+
and marks
|
|
4671
4677
|
oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
|
|
4672
4678
|
--workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
|
|
4673
4679
|
[--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
|
|
@@ -4922,7 +4928,9 @@ Usage:
|
|
|
4922
4928
|
again with the same arguments: a no-op; --preview:
|
|
4923
4929
|
the clone, path, branch, base and hooks, nothing done
|
|
4924
4930
|
oats worktree remove --purpose <p> [--json] git worktree remove of a tree made by add (a dirty
|
|
4925
|
-
tree is refused: E_WORKTREE_DIRTY
|
|
4931
|
+
tree is refused: E_WORKTREE_DIRTY; so is the work of an
|
|
4932
|
+
attached instance whose session is running or cannot
|
|
4933
|
+
be read: E_CHILDREN_RUNNING); the branch is kept
|
|
4926
4934
|
oats readiness (--soul <n> | --home <abs>) [--policy] [--json]
|
|
4927
4935
|
readinessApi 2 for a soul or an instance home:
|
|
4928
4936
|
installed | configured | member | providers, each
|
package/docs/configuration.md
CHANGED
|
@@ -87,9 +87,14 @@ Loading development channels” prompt through the **approved route**: the
|
|
|
87
87
|
development prompt. Claude admits the plugin when a root-owned machine
|
|
88
88
|
managed-settings file lists it. The route does not depend on the Claude
|
|
89
89
|
version and needs no OATS mechanism beyond these settings. The operator's
|
|
90
|
-
ordered procedure is the `oats.setup` host
|
|
91
|
-
|
|
92
|
-
|
|
90
|
+
ordered procedure is the `oats.setup` skill `/oats-host-delivery`, whose
|
|
91
|
+
Choice 1 is this route and whose Choice 2 is the host wake broker;
|
|
92
|
+
`/oats-onboarding` card 4 makes both choices and card 8 checks them. The provider's side is
|
|
93
|
+
`/oats-aweb` §4.
|
|
94
|
+
|
|
95
|
+
An unset `claudeChannelMode` is development mode, so a host that never makes
|
|
96
|
+
the choice runs every Claude home with the development prompt. Set the key
|
|
97
|
+
explicitly, to `approved` or, as a recorded fallback, `development`.
|
|
93
98
|
|
|
94
99
|
**The managed-settings file** is a host change made by a human admin with
|
|
95
100
|
sudo. OATS never writes it.
|
|
@@ -127,7 +132,11 @@ settings:
|
|
|
127
132
|
```
|
|
128
133
|
|
|
129
134
|
With channel delivery, pi uses its `@awebai/pi` extension and Codex always
|
|
130
|
-
uses the host broker.
|
|
135
|
+
uses the host broker. The broker (`aw wake run`, one per host user) also wakes
|
|
136
|
+
every joined team and every `delivery: session` home. Without it, joined teams
|
|
137
|
+
are poll-only. It runs as a per-user launchd or systemd service that the
|
|
138
|
+
operator installs, with `AW_WAKE_OATS_BIN` and a `PATH` that reaches `oats`,
|
|
139
|
+
`node` and `tmux`. That procedure is Choice 2 of `/oats-host-delivery`.
|
|
131
140
|
|
|
132
141
|
**The plugin.** `aweb-channel` must be installed from the marketplace named
|
|
133
142
|
`awebai-marketplace` (GitHub `awebai/claude-plugins`) and enabled, in the
|
|
@@ -142,29 +151,10 @@ without the operator's word.
|
|
|
142
151
|
confirm: [the development-channel confirmation](#the-development-channel-confirmation)
|
|
143
152
|
applies only to a launch with the development-channel flag.
|
|
144
153
|
|
|
145
|
-
**Verify
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
2. The started session shows no development prompt, and its banner shows
|
|
150
|
-
“Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace
|
|
151
|
-
inject directly in this session”, followed by “restart without --channels
|
|
152
|
-
to stop”. At normal terminal widths the banner wraps over two rows: look
|
|
153
|
-
for each part, not for one string.
|
|
154
|
-
3. The banner says none of `not on the approved channels allowlist`,
|
|
155
|
-
`not on your org's approved channels list`, `blocked by org policy` or
|
|
156
|
-
`plugin not installed`.
|
|
157
|
-
4. Receive is proven only by the `/oats-aweb` nonce exchange.
|
|
158
|
-
|
|
159
|
-
**Failure banners**, their cause and remedy:
|
|
160
|
-
|
|
161
|
-
| What the session shows | Cause | Remedy |
|
|
162
|
-
|---|---|---|
|
|
163
|
-
| `not on the approved channels allowlist` | the effective managed policy has no `allowedChannelPlugins` (no file, the file not read, or the key missing), so Anthropic's default list applied | write or fix the file |
|
|
164
|
-
| `not on your org's approved channels list` | the effective policy has an `allowedChannelPlugins` without this plugin and marketplace pair: the names in the file are wrong, or a higher source (server-managed settings or MDM) supplies its own list | fix the entry, or have the organization admin add it |
|
|
165
|
-
| `blocked by org policy` (then “Inbound messages will be silently dropped”) | the effective policy lacks `channelsEnabled: true`, which Team/Enterprise subscribers need, and API-key use whenever any managed policy exists | add the key, or have the organization admin set it |
|
|
166
|
-
| `plugin:aweb-channel@awebai-marketplace · plugin not installed` | the plugin is not installed in the launch's Claude config directory | install and enable it there |
|
|
167
|
-
| the development prompt still appears | the home started in development mode, not approved: the host setting is missing, or the home was spawned before the change | set `claudeChannelMode: approved`, then respawn the home |
|
|
154
|
+
**Verify** with the success list and the failure-banner table of
|
|
155
|
+
`/oats-host-delivery`, Choice 1: the preview's mode, the admitted banner
|
|
156
|
+
with no failure banner, then the `/oats-aweb` nonce exchange, which alone
|
|
157
|
+
proves receive.
|
|
168
158
|
|
|
169
159
|
**Limits.** Channels are an Anthropic research preview. Anthropic's
|
|
170
160
|
account-level feature flag gates channels on every route. The allowlist
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -2542,7 +2542,11 @@ what could not be printed is dropped. Its result:
|
|
|
2542
2542
|
|
|
2543
2543
|
`remove` answers `{purpose, path, removed: true, rolledBack, branch,
|
|
2544
2544
|
branchKept, branchKeptReason?, warnings?}`. After removing a `ready` tree,
|
|
2545
|
-
`rolledBack` is `false` and `branchKept` is `true`. When
|
|
2545
|
+
`rolledBack` is `false` and `branchKept` is `true`. When an instance whose
|
|
2546
|
+
session is stopped was [attached](souls-and-instances.md#extra-trees) to the
|
|
2547
|
+
removed tree, `warnings` carries one string for it: `<instance>: its work
|
|
2548
|
+
was <tree>, which was removed; its work link <home>/work now points at a
|
|
2549
|
+
path that is gone`. With no attached instance the answer is what it was. When it completed an
|
|
2546
2550
|
interrupted add's rollback, `rolledBack` is `true` and `branchKept` says
|
|
2547
2551
|
whether the branch still exists. The rollback deletes the branch only when
|
|
2548
2552
|
that add created it, no worktree has it checked out, and it still points at
|
|
@@ -2654,6 +2658,7 @@ A failed `add` reports the same facts about its rollback in `details`:
|
|
|
2654
2658
|
| `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
|
|
2655
2659
|
| `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
|
|
2656
2660
|
| `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message); the record is kept. Commit and push, or discard, then retry |
|
|
2661
|
+
| `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
|
|
2657
2662
|
| `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
|
|
2658
2663
|
| `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
|
|
2659
2664
|
|
|
@@ -4337,7 +4342,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4337
4342
|
- of other homes: the children as the plan names them (`instance`,
|
|
4338
4343
|
`agent`, `home`; a child's agent is the name its soul's file gives),
|
|
4339
4344
|
the edges that could not be followed (`facts.ambiguous`, whole) and the
|
|
4340
|
-
|
|
4345
|
+
instances attached to this home's `work/` and to each of its extra
|
|
4346
|
+
trees, the recorded children and those of a name that is not unique
|
|
4347
|
+
alike: the plan's notes name them (#964).
|
|
4341
4348
|
|
|
4342
4349
|
A key that is derived is bound through what it is derived from:
|
|
4343
4350
|
`facts.ownWorktree` and `defaults.retainWorktree` (the reading), and
|
|
@@ -4538,6 +4545,32 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4538
4545
|
--discard-worktree the worktree is removed and their work link will
|
|
4539
4546
|
dangle`. It holds for either choice; no other key changes. A relink that
|
|
4540
4547
|
fails is a string in the receipt's `warnings`.
|
|
4548
|
+
- The note of an extra tree that recorded children are attached to (their
|
|
4549
|
+
`work` is a link to that tree) names them and says what the retire leaves
|
|
4550
|
+
them with. For a tree that would be removed it ends `; attached child
|
|
4551
|
+
instance(s) <names> use it as their work, and their work link would then
|
|
4552
|
+
point at a path that is gone`; for one that would be re-homed, `; attached
|
|
4553
|
+
child instance(s) <names> use it as their work, and the retire repoints
|
|
4554
|
+
their work link to it`. A tree the retire refuses is neither moved nor
|
|
4555
|
+
removed, and its note says nothing of them. Names too long for the note
|
|
4556
|
+
give way to `<n> of the recorded children`. They are strings in `notes`: no
|
|
4557
|
+
key changes. Who is attached to each tree is part of `planRevision`
|
|
4558
|
+
([what the revision binds](#retire-revision-work)).
|
|
4559
|
+
- The retire does not act on an instance listed under `ambiguous`, and one
|
|
4560
|
+
that is attached to a tree of this home is named with what that leaves it
|
|
4561
|
+
with. An extra tree's note gains a clause of its own, after the one for
|
|
4562
|
+
the recorded children: `; attached instance(s) <names>, listed under
|
|
4563
|
+
ambiguous, use it as their work: the retire does not stop them, and their
|
|
4564
|
+
work link would then point at a path that is gone` for a tree that would
|
|
4565
|
+
be removed, and `…: the retire neither stops them nor repoints their work
|
|
4566
|
+
link, which would then point at a path that is gone (the tree would be at
|
|
4567
|
+
<movedTo>)` for one that would be re-homed. For `work/` it is a note of
|
|
4568
|
+
its own, in a worktree-mode plan: `attached instance(s) <names>, listed
|
|
4569
|
+
under ambiguous, use this home's work/ as their work: the retire neither
|
|
4570
|
+
stops them nor repoints their work link, which will then point at a path
|
|
4571
|
+
that is gone, whether the worktree is retained (the receipt names where)
|
|
4572
|
+
or removed with --discard-worktree`. The note for the recorded children
|
|
4573
|
+
above is unchanged.
|
|
4541
4574
|
- `facts.recordedBranch` is `null` where the home records the word `"HEAD"`
|
|
4542
4575
|
(a detached checkout or attached spawn before 0.49.0, #641): it is not a
|
|
4543
4576
|
branch name, so `facts.work.drift` is `false` for it as well.
|
|
@@ -4648,6 +4681,29 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
4648
4681
|
removed unplanned (OATS 0.52.0; it was `E_PLAN_STALE`, a code that says
|
|
4649
4682
|
nothing happened, answered after the hooks: #895).
|
|
4650
4683
|
The key is additive.
|
|
4684
|
+
- `warnings` also says what the retire left the attached children of a tree
|
|
4685
|
+
it moved or removed with, one string per child, for `work/` and for each
|
|
4686
|
+
extra tree. A child that could not be repointed to a retained tree:
|
|
4687
|
+
`<child>: its work link could not be repointed to the retained worktree
|
|
4688
|
+
<movedTo> (<why>) and still points at <link>; repoint it by hand: ln -sfn
|
|
4689
|
+
…`, or `<child>: its attachment changed during the retire, so its work was
|
|
4690
|
+
left as it is now and not repointed to the retained worktree <movedTo>;
|
|
4691
|
+
inspect <home>/work`. A child of a tree the retire removed (a clean extra
|
|
4692
|
+
tree, or `work/` with `--discard-worktree`): `<child>: its work was
|
|
4693
|
+
<tree>, which this retire removed (<why>); its work link <home>/work now
|
|
4694
|
+
points at a path that is gone`. A child that was repointed has no string:
|
|
4695
|
+
the text summary's `child <name>` line says where its work now links. No
|
|
4696
|
+
key is new.
|
|
4697
|
+
|
|
4698
|
+
An attached instance the plan lists under `ambiguous` is not stopped and
|
|
4699
|
+
not repointed, and has a string for each tree that was moved or removed:
|
|
4700
|
+
the sentence above for a removed tree, followed by ` (it records this
|
|
4701
|
+
instance as its parent under a name that is not unique, so the retire did
|
|
4702
|
+
not stop it)`, or, for a re-homed tree, `<instance>: its work was <tree>,
|
|
4703
|
+
which this retire re-homed to <movedTo>; its work link <home>/work was not
|
|
4704
|
+
repointed and now points at a path that is gone (it records … did not stop
|
|
4705
|
+
it); to repoint it by hand: ln -sfn …`. A `--self` retirement's receipt
|
|
4706
|
+
does not carry these strings.
|
|
4651
4707
|
- `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
|
|
4652
4708
|
notCopied?, afterHooks?}`, present when a recovery was written. One retire
|
|
4653
4709
|
writes at most one recovery directory, and `path` is that directory.
|
|
@@ -4736,7 +4792,7 @@ nothing is established. A plain or
|
|
|
4736
4792
|
always does (`[]` when there are none). One child still running after the
|
|
4737
4793
|
grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
|
|
4738
4794
|
`E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`, …), refuses everything: nothing is retired, exit 1,
|
|
4739
|
-
|
|
4795
|
+
<a id="retire-children-running"></a>`E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
|
|
4740
4796
|
`code`, always a [kernel code](#kernel-codes); the message says `still running after a bounded stop`
|
|
4741
4797
|
only of a child whose row lists processes in `stillRunning`, and `<child> could not be stopped
|
|
4742
4798
|
(<code>)` of any other, OATS 0.52.0). **`--force` does not bypass it**: `--force` covers incomplete
|
package/docs/desktop.md
CHANGED
|
@@ -166,6 +166,16 @@ workspace on a server: `name — server`).
|
|
|
166
166
|
- Tabs belong to their window: a workspace's terminals and tabs stay in the
|
|
167
167
|
window they were opened in, and switching that window back to the
|
|
168
168
|
workspace brings them back.
|
|
169
|
+
- A tab's terminal ends ("session ended") when its instance's tmux window
|
|
170
|
+
goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
|
|
171
|
+
another instance's terminal. Stopping an instance leaves its tab open.
|
|
172
|
+
- When a roster read shows an instance retired, from the Desktop, the CLI,
|
|
173
|
+
another agent or another machine, every tab of that instance closes, in
|
|
174
|
+
every split. In each split the next tab (or else the previous one) becomes
|
|
175
|
+
active, and the focus moves to it only if it was in a closed tab. A
|
|
176
|
+
workspace that isn't shown closes them the next time its roster is read.
|
|
177
|
+
An instance respawned under the same name is a new instance: opening it
|
|
178
|
+
opens a new tab.
|
|
169
179
|
|
|
170
180
|
## Capabilities and spawning
|
|
171
181
|
|
|
@@ -353,10 +363,17 @@ join** says who else may join it. Both are read from the workspace's committed
|
|
|
353
363
|
`souls:`; a team nobody may join yet says so. The address (the team on the
|
|
354
364
|
messaging provider) and the members running in it follow.
|
|
355
365
|
|
|
356
|
-
The **Setup** tab's List view
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
366
|
+
The **Setup** tab's List view is one column. Under the workspace's name, one
|
|
367
|
+
line counts its members (and those that need attention), its packages and the
|
|
368
|
+
state of the lock. The next line says where the workspace is declared. An
|
|
369
|
+
**Overview** says that the workspace's **host**, the repository that holds
|
|
370
|
+
`oats-workspace.yaml`, defines the workspace: its member repositories and its
|
|
371
|
+
packages. **For developers** (folded) explains how a repository becomes a
|
|
372
|
+
member and what each member state means. Then **Shared through Git** lists
|
|
373
|
+
what the workspace declares (Members, with the host first and tagged
|
|
374
|
+
**Host**, Packages and Defaults). **This computer** lists what is not shared:
|
|
375
|
+
this deployment's settings, lock, CLI and instances, the member clones, and
|
|
376
|
+
the machines that run the workspace.
|
|
360
377
|
|
|
361
378
|
## A workspace's machines
|
|
362
379
|
|
|
@@ -435,6 +452,10 @@ any other exit code. Closing the tab ends the reconnecting. Reconnecting
|
|
|
435
452
|
never stops or restarts the agent on the server: only the local ssh viewer
|
|
436
453
|
ends.
|
|
437
454
|
|
|
455
|
+
A remote instance's tabs close only when its server answers without it
|
|
456
|
+
(retired there, or gone from it), never because the server can't be reached
|
|
457
|
+
or its roster read is out of date.
|
|
458
|
+
|
|
438
459
|
## Copy from a terminal
|
|
439
460
|
|
|
440
461
|
Drag over an agent's output to select it, as in any terminal. The selection
|
|
@@ -1076,7 +1076,12 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1076
1076
|
acceptance evidence remain separate contracts.
|
|
1077
1077
|
- **attach** is interactive and takes no `--json`. It opens a temporary tmux
|
|
1078
1078
|
session linked to the agent's window alone.
|
|
1079
|
-
Closing the viewer leaves the agent running.
|
|
1079
|
+
Closing the viewer leaves the agent running. When the agent's window ends
|
|
1080
|
+
(for example, the instance is stopped or retired), the viewer ends too: it
|
|
1081
|
+
sets tmux's `detach-on-destroy on` for its own session, so a server
|
|
1082
|
+
configured with `detach-on-destroy off` never moves the viewer's client to
|
|
1083
|
+
another session, another agent's terminal. Your own sessions keep your
|
|
1084
|
+
setting.
|
|
1080
1085
|
|
|
1081
1086
|
On tmux 3.2 and later the viewer's tmux client asks for synchronized
|
|
1082
1087
|
output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
|
package/docs/implementation.md
CHANGED
|
@@ -79,7 +79,7 @@ and the rules its tests pin.
|
|
|
79
79
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
80
80
|
| `docs/` | the reference pages, schemas, design records and release notes |
|
|
81
81
|
| `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
|
|
82
|
-
| `scripts/` | the test runner (`run-tests.mjs`)
|
|
82
|
+
| `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane and the assembly of release-notes entries |
|
|
83
83
|
| `test/` | the kernel and CLI suites, with their fixtures |
|
|
84
84
|
|
|
85
85
|
## Kernel modules
|
|
@@ -443,7 +443,7 @@ scaling by call count.
|
|
|
443
443
|
|
|
444
444
|
| command | what it checks |
|
|
445
445
|
|---|---|
|
|
446
|
-
| `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output |
|
|
446
|
+
| `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output, or a test file leaves something in its temporary directory |
|
|
447
447
|
| `npm run test:session` | the suites that have followed a variable of the session that runs them, with every such variable set to a value that cannot work (`scripts/test-session-inheritance.mjs`) |
|
|
448
448
|
| `npm run check` | syntax of every shipped file |
|
|
449
449
|
| `npm run check:pi` | the pi adapter's TypeScript |
|
|
@@ -472,6 +472,65 @@ its own; a line a child wrote into a pipe the test reads is the test's, and
|
|
|
472
472
|
does not count. `test/unasserted-warnings.test.mjs` pins the rule with nested
|
|
473
473
|
runs.
|
|
474
474
|
|
|
475
|
+
**A test file leaves nothing behind.** Where a test makes a directory, it
|
|
476
|
+
registers the removal there (`t.after`, or a list the file empties when it has
|
|
477
|
+
ended), so a test that fails or times out removes it too; and a fixture is
|
|
478
|
+
ended, not only removed (`v2Deployment({ t })`, below). A file whose setup is
|
|
479
|
+
shared by its tests does that setup in a `test.before` hook, not at its top
|
|
480
|
+
level: a file that throws while it loads runs no hook, `test.after` included,
|
|
481
|
+
so a step that failed would leave what the steps before it made
|
|
482
|
+
(test/tui-acts.test.mjs). On a development host
|
|
483
|
+
the leftovers of runs that passed once used up the inodes of the temporary
|
|
484
|
+
file system, and every test that makes a directory then failed with "no
|
|
485
|
+
space", whatever the change under test (awebai/oats#1025). The root run holds
|
|
486
|
+
the rule:
|
|
487
|
+
|
|
488
|
+
- `scripts/run-tests.mjs` makes one directory for the run, and each test
|
|
489
|
+
file's process is preloaded with `scripts/test-file-tmpdir.mjs`, which gives
|
|
490
|
+
the file a directory of its own inside it: as `TMPDIR`, and as
|
|
491
|
+
`TMUX_TMPDIR`, which is tmux's default place. A tmux client that runs with
|
|
492
|
+
no `TMUX_TMPDIR` of a fixture makes its socket directory there, where the
|
|
493
|
+
run sees it, instead of reaching the host's default server. `TMUX` is not
|
|
494
|
+
changed: a client that names no server (no `-L` or `-S`) and inherits
|
|
495
|
+
`TMUX`, as in a run from a session inside tmux, still uses that session's
|
|
496
|
+
server and makes nothing the run sees. The run names its directory to the
|
|
497
|
+
preload in `OATS_TEST_RUN_DIR`, and the preload takes that variable out of
|
|
498
|
+
the file's environment before any code of the file runs. No test sees it,
|
|
499
|
+
nor any process a test starts.
|
|
500
|
+
- When the run has ended it reads each file's directory. If one is not empty
|
|
501
|
+
the run fails, even if every test passed, and names each file and what it
|
|
502
|
+
left.
|
|
503
|
+
- One name is not counted, by its exact name: `node-compile-cache`. Node makes
|
|
504
|
+
it under the temporary directory when a tool a test starts asks for a
|
|
505
|
+
compile cache (npm does), so under the root run it is made in the file's
|
|
506
|
+
own directory and goes with the run's. It is Node's, not something the file
|
|
507
|
+
left. A developer's shared cache, the one in the platform's temporary
|
|
508
|
+
directory, is neither used nor removed by a root run; a file run alone uses
|
|
509
|
+
it as before, and no test deletes it. The run's processes do not inherit
|
|
510
|
+
`NODE_COMPILE_CACHE` either: with a developer's set, no process of the run
|
|
511
|
+
writes into that cache.
|
|
512
|
+
- The run's directory is removed when the run has ended, whatever was left in
|
|
513
|
+
it. A run that is killed leaves that one directory: `ot-*` under the
|
|
514
|
+
temporary directory, or under `/tmp` when that path is longer than 20
|
|
515
|
+
characters.
|
|
516
|
+
- A file's directory, `<parent>/ot-XXXXXX/<n>`, takes from a socket's path
|
|
517
|
+
what `/tmp` alone did not. ssh binds a control socket at
|
|
518
|
+
`<OATS_HOME_DIR>/ssh/<40 hex>` plus a 17-byte suffix, in 104 bytes: 86 for
|
|
519
|
+
the path. A fixture whose `OATS_HOME_DIR` holds it keeps it short: a
|
|
520
|
+
5-character prefix and `<base>/h` (`o-up-`) come to 85 bytes when the
|
|
521
|
+
run's parent resolves to at most 12 characters, as `/tmp` does on Linux
|
|
522
|
+
and on macOS (`/private/tmp`), with up to 999 files. Longer, the kernel
|
|
523
|
+
warns that the path is too long and runs ssh without connection reuse,
|
|
524
|
+
which fails the run as any unasserted warning does: run the suite with a
|
|
525
|
+
`TMPDIR` of `/tmp` then.
|
|
526
|
+
- The run sees what is made under the file's temporary directory: by the
|
|
527
|
+
file's process, by a process it starts with that environment, and by the
|
|
528
|
+
fixture helpers (`fixtureBase` and `privateTmuxTmpdir`, below), in a
|
|
529
|
+
process the test started with `inheritedEnv()` too. It does not see what a
|
|
530
|
+
process makes when a test built its environment without `TMPDIR`.
|
|
531
|
+
|
|
532
|
+
`test/left-behind.test.mjs` pins the rule with nested runs.
|
|
533
|
+
|
|
475
534
|
Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
|
|
476
535
|
load with only Desktop dependencies installed. The release builds Desktop that
|
|
477
536
|
way: its `desktop-build` job installs and tests inside `packages/desktop` and
|
|
@@ -535,6 +594,31 @@ which fails with `ENOTEMPTY` (awebai/oats#451). So:
|
|
|
535
594
|
|
|
536
595
|
Never paper over such a race with a retry around the cleanup.
|
|
537
596
|
|
|
597
|
+
A process that a test kills can leave such a writer too. Killing a process
|
|
598
|
+
that starts processes of its own ends that one alone: a child it had just
|
|
599
|
+
started goes on by itself and writes where it was told to after its parent has
|
|
600
|
+
gone, and it has not run a line yet, so it has announced itself nowhere. The
|
|
601
|
+
Desktop server's tests are the case: the server runs the CLI, and a fake CLI
|
|
602
|
+
writes its log in the test's directory. Such a test starts the process with
|
|
603
|
+
`startGroup` and closes it with `closeGroup`
|
|
604
|
+
(`test/helpers/process-group.mjs`):
|
|
605
|
+
|
|
606
|
+
- `startGroup` starts it as `spawn` does, as the leader of a process group of
|
|
607
|
+
its own, which holds whatever it starts.
|
|
608
|
+
- `closeGroup` kills that one process and waits until its group, that process
|
|
609
|
+
among it, is empty. The bound, 30 s, covers the whole close from its start:
|
|
610
|
+
a group that outlives it fails the test and names every process that is
|
|
611
|
+
left, the killed one too if it still runs. Only then does the test remove
|
|
612
|
+
what they worked in.
|
|
613
|
+
- A group of its own is not in the terminal's foreground group, so an
|
|
614
|
+
interrupt of the test's process does not reach it. The helper passes it on:
|
|
615
|
+
on `SIGINT`, `SIGTERM` or `SIGHUP` it kills every group that process
|
|
616
|
+
started, whole, and then the signal ends the process as it would have. A
|
|
617
|
+
test process killed with `SIGKILL` passes nothing on: what it started stays,
|
|
618
|
+
as any child of a process killed that way does.
|
|
619
|
+
|
|
620
|
+
`test/process-group.test.mjs` pins the three.
|
|
621
|
+
|
|
538
622
|
A test never reaches the operator's tmux. The kernel creates sessions on the
|
|
539
623
|
server named `oats` (`tmux -L oats`), which tmux resolves under `TMUX_TMPDIR`,
|
|
540
624
|
and acts on every existing session through its recorded socket
|
|
@@ -581,7 +665,13 @@ and acts on every existing session through its recorded socket
|
|
|
581
665
|
(`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
|
|
582
666
|
bytes a terminal sends (`send-keys -l`). A pane program that must show the
|
|
583
667
|
keys it reads puts its terminal in raw mode first: in cooked mode a control
|
|
584
|
-
byte is a signal or an edit, not input.
|
|
668
|
+
byte is a signal or an edit, not input. A signal to the command's process
|
|
669
|
+
group (what a pty hang-up or a C-c delivers) needs the command to be a group
|
|
670
|
+
of its own: the pane's script starts `trap : INT; set -m`, so the shell
|
|
671
|
+
survives to record the status (bash would otherwise end itself after a job
|
|
672
|
+
that INT ended). A `tmux` first on the command's `PATH` times the signal
|
|
673
|
+
against one of the command's tmux calls; it finds the group with
|
|
674
|
+
`ps -o pgid= -p $PPID`.
|
|
585
675
|
- A test of a full-screen program (`oats tui`) uses a pane of a private
|
|
586
676
|
server as its terminal (`test/tui-terminal.test.mjs`): the real CLI is typed
|
|
587
677
|
at an interactive shell in the pane, keys go in with `send-keys`, the screen
|
|
@@ -624,7 +714,12 @@ inherits it (awebai/oats#816):
|
|
|
624
714
|
- **A short base.** `fixtureBase(prefix)` makes the fixture directory under
|
|
625
715
|
the platform's temporary directory, or under `/tmp` when that is longer than
|
|
626
716
|
20 characters (macOS's `/private/var/folders/…/T/` is about 49), as its
|
|
627
|
-
realpath, taken once.
|
|
717
|
+
realpath, taken once. Under the root run the temporary directory is the
|
|
718
|
+
test file's own (above), and is used whatever its length, so that nothing a
|
|
719
|
+
fixture makes is outside what the run reads; the run keeps it short. The
|
|
720
|
+
helper knows it by what the runner makes (`ot-XXXXXX/<n>`, with the file
|
|
721
|
+
`<n>.file` beside it) and by no variable, so a process a test starts with
|
|
722
|
+
`inheritedEnv()` uses it too.
|
|
628
723
|
- **Names and paths sized from the base.** `nameOfLength(base, n)` (a file
|
|
629
724
|
name or branch segment) and `pathOfLength(base, n)` (an absolute path under
|
|
630
725
|
the base, `n` characters in all) are capped below NAME_MAX and PATH_MAX of
|
|
@@ -743,4 +838,10 @@ inherits it (awebai/oats#816):
|
|
|
743
838
|
still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
|
|
744
839
|
and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
|
|
745
840
|
`t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
|
|
746
|
-
built removes its base itself.
|
|
841
|
+
built removes its base itself. Removing the base is not ending the fixture:
|
|
842
|
+
only `fx.cleanup` stops the fixture's tmux server, checks for leftover
|
|
843
|
+
processes and removes the fixture's private `TMUX_TMPDIR`
|
|
844
|
+
(`privateTmuxTmpdir()`), which is made beside the base and never inside it.
|
|
845
|
+
So a fixture that was made and never ended leaves that directory, and the
|
|
846
|
+
root run fails on it (awebai/oats#1025). A file that collects its fixtures
|
|
847
|
+
ends each of them in the hook that used to remove their bases.
|
package/docs/integrations.md
CHANGED
|
@@ -40,7 +40,7 @@ arrives from.
|
|
|
40
40
|
```yaml
|
|
41
41
|
# oats-workspace.yaml: one default per slot, for every soul
|
|
42
42
|
packages:
|
|
43
|
-
oats.okf: v5.
|
|
43
|
+
oats.okf: v5.2.0
|
|
44
44
|
oats.aweb: v1.27.3
|
|
45
45
|
oats.linear: v1.0.1
|
|
46
46
|
oats.jira: v1.0.1
|
|
@@ -84,8 +84,10 @@ operations in full.
|
|
|
84
84
|
| `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
|
|
85
85
|
|
|
86
86
|
- **`oats.okf`** consults the soul's external OKF bases, keeps instance
|
|
87
|
-
knowledge, and
|
|
88
|
-
|
|
87
|
+
knowledge, and teaches the harvest duty in its IMPORTANT inject block and
|
|
88
|
+
compulsory `okf-propose` skill, not the task briefing. Eligible instances
|
|
89
|
+
propose durable claims at finished tasks or PR hand-overs by directly
|
|
90
|
+
spawning `oats.okf/knowledge-harvester`. The
|
|
89
91
|
soul-only `knowledge: { harvest: off }` forbids harvest while retaining
|
|
90
92
|
consultation. No host switch or automatic transcript/retire capture remains;
|
|
91
93
|
`knowledge-maintainer` reviews the resulting Git PRs.
|
|
@@ -98,7 +100,9 @@ operations in full.
|
|
|
98
100
|
becomes quiet after the kernel records a completed confirmation. If Claude
|
|
99
101
|
ignored the flag, readiness reports `claude-channels-unavailable`.
|
|
100
102
|
`settings.oats.aweb.delivery: session` or
|
|
101
|
-
`settings.oats.aweb.claudeChannelMode: approved` stop the prompt.
|
|
103
|
+
`settings.oats.aweb.claudeChannelMode: approved` stop the prompt. Which one a
|
|
104
|
+
host uses, and its host wake broker, are the operator's choices in
|
|
105
|
+
oats.setup's `/oats-host-delivery`. `oats aweb roster` lists the team:
|
|
102
106
|
its membership certificates and workspaces, one entry per alias with its
|
|
103
107
|
sources, status and kind (global identities first), and says when either
|
|
104
108
|
source is incomplete. After `oats server connect`, `oats aweb connect
|