@awebai/oats 0.68.0 → 0.69.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.
Files changed (72) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +147 -13
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.68.1.md +102 -0
  15. package/docs/release-notes/v0.69.0.md +658 -0
  16. package/docs/release-notes/v0.69.1.md +25 -0
  17. package/docs/servers.md +44 -5
  18. package/docs/souls-and-instances.md +11 -7
  19. package/docs/tui.md +114 -31
  20. package/docs/upgrading.md +14 -5
  21. package/docs/workspaces.md +1 -1
  22. package/lib/core.mjs +345 -89
  23. package/lib/file-pieces.mjs +49 -0
  24. package/lib/instance-events.mjs +25 -4
  25. package/lib/launch-prompt-fixtures/README.md +62 -0
  26. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  27. package/lib/launch-prompt-fixtures.mjs +49 -0
  28. package/lib/launch-prompt-resume.mjs +55 -0
  29. package/lib/login-environment.mjs +27 -9
  30. package/lib/schedule.mjs +3 -3
  31. package/lib/servers.mjs +117 -23
  32. package/lib/session-end.mjs +82 -0
  33. package/lib/session-input.mjs +43 -9
  34. package/lib/session-resume-contract.mjs +32 -0
  35. package/lib/session-resume.mjs +310 -0
  36. package/lib/session-seen.mjs +163 -0
  37. package/lib/session-viewer.mjs +147 -44
  38. package/lib/soul-composition.mjs +2 -1
  39. package/lib/start-env.mjs +110 -0
  40. package/lib/tmux-server-scope.mjs +139 -14
  41. package/lib/workspace.mjs +38 -4
  42. package/package-catalog.json +10 -4
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +9 -0
  45. package/packages/client/cli-locator.mjs +3 -2
  46. package/packages/client/deployment-data.mjs +7 -0
  47. package/packages/client/deployment-panel.mjs +3 -0
  48. package/packages/client/file-output-exec.mjs +98 -0
  49. package/packages/client/instance-display-name.mjs +18 -0
  50. package/packages/client/launch-prompt-outcome.mjs +25 -13
  51. package/packages/client/own-codes.mjs +2 -0
  52. package/packages/client/session-attach.mjs +35 -5
  53. package/packages/client/session-resume-cli.mjs +64 -0
  54. package/packages/client/session-resume-trigger.mjs +167 -0
  55. package/packages/client/session-resume.mjs +332 -0
  56. package/packages/client/tmux-status.mjs +30 -7
  57. package/packages/client/waiting-on-you.mjs +11 -4
  58. package/packages/client/workspace-step.mjs +17 -5
  59. package/packages/record/lib/last-conversation.mjs +123 -0
  60. package/packages/record/lib/session-roots.mjs +10 -1
  61. package/packages/tui/README.md +1 -1
  62. package/packages/tui/lib/client.mjs +2 -1
  63. package/packages/tui/lib/main.mjs +5 -3
  64. package/packages/tui/lib/model.mjs +57 -15
  65. package/packages/tui/lib/store.mjs +8 -7
  66. package/packages/tui/lib/term/text.mjs +12 -9
  67. package/packages/tui/lib/views/capabilities.mjs +6 -6
  68. package/packages/tui/lib/views/frame.mjs +72 -7
  69. package/packages/tui/lib/views/help.mjs +9 -4
  70. package/packages/tui/lib/views/instances.mjs +46 -29
  71. package/packages/tui/lib/views/souls.mjs +9 -8
  72. package/skills/oats-getting-started/SKILL.md +117 -4
package/docs/desktop.md CHANGED
@@ -191,6 +191,18 @@ workspace on a server: `name — server`).
191
191
  window they were opened in, and switching that window back to the
192
192
  workspace brings them back. A window whose workspace another window takes
193
193
  over closes its tabs of that workspace.
194
+ - Switching back also puts the keyboard back where you left it in that
195
+ workspace, with no click: in the terminal you were typing in, ready to
196
+ type; on the instance's row in the list of instances, once that list is
197
+ read; on the tab, or the control of the page or the views you were on. Going
198
+ to the list of workspaces to pick one doesn't move that place: the
199
+ terminal you typed in before is still where the focus comes back. If that
200
+ tab closed while the workspace was hidden, the focus goes to the tab active
201
+ in its place, or to the page when no tab is left. An instance retired
202
+ elsewhere keeps its tab until the workspace's list of instances is read
203
+ again: the focus goes into that tab, and when it closes, to the next tab. A
204
+ stopped instance's tab ("session ended") gets the focus, and nothing typed
205
+ there reaches a terminal.
194
206
  - A tab's terminal ends ("session ended") when its instance's tmux window
195
207
  goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
196
208
  another instance's terminal. Stopping an instance leaves its tab open.
@@ -213,8 +225,8 @@ foot, one bar: the OATS mark and the sidebar toggle (**Hide the sidebar**)
213
225
  after it, and at the bar's right **Spawn instance**, its words alone (a ground
214
226
  only on hover), which
215
227
  opens Quick Open (⌘P / Alt+P, named in its tooltip) to pick a soul and then
216
- the spawn dialog, and the settings cog, whose menu holds **Theme…** and **Keyboard
217
- shortcuts…**, each with its shortcut. A window opens on the **Workspace
228
+ the spawn dialog, and the settings cog, whose menu holds **Theme…**, **Font…** and
229
+ **Keyboard shortcuts…**, each with its shortcut when it has one. A window opens on the **Workspace
218
230
  overview** page, on its **Souls** tab: at launch, and after you choose a
219
231
  workspace for it. Connections is in the command palette
220
232
  (**Settings: Connections…**), and the palette opens with its shortcut or
@@ -225,6 +237,58 @@ instance roster**) and `/` in the sidebar go to the roster's current row;
225
237
  on an empty roster, to its one action, the foot's **Spawn instance**, where
226
238
  F6 lands too (a failed read's **Retry** comes first).
227
239
 
240
+ The sidebar is 288px wide, and you can make it wider or narrower: drag its
241
+ right edge, between 240px and 480px (or 45% of the window, when that is
242
+ less, so the terminals keep the rest). With the keyboard, Tab to that edge
243
+ (after the settings cog) and use ← and → (8px a step, 32px with Shift), Home
244
+ and End for the narrowest and the widest. A double-click on the edge, Enter
245
+ on it, or the command palette's **Sidebar: reset width** put it back to 288px.
246
+ The width is remembered on this computer, and kept while the sidebar is
247
+ hidden; a window too narrow for it shows it narrower, and gives it back when
248
+ the window grows again. The terminals refit as it moves, and their programs
249
+ hear the new size once, when you let go.
250
+
251
+ **Theme and font.** The settings cog's **Theme…**, the palette's **Theme: choose…** and
252
+ ⇧⌘Space / Ctrl+Shift+Space open the theme picker (White, Solarized, Dark, or
253
+ This computer, which follows the computer's own theme). The font has a picker
254
+ of its own, the settings cog's **Font…** or **Font: choose…** in the palette (no
255
+ shortcut unless you give it one in the shortcuts editor), with two choices:
256
+
257
+ - **Omarchy's font**, the default on a computer that runs Omarchy. On Linux the whole window and its
258
+ terminals use the computer's monospace font, the one `omarchy font current`
259
+ names and `omarchy font set` changes (fontconfig's `monospace`, on any
260
+ Linux). A font changed that way shows when Desktop next starts, at the
261
+ latest. On Windows it is the system's monospace font, for the window and the
262
+ terminals. On macOS the choice is named **JetBrains Mono**, Omarchy's default
263
+ face: the window uses it (or the system's monospace font where it is not
264
+ installed), and the terminals keep Inconsolata. On every platform, instance
265
+ names in the sidebar and on tabs are a little smaller in it (12px, from
266
+ 12.5px), since a monospace face runs wider.
267
+ - **System font**, the faces Desktop had before: the system's interface font
268
+ for the window and Inconsolata in the terminals. It is the default on every
269
+ computer that doesn't run Omarchy (other Linux, macOS and Windows).
270
+
271
+ Desktop knows a computer runs Omarchy when Omarchy's theme directory
272
+ (`~/.local/state/omarchy/current`) is there, the same one the **This computer**
273
+ theme reads. A font you chose always wins over the default. On Omarchy the
274
+ terminal's default size is also smaller, 13px (JetBrains Mono, Omarchy's
275
+ default face, at 13px), where it is 15px elsewhere. A size you set wins, and
276
+ resetting the size or the zoom goes back to the computer's default.
277
+
278
+ The computer's monospace font is used only once it draws at a fixed width.
279
+ Desktop checks it at start and on each choice in the picker. Where the
280
+ computer has no monospace font, or `monospace` names a bitmap font (which the
281
+ window cannot draw), **Omarchy's font** shows System font's faces, and its row
282
+ in the picker says **No monospace font on this computer: showing System
283
+ font**. The choice stays Omarchy's font, so the computer's font is used once
284
+ it draws.
285
+
286
+ The choice is kept on this computer, like the theme, and applies at once:
287
+ open terminals switch font in place and keep what they show. The terminal's
288
+ font size, Settings → Terminal and the zoom keys are not changed by it, and a
289
+ terminal font family set with the palette's **Terminal: set font family…**
290
+ still wins until **Terminal: reset typography**.
291
+
228
292
  The list of workspaces is always shown. Its heading holds **Add local
229
293
  workspace…** (the **+**). The list has one row per workspace this window can show, whatever
230
294
  machine it is on: every workspace the Desktop serves, those only on servers
@@ -260,7 +324,7 @@ computer.
260
324
  and the list's description names it, by the same name as its row.
261
325
  - **The needs-input mark.** A row has an exclamation mark (a small amber
262
326
  disc with a "!") at its right end when an instance of that workspace needs
263
- input, the same mark an instance's **Needs input** pill starts with: the claim the instance roster shows
327
+ input, the same mark a waiting instance's dot shows in the instance tree: the claim the instance roster shows
264
328
  for that instance, from a running session (OATS with the `waiting-on-you`
265
329
  feature), as the Desktop already reads it for the workspaces it serves.
266
330
  Every row can have it, the current one included. The row's name then ends
@@ -274,8 +338,9 @@ computer.
274
338
  in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
275
339
  selection; one another window shows moves here ([A workspace another window
276
340
  shows](#a-workspace-another-window-shows)). The leader's ↑ / ↓ go to the
277
- previous / next row, and stop at the ends ("No workspace above this one." /
278
- "No workspace below this one."). Each is a pick, so walking the list with
341
+ previous / next row, and wrap: past the last row comes the first, and
342
+ before the first the last. With no other workspace to show, nothing moves
343
+ and one line says "No other workspace to show." Each is a pick, so walking the list with
279
344
  them moves every workspace it passes that another window shows into this
280
345
  window.
281
346
  - **Open in new window** is in a row's context menu (a right-click, or
@@ -533,7 +598,8 @@ roster row reads **Retiring…** while:
533
598
  changed, runs nothing, and the row reads as the roster says at once.
534
599
 
535
600
  A retiring row offers no Start, Stop, Restart or Open, and no inline
536
- button. **Retire instance…** stays in the row's menu, after its usual
601
+ button. **Retire instance…** stays in the row's context menu (right-click,
602
+ Shift+F10 or the ContextMenu key), after its usual
537
603
  confirmation: OATS refuses a second retire while one runs, and when the
538
604
  holder can't be read it may be the only way on.
539
605
 
@@ -578,7 +644,7 @@ heading. The tab you chose is
578
644
  is disabled, and says why, when that soul can't be told or shown exactly:
579
645
  the instance records none, it is no longer among the deployment's souls,
580
646
  several match, another soul of the deployment has the same name, or the
581
- instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the instance's menu and its panel.
647
+ instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the row's context menu (right-click, Shift+F10 or the ContextMenu key) and its panel.
582
648
  - **Not shown live.** A deployment that can't be shown live says why in a few
583
649
  words on its heading ("ssh needs a prompt", "Timed out", "OATS too old to
584
650
  report its workspace"), and **How to fix** under it gives the full sentence
@@ -738,7 +804,7 @@ than showing nothing. A row that can't be opened says why on the row:
738
804
  Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
739
805
  For an instance a server no longer lists, the reason names the command that removes it from this
740
806
  computer (`oats server forget <server> --instance <name>`), and the row offers **Forget…**, in its
741
- actions menu and in the context panel, which runs that command for that row after a confirmation.
807
+ context menu (right-click, Shift+F10 or the ContextMenu key) and in the context panel, which runs that command for that row after a confirmation.
742
808
  Only this computer's saved route goes; nothing changes on the server, and the roster is read again.
743
809
 
744
810
  ## Remote terminals
@@ -765,6 +831,28 @@ A remote instance's tabs close only when its server answers without it
765
831
  (retired there, or gone from it), never because the server can't be reached
766
832
  or its roster read is out of date.
767
833
 
834
+ ## When an agent waits on you
835
+
836
+ While an instance waits on you (its `waitingOnYou` claim), the sidebar marks
837
+ its row **Needs input**, and each terminal tab that shows it carries a row
838
+ over its terminal:
839
+
840
+ - **Needs input**, then how long it has waited (`· 12 min`), on one line.
841
+ - Under it, the agent's question as it wrote it, shown as plain text. When
842
+ the agent left no text, the row says why in words, for example "Waiting for
843
+ a tool approval". When the agent gave no reason either, the first line
844
+ says it all and the row has no second line.
845
+ - The question wraps to at most three lines, and the row never takes more
846
+ than a quarter of the pane; a longer question ends with "…". The tab's
847
+ tooltip and the sidebar's card have the whole of it. A pane too short
848
+ for even the first line shows no row: the tab's mark still says the
849
+ instance needs input.
850
+
851
+ The terminal gives up exactly the row's height. It resizes only when the wait
852
+ starts, ends or its text changes, never as the age ticks over. In a split,
853
+ each group's row follows its own tab. The row goes as soon as the wait ends,
854
+ and it never shows for a stopped instance or a roster that is out of date.
855
+
768
856
  ## Copy from a terminal
769
857
 
770
858
  Drag over an agent's output to select it, as in any terminal. The selection
@@ -775,8 +863,17 @@ With nothing selected, Ctrl+Shift+C, ⌘C and Edit › Copy do nothing and leave
775
863
  the clipboard as it was, and Ctrl+C still interrupts the program in the pane. Copies trim trailing spaces at line ends, as native
776
864
  terminals do.
777
865
 
778
- A drag selects what is on the screen. To select older output, wheel up first
779
- (the pane scrolls back through tmux's history), then select. The wheel scrolls
866
+ A drag selects what is on the screen. To select older output, scroll back
867
+ first, then select. Wheel up, or press **Shift+PgUp**, or **Ctrl+B** then `[`:
868
+ the pane scrolls back through tmux's history, and `q` returns to the bottom.
869
+ Ctrl+B `[` needs tmux 3.3 or later on the computer the agent runs on. On
870
+ another computer, Shift+PgUp and Ctrl+B `[` need OATS 0.69.0 or later there;
871
+ with an older OATS, scroll back with the wheel. Ctrl+B followed by any other
872
+ key still reaches the agent. On Linux and Windows, a shortcut you bind to
873
+ Ctrl+B in the shortcuts window takes Ctrl+B first, if it is one that works in
874
+ a terminal. The pane is shared: while
875
+ you scroll back, anyone else viewing the same agent sees the same paused view
876
+ until you return to the bottom, as with the wheel. The wheel scrolls
780
877
  as before, and a program that uses the mouse itself still receives the wheel.
781
878
  It no longer receives mouse clicks or drags from the Desktop: those always
782
879
  select.
@@ -818,14 +915,51 @@ right of its parent, and related instances are grouped together. Siblings are
818
915
  joined by a dotted line through their dots. A parent's line to its children
819
916
  runs just to the right of the dotted line, so the two never merge.
820
917
 
918
+ A row shows the instance's name as words: each `-` is a space, and the first
919
+ letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
920
+ maintainer lanes". Only the row's label changes. The hover card, the command
921
+ palette (which still finds the instance by its name), its terminal tab, a
922
+ screen reader and the `oats` CLI all use the instance's real name. The TUI's
923
+ sidebar shows the same words.
924
+
925
+ A row's dot says the instance's state: filled while it runs, a ring when it is
926
+ stopped, a grey ring with a small grey centre when its state is unknown (the
927
+ command palette, Quick Open and the overview show it the same way). An
928
+ instance that needs input (a running session's claim, from OATS with the
929
+ `waiting-on-you` feature) shows the needs-input mark in place of its dot: a
930
+ slightly larger amber disc with a "!" cut out of it, the mark its terminal tab
931
+ and the workspace list show. Amber means needs input and nothing else.
932
+ Elsewhere, a dot that flags a problem is red: a keyboard shortcut that clashes
933
+ with another (on the settings cog), Setup or Teams needing attention (on the
934
+ Workspace page's tabs), and an automation that doesn't run here or a
935
+ scheduler that is off.
936
+ The row keeps its soul and repository on its second line. A screen reader
937
+ hears "Needs input" after the name, and the hover card gives the reason and
938
+ how long it has waited. A collapsed parent shows "! N below" on its second
939
+ line for the rows it hides that need input, beside its own mark when it waits
940
+ too. Rows never move or grow, and nothing animates.
941
+
942
+ A row has no ⋯ button. Its actions (Open in split, Open pull request…,
943
+ Knowledge & capabilities…, Start…, Restart with…, Stop…, Retire instance…, and
944
+ Forget… for an instance its server no longer lists) are in the row's context
945
+ menu (right-click, Shift+F10 or the ContextMenu key), as a workspace row's are.
946
+ It opens where you right-click, or on the row from the keyboard; the arrow keys,
947
+ Home and End move in it, and Esc or Tab close it with the focus back on the
948
+ row. A right-click never opens the row's terminal. While the menu can't be used
949
+ (the roster is out of date, one of its actions is still running, or the row
950
+ can't be used from this computer), it opens nothing, and one line at the
951
+ bottom of the main area says why, as a leader key that can't act does. The row's own tools stay: its pull request link and, on a
952
+ stopped row, **Start…**.
953
+
821
954
  ## An instance's colour
822
955
 
823
956
  An instance can have a colour, one of the soul palette's six (Sand, Sage,
824
957
  Slate, Mauve, Clay, Olive). Its dot shows it wherever the instance is listed:
825
958
  the sidebar, its terminal tab, the command palette and the overview. A running
826
959
  instance's dot is filled with the colour, a stopped one's is a ring in it. An
827
- instance whose state is unknown keeps the warning dot, and one without a colour
828
- looks as before. The shape says the state, never the colour alone.
960
+ instance whose state is unknown keeps its grey bullseye, one that needs input
961
+ shows the needs-input mark in the sidebar, never in its colour, and one without
962
+ a colour looks as before. The shape says the state, never the colour alone.
829
963
 
830
964
  To set it, open **Instance: name and colour…** from the command palette, or
831
965
  press Alt+R (⌥⌘R on macOS; Ctrl+Alt+R in the Ctrl+Alt family). It acts on the instance of the terminal you
@@ -890,7 +1024,7 @@ unknown or unreported harness shows "?". Sources and licences are in
890
1024
  | "This Desktop is older than the installed oats CLI" card | The CLI found is a released version above the range this Desktop works with, usually because the CLI was updated first. Install OATS Desktop of the version the card names; the card offers no npm command, since installing the CLI this Desktop pins would downgrade it. Reads and terminals keep working meanwhile; **Choose oats…** points at another, compatible CLI and **Retry** re-probes. |
891
1025
  | Spawn disabled, no card | The probe hasn't settled yet (transient, resolves in ms). If it persists, the backend is unreachable — restart the app. |
892
1026
  | Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux -L oats ls` (the OATS tmux server, where instances run) and `tmux ls` (your default server, where an instance started by an earlier kernel may still be). |
893
- | Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
1027
+ | Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: scroll back first (wheel up, Shift+PgUp or Ctrl+B then `[`) for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
894
1028
  | macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
895
1029
  | Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
896
1030
  | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use **Add local workspace…** (the **+** at the top of the sidebar) to select the right folder. |