@awebai/oats 0.59.0 → 0.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +14 -18
  2. package/bin/oats.mjs +42 -10
  3. package/docs/configuration.md +9 -0
  4. package/docs/desktop-cli-api.md +40 -10
  5. package/docs/desktop.md +7 -0
  6. package/docs/execution-targets.md +7 -2
  7. package/docs/first-team.md +8 -0
  8. package/docs/implementation.md +1 -0
  9. package/docs/integrations.md +1 -1
  10. package/docs/official-catalog.md +2 -2
  11. package/docs/packages.md +7 -7
  12. package/docs/release-notes/v0.60.0.md +104 -0
  13. package/docs/release-notes/v0.61.0.md +155 -0
  14. package/docs/tui.md +133 -19
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +42 -15
  17. package/lib/session-input.mjs +45 -28
  18. package/package-catalog.json +2 -2
  19. package/package.json +1 -1
  20. package/packages/client/capability-catalog.mjs +93 -0
  21. package/packages/client/capability-facts.mjs +59 -0
  22. package/packages/client/capability-rows.mjs +121 -0
  23. package/packages/client/catalog-messages.mjs +12 -0
  24. package/packages/client/cli-locator.mjs +2 -2
  25. package/packages/client/instance-presentation.mjs +10 -0
  26. package/packages/client/instance-tree.mjs +48 -6
  27. package/packages/client/soul-catalog.mjs +8 -0
  28. package/packages/client/soul-facts.mjs +7 -0
  29. package/packages/client/spawn-messages.mjs +8 -0
  30. package/packages/client/subsequence-score.mjs +15 -0
  31. package/packages/tui/README.md +1 -1
  32. package/packages/tui/lib/actions.mjs +1 -1
  33. package/packages/tui/lib/client.mjs +9 -4
  34. package/packages/tui/lib/main.mjs +58 -9
  35. package/packages/tui/lib/model.mjs +150 -50
  36. package/packages/tui/lib/store.mjs +133 -16
  37. package/packages/tui/lib/views/capabilities.mjs +239 -0
  38. package/packages/tui/lib/views/frame.mjs +55 -20
  39. package/packages/tui/lib/views/help.mjs +9 -4
  40. package/packages/tui/lib/views/palette.mjs +13 -4
  41. package/packages/tui/lib/views/souls.mjs +6 -4
  42. package/packages/tui/lib/views/spawn.mjs +5 -3
  43. package/skills/oats-getting-started/SKILL.md +1 -1
package/README.md CHANGED
@@ -1,33 +1,29 @@
1
1
  # OATS: an open framework for specialised agent teams
2
2
 
3
- **Free, open source, provider-agnostic, and decentralised by design.**
3
+ **Free, open source, provider- and harness-agnostic, and decentralised by design.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@awebai/oats.svg)](https://www.npmjs.com/package/@awebai/oats)
6
6
  [![Release](https://img.shields.io/github/v/release/awebai/oats?display_name=tag)](https://github.com/awebai/oats/releases)
7
7
  [![Node 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
8
8
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
9
 
10
- OATS—**Open Agent Team Specification**—is a framework for building, running and coordinating teams of specialised AI agents. You can organise your team however you need, choosing models, harnesses and capabilities without being tied to a particular provider or stack.
10
+ OATS—**Open Agent Team Specification**—is a provider- and harness-agnostic framework for building distributed agent teams: on one laptop, across machines or across a large organisation, as flexibly as you need. It is completely free and open source.
11
11
 
12
- **Capabilities are the building blocks of an OATS setup.** When you define an agent, you choose its capabilities. Each provides the know-how and tools for knowledge systems, messaging, task coordination or any other workflows, tools or ways of working. We provide defaults to get started, but you can adapt existing capabilities or create fully custom ones to shape how your agents work and which tools they use.
12
+ - **Every agent keeps the full power of its harness.** Claude Code, Codex or pi: OATS connects them, so agents on different harnesses and providers communicate and work together.
13
+ - **The CLI and contracts set up the team; capabilities shape it.** Choose the agents, the tools you already use and how they coordinate. We ship opinionated defaults that we think work well, and you can change or replace any of them.
14
+ - **You keep control** of messaging, knowledge, coordination and anything else your team does, so your knowledge, workflows and team structure outlast any model or platform.
15
+ - **So you don't lose your head as the threads multiply,** there are two clients: **OATS Desktop**, a free, fully integrated ADE (an agentic IDE), and **`oats tui`** for the terminal (in preview).
16
+ - **Built on what you already use:** Git, GitHub or GitLab, and your agent harnesses. No OATS account, central server or OATS-hosted database; integrations you choose may run their own.
13
17
 
14
- The [official catalog](docs/official-catalog.md) is the reviewed list of official packages; a workspace trusts a package by declaring it, and listing does not declare it for you.
18
+ For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has its own for its area. Through capabilities you decide:
15
19
 
16
- For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has specific capabilities for its own area of expertise.
20
+ - which specialists make up the team;
21
+ - which models and harnesses their instances use;
22
+ - where their knowledge lives and how it grows;
23
+ - which skills, tools and workflows they receive;
24
+ - how they communicate and coordinate.
17
25
 
18
- Through your capabilities, you remain in control of:
19
-
20
- - Which specialists make up the team.
21
- - Which models and harnesses their instances use.
22
- - Where their knowledge lives and how it develops.
23
- - Which skills, tools and workflows they receive.
24
- - How they communicate and coordinate.
25
-
26
- These choices determine how your team operates and where the value of its work accumulates. Keeping them under your control means your knowledge, workflows and team structure can outlast any particular model or platform.
27
-
28
- OATS also provides **OATS Desktop: a free, fully integrated ADE—an agentic IDE**. It brings your team, its work and its agent sessions into one place, making day-to-day collaboration with your agents clearer and more pleasant.
29
-
30
- OATS builds on tools you already use—**Git, GitHub or GitLab, and your preferred agent harnesses**. People can share agent definitions, knowledge and workflows across projects without an OATS account, a central OATS server or an OATS-hosted database. Selected integrations may use their own servers or databases; those are your choices, not a mandatory OATS service.
26
+ The [official catalog](docs/official-catalog.md) is the reviewed list of official packages. A workspace trusts a package by declaring it; being listed doesn't declare it.
31
27
 
32
28
  ## Why OATS
33
29
 
package/bin/oats.mjs CHANGED
@@ -44,7 +44,7 @@ import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlo
44
44
  import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
45
45
  import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
46
46
  import { terminalText } from "../lib/refused-text.mjs";
47
- import { soulsOffered } from "../lib/instance-resolution.mjs";
47
+ import { qualifiedSoulName, soulCandidates, soulsOffered } from "../lib/instance-resolution.mjs";
48
48
  import { parseConfigData } from "../lib/config-data.mjs";
49
49
  import * as remoteModule from "../lib/remote.mjs";
50
50
  import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
@@ -3536,7 +3536,7 @@ async function tuiCmd() {
3536
3536
  * instance homes), then runs exactly the `oats sync` path — discover over the
3537
3537
  * remotes, confirm membership, resolve `packages:`, write `oats-lock.json`. Nothing is installed, no soul
3538
3538
  * is created, nothing is spawned, no `oats-config.yaml` is written: the member
3539
- * clones and the operator expert are the operator's next steps, printed here. */
3539
+ * clones and the workspace's setup expert are the operator's next steps, printed here. */
3540
3540
  async function onboardCmd() {
3541
3541
  const bail = (code, message, details) => (JSON_MODE ? jsonFail(code, message, details) : die(message));
3542
3542
  const usage = "usage: oats onboard [<dir>] --workspace <repo ref> [--json] (or --dir <dir>)";
@@ -3615,12 +3615,15 @@ async function onboardCmd() {
3615
3615
  // (4) The taught layout as next steps (design doc §4), and the envelope.
3616
3616
  const standalone = synced.discovery.standalone === true;
3617
3617
  const members = synced.report.members;
3618
- // The operator expert is suggested only when THIS workspace lists a soul by that name (a
3619
- // confirmed member's or, standalone, the repo's own); otherwise any listed soul is spawnable.
3618
+ // The setup expert is suggested only when THIS workspace lists one (setupExpertOf); otherwise
3619
+ // any listed soul is spawnable.
3620
3620
  const soulNames = synced.items.souls.map((s) => s.name);
3621
- const setupExpert = soulNames.includes("oats-operator-expert");
3622
- const spawnHint = setupExpert ? `oats spawn oats-operator-expert --dir ${shortPath(dir)}` : null;
3623
- const anySoulHint = `spawn any listed soul: oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
3621
+ const { OPERATOR_CAPABILITY } = await import("../lib/operator-coverage.mjs");
3622
+ const wsName = standalone ? null : synced.discovery.workspace?.name;
3623
+ const conventional = typeof wsName === "string" && wsName ? `${wsName}-oats-setup-expert` : null;
3624
+ const setupExpert = setupExpertOf(synced.discovery, { conventional, capability: OPERATOR_CAPABILITY });
3625
+ const spawnHint = setupExpert ? `oats spawn ${setupExpert} --dir ${shortPath(dir)}` : null;
3626
+ const anySoulHint = `oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
3624
3627
  // A member's clone goes beside oats-local.yaml under its repo name; `agents/` is the instance
3625
3628
  // homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4). The HOST is
3626
3629
  // listed exactly like any other member when it is one: a clone of it is needed only if someone
@@ -3660,10 +3663,38 @@ Next:
3660
3663
  2. Check who may read the host: ${synced.discovery.key}${hostIsMember ? " is itself a member" : " is a dedicated host"}. The workspace file
3661
3664
  names every member, so if any member is private the host must be a private repo that is not
3662
3665
  a public member; public contributors then get the standalone case (from: here + oats.core).
3663
- 3. ${setupExpert ? "Spawn the operator expert to guide the rest (souls, teams, provider settings):" : "No soul named oats-operator-expert is listed here —"}
3666
+ 3. ${setupExpert ? `Spawn ${setupExpert}, this workspace's OATS setup expert
3667
+ (it holds ${OPERATOR_CAPABILITY}), to guide the rest:` : `No soul here holds ${OPERATOR_CAPABILITY} — add a ${conventional ? `${conventional} soul` : "soul"} that declares it,
3668
+ or spawn any listed soul:`}
3664
3669
  ${spawnHint ?? anySoulHint}`);
3665
3670
  }
3666
3671
 
3672
+ /** The soul `oats onboard` names as the workspace's OATS setup expert (awebai/oats#1314), among the
3673
+ * souls a spawn can name (soulCandidates) whose own soul.yaml declares `capability` (oats.setup) with
3674
+ * `{ from: … }`, from any source (`off` is no declaration): the one named `conventional`
3675
+ * (`<workspace name>-oats-setup-expert`, null in a standalone view, which has no workspace name);
3676
+ * else the first by name; else null. A soul is never chosen by its name alone. Only the soul's own declaration is read, never
3677
+ * a resolution: oats.setup that reaches a soul through the workspace defaults alone is not seen. → the
3678
+ * name to spawn it by: the bare name, else `<member>/<soul>` (`<package>/<soul>`), else
3679
+ * `<member repo key>/<soul>`, the first that names this soul alone. */
3680
+ function setupExpertOf(discovery, { conventional, capability }) {
3681
+ const candidates = soulCandidates(discovery);
3682
+ const declares = (entry) => {
3683
+ const caps = entry.definition?.capabilities;
3684
+ const choice = caps !== null && typeof caps === "object" && Object.hasOwn(caps, capability) ? caps[capability] : null;
3685
+ return choice !== null && typeof choice === "object" && typeof choice.from === "string" && choice.from !== "";
3686
+ };
3687
+ const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
3688
+ const entries = candidates.map((c) => c.entry).sort((a, b) => order(a.name, b.name) || order(qualifiedSoulName(a), qualifiedSoulName(b)));
3689
+ const chosen = (conventional && entries.find((e) => e.name === conventional && declares(e))) || entries.find(declares);
3690
+ if (!chosen) return null;
3691
+ // The shortest name a spawn resolves to exactly this soul: two members can share a repository
3692
+ // basename (github.com/a/agents, github.com/b/agents), so the last form is the full repo key.
3693
+ const forms = [chosen.name, qualifiedSoulName(chosen), ...(typeof chosen.package === "string" ? [] : [`${chosen.repoKey}/${chosen.name}`])];
3694
+ const only = (name) => { const hits = candidates.filter((c) => c.matches(name)); return hits.length === 1 && hits[0].entry === chosen; };
3695
+ return forms.find(only) ?? forms[forms.length - 1];
3696
+ }
3697
+
3667
3698
  /** `oats onboard <dir> [--workspace <ref>] --check`: what onboarding <dir> here would meet, read-only (the
3668
3699
  * question `oats server connect` asks a host before onboarding there, and `oats server check` asks of a
3669
3700
  * registered deployment). A leading ~ is this machine's home. `state` is absent | empty | not-empty |
@@ -4734,8 +4765,9 @@ Usage:
4734
4765
  oats onboard [<dir>] --workspace <repo ref> realize a workspace here: writes <dir>/oats-local.yaml
4735
4766
  [--json] and agents/, then runs the oats sync path (lock v3)
4736
4767
  and prints the
4737
- next steps (clone members you work IN, spawn
4738
- oats-operator-expert); creates no soul, spawns nothing
4768
+ next steps (clone members you work IN, spawn the
4769
+ workspace's setup expert (the soul holding oats.setup));
4770
+ creates no soul, spawns nothing
4739
4771
  [--check] --check: write nothing; report <dir> (~ = this home),
4740
4772
  its state and whether Git reads the workspace remote
4741
4773
  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
@@ -305,6 +305,15 @@ configuration is a host choice: a soul never names one.
305
305
  environment, command and preflight checks) and starts nothing.
306
306
  - The old key `runtime` is still read as `harness`, with a
307
307
  `deprecated-runtime-name` warning.
308
+ - **Claude's permissions** are Claude's own settings, not OATS keys. They go
309
+ in the user settings of the Claude config a launch uses (its
310
+ `CLAUDE_CONFIG_DIR`, else `~/.claude`), or `--permission-mode` goes in a
311
+ configuration's `args`. Never in a home's `.claude/settings.json`: the
312
+ capabilities manage it at every start, and Claude ignores auto mode there.
313
+ oats.setup's `/oats-agent-permissions` (oats.framework 1.13.0) teaches the
314
+ setup: auto mode, narrow allow rules for the `oats` and `gh` reads,
315
+ `oats spawn` and reading `aw` mail and chat, and what stays gated.
316
+ `yolo` is separate and is meant for isolated machines.
308
317
 
309
318
  ### The harness default
310
319
 
@@ -882,8 +882,8 @@ same argument, given once). The ref is checked before anything is written.
882
882
  "hosting":{"host":"github.com/acme/agents","hostIsMember":true,"rule":"If any member is private, host oats-workspace.yaml in a private repo …"},
883
883
  "next":{"clone":[{"key":"github.com/acme/agents","name":"agents","url":"https://github.com/acme/agents.git","dir":"/w/agents-repo","present":false,"host":true},
884
884
  {"key":"github.com/acme/platform","name":"platform","url":"https://github.com/acme/platform.git","dir":"/w/platform","present":true,"host":false}],
885
- "spawn":"oats spawn oats-operator-expert --dir /w",
886
- "souls":["oats-operator-expert","platform-engineer","release-manager"]}}
885
+ "spawn":"oats spawn acme-oats-setup-expert --dir /w",
886
+ "souls":["acme-oats-setup-expert","platform-engineer","release-manager"]}}
887
887
  ```
888
888
 
889
889
  - `sync` is the full [`oats sync`](#oats-sync) report (abridged above).
@@ -895,9 +895,32 @@ same argument, given once). The ref is checked before anything is written.
895
895
  existing clone (the `clones:` entry, else `<dir>/<name>`), else where to
896
896
  clone it: `<dir>/<name>`, or `<dir>/agents-repo` for a member named
897
897
  `agents`. `url` is `null` when unknown.
898
- - `next.spawn` is `oats spawn oats-operator-expert --dir <dir>` when the
899
- workspace has a soul by that name, else `null`. `next.souls` is the first
900
- three soul names, sorted.
898
+ - `next.spawn` is `oats spawn <soul> --dir <dir>` naming the workspace's
899
+ OATS setup expert, else `null` (OATS 0.61.0; before it, only a soul named
900
+ `oats-operator-expert` was named). Among the souls onboarding lists
901
+ (confirmed members', external and package souls; standalone, the
902
+ repository's own), the setup expert is:
903
+ 1. the soul named `<workspace name>-oats-setup-expert` that declares
904
+ `oats.setup`, where the workspace name is the `name:` of
905
+ `oats-workspace.yaml` (`sync.workspace.name`); a standalone view has no
906
+ workspace name, so this step does not apply there;
907
+ 2. otherwise the first soul by name that declares `oats.setup`;
908
+ 3. otherwise none: `null`.
909
+
910
+ A soul declares `oats.setup` when its own `soul.yaml` names it under
911
+ `capabilities:` as `{ from: … }`, from any source (`package`, `here` or a
912
+ member key); `oats.setup: off` does not count. A soul is never chosen by
913
+ its name alone: one named `<workspace name>-oats-setup-expert` that does
914
+ not declare `oats.setup` falls through to step 2.
915
+
916
+ Only the soul's own declaration is read, not its resolved composition:
917
+ `oats.setup` that reaches a soul only through the workspace's `defaults:`
918
+ is not seen, and a declared `oats.setup` is not checked to resolve. A soul
919
+ whose name another listed soul shares is named so that `oats spawn` finds
920
+ it alone: `<member>/<soul>` or `<package>/<soul>`, else, when two members
921
+ share a repository name, `<member repo key>/<soul>`. The text output's step 3 names
922
+ the same soul, or, with none, the conventional name to add.
923
+ `next.souls` is the first three soul names, sorted.
901
924
  - Errors: `E_BAD_ARGS` (usage, no `--workspace`, a repeated directory, an
902
925
  unknown flag), `E_REPO_REF`, `E_ALREADY_ONBOARDED {local, dir}` (this
903
926
  directory already has `oats-local.yaml`), `E_ONBOARD_FAILED {dir}`. A
@@ -2800,8 +2823,13 @@ its absence.
2800
2823
  redacted) plus `home` and `instance` (from the directory; a disagreeing
2801
2824
  claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
2802
2825
  the row's recorded tmux socket and session, never the caller's `$TMUX`;
2826
+ `true` means the harness is running, using the same pane and shell-descendant
2827
+ rule as session inspection. A fallback shell is `false` with `runtimeState:
2828
+ "shell"`, even though the window remains; a dead pane or absent window is
2829
+ `false`. A wrapper shell with a live non-shell descendant stays `true`;
2803
2830
  `null` with `runtimeState: "unreachable"` and the tmux error as
2804
- `runtimeError` when that server cannot be read, and also when its socket
2831
+ `runtimeError` when that server or its panes cannot be read (including a split
2832
+ agent window or a failed shell-descendant process scan), and also when its socket
2805
2833
  file is missing while a process works in the home or the process scan
2806
2834
  cannot run, `runtimeError` then naming the processes or the scan's error
2807
2835
  ([#624](execution-targets.md#missing-socket); with no process in the home
@@ -2846,10 +2874,12 @@ its absence.
2846
2874
  waiting"). Its rules are the events read's ([Waiting on you](#waiting-on-you)):
2847
2875
  one bounded read of the home's log per running row. A remote roster row
2848
2876
  carries what the remote kernel reports; an older kernel omits the field.
2849
- `running` is the window's presence, which a crashed harness's fallback
2850
- shell or a retained dead pane keeps, so a row with a claim is checked
2851
- against its session (as `oats session inspect` observes it) and reads
2852
- `null` unless a harness runs there.
2877
+ From OATS 0.60.0 `running` is the harness's liveness, so a fallback shell
2878
+ or a retained dead pane already reads `running: false` and carries no
2879
+ claim; the claim still needs the home's session receipt to name a target.
2880
+ An older kernel's `running` is the window's presence, and it checks a row
2881
+ with a claim against its session (as `oats session inspect` observes it),
2882
+ reading `null` unless a harness runs there.
2853
2883
  - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
2854
2884
  0.59.0): `{state, since, self, code?, message?}` while a retire of the home
2855
2885
  is running, scheduled or owed; absent otherwise, and from older kernels.
package/docs/desktop.md CHANGED
@@ -529,6 +529,13 @@ has reached the execution host. Both CLI installations must advertise
529
529
  `session-upload`. A failed transfer leaves the draft unchanged and shows an
530
530
  error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
531
531
 
532
+ ## The sidebar's instance tree
533
+
534
+ The sidebar lists a workspace's instances as a tree: a child sits one step
535
+ right of its parent, and related instances are grouped together. Siblings are
536
+ joined by a dotted line through their dots. A parent's line to its children
537
+ runs just to the right of the dotted line, so the two never merge.
538
+
532
539
  ## Identity marks and harness badges
533
540
 
534
541
  Souls, capabilities and workspaces carry a coloured two-letter mark beside
@@ -51,8 +51,13 @@ deployment's `session.tmuxSession`, else `OATS_TMUX_SESSION`, else
51
51
  session it recorded, and `oats status` reads each home on its recorded tmux
52
52
  socket and session, never the caller's `$TMUX` server: a caller outside the
53
53
  agents' tmux (ssh, cron, a plain terminal) sees the same liveness as `session
54
- inspect`. A recorded server that cannot be read gives `running: null` with
55
- `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
54
+ inspect`. `running` means the harness is running, not merely that its window
55
+ exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
56
+ a retained dead pane also reads `false`. A wrapper shell with a live non-shell
57
+ descendant still reads `true`. Status shares session inspection's pane rule,
58
+ with one batched pane read per socket/session and one lazy process scan across
59
+ all shell panes. A recorded server or pane that cannot be read gives
60
+ `running: null` with `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
56
61
  inspect --json` reports the session a new spawn would open in as `session`
57
62
  (`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
58
63
  session it would open in, on the OATS tmux server (`E_INSTANCE_NAME_TAKEN`); a
@@ -69,6 +69,14 @@ runs before adding its pin. Then clone the
69
69
  member you will work in beside `oats-local.yaml` (only a soul's work target
70
70
  needs a clone — discovery and resolution run over the remotes).
71
71
 
72
+ The last next step names the workspace's OATS setup expert to spawn, among the
73
+ souls that declare `oats.setup` in their own `soul.yaml`: the one named
74
+ `<workspace name>-oats-setup-expert` (`acme-oats-setup-expert` for a
75
+ workspace named `acme`), else the first by name. With neither, it says so and suggests
76
+ adding that conventional soul, or spawning any listed soul. The full rule and
77
+ its limits are in
78
+ [desktop-cli-api.md](desktop-cli-api.md#oats-onboard-onboardapi-2).
79
+
72
80
  `--json` returns `onboardApi: 2` (`local`, `dir`, `agents`, `lock`, the full
73
81
  `sync` report, `hosting`, `next.clone[]`, `next.spawn`); running it twice is
74
82
  `E_ALREADY_ONBOARDED` (use `oats sync`); a mistyped ref is `E_REPO_REF`, an
@@ -123,6 +123,7 @@ and the rules its tests pin.
123
123
  | `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
124
124
  | `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
125
125
  | `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
126
+ | `session-input.mjs` | session inspection and input transport. `createSessionPaneInspector` interprets one window's panes for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
126
127
  | `servers.mjs` | routing commands to a registered server |
127
128
  | `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
128
129
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v5.2.1
44
- oats.aweb: v1.28.0
44
+ oats.aweb: v1.29.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.12.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.13.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.28.0` | `oats.aweb` (messaging) | |
14
+ | `oats.aweb` | `v1.29.0` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.2.1` or `oats-framework/v1.12.2`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.13.0`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.12.2
77
+ oats.framework: v1.13.0
78
78
  oats.okf: v5.2.1
79
- oats.aweb: v1.28.0
79
+ oats.aweb: v1.29.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.28.0 # a catalog version
137
+ oats package add oats.aweb v1.29.0 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.2", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.0", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.12.2`
362
- resolves to tag `oats-framework/v1.12.2`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.13.0`
362
+ resolves to tag `oats-framework/v1.13.0`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,104 @@
1
+ # OATS 0.60.0
2
+
3
+ 2026-10-16
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.59 Desktop refuses a 0.60.0 CLI. The
9
+ 0.60.0 Desktop accepts OATS CLIs `>=0.26.0 <0.61.0`.
10
+
11
+ - **`running` in a status row now means the harness is running**
12
+ ([#364](https://github.com/awebai/oats/issues/364)). A window left at its
13
+ fallback shell after Stop reads `running: false`, `runtimeState: "shell"`;
14
+ before, it read `true` because the window existed. A script or tool that
15
+ reads `oats status --json` to see whether an agent is running now gets the
16
+ answer the lifecycle commands give. See Changed.
17
+
18
+ - **The official catalog moves two pins:** oats.framework 1.12.2 → 1.12.3
19
+ and oats.aweb 1.28.0 → 1.29.0 (see Provider updates). The other packages
20
+ are unchanged. A deployment takes them by changing its pins and running
21
+ `oats sync`. Only new spawns use them.
22
+
23
+ ## Added
24
+
25
+ - **`oats tui` lists the open workspace's capabilities**
26
+ ([#855](https://github.com/awebai/oats/issues/855)). `3`, or the leader
27
+ then `3`, shows the Capabilities view, which until now was a placeholder:
28
+ the capabilities in the OATS Desktop's sections (Workspace owned, Repo
29
+ owned, Packages), grouped by repository or package, each with its layer.
30
+ The detail beside it says what the capability is, where it comes from,
31
+ the skills, commands and hooks it provides, and the souls that use it,
32
+ each with how many of its instances here carry it and how many of those
33
+ are on an older version. In the detail, `Up`/`Down` mark a soul and
34
+ `Enter` shows it in the Souls view. The list is the Desktop's, read with
35
+ `oats capabilities` only once the view is first shown, and again only
36
+ when the workspace changes, or with `r`. The palette lists the
37
+ capabilities once they are read. See
38
+ [the TUI page](../tui.md#the-capabilities-view).
39
+
40
+ ## Changed
41
+
42
+ - **`oats status` reports whether the harness is running**
43
+ ([#364](https://github.com/awebai/oats/issues/364)). After Stop leaves a
44
+ fallback shell, the row reads `running: false` with `runtimeState: "shell"`,
45
+ even though its tmux window remains. A live harness remains running, and an
46
+ unreadable session remains unknown. Pane reads are batched per socket and
47
+ session.
48
+
49
+ - **OATS Desktop accepts an `oats` CLI 0.60.x.** Its band is now
50
+ `>=0.26.0 <0.61.0`. 0.60 adds no new gate on the band: a status row's
51
+ `running: false` with `runtimeState: "shell"` for a window at its fallback
52
+ shell is what the Desktop's own terminal probe already reports for a local
53
+ row, and a server's rows now read the same way.
54
+
55
+ - **`oats tui` polish** ([#855](https://github.com/awebai/oats/issues/855)).
56
+ The footer names `[/] tab` while two tabs or more are open. The help's
57
+ Marks section lists the soul mark `■` (`#` in ASCII) and a refused soul's
58
+ `!`. A split one above the other joins the list's bar with `├` (`+` in
59
+ ASCII).
60
+
61
+ ## Fixed
62
+
63
+ - **`r` in the `oats tui` Souls view keeps the souls when the read fails**
64
+ ([#1301](https://github.com/awebai/oats/issues/1301)). In 0.59.0, `r`
65
+ forgot the souls before reading them again, so a read that failed left
66
+ only the failure. Now the souls stay listed while `r` reads, and a read
67
+ that fails keeps them under a heading that says it failed, as the
68
+ Capabilities view does. See [the TUI page](../tui.md#the-souls-view).
69
+
70
+ - **`oats tui`: a package soul's instances are its own in the Souls view**
71
+ ([#855](https://github.com/awebai/oats/issues/855)). In 0.59.0 the Souls
72
+ view counted no instances for a soul that comes from a package, and `i`
73
+ on it listed none: the view did not match the name its instances carry,
74
+ `<package>--<soul>`. Its row now counts its instances on this machine,
75
+ `i` lists them in the Instances view, and its detail names them. See
76
+ [the TUI page](../tui.md#the-souls-view).
77
+
78
+ ## Provider updates
79
+
80
+ - **oats.framework 1.12.3, oats.core 2.6.3: `/oats-operate` says what
81
+ `running` means** ([#364](https://github.com/awebai/oats/issues/364)).
82
+ From OATS 0.60.0, a status row's `running` is the harness's liveness: a
83
+ window left at its fallback shell after Stop reads `running: false`,
84
+ `runtimeState: "shell"`. The skill dates the rule, since an older kernel
85
+ still reports such a window as running. Instruction text only; the floors
86
+ are unchanged. A deployment gets it by pinning `oats.framework: v1.12.3`
87
+ and running `oats sync`.
88
+
89
+ - **oats.aweb 1.29.0: the agent status publisher.** The catalog and this
90
+ workspace pin `oats.aweb: v1.29.0`.
91
+ - `oats aweb health enable | status | disable | publish` publishes, once a
92
+ minute, a signed status for every agent of the deployment to aweb:
93
+ whether it can be reached (`yes`, `degraded`, `no` or `unknown`), why
94
+ not, and who fixes it. It is opt-in and host-only
95
+ (`settings.oats.aweb.health` in `oats-local.yaml`), runs in the
96
+ deployment directory, never inside an instance, and needs aw 1.36.38 to
97
+ publish (checked before anything is sent). `disable` clears every
98
+ designation it made.
99
+ - `/oats-aweb`: on macOS, `oats aweb wake install` runs from the desktop
100
+ login, not over ssh.
101
+ - The floors are unchanged (OATS >=0.52.0, aw >=1.36.33). A deployment
102
+ gets it by pinning `oats.aweb: v1.29.0` and running `oats sync`; only
103
+ new spawns use it. The provider's reference is its
104
+ `docs/health-publisher.md`.
@@ -0,0 +1,155 @@
1
+ # OATS 0.61.0
2
+
3
+ 2026-10-16
4
+
5
+ ## Upgrade
6
+
7
+ - **A pi instance stuck on its opening task: restart it after the update**
8
+ ([#1322](https://github.com/awebai/oats/issues/1322)). On pi 1.2 and
9
+ later, the 0.60.0 bridge (`@awebai/oats-pi`) held an instance's opening
10
+ task forever, and everything typed after it stayed queued. Install the
11
+ 0.61.0 bridge (`oats update` moves it in every pi folder your launches
12
+ use), then restart each pi instance that is stuck. Instances that already
13
+ ran their opening task are unaffected. See Fixed.
14
+
15
+ - **Install the Desktop first and the CLI second,** as
16
+ [Upgrading](../upgrading.md) says: a 0.60 Desktop refuses a 0.61.0 CLI. The
17
+ 0.61.0 Desktop accepts OATS CLIs `>=0.26.0 <0.62.0`.
18
+
19
+ - **The official catalog moves oats.framework 1.12.3 → 1.13.0** (oats.setup
20
+ 2.8.0, see Provider updates). The other packages are unchanged. A
21
+ deployment takes it by changing its pin and running `oats sync`. Only new
22
+ spawns use it.
23
+
24
+ - **OATS 0.61.0: `oats onboard`'s `next.spawn` can name a soul other than
25
+ `oats-operator-expert`** ([#1314](https://github.com/awebai/oats/issues/1314)).
26
+ Before OATS 0.61.0 it named `oats-operator-expert` whenever a soul had that
27
+ name, and only then; from OATS 0.61.0 it names the soul that holds
28
+ `oats.setup`, the workspace's setup expert, so a workspace without this
29
+ project's soul is pointed at its own. The JSON shape is unchanged
30
+ (`onboardApi` 2, text or `null`). A script that matched the old exact name
31
+ sees a different answer: a soul named `oats-operator-expert` that does not
32
+ declare `oats.setup` now gives `null`.
33
+
34
+ ## Changed
35
+
36
+ - **OATS Desktop's command palette shows when two instances are siblings**
37
+ ([#1312](https://github.com/awebai/oats/issues/1312)). An instance declared
38
+ a sibling of a root, and that root, each say `sibling of <name>` beside
39
+ the name, in the tree, as a match's context and in Recent, and assistive
40
+ technology reads it once with the row. Siblings under one parent still read
41
+ `under <parent>`. Matching, order and groups are unchanged
42
+ ([keyboard reference](../../packages/desktop/docs/desktop-keyboard.md)).
43
+
44
+ - **The Desktop sidebar draws the sibling line apart from the lines to
45
+ children** ([#1312](https://github.com/awebai/oats/issues/1312)). The
46
+ dotted line joining sibling instances runs through their dots, and a
47
+ parent's line to its children runs just to the right of it, so the two no
48
+ longer share one line. The dotted line is darker in the White and Solarized
49
+ themes, so it stands out on every row (3:1 contrast). See
50
+ [the sidebar's instance tree](../desktop.md#the-sidebars-instance-tree).
51
+
52
+ - **OATS 0.61.0: `oats onboard` names the workspace's OATS setup expert**
53
+ ([#1314](https://github.com/awebai/oats/issues/1314)). Its last next step,
54
+ and `next.spawn` in `--json`, name a soul whose own `soul.yaml` declares
55
+ `oats.setup` (from any source; `off` does not count): the one called
56
+ `<workspace name>-oats-setup-expert`, else the first by name, else none,
57
+ when the text suggests adding that conventional soul. A name alone never
58
+ counts. Only the
59
+ soul's own declaration is read: `oats.setup` given only through workspace
60
+ defaults is not seen. A standalone view has no workspace name, so only
61
+ the declaration counts there. `oats help` describes the step the same way
62
+ ([the rule](../desktop-cli-api.md#oats-onboard-onboardapi-2)).
63
+
64
+ - **OATS Desktop accepts an `oats` CLI 0.61.x.** Its band is now
65
+ `>=0.26.0 <0.62.0`. 0.61 adds no new gate on the band: `oats onboard`'s
66
+ next step names the workspace's setup expert in the same text-or-`null`
67
+ shape the Desktop already reads.
68
+
69
+ ## Fixed
70
+
71
+ - **pi 1.2 and later run an instance's opening task again**
72
+ ([#1322](https://github.com/awebai/oats/issues/1322)). From pi 1.2.0 a run
73
+ counts as active before its `before_agent_start`, and the bridge's hold on
74
+ the opening prompt waited for that same run. So on pi 1.2 and later, an
75
+ instance's opening task never ran. That was the launch's `@TASK.md` in
76
+ interactive mode, or the first default `session.prompt()` of an SDK
77
+ session. Escape didn't release it, and every later prompt waited queued
78
+ behind it, even after the aweb welcome's turn had finished. The hold now
79
+ never waits for the prompt's own run, and a session that shuts down
80
+ releases it. The task still runs once, after a welcome turn that started
81
+ first. On pi 1.2 and later, a welcome sent while the task's run starts is
82
+ queued by pi into that run, after the task. The bridge still sends and
83
+ alters nothing. Restart a pi instance that hangs on its opening task once
84
+ the updated `@awebai/oats-pi` is installed (`oats update`).
85
+
86
+ - **`oats tui` names a sibling at both ends of the link, and its palette
87
+ names siblings** ([#1315](https://github.com/awebai/oats/issues/1315)).
88
+ The detail's parent line named a sibling only on the instance that
89
+ declared the link, and named it as written, even when no instance had
90
+ that name or two had it. Now both ends say `sibling of <names>`, as the
91
+ Desktop does, and a name that resolves to no instance, or to more than
92
+ one, is not shown. The palette shows the same words, dim, after an
93
+ instance's name; a query never matches them. See
94
+ [the TUI page](../tui.md#the-palette).
95
+
96
+
97
+ ## Provider updates
98
+
99
+ - **oats.framework 1.13.0, oats.setup 2.8.0: the setup expert runs the
100
+ setup, and the person types only secrets**
101
+ ([#1314](https://github.com/awebai/oats/issues/1314)).
102
+ - **The setup briefing has one rule for what the person types:**
103
+ passwords, tokens, API keys and interactive logins. It also keeps the two
104
+ installs that capture their own shell, the host wake broker and the host
105
+ timer (#922). Everything else the agent runs and reads back.
106
+ - **A secret reaches its command by a route the agent never sees,** in
107
+ this order:
108
+ - a browser device flow the agent starts (`gh auth login --web` without
109
+ a terminal);
110
+ - a no-echo prompt in a split of the agent's own tmux pane, which closes
111
+ when its command ends (while it is open, wakes and `oats session input`
112
+ can't reach that instance);
113
+ - the person's own terminal.
114
+
115
+ Each route is checked with a read-only command.
116
+ - **`/oats-git-setup` is run by the agent.** The person approves each gh
117
+ login in the browser and chooses their name, email and passphrase
118
+ option. The SSH key is made with no passphrase, because the kernel's ssh
119
+ runs in batch mode; a passphrase key held in an ssh-agent is the
120
+ alternative. The GitHub host key that was checked against its published
121
+ fingerprint is the one recorded. Step 0 reads the global Git
122
+ configuration's names only, and step 7's check runs as one block.
123
+ - **`/oats-setup-expert` (new):** a workspace setup expert's first session.
124
+ It starts from the intake that the `oats-getting-started` skill hands it
125
+ from OATS 0.62.0,
126
+ covers a new or an existing workspace, and ends at a first working soul.
127
+ `/oats-onboarding` points to it.
128
+ - **`/oats-agent-permissions` (new): Claude Code's permissions for OATS
129
+ instances.** The setup expert writes the user settings of the Claude
130
+ config the launches use, never the home's `.claude/settings.json`:
131
+ - auto mode, by `permissions.defaultMode` or `--permission-mode auto` in
132
+ a launch configuration's `args`;
133
+ - an `autoMode` block naming what the workspace trusts;
134
+ - narrow allow rules for the `oats` reads, `oats spawn` (with an `ask`
135
+ rule on `--yolo`, `--server` and `--wake-*`), reading `aw` mail and
136
+ chat, and `gh` reads.
137
+
138
+ Retire and stop (except `--plan`), `aw` sends, `git` beyond Claude's
139
+ built-in read-only forms, pushes, merges and the operator acts stay
140
+ with the classifier, or an `ask` rule. The person approves the
141
+ change. The check: no `waitingOnYou` with reason `permission` during the
142
+ first working soul's task. Claude only; Codex and pi are named.
143
+ - **`/oats-setup-model` explains the per-workspace setup expert,** and how
144
+ `oats onboard` finds it from OATS 0.61.0.
145
+ - Instruction text only; the floors are unchanged. A deployment gets it by
146
+ pinning `oats.framework: v1.13.0` and running `oats sync`.
147
+
148
+ ## Documentation
149
+
150
+ - **The README's opening reads at a skim.** One paragraph says what OATS is
151
+ (a provider- and harness-agnostic framework for distributed agent teams,
152
+ completely free and open source), then five short points: each agent
153
+ keeps its harness's full power, capabilities shape the team over
154
+ opinionated defaults, you keep control, the two clients, and what it
155
+ builds on.