@awebai/oats 0.68.1 → 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 (67) 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 +108 -10
  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.69.0.md +658 -0
  15. package/docs/release-notes/v0.69.1.md +25 -0
  16. package/docs/servers.md +44 -5
  17. package/docs/souls-and-instances.md +11 -7
  18. package/docs/tui.md +77 -12
  19. package/docs/upgrading.md +12 -7
  20. package/docs/workspaces.md +1 -1
  21. package/lib/core.mjs +345 -89
  22. package/lib/file-pieces.mjs +49 -0
  23. package/lib/instance-events.mjs +25 -4
  24. package/lib/launch-prompt-fixtures/README.md +62 -0
  25. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  26. package/lib/launch-prompt-fixtures.mjs +49 -0
  27. package/lib/launch-prompt-resume.mjs +55 -0
  28. package/lib/login-environment.mjs +27 -9
  29. package/lib/schedule.mjs +3 -3
  30. package/lib/servers.mjs +117 -23
  31. package/lib/session-end.mjs +82 -0
  32. package/lib/session-input.mjs +43 -9
  33. package/lib/session-resume-contract.mjs +32 -0
  34. package/lib/session-resume.mjs +310 -0
  35. package/lib/session-seen.mjs +163 -0
  36. package/lib/session-viewer.mjs +147 -44
  37. package/lib/soul-composition.mjs +2 -1
  38. package/lib/start-env.mjs +110 -0
  39. package/lib/tmux-server-scope.mjs +139 -14
  40. package/lib/workspace.mjs +38 -4
  41. package/package-catalog.json +10 -4
  42. package/package.json +1 -1
  43. package/packages/client/cli-adapter.mjs +9 -0
  44. package/packages/client/cli-locator.mjs +3 -2
  45. package/packages/client/deployment-data.mjs +7 -0
  46. package/packages/client/deployment-panel.mjs +3 -0
  47. package/packages/client/file-output-exec.mjs +98 -0
  48. package/packages/client/launch-prompt-outcome.mjs +25 -13
  49. package/packages/client/own-codes.mjs +2 -0
  50. package/packages/client/session-attach.mjs +35 -5
  51. package/packages/client/session-resume-cli.mjs +64 -0
  52. package/packages/client/session-resume-trigger.mjs +167 -0
  53. package/packages/client/session-resume.mjs +332 -0
  54. package/packages/client/tmux-status.mjs +30 -7
  55. package/packages/client/waiting-on-you.mjs +11 -4
  56. package/packages/client/workspace-step.mjs +17 -5
  57. package/packages/record/lib/last-conversation.mjs +123 -0
  58. package/packages/record/lib/session-roots.mjs +10 -1
  59. package/packages/tui/lib/client.mjs +1 -1
  60. package/packages/tui/lib/main.mjs +5 -3
  61. package/packages/tui/lib/model.mjs +45 -12
  62. package/packages/tui/lib/store.mjs +8 -7
  63. package/packages/tui/lib/term/text.mjs +12 -9
  64. package/packages/tui/lib/views/frame.mjs +72 -7
  65. package/packages/tui/lib/views/help.mjs +8 -3
  66. package/packages/tui/lib/views/instances.mjs +3 -2
  67. 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
@@ -236,6 +248,47 @@ hidden; a window too narrow for it shows it narrower, and gives it back when
236
248
  the window grows again. The terminals refit as it moves, and their programs
237
249
  hear the new size once, when you let go.
238
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
+
239
292
  The list of workspaces is always shown. Its heading holds **Add local
240
293
  workspace…** (the **+**). The list has one row per workspace this window can show, whatever
241
294
  machine it is on: every workspace the Desktop serves, those only on servers
@@ -285,8 +338,9 @@ computer.
285
338
  in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
286
339
  selection; one another window shows moves here ([A workspace another window
287
340
  shows](#a-workspace-another-window-shows)). The leader's ↑ / ↓ go to the
288
- previous / next row, and stop at the ends ("No workspace above this one." /
289
- "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
290
344
  them moves every workspace it passes that another window shows into this
291
345
  window.
292
346
  - **Open in new window** is in a row's context menu (a right-click, or
@@ -544,7 +598,8 @@ roster row reads **Retiring…** while:
544
598
  changed, runs nothing, and the row reads as the roster says at once.
545
599
 
546
600
  A retiring row offers no Start, Stop, Restart or Open, and no inline
547
- 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
548
603
  confirmation: OATS refuses a second retire while one runs, and when the
549
604
  holder can't be read it may be the only way on.
550
605
 
@@ -589,7 +644,7 @@ heading. The tab you chose is
589
644
  is disabled, and says why, when that soul can't be told or shown exactly:
590
645
  the instance records none, it is no longer among the deployment's souls,
591
646
  several match, another soul of the deployment has the same name, or the
592
- 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.
593
648
  - **Not shown live.** A deployment that can't be shown live says why in a few
594
649
  words on its heading ("ssh needs a prompt", "Timed out", "OATS too old to
595
650
  report its workspace"), and **How to fix** under it gives the full sentence
@@ -749,7 +804,7 @@ than showing nothing. A row that can't be opened says why on the row:
749
804
  Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
750
805
  For an instance a server no longer lists, the reason names the command that removes it from this
751
806
  computer (`oats server forget <server> --instance <name>`), and the row offers **Forget…**, in its
752
- 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.
753
808
  Only this computer's saved route goes; nothing changes on the server, and the roster is read again.
754
809
 
755
810
  ## Remote terminals
@@ -776,6 +831,28 @@ A remote instance's tabs close only when its server answers without it
776
831
  (retired there, or gone from it), never because the server can't be reached
777
832
  or its roster read is out of date.
778
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
+
779
856
  ## Copy from a terminal
780
857
 
781
858
  Drag over an agent's output to select it, as in any terminal. The selection
@@ -786,8 +863,17 @@ With nothing selected, Ctrl+Shift+C, ⌘C and Edit › Copy do nothing and leave
786
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
787
864
  terminals do.
788
865
 
789
- A drag selects what is on the screen. To select older output, wheel up first
790
- (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
791
877
  as before, and a program that uses the mouse itself still receives the wheel.
792
878
  It no longer receives mouse clicks or drags from the Desktop: those always
793
879
  select.
@@ -853,6 +939,18 @@ how long it has waited. A collapsed parent shows "! N below" on its second
853
939
  line for the rows it hides that need input, beside its own mark when it waits
854
940
  too. Rows never move or grow, and nothing animates.
855
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
+
856
954
  ## An instance's colour
857
955
 
858
956
  An instance can have a colour, one of the soul palette's six (Sand, Sage,
@@ -926,7 +1024,7 @@ unknown or unreported harness shows "?". Sources and licences are in
926
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. |
927
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. |
928
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). |
929
- | 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. |
930
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. |
931
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. |
932
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. |