happier-tui 0.2.1 → 0.3.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.
package/README.md CHANGED
@@ -6,7 +6,7 @@ Pick a session running on any of your machines, read it live, send prompts, answ
6
6
  requests, start new sessions — and get a bell or a notification from your terminal, tmux or cmux
7
7
  when an agent needs you.
8
8
 
9
- ![happier-tui start screen](https://raw.githubusercontent.com/CyrilPeponnet/happier-tui/main/assets/main.png)
9
+ ![A tour of happier-tui: the start screen, a conversation, an agent at work, a permission request and a question](https://raw.githubusercontent.com/CyrilPeponnet/happier-tui/main/assets/demo.gif)
10
10
 
11
11
  happier-tui is an independent, unofficial client. It talks to the Happier relay directly (HTTP and
12
12
  Socket.IO, end-to-end encrypted) and is built on
@@ -48,7 +48,7 @@ To update: `git pull && npm install && npm run build` in the same folder. Withou
48
48
 
49
49
  ```
50
50
  happier-tui start screen: pick or start a session
51
- happier-tui <session-id-or-prefix> open a session directly
51
+ happier-tui <session-id-or-prefix> open a session directly (or --session <id>)
52
52
  happier-tui <directory> start a new session on this machine in that directory
53
53
  happier-tui --list [--all] print active (or all) sessions and exit
54
54
 
@@ -62,12 +62,17 @@ happier-tui --list [--all] print active (or all) sessions and exit
62
62
 
63
63
  ### Start screen
64
64
 
65
- Active sessions grouped by machine. Type to search by title, host, agent or path.
65
+ Active sessions grouped by machine, each with its agent, folder and last activity, or what it
66
+ is doing: `working`, `needs you` (a permission request or a question) or `new reply` (not seen
67
+ yet). Type to search by title, host, agent or path.
68
+
69
+ ![The start screen: sessions on several machines, with what each one is doing](https://raw.githubusercontent.com/CyrilPeponnet/happier-tui/main/assets/home.png)
66
70
 
67
71
  | Key | Action |
68
72
  | --- | --- |
69
73
  | `↑` `↓`, `enter` | select, open |
70
74
  | `ctrl+n` | new session: machine → agent → directory |
75
+ | `ctrl+x` | stop the selected session's agent, archive the session, or both |
71
76
  | `tab` | show or hide inactive sessions |
72
77
  | `esc` | clear the search, then go back to the open session |
73
78
 
@@ -104,7 +109,12 @@ arrows to send one as your reply, or `esc` to write your own (`ctrl+r` brings it
104
109
  also click a choice in the transcript. Permission requests open the same way.
105
110
 
106
111
  Anything else starting with `/` goes to the agent, whose own commands are offered in
107
- autocomplete. Model, mode and thinking-level changes apply from your next message.
112
+ autocomplete. The agent publishes them once it has handled a first message, so a new session
113
+ offers only the TUI's own commands until then. An agent lists only what it can run from a
114
+ message: Claude includes its built-ins (`/compact`, `/clear`, `/context`, …), while pi lists its
115
+ extensions and skills, since its other built-ins belong to its own terminal UI (the commands
116
+ above cover the model, thinking level, rename and `/tree`). `/compact` works with every agent.
117
+ Model, mode and thinking-level changes apply from your next message.
108
118
 
109
119
  Above the editor, the TUI shows what needs you or is pending: permission requests and questions,
110
120
  messages waiting in the queue, the session's goal and a usage-limit wait. Once a turn is over, its tool calls
@@ -114,6 +124,8 @@ output; `ctrl+o` unfolds everything.
114
124
 
115
125
  ## Knowing when an agent needs you
116
126
 
127
+ ![A permission request from an agent on another machine, answered from the TUI](https://raw.githubusercontent.com/CyrilPeponnet/happier-tui/main/assets/permission.png)
128
+
117
129
  When a session you are not looking at finishes its turn, fails, or asks for a permission or an
118
130
  answer, happier-tui signals it through the terminal:
119
131
 
@@ -135,6 +147,14 @@ session is also marked read, so the unread badge clears on your other devices.
135
147
  If a signal does not show up, run with `HAPPIER_TUI_DEBUG=/tmp/happier-tui.log`. The log records
136
148
  focus changes and, for each turn or request change, whether a signal was sent.
137
149
 
150
+ ## cmux tab restore
151
+
152
+ Inside [cmux](https://cmux.com), happier-tui registers the open session as the tab's restore
153
+ command (`happier-tui --session <id>`), so the tab comes back on that session after cmux restarts.
154
+ cmux only restores tabs registered by its agent hooks, so happier-tui uses pi's: the tab shows as Pi.
155
+ Quitting normally clears the entry. The restore runs with your default server: cmux does not keep
156
+ other options such as `--server`.
157
+
138
158
  ## How it works
139
159
 
140
160
  ```
@@ -174,24 +194,51 @@ of CLI 0.2.20, so a relay or CLI upgrade may require changes here.
174
194
 
175
195
  ```bash
176
196
  npm run dev # run from source
197
+ npm run demo # the TUI on made-up sessions, no account needed
177
198
  npm test # unit tests
178
199
  npm run typecheck
179
200
  ```
180
201
 
202
+ The README's animation and screenshots come from the demo: `npm run screenshots` (needs
203
+ [VHS](https://github.com/charmbracelet/vhs), `brew install vhs`) plays the tour in
204
+ [`scripts/screenshots.tape`](scripts/screenshots.tape) and rewrites `assets/demo.gif` and the PNGs.
205
+ Change the made-up sessions and the agent's scripted replies in [`scripts/demo.ts`](scripts/demo.ts).
206
+
181
207
  ### Releasing
182
208
 
183
- Pushing a version tag publishes the package to npm and creates the GitHub release
184
- (`.github/workflows/release.yml`):
209
+ Releases are made by GitHub Actions. Pushing a version tag runs `.github/workflows/release.yml`,
210
+ which checks that the tag matches `package.json`, runs the typecheck and tests, publishes to npm
211
+ (with provenance) and creates the GitHub release.
185
212
 
186
- ```bash
187
- npm version patch # or minor / major: bumps package.json, commits, tags vX.Y.Z
188
- git push --follow-tags
189
- ```
213
+ 1. Commit and push to `main`, and check that CI is green (`gh run list`).
214
+ 2. Preview the release notes: `node scripts/release-notes.mjs`. They list the commits since the
215
+ last tag, grouped by their subject's type: `feat…:` under New, `fix…:` under Fixes, anything
216
+ else under Other changes. Reword a subject before tagging if it reads badly.
217
+ 3. Bump the version, which commits and tags it (`vX.Y.Z`):
218
+
219
+ ```bash
220
+ npm version patch # fixes: 0.2.1 → 0.2.2
221
+ npm version minor # new features: 0.2.1 → 0.3.0
222
+ npm version major # breaking changes: 0.2.1 → 1.0.0
223
+ ```
224
+
225
+ 4. Push the commit and the tag; this starts the release:
226
+
227
+ ```bash
228
+ git push --follow-tags
229
+ ```
230
+
231
+ It takes a minute, and npm another minute or two to list the new version. Edit the notes
232
+ afterwards on GitHub (or `gh release edit vX.Y.Z --notes "…"`) to add context.
233
+
234
+ If the tests fail in the release run, nothing is published: fix, then move the tag to the fixed
235
+ commit (`git tag -d vX.Y.Z && git push origin :vX.Y.Z`, then `git tag vX.Y.Z && git push --tags`).
236
+ If only the publish step failed, use "Re-run failed jobs" on the run. A version number can never be
237
+ published twice on npm; a bad release is fixed by the next one.
190
238
 
191
- The workflow logs in to npm through
192
- [trusted publishing](https://docs.npmjs.com/trusted-publishers), so there is no npm token to
193
- store: the package's settings on npmjs.com name this repository and `release.yml` as its
194
- trusted publisher.
239
+ npm authenticates the workflow through [trusted publishing](https://docs.npmjs.com/trusted-publishers),
240
+ so there is no npm token to store: the package's settings on npmjs.com trust this repository's
241
+ `release.yml`, in the `Release` environment.
195
242
 
196
243
  ## License
197
244
 
package/dist/app.js CHANGED
@@ -6,6 +6,7 @@ import { latestOptions, Transcript } from "./happier/transcript.js";
6
6
  import { attentionChange, FOCUS_IN, FOCUS_OUT, notificationSequence, } from "./ui/notify.js";
7
7
  import { NewSessionFlow } from "./new-session.js";
8
8
  import { errorText, justify, machineName, questionsOf, requestSummary, shortHost, untilText } from "./ui/format.js";
9
+ import { cmuxBind, cmuxUnbind } from "./cmux.js";
9
10
  import { SessionAutocomplete } from "./ui/autocomplete.js";
10
11
  import { PromptEditor } from "./ui/prompt-editor.js";
11
12
  import { Picker } from "./ui/picker.js";
@@ -33,6 +34,10 @@ const LOCAL_COMMANDS = [
33
34
  { name: "keys", description: "Show key bindings" },
34
35
  { name: "quit", description: "Exit" },
35
36
  ];
37
+ /** Sent to the agent like its own commands; Happier runs them for every agent, listed or not. */
38
+ const RUNNER_COMMANDS = [
39
+ { name: "compact", description: "Summarize the conversation so far to free up context" },
40
+ ];
36
41
  const KEYS_HELP = [
37
42
  "enter send · shift+enter newline · esc interrupt the agent",
38
43
  "ctrl+s session list · ctrl+n new session · alt+↑/↓ previous/next active session",
@@ -133,7 +138,7 @@ export class App {
133
138
  scrollToEndIndicator: () => c.accent(" ↓ jump to latest "),
134
139
  });
135
140
  this.scroll = new ScrollView(this.view, { follow: "end", primary: true, scrollbar: "auto" });
136
- this.editor = new PromptEditor(this.tui, editorTheme, { paddingX: 1 });
141
+ this.editor = new PromptEditor(this.tui, editorTheme, { paddingX: 2 });
137
142
  this.editor.onSubmit = (text) => void this.submit(text);
138
143
  this.home = new Home(() => {
139
144
  const machines = [...this.client.machines.values()];
@@ -151,12 +156,20 @@ export class App {
151
156
  frame: this.frame,
152
157
  rows: this.tui.terminal.rows - this.renderRequests(this.tui.terminal.columns).length,
153
158
  status: this.loaded
154
- ? `${this.client.config.serverName} ${link}${c.dim(` · ${active} active session${active === 1 ? "" : "s"} · ${online} machine${online === 1 ? "" : "s"} online`)}`
155
- : c.dim(this.loadError || `Connecting to ${this.client.config.serverName}…`),
159
+ ? [
160
+ `${this.client.config.serverName} ${link}`,
161
+ c.dim(`${active} active session${active === 1 ? "" : "s"} · ${online} machine${online === 1 ? "" : "s"} online`),
162
+ ]
163
+ : [c.dim(this.loadError || `Connecting to ${this.client.config.serverName}…`)],
156
164
  };
157
165
  });
158
166
  this.home.onOpen = (id) => void this.openSession(id);
159
167
  this.home.onNew = () => this.run(() => this.newSession());
168
+ this.home.onManage = (id) => {
169
+ const s = this.client.sessions.get(id);
170
+ if (s)
171
+ this.run(() => this.manageSession(s));
172
+ };
160
173
  this.home.onToggleInactive = () => {
161
174
  this.showInactive = !this.showInactive;
162
175
  this.tui.requestRender();
@@ -166,7 +179,7 @@ export class App {
166
179
  void this.openSession(this.currentId);
167
180
  };
168
181
  this.chatRoot = new VStack([
169
- { component: new Lines((w) => this.renderHeader(w)), basis: 1, shrink: 0 },
182
+ { component: new Lines((w) => this.renderHeader(w)), basis: 2, shrink: 0 },
170
183
  { component: this.scroll, basis: 0, grow: 1, minSize: 3 },
171
184
  { component: new Lines((w) => this.renderRequests(w)), basis: "auto", shrink: 0 },
172
185
  { component: this.editor, basis: "auto", shrink: 1, minSize: 3 },
@@ -244,6 +257,7 @@ export class App {
244
257
  if (this.timer)
245
258
  clearInterval(this.timer);
246
259
  this.client.close();
260
+ cmuxUnbind();
247
261
  // The alt-screen renderer prints its document to the main screen on stop; leave nothing behind.
248
262
  this.tui.setLayoutRoot(new Lines(() => []));
249
263
  this.tui.stop();
@@ -267,7 +281,7 @@ export class App {
267
281
  const anyBusy = [...this.client.sessions.values()].some((s) => this.busy(s));
268
282
  if (anyBusy)
269
283
  dirty = true;
270
- // The start screen's logo is animated.
284
+ // The start screen shows each session's age.
271
285
  if (this.mode === "home" && !this.overlay)
272
286
  dirty = true;
273
287
  this.maybeLoadEarlier();
@@ -406,6 +420,7 @@ export class App {
406
420
  if (!s)
407
421
  return;
408
422
  this.currentId = id;
423
+ cmuxBind(id);
409
424
  this.unread.delete(id);
410
425
  if (this.mode !== "chat") {
411
426
  this.mode = "chat";
@@ -530,8 +545,9 @@ export class App {
530
545
  const details = Array.isArray(s.metadata.slashCommandDetails) ? s.metadata.slashCommandDetails : [];
531
546
  const names = Array.isArray(s.metadata.slashCommands) ? s.metadata.slashCommands : [];
532
547
  const seen = new Set(LOCAL_COMMANDS.map((x) => x.name));
533
- for (const d of [...details, ...names]) {
534
- const name = typeof d === "string" ? d : isObj(d) && typeof d.name === "string" ? d.name : "";
548
+ // Details are `{command, description}`; plain names cover agents that publish only those.
549
+ for (const d of [...details, ...names, ...RUNNER_COMMANDS]) {
550
+ const name = typeof d === "string" ? d : isObj(d) ? String(d.command ?? d.name ?? "") : "";
535
551
  const clean = name.replace(/^\//, "");
536
552
  if (!clean || seen.has(clean))
537
553
  continue;
@@ -539,7 +555,7 @@ export class App {
539
555
  const description = isObj(d) && typeof d.description === "string" ? d.description : "agent command";
540
556
  remote.push({ name: clean, description });
541
557
  }
542
- const key = `${s.id}:${remote.length}`;
558
+ const key = `${s.id}:${remote.map((c) => c.name).join(" ")}`;
543
559
  if (key === this.commandsKey)
544
560
  return;
545
561
  this.commandsKey = key;
@@ -795,31 +811,55 @@ export class App {
795
811
  case "stop-session": {
796
812
  if (!s)
797
813
  return;
798
- if (!(await this.confirm(`Stop the agent process for "${sessionTitle(s)}"?`)))
799
- return;
800
- await this.client.stopSession(s);
801
- this.flash("Stop requested.", "info");
814
+ if (await this.confirm(`Stop the agent process for "${sessionTitle(s)}"?`))
815
+ await this.endSession(s, "stop");
802
816
  return;
803
817
  }
804
818
  case "archive": {
805
819
  if (!s)
806
820
  return;
807
- if (!(await this.confirm(`Archive "${sessionTitle(s)}"?`)))
808
- return;
809
- try {
810
- await this.client.archive(s);
811
- }
812
- catch (e) {
813
- if (e instanceof HappierError && e.code === "session-active") {
814
- throw new HappierError("Session is still running — /stop-session first, then /archive.");
815
- }
816
- throw e;
817
- }
818
- this.flash("Archived.", "info");
821
+ if (await this.confirm(`Archive "${sessionTitle(s)}"?`))
822
+ await this.endSession(s, "archive");
819
823
  return;
820
824
  }
821
825
  }
822
826
  }
827
+ /** ctrl+x in the session list: stop a session's agent, archive the session, or both. */
828
+ async manageSession(s) {
829
+ const how = await this.pick({
830
+ title: `End "${oneLine(sessionTitle(s))}"`,
831
+ noFilter: true,
832
+ items: s.active
833
+ ? [
834
+ { value: "stop", label: "Stop the agent", description: "the session stays listed as inactive" },
835
+ { value: "stop-archive", label: "Stop and archive", description: "remove it from the list" },
836
+ ]
837
+ : [{ value: "archive", label: "Archive", description: "remove it from the list" }],
838
+ });
839
+ if (how === "stop" || how === "stop-archive" || how === "archive")
840
+ await this.endSession(s, how);
841
+ }
842
+ async endSession(s, how) {
843
+ if (how !== "archive") {
844
+ await this.client.stopSession(s);
845
+ if (how === "stop")
846
+ return this.flash("Stop requested.", "info");
847
+ this.flash("Stopping…", "info");
848
+ if (!(await this.client.waitStopped(s.id))) {
849
+ throw new HappierError("The agent is still running; archive the session once it has stopped.");
850
+ }
851
+ }
852
+ try {
853
+ await this.client.archive(s);
854
+ }
855
+ catch (e) {
856
+ if (e instanceof HappierError && e.code === "session-active") {
857
+ throw new HappierError("Session is still running — stop it first (/stop-session, or ctrl+x in the session list).");
858
+ }
859
+ throw e;
860
+ }
861
+ this.flash("Archived.", "info");
862
+ }
823
863
  async abort() {
824
864
  const s = this.current();
825
865
  if (!s)
@@ -1063,12 +1103,13 @@ export class App {
1063
1103
  this.run(() => this.answer(s, next));
1064
1104
  return;
1065
1105
  }
1066
- const options = this.offeredOptions(s);
1067
- const key = `${s.id}:options:${this.entries.get(s.id)?.transcript.maxSeq}`;
1068
- if (options.length === 0 || this.prompted.has(key) || this.editor.getText().trim())
1106
+ const offer = this.offeredOptions(s);
1107
+ // Keyed on the message that offers them, so a dismissed popup stays dismissed.
1108
+ const key = offer && `${s.id}:options:${offer.key}`;
1109
+ if (!offer || !key || this.prompted.has(key) || this.editor.getText().trim())
1069
1110
  return;
1070
1111
  this.prompted.add(key);
1071
- this.run(() => this.chooseOption(options));
1112
+ this.run(() => this.chooseOption(offer.options));
1072
1113
  }
1073
1114
  /** ctrl+r: answer what the agent is waiting for: a permission request, else its offered choices. */
1074
1115
  async answerRequest() {
@@ -1076,12 +1117,12 @@ export class App {
1076
1117
  const req = s && pendingRequests(s)[0];
1077
1118
  if (s && req)
1078
1119
  return this.answer(s, req);
1079
- const options = s ? this.offeredOptions(s) : [];
1080
- if (!s || options.length === 0) {
1120
+ const offer = s && this.offeredOptions(s);
1121
+ if (!offer) {
1081
1122
  this.flash("Nothing to answer in this session.", "info");
1082
1123
  return;
1083
1124
  }
1084
- await this.chooseOption(options);
1125
+ await this.chooseOption(offer.options);
1085
1126
  }
1086
1127
  async chooseOption(options) {
1087
1128
  const choice = await this.pick({
@@ -1096,7 +1137,7 @@ export class App {
1096
1137
  /** Choices the agent offered at the end of its last turn, while it waits for the reply. */
1097
1138
  offeredOptions(s) {
1098
1139
  const entry = this.entries.get(s.id);
1099
- return entry && !this.busy(s) ? latestOptions(entry.transcript) : [];
1140
+ return entry && !this.busy(s) ? latestOptions(entry.transcript) : undefined;
1100
1141
  }
1101
1142
  async answer(s, req) {
1102
1143
  const questions = questionsOf(req);
@@ -1207,7 +1248,7 @@ export class App {
1207
1248
  : this.connection === "connecting"
1208
1249
  ? c.warn("◌ connecting")
1209
1250
  : c.err("○ offline — retrying");
1210
- let left = ` ${c.accent.bold("happier")}`;
1251
+ let left = ` ${c.accent.bold("happier-tui")}`;
1211
1252
  if (s) {
1212
1253
  left += ` ${statusGlyph(s, this.frame)} ${c.bold.whiteBright(clean(sessionTitle(s)).replace(/\s+/g, " "))}`;
1213
1254
  left += c.faint(` ${s.metadata.flavor ?? "?"} · ${this.hostOf(s)} · ${shortPath(s.metadata.path, s.metadata.homeDir)}`);
@@ -1215,7 +1256,8 @@ export class App {
1215
1256
  else {
1216
1257
  left += c.dim(` ${this.client.config.serverName}`);
1217
1258
  }
1218
- return [c.headerBg(justify(left, `${conn} `, width))];
1259
+ // A blank line keeps the conversation off the header when scrolled.
1260
+ return [c.headerBg(justify(left, `${conn} `, width)), ""];
1219
1261
  }
1220
1262
  renderRequests(width) {
1221
1263
  const lines = [];
@@ -1249,7 +1291,7 @@ export class App {
1249
1291
  lines.push(c.faint(` ${more}/queue to edit or cancel`));
1250
1292
  }
1251
1293
  const reqs = pendingRequests(s);
1252
- const offered = reqs.length === 0 ? this.offeredOptions(s).length : 0;
1294
+ const offered = reqs.length === 0 ? (this.offeredOptions(s)?.options.length ?? 0) : 0;
1253
1295
  if (offered > 0)
1254
1296
  lines.push(` ${c.accent("❯")} ${c.dim(`${offered} choices above · click one, or ctrl+r`)}`);
1255
1297
  const first = reqs[0];